support for openclaw protocol v4

[CameronVetter]

The meaningful changes are:

• handshake now advertises protocol 4 instead of 3
• device auth now signs the newer v3 device payload used by current v4 gateways, including normalized platform metadata
• session helpers were moved off the older session_id-style calls to the current chat/session request shapes and now normalize v4 response envelopes
• added a focused test for the new device-auth payload builder in src\lib\openclaw\device-identity.test.ts

The code itself is in src\lib\openclaw\client.ts; I also updated the coupled helper in src\lib\openclaw\device-identity.ts because the v4 handshake depends on that signature format. TypeScript and the new targeted test passed. Full repo validation is still blocked by existing repository/environment issues on Windows: npm test uses rm, and npm run build fails on an unrelated EPERM scandir against C:\Users\camer\Application Data.

This update now advertises minProtocol: 4 and maxProtocol: 4, so it expects a v4 gateway handshake and v4-era request shapes. A protocol v3-only client or gateway would not negotiate successfully.

There is one easy point of confusion: the device-auth signature payload is now v3, but that is not the same as OpenClaw Protocol v3. That signature format is part of the Protocol v4 handshake path.

This addresses #137

---

Per copilot suggestion now fails loudly on unexpected protocol envelopes instead of silently treating them as empty results.

I added:

• describeResponseShape(...) to summarize the actual payload shape
• unexpectedResponseShape(...) to log a descriptive error and throw
• updated listSessions, getSessionHistory, createSession, listAgents, listModels, and getConfig to use that stricter handling

So if the gateway returns the wrong shape in production, you’ll now get a clear error like “unexpected response shape for sessions.list” rather than a misleading “no sessions” outcome. TypeScript passes.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new “v3” canonical device-auth payload builder with normalized device metadata, updates the OpenClaw client to negotiate protocol v4, and adjusts session/chat RPC handling to accept multiple response shapes.

Changes:

• Introduce buildDeviceAuthPayloadV3() and metadata normalization for signing.
• Update client connect handshake to use protocol v4 and send normalized platform metadata.
• Make session/history/message APIs more flexible to server response shape differences.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
src/lib/openclaw/device-identity.ts	Adds metadata normalization + new v3 signing payload builder including platform/deviceFamily.
src/lib/openclaw/device-identity.test.ts	Adds a unit test asserting normalization behavior in the v3 payload.
src/lib/openclaw/client.ts	Switches to protocol v4 negotiation and updates auth/session/chat RPC calls + response parsing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[CameronVetter]

I'm still testing, but initial results look promising. I will move this to ready for review once I get some more runtime on these changes.

[CameronVetter]

@crshdn I've tested this and I believe it is working completely.