mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-03 01:27:09 +01:00
4b1332b61c
Fixes #5997, fixes #4081, fixes #4723, fixes #6625, fixes #3923 Refs #6606 — this PR removes the rejected root `paperclip` field, but #6606 also requires the protocol v3→v4 bump, which is out of scope here; referencing rather than closing it. ## Thinking Path > - Paperclip is the control plane that wakes and coordinates agent workers across company-scoped execution flows. > - The `openclaw_gateway` adapter is part of that wake path, so its outbound payload contract has to match the gateway's validated `agent` schema. > - `master` currently reintroduces a previously fixed regression by sending a top-level `paperclip` property in `agentParams` (see #3923, which reverts the original fix in #626). > - The gateway rejects unknown root params, which means OpenClaw wakes fail before the remote agent can start work. > - The actual wake context already rides in the generated `message`, so the extra root property is both redundant and harmful. > - This pull request removes that leaked root property, adds a focused regression test around param construction, and updates affected server expectations/docs to the supported contract. > - The benefit is that OpenClaw Gateway agents wake successfully again without losing inline wake context. ## What Changed - Removed the top-level `paperclip` field from OpenClaw Gateway `agentParams` and extracted `buildAgentParams()` so the contract is easy to test. - Added a package-level regression test that proves `payloadTemplate.paperclip` is stripped while explicit `agentId`/`timeout` behavior stays intact. - Updated server tests that inspect OpenClaw Gateway payloads to assert wake data is delivered in `message` instead of a rejected root field. - Updated the adapter configuration docs to state that wake context is embedded in the generated message text, not sent as a top-level param. ### Rebase onto current `master` (conflict resolution) This branch was opened against an older `master`; re-merging current `master` required: - Resolving conflicts in `execute.ts` — `master` hoisted `configuredAgentId` and moved the agentId/timeout precedence inline; this PR keeps the `buildAgentParams()` extraction that strips the gateway-rejected root `paperclip`. - Updating tests `master` added **after** this branch's base that assert the old root-`paperclip` contract. These suites use the OpenClaw gateway adapter purely as a delivery harness (`adapterType: "openclaw_gateway"` + a mock gateway) and observe wake content via the gateway payload, so dropping the root field requires them to read wake context from `message` instead: - `server/src/__tests__/heartbeat-comment-wake-batching.test.ts` - `server/src/__tests__/low-trust-red-team-routes.test.ts` (redaction guarantees preserved — sanitized body + `expectNoCanary` on the raw canary) - Replaced brittle JSON-substring assertions (flagged by Greptile) with a shared `parseWakePayloadFromMessage()` helper + `toMatchObject`, robust to serialization/key-order changes. The strict contract is confirmed upstream: OpenClaw's `AgentParamsSchema` is `Type.Object(..., { additionalProperties: false })` with no `paperclip` field, so a root `paperclip` is rejected (`invalid agent params: at root: unexpected property 'paperclip'`). ## Verification - `pnpm --filter @paperclipai/adapter-openclaw-gateway typecheck` — clean - `pnpm --filter @paperclipai/server typecheck` — clean - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/openclaw-gateway-adapter.test.ts server/src/__tests__/heartbeat-comment-wake-batching.test.ts server/src/__tests__/low-trust-red-team-routes.test.ts` — 26 passed (7 + 11 + 8) - `packages/adapters/openclaw-gateway/src/server/execute.test.ts` — 6 passed (run via a local temp vitest config because the root `vitest.config.ts` does not include this package) ## Risks - Low risk: this narrows the outbound payload to the gateway-supported contract and keeps wake context in the already-supported `message` channel. - Any downstream consumer that incorrectly depended on a top-level `paperclip` field from the gateway mock payloads would need to follow the supported `message` contract instead. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex CLI coding agent via API authored the original change; exact underlying model ID and context window were not exposed in that environment. - Rebase/conflict resolution and the test-assertion migration were done with Claude Code (Claude Opus 4.8, 1M context). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked the related issues above - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: serenakeyitan via breeze-runner <serenakeyitan@users.noreply.github.com> Co-authored-by: Andrew Aymeloglu <aaymeloglu@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
54 lines
2.9 KiB
TypeScript
54 lines
2.9 KiB
TypeScript
export const type = "openclaw_gateway";
|
|
export const label = "OpenClaw Gateway";
|
|
|
|
export const models: { id: string; label: string }[] = [];
|
|
|
|
export const agentConfigurationDoc = `# openclaw_gateway agent configuration
|
|
|
|
Adapter: openclaw_gateway
|
|
|
|
Use when:
|
|
- You want Paperclip to invoke OpenClaw over the Gateway WebSocket protocol.
|
|
- You want native gateway auth/connect semantics instead of HTTP /v1/responses or /hooks/*.
|
|
|
|
Don't use when:
|
|
- You only expose OpenClaw HTTP endpoints.
|
|
- Your deployment does not permit outbound WebSocket access from the Paperclip server.
|
|
|
|
Core fields:
|
|
- url (string, required): OpenClaw gateway WebSocket URL (ws:// or wss://)
|
|
- headers (object, optional): handshake headers; supports x-openclaw-token / x-openclaw-auth
|
|
- authToken (string, optional): shared gateway token override
|
|
- password (string, optional): gateway shared password, if configured
|
|
|
|
Gateway connect identity fields:
|
|
- clientId (string, optional): gateway client id (default gateway-client)
|
|
- clientMode (string, optional): gateway client mode (default backend)
|
|
- clientVersion (string, optional): client version string
|
|
- role (string, optional): gateway role (default operator)
|
|
- scopes (string[] | comma string, optional): gateway scopes (default ["operator.admin"])
|
|
- disableDeviceAuth (boolean, optional): disable signed device payload in connect params (default false)
|
|
|
|
Request behavior fields:
|
|
- payloadTemplate (object, optional): additional fields merged into gateway agent params
|
|
- workspaceRuntime (object, optional): reserved workspace runtime metadata; workspace runtime services are manually controlled from the workspace UI and are not auto-started by heartbeats
|
|
- timeoutSec (number, optional): adapter timeout in seconds (default 120)
|
|
- waitTimeoutMs (number, optional): agent.wait timeout override (default timeoutSec * 1000)
|
|
- autoPairOnFirstConnect (boolean, optional): on first "pairing required", attempt device.pair.list/device.pair.approve via shared auth, then retry once (default true)
|
|
- paperclipApiUrl (string, optional): absolute Paperclip base URL advertised in wake text
|
|
- claimedApiKeyPath (string, optional): path to the claimed API key JSON file read by the agent at wake time (default ~/.openclaw/workspace/paperclip-claimed-api-key.json)
|
|
|
|
Session routing fields:
|
|
- sessionKeyStrategy (string, optional): issue (default), fixed, or run
|
|
- sessionKey (string, optional): fixed session key when strategy=fixed (default paperclip)
|
|
|
|
Wake payload notes:
|
|
- Paperclip wake context is embedded into the generated message text
|
|
- No top-level paperclip field is sent; the gateway agent schema rejects unknown root params
|
|
|
|
Standard result metadata supported:
|
|
- meta.runtimeServices (array, optional): normalized adapter-managed runtime service reports
|
|
- meta.previewUrl (string, optional): shorthand single preview URL
|
|
- meta.previewUrls (string[], optional): shorthand multiple preview URLs
|
|
`;
|