Summary

AgentParamsSchema (in dist/protocol-*.js, e.g. protocol-Hjar_s3V.js in 2026.4.26) is closed with additionalProperties: false and only allows the 35 keys listed below. Adapters that legitimately want to attach context metadata to a wake — Paperclip's @paperclipai/adapter-openclaw-gateway is the case I hit — get every wake rejected with:

[ws] ⇄ res ✗ agent 0ms errorCode=INVALID_REQUEST errorMessage=invalid agent params: at root: unexpected property 'paperclip'

In our case, every agent wake from Paperclip has been silently failing for 12 days (651 errors in our gateway.log since 2026-04-16). It got buried under a separate WS-open-timeout regression, and only surfaced once we fixed that.

Reproduce

1. Run any 3rd-party adapter that adds a top-level field to agent request params (e.g. paperclipai/adapter-openclaw-gateway).
2. Send the WS request: { kind: \"request\", method: \"agent\", params: { message, agentId, sessionKey, idempotencyKey, ...adapterMeta } }.
3. Observe errorCode=INVALID_REQUEST: at root: unexpected property '<field>'.

Why this is a problem

• Adapters legitimately need to ship metadata alongside agent wakes (run IDs, source-system context, workspace info). Today the schema gives them no escape hatch — they have to embed it in message text (lossy) or attachments[] (semantically wrong).
• The error is a hard rejection at the validation layer with no version negotiation, so any future allowlist entry that an adapter tries to use on an older gateway is a silent break.
• Today's allowlist is 35 keys curated to OpenClaw's needs. Third-party adapters can't extend it without forking the schema.

Allowlist today (35 keys)

message, agentId, provider, model, to, replyTo, sessionId, sessionKey,
thinking, deliver, attachments, channel, replyChannel, accountId,
replyAccountId, threadId, groupId, groupChannel, groupSpace, timeout,
bestEffortDeliver, lane, cleanupBundleMcpOnRunEnd, modelRun, promptMode,
extraSystemPrompt, bootstrapContextMode, bootstrapContextRunKind,
acpTurnSource, internalEvents, inputProvenance, voiceWakeTrigger,
idempotencyKey, label

(Verified by allowlist-extracting our local copy; protocol-Hjar_s3V.js line 184–227.)

Proposed fixes (any one would work; not mutually exclusive)

1. Add a typed adapterMeta/adapterContext namespace to the schema — Type.Optional(Type.Record(Type.String(), Type.Unknown())) — so adapters have an explicit contract for shipping their own metadata without polluting the top-level keyspace.
2. Relax to additionalProperties: true (or use .passthrough() equivalent) — simplest, lets adapters extend with anything, but loses validation safety on typos.
3. Add paperclip (and other known integration partners) to the allowlist as Type.Optional(Type.Unknown()) — narrowest fix; keeps the rejection as a typo-catcher.

Option 1 is cleanest for long-term ecosystem health.

Workaround we shipped

Two-layer local fix: schema patch (filename hash changes per build, so we discover it dynamically and re-apply via WatchPaths on package.json) plus a source-side strip in the offending adapter. Defense in depth verified — strip alone is sufficient, schema patch is the safety net. We'll retire both when this is fixed upstream.

Environment

• macOS 26.4.1 / arm64
• OpenClaw 2026.4.26 (be8c246)
• Paperclip @paperclipai/[email protected]