PR #10: fix(gateway): allow optional paperclip field in AgentParamsSchema

• Repository: suboss87/openclaw
• Author: suboss87
• State: closed | merged: False
• Link: https://github.com/suboss87/openclaw/pull/10

Description (problem / solution / changelog)

What and why

Paperclip now injects a paperclip property into the root of its agent invocation payload when calling the openclaw_gateway adapter. Because AgentParamsSchema has additionalProperties: false, the gateway rejected every Paperclip-triggered invocation with:

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

Agents stayed in error status and tasks never executed.

Root cause

AgentParamsSchema in src/gateway/protocol/schema/agent.ts (line 74) does not include a paperclip property. Any field not listed in the schema is rejected by the AJV validator compiled at index.ts:265.

Fix

Add paperclip: Type.Optional(Type.Unknown()) to AgentParamsSchema. The field is optional and untyped - OpenClaw passes it through without inspecting it, similar to how attachments: Type.Optional(Type.Array(Type.Unknown())) already works for opaque attachment payloads.

Testing

• Added validateAgentParams regression test: verifies a payload with paperclip: { runId: "...", workspaceId: "..." } is accepted (previously returned false, now returns true).
• Added complementary test: confirms truly unknown fields still fail, so the additionalProperties: false guard is still enforced for everything else.

Fixes #74635

Generated by Claude Code

Changed files

• src/gateway/protocol/index.test.ts (modified, +23/-1)
• src/gateway/protocol/schema/agent.ts (modified, +1/-0)

PR #12: fix(gateway): allow Paperclip integration metadata through AgentParams validator

• Repository: suboss87/openclaw
• Author: suboss87
• State: open | merged: False
• Link: https://github.com/suboss87/openclaw/pull/12

Description (problem / solution / changelog)

Closes openclaw/openclaw#74635

Problem

The AJV-compiled validateAgentParams validator is compiled with additionalProperties: false from AgentParamsSchema. Any gateway RPC call that includes a paperclip field (Paperclip integration metadata attached by the iOS/macOS app) is rejected with a validation error before reaching the agent runner.

Root cause

AgentParamsSchema in src/gateway/protocol/schema/agent.ts had no paperclip property. The TypeBox schema uses additionalProperties: false, so AJV rejects any unknown top-level property including paperclip.

Fix

Added paperclip: Type.Optional(Type.Unknown()) to AgentParamsSchema. Using Type.Unknown() keeps it maximally permissive -- Paperclip metadata is opaque to the gateway and only consumed downstream by Paperclip-aware agents.

Tests

Added two regression tests to src/gateway/protocol/index.test.ts:

• accepts agentParams with paperclip metadata -- verifies validateAgentParams({ ..., paperclip: { source: "paperclip", attachmentId: "abc" } }) returns true
• rejects agentParams with an unrecognized unknown field -- verifies validateAgentParams({ ..., unknownField: true }) still returns false (strict mode preserved)

Generated by Claude Code

Changed files

• src/gateway/protocol/index.test.ts (modified, +23/-1)
• src/gateway/protocol/schema/agent.ts (modified, +1/-0)