a498c268c5
New adapter type for invoking OpenClaw agents via the gateway protocol. Registers in server, CLI, and UI adapter registries. Adds onboarding wizard support with gateway URL field and e2e smoke test script. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
72 lines
2.2 KiB
Markdown
72 lines
2.2 KiB
Markdown
# 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
|
|
|
|
## Session Strategy
|
|
|
|
The adapter supports the same session routing model as HTTP OpenClaw mode:
|
|
|
|
- `sessionKeyStrategy=fixed|issue|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.
|