跳转至

用于 Talk 和 TTS、secrets、config、update 和 wizard 流程，以及 agent 和 workspace 辅助工具的 RPC 方法族

Talk 和 TTS

  • talk.catalog 返回用于语音、流式转写和实时语音的只读 Talk 提供商目录：规范提供商 ID、注册表别名、标签、配置状态、可选的组级 ready 结果、暴露的模型/语音 ID、规范模式、传输方式、brain 策略以及实时音频/能力标志；不会返回提供商 secrets，也不会修改全局配置。当前网关在应用运行时提供商选择后会设置 ready；在较旧网关上，若缺少该字段，应视为未验证。
  • talk.config 返回有效的 Talk 配置负载；includeSecrets 需要 operator.talk.secrets（或 operator.admin）权限。
  • talk.session.create（需要 operator.talk）为 realtime/gateway-relay、transcription/gateway-relay 或 stt-tts/managed-room 创建网关拥有的 Talk 会话。对于 stt-tts/managed-room，传入 sessionKey 的非管理员调用者还必须传入 spawnedBy，以实现有作用域的 session-key 可见性；无作用域的 sessionKey 创建以及 brain: "direct-tools" 需要 operator.admin 权限。
  • talk.session.appendAudio 将 base64 PCM 输入音频追加到网关拥有的实时中继和转写会话。
  • talk.session.cancelOutput 停止助手音频输出，主要用于网关中继会话中的 VAD 门控插话（barge-in）。从当前音频事件的 talkEvent 中传入 turnId；结果为 applied、stale 或 idle。
  • talk.session.submitToolResult 完成由网关拥有的实时中继会话发出的提供商工具调用。该请求会等待 provider bridge 暴露的任何异步完成信号；失败的提交会使关联的 run 保持活动状态，并且不会发出成功的 tool-result 事件。若要提供中间工具输出，请传入 options: { willContinue: true }；当 provider bridge 声明支持抑制且结果不应启动另一个响应时，请传入 options: { suppressResponse: true }。
  • talk.session.steer 将 active-run 语音控制发送到网关拥有的、由 agent 支持的 Talk 会话：{ sessionId, text, mode? }，其中 mode 为 status、steer、cancel 或 followup；省略 mode 时会根据语音文本进行分类。它只选择绑定到该逻辑语音呼叫的工作，而不是共享同一连接和 agent 会话的其他呼叫。
  • talk.session.close 关闭网关拥有的中继、转写或 managed-room 会话，并发出终态 Talk 事件。
  • talk.mode 为 WebChat/Control UI 客户端设置/广播当前的 Talk 模式状态。
  • talk.client.create 使用 webrtc 或 provider-websocket 创建或恢复客户端拥有的实时提供商会话，而网关拥有凭据、指令、工具策略以及返回的 voiceSessionId。客户端在单次呼叫中替换提供商传输时会传入 sessionKey 并复用 voiceSessionId。协商 gateway-control-v1 的客户端保持 WebRTC 媒体直连，但会将提供商控制通道和工具生命周期移交给 Gateway。
  • talk.client.transcript 将一条已最终确定的 { role, text } 项追加到常规 agent 会话。必需的 entryId 在 voiceSessionId 内是幂等的；重试不会导致 transcript 消息重复。
  • talk.client.close 在待处理的 transcript 写入完成后关闭逻辑语音会话。关闭是幂等的，并且可能会向该会话的最后一个非 WebChat 通道投递仅包含变更的调用摘要。
  • talk.client.toolCall 允许客户端拥有的实时传输将提供商工具调用转发给网关策略。第一个受支持的工具是 openclaw_agent_consult；客户端会获得 runId、agentId 和规范的 agentSessionKey，并在提交提供商特定的工具结果之前等待常规聊天生命周期事件。对 chat.abort 和 chat.history 使用返回的 target；对语音会话请求则保留原始 key。语音绑定的高影响操作会返回 VOICE_CONFIRMATION_REQUIRED:<id>，直到后续一条已最终确定并保存的用户话语明确确认该确切的最终执行操作。函数工具咨询会在下一次咨询时提供 confirmationId，绝不会在底层操作工具上提供。原生语音委托会在用户 transcript 保存后通过 Gateway 解析当前确认。策略或 hook 重写后需要再次确认。Code Mode 脚本不会作为一个整体被确认；每个嵌套的工具调用都由其自身的操作确认。
  • talk.client.steer 为客户端拥有的实时传输发送会话作用域的 active-run 语音控制。网关会从 sessionKey 解析其拥有的活动工作，无需语音呼叫 ID，并返回结构化的 accepted/rejected 结果，而不是静默丢弃转向控制。相反，与提供商绑定的 Gateway 控制则按呼叫作用域生效。
  • talk.event 是用于实时、转写、STT/TTS、managed-room、电话和会议适配器的单一 Talk 事件通道。
  • talk.speak 通过当前活动的 Talk 语音提供商合成语音。
  • tts.status 返回 TTS 启用状态、当前提供商、备用提供商以及提供商的配置状态。
  • tts.providers 返回可见的 TTS 提供商清单。
  • tts.enable 和 tts.disable 切换 TTS 偏好设置状态。
  • tts.setProvider 更新首选的 TTS 提供商。
  • tts.convert 执行一次性文本转语音转换。
  • tts.speak（需要 operator.write）使用配置的通用 TTS 提供商链渲染非空 text，并以 audioBase64 形式内联返回一整段音频片段，同时返回 provider 以及可选的 outputFormat、mimeType 和 fileExtension 元数据。与 tts.convert 不同，它不会返回 Gateway 本地路径；与 talk.speak 不同，它不要求 Talk 提供商。超过 tts.maxTextLength 的文本返回 INVALID_REQUEST；合成失败返回 UNAVAILABLE。

中继输出取消

对于可中断的提供商，applied 仅确认输出已在本地清除，并不表示提供商已完成被中断的响应。如果确认耗时超过一秒，麦克风输入将恢复，同时 Gateway 会继续丢弃该响应的音频、助手转录和工具调用。只有该提供商的边界或提供商连续性重置才会释放该输出所有者。如果响应在接下来的 30 秒内仍未完成，会话将失败，而不是接受过期的输出。

当被中断的响应仍拥有输出时，取消较新的纯输入轮次会返回 stale，包括省略 turnId 时。一旦提供商开始较新的响应，其自身的轮次就可以正常取消。故意不可中断的提供商会忽略抢占（barge-in），并在显式停止输出时结束会话。talk.session.close 始终结束会话。

Secrets、config、update 与 wizard

  • secrets.reload 重新解析活动的 SecretRef，并原子地发布感知所有者的运行时状态。符合条件的所有者故障可以发布为冷或陈旧降级，并带有 warningCount；严格或未映射的故障会拒绝重新加载并保留活动快照。
  • secrets.resolve 为特定的命令/目标集合解析命令目标的 secret 分配。
  • secrets.store.list（operator.admin）仅针对 kind: "env" 条目返回团队作用域的元数据和值。kind: "secret" 条目使用不同的结果结构，且没有 value 字段；没有 reveal 方法。
  • secrets.store.set 和 secrets.store.delete（operator.admin）创建/更新或软删除一个团队作用域的条目。成功写入后，仅当该名称被活动源配置中的 store SecretRef 引用时，Gateway 才会刷新活动的 secrets 运行时。
  • config.get 返回当前磁盘上的配置快照、由作者生成的不透明 hash（覆盖根文件字节以及捕获的 include 标识和内容）、解析后的 configRevisionHash，以及可选 appliedConfigHash（对应活动 Gateway 运行时已接受的已解析修订版本）。
  • config.set 写入经过验证的配置负载。
  • config.patch 合并部分配置更新。破坏性数组替换要求在 replacePaths 中包含受影响的路径；数组条目下的嵌套数组使用 [] 路径，例如 agents.entries.*.skills。
  • config.apply 验证并替换完整的配置负载。
  • config.schema 返回 Control UI 和 CLI 工具使用的实时配置模式负载：schema、uiHints、版本、生成元数据，以及可加载时的插件 + 通道模式元数据。它包含与 UI 相同标签/帮助文本中的 title / description 元数据，包括嵌套对象、通配符、数组项，以及在存在匹配字段文档时的 anyOf / oneOf / allOf 组合分支。
  • config.schema.lookup 为单个配置路径返回路径作用域的查找负载：规范化路径、浅层 schema 节点、匹配的提示 + hintPath、可选的 reloadKind，以及供 UI/CLI 向下钻取的直属子级摘要。reloadKind 是 restart、hot 或 none（src/config/schema.ts）之一，并镜像所请求路径的网关配置重载规划器。查找 schema 节点保留面向用户的文档和常见验证字段（title、description、type、enum、const、format、pattern、数字/字符串/数组/对象边界、additionalProperties、deprecated、readOnly、writeOnly）。子级摘要暴露 key、规范化 path、type、required、hasChildren、可选的 reloadKind，以及匹配的 hint / hintPath。
  • update.run 接受更新并返回其持久化的 runId；确认并不等于完成，带有会话的调用者可以包含 continuationMessage，以便启动时通过重启续接队列恢复一个后续的 agent 轮次。来自控制平面的受支持的包管理器和 Git 检出更新使用分离的 CLI 更新器。Gateway 在验证期间继续提供服务，并在其运行时文件被替换之前关闭。已启动的交接返回 ok: true，并带有 result.reason: "managed-service-handoff-started" 和 handoff.status: "started"。由同一 Gateway 进程处理的第二个并发 update.run 返回 ok: false，并带有 result.reason: "managed-service-handoff-already-running" 和 handoff.status: "already-running"；其续接不被接受，因此调用者可以在活动更新完成后重试。独立的 CLI 更新器和替换后的 Gateway 进程不受此进程本地保护的限制。不可用或失败的交接返回 ok: false，并带有 managed-service-handoff-unavailable 或 managed-service-handoff-failed，以及在需要手动 shell 更新时附加的 handoff.command。不可用意味着 OpenClaw 缺乏安全的监督边界或持久的服务标识，例如 systemd 的 OPENCLAW_SYSTEMD_UNIT。在已启动的交接期间，重启哨兵可能短暂报告 stats.reason: "restart-health-pending"；续接会等待重启后的 Gateway 的验证。
  • update.run 的确认字段区分通知投递与更新完成：ackDelivered 报告投递情况，ackQueued 报告通知所有者的接受情况，可选的 acknowledgement 包含通知文本。读取持久化的 run 以确定更新结果。
  • 来自 update.runs.get、update.runs.list 和更新状态的持久化 run JSON 可以包含 admission: { owner: "candidate" | "installed", protocol?, candidateVersion?, checks?, fallbackReason? }。每个检查都有 name、status（ok、warn 或 refuse）和可选的 detail。这会从现有的账本 JSON 中投射 origin.admission；origin.candidateAdmission 保留有界的候选判定、原因、警告和事实。较旧的记录省略这些字段。有关所有权和回退行为，请参阅候选拥有的准入。
  • update.status 刷新并返回最新的更新重启哨兵，包括可用时的重启后运行版本。
  • wizard.start、wizard.next、wizard.status 和 wizard.cancel 通过 WS RPC 暴露引导向导。

Agent 与工作区辅助功能

  • agents.list 返回网关可见的 agent 条目，包括有效的模型/运行时元数据和可选的语义 kind（agent 或 system）。带有记录创建来源的条目还包括 createdVia（operator、agent 或 claw）、可空的 creatorAgentId 和毫秒级 createdAt；没有来源的条目省略这些字段。客户端通告 agent-kind 握手能力以接收完整的类型化名单；没有该能力的客户端保留没有 system 行的旧版选择器安全名单。感知 kind 的客户端从普通选择器中排除 system 行，同时在诊断视图中保留它们。较旧的 v4 Gateway 可能返回没有 kind 的行。
  • agents.create、agents.update 和 agents.delete 管理 agent 记录和工作区连接。
  • claws.monitors（operator.admin，所有阶段均作为控制平面写入进行限流）支持Claw 移除。每个请求都包含本地配置文件的 binding: { configPath, statePath, cronStorePath }，并对照服务所有者进行检查。{ phase: "inspect", agentId, binding } 返回最多两个经证实的配置拥有的监控器快照，每个快照包含 id、name、enabled、agentId、null ownerAgentId、storeKey、declarationKey 和 revision。{ phase: "quiesce", agentId, operationId, monitors, binding } 在取消计划工作之前验证当前的删除日志和确切同意的快照。{ phase: "drain", agentId, operationId, binding } 还要求已应用的 agent 移除和监控器收敛。成功的静默或排空返回 { drained: true }；不完整的排空在五秒等待后返回 UNAVAILABLE。操作 id 必须与服务中 Gateway 状态里的实时日志匹配；它不是独立的清理权威。额外的请求字段将被拒绝。
  • agents.files.list、agents.files.get 和 agents.files.set 管理为 agent 暴露的引导工作区文件。agents.files.get 和 agents.files.set 返回文件内容的 hash（磁盘字节的 SHA-256 十六进制，与 sessions.files.set 使用的令牌相同）。agents.files.set 接受现有文件的可选 expectedHash，或对读取时缺失的文件接受 expectedMissing: true；这些前置条件不能组合使用。哈希已更改或文件已创建会拒绝写入，并返回 INVALID_REQUEST 错误，其 details.type 为 agent_file_conflict。可用时，details.currentHash 携带当前哈希；重新读取文件以重新基线。条件创建需要工作区主机的原子独占创建能力，如果该能力不可用则在不写入的情况下失败。省略两个前置条件则保持无条件覆盖。
  • audit.activity.list 返回版本化的仅元数据活动账本；audit.run.inspect 发现执行 id 或检查一个确切的执行身份上下文；audit.list 仍然是兼容性安全的 run/tool RPC。
  • agents.workspace.list 和 agents.workspace.get（operator.read）为Operator 作用域中所述的可信操作员域中的客户端提供 agent 工作区目录的只读分页浏览。请求仅接受工作区相对路径；读取保持限制在真实路径化的工作区根目录内（拒绝符号链接和硬链接逃逸）、大小受限，并且仅限于 UTF-8 文本和常见图像类型（base64）。当文件名不是有效的 UTF-8 时，工作区目录列表和文件搜索会报告错误；请在重试之前在主机上重命名该条目。响应不会暴露主机工作区路径。此命名空间中没有写操作。
  • transcripts.list（operator.read）列出持久化的会议捕获，最新的在前。可选的 limit 接受 1–200（默认 50）；providerId 过滤来源。sessions 结果包括选择器、提供商/来源定位器、时间、活动状态、话语计数、参与者、摘要可用性、可选的模型/启发式来源，以及限制为 280 字符的概览预览。来源定位器仅暴露 providerId、accountId、guildId、channelId 和 meetingUrl，绝不暴露自由格式的元数据。
  • transcripts.get（operator.read）接受 selector 和可选的 includeUtterances。它返回会话和存储的摘要，包括其规范化 Markdown；请求的话语经过净化并受限于 2,000 的捕获上限。缺失的摘要省略 summary 而不是生成笔记。两种 transcript 方法都像 agents.workspace.* 一样在单个可信 Gateway 域内读取；读者隔离需要单独的域。它们不导出文件或更改捕获状态。请参阅Transcripts CLI。
  • artifacts.download 为具有可达 Gateway HTTPS 来源的客户端接受可选的 transport: "http"。内联 transcript 工件随后返回用于原始字节下载的短期、连接绑定的 URL；省略 transport 则保留现有连接上的 base64。仅 WebSocket 可用性并不建立 HTTP 可达性。对于单个 WebSocket 响应来说过大的内联负载会被拒绝，并返回 artifact_download_unsupported；请使用 transport: "http"。请参阅HTTPS 工件下载。
  • artifacts.list、artifacts.get 和 artifacts.download 为显式的 sessionKey 或 runId 作用域暴露源自 transcript 的工件摘要和下载。Run 查询在服务端解析所属会话，并且只返回具有匹配来源的 transcript 媒体；不安全或本地 URL 来源返回不支持的下载，而不是在服务端获取。在 list、get 和 download 上设置 messageRole: "assistant" 以选择助手投递的工件（包括投递镜像），并排除上传的输入和原始工具观察。省略过滤器以保持所有角色的发现。将其与 runId 组合以用于特定 run；仅 run ID 不能标识生成的输出。较旧的 Gateway 拒绝新过滤器；客户端必须呈现该拒绝，而不是不带过滤器地重试。

  • artifacts.list 还接受 type: "image"、可选的 limit（1–4，默认 4）和不透明的 cursor，用于最近的图像发现。每页以 1 MiB 预算读取最多 32 条 transcript 消息，最新的在前，并且完整读取超大的消息；即使稀疏页面没有图像，nextCursor 也会继续进入更旧的消息。不超过 256 KiB 的内联图像在 image.url 中返回有界的数据 URL 预览。被引用的内联图像还返回可下载的 artifact_transcript_image_ id；超过预览边界时它们仅可引用，没有 image.url，其字节通过 artifacts.download 加载。超过边界且未被引用的内联图像被省略，页面报告 omittedOversized: true；打开会话以查看它们。基于 URL 的图像摘要保留来自结构化内容、规范化上传媒体事实或渲染后的 Markdown 引用中的 image.url。非托管的 URL 图像使用 preview_ id、source: "session-transcript-preview" 和不支持的下载：这些是预览引用，不是 artifacts.get 或 artifacts.download 的标识符。Control UI 对本地来源使用现有的经过身份验证的媒体路由和会话媒体策略，对托管的媒体和内联 transcript 图像使用工件下载所有者。发现永远不会恢复冷 transcript 或重建其投影；打开会话以恢复不可用的预览。游标在 15 分钟后过期，属于发起连接、agent、会话和查询，并拒绝 transcript 重置。没有 type 的请求保留完整的工件列表；limit 和 cursor 需要图像过滤器。

  • 完整的工件列表在 SQLite 转录修订版保持不变时，会在转录 worker 中复用有界的摘要元数据。追加、重写、分支变更和重置会在下次读取时使结果失效；每次请求仍会执行访问检查。列表操作不会 stat 工件文件，也不会在摘要缓存中保留其内容。

  • environments.list 和 environments.status (operator.read) 在没有 cloud-worker 配置时仍可用，并保留网关本地和节点环境发现。environments.list 还接受来自具有 operator.write 的调用方的可选 runtimeId。当运行时要求节点命令时，该请求会为每个已连接节点添加一个 Gateway 拥有的 requiredNodeCommand 结果。其封闭状态为 invocable、pending-approval、undeclared 或 unauthorized；它从不暴露节点的完整待处理声明。节点环境包含用于保持已知离线主机可见的持久化 sessionHost 标识，而当前已连接清单相对于该历史具有权威性。缺少标识表示 false。精确的有界 { total, available } worker 槽位仅在线可用，离线时省略；worker-turn 准入会消耗一个槽位，而基于节点的 remote-exec 不会。已配置的配置概要会暴露其有界的、按规范顺序排列的 executionModes 数组，以及现有的单值 executionMode 主要/默认显示投影。当前客户端仅通过 executionModes 中的成员关系选择配置。已配置的 cloud worker 以及早期配置留下的持久化记录会添加 worker 元数据，包含已配置的 profileId、providerId、可选的 leaseId、state、ageMs、可选的 idleMs 和 attachedSessionIds。Worker 生命周期状态为 requested、provisioning、bootstrapping、ready、attached、idle、draining、destroying、destroyed、failed 和 orphaned。已连接的节点还可能包含 workerBundle: { status: "installed", version } 或 workerBundle: { status: "missing" }。此可选观察具有重连作用域，并报告对一个 Gateway 保留 bundle 的验证；它不是启动权限。公开结果从不暴露 bundle 哈希、Gateway 命名空间、节点文件系统路径、回执或协议特性详情。
  • 带有 { projection: "profiles" } 的 environments.list 仅读取已配置的配置目录，包括由 provider 编写的机器和操作系统选项。如果没有通告任何配置，则返回 environments: [] 并省略 profiles。不会读取 worker 和配对设备清单，因此清单故障不会阻止配置发现。省略 projection 会保留完整清单行为。即使使用配置投影，包含 runtimeId 仍需要 operator.write。
  • environments.create ({ profileId, idempotencyKey }) 根据已配置的插件 provider 配置供应环境；使用相同密钥重试会复用持久化操作。在没有会话的情况下直接创建不会选择执行模式，因此 provider 会使用其有意设置的默认值；Crabbox 会准备 worker-turn。environments.destroy ({ environmentId }) 请求对持久化 worker 环境进行幂等拆除。两者都需要 operator.admin，属于控制平面写入，并返回状态响应所使用的相同环境摘要形状。
  • environments.prepare ({ profileId, projectPath }, operator.admin) 允许在没有会话的情况下进行项目构建，并返回 { environmentId, preparationKey, reused }。它是一个受 provider 启动门控的控制平面写入。项目必须是本地 Git checkout；已配置的 provider 必须支持项目准备。匹配的未消耗构建或预留会被复用。已知错误会保留 details.code：profile_not_found、invalid_profile 和 invalid_project 映射到 INVALID_REQUEST；capacity 映射到 UNAVAILABLE。其他故障返回通用的 UNAVAILABLE，不包含 provider 详情。准备好的摘要仅暴露 preparation: { purpose: "reserve" | "build", key }。使用 environments.destroy 取消。有关池策略和设置授权，请参阅 按需构建。
  • worker.desktop.observe ({ environmentId, control? }, operator.admin) 启动或复用环境的桌面转发，并返回 { transport, wsPath, expiresAtMs, control, vncPassword? }。wsPath 携带一个供 Gateway 桌面观察器 WebSocket 使用的单次 60 秒 token；重连需要新的 observe 调用。具有可观察桌面的环境会在 environments.list 中通告 worker.desktop: true。仅当启用 cloudWorkers.desktop lab 时，才会通告该方法。请参阅 云 worker。
  • desktop.release ({ wsPath }, operator.admin) 在原始请求 Gateway 连接上放弃来自 desktop.observe 或 worker.desktop.observe 的未认领结果。它返回 { released }，并且仅释放该 ticket 的待处理节点流。未知、已过期、已认领以及其他连接的 ticket 返回 released: false；现有查看者和控制所有权保持不变。客户端应保留清理责任，直到 RFB 认证完成，并在其 presenter 关闭时释放迟到的结果。
  • agent.identity.get 返回 agent 或会话的有效助手身份。
  • agent.wait 等待运行完成，并在可用时返回终端快照。

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