系统与通道

面向网关状态与身份、模型与用量、渠道与登录、插件管理、消息与日志，以及操作员终端的 RPC 方法族。

系统与身份¶

• health 返回缓存或新探测到的网关健康快照。
• diagnostics.stability 返回近期的有界诊断稳定性记录器：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称、会话 ID。不包含聊天文本、webhook 请求体、工具输出、原始请求/响应体、令牌、Cookie 或机密。需要 operator.read 权限。
• status 返回 /status 风格的网关摘要；敏感字段仅对具有 admin 作用域的操作员客户端可见。
• gateway.identity.get 返回用于中继和配对流程的网关设备身份。
• system-presence 返回已连接操作员/节点设备的当前在线状态快照。
• system-event 追加一个系统事件，并可更新/广播在线状态上下文。
• last-heartbeat 返回最新持久化的心跳事件。
• set-heartbeats 切换网关上的心跳处理。
• gateway.restart.preflight 是一个已弃用的只读兼容性预览，用于查看与重启相关的进行中工作。它不会关闭准入、创建挂起租约，也不会提供 gateway.suspend.prepare 那样的原子性全部工作栅栏；新的重启流程应调用 gateway.restart.request。
• gateway.suspend.prepare 仅在已跟踪的网关工作空闲时创建短期协作式挂起租约。处于已准备状态期间，已认证的 WebSocket 连接仍然可用，但只允许运行 gateway.suspend.* 以及精确指定目标且非安全的 gateway.restart.request；安全且未指定目标的重启仍保持被栅栏隔离。gateway.suspend.status 检查租约，gateway.suspend.resume 在解冻或宿主机操作中止后释放该租约。

模型与用量¶

• models.list 返回运行时允许的模型目录。参见 models.list 视图。
• usage.status 返回提供商用量窗口/剩余配额摘要。声明支持 usage-refreshing 的客户端在冷缓存上会立即收到一个 refreshing: true 占位结果，并且必须按有界计划重新获取；其他调用方会阻塞等待提供商冷数据读取完成。
• usage.cost 返回指定日期范围内的聚合成本用量摘要。传入 agentId 可查询单个智能体，或传入 agentScope: "all" 聚合已配置的智能体。
• doctor.memory.status 返回当前默认智能体工作区的向量内存/缓存嵌入就绪状态。仅在需要显式对实时嵌入提供商执行 ping 时，才传入 { "probe": true } 或 { "deep": true }。传入 { "agentId": "agent-id" } 可将 Dreaming 存储统计限定到单个智能体工作区；省略该参数则聚合所有已配置的 Dreaming 工作区。
• doctor.memory.dreamDiary、doctor.memory.backfillDreamDiary、doctor.memory.resetDreamDiary、doctor.memory.resetGroundedShortTerm、doctor.memory.repairDreamingArtifacts 和 doctor.memory.dedupeDreamDiary 接受可选的 { "agentId": "agent-id" }；省略时，它们作用于已配置的默认智能体工作区。
• sessions.usage 返回按会话的用量摘要。传入 agentId 可查询单个智能体，或传入 agentScope: "all" 将已配置的智能体一起列出。 这两个用量方法都接受 mode: "specific"，配合 IANA timeZone 以支持感知夏令时的日历日边界与分桶。utcOffset 仍然受支持，用于旧客户端，并在网关运行时无法识别所请求时区时作为回退。
• sessions.usage.timeseries 返回单个会话的时间序列用量。
• sessions.usage.logs 返回单个会话的用量日志条目。 这两个详情方法都接受所选行的 key 和可选的 agentId。当打开不带限定符的键（如 global）的详情时，请同时保留这两个字段。

渠道与登录辅助¶

• channels.status 返回内置及捆绑的渠道/插件状态摘要。
• channels.start（operator.admin）启动一个渠道账户运行时，无需重新认证。参数为 { channel, accountId? }；省略 accountId 时选择默认账户。响应为 { channel, accountId, started, outcome }；仅当结果运行时快照报告 running: true 时，started 才为 true。outcome 携带账户生命周期决策：{ status: "handed-off" }、{ status: "retry", reason } 或 { status: "skipped", reason }。此 RPC 是自动启动抑制的手动覆盖机制；不接受 manual 参数。这不是提供商连通性检查；原因和恢复指导请参阅 按账户恢复。
• channels.stop（operator.admin）停止一个渠道账户运行时，但不清除认证状态。参数为 { channel, accountId? }；省略 accountId 时选择默认账户。响应为 { channel, accountId, stopped }；当结果运行时快照未报告 running: true 时，stopped 为 true。与 channels.logout 不同，它会保留该账户的凭据。
• channels.logout 在渠道支持的情况下注销特定的渠道/账户。
• web.login.start 启动二维码/网页登录流程。参数包含可选的 { channel, accountId, force, timeoutMs, verbose }。当存在 channel 时，网关会将其规范 ID 或别名规范化，并仅分派到该已安装的渠道插件。省略 channel 会保留旧版行为，即选择第一个已加载的支持二维码的提供商。提供商可在其二维码响应中返回不透明的 sessionKey。
• web.login.wait 等待该流程完成，并在成功后启动渠道。参数包含可选的 { channel, accountId, sessionKey, timeoutMs, currentQrDataUrl }。请使用与 web.login.start 相同的 channel，并将其返回的 sessionKey 原样透传，以便提供商将等待请求与二维码会话关联。省略 channel 会保留与 web.login.start 相同的旧版提供商回退行为。
• push.test 向已注册的 iOS 节点发送一条测试 APNs 推送。
• voicewake.get 返回已存储的唤醒词触发器。
• voicewake.set 更新唤醒词触发器并广播该变更。

插件管理¶

• plugins.list (operator.read) 返回已安装插件清单，以及本地精选的官方推荐、诊断信息，和当前安装模式是否允许变更。它包含当前运行时 generation，并将每个插件的运行时状态与已配置的启用状态分开。
• plugins.inspect (operator.read) 使用 { pluginId } 检查一个插件，包括声明的能力、授权、信任详情，以及用于能力同意的 reviewToken。
• plugins.search (operator.read) 搜索可安装的 ClawHub 代码插件和捆绑插件系列。传入非空的 query 以及 1 到 100 之间的可选 limit。
• plugins.catalog.browse (operator.read) 返回 ClawHub 发现结果，并附带 Gateway 本地的已安装和捆绑状态。Control UI 仅在手动输入至少两个字符并稳定 250 ms 后添加 searchSource: "openclaw-control-ui"。初始浏览、刷新、筛选器更改和通用 API 搜索会省略它。Gateway 遵循 CLAWHUB_DISABLE_TELEMETRY，并且在瞬时故障后不会重放已归因的 HTTP 搜索。ClawHub 会记录规范化查询、来源和远程结果计数；这些计数不包括 Gateway 添加的仅限本地的匹配项。已安装清单以及操作员、设备和会话身份不会包含在观察数据中。
• plugins.install (operator.admin) 接受以下特定于来源的请求字段：

每个请求还可以包含 mode: "install" | "update"、acknowledgeInstallPolicyWarning: true 以及 acknowledgeCapabilities: { reviewToken }。省略 mode 表示安装。本地路径、npm-pack 归档、marketplace 源和本地 Git 源需要 Gateway 识别为本地的连接；路径指向该 Gateway 主机。对于特定官方包版本，请使用 npm 规范。

当安装策略返回 warn 时，错误 details 包含 installPolicyCode: "install_policy_warning_acknowledgement_required"、目标、原因和可选的发现。审核之后，使用 acknowledgeInstallPolicyWarning: true 重试同一操作会批准该安装调用中的所有警告；在安装继续之前，每个警告都会重新评估。block 和策略失败仍然是终止性的。ClawHub 安装会保留 Gateway 信任和完整性检查。

• plugins.setEnabled (operator.admin) 使用 { pluginId, enabled, acknowledgeCapabilities? } 更改一个已安装插件的启用策略。响应包含更新后的目录项以及任何插槽选择警告。
• plugins.reload (operator.admin) 使用 { plugins: [{ pluginId, installHash?, sourceDigests? }], acknowledgeCapabilities? } 重新加载一个或多个已发现的插件，并保留已配置的启用状态。发送 1–64 个目标；单插件请求使用相同的数组信封。响应包含 pluginIds、布尔值 restartRequired 以及必需的 runtime 回执。当编译后的捆绑代码在其文件更改后仍保留其已加载模块时，restartRequired 为 true，并且结果会说明原因。
• plugins.refresh (operator.admin) 使用 {} 刷新插件元数据并应用生成的注册表。
• plugins.uninstall (operator.admin) 使用 { pluginId, keepFiles? } 移除一个外部安装的插件：配置引用、安装记录和受管文件。捆绑插件无法卸载，只能禁用。响应会列出移除操作。

仅运行时刷新适用于只读、Nix 管理的以及根 $include 配置，且不会重写它们。 当另一个插件或配置操作正在应用时，插件生命周期和 Claw 包移除请求会返回可重试的 UNAVAILABLE，并带有 retryAfterMs。此繁忙响应发生在请求的变更开始之前；请在当前操作完成后重试。变更开始后的失败会保留其应用详情，并且不会自动重试。

这些变更会等待运行时应用完成，而不会重启 Gateway。成功响应包含 restartRequired 以及带有 operationId、generation、pluginIds 和可选 sourceDigests 的 runtime 回执。重新加载未更改的捆绑代码或替换已捕获的外部代码会返回 restartRequired: false；仍保持加载状态的已编辑捆绑代码，或无法验证其文件的代码，需要重启。Gateway 会在发布后广播带有 { generation } 的 plugins.changed。运行时替换错误包含 details.runtime.phase 和 details.runtime.committed，因此客户端可以区分发布前的拒绝与新代际激活后的失败。

如果多步变更发布了运行时但随后失败，details.runtime 会保留带有 committed: true 的已发布回执。后续在发布前失败的替换会在 details.runtimeAttempt 中单独报告。客户端应在任何已提交更改后刷新其运行时视图，即使整体变更失败。

安装错误还可能包含 details.persistence: { operation: "install", pluginId }。这表示安装已保存，独立于运行时发布。刷新已安装清单和配置；修复报告的问题并重新加载已安装插件，而不是盲目重复安装。details.runtime.committed: false 并不意味着安装已回滚。

安装、启用和重新加载可能需要能力同意。审查已声明的能力后，传入 acknowledgeCapabilities: { reviewToken }；该令牌会在应用前对照最新检查进行校验。这与安装策略警告批准是分开的。参见 插件管理。

重新加载前置条件可选。installHash 是规范化的已保存安装记录的小写 SHA-256，并且需要受跟踪的包。sourceDigests 将已解析的运行时插件 ID 映射到小写 SHA-256 源摘要。受跟踪的目标会解析其整个包；没有安装记录的捆绑源或配置源会解析其发现的运行时 ID。模糊、缺失或冲突的受管所有权仍会拒绝该请求。Gateway 会在同意前后检查目标所有权和预期记录，然后将源预期与其加载的捕获代码进行验证。同意可以更新已保存的安装记录：如果这更改了所提供的 installHash，重新加载会明显失败，而不会发布运行时。调用方必须在重试前刷新其预期状态；Gateway 从不重写所提供的哈希。确认覆盖其已审查的声明面，不同的必需面会在运行时发布前停止操作。重新加载不会重新构建已编译的捆绑代码，也不会授予文件修改权限。

sourceDigests 需要捕获源插件实例和 Node 的同步模块钩子。没有这些钩子的运行时（包括 Bun 1.4.2）会省略这些摘要，并拒绝提供这些摘要的请求。普通 Bun 重新加载会为替换项捕获新源，同时为已接纳的消费者保留旧实例；参见 运行时实例和源生命周期。

消息与日志¶

• send 是聊天运行器之外针对频道/账户/线程发送的直接出站投递 RPC。
• logs.tail 返回已配置的 Gateway 文件日志尾部，带有游标/限制和最大字节控制。

操作员终端¶

• terminal.open 为显式 agentId 或默认代理启动主机 PTY，并返回已解析的代理、工作目录、shell 和限制状态。传入 sessionKey 会将 PTY 绑定到该确切代理会话，并将调用连接附加为其第一个查看者；省略它则创建一个连接拥有的操作员终端。
• terminal.input 和 terminal.resize 作用于调用连接拥有的会话，以及该连接是已附加查看者的代理拥有会话。terminal.close 会终止连接拥有的会话，但对于已建立的代理拥有会话，仅分离调用查看者。对于新的会话绑定 Control UI 终端，发起查看者的关闭或断开会丢弃 PTY，直到浏览器或确切会话代理通过授权操作首次接管它。
• terminal.upload 接受一个最大 16 MiB 的 base64 文件，将其暂存到会话的 Gateway 或配对节点主机上的私有 24 小时临时目录中，并返回绝对路径。调用方仍必须粘贴或以其他方式使用该路径；RPC 从不写入终端输入或执行命令。
• terminal.data 和 terminal.exit 事件会流式传输到连接所有者和已附加查看者。会话拥有的终端保持持久。面向代理的 terminal 工具只能列出、读取、调整大小或关闭操作员为其确切会话打开的终端；它不能打开终端。代理输入遵循有效的会话和执行策略：full（YOLO）立即发送，guarded 和 workspace（包括仅接受或 Guardian 审查流程）需要对该确切输入进行显式一次性批准，read-only 或 deny 会阻止它。
• 连接拥有的会话在连接断开时会被分离，而不是终止：它们在 gateway.terminal.detachedSessionTimeoutSeconds（默认 300；0 恢复断开即终止）期间保持可重新附加，同时近期输出累积在有限的服务器端缓冲区中。已建立的代理拥有会话同样会在查看者断开后存活。
• terminal.list 返回可附加的会话。terminal.attach 返回重放缓冲区，并重新绑定连接拥有的会话（tmux 式接管——之前的活动所有者会收到原因为 detached 的 terminal.exit），或将连接添加为代理拥有会话的查看者。
• 每个终端方法都需要 operator.admin；gateway.terminal.enabled 默认开启，设置为 false 时会拒绝所有方法。完全沙箱化的代理会被拒绝，并且代理策略变更会关闭现有和进行中的 PTY，包括已分离的 PTY。