Bug 报告AgentParams Schema 严格模式拒绝 Paperclip 的 paperclip 属性 / Schema .strict() rejects paperclip property from Paperclip wake payload链接: https://blog.csdn.net/cosmoslife作者: cosmoslife日期: 2026/04/18 11:25:15仓库: openclaw/openclaw创建时间: 2026-04-18 |关闭时间: 未关闭修复 PR: 无尚未修复现象升级 Paperclip 到 2026.416.0 后所有通过openclaw_gateway适配器发起的运行均失败错误信息为invalid agent params: at root: unexpected property paperclip。Paperclip 2026.416.0 在 wake payload 中新增了paperclip: {...}对象但 OpenClaw 的网关协议 schema 使用additionalProperties: false严格模式拒绝了任何未显式声明的属性。结果所有 Paperclip OpenClaw 集成完全中断。复现步骤安装 Paperclip 2026.416.0npx paperclipai onboard安装 OpenClaw 2026.4.15WSL2 或其他环境在 Paperclip 中创建openclaw_gateway适配器类型的 agent配置网关 URL、token、chat ID创建任何分配给该 agent 的 issue触发运行观察运行失败invalid agent params: at root: unexpected property paperclip根因分析触发条件当 Paperclip 2026.416.0 通过 WebSocket 向 OpenClaw 网关发送 agent 请求时payload 包含一个新的paperclip属性。OpenClaw 网关在处理请求前会通过 JSON Schema 校验器基于 TypeBox AJV验证 payload而AgentParamsSchema设置了additionalProperties: false导致包含未声明属性的 payload 被拒绝。代码位置网关协议 Schema:src/gateway/protocol/schema/agent.ts第 129-172 行网关请求处理:src/gateway/server-methods/agent.ts第 310-319 行Schema 编译与验证:src/gateway/protocol/index.ts第 314 行缺陷本质AgentParamsSchema使用 TypeBox 定义带additionalProperties: false选项。这是严格的白名单模式——只有显式列出的属性才被接受。Paperclip 2026.416.0 新增了paperclip属性但该属性未在AgentParamsSchema中声明因此整个 payload 被拒绝。这是一个跨产品 schema 同步失败Paperclip 团队在不改变 OpenClaw 网关协议 schema 的情况下在 wake payload 中添加了新字段。相关代码修复前// src/gateway/protocol/schema/agent.ts:129-172exportconstAgentParamsSchemaType.Object({message:NonEmptyString,agentId:Type.Optional(NonEmptyString),provider:Type.Optional(Type.String()),model:Type.Optional(Type.String()),to:Type.Optional(Type.String()),replyTo:Type.Optional(Type.String()),sessionId:Type.Optional(Type.String()),sessionKey:Type.Optional(Type.String()),thinking:Type.Optional(Type.String()),deliver:Type.Optional(Type.Boolean()),attachments:Type.Optional(Type.Array(Type.Unknown())),channel:Type.Optional(Type.String()),replyChannel:Type.Optional(Type.String()),accountId:Type.Optional(Type.String()),replyAccountId:Type.Optional(Type.String()),threadId:Type.Optional(Type.String()),groupId:Type.Optional(Type.String()),groupChannel:Type.Optional(Type.String()),groupSpace:Type.Optional(Type.String()),timeout:Type.Optional(Type.Integer({minimum:0})),bestEffortDeliver:Type.Optional(Type.Boolean()),lane:Type.Optional(Type.String()),extraSystemPrompt:Type.Optional(Type.String()),bootstrapContextMode:Type.Optional(Type.Union([Type.Literal(full),Type.Literal(lightweight)]),),bootstrapContextRunKind:Type.Optional(Type.Union([Type.Literal(default),Type.Literal(heartbeat),Type.Literal(cron)]),),internalEvents:Type.Optional(Type.Array(AgentInternalEventSchema)),inputProvenance:Type.Optional(InputProvenanceSchema),idempotencyKey:NonEmptyString,label:Type.Optional(SessionLabelString),},{additionalProperties:false},// BUG: 拒绝 Paperclip 的 paperclip 属性);// src/gateway/server-methods/agent.ts:310-319if(!validateAgentParams(p)){respond(false,undefined,errorShape(ErrorCodes.INVALID_REQUEST,invalid agent params:${formatValidationErrors(validateAgentParams.errors)},),);return;}Paperclip 发送的 payload{message:Paperclip wake event for a cloud adapter...,sessionKey:paperclip,idempotencyKey:uuid,paperclip:{runId:uuid,companyId:uuid,agentId:uuid,agentName:OpenClaw,wakeReason:retry_failed_run,apiUrl:http://localhost:3100/,cwd:C:\\Users\\...\\workspaces\\uuid,source:agent_home,mode:shared_workspace,strategy:project_primary,timeout:120000}}修复方案修复策略方案 A最小修复 - 推荐在AgentParamsSchema中添加paperclip作为可选的Type.Unknown()字段。接受但不验证其内容。方案 B完整修复为paperclip属性定义完整的 TypeBox schema包含所有子字段进行严格验证。方案 C架构改进将additionalProperties改为允许特定扩展属性或添加一个通用的metadata/extra字段供外部编排器使用。关键变更方案 A// src/gateway/protocol/schema/agent.tsexportconstAgentParamsSchemaType.Object({// ... 现有字段 ...idempotencyKey:NonEmptyString,label:Type.Optional(SessionLabelString),// 新增接受 Paperclip 编排器元数据paperclip:Type.Optional(Type.Unknown()),},{additionalProperties:false},);新增测试验证包含paperclip属性的 payload 能通过validateAgentParams校验验证不含paperclip属性的现有 payload 不受影响测试 Paperclip 完整 wake payload 的端到端流程影响评估受影响功能: 所有 Paperclip OpenClaw 的openclaw_gateway适配器集成受影响版本: OpenClaw 2026.4.15041266a Paperclip 2026.416.0严重程度: 高 — 适配器完全不可用100% 失败率受影响用户: 所有升级了 Paperclip 到 2026.416.0 的 OpenClaw 用户规避方法: 降级 Paperclip 到 2026.416.0 之前的版本经验教训严格的additionalProperties: false需要向前兼容策略当外部产品向 payload 添加新字段时严格模式会导致立即中断。应考虑使用additionalProperties: true或添加一个extra/metadata透传字段。跨产品 schema 应有协调机制Paperclip 和 OpenClaw 应共享 wake payload 的 schema 定义或在发布前进行集成测试。网关协议应设计为可扩展网关作为中间层应能容忍上游产品添加的新字段即使自身不使用这些字段。TypeBox 的additionalProperties默认行为与 Zod 的.strict()类似都拒绝未知字段。设计协议时应权衡安全性和兼容性。参考资料源文件:src/gateway/protocol/schema/agent.tsAgentParamsSchema定义源文件:src/gateway/server-methods/agent.ts参数验证路径源文件:src/gateway/protocol/index.tsSchema 编译与验证相关文件:src/config/zod-schema.agent-runtime.tsZod 侧的 AgentEntrySchema