跳转至

系统与频道

用于 Gateway 状态与身份、模型与用量、通道与登录、插件管理、消息与日志以及操作员终端的 RPC 方法族。

系统与身份

  • health 返回缓存的或新检查的 Gateway 健康快照。
  • diagnostics.stability 返回最近的有界诊断稳定性记录器:事件名称、计数、字节大小、内存读数、队列/会话状态、通道/插件名称、会话 ID。不包含聊天文本、webhook 主体、工具输出、原始请求/响应主体、Token、Cookie 或密钥。需要 operator.read。
  • status 返回 /status 样式的 Gateway 摘要;敏感字段仅对管理员作用域的操作员客户端可见。
  • gateway.identity.get 返回中继和配对流程使用的 Gateway 设备身份。
  • system-presence 返回已连接操作员/节点设备的当前在线状态快照。
  • system-event 追加系统事件,并可更新/广播在线状态上下文。
  • last-heartbeat 返回最新持久化的心跳事件。
  • set-heartbeats 切换 Gateway 上的心跳处理。
  • gateway.restart.preflight 是一个已弃用的、只读的兼容性预览,用于查看重启相关的活动工作。它不会关闭准入、创建挂起租约,或提供 gateway.suspend.prepare 的原子全工作围栏;新的重启流程应调用 gateway.restart.request。
  • gateway.suspend.prepare 仅在受跟踪的 Gateway 工作空闲时创建一个短暂的协作式挂起租约。在已准备期间,经过身份验证的 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 表示单个 agent,或传入 agentScope: "all" 以聚合已配置的 agent。
  • doctor.memory.status 返回原生内存提供商的提供商健康状态,或旧版提供商的向量内存/缓存嵌入就绪状态。仅在对旧版嵌入提供商进行显式 ping 时传入 { "probe": true } 或 { "deep": true }。传入 { "agentId": "agent-id" } 可将 Dreaming 存储统计限定到一个 agent 工作区;省略它则会聚合已配置的 Dreaming 工作区。
  • doctor.memory.dreamDiary、doctor.memory.backfillDreamDiary、doctor.memory.resetDreamDiary、doctor.memory.resetGroundedShortTerm、doctor.memory.repairDreamingArtifacts 和 doctor.memory.dedupeDreamDiary 接受可选的 { "agentId": "agent-id" };省略时,它们操作已配置的默认 agent 工作区。
  • sessions.usage 返回按会话划分的用量摘要。传入 agentId 表示单个 agent,或传入 agentScope: "all" 以一起列出已配置的 agent。 两个用量方法都接受 mode: "specific" 以及 IANA timeZone,用于支持夏令时的日历日边界和分桶。utcOffset 仍受支持,用于旧客户端,并在 Gateway 运行时无法识别请求时区时作为回退。
  • sessions.usage.timeseries 返回单个会话的时间序列用量。
  • sessions.usage.logs 返回单个会话的用量日志条目。 两个详情方法都接受所选行的 key 和可选的 agentId。为未限定的键(例如 global)打开详情时,请保留这两个字段。

内存

  • 使用 version: 2 的 memory.search 会搜索所选提供商并返回提供商范围的引用。省略 version 或发送 version: 1 时,仅对旧版提供商使用旧版文件式契约。原生提供商会返回一个指明插件名称的错误;请使用 version: 2 重试。
  • memory.get 通过所选提供商解析提供商范围的引用。
  • memory.status 报告所选提供商的健康状态。

这些方法需要经过身份验证的操作员读取权限。memory.get 和 memory.status 直接使用提供商运行时契约;memory.search 在存在 version: 2 时选择该契约。

通道与登录辅助

  • 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 启动 QR/Web 登录流程。参数包括可选的 { channel, accountId, force, timeoutMs, verbose }。当存在 channel 时,Gateway 会规范化其规范 ID 或别名,并仅分发到该已安装的通道插件。省略 channel 会保留旧版行为,即选择第一个已加载的具备 QR 能力的提供商。提供商可能会在其 QR 响应中返回一个不透明的 sessionKey。
  • web.login.wait 等待该流程完成,并在成功时启动通道。参数包括可选的 { channel, accountId, sessionKey, timeoutMs, currentQrDataUrl }。使用与 web.login.start 相同的 channel,并将其返回的 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 访问请求。它们与 设备引导 相互独立。

现有列表请求接受可选的 channel 和 accountId,并返回 accounts、requests、commandOwnerConfigured 和 limits。公共请求 行包含 requestId 以及发送者/账户元数据,从不包含配对代码。 现有批准和拒绝使用 channel、accountId 和 requestId; 批准还接受 notify 和 bootstrapCommandOwner。批准返回 requestId、senderId、notification 和 commandOwnerBootstrap;拒绝 返回 requestId 和 senderId。这些契约保持不变。

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

方法 请求 结果
channels.pairing.list format: "cli"、channel、expectedOwnerId;可选 accountId 原始请求数组,包含 id、code、createdAt、lastSeenAt 和可选的 meta。
channels.pairing.approve channel、code、expectedOwnerId;可选 accountId { id, entry },其中 entry 为原始已批准请求,若没有匹配的待处理代码则为 null。

代码选择器和现有请求 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 和可选的 limit,范围为 1 到 100。
  • plugins.catalog.browse (operator.read) 返回带有 Gateway 本地已安装和捆绑状态的 ClawHub 发现结果。Control UI 仅在手动输入至少两个字符并稳定 250 ms 后添加 searchSource: "openclaw-control-ui"。初始浏览、刷新、筛选器更改和通用 API 搜索会省略它。Gateway 会遵循 CLAWHUB_DISABLE_TELEMETRY,并在瞬时故障后不重放已归因的 HTTP 搜索。ClawHub 会记录规范化查询、来源和远程结果计数;这些计数不包括 Gateway 添加的仅本地匹配项。已安装清单以及操作员、设备和会话标识不包含在观察数据中。
  • plugins.catalog.get (operator.read) 接受 { id, version? },使用来自 plugins.catalog.browse 的未更改发现 ID。详情包括 ClawHub 提供时的发布者元数据、README、主题、包标签、所选发布说明、能力、配置、验证和安全信息。detail.selectedRelease 独立于 plugin.catalog.latestVersion 指明实际发布;null 表示未选择发布。detail.metadata 明确报告可用或缺失的 README、manifest 和安全数据。已安装对应项可在注册表故障期间提供本地详情;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 来源需要 Gateway 识别为本地的连接;路径指向该 Gateway 主机。对于特定官方包版本,请使用 npm spec。

当安装策略返回 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? } 移除一个外部安装的插件:配置引用、安装记录以及受管理的文件。捆绑插件无法卸载,只能禁用。响应会列出移除操作。

目录详情与客户端确认

detail.downloadability 具有以下其中一种形式:

状态 含义
{ "status": "downloadable" } 源已确认所选版本的工件可用性。
{ "status": "unavailable", "reason": "..." } 缺失的版本或源下载策略阻止下载。
{ "status": "unknown", "reason": "..." } 源无法确认可用性,或注册表读取失败。

ClawHub 当前会公开所选插件版本的下载策略块,但其只读详情和工件解析器不会检查已存储的工件字节。因此,被允许的安全判定、下载 URL、列表或本地安装操作只会产生 unknown,绝不会产生 downloadable。无副作用的按版本可用性事实需要 ClawHub 契约扩展。Gateway 检查不会下载包来检查它们;注册表下载路由会记录遥测。

原生客户端可以获取 plugins.catalog.get,检查相同的 catalogId,显示返回的事实,并自行收集确认。批准后,调用 plugins.install,使用 source: "clawhub"、精确返回的 packageName,以及存在时的 selectedRelease.version。保留作用域和发布者拼写;不要从运行时插件 ID 重建包名。如果安装需要能力同意或安装策略确认,显示该所有者签发的审阅,并使用其确认重试同一意图。目录检查不会授予同意,也不会绕过安装策略、完整性、信任或授权。取消不会发送安装 RPC。Gateway 不管理确认对话框。

仅运行时刷新适用于只读、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 重新加载会为替换项捕获新的源,同时为已获准的消费者保留旧实例;参见 运行时实例和源生命周期。

ClawHub 目录发现

catalog.browse 和 catalog.searchKeywords 需要 operator.read。客户端在使用它们之前会检查 hello-ok.features.methods;旧版 Gateway 会继续暴露现有的插件和技能 RPC。所有注册表请求都在 Gateway 上运行,包括 Gateway 远程运行或运行在 WSL 内部时。

调用 catalog.browse 时使用以下字段:

字段 约定
kind 必填:plugin 或 skill。结果保持在该类型内。
query 可选文本,最多 200 个字符。仅包含空白字符的文本表示浏览。
feed catalog(默认)或 trending。搜索不能选择 trending。
officialOnly 可选布尔值,默认 false。Gateway 会排除任何没有显式官方标志的列表项。
pageSize 1 到 100 的整数,默认 20。
cursor 来自相同类型、feed 和过滤请求的不透明续传游标。搜索不接受游标。
agentId 选择技能工作区。仅当 Gateway 能够无歧义地选择代理时才可省略。插件发现不需要代理。

例如:

{
  "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。它们来自所选工作区的现有状态读取器和有效的受跟踪注册表/源/发布者标识。匹配的显示名称或裸 slug 不能确立安装状态。插件本地事实复用现有的受管清单和变更策略。这两个操作都不会安装任何内容或更改审批要求。

批量关键词发现

调用 catalog.searchKeywords 时使用 keywords(1–100 个非空白字符串,每个最多 200 个字符)、可选的 kinds(plugin、skill 或两者;默认两者)、agentId、pageSize(1–100,默认 20)以及可选的返回 cursor。Gateway 会修剪并合并空白字符,将术语小写并去重,然后针对每个所选类型搜索每个单独术语。它始终只返回官方列表项,按规范标识去重,并以确定性的标识顺序返回。它从不拼接术语或解释应用清单。客户端负责应用检测和关键词生成。

响应包含规范化后的 keywords、items、searchLimit: 100、errors(每个包含 kind、query 和 message)以及可选的 nextCursor。游标对这些有界搜索的完整并集进行分页;该并集内的匹配项不会被静默丢弃。上游 100 个候选项的限制仍然适用于每个术语和类型,因此这不是穷尽式注册表搜索。没有错误的空并集与带有失败查询的空并集或部分并集不同。重试带有错误的请求以恢复失败的术语。

批量续传会重新读取相同的有界搜索,最多同时有四个搜索在执行,而不保留第二份清单。游标绑定规范化术语、类型、注册表、所选工作区和结果标识。如果匹配项发生变化,Gateway 会返回带有重启指令的 INVALID_REQUEST,而不是静默跳过结果。大型关键词集合和后续页面会执行比普通搜索更多的注册表读取;客户端应允许更长的 RPC 请求超时,并保留原始请求以便重试。

上游契约与缺口

原生技能目录浏览和搜索使用 ClawHub 现有的 /api/v1/packages?family=skill 和 /api/v1/packages/search?family=skill 契约。这些契约投影原生技能目录,并公开列表的 isOfficial 标志。/api/v1/skills 当前省略该标志。规范技能 搜索和趋势可以组合发布者与列表的官方状态;新 目录不使用发布者官方状态作为替代。原生趋势 条目因此以有界批次从包元数据读取其列表标志。包详情路由可以先解析同名包;仅当 family、slug 和发布者与精确技能匹配时,其元数据才符合条件。 不匹配的元数据会使官方状态未知。缺失的标志永远不符合条件;精选状态、验证层级、 发布者句柄和捆绑来源也不能使列表符合条件。

包技能目录当前覆盖原生 ClawHub 技能。外部 来源可以以其原始仅安装身份出现在规范趋势源中,但目前 不公开单独的列表级官方标志,也不能符合官方建议条件。现有 skills.search 保留其规范跨源搜索和省略查询趋势行为; 其公开结果契约也声明了现有可选 official 字段。 不引入跨类型分类法或全局相关性排序。

消息与日志

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

操作员终端

  • 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。

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