网关协议体系和通道方法

RPC 方法系列，用于网关状态和身份、模型和使用、通道和登录、插件管理、消息传递和日志以及操作员终端。

系统和身份

• health 返回缓存的或新检查的网关运行状况快照。
• diagnostics.stability 返回最近有界诊断稳定性记录器：事件名称、计数、字节大小、内存读数、queue/session 状态、channel/plugin 名称、会话 ID。没有聊天文本、webhook 主体、工具输出、原始 request/response 主体、令牌、cookie 或机密。需要 operator.read。
• status 返回 /status-style 网关摘要；敏感字段仅适用于管理员范围的操作员客户端。
• gateway.identity.get 返回中继和配对流程使用的网关设备身份。
• system-presence 返回已连接 operator/node 设备的当前存在快照。
• system-event 附加系统事件并且可以 update/broadcast 存在上下文。
• 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 返回提供程序使用情况 windows/remaining 配额摘要。宣传 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"将已配置的代理一起列出。报告读取持久的使用情况存储桶，而不是重播对齐日历范围的记录；令牌计数保持精确，而成本加法在浮点精度上可能有所不同。每个代理读取共享一个32 MiB允许保留的缓存有效负载和解码JSON；上面的各个缓存主体1 MiB在加载之前被推迟。精确的部分边界使用每个代理5-第二，16 MiB重播预算。延迟的行保持标记computing在部分缓存快照中，而不安排刷新其他当前数据。最多允许一个请求20,000创建者过滤后的会话实例，并且具有15-第二个截止日期；如果超出这些限制，请缩小日期范围或选择一个会话。断开连接会取消该请求，而其他客户端的报告将独立继续。在返回行和总计之前会检查每行的访问权限，因此撤销会删除受影响的行，而不会丢弃报表的其余部分。上下文水合在撤销后回填所选页面；持续的访问变化可能会在两次水化过程后留下一小页。两种使用方法都接受mode: "specific"与一个IANA timeZone为了DST-了解日历日的界限和时间段。utcOffset仍然支持较旧的客户端，并在网关运行时无法识别所请求的区域时作为后备。
• sessions.usage.timeseries 返回单个会话的时序用量。
• sessions.usage.logs 返回一个会话的使用日志条目。两种详细方法都接受所选行的 key 和可选的 agentId。打开非限定密钥（例如 global）的详细信息时，保留这两个字段。

内存

• memory.search 和 version: 2 搜索选定的提供者并返回提供者范围内的引用。省略 version 或发送 version: 1，仅对旧提供商使用旧文件形合同。本机提供程序返回命名插件的错误；使用 version: 2 重试。
• memory.get 通过选定的提供程序解析提供程序范围的引用。
• memory.status 报告所选提供商的运行状况。

这些方法需要经过身份验证的操作员读取权限。 memory.get和memory.status直接使用provider-runtime合约；当 version: 2 存在时，memory.search 选择该合约。

频道和登录助手

• channels.status 返回内置 + 捆绑的 channel/plugin 状态摘要。
• channels.start（operator.admin）启动一个通道帐户运行时，无需重新验证。参数 { channel, accountId? }；省略accountId选择默认帐户。仅当生成的运行时快照报告 running: true 时，才响应 { channel, accountId, started, outcome }，started 为 true。 outcome 携带帐户生命周期决策：{ status: "handed-off" }、{ status: "retry", reason } 或 { status: "skipped", reason }。 RPC 是自动启动抑制的手动超控；不接受 manual 参数。这不是提供商连接检查；请参阅 按账户恢复 了解原因和恢复指南。
• channels.stop （operator.admin） 停止一个通道帐户运行而不清除身份验证状态。参数 { channel, accountId? }；省略accountId选择默认帐户。当生成的运行时快照不报告 running: true 时，响应 { channel, accountId, stopped }，stopped 为 true。与 channels.logout 不同，它保留帐户的凭据。
• channels.logout 注销通道支持的特定 channel/account。
• web.login.start 启动 QR/web 登录流程。参数包括可选的 { channel, accountId, force, timeoutMs, verbose }。当 channel 存在时，网关会标准化其标准 ID 或别名，并仅分派到已安装的通道插件。省略 channel 会保留选择第一个加载的 QR- 功能的提供程序的旧行为。如果通道配置的账号超过1个，则需要填写accountId；省略或空白的 ID 会因有效帐户 ID 被拒绝。单帐户请求保留其现有的默认行为。仅停止或恢复所选帐户的侦听器。提供者可以通过其 QR 响应返回不透明的 sessionKey。如果配对期间通道配置发生变化，请开始新的登录。
• web.login.wait 等待该流程完成并在成功时启动通道。参数包括可选的 { channel, accountId, sessionKey, timeoutMs, currentQrDataUrl }。使用与 web.login.start 相同的 channel 和 accountId 并不变地传递其返回的 sessionKey，以便提供者可以将等待请求与 QR 会话关联起来。省略 channel 会保留与 web.login.start 相同的旧提供程序回退。
• push.test 向已注册的 iOS 节点发送测试 APNs 推送。
• voicewake.get 返回已存储的唤醒词触发器。
• voicewake.set 更新唤醒词触发器并广播变更。

通道 DM 配对

channels.pairing.list、channels.pairing.approve和channels.pairing.dismiss管理通道DM访问请求。它们与 device bootstrap 分开。

现有列表请求接受可选的 channel 和 accountId 并返回 accounts、requests、commandOwnerConfigured 和 limits。公共请求行包含 requestId 和 sender/account 元数据，而不是配对代码。现有审批和驳回使用channel、accountId、requestId；批准还接受 notify 和 bootstrapCommandOwner。批准返回 requestId、senderId、notification 和 commandOwnerBootstrap；解雇返回 requestId 和 senderId。这些合同保持不变。

在协商相应的 所有者能力 后，本地 CLI 使用两个显式的、operator.admin- 受保护的分支：

代码选择器和现有的 request-ID 选择器是互斥的。在CLI分支中省略accountId可以保留跨账户列表和代码查找；明确的帐户限制两者。所有者解析并改变匹配的请求。 CLI 输出保持不变，第一命令所有者配置引导和可选通知在确认后仍保留在客户端。两者都不会在拒绝或未知结果后运行。列表具有突变能力，因为它会修剪过期或过多的待处理请求。

插件管理

• plugins.list （operator.read） 返回已安装的插件清单以及本地策划的官方选择、诊断以及当前安装模式是否允许突变。它包括当前运行时 generation 以及每个插件的运行时状态，与配置的启用分开。

• plugins.inspect （operator.read） 接受 { pluginId } 作为已安装、上演或正式候选人； { source: "clawhub", packageName, version? } 用于任意 ClawHub 插件；或使用发现身份的 { catalogId, version? }。安装和分阶段检查包括用于能力同意的 reviewToken。远程检查公开所选目录的详细信息、适用的拨款并释放信任。他们的 declaredSurfaceStatus 是 partial 或 unavailable：注册表摘要省略了一些功能组和包同级，因此他们无法颁发同意令牌。不支持的空组并不意味着该包声明没有此类功能。

• plugins.search（operator.read）搜索可安装的 ClawHub 代码插件和捆绑插件系列。传入非空的 query，以及可选的 1 到 100 之间的 limit。

• plugins.catalog.browse （operator.read） 返回 ClawHub 发现结果，其中包含网关本地安装和捆绑状态。 Control UI 仅在手动输入至少两个字符稳定 250 ms 后才添加 searchSource: "openclaw-control-ui"。初始浏览、刷新、过滤器更改和通用 API 搜索都会忽略它。网关遵循 CLAWHUB_DISABLE_TELEMETRY，并且在瞬时故障后不会重播归因于 HTTP 的搜索。 ClawHub 记录规范化查询、源和远程结果计数；这些计数不包括网关添加的仅限本地的匹配项。观察中不包括已安装的清单以及操作员、设备和会话身份。

• plugins.catalog.get （operator.read） 使用来自 plugins.catalog.browse 的未更改发现 ID 接受 { id, version? }。详细信息包括发布者元数据、README、主题、包标签、选定发行说明、功能、配置、验证和安全性（由 ClawHub 提供）。 detail.selectedRelease 独立于 plugin.catalog.latestVersion 命名实际版本； null 表示未选择任何版本。 detail.metadata 明确报告可用或缺失的 README、清单和安全数据。安装的对应项可以在注册表中断期间提供本地详细信息； remoteError 解释了该故障，而远程选择发布事实仍然未知。仅本地身份不支持远程版本选择。

• plugins.install （operator.admin） 接受以下特定于源的请求字段：

  source	字段
  bundled	pluginId，可选spec
  clawhub	packageName，可选version，expectedPluginId，expectedIntegrity
  git	spec
  local	path，可选link
  marketplace	marketplace, plugin
  npm	spec，可选pin，expectedPluginId，expectedIntegrity
  npm-pack	archivePath
  official	pluginId，可选version: "latest"，pin

  每个请求还可以包括 mode: "install" | "update"、acknowledgeInstallPolicyWarning: true 和 acknowledgeCapabilities: { reviewToken }。省略mode表示安装。本地路径、npm-pack 档案、市场源和本地 Git 源需要网关识别为本地的连接；路径引用该网关主机。对特定的官方软件包版本使用 npm 规范。

  当安装策略返回 warn 时，错误 details 包括 installPolicyCode: "install_policy_warning_acknowledgement_required"、目标、原因和可选结果。经过审查后，使用 acknowledgeInstallPolicyWarning: true 重试相同的操作会批准该安装调用中的每个警告；在继续安装之前，会重新评估每个警告。 block 和策略失败仍然是最终的。 ClawHub 安装可保留网关信任和完整性检查。

• 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? } 删除一个外部安装的插件：配置引用、安装记录和托管文件。捆绑的插件无法卸载，只能禁用。响应列出了删除操作。

目录详细信息和客户确认

detail.downloadability 具有以下形状之一：

ClawHub 当前公开了选定插件版本的下载策略块，但其只读详细信息和工件解析器不检查存储的工件字节。因此，允许的安全判决、下载 URL、列表或本地安装操作会生成 unknown，而不是 downloadable。无副作用的每次发布可用性事实需要 ClawHub 合同延期。网关检查不下载包来检查；注册表下载路由记录遥测。

本机客户端可以获取 plugins.catalog.get，检查相同的 catalogId，显示返回的事实，并自行收集确认。批准后，使用 source: "clawhub"、准确返回的 packageName 和 selectedRelease.version（如果存在）调用 plugins.install。保留范围和出版商拼写；不要从运行时插件 ID 重建包名称。如果安装需要功能同意或安装策略确认，则显示所有者发布的审查并重试相同的意图及其确认。目录检查不会授予同意或绕过安装策略、完整性、信任或授权。取消发送不安装RPC。网关不管理确认对话框。

仅运行时刷新适用于只读、Nix 管理的和根 $include 配置，无需重写它们。当另一个插件或配置操作已在应用时，插件生命周期和 Claw 包删除请求将返回可重试的 UNAVAILABLE 和 retryAfterMs。这种繁忙的响应发生在请求的突变开始之前；当前操作完成后重试。突变开始后的失败会保留其应用程序详细信息，并且不会自动重试。

这些突变会等待运行时应用程序，而无需重新启动网关。成功的回复包括 restartRequired 和带有 operationId、generation、pluginIds 和可选 sourceDigests 的 runtime 收据。重新加载未更改的捆绑代码或替换捕获的外部代码将返回 restartRequired: false；已编辑的捆绑代码若仍处于加载状态，或其文件无法验证，则需要重新启动。发布后，网关将 plugins.changed 与 { generation } 一起广播。运行时替换错误包括 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。不明确、缺失或冲突的托管所有权仍会拒绝该请求。网关在同意之前和之后检查目标所有权和预期记录，然后根据其加载的捕获的代码验证源期望。同意可以更新保存的安装记录：如果这更改了提供的 installHash，则重新加载会明显失败，而无需发布运行时。调用者在重试之前必须刷新其预期状态；网关永远不会重写提供的哈希值。确认覆盖其已审查的声明表面，并且不同的所需表面在运行时发布之前停止操作。重新加载不会重建编译的捆绑代码或授予文件修改权限。

sourceDigests 需要捕获源插件实例和 Node 的同步模块挂钩。没有这些钩子的运行时（包括 Bun 1.4.3）会忽略这些摘要并拒绝提供它们的请求。普通Bun重载捕获新的源用于替换，同时为认可的消费者保留旧实例；请参阅 运行时实例和源生命周期 。

ClawHub 目录发现

catalog.browse 和 catalog.searchKeywords 需要 operator.read。客户使用前检查hello-ok.features.methods；旧的网关继续公开现有的插件和技能 RPC。所有注册表请求都在网关上运行，包括远程运行或在 WSL 内部运行时。

浏览搜索

使用以下字段调用 catalog.browse：

例如：

{  "kind": "skill",  "officialOnly": true,  "pageSize": 20,  "agentId": "main"}

响应包含items和mode（catalog、trending或search）。目录和趋势页面可以返回 nextCursor。过滤可以产生一个带有延续的空页；当光标存在时继续。完整目录浏览使用注册表的分页插件和本机技能目录。趋势是一个有限的排名源，而不是完整的目录。现有的初始 plugins.catalog.browse 概述保留其有界行为。

文本搜索最多返回 searchLimit 上游候选，等于请求的页面大小。官方过滤可以减少该数量。上游搜索没有延续，因此它不能保证所有可能的匹配列表。成功的空响应意味着没有返回符合条件的列表。 remoteError表示注册表发现失败；任何返回的光标都会重复输入光标，以便客户端可以重试同一页面。安装状态失败返回 UNAVAILABLE，而不是声称列表已卸载。

每个项目都有 kind、registry、id、catalog 元数据和 local 事实。将 (kind, registry, id) 视为其唯一标识。插件 ID 保留现有的 ch_... 发现身份，因此 plugins.catalog.get 可以打开详细信息； catalog.packageName 提供现有的插件安装定位器。技能 ID 等于 installRef：本机 @publisher/slug 或源限定的外部参考。将 installRef 不变地作为 slug 传递到现有技能生命周期 RPC。尊重installOnly；这些条目没有普通技能明细卡。伴随列表详细信息工作流不会更改这些身份。

技能本地事实包括已解析的 agentId、installed、enabled、eligible 以及安装后的 skillKey。它们来自所选工作区的现有状态读取器和有效的跟踪 registry/source/publisher 身份。匹配的显示名称或裸线名不会建立安装。插件本地事实重用现有的托管库存和突变策略。这两项操作都不会安装任何内容或更改批准要求。

批量关键字发现

使用 keywords（1–100 个非空字符串，每个最多 200 个字符）、可选 kinds（plugin、skill 或两者；默认两者）、agentId、pageSize 调用 catalog.searchKeywords （1–100，默认 20），以及可选返回的 cursor。 Gateway 会修剪和折叠空格、小写并删除重复术语，并搜索每个选定类型的单个术语。它始终仅返回官方列表，并按固定身份顺序按唯一身份进行重复数据删除。它从不连接术语或解释应用程序清单。客户自己的应用程序检测和关键字生成。

响应包含归一化的 keywords、items、searchLimit: 100、errors（每个包含 kind、query 和 message）以及可选的 nextCursor。光标分页那些有界搜索的完整联合；该联盟内的任何匹配项都不会被默默删除。上游 100 名候选者限制仍然适用于每个术语和种类，因此这不是详尽的注册表搜索。没有错误的空联合与查询失败的空联合或部分联合不同。重试有错误的请求以恢复失败的条款。

批量延续会重新读取相同的有界搜索，最多执行四个搜索，而不保留第二个库存。游标绑定规范化的术语、类型、注册表和选定的工作区。当远程列表在请求之间发生变化时，分页是最好的选择：延续使用其在当前结果中的偏移量，因此列表可能会重复或被跳过。重新启动发现以进行新的遍历。大型关键字集和后续页面比普通搜索执行更多的注册表读取；客户端应允许更长的 RPC 请求超时并保留原始请求以进行重试。

上游合约和缺口

原生技能目录浏览和搜索使用ClawHub现有的/api/v1/packages?family=skill和/api/v1/packages/search?family=skill合约。这些项目显示本机技能目录并公开列表的 isOfficial 标志。 /api/v1/skills 目前忽略该标志。现有的技能搜索和趋势可以结合发布者和列表官方状态；新目录不使用出版商​​官方身份作为替代。因此，本机趋势条目会从有界批次的包元数据中读取其列表标志。 package-detail路由可以优先解析同名包；仅当家族、蛞蝓和出版商与确切的技能匹配时，其元数据才符合资格。元数据不匹配导致官方状态未知。缺少旗帜永远不符合资格；特色状态、验证级别、发布者句柄和捆绑出处也不能限定列表。

包技能目录目前涵盖原生 ClawHub 技能。外部来源可以以其原始的仅安装身份出现在现有的趋势提要中，但目前没有公开单独的列表级官方标志，并且没有资格获得官方建议。现有的skills.search保留其现有的跨源搜索和省略查询趋势行为；其公共结果合约还声明了现有的可选 official 字段。没有引入跨种类的类别分类法或全球相关性排名。

消息和日志

• send 是 channel/account/thread-targeted 在聊天运行器外部发送的直接出站递送 RPC。
• logs.tail 返回配置的网关文件日志尾部以及 cursor/limit 和最大字节控制。

操作终端

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