RomanNum3ral
/
paperclip
mirror of https://github.com/paperclipai/paperclip.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
paperclip/packages/adapters/openclaw-gateway
History
sparkeros ec2d87d353
fix(openclaw-gateway): bump adapter PROTOCOL_VERSION to 4 to match gateway (#5984) 
## Summary

Local OpenClaw gateways since v2026.5.x require
`MIN_CLIENT_PROTOCOL_VERSION = 4` (see
[openclaw/src/gateway/protocol/version.ts](https://github.com/NousResearch/openclaw/blob/main/src/gateway/protocol/version.ts)).
The Paperclip openclaw_gateway adapter at v0.3.1 still sends
`PROTOCOL_VERSION = 3`, which produces a WebSocket close (code 1002
\`protocol mismatch\`) before any auth challenge is issued.

## Symptom

Every \`openclaw_gateway\` agent run fails with:
- \`errorCode: openclaw_gateway_request_failed\`
- \`error: protocol mismatch\`

OpenClaw gateway journal:
\`\`\`
[ws] protocol mismatch conn=... remote=127.0.0.1 client=gateway-client
backend vpaperclip
[ws] closed before connect conn=... peer=...->127.0.0.1:18789 code=1002
reason=protocol mismatch
\`\`\`

## Fix

One-line bump in
[\`packages/adapters/openclaw-gateway/src/server/execute.ts:89\`](packages/adapters/openclaw-gateway/src/server/execute.ts#L89):
\`PROTOCOL_VERSION = 3\` → \`PROTOCOL_VERSION = 4\`. No protocol
semantics changed — the adapter's existing frames are compatible with
v4.

## Test plan

- [x] \`pnpm --filter @paperclipai/adapter-openclaw-gateway typecheck\`
clean
- [x] \`pnpm --filter @paperclipai/adapter-openclaw-gateway build\`
clean
- [x] Verified locally: openclaw_gateway agent connects + receives
challenge + completes auth handshake after the bump

## Related

- Same root cause affects every openclaw_gateway-backed agent in the
field. Sparkeros companies SparkEros, Inc. and SparkEros AOS Inc. both
hit it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 		2026-07-06 19:20:11 -05:00
..
doc Introduce bind presets for deployment setup 2026-04-11 07:09:07 -05:00
src fix(openclaw-gateway): bump adapter PROTOCOL_VERSION to 4 to match gateway (#5984) 2026-07-06 19:20:11 -05:00
CHANGELOG.md chore: release v0.3.1 2026-03-12 13:09:22 -05:00
README.md PAPA-430: workspace finalize gates + no-remote-git enforcement (#6969) 2026-05-29 08:25:29 -07:00
package.json build(deps-dev): bump @types/node from 22.19.11 to 22.19.21 (#7748) 2026-06-18 15:46:06 -07:00
tsconfig.json Fix root TypeScript solution config 2026-03-09 14:09:30 -05:00

README.md

OpenClaw Gateway Adapter

This document describes how @paperclipai/adapter-openclaw-gateway invokes OpenClaw over the Gateway protocol.

Transport

This adapter always uses WebSocket gateway transport.

  • URL must be ws:// or wss://
  • Connect flow follows gateway protocol:
  1. receive connect.challenge
  2. send req connect (protocol/client/auth/device payload)
  3. send req agent
  4. wait for completion via req agent.wait
  5. stream event agent frames into Paperclip logs/transcript parsing

Auth Modes

Gateway credentials can be provided in any of these ways:

  • authToken / token in adapter config
  • headers.x-openclaw-token
  • headers.x-openclaw-auth (legacy)
  • password (shared password mode)

When a token is present and authorization header is missing, the adapter derives Authorization: Bearer <token>.

Device Auth

By default the adapter sends a signed device payload in connect params.

  • set disableDeviceAuth=true to omit device signing
  • set devicePrivateKeyPem to pin a stable signing key
  • without devicePrivateKeyPem, the adapter generates an ephemeral Ed25519 keypair per run
  • when autoPairOnFirstConnect is enabled (default), the adapter handles one initial pairing required by calling device.pair.list + device.pair.approve over shared auth, then retries once.

Session Strategy

The adapter supports the same session routing model as HTTP OpenClaw mode:

  • sessionKeyStrategy=issue|fixed|run
  • sessionKey is used when strategy is fixed

Resolved session key is sent as agent.sessionKey.

Payload Mapping

The agent request is built as:

  • required fields:
    • message (wake text plus optional payloadTemplate.message/payloadTemplate.text prefix)
    • idempotencyKey (Paperclip runId)
    • sessionKey (resolved strategy)
  • optional additions:
    • all payloadTemplate fields merged in
    • agentId from config if set and not already in template

Timeouts

  • timeoutSec controls adapter-level request budget
  • waitTimeoutMs controls agent.wait.timeoutMs

If agent.wait returns timeout, adapter returns openclaw_gateway_wait_timeout.

Log Format

Structured gateway event logs use:

  • [openclaw-gateway] ... for lifecycle/system logs
  • [openclaw-gateway:event] run=<id> stream=<stream> data=<json> for event agent frames

UI/CLI parsers consume these lines to render transcript updates.

No-remote-git contract

Like every Paperclip adapter, this one must treat the local execution-workspace cwd as the only persistence boundary across runs — no git push from runtime code, no assuming a git remote exists. The gateway transport here doesn't touch the workspace directly, but if you extend the adapter to ship code to the OpenClaw side, use the round-trip helpers in @paperclipai/adapter-utils (prepareWorkspaceForSshExecution → restoreWorkspaceFromSshExecution) rather than reaching for a git remote. See packages/adapters/AUTHORING.md for the full contract and the pinning test at packages/adapter-utils/src/ssh-fixture.test.ts.