系统与频道
用于 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"以及 IANAtimeZone,用于支持夏令时的日历日边界和分桶。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 能够无歧义地选择代理时才可省略。插件发现不需要代理。 |
例如:
响应包含 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