版本控制
客户端可以协商哪些协议版本，以及参考客户端随附的常量。
版本管理¶
PROTOCOL_VERSION、MIN_CLIENT_PROTOCOL_VERSION、MIN_NODE_PROTOCOL_VERSION和MIN_PROBE_PROTOCOL_VERSION位于packages/gateway-protocol/src/version.ts中。- 客户端发送
minProtocol+maxProtocol。操作员和 UI 客户端必须在该范围内包含当前协议；当前客户端和服务器运行协议 v4。 - 同时具有
role: "node"和client.mode: "node"的已认证客户端可以使用 N-1 节点协议（v3）。轻量级重启探测使用相同的 N-1 窗口。设备认证、配对、作用域、命令策略和 exec 审批不受此兼容窗口的影响。插件拥有的节点能力和命令在节点升级到当前协议之前会被保留，因为它们托管的接口不属于 N-1 契约的一部分。 - 模式和模型由 TypeBox 定义生成：
pnpm protocol:genpnpm protocol:gen:swiftpnpm protocol:check
客户端常量¶
参考客户端实现位于 packages/gateway-client/src/（OpenClaw 通过精简的 src/gateway/client.ts 门面将其包装）。这些默认值在协议 v4 中保持稳定，是第三方客户端的预期基线。
| 常量 | 默认值 | 来源 |
|---|---|---|
PROTOCOL_VERSION |
4 |
packages/gateway-protocol/src/version.ts |
MIN_CLIENT_PROTOCOL_VERSION |
4 |
packages/gateway-protocol/src/version.ts |
MIN_NODE_PROTOCOL_VERSION |
3 |
packages/gateway-protocol/src/version.ts |
MIN_PROBE_PROTOCOL_VERSION |
3 |
packages/gateway-protocol/src/version.ts |
| 请求超时（每次 RPC） | 30_000 毫秒 |
packages/gateway-client/src/client.ts（requestTimeoutMs） |
| 预认证 / 连接挑战超时 | 15_000 毫秒 |
packages/gateway-client/src/timeouts.ts（OPENCLAW_HANDSHAKE_TIMEOUT_MS 环境变量可以提高配对服务器/客户端的预算） |
| 初始重连退避 | 1_000 毫秒 |
packages/gateway-client/src/client.ts（GATEWAY_RECONNECT_POLICY） |
| 最大重连退避 | 30_000 毫秒 |
packages/gateway-client/src/client.ts（GATEWAY_RECONNECT_POLICY） |
| 设备令牌关闭后的快速重试上限 | 250 毫秒 |
packages/gateway-client/src/client.ts |
terminate() 之前的强制停止宽限期 |
250 毫秒 |
FORCE_STOP_TERMINATE_GRACE_MS |
stopAndWait() 默认超时 |
1_000 毫秒 |
STOP_AND_WAIT_TIMEOUT_MS |
默认 tick 间隔（hello-ok 之前） |
30_000 毫秒 |
packages/gateway-client/src/client.ts |
| Tick 超时关闭 | 当静默超过 tickIntervalMs * 2 时使用代码 4000 |
packages/gateway-client/src/client.ts |
MAX_PAYLOAD_BYTES |
25 * 1024 * 1024（25 MB） |
src/gateway/server-constants.ts |
| 聊天附件上限 | agents.defaults.mediaMaxMb，默认解码后 20 MB |
src/gateway/chat-attachment-policy.ts |
| 聊天附件图片上限 | min(attachment ceiling, 6 MB) |
src/gateway/chat-attachment-policy.ts、packages/media-core/src/constants.ts |
服务器在 hello-ok 中通告有效的 policy.tickIntervalMs、policy.maxPayload、policy.maxBufferedBytes 和 policy.attachments；客户端应遵循这些值，而不是握手前的默认值或硬编码的附件大小。
当每个待处理请求都有配置的截止时间时，参考客户端会允许有限请求拥有其配置的截止时间。没有有限 timeoutMs 的 expectFinal 请求、任何 timeoutMs: null 的请求，或有限与无限请求的混合，都会使 tick 看门狗保持活动状态。如果入站事件和响应在超过 tick 超时阈值后仍保持静默，客户端将使用代码 4000 关闭套接字，拒绝所有待处理请求，并重新连接。重新连接后，它不会重放被拒绝的请求。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw