跳转至

操作员方法

操作员客户端代表人员调用的方法:辅助读取、执行审批解析,以及代理运行的投递行为。

操作员辅助方法

  • commands.list (operator.read) 获取某个代理的运行时命令清单。
  • agentId 可选;省略它以读取默认代理工作区。
  • scope 控制主要 name 面向哪个界面:text 返回不带前导 / 的主要文本命令标记;native 和默认的 both 路径在可用时返回感知提供方的原生名称。
  • textAliases 携带精确的斜杠别名,例如 /model 和 /m。
  • nativeName 在存在时携带感知提供方的原生命令名称。
  • provider 可选,仅影响原生命名以及原生插件命令可用性。
  • includeArgs=false 会从响应中省略序列化参数元数据。
  • tools.catalog (operator.read) 获取某个代理的运行时工具目录。响应包含分组工具和来源元数据:
  • source:core 或 plugin
  • pluginId:当 source="plugin" 时的插件所有者
  • optional:插件工具是否为可选
  • tools.effective (operator.read) 获取某个会话的预期工具预览。
  • sessionKey 必填。
  • 网关在服务器端从会话派生受信任的运行时上下文,而不是接受调用方提供的身份验证或投递上下文。
  • 响应是从已保存设置派生的会话范围服务器端投影,包括核心、插件、通道以及已发现的 MCP 服务器工具。它不是活动运行的精确工具清单:运行权限、凭据、发现和最终运行策略可能会改变所提供的工具。未出现在此预览中并不能证明某个工具已被禁用,出现也不保证执行访问权限。
  • 投影可以在刷新时使用缓存清单。未保存的 UI 编辑不是输入,已保存或运行时更改可能不会立即出现。
  • tools.effective 对 MCP 是只读的:它可能通过最终工具策略投影一个热会话 MCP 目录,但不会创建 MCP 运行时、连接传输或发出 tools/list。如果不存在匹配的热目录,响应可能包含诸如 mcp-not-yet-connected、mcp-not-yet-listed 或 mcp-stale-catalog 之类的通知。
  • 有效工具条目使用 source="core"、source="plugin"、source="channel" 或 source="mcp"。
  • tools.invoke (operator.write) 通过与 /tools/invoke 相同的网关策略路径调用一个可用工具。
  • name 必填。args、sessionKey、agentId、confirm 和 idempotencyKey 可选。
  • 如果同时存在 sessionKey 和 agentId,解析后的会话代理必须与 agentId 匹配。
  • 仅限所有者的核心包装器,例如 cron、gateway 和 nodes,即使 tools.invoke 本身是 operator.write,也需要所有者/管理员身份(operator.admin)。
  • 响应是面向 SDK 的信封,包含 ok、toolName、可选的 output 和类型化的 error 字段。审批或策略拒绝会在负载中返回 ok:false,而不是绕过网关工具策略管道。
  • skills.status (operator.read) 获取某个代理的可见技能清单。
  • agentId 可选;省略它以读取默认代理工作区。
  • 响应包括资格、缺失要求、配置检查以及经过净化的安装选项,而不暴露原始机密值。
  • skills.search 和 skills.detail (operator.read) 返回 ClawHub 发现元数据。skills.detail({ slug, version? }) 接受来自搜索的发布者限定的 installRef,并读取该版本的卡片和扫描摘要。参见 技能注册表详情。
  • skills.upload.begin、skills.upload.chunk 和 skills.upload.commit (operator.admin) 在安装前暂存私有技能归档。这是面向可信客户端的独立管理员上传路径,而不是正常的 ClawHub 技能安装流程,并且默认禁用,除非启用 skills.install.allowUploadedArchives。
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) 创建一个绑定到该 slug 和 force 值的上传。
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) 在精确的解码偏移量处追加字节。
  • skills.upload.commit({ uploadId, sha256? }) 验证最终大小和 SHA-256。提交仅最终确定上传;它不会安装技能。
  • 上传的技能归档是包含 SKILL.md 根部的 zip 归档。归档的内部目录名称永远不会选择安装目标。
  • skills.install (operator.admin) 有三种模式:
  • ClawHub 模式:{ source: "clawhub", slug, version?, force? } 将技能文件夹安装到默认代理工作区的 skills/ 目录。
  • 上传模式:{ source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } 将已提交的上传安装到默认代理工作区的 skills/<slug> 目录。slug 和 force 值必须与原始 skills.upload.begin 请求匹配。除非启用 skills.install.allowUploadedArchives,否则拒绝;该设置不影响 ClawHub 安装。
  • 网关安装器模式:{ name, installId, timeoutMs? } 在网关主机上运行已声明的 metadata.openclaw.install 操作。旧客户端可能仍会发送 dangerouslyForceUnsafeInstall;此字段已弃用,仅为协议兼容性而接受,并被忽略。对于操作员拥有的安装决策,请使用 security.installPolicy。
  • skills.update (operator.admin) 有两种模式:
  • ClawHub 模式更新默认代理工作区中一个受跟踪的 slug 或所有受跟踪的 ClawHub 安装。如果更新将替换一个其已安装文件不再匹配已记录安装摘要的技能目录,则会被拒绝;details.results 中的每个技能失败携带 code: "force_required"。使用可选的 force: true 参数重试,以无论如何替换该技能。
  • 配置模式修补 skills.entries.<skillKey> 值,例如 enabled、apiKey 和 env。

models.list 视图

models.list 接受可选的 view 参数 (src/agents/model-catalog-visibility.ts):

  • 省略或 "default":如果已配置 agents.defaults.modelPolicy.allow,则 响应为允许的目录,包括 provider/* 条目的动态发现模型。 否则响应为完整网关目录。
  • "configured":一个紧凑目录,也会保留当前模型控件的已配置默认值和 回退值。这些元数据行不一定是允许的手动选择。由 provider/* 匹配的已发布行 仍会包含。如果没有允许列表,已配置和已认证的行仍可见。
  • "provider-config":源编写的 models.providers.*.models 清单, 独立于选择器允许列表。行包括公开模型能力和 路由感知可用性,但省略提供程序端点、认证材料和 运行时请求配置。
  • "all":完整网关目录,绕过 agents.defaults.modelPolicy.allow。用于 诊断/发现 UI,而不是常规模型选择器。

在 "provider-config" 视图之外,推荐模型列表 为其提供程序指定的行 带有 recommended: true。每个提供程序的推荐行按列表顺序位于其其他行 之前,且位于会话已选模型之后。选择器可以将剩余行 折叠到“所有模型”控件之后。

在连接 caps 中声明 model-selection-policy 的客户端 会在每个 models.list 行上收到 manualSelectionAllowed。同一事实也出现在 其初始 models.snapshot 中。仅在推导手动选择时过滤值为 false 的行; 保留完整目录用于当前模型能力和 就绪状态。作用域内的已配置读取也会保留当前会话模型的已知元数据, 而不改变其选择或授予权限。

该事实独立于 available,并且不授权会话写入。 服务器在模型被选择时会再次检查当前策略。无能力 连接保留先前的行结构。通用客户端库不会选择加入: 转发具备能力连接的代理必须支持其协商的行结构, 或者为较旧的封闭模式消费者使用无能力上下文。

常规请求读取已发布目录,而不会启动提供程序发现。 视图选择行;它们不决定发现是否运行。如果所有者尚未 发布,请求会报告模型目录尚未就绪。在投影期间其所有者 变为过期的结果会以 UNAVAILABLE、 retryable: true 和 retryAfterMs: 0 被拒绝。控制 UI 在目录消费者之间共享一次重试, 并保留取消和任何显式请求截止时间。

  • preparedOnly: true 仍受自动客户端支持。无论是否带有此标志,常规读取 都是被动的。
  • refresh: true 在读取新发布版本之前请求提供程序获取。 并发刷新共享所有者构建。失败的获取 会保留兼容行并报告其 providerOutcomes;成功的空 获取仍为空。
  • provider: "<id>" 通过捕获的提供程序别名过滤已发布结果。 未知提供程序 ID 会返回 INVALID_REQUEST 并附带被拒绝的 ID。 省略该过滤器或运行 openclaw models list --all 以列出模型及其 提供程序 ID。
  • includeDetails: true 包括可用输入模态、有效 contextTokens 和 local 端点分类。它不会公开 端点 URL、请求头、凭据、成本或运行时请求参数。

对于会话选择器,传入 sessionKey 以读取会话的规范 代理和已保存的账户选择。冲突的 agentId 会被拒绝。 查看者当前账户默认值不会替换已保存会话的选择。 对于新草稿,authProfileId 会预览由具有 operator.read 访问权限的已识别调用者拥有的保留账户。 它不会保存账户默认值。sessionKey 和 authProfileId 互斥。

已保存会话元数据和草稿预览在无关的会话创建 和写入中保持最新。发布前,Gateway 会重新检查所选 会话的身份和规范元数据、运行时配置以及当前 访问权限。使用相同会话事实重建行不会使读取失效。 当其元数据输入和访问事实保持不变时,chat.metadata 也允许对选中行进行标题、活动和常规偏好 更新。账户、模型、运行时、生命周期和访问变更仍会使进行中的元数据读取失效。

会话和已识别账户结果会随模型包含 accountSelection 显示事实。 协作者不会收到他人的私有账户定位符。provider-config 视图仍为共享编写清单,并省略 账户选择。refreshFailed: true 报告获取失败,同时 兼容行仍可用;恢复会清除它。成功的空目录 仍为空。

Gateway 为此契约声明 session-scoped-model-catalog。 chat.metadata 仍对旧版客户端可用。直接读取模型的客户端 可以传入 includeModels: false 以跳过重复目录、账户 选择和运行时选择投影。命令和 swarm 可用性 仍可用。紧凑响应包含不透明的 revision;在后续紧凑读取中将其作为 ifRevision 传入,以收到 unchanged: true 而不是 另一个命令列表。该修订版本描述已准备的命令和 swarm 事实。 捆绑的 Control UI 无需会话或账户选择即可读取这些代理作用域事实, 并在会话活动中保留它们。会话作用域模型 结果和完整会话行可以携带 sessionModelRevision,它是已保存模型、账户、运行时和生命周期输入的不透明令牌。 当该令牌匹配时,UI 会保留其目录;缺失的令牌和显式 catalogChanged 通知会保留权威读取。共享目录、认证、配置和 连接变更会独立失效。Harness 拥有的、模型锁定会话 会省略此令牌,因为其原生所有者可以独立于已保存行替换私有模型绑定。 同时支持较旧 Gateway 的原生客户端保留默认 请求结构。打开会话选择器 会执行被动读取,没有模型缓存计时器或隐式提供程序刷新。 元数据刷新会发布模型所有者事实,而无需准备每个代理的 命令和模型投影。请求按需准备其代理的元数据; 慢速代理不会延迟其他代理。保留的命令和投影 是有界的,并且不会保留已完成请求的会话文档。即使当前会话的模型目录是共享的, 也会为当前会话投影账户选择。 提供程序续期在清单和认证元数据未变化时,会保留缓存元数据, 而不广播 chat.metadata.changed。仅发现进度不会 使元数据失效;目录变更和 refreshFailed 转换仍会使其失效。 发现进度会使共享 RPC 响应字节退役,而无需重建元数据 或发送另一个客户端广播。 共享模型或账户替换仍会门控这些读取,并且历史记录 仅使用已准备的目录,而不会启动或等待准备。 模型设置页面在初始加载时使用 preparedOnly: true,然后 针对当前核心数据快照,在首次打开主要、实用或回退模型 选择器时请求 refresh: true。待处理的打开共享该页面的请求;已完成的重新打开读取 当前已发布目录,而不会再次获取提供程序。显式 重试 请求新的获取。替换核心设置数据、页面、代理或 Gateway 会重置此请求状态。配置变更后核心数据会重新加载, 因此下一次打开选择器可以从新配置的提供程序发现模型。 刷新失败时,可用选择仍可用。 这取代了先前的五分钟自动刷新策略;仅经过时间 不会使重新打开的设置选择器刷新。Gateway 共享并发 提供程序获取。

preparedOnly: true 和 refresh: true 仍然是互斥的。

WebSocket 分发器在符合条件的人类连接之间共享相同的 cron.list、cron.status、sessions.list、models.list 和 chat.metadata 响应。每个请求仍会检查其自身的当前权限。共享键区分用户与配置文件身份、作用域、客户端能力以及请求参数,包括智能体、会话和账户选择。显式模型刷新、合成调用方以及受限会话可见性的 cron 读取不参与共享。会话、cron 和模型元数据广播会在客户端重新获取之前使相关响应失效。配置、访问和会话行修订也会阻止重用。这些方法目前使用一秒的绝对上限;此上限限制了不发布广播的个人模型元数据更改。这不会引入客户端轮询或提供方刷新。会话目录和工作板读取不使用此响应共享所有者。

运行中的 cron 拥有者会保留不可变的作业读取视图和聚合状态,直到已提交的修订、已加载存储的替换或调度器的变更修改它们。每个列表请求仍会应用其当前的可见性过滤器。投递预览保留其会话和配置依赖;单独的 cron 修订不会使其可重用。被动 cron 读取方保留其存储刷新行为。

网关将这些已发布读取和详细信息控制通告为 published-model-catalog。需要此契约的客户端必须在发送新字段之前检查该能力;较旧的网关需要更新或重启,而不是静默本地回退。模型 CLI 将此契约用于 models list 和 models list --refresh。

技能注册表详细信息

在请求详细信息时,请使用来自 skills.search 的精确 installRef。例如:

{ "slug": "@example-publisher/example-skill", "version": "1.2.0" }

省略 version 会选择最新已发布的版本。响应保留 skill、latestVersion、metadata 和 owner,并新增 registry、source、installRef 和 selectedRelease。latestVersion 和 metadata 始终描述该列表条目的最新版本;selectedRelease、card 和 security 描述所请求的版本。发布者与版本不匹配时,绝不会替换为其他技能或版本。

card 在其 status 为 available 时包含完整的卡片文本。否则它包含 status: "unavailable" 和一个 reason。security 报告 scanStatus、hasWarnings、hasScanResult 以及任何扫描时间、摘要或 VirusTotal URL。缺失的扫描会被显式标记为不可用。可选的发布或卡片失败会使基本列表条目元数据保持可读,并出现在受影响的部分或 warnings 中。

requirements 报告最新发布中可用的注册表设置键、操作系统和系统。其 scope: "registry-setup" 和 note 说明设置键综合了环境与配置要求,并不包含二进制要求。较旧版本的结构化要求不可用,因为 ClawHub 仅针对最新版本发布这些事实。这些是注册表声明,而非对本地智能体资格的检查;请使用 skills.status 进行本地要求和配置检查。

downloadability 独立于卡片可用性、列表条目可见性和扫描结果。缺失或已移除的版本为 unavailable;其他技能版本为 unknown,因为 ClawHub 不发布精确版本的工件可用性断言。两种状态都包含原因。安装仍会执行其自身的解析、完整性和策略检查。

外部 skills-sh: 引用仍然仅用于安装。skills.detail 会拒绝它们,而不是返回具有相同 slug 的原生注册表技能。

执行审批

  • 当 exec 请求需要审批时,网关会广播 exec.approval.requested。
  • 操作员客户端通过调用 exec.approval.resolve 来完成审批(需要 operator.approvals)。
  • 对于 host=node,exec.approval.request 必须包含 systemRunPlan(规范化的 argv/cwd/rawCommand/会话元数据)。缺少 systemRunPlan 的请求将被拒绝。
  • 审批通过后,转发的 node.invoke system.run 调用会重用该规范化的 systemRunPlan,作为权威的命令/cwd/会话上下文。
  • 如果调用方在准备阶段和最终获批的 system.run 转发之间修改了 command、rawCommand、cwd、agentId 或 sessionKey,网关将拒绝该运行,而不是信任被修改的负载。

智能体投递回退

  • agent 请求可以包含 deliver=true 以请求出站投递。
  • bestEffortDeliver=false(默认值)保持严格行为:未解析或仅限内部的投递目标返回 INVALID_REQUEST。
  • bestEffortDeliver=true 允许在无法解析外部可投递路由时回退到仅会话执行(例如内部/webchat 会话或模糊的多通道配置)。
  • 当请求了投递时,最终的 agent 结果可能包含 result.deliveryStatus,采用 openclaw agent --json --deliver 中记录的相同 sent、suppressed、partial_failed 和 failed 状态。

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