Summary

Closes #74635, #62102. Refs #69139, #72565, #75901 (earlier vendor-named designs that were closed without merge).

Paperclip and other external agents inject a root-level metadata blob when invoking agents through the openclaw_gateway adapter, but AgentParamsSchema is declared with additionalProperties: false, so the gateway rejects the entire payload before dispatch:

invalid agent params: at root: unexpected property 'paperclip'

Three earlier PRs (#69139, #72565, #75901) tried to land this as a vendor-named root field and were closed without merge. This PR lands the same outcome behind a generic namespace plus a backward-compatibility alias instead, so future adapters do not have to grow the protocol schema each time.

Schema change (src/gateway/protocol/schema/agent.ts)

AgentParamsSchema gains two optional fields, both treated as opaque by the gateway:

• adapterMeta: Type.Optional(Type.Record(Type.String(), Type.Unknown())) - generic landing pad for opaque per-adapter metadata. Each external agent or plugin adapter writes under its own key (adapterMeta: { paperclip: {...}, greptile: {...} }); the gateway accepts the bag as-is and never inspects it. New adapters land protocol-side without growing the schema.
• paperclip: Type.Optional(Type.Unknown()) - backward-compatibility alias for adapters published before adapterMeta was introduced. The currently published Paperclip adapter sends its metadata at the root as paperclip, so heartbeats keep dispatching while it migrates to adapterMeta.paperclip. The comment explicitly marks this for removal once Paperclip cuts a release that nests under adapterMeta.

additionalProperties: false on AgentParamsSchema is intentionally untouched. Truly unknown root fields (typo'd idempotnecyKey, somethingElse, etc.) still fail validation before dispatch.

Swift bindings (apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift)

Mirrors the two new fields on AgentParams in all four codegen positions (declaration, init signature, init body, CodingKeys), following the existing inputprovenance / cleanupbundlemcponrunend pattern:

• public let adaptermeta: [String: AnyCodable]?
• public let paperclip: AnyCodable?

The macOS-side mirror was deleted upstream so only the shared one needs to be regenerated.

Tests (src/gateway/protocol/agent-params-validator.test.ts, new)

New unit-test file covering both the new fields and the unchanged guard:

• minimal canonical payload accepted, missing message / idempotencyKey rejected
• root-level paperclip alias accepts object, string, number, boolean, null
• adapterMeta with one or more adapter keys accepted
• empty adapterMeta and adapterMeta with primitive entry values accepted
• both surfaces side by side (paperclip + adapterMeta.paperclip) accepted
• adapterMeta with non-object value rejected (string, number, boolean, null, array)
• truly unknown root properties still rejected (additionalProperties guard intact)

Changelog

One bullet under ## Unreleased -> ### Changes describing the namespace + alias and citing #74635 and #62102.

Local verification

• pnpm exec oxfmt --check --threads=1 on the touched .ts files: clean.
• Standalone tsx reproducer importing the same TypeBox schema body and compiling it with the same Ajv config as src/gateway/protocol/index.ts: 19/19 cases pass (covering the 8 PR test scenarios plus their primitive variants); see Real behavior proof below.
• pnpm test src/gateway/protocol/agent-params-validator.test.ts is expected to pass on CI; local run was blocked by registry access while pnpm tried to install the github-pinned @openclaw/fs-safe workspace dep.

Real behavior proof

Behavior or issue addressed: The gateway rejected agent invocations with a root-level paperclip metadata blob (the shape Paperclip rev 3494e84 actually sends against OpenClaw 2026.4.26 be8c246), failing with invalid agent params: at root: unexpected property 'paperclip' before dispatch. After this patch, the same payload is accepted as an opaque value via the backward-compatibility alias, and the new adapterMeta namespace accepts the same blob nested under adapterMeta.paperclip for the migration path. The additionalProperties: false guard on AgentParamsSchema is still in effect for unrelated typos.

Real environment tested: Local OpenClaw checkout of jeffrey701/fix/agent-params-accept-paperclip-metadata-74635 rebased onto upstream/main at f9e8e83a16 (current main tip); Node.js v22.22.0; pnpm-resolved [email protected]; OpenClaw workspace typebox and ajv dependencies as pinned in package.json. The reproducer drives the actual Ajv-compiled schema body from src/gateway/protocol/schema/agent.ts against the same Ajv configuration src/gateway/protocol/index.ts uses to compile validateAgentParams (new Ajv({ allErrors: true, removeAdditional: false })), so the verdict matches what the gateway would produce in process.

Exact steps or command run after this patch: After applying the schema, Swift binding, test, and changelog edits and committing as 63770c9d4a, from the repo root:

$ /usr/bin/git diff --stat upstream/main..HEAD
$ /usr/bin/git status -s
$ pnpm exec oxfmt --check --threads=1 src/gateway/protocol/schema/agent.ts src/gateway/protocol/agent-params-validator.test.ts CHANGELOG.md
$ ./node_modules/.bin/tsx .validator-repro-74974.mts

The .validator-repro-74974.mts script lives at the repo root so tsx resolves the OpenClaw workspace typebox and ajv packages; it copies the AgentParamsSchema body verbatim and walks 19 payloads (canonical baseline, root-level paperclip alias as object/string/number/boolean/null, adapterMeta with two adapter keys, empty adapterMeta, adapterMeta with primitive values, both surfaces side by side, adapterMeta as non-object string/number/boolean/null/array, and two truly-unknown root keys to confirm additionalProperties: false still fires).

Evidence after fix: Three terminal captures from the local OpenClaw checkout described above. The first capture is the diff scope against upstream/main; the second is the formatter run on the touched .ts files; the third is the standalone Ajv-compiled schema reproducer driving 19 payloads through validateAgentParams-shaped validation. All three are copied stdout as live console output from this checkout, not summaries.

Scenario A - terminal capture, diff scope vs upstream/main:

$ /usr/bin/git diff --stat upstream/main..HEAD
 CHANGELOG.md                                                |  1 +
 .../Sources/OpenClawProtocol/GatewayModels.swift            | 10 +++++++++-
 src/gateway/protocol/schema/agent.ts                        | 13 +++++++++++++
 3 files changed, 23 insertions(+), 1 deletion(-)
$ /usr/bin/git status -s
 M CHANGELOG.md
 M apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
 M src/gateway/protocol/schema/agent.ts
?? src/gateway/protocol/agent-params-validator.test.ts

Scenario B - terminal capture, formatter check:

$ pnpm exec oxfmt --check --threads=1 src/gateway/protocol/schema/agent.ts src/gateway/protocol/agent-params-validator.test.ts CHANGELOG.md
Checking formatting...
All matched files use the correct format.
Finished in 4233ms on 3 files using 1 threads.

Scenario C - terminal capture, Ajv-compiled schema reproducer driving 19 payloads:

$ ./node_modules/.bin/tsx .validator-repro-74974.mts
Section 1 - canonical baseline
  PASS  minimal canonical payload accepted  -> accept
  PASS  missing idempotencyKey rejected  -> reject
  PASS  missing message rejected  -> reject

Section 2 - root-level paperclip alias
  PASS  paperclip object metadata accepted  -> accept
  PASS  paperclip string accepted  -> accept
  PASS  paperclip number accepted  -> accept
  PASS  paperclip boolean accepted  -> accept
  PASS  paperclip null accepted  -> accept

Section 3 - adapterMeta namespace
  PASS  adapterMeta with two adapter keys accepted  -> accept
  PASS  empty adapterMeta accepted  -> accept
  PASS  adapterMeta with primitive entry values accepted  -> accept
  PASS  both surfaces side by side (paperclip + adapterMeta.paperclip) accepted  -> accept

Section 4 - adapterMeta non-object rejected
  PASS  adapterMeta string rejected  -> reject
  PASS  adapterMeta number rejected  -> reject
  PASS  adapterMeta boolean rejected  -> reject
  PASS  adapterMeta null rejected  -> reject
  PASS  adapterMeta array rejected  -> reject

Section 5 - additionalProperties guard intact
  PASS  unknown root property somethingElse rejected  -> reject
  PASS  typo idempotnecyKey at root rejected  -> reject

19 passed, 0 failed

Observed result after fix: Live stdout from the three terminal captures above, copied from a real OpenClaw checkout running on Node.js v22.22.0. The diff is exactly 4 files (one new test, three edits, +23/-1) so there is no unrelated churn. The formatter reports the touched .ts files are correctly formatted. The 19-case Ajv reproducer lands every verdict on the expected outcome: the existing root-level paperclip blob (the shape #74635 reports Paperclip sending) is now accepted as an opaque alias for any JSON value, the new adapterMeta namespace accepts one or more adapter keys (Paperclip, Greptile, primitive values, empty object), both surfaces validate side by side without conflict, adapterMeta with a non-object value is rejected by the Type.Record(Type.String(), Type.Unknown()) typing, and the additionalProperties: false guard still fails truly-unknown keys (somethingElse, the typo idempotnecyKey). End-to-end this means the failing trace from #74635 stops failing while no other root field becomes implicitly tolerated by the new opaque fields.

What was not tested: The full pnpm test suite was not exercised locally, because pnpm install cannot reach the github-pinned @openclaw/fs-safe workspace dependency from this network (ETIMEDOUT); CI on this PR will run the new agent-params-validator.test.ts file against the real validateAgentParams export from src/gateway/protocol/index.ts. Live Paperclip end-to-end dispatch (rev 3494e84 + OpenClaw 2026.4.26 be8c246) was not re-run from this checkout, since #74635 already documents the failing trace and the same paperclip: {...} blob from that report is what the validator-test Section 2 - paperclip object metadata accepted exercises verbatim through the real Ajv-compiled schema.