操作员方法

操作者客户端代表用户调用的方法：辅助读取、exec 审批解析，以及代理运行的交付行为。

操作者辅助方法¶

• 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）要求所有者/管理员身份（operator.admin），尽管 tools.invoke 本身是 operator.write。
• 响应是一个面向 SDK 的封装结构，包含 ok、toolName、可选的 output 和类型化的 error 字段。审批或策略拒绝会在负载中返回 ok:false，而不是绕过网关工具策略管道。
• skills.status（operator.read）获取某个代理的可见技能清单。
• agentId 可选；省略它可读取默认代理工作区。
• 响应包含资格、缺失要求、配置检查以及脱敏后的安装选项，不会暴露原始机密值。
• skills.search 和 skills.detail（operator.read）返回 ClawHub 发现元数据。
• 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。提交仅完成上传；它不会安装技能。
• 上传的技能存档是 zip 压缩包，其根位置包含 SKILL.md。存档的内部目录名绝不会决定安装目标。
• 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"：紧凑型目录，同时保留当前模型控件（current-model controls）的已配置默认值和回退选项。这些元数据行不一定是允许的手动选择。被 provider/* 匹配的已发布行仍会包含在内。如果没有允许列表，已配置和已认证的行仍可见。
• "provider-config"：由来源编写的 models.providers.*.models 清单，独立于选择器允许列表。行包含公开的模型能力和路由感知的可用性，但省略提供者端点、认证材料和运行时请求配置。
• "all"：完整网关目录，绕过 agents.defaults.modelPolicy.allow。用于诊断/发现界面，而非常规模型选择器。

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

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

普通请求直接读取已发布的目录，而不会启动提供者发现。视图选择行；它们不决定是否运行发现。如果属主尚未发布，请求会报告模型目录尚未就绪。如果结果在投影期间其属主变为过期，则该结果会被拒绝，返回 UNAVAILABLE、retryable: true 和 retryAfterMs: 0。Control 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 仍可供旧版客户端使用；Control UI 直接读取模型，并在其元数据缓存中保留命令。打开对话选择器会执行被动读取，不涉及模型缓存定时器或隐式提供者刷新。元数据刷新会发布模型属主事实，而不会准备每个智能体的命令和模型投影。请求按需准备其智能体的元数据；慢速智能体不会延迟其他智能体。保留的命令和投影是有界的，并且不会保留已完成请求的会话文档。即使会话的模型目录是共享的，也会为当前会话投影账户选择。提供者续期在清单和认证元数据不变时保留缓存元数据，而不会广播 chat.metadata.changed。仅发现进展不会使元数据失效；目录变更和 refreshFailed 转换仍然会使元数据失效。共享模型或账户替换仍会门控这些读取，历史记录只使用已准备好的目录，而不会启动或等待准备。Models 设置页面在初始加载时使用 preparedOnly: true，然后在主模型、实用模型或回退模型选择器首次为当前核心数据快照打开时请求 refresh: true。待处理的打开会共享该页面的请求；已完成的重新打开会读取当前已发布的目录，而不会再次获取提供者。显式的 Retry 会请求新的获取。替换核心设置数据、页面、智能体或 Gateway 会重置此请求状态。配置变更后核心数据会重新加载，因此下一次打开选择器可以从新配置的提供者中发现模型。当刷新失败时，可用的选择仍然可用。这取代了先前五分钟自动刷新策略；仅经过时间并不会让重新打开的 Settings 选择器刷新。Gateway 会共享并发的提供者获取。

preparedOnly: true 和 refresh: true 仍然互斥。 Gateway 将这些已发布读取和详情控制作为 published-model-catalog 进行通告。需要此契约的客户端在发送新字段之前必须检查该能力；旧版 Gateway 需要更新 或重启，而不是静默本地回退。模型 CLI 使用此契约用于 models list 和 models list --refresh。

执行审批¶

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

代理投递回退¶

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