跳转至

版本管理

客户端可以协商哪些协议版本,以及参考客户端随附的常量。

版本控制

  • PROTOCOL_VERSION、MIN_CLIENT_PROTOCOL_VERSION、 MIN_NODE_PROTOCOL_VERSION 和 MIN_PROBE_PROTOCOL_VERSION 位于 packages/gateway-protocol/src/version.ts。
  • 客户端发送 minProtocol + maxProtocol。Operator 和 UI 客户端必须 在该范围内包含当前协议;当前客户端和服务器运行 协议 v4。
  • 同时具有 role: "node" 和 client.mode: "node" 的已认证客户端可以使用 N-1 节点协议(v3)。轻量级重启检查使用 相同的 N-1 窗口。设备认证、配对、作用域、命令策略和执行 审批不会因该兼容性窗口而改变。插件拥有的节点 能力和命令会在节点升级到当前协议之前暂不暴露,因为其托管界面不属于 N-1 契约。
  • 模式和模型从 TypeBox 定义生成:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm 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 ms packages/gateway-client/src/client.ts (requestTimeoutMs)
预认证 / 连接质询超时 15_000 ms packages/gateway-client/src/timeouts.ts(OPENCLAW_HANDSHAKE_TIMEOUT_MS 环境变量可提高成对的服务器/客户端预算)
初始重连退避 1_000 ms packages/gateway-client/src/client.ts (GATEWAY_RECONNECT_POLICY)
最大重连退避 30_000 ms packages/gateway-client/src/client.ts (GATEWAY_RECONNECT_POLICY)
设备令牌关闭后的快速重试上限 250 ms packages/gateway-client/src/client.ts
terminate() 前的强制停止宽限期 250 ms FORCE_STOP_TERMINATE_GRACE_MS
stopAndWait() 默认超时 1_000 ms STOP_AND_WAIT_TIMEOUT_MS
默认 tick 间隔(hello-ok 之前) 30_000 ms 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 关闭套接字,拒绝所有待处理请求,并重连。它不会在重连后重放被拒绝的请求。

本地状态所有者路由

受支持的本地管理命令在打开可变更状态之前,会先发现拥有其选定物理状态目录的进程。存活的拥有者会在其记录的本地端口上接收经过身份验证的 RPC;已配置的远程 Gateway 或 URL 覆盖不会重定向这些本地目标。如果没有拥有者,CLI 会获取独占的生命周期所有权,并保留该所有权,直到已接受的工作和清理完成。无法访问、无法检查或仍在启动中的拥有者,并不证明该目录已离线。

这些路由要求 hello-ok.features.capabilities 中包含 operator.admin 和 local-state-owner-routing-v1。仅存在方法并不足够。除创建外(创建由该原始能力覆盖),每个操作还需要其自身的能力:

本地操作 RPC 附加能力
worktrees create worktrees.create 无
worktrees remove,包括无损和精确状态模式 worktrees.remove worktrees-remove-owner-v1
worktrees restore,包括精确状态恢复 worktrees.restore worktrees-restore-owner-v1
worktrees gc worktrees.gc worktrees-gc-owner-v1
worktrees recover-removal worktrees.recoverRemoval worktrees-recover-removal-owner-v1
worktrees retire-snapshot worktrees.retireSnapshot worktrees-retire-snapshot-owner-v1
pairing list channels.pairing.list channels-pairing-list-owner-v1
pairing approve channels.pairing.approve channels-pairing-approve-owner-v1
默认 approvals get exec.approvals.get exec-approvals-get-owner-v1
默认 approvals set 和允许列表编辑 exec.approvals.set exec-approvals-set-owner-v1

CLI 发送发现的 expectedOwnerId;服务器在产生效果前检查当前拥有者和请求者。工作树创建还会携带 expectedRepoIdentity,作为所捕获仓库目录的 device:inode。这些字段标识预期的拥有者和目标;它们不授予任何权限。参见 工作树请求和结果契约、通道配对 以及 审批快照。

拒绝与不确定结果

CLI 区分 OWNER_UNAVAILABLE(无法建立所有权)、OWNER_REFUSED(未发生分发,或服务器在变更前明确拒绝)和 OUTCOME_UNKNOWN(已分发的操作可能已生效)。带有 details.mutationAccepted: false 的服务器错误标识明确的变更前拒绝;分发后的其他错误不能证明回滚。

这些状态中的任何一个都不会触发本地回退或自动重放。对于较旧的 Gateway、缺失能力或身份验证拒绝,请更新 Gateway 或修复身份验证。若要离线工作,请通过其服务拥有者停止 Gateway,等待所有权释放,然后重新运行完全相同的命令。在收到不确定的响应后,在决定是否重试之前,检查目标及其特定于操作的状态或恢复输出。本地路由为现有拥有者操作最多允许十分钟;超时不会转移所有权。

混合版本与保留边界

新客户端要求其操作的完整能力,即使较旧的 Gateway 通告了相同的方法。它们从不丢弃选择器或保护条件,以使旧请求适配。现有 RPC 客户端可以在早于路由的方法上省略附加的拥有者字段,并保留其现有响应契约。新的 worktrees.recoverRemoval 和 worktrees.retireSnapshot 方法要求 expectedOwnerId。

较旧的 CLI 和 SDK 二进制文件保留其现有直接写入行为。路由不会拦截这些写入、任意受信任 SQL,或共享外部数据库的另一个状态根。请匹配 CLI、Gateway 和 SDK 版本;调用方必须保留其现有外部提交新鲜度检查。路由覆盖上述命名操作;它不保证 Gateway 是唯一的 SQLite 写入者。

以下边界保留其现有拥有者和契约:

边界 保留行为
设备引导 隐式环回设备配对恢复、QR/设置码签发以及 SDK 设备令牌保留在引导拥有者处,因此获取 RPC 凭据不需要先拥有这些凭据。
配置和代理设置 代理身份、绑定和配置编辑保留文件写入/重载行为。交互式代理创建和入门仍会在本地暂存身份验证、插件、工作区和配置;其权威提交未迁移到该路由。
边界 保留的行为
执行策略同步 exec-policy preset 和 exec-policy set 保留其现有的本地配置/策略所有者。对 approvals 命令进行路由不会改变这些操作或执行授权。
凭据 模型认证密钥/顺序和 SDK 认证写入、MCP OAuth、密钥存储编辑,以及通道认证保留其现有的锁定、失效和生命周期所有者。
客户端偏好 TUI 的记忆会话仍然是客户端偏好写入,而非会话权限。
插件和投递状态 插件键控存储和去重保留插件所有权;投递队列操作保留出站所有者准入。
会话和工作区 SDK 会话入口、维护、目录/导入/链接、转录/回调,以及 workspace/worktree API 保留其现有契约。会话清理、agent 删除,以及外部 SDK 的 workspace/worktree 变更不在此路由契约范围内。
原始存储 API 原始 cron 替换和低级 SQLite SDK/原生访问不会因 CLI 路由而变为独占。在可用时优先使用领域 RPC;不同进程中的 worker 仍然是外部写入者。
离线和维护所有者 sandbox recreate 需要独占的离线所有权。嵌入式执行、重置/卸载、启动准入、迁移、Doctor 和更新保留其现有生命周期所有者。

更新不需要新的路由 RPC 来安装提供它的版本。 已安装的更新器和候选 Doctor 保留其停止、排空、备份、 维护和最终化契约。此路由不引入协议版本、 模式、配置、保留或持久性变更。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw