Files

lin 6c9e639a68 fix: remove paperclip property from OpenClaw Gateway agent params

The OpenClaw Gateway's agent method has strict parameter validation
that rejects unknown properties. The paperclip property was being
sent at the root level of agentParams, causing validation failures
with error: "invalid agent params: at root: unexpected property 'paperclip'"

The paperclip metadata is already included in the message field
via wakeText, so removing the separate paperclip property resolves
the validation error while preserving the necessary information.

Fixes #606

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-12 00:27:41 +08:00

doc

Remove legacy OpenClaw adapter and keep gateway-only flow

2026-03-07 18:50:25 -06:00

src

fix: remove paperclip property from OpenClaw Gateway agent params

2026-03-12 00:27:41 +08:00

CHANGELOG.md

release files

2026-03-09 16:43:53 -05:00

package.json

chore: release v0.3.0

2026-03-09 16:31:12 -05:00

README.md

Fix CI typecheck and default OpenClaw sessions to issue scope

2026-03-07 18:33:40 -06: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:

receive connect.challenge
send req connect (protocol/client/auth/device payload)
send req agent
wait for completion via req agent.wait
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.