openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 07:55:01 +00:00
parent ad18488134
commit f015291c79
7 changed files with 1182 additions and 1136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

556
docs/zh-CN/gateway/configuration-reference.md
View File

@ -1,63 +1,63 @@
---
read_when:
- 你需要精确的字段级配置语义或默认值
- 你正在验证渠道、模型、Gateway 网关或工具配置块
summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考的链接
- 你正在验证渠道、模型、Gateway 网关或工具的配置块
summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键、默认值，以及指向专用子系统参考的链接
title: 配置参考
x-i18n:
generated_at: "2026-05-02T05:38:55Z"
generated_at: "2026-05-02T07:52:23Z"
model: gpt-5.5
provider: openai
source_hash: 0a5820cac79161975cb4ab4ba8171df3d29366cbee2913d093374e2aa8b604a1
source_hash: afdbe56195982130603f02ff2350f253c32db4d72723035bba52d630a971602a
source_path: gateway/configuration-reference.md
workflow: 16
---
`~/.openclaw/openclaw.json` 的核心配置参考。有关面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。
`~/.openclaw/openclaw.json` 的核心配置参考。如需面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。
涵盖主要的 OpenClaw 配置界面，并在子系统有自己的更深入参考时链接到相应页面。渠道和插件拥有的命令目录以及深层记忆/QMD 调整项位于它们自己的页面，而不是此页面。
涵盖主要的 OpenClaw 配置界面；当某个子系统有自己的更深入参考时，会链接到对应页面。渠道和插件拥有的命令目录，以及深层记忆/QMD 调节项，位于各自页面，而不在本页。
代码真相：
代码事实来源：
- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据
- `config.schema.lookup` 返回一个路径限定的 schema 节点，供下钻工具使用
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希
- `openclaw config schema` 会打印用于验证和控制 UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据
- `config.schema.lookup` 会返回一个按路径限定的 schema 节点，供下钻工具使用
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 界面验证配置文档基线哈希
智能体查找路径：编辑前，使用 `gateway` 工具操作 `config.schema.lookup` 获取精确的字段级文档和约束。使用 [配置](/zh-CN/gateway/configuration) 获取面向任务的指导，并使用此页面了解更广泛的字段映射、默认值以及指向子系统参考的链接。
智能体查找路径：编辑前，使用 `gateway` 工具操作 `config.schema.lookup` 获取精确的字段级文档和约束。使用 [配置](/zh-CN/gateway/configuration) 获取面向任务的指导，使用本页查看更广泛的字段映射、默认值以及子系统参考链接。
专用深度参考：
专用深层参考：
- [记忆配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
- [斜杠命令](/zh-CN/tools/slash-commands)，适用于当前内置 + 打包命令目录
- 拥有相关渠道专属命令表面的渠道/插件页面
- [记忆配置参考](/zh-CN/reference/memory-config)，涵盖 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
- [斜杠命令](/zh-CN/tools/slash-commands)，涵盖当前内置 + 内置打包命令目录
- 拥有渠道特定命令界面的渠道/插件页面
配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 — 省略时，OpenClaw 会使用安全默认值。
配置格式为 **JSON5**（允许注释 + 尾随逗号）。所有字段都是可选的 —— 省略时 OpenClaw 会使用安全默认值。
---
## 渠道
各渠道配置键已移至专用页面 — 请参阅 [配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`，包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他内置渠道（凭证、访问控制、多账号、提及门控）。
每个渠道的配置键已移至专用页面 —— 请参阅 [配置 — 渠道](/zh-CN/gateway/config-channels) 获取 `channels.*`，包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道（认证、访问控制、多账户、提及门控）。
## 智能体默认值、多智能体、会话和消息
已移至专用页面 — 请参阅 [配置 — 智能体](/zh-CN/gateway/config-agents)，了解：
已移至专用页面 —— 请参阅 [配置 — 智能体](/zh-CN/gateway/config-agents)，涵盖：
- `agents.defaults.*`（工作区、模型、thinking、heartbeat、记忆、媒体、Skills、沙箱）
- `agents.defaults.*`（工作区、模型、思考、Heartbeat、记忆、媒体、Skills、沙箱）
- `multiAgent.*`（多智能体路由和绑定）
- `session.*`（会话生命周期、压缩、裁剪）
- `session.*`（会话生命周期、压缩、修剪）
- `messages.*`（消息投递、TTS、Markdown 渲染）
- `talk.*`（Talk 模式）
- `talk.speechLocale`：用于 iOS/macOS 上 Talk 语音识别的可选 BCP 47 locale id
- `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转写文本前保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）
- `talk.speechLocale`：用于 iOS/macOS 上 Talk 语音识别的可选 BCP 47 语言区域 ID
- `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）
## 工具和自定义提供商
工具策略、实验性开关、由提供商支持的工具配置，以及自定义提供商 / base-URL 设置已移至专用页面 — 请参阅 [配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。
工具策略、实验性开关、由提供商支持的工具配置，以及自定义提供商/base-URL 设置已移至专用页面 —— 请参阅 [配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。
## Models
提供商定义、模型允许列表和自定义提供商设置位于 [配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。`models` 根级也拥有全局模型目录行为。
提供商定义、模型 allowlist 和自定义提供商设置位于 [配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。`models` 根节点还拥有全局模型目录行为。
```json5
{
@ -69,12 +69,12 @@ x-i18n:
```
- `models.mode`：提供商目录行为（`merge` 或 `replace`）。
- `models.providers`：按提供商 id 键控的自定义提供商映射。
- `models.pricing.enabled`：控制后台定价引导。当为 `false` 时，Gateway 网关启动会跳过 OpenRouter 和 LiteLLM 定价目录获取；已配置的 `models.providers.*.models[].cost` 值仍可用于本地成本估算。
- `models.providers`：按提供商 ID 索引的自定义提供商映射。
- `models.pricing.enabled`：控制后台价格引导流程。当为 `false` 时，Gateway 网关启动会跳过 OpenRouter 和 LiteLLM 价格目录抓取；已配置的 `models.providers.*.models[].cost` 值仍可用于本地成本估算。
## MCP
OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、`show`、`set` 和 `unset` 命令会在配置编辑期间管理此区块，而不会连接到目标服务器。
由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、`show`、`set` 和 `unset` 命令会管理此块，且在编辑配置期间不会连接到目标服务器。
```json5
{
@ -98,11 +98,14 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
}
```
- `mcp.servers`：命名的 stdio 或远程 MCP 服务器定义，供暴露已配置 MCP 工具的运行时使用。远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`；`type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。
- `mcp.sessionIdleTtlMs`：会话限定的内置 MCP 运行时的空闲 TTL。一次性嵌入式运行会请求运行结束清理；此 TTL 是长生命周期会话和未来调用方的后备机制。
- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。下一次工具发现/使用会根据新配置重新创建它们，因此已移除的 `mcp.servers` 条目会立即被回收，而不是等待空闲 TTL。
- `mcp.servers`：命名 stdio 或远程 MCP 服务器定义，供暴露已配置 MCP 工具的运行时使用。
远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`；`type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。
- `mcp.sessionIdleTtlMs`：会话限定的内置 MCP 运行时的空闲 TTL。
一次性嵌入式运行会请求在运行结束时清理；此 TTL 是长期会话和未来调用方的兜底机制。
- `mcp.*` 下的变更会通过释放缓存的会话 MCP 运行时来热应用。
下一次工具发现/使用会根据新配置重新创建它们，因此移除的 `mcp.servers` 条目会立即回收，而不是等待空闲 TTL。
有关运行时行为，请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 [CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。
请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 [CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays) 了解运行时行为。
## Skills
@ -129,12 +132,12 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
}
```
- `allowBundled`：仅用于内置 Skills 的可选允许列表（不影响托管/工作区 Skills）。
- `load.extraDirs`：额外的共享 skill 根目录（最低优先级）。
- `allowBundled`：可选 allowlist，仅适用于内置 Skills（不影响托管/工作区 Skills）。
- `load.extraDirs`：额外共享 skill 根目录（最低优先级）。
- `install.preferBrew`：为 true 时，如果 `brew` 可用，会优先使用 Homebrew 安装器，然后再回退到其他安装器类型。
- `install.nodeManager`：`metadata.openclaw.install` 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使某个 skill 已内置/安装，也会禁用它。
- `entries.<skillKey>.apiKey`：为声明主环境变量的 Skills 提供的便捷项（明文字符串或 SecretRef 对象）。
- `install.nodeManager`：用于 `metadata.openclaw.install` 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使 skill 是内置/已安装的，也会禁用它。
- `entries.<skillKey>.apiKey`：便捷字段，供声明主环境变量的 Skills 使用（明文字符串或 SecretRef 对象）。
---
@ -162,41 +165,41 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
}
```
- 从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 以及 `plugins.load.paths` 加载。
- 设备发现接受原生 OpenClaw 插件以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。
- **配置更改需要重启 Gateway 网关。**
- `allow`：可选允许列表（只加载列出的插件）。`deny` 优先。
- 从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 加上 `plugins.load.paths` 加载。
- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括没有 manifest 的 Claude 默认布局 bundles。
- **配置变更需要重启 Gateway 网关。**
- `allow`：可选 allowlist（仅加载列出的插件）。`deny` 优先。
- `plugins.entries.<id>.apiKey`：插件级 API key 便捷字段（当插件支持时）。
- `plugins.entries.<id>.env`：插件限定的环境变量映射。
- `plugins.entries.<id>.hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略来自旧版 `before_agent_start` 的 prompt 变更字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持的由 bundle 提供的钩子目录。
- `plugins.entries.<id>.env`：插件作用域的环境变量映射。
- `plugins.entries.<id>.hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持的 bundle 提供的钩子目录。
- `plugins.entries.<id>.hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可以从类型化钩子读取原始对话内容，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`。
- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任此插件为后台子智能体运行请求逐次运行的 `provider` 和 `model` 覆盖。
- `plugins.entries.<id>.subagent.allowedModels`：受信任子智能体覆盖的标准 `provider/model` 目标的可选允许列表。仅在你有意允许任何模型时使用 `"*"`。
- `plugins.entries.<id>.config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。
- 渠道插件账号/运行时设置位于 `channels.<id>` 下，并应由拥有该插件的 manifest `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。
- `plugins.entries.<id>.subagent.allowModelOverride`：明确信任此插件，使其可以为后台 subagent 运行请求每次运行的 `provider` 和 `model` 覆盖。
- `plugins.entries.<id>.subagent.allowedModels`：可信 subagent 覆盖目标的标准 `provider/model` 可选 allowlist。仅在你有意允许任何模型时才使用 `"*"`。
- `plugins.entries.<id>.config`：插件定义的配置对象（当可用时，会由原生 OpenClaw 插件 schema 验证）。
- 渠道插件账户/运行时设置位于 `channels.<id>` 下，并应由所属插件的 manifest `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl Web 抓取提供商设置。
- `apiKey`：Firecrawl API key（接受 SecretRef）。回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。
- `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`；自托管覆盖必须指向私有/内部端点）。
- `onlyMainContent`：仅从页面中提取主内容（默认：`true`）。
- `maxAgeMs`：最大缓存时长，单位为毫秒（默认：`172800000` / 2 天）。
- `timeoutSeconds`：抓取请求超时时间，单位为秒（默认：`60`）。
- `onlyMainContent`：仅从页面提取主要内容（默认：`true`）。
- `maxAgeMs`：最大缓存年龄，单位为毫秒（默认：`172800000` / 2 天）。
- `timeoutSeconds`：抓取请求超时，单位为秒（默认：`60`）。
- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok Web 搜索）设置。
- `enabled`：启用 X Search 提供商。
- `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。
- `plugins.entries.memory-core.config.dreaming`：记忆 dreaming 设置。有关阶段和阈值，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
- `enabled`：主 dreaming 开关（默认 `false`）。
- `plugins.entries.memory-core.config.dreaming`：记忆 dreaming 设置。请参阅 [Dreaming](/zh-CN/concepts/dreaming) 了解阶段和阈值。
- `enabled`：dreaming 主开关（默认 `false`）。
- `frequency`：每次完整 dreaming 扫描的 cron 节奏（默认为 `"0 3 * * *"`）。
- `model`：可选的 Dream Diary 子智能体模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；与 `allowedModels` 搭配使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。
- 阶段策略和阈值是实现细节（不是面向用户的配置键）。
- `model`：可选的 Dream Diary subagent 模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；与 `allowedModels` 配对以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或 allowlist 失败不会静默回退。
- 阶段策略和阈值属于实现细节（不是面向用户的配置键）。
- 完整记忆配置位于 [记忆配置参考](/zh-CN/reference/memory-config)：
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
- 已启用的 Claude bundle 插件也可以从 `settings.json` 贡献嵌入式 Pi 默认值；OpenClaw 会将这些默认值作为经过清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。
- `plugins.slots.memory`：选择活动记忆插件 id，或使用 `"none"` 禁用记忆插件。
- `plugins.slots.contextEngine`：选择活动 context engine 插件 id；除非你安装并选择其他 engine，否则默认为 `"legacy"`。
- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些作为已清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。
- `plugins.slots.memory`：选择活动记忆插件 ID，或选择 `"none"` 禁用记忆插件。
- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；除非你安装并选择另一个引擎，否则默认为 `"legacy"`。
请参阅 [插件](/zh-CN/tools/plugin)。
@ -249,30 +252,30 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
```
- `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。
- `tabCleanup` 会在空闲一段时间后，或在会话超出上限时，回收已跟踪的主智能体标签页。设置 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可禁用对应的单项清理模式。
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置时会被禁用，因此浏览器导航默认保持严格模式。
- 仅在你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到同样的私有网络阻止限制。
- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。
- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。
- 远程配置文件仅支持附加连接（启动/停止/重置已禁用）。
- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当你的提供商提供直接的 DevTools WebSocket URL 时使用 WS(S)。
- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 `attachOnly` CDP 可达性以及标签页打开请求。托管的 local loopback 配置文件会保留本地 CDP 默认值。
- 如果外部托管的 CDP 服务可通过 loopback 访问，请为该配置文件设置 `attachOnly: true`；否则 OpenClaw 会将该 loopback 端口视为本地托管浏览器配置文件，并可能报告本地端口归属错误。
- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到所选主机或通过已连接的浏览器节点附加。
- `existing-session` 配置文件可以设置 `userDataDir`，以定位特定的基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。
- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：使用快照/引用驱动的操作而不是 CSS 选择器定位、单文件上传钩子、无对话框超时覆盖、无 `wait --load networkidle`，并且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。
- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有远程 CDP 才需要显式设置 `cdpUrl`。
- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 `browser.executablePath`。可用它让一个配置文件运行在 Chrome 中，另一个运行在 Brave 中。
- 本地托管配置文件会使用 `browser.localLaunchTimeoutMs` 在进程启动后进行 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 检查启动后的 CDP websocket 就绪状态。在 Chrome 能成功启动但就绪检查与启动过程发生竞态的较慢主机上，可提高这些值。两个值都必须是最大为 `120000` ms 的正整数；无效配置值会被拒绝。
- `tabCleanup` 会在空闲一段时间后，或当某个会话超过上限时，回收已跟踪的主智能体标签页。设置 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可禁用对应的单项清理模式。
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置时处于禁用状态，因此浏览器导航默认保持严格。
- 仅当你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止。
- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受到支持。
- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 设置显式例外。
- 远程配置文件仅可附加（禁用启动/停止/重置）。
- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当你的提供商给出直接的 DevTools WebSocket URL 时使用 WS(S)。
- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 `attachOnly` CDP 可达性以及标签页打开请求。托管的 loopback 配置文件会保留本地 CDP 默认值。
- 如果外部托管的 CDP 服务可通过 loopback 访问，请将该配置文件的 `attachOnly: true`；否则 OpenClaw 会把该 loopback 端口视为本地托管的浏览器配置文件，并可能报告本地端口归属错误。
- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以在所选主机上附加，或通过已连接的浏览器节点附加。
- `existing-session` 配置文件可以设置 `userDataDir`，以指向特定的基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。
- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：使用快照/ref 驱动的操作而不是 CSS 选择器定位、单文件上传钩子、不支持对话框超时覆盖、不支持 `wait --load networkidle`，并且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。
- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅对远程 CDP 显式设置 `cdpUrl`。
- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 `browser.executablePath`。可用它让一个配置文件运行 Chrome，另一个运行 Brave。
- 本地托管配置文件在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 等待启动后的 CDP websocket 就绪。在较慢的主机上，如果 Chrome 启动成功但就绪检查与启动过程产生竞争，请提高这些值。两个值都必须是最大为 `120000` 毫秒的正整数；无效的配置值会被拒绝。
- 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
- `browser.executablePath` 和 `browser.profiles.<name>.executablePath` 都接受 `~` 和 `~/...`，在启动 Chromium 前会将其展开为你的 OS 主目录。`existing-session` 配置文件上的每配置文件 `userDataDir` 也会进行波浪号展开。
- `browser.executablePath` 和 `browser.profiles.<name>.executablePath` 在启动 Chromium 前都接受 `~` 和 `~/...` 表示你的操作系统主目录。`existing-session` 配置文件上的单配置文件 `userDataDir` 也会展开波浪号。
- 控制服务：仅 loopback（端口派生自 `gateway.port`，默认 `18791`）。
- `extraArgs` 会向本地 Chromium 启动追加额外启动标志（例如 `--disable-gpu`、窗口尺寸或调试标志）。
- `extraArgs` 会向本地 Chromium 启动追加额外启动标志（例如 `--disable-gpu`、窗口大小或调试标志）。
---
## UI
## 界面
```json5
{
@ -286,8 +289,8 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
}
```
- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡色调等）。
- `assistant`：Control UI 身份覆盖。回退到当前活动智能体身份。
- `seamColor`：原生应用 UI chrome 的强调色（Talk Mode 气泡色调等）。
- `assistant`：Control UI 身份覆盖设置。回退到当前活跃智能体身份。
---
@ -362,54 +365,54 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
}
```
<Accordion title="Gateway field details">
<Accordion title="Gateway 网关字段详情">
- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。
- `port`：用于 WS + HTTP 的单一多路复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关拒绝启动。
- `port`：WS + HTTP 的单个复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
- `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。
- **旧版绑定别名**：在 `gateway.bind` 中使用绑定模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
- **Docker 注意事项**：默认的 `loopback` 绑定会监听容器内的 `127.0.0.1`。使用 Docker 桥接网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此无法访问 Gateway 网关。使用 `--network host`，或设置 `bind: "lan"`（或将 `bind: "custom"` 与 `customBindHost: "0.0.0.0"` 搭配使用）以监听所有接口。
- **身份验证**：默认必需。非 loopback 绑定要求 Gateway 网关身份验证。实际使用中，这意味着共享令牌/密码，或使用带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成一个令牌。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。两者都配置且未设置模式时，启动以及服务安装/修复流程会失败。
- `gateway.auth.mode: "none"`：显式无身份验证模式。仅用于可信的 local loopback 设置；新手引导提示有意不提供此选项。
- `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户身份验证委派给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（见 [可信代理身份验证](/zh-CN/gateway/trusted-proxy-auth)）。默认情况下，此模式预期使用**非 loopback** 代理来源；同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可以使用 `gateway.auth.password` 作为本地直接回退；`gateway.auth.token` 仍与 trusted-proxy 模式互斥。
- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份标头可以满足控制界面/WebSocket 身份验证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头身份验证；它们会改用 Gateway 网关的常规 HTTP 身份验证模式。此无令牌流程假设 Gateway 网关主机可信。当 `tailscale.mode = "serve"` 时默认为 `true`。
- `gateway.auth.rateLimit`：可选的身份验证失败限制器。按客户端 IP 和身份验证范围应用（shared-secret 和 device-token 独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
- 在异步 Tailscale Serve 控制界面路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败之前被串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求触发限制器，而不是两个请求都作为普通不匹配竞态通过。
- `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意希望 localhost 流量也受到速率限制时（用于测试设置或严格代理部署），请设置为 `false`。
- 浏览器来源的 WS 身份验证尝试始终会被节流，并且禁用 loopback 豁免（作为防御浏览器型 localhost 暴力破解的纵深防御）。
- 在 loopback 上，这些浏览器来源的锁定会按规范化后的 `Origin`
- **Docker 注意事项**：默认的 `loopback` 绑定会监听容器内的 `127.0.0.1`。使用 Docker 桥接网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关不可访问。使用 `--network host`，或设置 `bind: "lan"`（或将 `bind: "custom"` 与 `customBindHost: "0.0.0.0"` 配合使用）以监听所有接口。
- **认证**：默认必需。非 loopback 绑定需要 Gateway 网关认证。实际使用中，这意味着共享令牌/密码，或带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成令牌。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。当两者都已配置且模式未设置时，启动和服务安装/修复流程会失败。
- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的 local loopback 设置；新手引导提示会刻意不提供此选项。
- `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。默认情况下，此模式期望一个**非 loopback**代理源；同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可以将 `gateway.auth.password` 用作本地直接回退；`gateway.auth.token` 仍然与 trusted-proxy 模式互斥。
- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头认证；它们会改为遵循 Gateway 网关的常规 HTTP 认证模式。这个无令牌流程假定 Gateway 网关主机受信任。当 `tailscale.mode = "serve"` 时默认为 `true`。
- `gateway.auth.rateLimit`：可选的失败认证限制器。按客户端 IP 和认证作用域应用（shared-secret 和 device-token 独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败响应前被串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求触发限制器，而不是两个请求都作为普通不匹配竞态通过。
- `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意也要对 localhost 流量进行速率限制时（用于测试设置或严格代理部署），请设置为 `false`。
- 浏览器来源的 WS 认证尝试始终会被限流，并禁用 loopback 豁免（针对基于浏览器的 localhost 暴力破解进行纵深防御）。
- 在 loopback 上，这些浏览器来源锁定会按规范化的 `Origin`
值隔离，因此来自某个 localhost 来源的重复失败不会自动
锁定另一个来源。
- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开，需要身份验证）。
- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开，需要认证）。
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时必需。
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 标头来源策略的部署启用 Host 标头来源回退。
- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境
破例覆盖项，允许向可信私有网络
IP 使用明文 `ws://`；明文默认仍仅限 loopback。没有对应的 `openclaw.json`
配置，并且诸如
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 之类的浏览器私有网络配置不会影响 Gateway 网关
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境中的
破窗覆盖开关，允许对受信任的私有网络
IP 使用明文 `ws://`；默认仍然仅允许 loopback 使用明文。没有等效的 `openclaw.json`
配置，并且像
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 这样的浏览器私有网络配置不会影响 Gateway 网关
WebSocket 客户端。
- `gateway.remote.token` / `.password` 是远程客户端凭据字段。它们本身不会配置 Gateway 网关身份验证。
- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 Gateway 网关发布由中继支持的注册后，用于外部 APNs 中继的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建的中继 URL 匹配。
- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。
- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 Gateway 网关发布基于中继的注册后使用的外部 APNs 中继的 HTTPS 基础 URL。此 URL 必须与编译进 iOS 构建的中继 URL 匹配。
- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时，单位为毫秒。默认为 `10000`。
- 由中继支持的注册会委派给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并将注册范围的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用该已存储的注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上方中继配置的临时环境变量覆盖项。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅开发用途的逃生开关，用于 loopback HTTP 中继 URL。生产中继 URL 应保持使用 HTTPS。
- `gateway.handshakeTimeoutMs`：预身份验证 Gateway 网关 WebSocket 握手超时，单位为毫秒。默认：`15000`。设置 `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 时它优先。在负载较高或低功耗主机上，如果本地客户端可能在启动预热仍在稳定时连接，请增大此值。
- 基于中继的注册会委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并将注册范围的发送授权转发给 Gateway 网关。另一个 Gateway 网关不能重用该已存储注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：用于上述中继配置的临时环境变量覆盖。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅开发用的逃生口，用于 loopback HTTP 中继 URL。生产中继 URL 应保持 HTTPS。
- `gateway.handshakeTimeoutMs`：认证前 Gateway 网关 WebSocket 握手超时，单位为毫秒。默认：`15000`。设置 `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 时优先使用它。对于负载较高或低功耗主机，如果本地客户端能连接但启动预热仍在稳定中，可增大此值。
- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设置为 `0` 可全局禁用健康监控重启。默认：`5`。
- `gateway.channelStaleEventThresholdMinutes`：过期套接字阈值，单位为分钟。保持此值大于或等于 `gateway.channelHealthCheckMinutes`。默认：`30`。
- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内的最大健康监控重启次数。默认：`10`。
- `channels.<provider>.healthMonitor.enabled`：每渠道选择退出健康监控重启，同时保持全局监控启用。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号渠道的每账号覆盖项。设置后，它优先于渠道级覆盖项。
- 只有在 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可以使用 `gateway.remote.*` 作为回退。
- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 且无法解析，解析会失败关闭（不会用远程回退掩盖）。
- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。
- `allowRealIpFallback`：当为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现失败关闭行为。
- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准首次节点设备配对，且无请求的范围。未设置时禁用。它不会自动批准操作员/浏览器/控制界面/WebChat 配对，也不会自动批准角色、范围、元数据或公钥升级。
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和平台允许列表评估后，对声明的节点命令进行全局允许/拒绝塑形。使用 `allowCommands` 选择启用危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许原本会包含某个命令，`denyCommands` 也会移除它。节点更改其声明的命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。
- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 阻止的额外工具名称（扩展默认拒绝列表）。
- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。保持此值大于或等于 `gateway.channelHealthCheckMinutes`。默认：`30`。
- `gateway.channelMaxRestartsPerHour`：每个渠道/账户在滚动一小时内的最大健康监控重启次数。默认：`10`。
- `channels.<provider>.healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保持全局监控启用。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账户渠道的按账户覆盖。设置后，它优先于渠道级覆盖。
- 只有当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可以将 `gateway.remote.*` 用作回退。
- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置且未解析，解析会失败关闭（不会用远程回退掩盖）。
- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。Loopback 条目对于同主机代理/本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。
- `allowRealIpFallback`：当为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认为 `false`，以实现失败关闭行为。
- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准无请求作用域的首次节点设备配对。未设置时禁用。它不会自动批准操作员/浏览器/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和平台允许列表评估之后，对声明的节点命令进行全局允许/拒绝塑形。使用 `allowCommands` 选择启用危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许本来会包含某个命令，`denyCommands` 也会移除它。节点更改其声明的命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。
- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。
- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。
</Accordion>
@ -425,7 +428,7 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
空允许列表会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false`
和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 获取。
- 可选响应加固标头：
- `gateway.http.securityHeaders.strictTransportSecurity`（仅为你控制的 HTTPS 来源设置；见 [可信代理身份验证](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
- `gateway.http.securityHeaders.strictTransportSecurity`（仅为你控制的 HTTPS 来源设置；见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
### 多实例隔离
@ -437,9 +440,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
```
便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile <name>`（使用 `~/.openclaw-<name>`）。
便利标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile <name>`（使用 `~/.openclaw-<name>`）。
见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。
见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。
### `gateway.tls`
@ -458,10 +461,10 @@ openclaw gateway --port 19001
```
- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。
- `autoGenerate`：未配置显式文件时，自动生成本地自签名证书/密钥对；仅用于本地/开发。
- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅用于本地/开发。
- `certPath`：TLS 证书文件的文件系统路径。
- `keyPath`：TLS 私钥文件的文件系统路径；保持权限受限。
- `caPath`：用于客户端验证或自定义信任链的可选 CA 捆绑包路径。
- `keyPath`：TLS 私钥文件的文件系统路径；请限制权限。
- `caPath`：用于客户端验证或自定义信任链的可选 CA 包路径。
### `gateway.reload`
@ -477,13 +480,13 @@ openclaw gateway --port 19001
}
```
- `mode`：控制配置编辑在运行时如何应用。
- `mode`：控制配置编辑在运行时的应用方式。
- `"off"`：忽略实时编辑；更改需要显式重启。
- `"restart"`：配置更改时始终重启 Gateway 网关进程。
- `"hot"`：在进程内应用更改而不重启。
- `"hybrid"`（默认）：先尝试热重载；如果需要则回退到重启。
- `"hot"`：在进程内应用更改，无需重启。
- `"hybrid"`（默认）：先尝试热重载；必要时回退到重启。
- `debounceMs`：应用配置更改前的防抖窗口，单位为毫秒（非负整数）。
- `deferralTimeoutMs`：在强制重启前等待进行中操作的可选最长时间，单位为毫秒。省略它以使用默认有界等待（`300000`）；设置为 `0` 表示无限期等待并定期记录仍在等待的警告。
- `deferralTimeoutMs`：在强制重启前等待进行中操作的可选最长时间，单位为毫秒。省略它会使用默认有界等待（`300000`）；设置为 `0` 表示无限期等待，并定期记录仍有待处理操作的警告。
---
@ -520,47 +523,47 @@ openclaw gateway --port 19001
}
```
身份验证：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
认证：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
查询字符串钩子令牌会被拒绝。
验证与安全注意事项：
验证和安全说明：
- `hooks.enabled=true` 需要非空的 `hooks.token`。
- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关令牌会被拒绝。
- `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。
- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
- 如果某个映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该选择加入。
- 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
- 如果映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该选择加入。
**端点：**
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- 仅当 `hooks.allowRequestSessionKey=true`（默认值：`false`）时，才接受请求载荷中的 `sessionKey`。
- 只有当 `hooks.allowRequestSessionKey=true`（默认值：`false`）时，才接受请求负载中的 `sessionKey`。
- `POST /hooks/<name>` → 通过 `hooks.mappings` 解析
- 模板渲染的映射 `sessionKey` 值会被视为外部提供，也需要 `hooks.allowRequestSessionKey=true`。
- 模板渲染的映射 `sessionKey` 值会被视为外部提供的值，也需要 `hooks.allowRequestSessionKey=true`。
<Accordion title="映射详情">
- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。
- `match.source` 匹配通用路径的载荷字段。
- `{{messages[0].subject}}` 这样的模板会从载荷读取。
- `transform` 可以指向返回钩子操作的 JS/TS 模块。
- `transform.module` 必须是相对路径，并且保留在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。
- `match.source` 匹配通用路径的负载字段。
- 类似 `{{messages[0].subject}}` 的模板会从负载中读取。
- `transform` 可以指向返回 hook 动作的 JS/TS 模块。
- `transform.module` 必须是相对路径，并且保留在 `hooks.transformsDir` 内（绝对路径和目录遍历会被拒绝）。
- `agentId` 路由到特定智能体；未知 ID 会回退到默认值。
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 全部允许，`[]` = 全部拒绝）。
- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的钩子智能体运行。
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 拒绝全部）。
- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的 hook 智能体运行。
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。
- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化的 `sessionKey` 时，它会变为必需。
- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。
- `model` 会覆盖此钩子运行的 LLM（如果设置了模型目录，则必须被允许）。
- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。
- `model` 会覆盖此 hook 运行的 LLM（如果设置了模型目录，则必须被允许）。
</Accordion>
### Gmail 集成
- 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
- 如果保留这种按消息路由，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
- 如果需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该预设，而不是使用模板化默认值。
- 如果保留这种按消息路由，请设置 `hooks.allowRequestSessionKey: true`，并限制 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
- 如果需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖预设，而不是使用模板化默认值。
```json5
{
@ -584,7 +587,7 @@ openclaw gateway --port 19001
```
- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。
- 不要在 Gateway 网关旁边单独运行 `gog gmail watch serve`。
- 不要在 Gateway 网关旁边另行运行 `gog gmail watch serve`。
---
@ -600,16 +603,16 @@ openclaw gateway --port 19001
}
```
- 在 Gateway 网关端口下通过 HTTP 提供智能体可编辑的 HTML/CSS/JS 和 A2UI：
- 通过 HTTP 在 Gateway 网关端口下提供智能体可编辑的 HTML/CSS/JS 和 A2UI：
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
- 仅限本地：保留 `gateway.bind: "loopback"`（默认值）。
- 非 loopback 绑定：canvas 路由需要 Gateway 网关认证（令牌/密码/可信代理），与其他 Gateway 网关 HTTP 表面相同。
- Node WebView 通常不会发送认证标头；节点配对并连接后，Gateway 网关会公布节点作用域的能力 URL，用于 canvas/A2UI 访问。
- 能力 URL 绑定到活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。
- 将实时重载客户端注入到所提供的 HTML 中。
- 仅限本地：保持 `gateway.bind: "loopback"`（默认值）。
- 非 loopback 绑定：canvas 路由需要 Gateway 网关认证（令牌/密码/受信任代理），与其他 Gateway 网关 HTTP 表面相同。
- 节点 WebViews 通常不会发送认证标头；节点完成配对并连接后，Gateway 网关会广播节点范围的能力 URL，用于访问 canvas/A2UI。
- 能力 URL 绑定到活跃的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。
- 将实时重载客户端注入到提供的 HTML 中。
- 为空时自动创建起始 `index.html`。
- 还会在 `/__openclaw__/a2ui/` 提供 A2UI。
- 也在 `/__openclaw__/a2ui/` 提供 A2UI。
- 更改需要重启 Gateway 网关。
- 对于大型目录或 `EMFILE` 错误，请禁用实时重载。
@ -631,9 +634,9 @@ openclaw gateway --port 19001
- `minimal`（默认值）：从 TXT 记录中省略 `cliPath` + `sshPort`。
- `full`：包含 `cliPath` + `sshPort`。
- 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。
- 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。可用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。
### 广域 (DNS-SD)
### 广域（DNS-SD）
```json5
{
@ -668,10 +671,10 @@ openclaw gateway --port 19001
}
```
- 仅当进程环境变量缺少该键时，才会应用内联环境变量。
- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。
- 仅当进程环境缺少该键时，才会应用内联环境变量。
- `.env` 文件：CWD `.env` + `~/.openclaw/.env`（都不会覆盖已有变量）。
- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。
- 完整优先级请参阅[环境](/zh-CN/help/environment)。
- 查看 [环境](/zh-CN/help/environment) 了解完整优先级。
### 环境变量替换
@ -685,16 +688,16 @@ openclaw gateway --port 19001
}
```
- 只匹配大写名称：`[A-Z_][A-Z0-9_]*`。
- 缺失/空变量会在配置加载时报错。
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。
- 缺失或为空的变量会在配置加载时报错。
- 使用 `$${VAR}` 转义为字面量 `${VAR}`。
- 可与 `$include` 配合使用。
- 可与 `$include` 一起使用。
---
## 密钥
密钥引用是增量式的：明文值仍然可用。
密钥引用是增量能力：明文值仍然可用。
### `SecretRef`
@ -704,19 +707,19 @@ openclaw gateway --port 19001
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
```
校验：
验证：
- `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$`
- `source: "env"` id 模式：`^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"` id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`）
- `source: "exec"` id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "exec"` id 不得包含 `.` 或 `..` 这样的以斜杠分隔的路径段（例如 `a/../b` 会被拒绝）
- `source: "exec"` id 不得包含 `.` 或 `..` 这种以斜杠分隔的路径段（例如 `a/../b` 会被拒绝）
### 支持的凭据表面
### 支持的凭证作用面
- 规范矩阵：[SecretRef 凭据表面](/zh-CN/reference/secretref-credential-surface)
- `secrets apply` 面向受支持的 `openclaw.json` 凭据路径。
- `auth-profiles.json` 引用包含在运行时解析和审计覆盖范围内。
- 规范矩阵：[SecretRef 凭证作用面](/zh-CN/reference/secretref-credential-surface)
- `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。
- `auth-profiles.json` 引用会包含在运行时解析和审计覆盖范围中。
### 密钥提供商配置
@ -749,13 +752,13 @@ openclaw gateway --port 19001
注意：
- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。
- 当 Windows ACL 校验不可用时，file 和 exec 提供商路径会以关闭失败方式处理。仅对无法校验但可信的路径设置 `allowInsecurePath: true`。
- `exec` 提供商需要绝对 `command` 路径，并通过 stdin/stdout 使用协议载荷。
- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时校验解析后的目标路径。
- 如果配置了 `trustedDirs`，可信目录检查会应用于解析后的目标路径。
- 默认情况下，`exec` 子进程环境是最小化的；使用 `passEnv` 显式传入所需变量。
- 密钥引用会在激活时解析到内存快照中，随后请求路径只读取该快照。
- 激活期间会应用活动表面过滤：已启用表面上的未解析引用会导致启动/重载失败，而非活动表面会被跳过并附带诊断信息。
- 当 Windows ACL 验证不可用时，file 和 exec 提供商路径会失败关闭。仅对无法验证且受信任的路径设置 `allowInsecurePath: true`。
- `exec` 提供商需要绝对 `command` 路径，并在 stdin/stdout 上使用协议载荷。
- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证解析后的目标路径。
- 如果配置了 `trustedDirs`，受信任目录检查会应用到解析后的目标路径。
- `exec` 子环境默认是最小环境；用 `passEnv` 显式传入所需变量。
- 密钥引用会在激活时解析为内存快照，之后请求路径只读取该快照。
- 激活期间会应用活动作用面过滤：已启用作用面上的未解析引用会导致启动/重新加载失败，而非活动作用面会被跳过并带有诊断信息。
---
@ -778,13 +781,13 @@ openclaw gateway --port 19001
```
- 每个智能体的配置文件存储在 `<agentDir>/auth-profiles.json`。
- `auth-profiles.json` 支持静态凭据模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将它们重写为规范的 `provider:default` API key 配置文件，并生成 `.legacy-flat.*.bak` 备份。
- OAuth 模式配置文件（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭据。
- 静态运行时凭据来自已解析的内存快照；发现旧版静态 `auth.json` 条目时会将其清理。
- `auth-profiles.json` 支持静态凭证模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将它们改写为规范的 `provider:default` API-key 配置文件，并创建 `.legacy-flat.*.bak` 备份。
- OAuth 模式配置文件（`auth.profiles.<id>.mode = "oauth"`）不支持基于 SecretRef 的 auth-profile 凭证。
- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会清理它们。
- 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。
- 请参阅 [OAuth](/zh-CN/concepts/oauth)。
- 密钥运行时行为以及 `audit/configure/apply` 工具：[密钥管理](/zh-CN/gateway/secrets)。
- 查看 [OAuth](/zh-CN/concepts/oauth)。
- 密钥运行时行为和 `audit/configure/apply` 工具：[密钥管理](/zh-CN/gateway/secrets)。
### `auth.cooldowns`
@ -806,19 +809,24 @@ openclaw gateway --port 19001
}
```
- `billingBackoffHours`：当配置文件因真实的账单/额度不足错误而失败时的基础退避时间（小时，默认值：`5`）。即使在 `401`/`403` 响应上，显式账单文本仍可能归入这里，但特定提供商的文本匹配器仍限定在其所属提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或组织/工作区支出限额消息会继续走 `rate_limit` 路径。
- `billingBackoffHoursByProvider`：可选的按提供商覆盖账单退避小时数。
- `billingMaxHours`：账单退避指数增长的小时上限（默认值：`24`）。
- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时间（分钟，默认值：`10`）。
- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认值：`60`）。
- `failureWindowHours`：用于退避计数器的滚动窗口（小时，默认值：`24`）。
- `overloadedProfileRotations`：在切换到模型回退之前，因过载错误允许的最大同提供商 auth-profile 轮换次数（默认值：`1`）。`ModelNotReadyException` 等提供商繁忙形态会归入这里。
- `overloadedBackoffMs`：重试过载的提供商/配置文件轮换前的固定延迟（默认值：`0`）。
- `rateLimitedProfileRotations`：在切换到模型回退之前，因速率限制错误允许的最大同提供商 auth-profile 轮换次数（默认值：`1`）。该速率限制桶包含提供商形态文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
- `billingBackoffHours`：当某个配置文件因真正的
计费/余额不足错误而失败时的基础退避小时数（默认：`5`）。即使是在 `401`/`403` 响应上，
明确的计费文本仍可能进入这里，但提供商特定的文本
匹配器仍限定在拥有它们的提供商范围内（例如 OpenRouter
`Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或
组织/工作区支出上限消息会保留在 `rate_limit` 路径中。
- `billingBackoffHoursByProvider`：可选的按提供商覆盖计费退避小时数。
- `billingMaxHours`：计费退避指数增长的小时数上限（默认：`24`）。
- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认：`10`）。
- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟数上限（默认：`60`）。
- `failureWindowHours`：用于退避计数器的滚动窗口小时数（默认：`24`）。
- `overloadedProfileRotations`：在切换到模型回退前，过载错误允许的最大同提供商 auth-profile 轮换次数（默认：`1`）。类似 `ModelNotReadyException` 的提供商忙碌形态会进入这里。
- `overloadedBackoffMs`：重试过载提供商/配置文件轮换前的固定延迟（默认：`0`）。
- `rateLimitedProfileRotations`：在切换到模型回退前，速率限制错误允许的最大同提供商 auth-profile 轮换次数（默认：`1`）。该速率限制桶包含提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
---
## 日志记录
## 日志
```json5
{
@ -836,8 +844,8 @@ openclaw gateway --port 19001
- 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。
- 设置 `logging.file` 以使用稳定路径。
- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。
- `maxFileBytes`：轮转前活动日志文件的最大大小（字节）（正整数；默认：`104857600` = 100 MB）。OpenClaw 会在活动文件旁最多保留五个带编号的归档文件。
- `redactSensitive` / `redactPatterns`：尽力对控制台输出、文件日志、OTLP 日志记录以及持久化的会话转录文本进行遮蔽。`redactSensitive: "off"` 只会禁用这项通用日志/转录策略；UI/工具/诊断安全表面在发出前仍会遮蔽密钥。
- `maxFileBytes`：轮转前活动日志文件的最大大小，以字节为单位（正整数；默认值：`104857600` = 100 MB）。OpenClaw 会在活动文件旁边保留最多五个带编号的归档文件。
- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录和持久化的会话转录文本进行尽力而为的遮蔽。`redactSensitive: "off"` 只会禁用这个通用日志/转录策略；UI/工具/诊断安全表面在发出前仍会遮蔽密钥。
---
@ -887,23 +895,23 @@ openclaw gateway --port 19001
- `enabled`：检测输出的主开关（默认：`true`）。
- `flags`：启用定向日志输出的标志字符串数组（支持像 `"telegram.*"` 或 `"*"` 这样的通配符）。
- `stuckSessionWarnMs`：用于将长时间运行的处理会话分类为 `session.long_running`、`session.stalled` 或 `session.stuck` 的无进展时间阈值（毫秒）。回复、工具、Status、分块和 ACP 进度会重置计时器；重复的 `session.stuck` 诊断在未变化时会退避。
- `otel.enabled`：启用 OpenTelemetry 导出流水线（默认：`false`）。完整配置、信号目录和隐私模型请参阅 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。
- `otel.endpoint`：OTel 导出的收集器 URL。
- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的信号专用 OTLP 端点。设置后，它们只会为对应信号覆盖 `otel.endpoint`。
- `stuckSessionWarnMs`：用于将长时间运行的处理会话分类为 `session.long_running`、`session.stalled` 或 `session.stuck` 的无进展时间阈值，单位为毫秒。回复、工具、Status、分块和 ACP 进度会重置计时器；重复的 `session.stuck` 诊断在未变化时会退避。
- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。完整配置、信号目录和隐私模型见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。
- `otel.endpoint`：用于 OTel 导出的收集器 URL。
- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的信号专用 OTLP 端点。设置后，它们只会覆盖该信号的 `otel.endpoint`。
- `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。
- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据标头。
- `otel.serviceName`：资源属性的服务名称。
- `otel.traces` / `otel.metrics` / `otel.logs`：启用链路追踪、指标或日志导出。
- `otel.sampleRate`：链路追踪采样率 `0`–`1`。
- `otel.flushIntervalMs`：定期遥测刷新间隔（毫秒）。
- `otel.captureContent`：选择性启用 OTEL span 属性的原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：启用最新实验性 GenAI span 提供商属性的环境开关。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI 指标使用有界语义属性。
- `OPENCLAW_OTEL_PRELOADED=1`：用于已注册全局 OpenTelemetry SDK 的宿主的环境开关。随后 OpenClaw 会跳过插件拥有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。
- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：在对应配置键未设置时使用的信号专用端点环境变量。
- `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认：`false`）。
- `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含哪些内容（全部默认：`true`）。
- `otel.traces` / `otel.metrics` / `otel.logs`：启用跟踪、指标或日志导出。
- `otel.sampleRate`：跟踪采样率 `0`–`1`。
- `otel.flushIntervalMs`：定期遥测刷新间隔，单位为毫秒。
- `otel.captureContent`：选择启用对 OTEL span 属性的原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于最新实验性 GenAI span 提供商属性的环境开关。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI 指标使用有界语义属性。
- `OPENCLAW_OTEL_PRELOADED=1`：用于已经注册全局 OpenTelemetry SDK 的主机的环境开关。OpenClaw 随后会跳过插件自有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。
- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：在未设置匹配配置键时使用的信号专用端点环境变量。
- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。
- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含的内容（全部默认：`true`）。
---
@ -925,12 +933,12 @@ openclaw gateway --port 19001
}
```
- `channel`：npm/git 安装的发布渠道，即 `"stable"`、`"beta"` 或 `"dev"`。
- `channel`：npm/git 安装的发布渠道：`"stable"`、`"beta"` 或 `"dev"`。
- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。
- `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。
- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。
- `auto.stableJitterHours`：stable 渠道发布扩散的额外时间窗口（小时）（默认：`12`；最大：`168`）。
- `auto.betaCheckIntervalHours`：beta 渠道检查运行的频率（小时）（默认：`1`；最大：`24`）。
- `auto.stableDelayHours`：stable 渠道自动应用前的最短延迟小时数（默认：`6`；最大值：`168`）。
- `auto.stableJitterHours`：额外的 stable 渠道推出分散窗口，单位为小时（默认：`12`；最大值：`168`）。
- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率，单位为小时（默认：`1`；最大值：`24`）。
---
@ -963,23 +971,23 @@ openclaw gateway --port 19001
}
```
- `enabled`：全局 ACP 功能门控（默认：`true`；设为 `false` 可隐藏 ACP 分发和生成入口）。
- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可保留 ACP 命令可用，同时阻止执行。
- `enabled`：全局 ACP 功能门控（默认：`true`；设为 `false` 可隐藏 ACP 分派和生成入口）。
- `dispatch.enabled`：ACP 会话轮次分派的独立门控（默认：`true`）。设为 `false` 可保持 ACP 命令可用，同时阻止执行。
- `backend`：默认 ACP 运行时后端 ID（必须匹配已注册的 ACP 运行时插件）。
如果设置了 `plugins.allow`，请包含后端插件 ID（例如 `acpx`），否则内置默认插件不会加载。
- `defaultAgent`：生成时未指定显式目标时的后备 ACP 目标智能体 ID。
先安装后端插件；如果设置了 `plugins.allow`，请包含后端插件 ID（例如 `acpx`），否则 ACP 后端不会加载。
- `defaultAgent`：当生成未指定显式目标时使用的备用 ACP 目标智能体 ID。
- `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；为空表示没有额外限制。
- `maxConcurrentSessions`：可同时处于活动状态的 ACP 会话最大数量。
- `stream.coalesceIdleMs`：流式文本的空闲刷新窗口（毫秒）。
- `maxConcurrentSessions`：最大并发活动 ACP 会话数。
- `stream.coalesceIdleMs`：流式文本的空闲刷新窗口，单位为毫秒。
- `stream.maxChunkChars`：拆分流式分块投影前的最大分块大小。
- `stream.repeatSuppression`：每个轮次抑制重复的 Status/工具行（默认：`true`）。
- `stream.repeatSuppression`：按轮次抑制重复的 Status/工具行（默认：`true`）。
- `stream.deliveryMode`：`"live"` 会增量流式传输；`"final_only"` 会缓冲到轮次终止事件。
- `stream.hiddenBoundarySeparator`：隐藏工具事件后的可见文本前的分隔符（默认：`"paragraph"`）。
- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。
- `stream.maxOutputChars`：每个 ACP 轮次投影的最大助手输出字符数。
- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。
- `stream.maxSessionUpdateChars`：投影的 ACP Status/更新行的最大字符数。
- `stream.tagVisibility`：标签名称到流式事件布尔可见性覆盖的记录。
- `runtime.ttlMinutes`：ACP 会话 worker 符合清理条件前的空闲 TTL（分钟）。
- `runtime.installCommand`：引导 ACP 运行时环境时运行的可选安装命令。
- `runtime.ttlMinutes`：ACP 会话 worker 在符合清理条件前的空闲 TTL，单位为分钟。
- `runtime.installCommand`：引导 ACP 运行时环境时要运行的可选安装命令。
---
@ -996,16 +1004,16 @@ openclaw gateway --port 19001
```
- `cli.banner.taglineMode` 控制横幅标语样式：
- `"random"`（默认）：轮换的幽默/季节性标语。
- `"random"`（默认）：轮换的趣味/季节性标语。
- `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。
- `"off"`：不显示标语文本（仍会显示横幅标题/版本）。
- 如需隐藏整个横幅（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
- 若要隐藏整个横幅（不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
---
## 向导
CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数据：
由 CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数据：
```json5
{
@ -1023,15 +1031,15 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
## 身份
请参阅 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。
见 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。
---
## Bridge（旧版，已移除）
当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再属于配置架构的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以移除未知键）。
当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再是配置 schema 的一部分（验证会失败，直到移除这些键；`openclaw doctor --fix` 可以剥离未知键）。
<Accordion title="Legacy bridge config (historical reference)">
<Accordion title="旧版 bridge 配置（历史参考）">
```json
{
@ -1069,11 +1077,11 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
}
```
- `sessionRetention`：已完成的隔离 Cron 运行会话在从 `sessions.json` 裁剪前保留多长时间。也控制已归档删除的 Cron 转录的清理。默认：`24h`；设为 `false` 可禁用。
- `runLog.maxBytes`：裁剪前每个运行日志文件（`cron/runs/<jobId>.jsonl`）的最大大小。默认：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认：`2000`。
- `webhookToken`：用于 Cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不会发送 auth 标头。
- `webhook`：已弃用的旧版后备 webhook URL（http/https），仅用于仍包含 `notify: true` 的已存储任务。
- `sessionRetention`：在从 `sessions.json` 中剪除已完成的隔离 cron 运行会话前保留多长时间。也控制已归档的已删除 cron 转录的清理。默认：`24h`；设为 `false` 可禁用。
- `runLog.maxBytes`：剪除前每个运行日志文件（`cron/runs/<jobId>.jsonl`）的最大大小。默认：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志剪除时保留的最新行数。默认：`2000`。
- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不会发送认证标头。
- `webhook`：已弃用的旧版备用 webhook URL（http/https），仅用于仍包含 `notify: true` 的已存储作业。
### `cron.retry`
@ -1089,11 +1097,11 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
}
```
- `maxAttempts`：一次性任务在瞬时错误上的最大重试次数（默认：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 项）。
- `retryOn`：触发重试的错误类型，即 `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则重试所有瞬时类型。
- `maxAttempts`：一次性作业在瞬态错误上的最大重试次数（默认：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试的退避延迟数组，单位为毫秒（默认：`[30000, 60000, 300000]`；1–10 个条目）。
- `retryOn`：触发重试的错误类型：`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有瞬态类型。
仅适用于一次性 Cron 任务。重复任务使用单独的失败处理。
仅适用于一次性 cron 作业。周期性作业使用单独的失败处理。
### `cron.failureAlert`
@ -1112,11 +1120,11 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
}
```
- `enabled`：启用 Cron 任务失败提醒（默认：`false`）。
- `after`：触发提醒前的连续失败次数（正整数，最小：`1`）。
- `cooldownMs`：同一任务重复提醒之间的最小毫秒数（非负整数）。
- `includeSkipped`：将连续跳过的运行计入提醒阈值（默认：`false`）。跳过的运行会单独跟踪，不会影响执行错误退避。
- `mode`：投递模式，即 `"announce"` 通过渠道消息发送；`"webhook"` 发布到已配置的 webhook。
- `enabled`：启用 cron 作业的失败提醒（默认：`false`）。
- `after`：触发提醒前的连续失败次数（正整数，最小值：`1`）。
- `cooldownMs`：同一作业重复提醒之间的最小毫秒数（非负整数）。
- `includeSkipped`：将连续跳过的运行计入提醒阈值（默认：`false`）。跳过的运行会单独跟踪，且不影响执行错误退避。
- `mode`：投递模式：`"announce"` 通过渠道消息发送；`"webhook"` 发布到已配置的 webhook。
- `accountId`：用于限定提醒投递范围的可选账号或渠道 ID。
### `cron.failureDestination`
@ -1134,16 +1142,16 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
}
```
- 所有作业的 cron 失败通知的默认目标位置。
- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认为 `"announce"`。
- `channel`：用于公告投递的渠道覆盖项。`"last"` 会复用最后已知的投递渠道。
- `to`：显式公告目标或 webhook URL。webhook 模式必填。
- 所有作业的 cron 失败通知默认目标。
- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。
- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用最后已知的投递渠道。
- `to`：显式 announce 目标或 webhook URL。webhook 模式必需。
- `accountId`：用于投递的可选账号覆盖项。
- 单个作业的 `delivery.failureDestination` 会覆盖此全局默认值。
- 当既未设置全局失败目标位置，也未设置单个作业失败目标位置时，已经通过 `announce` 投递的作业会在失败时回退到该主要公告目标。
- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 作业，除非该作业的主要 `delivery.mode` 为 `"webhook"`。
- 当既未设置全局失败目标，也未设置单个作业失败目标时，已通过 `announce` 投递的作业会在失败时回退到其主要 announce 目标。
- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 作业，除非作业的主要 `delivery.mode` 为 `"webhook"`。
参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)跟踪。
请参阅 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)跟踪。
---
@ -1151,34 +1159,34 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
在 `tools.media.models[].args` 中展开的模板占位符：
| 变量 | 描述 |
| ------------------ | ------------------------------------------------- |
| `{{Body}}` | 完整的入站消息正文 |
| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） |
| `{{BodyStripped}}` | 移除群组提及后的正文 |
| `{{From}}` | 发送者标识符 |
| `{{To}}` | 目标标识符 |
| `{{MessageSid}}` | 渠道消息 ID |
| `{{SessionId}}` | 当前会话 UUID |
| `{{IsNewSession}}` | 创建新会话时为 `"true"` |
| `{{MediaUrl}}` | 入站媒体伪 URL |
| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（图片/音频/文档/……） |
| `{{Transcript}}` | 音频转录文本 |
| `{{Prompt}}` | CLI 条目的已解析媒体提示词 |
| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 |
| `{{ChatType}}` | `"direct"` 或 `"group"` |
| `{{GroupSubject}}` | 群组主题（尽力而为） |
| `{{GroupMembers}}` | 群组成员预览（尽力而为） |
| `{{SenderName}}` | 发送者显示名称（尽力而为） |
| `{{SenderE164}}` | 发送者电话号码（尽力而为） |
| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） |
| 变量 | 描述 |
| ------------------ | ----------------------------------------- |
| `{{Body}}` | 完整的入站消息正文 |
| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） |
| `{{BodyStripped}}` | 去除群组提及后的正文 |
| `{{From}}` | 发送者标识符 |
| `{{To}}` | 目标标识符 |
| `{{MessageSid}}` | 渠道消息 ID |
| `{{SessionId}}` | 当前会话 UUID |
| `{{IsNewSession}}` | 创建新会话时为 `"true"` |
| `{{MediaUrl}}` | 入站媒体伪 URL |
| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（图像/音频/文档/…） |
| `{{Transcript}}` | 音频转录文本 |
| `{{Prompt}}` | CLI 条目的已解析媒体提示词 |
| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 |
| `{{ChatType}}` | `"direct"` 或 `"group"` |
| `{{GroupSubject}}` | 群组主题（尽力而为） |
| `{{GroupMembers}}` | 群组成员预览（尽力而为） |
| `{{SenderName}}` | 发送者显示名称（尽力而为） |
| `{{SenderE164}}` | 发送者电话号码（尽力而为） |
| `{{Provider}}` | 提供商提示（WhatsApp、Telegram、Discord 等） |
---
## 配置包含（`$include`）
## 配置包含项（`$include`）
将配置拆分到多个文件：
将配置拆分为多个文件：
```json5
// ~/.openclaw/openclaw.json
@ -1194,12 +1202,12 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
**合并行为：**
- 单个文件：替换包含它的对象。
- 文件数组：按顺序深度合并（后者覆盖前者）。
- 文件数组：按顺序深度合并（后面的覆盖前面的）。
- 同级键：在包含项之后合并（覆盖已包含的值）。
- 嵌套包含：最多 10 层。
- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。绝对路径/`../` 形式仅在仍解析到该边界内时才允许。
- OpenClaw 拥有的写入如果只更改一个由单文件包含支持的顶层部分，会写入该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。
- 根包含、包含数组以及带有同级覆盖项的包含，对 OpenClaw 拥有的写入是只读的；这些写入会失败关闭，而不是展平配置。
- 嵌套包含项：最深 10 层。
- 路径：相对于包含它的文件解析，但必须保持在顶级配置目录（`openclaw.json` 的 `dirname`）内。绝对路径/`../` 形式仅在最终仍解析到该边界内时才允许。
- OpenClaw 拥有的写入如果只更改单文件包含项支持的一个顶级部分，会透传写入到该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。
- 根包含项、包含项数组，以及带有同级覆盖项的包含项，对 OpenClaw 拥有的写入是只读的；这些写入会失败关闭，而不是扁平化配置。
- 错误：针对缺失文件、解析错误和循环包含提供清晰消息。
---

142
docs/zh-CN/gateway/opentelemetry.md
View File

@ -1,30 +1,36 @@
---
read_when:
- 你想将 OpenClaw 模型使用情况、消息流或会话指标发送到 OpenTelemetry 收集器
- 你正在将跟踪、指标或日志接入 Grafana、Datadog、Honeycomb、New Relic、Tempo 或其他 OTLP 后端
- 你想将 OpenClaw 模型使用情况、消息流或会话指标发送到 OpenTelemetry 采集器
- 你正在将追踪、指标或日志接入 Grafana、Datadog、Honeycomb、New Relic、Tempo 或其他 OTLP 后端
- 你需要确切的指标名称、跨度名称或属性结构，才能构建仪表板或告警
summary: 通过 diagnostics-otel 插件（OTLP/HTTP）将 OpenClaw 诊断信息导出到任意 OpenTelemetry 收集器
summary: 通过 diagnostics-otel 插件（OTLP/HTTP）将 OpenClaw 诊断数据导出到任何 OpenTelemetry 收集器
title: OpenTelemetry 导出
x-i18n:
generated_at: "2026-05-01T23:59:34Z"
generated_at: "2026-05-02T07:52:25Z"
model: gpt-5.5
provider: openai
source_hash: be58bb48f06e72b5b08d21bf37c0dcc218be8e4c0030b074523794be01f2611a
source_hash: a0aed4ca8818d3bd1f5461fb58fbbe5c0d3ed1262cac506c60ee326800d98e1b
source_path: gateway/opentelemetry.md
workflow: 16
---
OpenClaw 通过内置的 `diagnostics-otel` 插件使用 **OTLP/HTTP（protobuf）** 导出诊断数据。任何接受 OTLP/HTTP 的收集器或后端都无需更改代码即可工作。关于本地文件日志以及如何读取它们，请参阅 [日志](/zh-CN/logging)。
OpenClaw 通过官方 `diagnostics-otel` 插件导出诊断数据，使用 **OTLP/HTTP（protobuf）**。任何接受 OTLP/HTTP 的收集器或后端都无需修改代码即可工作。关于本地文件日志以及如何读取它们，请参阅 [Logging](/zh-CN/logging)。
## 其工作方式
## 工作方式
- **诊断事件** 是结构化的进程内记录，由 Gateway 网关和内置插件为模型运行、消息流、会话、队列和 exec 发出。
- **`diagnostics-otel` 插件** 订阅这些事件，并通过 OTLP/HTTP 将其作为 OpenTelemetry **指标**、**追踪** 和 **日志** 导出。
- 当提供商传输层接受自定义标头时，**提供商调用** 会从 OpenClaw 的受信任模型调用 span 上下文接收 W3C `traceparent` 标头。插件发出的追踪上下文不会传播。
- 只有在诊断面和插件都启用时，导出器才会附加，因此默认情况下进程内成本接近于零。
- **诊断事件** 是由 Gateway 网关和内置插件为模型运行、消息流、会话、队列和 exec 发出的结构化进程内记录。
- **`diagnostics-otel` 插件** 订阅这些事件，并通过 OTLP/HTTP 将它们导出为 OpenTelemetry **指标**、**链路追踪** 和 **日志**。
- 当提供商传输层接受自定义标头时，**提供商调用** 会从 OpenClaw 可信的模型调用 span 上下文接收 W3C `traceparent` 标头。插件发出的 trace 上下文不会被传播。
- 仅当诊断接口和插件都启用时，导出器才会附加，因此默认情况下进程内成本接近零。
## 快速开始
对于打包安装，请先安装插件：
```bash
openclaw plugins install @openclaw/diagnostics-otel
```
```json5
{
plugins: {
@ -62,13 +68,13 @@ openclaw plugins enable diagnostics-otel
## 导出的信号
| 信号 | 内容 |
| 信号 | 内容 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **指标** | token 用量、成本、运行持续时间、消息流、队列通道、会话状态、exec 和内存压力的计数器与直方图。 |
| **追踪** | 模型用量、模型调用、harness 生命周期、工具执行、exec、webhook/消息处理、上下文组装和工具循环的 span。 |
| **日志** | 启用 `diagnostics.otel.logs` 时，通过 OTLP 导出的结构化 `logging.file` 记录。 |
| **指标** | token 使用量、成本、运行时长、消息流、队列 lane、会话状态、exec 和内存压力的计数器与直方图。 |
| **链路追踪** | 模型使用、模型调用、harness 生命周期、工具执行、exec、webhook/消息处理、上下文组装和工具循环的 span。 |
| **日志** | 启用 `diagnostics.otel.logs` 时，通过 OTLP 导出的结构化 `logging.file` 记录。 |
可以独立切换 `traces`、`metrics` 和 `logs`。当 `diagnostics.otel.enabled` 为 true 时，这三项默认都开启。
可以分别切换 `traces`、`metrics` 和 `logs`。当 `diagnostics.otel.enabled` 为 true 时，三者默认全部开启。
## 配置参考
@ -105,42 +111,42 @@ openclaw plugins enable diagnostics-otel
### 环境变量
| 变量 | 用途 |
| 变量 | 用途 |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆盖 `diagnostics.otel.endpoint`。如果值已经包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，则按原样使用。 |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 当匹配的 `diagnostics.otel.*Endpoint` 配置键未设置时使用的信号特定端点覆盖项。信号特定配置优先于信号特定环境变量，而后者又优先于共享端点。 |
| `OTEL_SERVICE_NAME` | 覆盖 `diagnostics.otel.serviceName`。 |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆盖传输协议（目前只接受 `http/protobuf`）。 |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | 设置为 `gen_ai_latest_experimental`，以发出最新的实验性 GenAI span 属性（`gen_ai.provider.name`），而不是旧版 `gen_ai.system`。无论如何，GenAI 指标始终使用有界、低基数的语义属性。 |
| `OPENCLAW_OTEL_PRELOADED` | 当另一个 preload 或宿主进程已经注册全局 OpenTelemetry SDK 时，设置为 `1`。随后插件会跳过自己的 NodeSDK 生命周期，但仍会连接诊断监听器并遵循 `traces`/`metrics`/`logs`。 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆盖 `diagnostics.otel.endpoint`。如果该值已包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，则按原样使用。 |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 当匹配的 `diagnostics.otel.*Endpoint` 配置键未设置时，使用特定于信号的端点覆盖。特定于信号的配置优先于特定于信号的环境变量，后者优先于共享端点。 |
| `OTEL_SERVICE_NAME` | 覆盖 `diagnostics.otel.serviceName`。 |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆盖线路协议（目前仅支持 `http/protobuf`）。 |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | 设置为 `gen_ai_latest_experimental`，以发出最新的实验性 GenAI span 属性（`gen_ai.provider.name`），而不是旧版 `gen_ai.system`。无论如何，GenAI 指标始终使用有界、低基数的语义属性。 |
| `OPENCLAW_OTEL_PRELOADED` | 当另一个 preload 或宿主进程已注册全局 OpenTelemetry SDK 时，设置为 `1`。随后插件会跳过自己的 NodeSDK 生命周期，但仍会连接诊断监听器并遵循 `traces`/`metrics`/`logs`。 |
## 隐私与内容捕获
默认情况下不会导出原始模型/工具内容。Span 携带有界标识符（渠道、提供商、模型、错误类别、仅哈希的请求 ID），并且绝不包含提示词文本、响应文本、工具输入、工具输出或会话键。
默认情况下，原始模型/工具内容**不会**被导出。Span 携带有界标识符（渠道、提供商、模型、错误类别、仅哈希请求 ID），绝不会包含提示词文本、响应文本、工具输入、工具输出或会话键。
出站模型请求可能包含 W3C `traceparent` 标头。该标头只会从 OpenClaw 拥有的、用于活跃模型调用的诊断追踪上下文生成。已有的调用方提供的 `traceparent` 标头会被替换，因此插件或自定义提供商选项无法伪造跨服务追踪祖先关系。
出站模型请求可能包含 W3C `traceparent` 标头。该标头只会从 OpenClaw 拥有的、活动模型调用的诊断 trace 上下文生成。现有调用方提供的 `traceparent` 标头会被替换，因此插件或自定义提供商选项无法伪造跨服务 trace 祖先关系。
仅当你的收集器和保留策略已获准处理提示词、响应、工具或系统提示词文本时，才将 `diagnostics.otel.captureContent.*` 设置为 `true`。每个子键都独立选择启用：
仅当你的收集器和保留策略已获准处理提示词、响应、工具或系统提示词文本时，才将 `diagnostics.otel.captureContent.*` 设置为 `true`。每个子键都需要单独选择启用：
- `inputMessages` — 用户提示词内容。
- `outputMessages` — 模型响应内容。
- `toolInputs` — 工具参数载荷。
- `toolOutputs` — 工具结果载荷。
- `toolInputs` — 工具参数负载。
- `toolOutputs` — 工具结果负载。
- `systemPrompt` — 组装后的系统/开发者提示词。
启用任何子键时，模型和工具 span 会仅针对该类别获得有界、已脱敏的 `openclaw.content.*` 属性。
启用任一子键时，模型和工具 span 只会为该类别获得有界且经过脱敏的 `openclaw.content.*` 属性。
## 采样与刷新
## 采样和刷新
- **追踪：** `diagnostics.otel.sampleRate`（仅根 span，`0.0` 丢弃全部，`1.0` 保留全部）。
- **链路追踪：** `diagnostics.otel.sampleRate`（仅根 span，`0.0` 丢弃全部，`1.0` 保留全部）。
- **指标：** `diagnostics.otel.flushIntervalMs`（最小值 `1000`）。
- **日志：** OTLP 日志遵循 `logging.level`（文件日志级别）。它们使用诊断日志记录脱敏路径，而不是控制台格式化。高容量安装应优先使用 OTLP 收集器采样/过滤，而不是本地采样。
- **文件日志关联：** 当日志调用携带有效诊断追踪上下文时，JSONL 文件日志会包含顶层 `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，这让日志处理器可以将本地日志行与导出的 span 连接起来。
- **请求关联：** Gateway 网关 HTTP 请求和 WebSocket 帧会创建内部请求追踪作用域。该作用域内的日志和诊断事件默认继承请求追踪，而智能体运行和模型调用 span 会作为子项创建，因此提供商 `traceparent` 标头会保留在同一条追踪上。
- **文件日志关联：** 当日志调用携带有效的诊断 trace 上下文时，JSONL 文件日志会包含顶层 `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，这让日志处理器可以将本地日志行与导出的 span 关联起来。
- **请求关联：** Gateway 网关 HTTP 请求和 WebSocket 帧会创建内部请求 trace 作用域。该作用域内的日志和诊断事件默认继承请求 trace，而智能体运行和模型调用 span 会作为子级创建，因此提供商 `traceparent` 标头会保持在同一 trace 上。
## 导出的指标
### 模型用量
### 模型使用情况
- `openclaw.tokens`（计数器，属性：`openclaw.token`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.agent`）
- `openclaw.cost.usd`（计数器，属性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
@ -148,10 +154,10 @@ openclaw plugins enable diagnostics-otel
- `openclaw.context.tokens`（直方图，属性：`openclaw.context`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
- `gen_ai.client.token.usage`（直方图，GenAI 语义约定指标，属性：`gen_ai.token.type` = `input`/`output`、`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`）
- `gen_ai.client.operation.duration`（直方图，秒，GenAI 语义约定指标，属性：`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`，可选 `error.type`）
- `openclaw.model_call.duration_ms`（直方图，属性：`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`，以及分类错误上的 `openclaw.errorCategory` 和 `openclaw.failureKind`）
- `openclaw.model_call.request_bytes`（直方图，最终模型请求载荷的 UTF-8 字节大小；不含原始载荷内容）
- `openclaw.model_call.response_bytes`（直方图，流式模型响应事件的 UTF-8 字节大小；不含原始响应内容）
- `openclaw.model_call.time_to_first_byte_ms`（直方图，首个流式响应事件之前经过的时间）
- `openclaw.model_call.duration_ms`（直方图，属性：`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`，分类错误上还包含 `openclaw.errorCategory` 和 `openclaw.failureKind`）
- `openclaw.model_call.request_bytes`（直方图，最终模型请求负载的 UTF-8 字节大小；不包含原始负载内容）
- `openclaw.model_call.response_bytes`（直方图，流式模型响应事件的 UTF-8 字节大小；不包含原始响应内容）
- `openclaw.model_call.time_to_first_byte_ms`（直方图，首次流式响应事件前经过的时间）
### 消息流
@ -171,21 +177,21 @@ openclaw plugins enable diagnostics-otel
- `openclaw.queue.depth`（直方图，属性：`openclaw.lane` 或 `openclaw.channel=heartbeat`）
- `openclaw.queue.wait_ms`（直方图，属性：`openclaw.lane`）
- `openclaw.session.state`（计数器，属性：`openclaw.state`、`openclaw.reason`）
- `openclaw.session.stuck`（计数器，属性：`openclaw.state`；仅为没有活跃工作的陈旧会话记账发出）
- `openclaw.session.stuck_age_ms`（直方图，属性：`openclaw.state`；仅为没有活跃工作的陈旧会话记账发出）
- `openclaw.session.stuck`（计数器，属性：`openclaw.state`；仅在没有活动工作的过期会话簿记中发出）
- `openclaw.session.stuck_age_ms`（直方图，属性：`openclaw.state`；仅在没有活动工作的过期会话簿记中发出）
- `openclaw.run.attempt`（计数器，属性：`openclaw.attempt`）
### 会话活跃度遥测
### 会话活跃性遥测
`diagnostics.stuckSessionWarnMs` 是会话活跃度诊断的无进展时长阈值。当 OpenClaw 观察到回复、工具、Status、分块或 ACP 运行时进展时，`processing` 会话不会朝此阈值老化。Typing keepalive 不计为进展，因此仍可检测到静默的模型或 harness。
`diagnostics.stuckSessionWarnMs` 是用于会话活跃性诊断的无进展时长阈值。当 OpenClaw 观察到回复、工具、Status、分块或 ACP 运行时进展时，`processing` 会话不会朝该阈值累积时长。Typing keepalive 不计为进展，因此静默模型或 harness 仍可被检测到。
OpenClaw 会按其仍能观察到的工作对会话进行分类：
OpenClaw 根据仍可观察到的工作对会话进行分类：
- `session.long_running`：活跃的嵌入式工作、模型调用或工具调用仍在推进。
- `session.stalled`：存在活跃工作，但活跃运行近期未报告进展。
- `session.stuck`：没有活跃工作的陈旧会话簿记。这是唯一会释放受影响会话通道的存活性分类。
- `session.long_running`：活动的嵌入式工作、模型调用或工具调用仍在推进。
- `session.stalled`：存在活动工作，但活动运行最近没有报告进展。
- `session.stuck`：没有活动工作的过期会话账本记录。这是唯一会释放受影响会话队列通道的活跃性分类。
只有 `session.stuck` 会发出 `openclaw.session.stuck` 计数器、`openclaw.session.stuck_age_ms` 直方图和 `openclaw.session.stuck` span。重复的 `session.stuck` 诊断会在会话保持不变时退避，因此仪表板应针对持续增加发出告警，而不是针对每个 Heartbeat tick 告警。有关配置开关和默认值，请参阅[配置参考](/zh-CN/gateway/configuration-reference#diagnostics)。
只有 `session.stuck` 会发出 `openclaw.session.stuck` 计数器、`openclaw.session.stuck_age_ms` 直方图和 `openclaw.session.stuck` 追踪跨度。当会话保持不变时，重复的 `session.stuck` 诊断会退避，因此仪表板应针对持续增长发出警报，而不是针对每个心跳周期发出警报。关于配置开关和默认值，请参阅[配置参考](/zh-CN/gateway/configuration-reference#diagnostics)。
### Harness 生命周期
@ -203,25 +209,25 @@ OpenClaw 会按其仍能观察到的工作对会话进行分类：
- `openclaw.tool.loop.iterations`（计数器，属性：`openclaw.toolName`、`openclaw.outcome`）
- `openclaw.tool.loop.duration_ms`（直方图，属性：`openclaw.toolName`、`openclaw.outcome`）
## 导出的 span
## 导出的追踪跨度
- `openclaw.model.usage`
- `openclaw.channel`、`openclaw.provider`、`openclaw.model`
- `openclaw.tokens.*`（input/output/cache_read/cache_write/total）
- 默认使用 `gen_ai.system`，或在启用最新 GenAI 语义约定时使用 `gen_ai.provider.name`
- 默认使用 `gen_ai.system`，或在选择使用最新 GenAI 语义约定时使用 `gen_ai.provider.name`
- `gen_ai.request.model`、`gen_ai.operation.name`、`gen_ai.usage.*`
- `openclaw.run`
- `openclaw.outcome`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.errorCategory`
- `openclaw.model.call`
- 默认使用 `gen_ai.system`，或在启用最新 GenAI 语义约定时使用 `gen_ai.provider.name`
- 默认使用 `gen_ai.system`，或在选择使用最新 GenAI 语义约定时使用 `gen_ai.provider.name`
- `gen_ai.request.model`、`gen_ai.operation.name`、`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`
- 错误时的 `openclaw.errorCategory` 和可选的 `openclaw.failureKind`
- 错误时的 `openclaw.errorCategory` 和可选 `openclaw.failureKind`
- `openclaw.model_call.request_bytes`、`openclaw.model_call.response_bytes`、`openclaw.model_call.time_to_first_byte_ms`
- `openclaw.provider.request_id_hash`（上游提供商请求 ID 的有界 SHA 哈希；不会导出原始 ID）
- `openclaw.provider.request_id_hash`（基于上游提供商请求 ID 的有界 SHA 哈希；不会导出原始 ID）
- `openclaw.harness.run`
- `openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`、`openclaw.provider`、`openclaw.model`、`openclaw.channel`
- 完成时：`openclaw.harness.result_classification`、`openclaw.harness.yield_detected`、`openclaw.harness.items.started`、`openclaw.harness.items.completed`、`openclaw.harness.items.active`
- 出错时：`openclaw.harness.phase`、`openclaw.errorCategory`、可选的 `openclaw.harness.cleanup_failed`
- 错误时：`openclaw.harness.phase`、`openclaw.errorCategory`、可选 `openclaw.harness.cleanup_failed`
- `openclaw.tool.execution`
- `gen_ai.tool.name`、`openclaw.toolName`、`openclaw.errorCategory`、`openclaw.tool.params.*`
- `openclaw.exec`
@ -237,21 +243,21 @@ OpenClaw 会按其仍能观察到的工作对会话进行分类：
- `openclaw.session.stuck`
- `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth`
- `openclaw.context.assembled`
- `openclaw.prompt.size`、`openclaw.history.size`、`openclaw.context.tokens`、`openclaw.errorCategory`（不包含提示、历史记录、响应或会话键内容）
- `openclaw.prompt.size`、`openclaw.history.size`、`openclaw.context.tokens`、`openclaw.errorCategory`（不包含提示词、历史、响应或会话键内容）
- `openclaw.tool.loop`
- `openclaw.toolName`、`openclaw.outcome`、`openclaw.iterations`、`openclaw.errorCategory`（不包含循环消息、参数或工具输出）
- `openclaw.memory.pressure`
- `openclaw.memory.level`、`openclaw.memory.heap_used_bytes`、`openclaw.memory.rss_bytes`
显式启用内容捕获时，模型和工具 span 还可以为你选择加入的特定内容类别包含有界且已脱敏的 `openclaw.content.*` 属性。
显式启用内容捕获时，模型和工具追踪跨度还可以包含针对你选择加入的特定内容类别的有界、已脱敏 `openclaw.content.*` 属性。
## 诊断事件目录
下面的事件为上述指标和 span 提供支撑。插件也可以在不导出 OTLP 的情况下直接订阅它们。
以下事件支撑上面的指标和追踪跨度。插件也可以直接订阅它们，而无需 OTLP 导出。
**模型用量**
- `model.usage` — token、成本、持续时间、上下文、提供商/模型/渠道、会话 ID。`usage` 是用于成本和遥测的提供商/轮次记账；`context.used` 是当前提示/上下文快照，在涉及缓存输入或工具循环调用时，可能低于提供商 `usage.total`。
- `model.usage` — 令牌、费用、耗时、上下文、提供商/模型/渠道、会话 ID。`usage` 是提供商/轮次层面的费用和遥测统计；`context.used` 是当前提示词/上下文快照，并且在涉及缓存输入或工具循环调用时，可能低于提供商的 `usage.total`。
**消息流**
@ -264,19 +270,19 @@ OpenClaw 会按其仍能观察到的工作对会话进行分类：
- `queue.lane.enqueue` / `queue.lane.dequeue`
- `session.state` / `session.long_running` / `session.stalled` / `session.stuck`
- `run.attempt` / `run.progress`
- `diagnostic.heartbeat`（聚合计数器：webhook/队列/会话）
- `diagnostic.heartbeat`（聚合计数器：webhooks/queue/session）
**Harness 生命周期**
- `harness.run.started` / `harness.run.completed` / `harness.run.error` — Agent harness 的每次运行生命周期。包含 `harnessId`、可选的 `pluginId`、提供商/模型/渠道，以及运行 ID。完成时会添加 `durationMs`、`outcome`、可选的 `resultClassification`、`yieldDetected` 和 `itemLifecycle` 计数。错误会添加 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory` 和可选的 `cleanupFailed`。
- `harness.run.started` / `harness.run.completed` / `harness.run.error` — Agent harness 的每次运行生命周期。包含 `harnessId`、可选 `pluginId`、提供商/模型/渠道以及运行 ID。完成时会添加 `durationMs`、`outcome`、可选 `resultClassification`、`yieldDetected` 和 `itemLifecycle` 计数。错误会添加 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory` 和可选 `cleanupFailed`。
**Exec**
- `exec.process.completed` — 终端结果、持续时间、目标、模式、退出码和失败类型。不包含命令文本和工作目录。
- `exec.process.completed` — 终端结果、耗时、目标、模式、退出代码和失败类型。不包含命令文本和工作目录。
## 没有导出器
## 没有导出器时
你可以在不运行 `diagnostics-otel` 的情况下，让诊断事件可供插件或自定义接收端使用：
你可以在不运行 `diagnostics-otel` 的情况下，让诊断事件可供插件或自定义接收器使用：
```json5
{
@ -284,7 +290,7 @@ OpenClaw 会按其仍能观察到的工作对会话进行分类：
}
```
如需在不提高 `logging.level` 的情况下获得有针对性的调试输出，请使用诊断标志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）：
如需在不提高 `logging.level` 的情况下输出有针对性的调试信息，请使用诊断标志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）：
```json5
{
@ -292,7 +298,7 @@ OpenClaw 会按其仍能观察到的工作对会话进行分类：
}
```
也可以作为一次性的环境变量覆盖：
或作为一次性环境覆盖：
```bash
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
@ -308,12 +314,12 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
}
```
你也可以将 `diagnostics-otel` 排除在 `plugins.allow` 之外，或运行 `openclaw plugins disable diagnostics-otel`。
你也可以将 `diagnostics-otel` 从 `plugins.allow` 中移除，或运行 `openclaw plugins disable diagnostics-otel`。
## 相关
- [日志记录](/zh-CN/logging) — 文件日志、控制台输出、CLI 跟踪，以及 Control UI Logs 标签页
- [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获
- [诊断标志](/zh-CN/diagnostics/flags) — 定向调试日志标志
- [诊断导出](/zh-CN/gateway/diagnostics) — 操作者支持包工具（独立于 OTEL 导出）
- [配置参考](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考
- [诊断标志](/zh-CN/diagnostics/flags) — 有针对性的调试日志标志
- [诊断导出](/zh-CN/gateway/diagnostics) — 操作员支持包工具（与 OTEL 导出分开）
- [配置参考](/zh-CN/gateway/configuration-reference#diagnostics) — 完整 `diagnostics.*` 字段参考

368
docs/zh-CN/help/testing-live.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 正在运行真实模型矩阵 / CLI 后端 / ACP / media-provider 冒烟测试
- 运行真实模型矩阵 / CLI 后端 / ACP / media-provider 冒烟测试
- 调试实时测试凭证解析
- 添加新的提供商特定实时测试
- 添加新的特定于提供商的实时测试
sidebarTitle: Live tests
summary: 真实环境（会访问网络的）测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证
title: 测试：真实环境套件
summary: 在线（会访问网络的）测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证
title: 测试：实时测试套件
x-i18n:
generated_at: "2026-05-02T01:45:19Z"
generated_at: "2026-05-02T07:52:30Z"
model: gpt-5.5
provider: openai
source_hash: ce8bd75ee7837b48e6ba1d888d281ee053fc13bdcf0907baddeb78ebcbbef31c
source_hash: 2268f20ce5c0bbee8bf610938851fe529f5e21fa31fe08a70400df94e9241cc3
source_path: help/testing-live.md
workflow: 16
---
快速开始、QA 运行器、单元/集成套件和 Docker 流程请参见
[测试](/zh-CN/help/testing)。本页介绍 **实网**（会访问网络的）测试套件：模型矩阵、CLI 后端、ACP、媒体提供商实网测试，以及凭证处理。
有关快速开始、QA 运行器、单元/集成测试套件和 Docker 流程，请参见
[测试](/zh-CN/help/testing)。本页涵盖**实时**（会访问网络的）测试套件：模型矩阵、CLI 后端、ACP 和媒体提供商实时测试，以及凭证处理。
## 实网：本地配置文件冒烟命令
## 实时：本地 profile 冒烟命令
在临时实网检查之前先 source `~/.profile`，这样提供商密钥和本地工具路径会与你的 shell 匹配：
在临时实时检查前 source `~/.profile`，以便提供商密钥和本地工具路径与你的 shell 匹配：
```bash
source ~/.profile
@ -34,102 +34,102 @@ pnpm openclaw infer tts convert --local --json \
--output /tmp/openclaw-live-smoke.mp3
```
安全语音呼叫就绪性冒烟测试：
安全语音通话就绪冒烟测试：
```bash
pnpm openclaw voicecall setup --json
pnpm openclaw voicecall smoke --to "+15555550123"
```
`voicecall smoke` 是一次试运行，除非同时传入 `--yes`。只有在你明确想发起真实通知呼叫时才使用 `--yes`。对于 Twilio、Telnyx 和 Plivo，成功的就绪性检查需要一个公开 webhook URL；按设计会拒绝仅本地的 loopback/private 回退。
除非同时带有 `--yes`，否则 `voicecall smoke` 是一次空运行。只有在你有意发起真实通知通话时才使用 `--yes`。对于 Twilio、Telnyx 和 Plivo，成功的就绪检查需要一个公开 webhook URL；local loopback/私有回退按设计会被拒绝。
## 实网：Android 节点能力扫描
## 实时：Android 节点能力扫描
- 测试：`src/gateway/android-node.capabilities.live.test.ts`
- 脚本：`pnpm android:test:integration`
- 目标：调用已连接 Android 节点**当前公开声明的每个命令**，并断言命令契约行为。
- 目标：调用已连接 Android 节点**当前宣告的每个命令**，并断言命令契约行为。
- 范围：
- 有前置条件的手动设置（该套件不会安装/运行/配对应用）。
- 针对选定 Android 节点逐命令验证 Gateway 网关 `node.invoke`。
- 必需的前置设置：
- 带前置条件的手动设置（该套件不会安装/运行/配对应用）。
- 对选定 Android 节点逐命令执行 Gateway 网关 `node.invoke` 验证。
- 必需的预先设置：
- Android 应用已连接并配对到 Gateway 网关。
- 应用保持在前台。
- 为你期望通过的能力授予权限/采集同意。
- 已授予你预期会通过的能力所需的权限/捕获同意。
- 可选目标覆盖：
- `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。
- 完整 Android 设置详情：[Android 应用](/zh-CN/platforms/android)
## 实网：模型冒烟测试（配置文件密钥）
## 实时：模型冒烟测试（profile 密钥）
实网测试分为两层，便于隔离故障：
实时测试拆分为两层，便于隔离故障：
- “直接模型”告诉我们，使用给定密钥时该提供商/模型是否完全能回答。
- “Gateway 网关冒烟测试”告诉我们，该模型的完整 Gateway 网关+智能体管线是否正常工作（会话、历史、工具、沙箱策略等）。
- “直接模型”会告诉我们给定密钥下提供商/模型本身是否能回答。
- “Gateway 网关冒烟测试”会告诉我们该模型的完整 Gateway 网关 + agent 管道是否可用（会话、历史记录、工具、沙箱策略等）。
### 第 1 层：直接模型补全（无 Gateway 网关）
- 测试：`src/agents/models.profiles.live.test.ts`
- 目标：
- 枚举发现的模型
- 使用 `getApiKeyForModel` 选择你有凭证的模型
- 对每个模型运行一次小型补全（以及在需要时运行定向回归）
- 枚举已发现的模型
- 使用 `getApiKeyForModel` 选择你拥有凭证的模型
- 对每个模型运行一次小型补全（并在需要时运行定向回归）
- 启用方式：
- `pnpm test:live`（或直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）才会实际运行此套件；否则它会跳过，以便让 `pnpm test:live` 聚焦在 Gateway 网关冒烟测试上
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，作为 modern 的别名）才会实际运行此套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试
- 选择模型的方式：
- `OPENCLAW_LIVE_MODELS=modern` 运行现代允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
- `OPENCLAW_LIVE_MODELS=all` 是现代允许列表的别名
- 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."`（逗号分隔允许列表）
- Modern/all 扫描默认使用精选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可进行穷尽式现代扫描，或设置正数作为更小上限。
- 穷尽式扫描使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS` 作为整个直接模型测试的超时时间。默认：60 分钟。
- Modern/all 扫描默认使用经过策划的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可进行详尽的 modern 扫描，或设置正数作为更小的上限。
- 详尽扫描使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS` 作为整个直接模型测试超时时间。默认值：60 分钟。
- 直接模型探测默认以 20 路并行运行；设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY` 可覆盖。
- 选择提供商的方式：
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔允许列表）
- 密钥来源：
- 默认：配置文件存储和 env 回退
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制仅使用**配置文件存储**
- 默认：profile 存储和环境变量回退
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以强制**仅使用 profile 存储**
- 存在原因：
- 将“提供商 API 损坏/密钥无效”与“Gateway 网关智能体管线损坏”区分开
- 包含小型、隔离的回归（示例：OpenAI Responses/Codex Responses reasoning replay + 工具调用流程）
- 将“提供商 API 损坏/密钥无效”与“Gateway 网关 agent 管道损坏”分离
- 包含小型、隔离的回归测试（示例：OpenAI Responses/Codex Responses 推理重放 + 工具调用流程）
### 第 2 层：Gateway 网关 + 开发智能体冒烟测试（“@openclaw”实际执行的内容）
### 第 2 层：Gateway 网关 + 开发 agent 冒烟测试（“@openclaw” 实际执行的内容）
- 测试：`src/gateway/gateway-models.profiles.live.test.ts`
- 目标：
- 启动一个进程内 Gateway 网关
- 启动进程内 Gateway 网关
- 创建/修补一个 `agent:dev:*` 会话（每次运行覆盖模型）
- 迭代带密钥的模型并断言：
- 迭代有密钥的模型并断言：
- “有意义”的响应（无工具）
- 真实工具调用可工作（读取探测）
- 可选额外工具探测（exec+read 探测）
- OpenAI 回归路径（仅工具调用 → 后续追问）持续工作
- 真实工具调用可用（读取探测）
- 可选的额外工具探测（执行 + 读取探测）
- OpenAI 回归路径（仅工具调用 → 后续回合）持续可用
- 探测详情（便于你快速解释故障）：
- `read` 探测：测试在工作区写入一个 nonce 文件，并要求智能体 `read` 它，然后回显该 nonce。
- `exec+read` 探测：测试要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 回来。
- 图片探测：测试附加一张生成的 PNG（cat + 随机代码），并期望模型返回 `cat <CODE>`。
- `read` 探测：测试在工作区写入一个 nonce 文件，并要求 agent `read` 它并回显 nonce。
- `exec+read` 探测：测试要求 agent 通过 `exec` 将 nonce 写入临时文件，然后再 `read` 读回。
- 图像探测：测试附加一个生成的 PNG（cat + 随机代码），并期望模型返回 `cat <CODE>`。
- 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。
- 启用方式：
- `pnpm test:live`（或直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
- 选择模型的方式：
- 默认：现代允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代允许列表的别名
- 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）来缩小范围
- Modern/all Gateway 网关扫描默认使用精选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可进行穷尽式现代扫描，或设置正数作为更小上限。
- 选择提供商的方式（避免“OpenRouter 全部模型”）：
- 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）以缩小范围
- Modern/all Gateway 网关扫描默认使用经过策划的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可进行详尽的 modern 扫描，或设置正数作为更小的上限。
- 选择提供商的方式（避免“OpenRouter 全部内容”）：
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔允许列表）
- 工具 + 图片探测在此实网测试中始终开启：
- `read` 探测 + `exec+read` 探测（工具压力测试）
- 当模型声明支持图片输入时运行图片探测
- 工具 + 图像探测在此实时测试中始终启用：
- `read` 探测 + `exec+read` 探测（工具压力）
- 当模型宣告支持图像输入时运行图像探测
- 流程（高层）：
- 测试生成一张带有 “CAT” + 随机代码的小 PNG（`src/gateway/live-image-probe.ts`）
- 通过 `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]` 发送它
- Gateway 网关将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
- 嵌入式智能体将多模态用户消息转发给模型
- 断言：回复包含 `cat` + 该代码（OCR 容错：允许小错误）
- 测试生成带有“CAT”+ 随机代码的小型 PNG（`src/gateway/live-image-probe.ts`）
- 通过 `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]` 发送
- Gateway 网关将附件解析到 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
- 嵌入式 agent 将多模态用户消息转发给模型
- 断言：回复包含 `cat` + 该代码（OCR 容错：允许轻微错误）
<Tip>
要查看你这台机器上可测试的内容（以及精确的 `provider/model` id），请运行：
要查看你的机器上可以测试什么（以及精确的 `provider/model` ID），请运行：
```bash
openclaw models list
@ -138,27 +138,27 @@ openclaw models list --json
</Tip>
## 实网：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI）
## 实时：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI）
- 测试：`src/gateway/gateway-cli-backend.live.test.ts`
- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体管线，且不触碰你的默认配置。
- 后端特定的冒烟测试默认值位于所属插件的 `cli-backend.ts` 定义中。
- 目标：使用本地 CLI 后端验证 Gateway 网关 + agent 管道，而不触碰你的默认配置。
- 后端专用冒烟默认值位于所属插件的 `cli-backend.ts` 定义中。
- 启用：
- `pnpm test:live`（或直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
- `OPENCLAW_LIVE_CLI_BACKEND=1`
- 默认值：
- 默认提供商/模型：`claude-cli/claude-sonnet-4-6`
- 命令/参数/图片行为来自所属 CLI 后端插件元数据。
- 命令/参数/图像行为来自所属 CLI 后端插件元数据。
- 覆盖（可选）：
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图片附件（路径会注入到提示中）。Docker 配方默认关闭此项，除非明确请求。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 将图片文件路径作为 CLI 参数传递，而不是提示注入。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）控制设置 `IMAGE_ARG` 时图片参数的传递方式。
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮并验证恢复流程。
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` 在所选模型支持切换目标时选择加入 Claude Sonnet -> Opus 同会话连续性探测。Docker 配方默认关闭此项，以提升聚合可靠性。
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 选择加入 MCP/工具 loopback 探测。Docker 配方默认关闭此项，除非明确请求。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会注入到提示词中）。Docker 配方默认关闭此项，除非显式请求。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 将图像文件路径作为 CLI 参数传递，而不是注入提示词。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）在设置 `IMAGE_ARG` 时控制图像参数的传递方式。
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二回合并验证恢复流程。
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` 当所选模型支持切换目标时，选择启用 Claude Sonnet -> Opus 同会话连续性探测。Docker 配方为提升聚合可靠性默认关闭此项。
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 选择启用 MCP/工具 loopback 探测。Docker 配方默认关闭此项，除非显式请求。
示例：
@ -175,7 +175,7 @@ OPENCLAW_LIVE_TEST=1 \
pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts
```
这不会要求 Gemini 生成响应。它会写入 OpenClaw 提供给 Gemini 的同一组系统设置，然后运行 `gemini --debug mcp list`，以证明已保存的 `transport: "streamable-http"` 服务器会被规范化为 Gemini 的 HTTP MCP 形状，并且可以连接到本地 streamable-HTTP MCP 服务器。
这不会要求 Gemini 生成响应。它会写入 OpenClaw 提供给 Gemini 的同一套系统设置，然后运行 `gemini --debug mcp list`，以证明已保存的 `transport: "streamable-http"` 服务器会规范化为 Gemini 的 HTTP MCP 形态，并且可以连接到本地 streamable-HTTP MCP 服务器。
Docker 配方：
@ -195,27 +195,27 @@ pnpm test:docker:live-cli-backend:gemini
说明：
- Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。
- 它会在仓库 Docker 镜像中以非 root 的 `node` 用户运行实网 CLI 后端冒烟测试。
- 它从所属插件解析 CLI 冒烟测试元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 处的可写缓存前缀（默认：`~/.cache/openclaw/docker-cli-tools`）。
- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可移植的 Claude Code 订阅 OAuth，可通过带有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它会先在 Docker 中证明直接 `claude -p` 可用，然后在不保留 Anthropic API-key 环境变量的情况下运行两轮 Gateway 网关 CLI 后端对话。此订阅通道默认禁用 Claude MCP/工具和图片探测，因为 Claude 目前会将第三方应用用量路由到额外用量计费，而不是常规订阅方案限额。
- 实网 CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 运行相同的端到端流程：文本轮次、图片分类轮次，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得早先的笔记。
- 它以非 root `node` 用户在仓库 Docker 镜像内运行实时 CLI 后端冒烟测试。
- 它从所属插件解析 CLI 冒烟元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 的缓存可写前缀中（默认：`~/.cache/openclaw/docker-cli-tools`）。
- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可移植的 Claude Code 订阅 OAuth，可以通过含有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它先证明 Docker 中的直接 `claude -p` 可用，然后在不保留 Anthropic API 密钥环境变量的情况下运行两次 Gateway 网关 CLI 后端回合。此订阅通道默认禁用 Claude MCP/工具和图像探测，因为 Claude 当前会将第三方应用使用路由到额外用量计费，而不是普通订阅计划额度。
- 实时 CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 运行相同的端到端流程：文本回合、图像分类回合，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得之前的笔记。
## 实网：ACP 绑定冒烟测试（`/acp spawn ... --bind here`）
## 实时：ACP 绑定冒烟测试（`/acp spawn ... --bind here`）
- 测试：`src/gateway/gateway-acp-bind.live.test.ts`
- 目标：使用实时 ACP 智能体验证真实的 ACP 会话绑定流程：
- 目标：使用实时 ACP 智能体验证真实的 ACP 对话绑定流程：
- 发送 `/acp spawn <agent> --bind here`
- 就地绑定一个合成的消息渠道会话
- 在同一个会话中发送普通后续消息
- 验证该后续消息落入已绑定的 ACP 会话转录中
- 就地绑定一个合成的消息渠道对话
- 在同一对话中发送普通后续消息
- 验证后续消息落入已绑定的 ACP 会话 transcript
- 启用：
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
- `OPENCLAW_LIVE_ACP_BIND=1`
- 默认值：
- Docker 中的 ACP 智能体：`claude,codex,gemini`
- 直接运行 `pnpm test:live ...` 时的 ACP 智能体：`claude`
- 合成渠道：Slack 私信风格的会话上下文
- 直接运行 `pnpm test:live ...` 时使用的 ACP 智能体：`claude`
- 合成渠道：Slack 私信风格的对话上下文
- ACP 后端：`acpx`
- 覆盖项：
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
@ -231,9 +231,9 @@ pnpm test:docker:live-cli-backend:gemini
- `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`
- `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.5`
- 说明：
- 此通道使用 Gateway 网关的 `chat.send` 表面，并带有仅限管理员使用的合成来源路由字段，因此测试可以附加消息渠道上下文，而不必假装向外部投递。
- 未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会为选定的 ACP harness 智能体使用内嵌 `acpx` 插件的内置智能体注册表。
- 默认情况下，已绑定会话的 cron MCP 创建是尽力而为的，因为外部 ACP harness 可能会在绑定/图像证明通过后取消 MCP 调用；设置 `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` 可让该绑定后 cron 探测变为严格模式。
- 此通道使用 Gateway 网关的 `chat.send` 表面，并带有仅限管理员的合成 originating-route 字段，以便测试可以附加消息渠道上下文，而无需假装向外部投递。
- 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用嵌入式 `acpx` 插件的内置智能体注册表，为选定的 ACP harness 智能体提供支持。
- 默认情况下，绑定会话的 cron MCP 创建是尽力而为的，因为外部 ACP harness 可能会在绑定/image 证明通过后取消 MCP 调用；设置 `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` 可使绑定后的 cron 探测变为严格模式。
示例：
@ -264,28 +264,34 @@ Docker 说明：
- Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。
- 默认情况下，它会按顺序针对聚合的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后是 `gemini`。
- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` 缩小矩阵范围。
- 它会加载 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，然后在缺失时安装所请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex`、通过 `https://app.factory.ai/cli` 安装的 Factory Droid、`@google/gemini-cli` 或 `opencode-ai`）。ACP 后端本身是来自 `acpx` 插件的内置捆绑 `acpx/runtime` 包。
- Droid Docker 变体会暂存 `~/.factory` 作为设置，转发 `FACTORY_API_KEY`，并且要求提供该 API key，因为本地 Factory OAuth/keyring 认证无法移植到容器中。它使用 ACPX 的内置 `droid exec --output-format acp` 注册表条目。
- OpenCode Docker 变体是严格的单智能体回归通道。它会在加载 `~/.profile` 后，根据 `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL`（默认 `opencode/kimi-k2.6`）写入临时 `OPENCODE_CONFIG_CONTENT` 默认模型，并且 `pnpm test:docker:live-acp-bind:opencode` 要求存在已绑定的助手转录，而不是接受通用的绑定后跳过。
- 直接调用 `acpx` CLI 只是用于在 Gateway 网关之外比较行为的手动/变通路径。Docker ACP 绑定冒烟测试会测试 OpenClaw 的内嵌 `acpx` 运行时后端。
- 它会 source `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，然后在缺失时安装请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex`、通过 `https://app.factory.ai/cli` 安装的 Factory Droid、`@google/gemini-cli` 或 `opencode-ai`）。ACP 后端本身是来自官方 `acpx` 插件的嵌入式 `acpx/runtime` 包。
- Droid Docker 变体会暂存 `~/.factory` 作为设置，转发 `FACTORY_API_KEY`，并且需要该 API key，因为本地 Factory OAuth/keyring 认证无法移植到容器中。它使用 ACPX 内置的 `droid exec --output-format acp` 注册表条目。
- OpenCode Docker 变体是严格的单智能体回归通道。它会在 source `~/.profile` 后，从 `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL`（默认 `opencode/kimi-k2.6`）写入一个临时的 `OPENCODE_CONFIG_CONTENT` 默认模型，并且 `pnpm test:docker:live-acp-bind:opencode` 要求存在已绑定的 assistant transcript，而不是接受通用的绑定后跳过。
- 直接调用 `acpx` CLI 只是一个手动/变通路径，用于比较 Gateway 网关之外的行为。Docker ACP 绑定冒烟测试会执行 OpenClaw 的嵌入式 `acpx` 运行时后端。
## 实时：Codex app-server harness 冒烟测试
- 目标：通过常规 Gateway 网关 `agent` 方法验证插件拥有的 Codex harness：
- 加载内置 `codex` 插件
- 目标：通过普通 Gateway 网关
`agent` 方法验证插件拥有的 Codex harness：
- 加载内置的 `codex` 插件
- 选择 `OPENCLAW_AGENT_RUNTIME=codex`
- 在强制使用 Codex harness 的情况下，向 `openai/gpt-5.5` 发送第一个 Gateway 网关智能体回合
- 向同一个 OpenClaw 会话发送第二个回合，并验证 app-server 线程可以恢复
- 在强制使用 Codex harness 的情况下，向 `openai/gpt-5.5` 发送第一个 Gateway 网关智能体轮次
- 向同一个 OpenClaw 会话发送第二个轮次，并验证 app-server
thread 可以恢复
- 通过同一个 Gateway 网关命令路径运行 `/codex status` 和 `/codex models`
- 可选运行两个经过 Guardian 审查的提权 shell 探测：一个应被批准的良性命令，以及一个应被拒绝、从而让智能体反问的伪密钥上传
- 可选运行两个经过 Guardian 审查的提权 shell 探测：一个应被批准的无害
命令，以及一个应被拒绝、从而让智能体回问的假 secret 上传
- 测试：`src/gateway/gateway-codex-harness.live.test.ts`
- 启用：`OPENCLAW_LIVE_CODEX_HARNESS=1`
- 默认模型：`openai/gpt-5.5`
- 可选图像探测：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- 可选 MCP/工具探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- 可选 image 探测：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- 可选 MCP/tool 探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- 可选 Guardian 探测：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，因此损坏的 Codex harness 不能通过静默回退到 PI 而通过测试。
- 认证：Codex app-server 认证来自本地 Codex 订阅登录。Docker 冒烟测试在适用时也可以为非 Codex 探测提供 `OPENAI_API_KEY`，以及可选复制的 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
- 该冒烟测试设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，因此损坏的 Codex
harness 无法通过静默回退到 PI 来通过测试。
- 认证：来自本地 Codex 订阅登录的 Codex app-server 认证。Docker
冒烟测试也可以在适用时为非 Codex 探测提供 `OPENAI_API_KEY`，
以及可选复制的 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
本地配方：
@ -309,13 +315,21 @@ pnpm test:docker:live-codex-harness
Docker 说明：
- Docker 运行器位于 `scripts/test-live-codex-harness-docker.sh`。
- 它会加载挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI 认证文件，把 `@openai/codex` 安装到可写的挂载 npm 前缀中，暂存源码树，然后只运行 Codex-harness 实时测试。
- Docker 默认启用图像、MCP/工具和 Guardian 探测。当你需要更窄的调试运行时，设置 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`、`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
- Docker 还会导出 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，与实时测试配置一致，因此旧别名或 PI 回退无法掩盖 Codex harness 回归。
- 它会 source 挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI
认证文件，将 `@openai/codex` 安装到可写的挂载 npm
prefix 中，暂存源码树，然后只运行 Codex-harness 实时测试。
- Docker 默认启用 image、MCP/tool 和 Guardian 探测。需要更窄的调试
运行时，设置
`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或
`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
- Docker 还会导出 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，与实时
测试配置保持一致，因此旧版别名或 PI 回退无法隐藏 Codex harness
回归。
### 推荐的实时配方
窄范围、显式的允许列表最快，且最不容易不稳定：
窄而明确的 allowlist 最快，也最不容易不稳定：
- 单模型，直接运行（不经过 Gateway 网关）：
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts`
@ -323,50 +337,50 @@ Docker 说明：
- 单模型，Gateway 网关冒烟测试：
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- 跨多个提供商调用工具：
- 跨多个提供商的工具调用：
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Google 重点覆盖（Gemini API key + Antigravity）：
- Google 聚焦（Gemini API key + Antigravity）：
- Gemini（API key）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Google 自适应思考冒烟测试：
- 如果本地密钥存在于 shell 配置文件中：`source ~/.profile`
- Gemini 3 动态默认值：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
- Gemini 2.5 动态预算：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`
- Google adaptive thinking 冒烟测试：
- 如果本地 key 存在于 shell profile 中：`source ~/.profile`
- Gemini 3 dynamic default：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
- Gemini 2.5 dynamic budget：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`
说明：
- `google/...` 使用 Gemini API（API key）。
- `google-antigravity/...` 使用 Antigravity OAuth 桥接（Cloud Code Assist 风格的智能体端点）。
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立认证 + 工具链细节差异）。
- `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist 风格的智能体端点）。
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立认证 + 工具链特性）。
- Gemini API 与 Gemini CLI：
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / profile 认证）；这就是大多数用户所说的 “Gemini”。
- CLI：OpenClaw 会 shell 到本地 `gemini` 二进制文件；它有自己的认证，并且行为可能不同（流式传输/工具支持/版本偏差）。
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / profile 认证）；这也是大多数用户所说的“Gemini”。
- CLI：OpenClaw shell out 到本地 `gemini` 二进制；它有自己的认证，并且行为可能不同（streaming/tool 支持/版本偏差）。
## 实时：模型矩阵（覆盖内容）
## 实时：模型矩阵（我们覆盖的内容）
没有固定的 “CI 模型列表”（实时测试是选择加入的），但以下是在有密钥的开发机器上建议定期覆盖的**推荐**模型。
没有固定的“CI 模型列表”（实时测试是选择性启用的），但以下是建议在有 key 的开发机器上定期覆盖的**推荐**模型。
### 现代冒烟测试集（工具调用 + 图像）
### 现代冒烟集合（工具调用 + image）
这是我们期望保持可用的“常用模型”运行：
- OpenAI（非 Codex）：`openai/gpt-5.5`
- OpenAI Codex OAuth：`openai-codex/gpt-5.5`
- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
- Google（Gemini API）：`google/gemini-3.1-pro-preview` 和 `google/gemini-3-flash-preview`（避免较旧的 Gemini 2.x 模型）
- Google（Gemini API）：`google/gemini-3.1-pro-preview` 和 `google/gemini-3-flash-preview`（避免旧版 Gemini 2.x 模型）
- Google（Antigravity）：`google-antigravity/claude-opus-4-6-thinking` 和 `google-antigravity/gemini-3-flash`
- DeepSeek：`deepseek/deepseek-v4-flash` 和 `deepseek/deepseek-v4-pro`
- Z.AI（GLM）：`zai/glm-5.1`
- MiniMax：`minimax/MiniMax-M2.7`
使用工具 + 图像运行 Gateway 网关冒烟测试：
使用工具 + image 运行 Gateway 网关冒烟测试：
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
### 基线：工具调用（Read + 可选 Exec）
每个提供商家族至少选择一个：
每个提供商系列至少选择一个：
- OpenAI：`openai/gpt-5.5`
- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
@ -378,77 +392,77 @@ Docker 说明：
可选的额外覆盖（有则更好）：
- xAI：`xai/grok-4.3`（或最新可用版本）
- Mistral：`mistral/`…（选择一个你已启用且支持“工具”的模型）
- Mistral：`mistral/`…（选择一个你已启用、支持“tools”的模型）
- Cerebras：`cerebras/`…（如果你有访问权限）
- LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式）
### 视觉：图像发送（附件 → 多模态消息）
### Vision：发送 image（附件 → 多模态消息）
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude/Gemini/OpenAI 视觉能力变体等），以执行图像探测。
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中包含至少一个支持 image 的模型（Claude/Gemini/OpenAI 支持 vision 的变体等），以执行 image 探测。
### 聚合器 / 备用网关
### 聚合器 / 替代 Gateway 网关
如果你已启用密钥，我们也支持通过以下方式测试：
如果你已启用 key，我们还支持通过以下方式测试：
- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选项）
- OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持 tool+image 的候选项）
- OpenCode：`opencode/...` 用于 Zen，`opencode-go/...` 用于 Go（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
你可以加入实时矩阵的更多提供商（如果你有凭证/配置）：
你可以包含在实时矩阵中的更多提供商（如果你有凭据/配置）：
- 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot`
- 通过 `models.providers`（自定义端点）：`minimax`（云/API），以及任何兼容 OpenAI/Anthropic 的代理（LM Studio、vLLM、LiteLLM 等）
- 通过 `models.providers`（自定义端点）：`minimax`（cloud/API），以及任何 OpenAI/Anthropic 兼容代理（LM Studio、vLLM、LiteLLM 等）
<Tip>
不要在文档中硬编码“所有模型”。权威列表是你机器上 `discoverModels(...)` 返回的内容，再加上可用的密钥。
不要在文档中硬编码“所有模型”。权威列表是你的机器上 `discoverModels(...)` 返回的内容，再加上可用的 key。
</Tip>
## 凭证（绝不要提交）
## 凭据（切勿提交）
实时测试会以与 CLI 相同的方式发现凭证。实际影响：
实时测试会以与 CLI 相同的方式发现凭据。实际影响：
- 如果 CLI 可用，live 测试应能找到相同的键名。
- 如果某个 live 测试提示“没有凭证”，请用调试 `openclaw models list` / 模型选择的同样方式来调试。
- 如果 CLI 可用，实时测试应能找到相同的键。
- 如果实时测试提示“没有凭证”，请按调试 `openclaw models list` / 模型选择的同样方式进行调试。
- 每智能体凭证配置文件：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是 live 测试中“profile keys”的含义）
- 每智能体凭证配置文件：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试中“profile keys”的含义）
- 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的 live 主目录，但它不是主要的配置文件键名存储）
- 默认情况下，本地 live 运行会把活动配置、每智能体 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 凭证目录复制到一个临时测试主目录；暂存的 live 主目录会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，以便探测不会触碰你的真实主机工作区。
- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时测试主目录中，但不是主要的 profile-key 存储位置）
- 本地实时运行默认会把当前配置、每智能体 `auth-profiles.json` 文件、旧版 `credentials/`，以及受支持的外部 CLI 凭证目录复制到临时测试主目录；暂存的实时测试主目录会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，以确保探测不会访问你真实主机上的工作区。
如果你想依赖环境键名（例如在你的 `~/.profile` 中导出），请在 `source ~/.profile` 之后运行本地测试，或使用下面的 Docker 运行器（它们可以把 `~/.profile` 挂载到容器中）。
如果你想依赖环境键（例如在你的 `~/.profile` 中导出的键），请在 `source ~/.profile` 后运行本地测试，或使用下面的 Docker 运行器（它们可以把 `~/.profile` 挂载到容器中）。
## Deepgram live（音频转写）
## Deepgram 实时（音频转录）
- 测试：`extensions/deepgram/audio.live.test.ts`
- 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
## BytePlus 编码计划 live
## BytePlus 编码计划实时测试
- 测试：`extensions/byteplus/live.test.ts`
- 启用：`BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts`
- 可选模型覆盖：`BYTEPLUS_CODING_MODEL=ark-code-latest`
## ComfyUI 工作流媒体 live
## ComfyUI 工作流媒体实时测试
- 测试：`extensions/comfy/comfy.live.test.ts`
- 启用：`OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
- 范围：
- 覆盖内置 comfy 图像、视频和 `music_generate` 路径
- 覆盖内置的 comfy 图像、视频和 `music_generate` 路径
- 除非已配置 `plugins.entries.comfy.config.<capability>`，否则跳过每项能力
- 适用于更改 comfy 工作流提交、轮询、下载或插件注册之后
## 图像生成 live
## 图像生成实时测试
- 测试：`test/image-generation.runtime.live.test.ts`
- 命令：`pnpm test:live test/image-generation.runtime.live.test.ts`
- Harness：`pnpm test:live:media image`
- 测试框架：`pnpm test:live:media image`
- 范围：
- 枚举每个已注册的图像生成提供商插件
- 探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
- 默认优先使用 live / 环境 API key，而不是已存储的凭证配置文件，因此 `auth-profiles.json` 中过期的测试键名不会遮蔽真实 shell 凭证
- 跳过没有可用凭证 / 配置文件 / 模型的提供商
- 让每个已配置的提供商通过共享图像生成运行时：
- 默认优先使用实时/环境 API key，而不是已存储的凭证配置文件，因此 `auth-profiles.json` 中过期的测试键不会掩盖真实的 shell 凭证
- 跳过没有可用凭证/配置文件/模型的提供商
- 通过共享图像生成运行时运行每个已配置提供商：
- `<provider>:generate`
- 当提供商声明支持编辑时，运行 `<provider>:edit`
- 当提供商声明支持编辑时运行 `<provider>:edit`
- 当前覆盖的内置提供商：
- `deepinfra`
- `fal`
@ -464,9 +478,9 @@ Docker 说明：
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"`
- 可选凭证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置文件存储凭证，并忽略仅环境变量的覆盖
- 使用 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置文件存储的凭证，并忽略仅环境变量的覆盖
对于已发布的 CLI 路径，请在提供商 / 运行时 live 测试通过后添加一个 `infer` 冒烟测试：
对于已发布的 CLI 路径，请在提供商/运行时实时测试通过后添加一个 `infer` 冒烟测试：
```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts
@ -478,75 +492,75 @@ openclaw infer image generate \
--json
```
这会覆盖 CLI 参数解析、配置 / 默认智能体解析、内置插件激活、共享图像生成运行时，以及 live 提供商请求。插件依赖项预期在运行时加载前已经存在。
这会覆盖 CLI 参数解析、配置/默认智能体解析、内置插件激活、共享图像生成运行时，以及实时提供商请求。插件依赖项应在运行时加载前已存在。
## 音乐生成 live
## 音乐生成实时测试
- 测试：`extensions/music-generation-providers.live.test.ts`
- 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
- Harness：`pnpm test:live:media music`
- 测试框架：`pnpm test:live:media music`
- 范围：
- 覆盖共享的内置音乐生成提供商路径
- 当前覆盖 Google 和 MiniMax
- 探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用 live / 环境 API key，而不是已存储的凭证配置文件，因此 `auth-profiles.json` 中过期的测试键名不会遮蔽真实 shell 凭证
- 跳过没有可用凭证 / 配置文件 / 模型的提供商
- 可用时运行两个声明的运行时模式：
- 使用仅提示词输入运行 `generate`
- 默认优先使用实时/环境 API key，而不是已存储的凭证配置文件，因此 `auth-profiles.json` 中过期的测试键不会掩盖真实的 shell 凭证
- 跳过没有可用凭证/配置文件/模型的提供商
- 可用时运行两个已声明的运行时模式：
- 使用仅提示输入的 `generate`
- 当提供商声明 `capabilities.edit.enabled` 时运行 `edit`
- 当前共享通道覆盖：
- 当前共享通道覆盖范围：
- `google`：`generate`、`edit`
- `minimax`：`generate`
- `comfy`：单独的 Comfy live 文件，不属于此共享扫描
- `comfy`：单独的 Comfy 实时文件，不在此共享扫描中
- 可选缩小范围：
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"`
- 可选凭证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置文件存储凭证，并忽略仅环境变量的覆盖
- 使用 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置文件存储的凭证，并忽略仅环境变量的覆盖
## 视频生成 live
## 视频生成实时测试
- 测试：`extensions/video-generation-providers.live.test.ts`
- 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
- Harness：`pnpm test:live:media video`
- 测试框架：`pnpm test:live:media video`
- 范围：
- 覆盖共享的内置视频生成提供商路径
- 默认使用适合发布的冒烟路径：非 FAL 提供商、每个提供商一个文本到视频请求、一秒钟龙虾提示词，以及由 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 设置的每提供商操作上限（默认 `180000`）
- 默认跳过 FAL，因为提供商侧队列延迟可能主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它
- 默认使用适合发布的冒烟路径：非 FAL 提供商、每个提供商一个文本转视频请求、一秒龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每提供商操作上限（默认 `180000`）
- 默认跳过 FAL，因为提供商侧队列延迟可能占用大量发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它
- 探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用 live / 环境 API key，而不是已存储的凭证配置文件，因此 `auth-profiles.json` 中过期的测试键名不会遮蔽真实 shell 凭证
- 跳过没有可用凭证 / 配置文件 / 模型的提供商
- 默认优先使用实时/环境 API key，而不是已存储的凭证配置文件，因此 `auth-profiles.json` 中过期的测试键不会掩盖真实的 shell 凭证
- 跳过没有可用凭证/配置文件/模型的提供商
- 默认只运行 `generate`
- 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，也会在可用时运行声明的转换模式：
- 当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受缓冲区支持的本地图像输入时，运行 `imageToVideo`
- 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受缓冲区支持的本地视频输入时，运行 `videoToVideo`
- 当前在共享扫描中已声明但跳过的 `imageToVideo` 提供商：
- `vydra`，因为内置 `veo3` 仅支持文本，且内置 `kling` 需要远程图像 URL
- Vydra 专属覆盖：
- 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，也会在可用时运行已声明的转换模式：
- 当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商/模型在共享扫描中接受由缓冲区支持的本地图像输入时，运行 `imageToVideo`
- 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商/模型在共享扫描中接受由缓冲区支持的本地视频输入时，运行 `videoToVideo`
- 共享扫描中当前已声明但跳过的 `imageToVideo` 提供商：
- `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL
- Vydra 的提供商特定覆盖：
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
- 该文件会运行 `veo3` 文本到视频，并运行一个默认使用远程图像 URL fixture 的 `kling` 通道
- 当前 `videoToVideo` live 覆盖：
- 该文件默认运行 `veo3` 文本转视频，以及使用远程图像 URL 固件的 `kling` 通道
- 当前 `videoToVideo` 实时覆盖：
- 仅当所选模型为 `runway/gen4_aleph` 时覆盖 `runway`
- 当前在共享扫描中已声明但跳过的 `videoToVideo` 提供商：
- 共享扫描中当前已声明但跳过的 `videoToVideo` 提供商：
- `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL
- `google`，因为当前共享 Gemini / Veo 通道使用缓冲区支持的本地输入，而该路径在共享扫描中不被接受
- `openai`，因为当前共享通道缺少组织专属视频修复 / 混剪访问保证
- `google`，因为当前共享 Gemini/Veo 通道使用本地缓冲区支持的输入，而共享扫描不接受该路径
- `openai`，因为当前共享通道缺少组织特定视频修补/混剪访问保证
- 可选缩小范围：
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,google,openai,runway"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 将默认扫描中的每个提供商都纳入，包括 FAL
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 为激进冒烟运行降低每个提供商的操作上限
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 可在默认扫描中包含每个提供商，包括 FAL
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 可降低每个提供商的操作上限，用于激进的冒烟运行
- 可选凭证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置文件存储凭证，并忽略仅环境变量的覆盖
- 使用 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置文件存储的凭证，并忽略仅环境变量的覆盖
## 媒体 live harness
## 媒体实时测试框架
- 命令：`pnpm test:live:media`
- 目的：
- 通过一个仓库原生入口点运行共享图像、音乐和视频 live 套件
- 用途：
- 通过一个仓库原生入口点运行共享的图像、音乐和视频实时测试套件
- 从 `~/.profile` 自动加载缺失的提供商环境变量
- 默认将每个套件自动缩小到当前拥有可用凭证的提供商
- 复用 `scripts/test-live.mjs`，因此 Heartbeat 和安静模式行为保持一致
- 默认自动将每个套件缩小到当前拥有可用凭证的提供商
- 复用 `scripts/test-live.mjs`，因此 Heartbeat 和静默模式行为保持一致
- 示例：
- `pnpm test:live:media`
- `pnpm test:live:media image video --providers openai,google,minimax`

243
docs/zh-CN/install/docker.md
View File

@ -1,34 +1,34 @@
---
read_when:
- 你想使用容器化的 Gateway 网关，而不是本地安装
- 你想要容器化的 Gateway 网关，而不是本地安装
- 你正在验证 Docker 流程
summary: OpenClaw 的可选 Docker 设置和新手引导
title: Docker
x-i18n:
generated_at: "2026-05-01T20:38:09Z"
generated_at: "2026-05-02T07:52:18Z"
model: gpt-5.5
provider: openai
source_hash: 2647caae7debfe0647842249a3a6000bfa73b191b1aa1d7ced1e9c0eb22228db
source_hash: 8467618438209c1c7c74eadf2c793dbae21622eb92fa3ddbd13d668d8be5bf1f
source_path: install/docker.md
workflow: 16
---
Docker 是**可选的**。仅当你想使用容器化的 Gateway 网关或验证 Docker 流程时才使用它。
Docker 是**可选的**。仅当你想使用容器化 Gateway 网关或验证 Docker 流程时才使用它。
## Docker 适合我吗？
- **是**：你想要一个隔离的、可丢弃的 Gateway 网关环境，或想在没有本地安装的主机上运行 OpenClaw。
- **否**：你在自己的机器上运行，并且只想要最快的开发循环。请改用常规安装流程。
- **沙箱注意事项**：启用沙箱隔离时，默认沙箱后端会使用 Docker，但沙箱隔离默认关闭，并且**不**要求完整 Gateway 网关在 Docker 中运行。SSH 和 OpenShell 沙箱后端也可用。参见[沙箱隔离](/zh-CN/gateway/sandboxing)。
- **否**：你正在自己的机器上运行，只想要最快的开发循环。请改用常规安装流程。
- **沙箱注意事项**：启用沙箱隔离时，默认沙箱后端使用 Docker，但沙箱隔离默认关闭，并且**不**要求完整 Gateway 网关在 Docker 中运行。SSH 和 OpenShell 沙箱后端也可用。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
## 前提条件
## 前置条件
- Docker Desktop（或 Docker Engine）+ Docker Compose v2
- 镜像构建至少需要 2 GB RAM（在 1 GB 主机上，`pnpm install` 可能会因 OOM 被终止并以 137 退出）
- 镜像构建至少需要 2 GB RAM（在 1 GB 主机上，`pnpm install` 可能因 OOM 被终止并以退出码 137 退出）
- 足够的磁盘空间用于镜像和日志
- 如果在 VPS/公网主机上运行，请查看
[网络暴露安全加固](/zh-CN/gateway/security)，
特别是 Docker `DOCKER-USER` 防火墙策略。
[网络暴露的安全加固](/zh-CN/gateway/security)，
尤其是 Docker `DOCKER-USER` 防火墙策略。
## 容器化 Gateway 网关
@ -56,22 +56,21 @@ Docker 是**可选的**。仅当你想使用容器化的 Gateway 网关或验证
<Step title="完成新手引导">
设置脚本会自动运行新手引导。它会：
- 提示输入提供商 API key
- 提示输入提供商 API 密钥
- 生成 Gateway 网关令牌并写入 `.env`
- 通过 Docker Compose 启动 Gateway 网关
设置期间，启动前的新手引导和配置写入会直接通过
`openclaw-gateway` 运行。`openclaw-cli` 用于 Gateway 网关容器已经存在后
你运行的命令。
`openclaw-gateway` 运行。`openclaw-cli` 用于在
Gateway 网关容器已经存在后运行的命令。
</Step>
<Step title="打开控制 UI">
在浏览器中打开 `http://127.0.0.1:18789/`，并将已配置的
共享密钥粘贴到设置中。设置脚本默认会将令牌写入 `.env`；
如果你把容器配置切换为密码认证，请改用该密码。
共享密钥粘贴到设置中。设置脚本默认会把令牌写入 `.env`；如果你把容器配置切换为密码认证，请改用该密码。
需要再次获取 URL？
还需要再次获取 URL？
```bash
docker compose run --rm openclaw-cli dashboard --no-open
@ -100,7 +99,7 @@ Docker 是**可选的**。仅当你想使用容器化的 Gateway 网关或验证
### 手动流程
如果你希望自己运行每个步骤，而不是使用设置脚本：
如果你希望自己逐步运行，而不是使用设置脚本：
```bash
docker build -t openclaw:local -f Dockerfile .
@ -114,50 +113,48 @@ docker compose up -d openclaw-gateway
<Note>
从仓库根目录运行 `docker compose`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS`
或 `OPENCLAW_HOME_VOLUME`，设置脚本会写入 `docker-compose.extra.yml`；
请使用 `-f docker-compose.yml -f docker-compose.extra.yml` 将其包含进去。
请用 `-f docker-compose.yml -f docker-compose.extra.yml` 包含它。
</Note>
<Note>
因为 `openclaw-cli` 共享 `openclaw-gateway` 的网络命名空间，它是一个
启动后工具。在运行 `docker compose up -d openclaw-gateway` 之前，
请通过带有 `--no-deps --entrypoint node` 的 `openclaw-gateway`
运行新手引导和设置时配置写入。
由于 `openclaw-cli` 共享 `openclaw-gateway` 的网络命名空间，它是一个
启动后的工具。在 `docker compose up -d openclaw-gateway` 之前，请通过
`openclaw-gateway` 并带上 `--no-deps --entrypoint node` 运行新手引导
和设置时配置写入。
</Note>
### 环境变量
设置脚本接受以下可选环境变量：
设置脚本接受这些可选环境变量：
| 变量 | 用途 |
| ------------------------------------------ | --------------------------------------------------------------- |
| `OPENCLAW_IMAGE` | 使用远程镜像而不是本地构建 |
| `OPENCLAW_DOCKER_APT_PACKAGES` | 在构建期间安装额外 apt 包（用空格分隔） |
| `OPENCLAW_EXTENSIONS` | 在构建时包含选定的内置插件辅助组件 |
| `OPENCLAW_EXTRA_MOUNTS` | 额外的主机绑定挂载（用逗号分隔的 `source:target[:opts]`） |
| `OPENCLAW_HOME_VOLUME` | 将 `/home/node` 持久化到命名 Docker 卷中 |
| `OPENCLAW_IMAGE` | 使用远程镜像，而不是在本地构建 |
| `OPENCLAW_DOCKER_APT_PACKAGES` | 构建期间安装额外 apt 包（以空格分隔） |
| `OPENCLAW_EXTENSIONS` | 构建时包含选定的内置插件辅助组件 |
| `OPENCLAW_EXTRA_MOUNTS` | 额外的主机绑定挂载（逗号分隔的 `source:target[:opts]`） |
| `OPENCLAW_HOME_VOLUME` | 将 `/home/node` 持久化到具名 Docker 卷 |
| `OPENCLAW_SANDBOX` | 选择启用沙箱引导（`1`、`true`、`yes`、`on`） |
| `OPENCLAW_SKIP_ONBOARDING` | 跳过交互式新手引导步骤（`1`、`true`、`yes`、`on`） |
| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker socket 路径 |
| `OPENCLAW_DISABLE_BONJOUR` | 禁用 Bonjour/mDNS 广播（Docker 中默认值为 `1`） |
| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | 禁用内置插件源代码绑定挂载覆盖层 |
| `OPENCLAW_DISABLE_BONJOUR` | 禁用 Bonjour/mDNS 广播（Docker 默认值为 `1`） |
| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | 禁用内置插件源码绑定挂载覆盖层 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 用于 OpenTelemetry 导出的共享 OTLP/HTTP 收集器端点 |
| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | 用于 traces、metrics 或 logs 的信号专属 OTLP 端点 |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 协议覆盖。目前仅支持 `http/protobuf` |
| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | 用于 traces、metrics 或 logs 的特定信号 OTLP 端点 |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 协议覆盖。当前仅支持 `http/protobuf` |
| `OTEL_SERVICE_NAME` | 用于 OpenTelemetry 资源的服务名称 |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | 选择启用最新的实验性 GenAI 语义属性 |
| `OPENCLAW_OTEL_PRELOADED` | 当已有一个 OpenTelemetry SDK 预加载时，跳过启动第二个 |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | 选择启用最新实验性 GenAI 语义属性 |
| `OPENCLAW_OTEL_PRELOADED` | 当已有一个 OpenTelemetry SDK 预加载时，跳过启动第二个 SDK |
维护者可以通过将一个插件源目录挂载到其打包源路径上，来针对打包镜像测试内置插件源代码，
例如
维护者可以通过将一个插件源码目录挂载到其打包源码路径上，使用打包镜像测试内置插件源码，例如
`OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro`。
该挂载的源目录会覆盖同一插件 id 对应的已编译
该挂载的源码目录会覆盖相同插件 ID 对应的已编译
`/app/dist/extensions/synology-chat` 包。
### 可观测性
OpenTelemetry 导出是从 Gateway 网关容器到你的 OTLP
收集器的出站连接。它不需要发布 Docker 端口。如果你在本地构建镜像，
并希望镜像内部可用内置 OpenTelemetry 导出器，请包含其运行时依赖：
OpenTelemetry 导出是从 Gateway 网关容器出站到你的 OTLP
收集器。它不需要发布 Docker 端口。如果你在本地构建镜像，并希望镜像内可用内置 OpenTelemetry 导出器，请包含它的运行时依赖：
```bash
export OPENCLAW_EXTENSIONS="diagnostics-otel"
@ -166,23 +163,21 @@ export OTEL_SERVICE_NAME="openclaw-gateway"
./scripts/docker/setup.sh
```
官方 OpenClaw Docker 发布镜像包含内置
`diagnostics-otel` 插件源代码。若要启用导出，请在配置中允许并启用
`diagnostics-otel` 插件，然后设置
`diagnostics.otel.enabled=true`，或使用
[OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)中的配置示例。收集器认证标头通过
在打包的 Docker 安装中启用导出前，请安装官方 `@openclaw/diagnostics-otel` 插件。自定义源码构建镜像仍可使用
`OPENCLAW_EXTENSIONS=diagnostics-otel` 包含本地插件源码。若要启用导出，请在配置中允许并启用 `diagnostics-otel` 插件，然后设置
`diagnostics.otel.enabled=true`，或使用 [OpenTelemetry
导出](/zh-CN/gateway/opentelemetry) 中的配置示例。收集器认证标头通过
`diagnostics.otel.headers` 配置，而不是通过 Docker 环境变量配置。
Prometheus metrics 使用已经发布的 Gateway 网关端口。启用
Prometheus 指标使用已经发布的 Gateway 网关端口。启用
`diagnostics-prometheus` 插件，然后抓取：
```text
http://<gateway-host>:18789/api/diagnostics/prometheus
```
该路由受 Gateway 网关认证保护。不要暴露单独的公网
`/metrics` 端口或未认证的反向代理路径。参见
[Prometheus metrics](/zh-CN/gateway/prometheus)。
该路由受 Gateway 网关认证保护。不要暴露单独的公网 `/metrics` 端口或未认证的反向代理路径。参见
[Prometheus 指标](/zh-CN/gateway/prometheus)。
### 健康检查
@ -204,32 +199,31 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA
### LAN 与 loopback
`scripts/docker/setup.sh` 默认设置 `OPENCLAW_GATEWAY_BIND=lan`，因此主机可通过
`http://127.0.0.1:18789` 访问 Docker 发布的端口。
`scripts/docker/setup.sh` 默认设置 `OPENCLAW_GATEWAY_BIND=lan`，因此通过 Docker 端口发布，主机可以访问
`http://127.0.0.1:18789`。
- `lan`（默认）：主机浏览器和主机 CLI 可以访问已发布的 Gateway 网关端口。
- `loopback`：只有容器网络命名空间内的进程可以直接访问
Gateway 网关。
<Note>
在 `gateway.bind` 中使用绑定模式值（`lan` / `loopback` / `custom` /
`tailnet` / `auto`），不要使用 `0.0.0.0` 或 `127.0.0.1` 这样的主机别名。
请使用 `gateway.bind` 中的绑定模式值（`lan` / `loopback` / `custom` /
`tailnet` / `auto`），不要使用 `0.0.0.0` 或 `127.0.0.1` 这类主机别名。
</Note>
### 主机本地提供商
当 OpenClaw 在 Docker 中运行时，容器内的 `127.0.0.1` 指的是容器本身，
不是你的主机机器。对于运行在主机上的 AI 提供商，请使用 `host.docker.internal`：
当 OpenClaw 在 Docker 中运行时，容器内的 `127.0.0.1` 指的是容器
本身，而不是你的主机。对于在主机上运行的 AI 提供商，请使用 `host.docker.internal`：
| 提供商 | 主机默认 URL | Docker 设置 URL |
| --------- | ------------------------ | ----------------------------------- |
| LM Studio | `http://127.0.0.1:1234` | `http://host.docker.internal:1234` |
| Ollama | `http://127.0.0.1:11434` | `http://host.docker.internal:11434` |
内置 Docker 设置会将这些主机 URL 用作 LM Studio 和 Ollama
新手引导默认值，并且 `docker-compose.yml` 会将 `host.docker.internal` 映射到
Linux Docker Engine 的 Docker 主机网关。Docker Desktop 已经在 macOS 和 Windows
上提供相同的主机名。
内置 Docker 设置会使用这些主机 URL 作为 LM Studio 和 Ollama
新手引导默认值，并且 `docker-compose.yml` 会在 Linux Docker Engine 上将
`host.docker.internal` 映射到 Docker 的主机网关。Docker Desktop 已在 macOS 和 Windows 上提供同一主机名。
主机服务还必须监听 Docker 可访问的地址：
@ -238,63 +232,55 @@ lms server start --port 1234 --bind 0.0.0.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve
```
如果你使用自己的 Compose 文件或 `docker run` 命令，请自行添加相同的主机映射，
例如
如果你使用自己的 Compose 文件或 `docker run` 命令，请自行添加相同的主机映射，例如
`--add-host=host.docker.internal:host-gateway`。
### Bonjour / mDNS
Docker bridge 网络通常无法可靠转发 Bonjour/mDNS 多播
Docker 桥接网络通常无法可靠转发 Bonjour/mDNS 多播
（`224.0.0.251:5353`）。因此，内置 Compose 设置默认使用
`OPENCLAW_DISABLE_BONJOUR=1`，这样 Gateway 网关就不会在 bridge 丢弃多播流量时
崩溃循环或反复重启广播。
`OPENCLAW_DISABLE_BONJOUR=1`，这样当桥接网络丢弃多播流量时，Gateway 网关不会崩溃循环或反复重启广播。
对于 Docker 主机，请使用已发布的 Gateway 网关 URL、Tailscale 或广域 DNS-SD。
仅当使用 host networking、macvlan 或其他已知 mDNS 多播可工作的网络时，
才设置 `OPENCLAW_DISABLE_BONJOUR=0`。
对 Docker 主机使用已发布的 Gateway 网关 URL、Tailscale 或广域 DNS-SD。
仅在使用主机网络、macvlan 或其他已知 mDNS 多播可用的网络时，才设置
`OPENCLAW_DISABLE_BONJOUR=0`。
有关注意事项和故障排除，请参见 [Bonjour 设备发现](/zh-CN/gateway/bonjour)。
### 存储和持久化
Docker Compose 会将 `OPENCLAW_CONFIG_DIR` 绑定挂载到 `/home/node/.openclaw`，
并将 `OPENCLAW_WORKSPACE_DIR` 绑定挂载到 `/home/node/.openclaw/workspace`，
因此这些路径会在容器替换后保留。当任一变量未设置时，内置
`docker-compose.yml` 会回退到 `${HOME}/.openclaw`（工作区挂载则回退到
Docker Compose 会将 `OPENCLAW_CONFIG_DIR` 绑定挂载到 `/home/node/.openclaw`，并将
`OPENCLAW_WORKSPACE_DIR` 绑定挂载到 `/home/node/.openclaw/workspace`，因此这些路径会在容器替换后保留。任一变量未设置时，内置
`docker-compose.yml` 会回退到 `${HOME}/.openclaw`（工作区挂载为
`${HOME}/.openclaw/workspace`），如果 `HOME` 本身也缺失，则回退到 `/tmp/.openclaw`。
这可以避免 `docker compose up` 在裸环境中发出空 source 卷规范。
这样可以避免 `docker compose up` 在裸环境中发出空源卷规范。
OpenClaw 在该挂载的配置目录中保存：
该挂载的配置目录是 OpenClaw 存放以下内容的位置：
- 用于行为配置的 `openclaw.json`
- 用于已存储的提供商 OAuth/API-key 凭证的 `agents/<agentId>/agent/auth-profiles.json`
- 用于环境变量支持的运行时密钥（如 `OPENCLAW_GATEWAY_TOKEN`）的 `.env`
- 用于已存储提供商 OAuth/API 密钥认证的 `agents/<agentId>/agent/auth-profiles.json`
- 用于环境变量支持的运行时密钥（例如 `OPENCLAW_GATEWAY_TOKEN`）的 `.env`
已安装的可下载插件会将其 package 状态存储在挂载的
OpenClaw home 下，因此插件安装记录和 package 根目录会在容器替换后保留。
Gateway 网关启动不会生成内置插件依赖树。
已安装的可下载插件会将其包状态存放在挂载的 OpenClaw home 下，因此插件安装记录和包根目录会在容器替换后保留。Gateway 网关启动不会生成内置插件依赖树。
有关 VM 部署的完整持久化详情，请参见
[Docker VM 运行时 - 哪些内容会持久化到哪里](/zh-CN/install/docker-vm-runtime#what-persists-where)。
有关 VM 部署完整持久化详情，请参见
[Docker VM 运行时 - 哪些内容持久化在哪里](/zh-CN/install/docker-vm-runtime#what-persists-where)。
**磁盘增长热点：** 关注 `media/`、会话 JSONL 文件、
`cron/runs/*.jsonl`、已安装的插件 package 根目录，以及
`/tmp/openclaw/` 下的滚动文件日志。
**磁盘增长热点：** 注意 `media/`、会话 JSONL 文件、`cron/runs/*.jsonl`、已安装的插件包根目录，以及 `/tmp/openclaw/` 下的滚动文件日志。
### Shell 辅助工具（可选）
为了更轻松地进行日常 Docker 管理，请安装 `ClawDock`：
为了更轻松地进行日常 Docker 管理，安装 `ClawDock`：
```bash
mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
```
如果你之前从较旧的 `scripts/shell-helpers/clawdock-helpers.sh` 原始路径安装了 ClawDock，请重新运行上面的安装命令，让你的本地辅助文件跟踪新位置。
如果你是从较旧的 `scripts/shell-helpers/clawdock-helpers.sh` raw 路径安装的 ClawDock，请重新运行上面的安装命令，让你的本地辅助文件跟踪新位置。
然后使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。运行
`clawdock-help` 查看所有命令。
完整辅助工具指南见 [ClawDock](/zh-CN/install/clawdock)。
然后使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等。运行 `clawdock-help` 查看所有命令。
查看 [ClawDock](/zh-CN/install/clawdock) 获取完整辅助工具指南。
<AccordionGroup>
<Accordion title="为 Docker Gateway 网关启用智能体沙箱">
@ -311,9 +297,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
./scripts/docker/setup.sh
```
只有在沙箱前置条件通过后，脚本才会挂载 `docker.sock`。如果
沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode`
重置为 `off`。
该脚本只会在沙箱前置条件通过后挂载 `docker.sock`。如果沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode` 重置为 `off`。
</Accordion>
@ -328,15 +312,11 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
</Accordion>
<Accordion title="共享网络安全注意事项">
`openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，因此 CLI
命令可以通过 `127.0.0.1` 访问 Gateway 网关。请将其视为共享的
信任边界。Compose 配置会移除 `NET_RAW`/`NET_ADMIN`，并在
`openclaw-cli` 上启用 `no-new-privileges`。
`openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，这样 CLI 命令可以通过 `127.0.0.1` 访问 Gateway 网关。请将其视为共享信任边界。Compose 配置会丢弃 `NET_RAW`/`NET_ADMIN`，并在 `openclaw-cli` 上启用 `no-new-privileges`。
</Accordion>
<Accordion title="权限和 EACCES">
镜像以 `node`（uid 1000）身份运行。如果你在
`/home/node/.openclaw` 上看到权限错误，请确保主机绑定挂载归 uid 1000 所有：
镜像以 `node`（uid 1000）身份运行。如果你在 `/home/node/.openclaw` 上看到权限错误，请确保你的主机绑定挂载由 uid 1000 拥有：
```bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
@ -344,9 +324,8 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
</Accordion>
<Accordion title="更快的重新构建">
调整 Dockerfile 顺序，让依赖层可以被缓存。这样除非 lockfile 发生变化，否则可以避免重新运行
`pnpm install`：
<Accordion title="更快的重建">
排列你的 Dockerfile，让依赖层可以被缓存。这样除非锁文件发生变化，否则可以避免重新运行 `pnpm install`：
```dockerfile
FROM node:24-bookworm
@ -369,58 +348,43 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
</Accordion>
<Accordion title="高级用户容器选项">
默认镜像优先考虑安全，并以非 root 的 `node` 身份运行。若要使用功能更完整的容器：
默认镜像以安全优先，并以非 root 的 `node` 身份运行。如需功能更完整的容器：
1. **持久化 `/home/node`**：`export OPENCLAW_HOME_VOLUME="openclaw_home"`
2. **预置系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
2. **内置系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
3. **安装 Playwright 浏览器**：
```bash
docker compose run --rm openclaw-cli \
node /app/node_modules/playwright-core/cli.js install chromium
```
4. **持久化浏览器下载内容**：设置
`PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright`，并使用
`OPENCLAW_HOME_VOLUME` 或 `OPENCLAW_EXTRA_MOUNTS`。
4. **持久化浏览器下载内容**：设置 `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright`，并使用 `OPENCLAW_HOME_VOLUME` 或 `OPENCLAW_EXTRA_MOUNTS`。
</Accordion>
<Accordion title="OpenAI Codex OAuth（无头 Docker）">
如果你在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL。在
Docker 或无头设置中，复制你最终到达的完整重定向 URL，并将其粘贴回
向导以完成认证。
如果你在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL。在 Docker 或无头设置中，复制你最终到达的完整重定向 URL，并将其粘贴回向导以完成身份验证。
</Accordion>
<Accordion title="基础镜像元数据">
主 Docker 运行时镜像使用 `node:24-bookworm-slim`，并发布 OCI
基础镜像注解，包括 `org.opencontainers.image.base.name`、
`org.opencontainers.image.source` 等。Node 基础摘要会通过 Dependabot Docker 基础镜像 PR
刷新；发布构建不会运行发行版升级层。见
[OCI 镜像注解](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。
主 Docker 运行时镜像使用 `node:24-bookworm-slim`，并发布 OCI 基础镜像注解，包括 `org.opencontainers.image.base.name`、`org.opencontainers.image.source` 和其他注解。Node 基础摘要会通过 Dependabot Docker 基础镜像 PR 刷新；发布构建不会运行发行版升级层。请参阅 [OCI 镜像注解](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。
</Accordion>
</AccordionGroup>
### 在 VPS 上运行？
请参阅 [Hetzner（Docker VPS）](/zh-CN/install/hetzner) 和
[Docker VM 运行时](/zh-CN/install/docker-vm-runtime)，了解共享 VM 部署步骤，
包括二进制预置、持久化和更新。
请参阅 [Hetzner（Docker VPS）](/zh-CN/install/hetzner) 和 [Docker VM 运行时](/zh-CN/install/docker-vm-runtime)，了解共享 VM 部署步骤，包括二进制内置、持久化和更新。
## Agent 沙箱
## 智能体沙箱
当使用 Docker 后端启用 `agents.defaults.sandbox` 时，Gateway 网关
会在隔离的 Docker 容器内运行智能体工具执行（shell、文件读写等），
而 Gateway 网关本身仍保留在主机上。这样无需将整个
Gateway 网关容器化，也能为不受信任或多租户的智能体会话提供硬隔离。
当使用 Docker 后端启用 `agents.defaults.sandbox` 时，Gateway 网关会在隔离的 Docker 容器内运行智能体工具执行（shell、文件读写等），而 Gateway 网关本身仍留在主机上。这样可以在不将整个 Gateway 网关容器化的情况下，为不受信任或多租户的智能体会话提供一道硬隔离墙。
沙箱范围可以是按智能体（默认）、按会话或共享。每个范围
都会获得自己的工作区，并挂载到 `/workspace`。你还可以配置
允许/拒绝工具策略、网络隔离、资源限制和浏览器容器。
沙箱范围可以是每个智能体（默认）、每个会话或共享。每个范围都会获得自己的工作区，并挂载到 `/workspace`。你还可以配置允许/拒绝工具策略、网络隔离、资源限制和浏览器容器。
完整配置、镜像、安全注意事项和多智能体配置文件见：
有关完整配置、镜像、安全注意事项和多智能体配置文件，请参阅：
- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整沙箱参考
- [OpenShell](/zh-CN/gateway/openshell) -- 对沙箱容器的交互式 shell 访问
- [多智能体沙箱和工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 按智能体覆盖配置
- [Multi-Agent Sandbox and Tools](/zh-CN/tools/multi-agent-sandbox-tools) -- 每个智能体的覆盖项
### 快速启用
@ -437,43 +401,36 @@ Gateway 网关容器化，也能为不受信任或多租户的智能体会话提
}
```
构建默认沙箱镜像（从源码 checkout）：
构建默认沙箱镜像（从源码检出）：
```bash
scripts/sandbox-setup.sh
```
对于没有源码 checkout 的 npm 安装，请参阅 [沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)，了解内联 `docker build` 命令。
对于没有源码检出的 npm 安装，请参阅 [沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)，获取内联 `docker build` 命令。
## 故障排除
<AccordionGroup>
<Accordion title="镜像缺失或沙箱容器未启动">
使用
[`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh)
（源码 checkout）或 [沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup) 中的内联 `docker build` 命令（npm 安装）
构建沙箱镜像，
或将 `agents.defaults.sandbox.docker.image` 设置为你的自定义镜像。
容器会按会话按需自动创建。
使用 [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh)（源码检出）或 [沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup) 中的内联 `docker build` 命令（npm 安装）构建沙箱镜像，或者将 `agents.defaults.sandbox.docker.image` 设置为你的自定义镜像。
容器会按需为每个会话自动创建。
</Accordion>
<Accordion title="沙箱中的权限错误">
将 `docker.user` 设置为与你挂载的工作区所有权匹配的 UID:GID，
或对工作区文件夹执行 chown。
将 `docker.user` 设置为与你挂载的工作区所有权匹配的 UID:GID，或对工作区文件夹运行 chown。
</Accordion>
<Accordion title="在沙箱中找不到自定义工具">
OpenClaw 使用 `sh -lc`（登录 shell）运行命令，它会加载
`/etc/profile`，并可能重置 PATH。设置 `docker.env.PATH` 来前置你的
自定义工具路径，或在你的 Dockerfile 中的 `/etc/profile.d/` 下添加脚本。
OpenClaw 使用 `sh -lc`（登录 shell）运行命令，它会加载 `/etc/profile`，并可能重置 PATH。设置 `docker.env.PATH` 以前置你的自定义工具路径，或在 Dockerfile 中的 `/etc/profile.d/` 下添加脚本。
</Accordion>
<Accordion title="镜像构建期间因 OOM 被终止（exit 137）">
<Accordion title="镜像构建期间因 OOM 被终止（退出 137）">
VM 至少需要 2 GB RAM。使用更大的机器规格后重试。
</Accordion>
<Accordion title="Control UI 中显示未授权或需要配对">
获取新的 dashboard 链接并批准浏览器设备：
<Accordion title="Control UI 中未授权或需要配对">
获取新的仪表板链接并批准浏览器设备：
```bash
docker compose run --rm openclaw-cli dashboard --no-open
@ -485,7 +442,7 @@ scripts/sandbox-setup.sh
</Accordion>
<Accordion title="Gateway 网关目标显示 ws://172.x.x.x 或 Docker CLI 出现配对错误">
<Accordion title="Gateway 网关目标显示 ws://172.x.x.x，或 Docker CLI 出现配对错误">
重置 Gateway 网关模式和绑定：
```bash

282
docs/zh-CN/plugins/voice-call.md
View File

@ -1,23 +1,23 @@
---
read_when:
- 你想从 OpenClaw 发起外拨语音通话
- 你正在配置或开发语音通话插件
- 你需要电话通信中的实时语音或流式转写
- 你正在配置或开发 voice-call 插件
- 你需要在电话通信中使用实时语音或流式转录
sidebarTitle: Voice call
summary: 通过 Twilio、Telnyx 或 Plivo 发起外呼语音通话并接听呼入语音通话，可选择启用实时语音和流式转录
summary: 通过 Twilio、Telnyx 或 Plivo 发起外呼并接听呼入语音通话，可选择启用实时语音和流式转录
title: 语音通话插件
x-i18n:
generated_at: "2026-05-01T11:40:33Z"
generated_at: "2026-05-02T07:52:27Z"
model: gpt-5.5
provider: openai
source_hash: cde64fa054743d4ed3f146042bd65532af0e9eb5b792b088a856889b3d2cb3c9
source_hash: fc27646aca94c88d50d42838e166ac81eba3373154797cbb564e9c2eab0533fa
source_path: plugins/voice-call.md
workflow: 16
---
通过插件为 OpenClaw 提供语音通话。支持出站通知、
多轮对话、全双工实时语音、流式转写，
以及带有允许列表策略的入站通话。
多轮对话、全双工实时语音、流式
转录，以及带允许列表策略的入站通话。
**当前提供商：** `twilio`（Programmable Voice + Media Streams）、
`telnyx`（Call Control v2）、`plivo`（Voice API + XML transfer + GetInput
@ -48,26 +48,27 @@ Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件
</Tab>
</Tabs>
如果 npm 将 OpenClaw 拥有的软件包报告为已弃用，该软件包版本
来自较旧的外部软件包发布线；请使用当前打包的 OpenClaw
如果 npm 报告 OpenClaw 拥有的软件包已弃用，该软件包版本
来自较旧的外部软件包发布序列；请使用当前打包的 OpenClaw
构建，或在发布更新的 npm 软件包之前使用本地文件夹路径。
之后重启 Gateway 网关，以便插件加载。
之后重启 Gateway 网关，让插件加载。
</Step>
<Step title="配置提供商和 webhook">
在 `plugins.entries.voice-call.config` 下设置配置（完整结构见下方
在 `plugins.entries.voice-call.config` 下设置配置（完整结构请参见下方
[配置](#configuration)）。至少需要：
`provider`、提供商凭据、`fromNumber`，以及可公开访问的 webhook URL。
`provider`、提供商凭证、`fromNumber`，以及一个可公开
访问的 webhook URL。
</Step>
<Step title="验证设置">
```bash
openclaw voicecall setup
```
默认输出便于在聊天日志和终端中阅读。它会检查
插件启用状态、提供商凭据、webhook 暴露情况，以及是否
只有一种音频模式（`streaming` 或 `realtime`）处于激活状态。脚本请使用
默认输出适合在聊天日志和终端中阅读。它会检查
插件是否启用、提供商凭证、webhook 暴露情况，以及是否
只启用了一个音频模式（`streaming` 或 `realtime`）。脚本请使用
`--json`。
</Step>
@ -77,7 +78,7 @@ Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件
openclaw voicecall smoke --to "+15555550123"
```
两者默认都是空运行。添加 `--yes` 可实际发起一次短的
两者默认都是试运行。添加 `--yes` 会实际发起一次简短的
出站通知通话：
```bash
@ -88,21 +89,21 @@ Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件
</Steps>
<Warning>
对于 Twilio、Telnyx 和 Plivo，设置必须解析到一个**公开 webhook URL**。
如果 `publicUrl`、隧道 URL、Tailscale URL 或服务回退
解析到 loopback 或专用网络空间，设置会失败，而不是
对于 Twilio、Telnyx 和 Plivo，设置必须解析到一个 **公开 webhook URL**。
如果 `publicUrl`、隧道 URL、Tailscale URL 或 serve 回退地址
解析到回环地址或私有网络空间，设置会失败，而不是
启动一个无法接收运营商 webhook 的提供商。
</Warning>
## 配置
如果 `enabled: true` 但选定的提供商缺少凭据，
Gateway 网关启动时会记录 setup-incomplete 警告，其中包含缺失键名，
并跳过运行时启动。命令、RPC 调用和智能体工具在使用时仍会
如果 `enabled: true`，但所选提供商缺少凭证，
Gateway 网关启动时会记录一条设置未完成警告，其中包含缺失的键名，并
跳过启动运行时。命令、RPC 调用和智能体工具在使用时仍会
返回确切缺失的提供商配置。
<Note>
语音通话凭据接受 SecretRefs。`plugins.entries.voice-call.config.twilio.authToken`、`plugins.entries.voice-call.config.realtime.providers.*.apiKey`、`plugins.entries.voice-call.config.streaming.providers.*.apiKey` 和 `plugins.entries.voice-call.config.tts.providers.*.apiKey` 会通过标准 SecretRef 界面解析；请参阅 [SecretRef 凭据界面](/zh-CN/reference/secretref-credential-surface)。
语音通话凭证接受 SecretRefs。`plugins.entries.voice-call.config.twilio.authToken`、`plugins.entries.voice-call.config.realtime.providers.*.apiKey`、`plugins.entries.voice-call.config.streaming.providers.*.apiKey` 和 `plugins.entries.voice-call.config.tts.providers.*.apiKey` 会通过标准 SecretRef 表面解析；请参见 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。
</Note>
```json5
@ -115,6 +116,7 @@ Gateway 网关启动时会记录 setup-incomplete 警告，其中包含缺失键
provider: "twilio", // or "telnyx" | "plivo" | "mock"
fromNumber: "+15550001234", // or TWILIO_FROM_NUMBER for Twilio
toNumber: "+15550005678",
sessionScope: "per-phone", // per-phone | per-call
twilio: {
accountSid: "ACxxxxxxxx",
@ -165,18 +167,18 @@ Gateway 网关启动时会记录 setup-incomplete 警告，其中包含缺失键
<AccordionGroup>
<Accordion title="提供商暴露和安全说明">
- Twilio、Telnyx 和 Plivo 都要求 webhook URL **可公开访问**。
- `mock` 是本地开发提供商（不进行网络调用）。
- Telnyx 要求 `telnyx.publicKey`（或 `TELNYX_PUBLIC_KEY`），除非 `skipSignatureVerification` 为 true。
- `mock` 是本地开发提供商（无网络调用）。
- Telnyx 要求设置 `telnyx.publicKey`（或 `TELNYX_PUBLIC_KEY`），除非 `skipSignatureVerification` 为 true。
- `skipSignatureVerification` 仅用于本地测试。
- 在 ngrok 免费层上，请将 `publicUrl` 设置为确切的 ngrok URL；签名验证始终强制执行。
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` 允许签名无效的 Twilio webhook，**仅**当 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地代理）时如此。仅限本地开发。
- Ngrok 免费层 URL 可能会变化或添加中间页行为；如果 `publicUrl` 漂移，Twilio 签名会失败。生产环境：优先使用稳定域名或 Tailscale funnel。
- 在 ngrok 免费层上，请将 `publicUrl` 设置为准确的 ngrok URL；始终强制执行签名验证。
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅当 `tunnel.provider="ngrok"` 且 `serve.bind` 是回环地址（ngrok 本地智能体）时，才允许带无效签名的 Twilio webhook。仅限本地开发。
- Ngrok 免费层 URL 可能变化或添加插页行为；如果 `publicUrl` 偏移，Twilio 签名会失败。生产环境：优先使用稳定域名或 Tailscale funnel。
</Accordion>
<Accordion title="流式连接上限">
- `streaming.preStartTimeoutMs` 会关闭从未发送有效 `start` 帧的套接字。
- `streaming.maxPendingConnections` 限制未认证预启动套接字的总数。
- `streaming.maxPendingConnectionsPerIp` 限制每个源 IP 的未认证预启动套接字数量。
- `streaming.maxPendingConnections` 限制未认证的预启动套接字总数。
- `streaming.maxPendingConnectionsPerIp` 限制每个来源 IP 的未认证预启动套接字数量。
- `streaming.maxConnections` 限制打开的媒体流套接字总数（待处理 + 活跃）。
</Accordion>
@ -184,8 +186,8 @@ Gateway 网关启动时会记录 setup-incomplete 警告，其中包含缺失键
使用 `provider: "log"`、`twilio.from` 或旧版
`streaming.*` OpenAI 键的较旧配置会由 `openclaw doctor --fix` 重写。
运行时回退目前仍接受旧的语音通话键，但
重写路径是 `openclaw doctor --fix`，兼容 shim
是临时的。
重写路径是 `openclaw doctor --fix`，并且兼容垫片是
临时的。
自动迁移的流式键：
@ -198,11 +200,19 @@ Gateway 网关启动时会记录 setup-incomplete 警告，其中包含缺失键
</Accordion>
</AccordionGroup>
## 会话范围
默认情况下，Voice Call 使用 `sessionScope: "per-phone"`，因此同一来电者的
重复来电会保留对话记忆。当每个运营商通话都应以全新上下文开始时，
请设置 `sessionScope: "per-call"`，例如前台接待、预订、IVR，
或 Google Meet 桥接流程，其中同一个电话号码可能
代表不同会议。
## 实时语音对话
`realtime` 会为实时通话音频选择一个全双工实时语音提供商。
它独立于 `streaming`，后者只会把音频转发给
实时转写提供商。
`realtime` 为实时通话音频选择一个全双工实时语音提供商。
它不同于 `streaming`，后者只会将音频转发给
实时转录提供商。
<Warning>
`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每次通话请选择一种
@ -212,13 +222,13 @@ Gateway 网关启动时会记录 setup-incomplete 警告，其中包含缺失键
当前运行时行为：
- Twilio Media Streams 支持 `realtime.enabled`。
- `realtime.provider` 是可选的。如果未设置，Voice Call 会使用第一个已注册的实时语音提供商。
- `realtime.provider` 是可选的。如果未设置，Voice Call 会使用第一个注册的实时语音提供商。
- 内置实时语音提供商：Google Gemini Live（`google`）和 OpenAI（`openai`），由各自的提供商插件注册。
- 提供商拥有的原始配置位于 `realtime.providers.<providerId>` 下。
- Voice Call 默认暴露共享的 `openclaw_agent_consult` 实时工具。当来电者要求更深入推理、当前信息或普通 OpenClaw 工具时，实时模型可以调用它。
- `realtime.fastContext.enabled` 默认关闭。启用后，Voice Call 会先针对 consult 问题搜索已索引的记忆/会话上下文，并在 `realtime.fastContext.timeoutMs` 内将这些片段返回给实时模型；只有当 `realtime.fastContext.fallbackToConsult` 为 true 时，才会回退到完整的 consult 智能体。
- Voice Call 默认暴露共享的 `openclaw_agent_consult` 实时工具。当来电者请求更深入推理、当前信息或常规 OpenClaw 工具时，实时模型可以调用它。
- `realtime.fastContext.enabled` 默认关闭。启用后，Voice Call 会先为 consult 问题搜索已索引的记忆/会话上下文，并在 `realtime.fastContext.timeoutMs` 内将这些片段返回给实时模型；只有当 `realtime.fastContext.fallbackToConsult` 为 true 时，才会回退到完整的 consult 智能体。
- 如果 `realtime.provider` 指向未注册的提供商，或根本没有注册实时语音提供商，Voice Call 会记录警告并跳过实时媒体，而不是让整个插件失败。
- Consult 会话键会在可用时复用现有语音会话，然后回退到主叫/被叫电话号码，以便后续 consult 调用在通话期间保留上下文。
- consult 会话键会在可用时复用已存储的通话会话，然后回退到配置的 `sessionScope`（默认为 `per-phone`，隔离通话为 `per-call`）。
### 工具策略
@ -226,7 +236,7 @@ Gateway 网关启动时会记录 setup-incomplete 警告，其中包含缺失键
| 策略 | 行为 |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `safe-read-only` | 暴露 consult 工具，并将常规智能体限制为 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 |
| `safe-read-only` | 暴露 consult 工具，并将常规智能体限制为使用 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 |
| `owner` | 暴露 consult 工具，并允许常规智能体使用正常的智能体工具策略。 |
| `none` | 不暴露 consult 工具。自定义 `realtime.tools` 仍会传递给实时提供商。 |
@ -235,8 +245,8 @@ Gateway 网关启动时会记录 setup-incomplete 警告，其中包含缺失键
<Tabs>
<Tab title="Google Gemini Live">
默认值：API key 来自 `realtime.providers.google.apiKey`、
`GEMINI_API_KEY` 或 `GOOGLE_GENERATIVE_AI_API_KEY`；模型为
`gemini-2.5-flash-native-audio-preview-12-2025`；语音为 `Kore`。
`GEMINI_API_KEY` 或 `GOOGLE_GENERATIVE_AI_API_KEY`；模型
`gemini-2.5-flash-native-audio-preview-12-2025`；语音 `Kore`。
```json5
{
@ -291,20 +301,20 @@ Gateway 网关启动时会记录 setup-incomplete 警告，其中包含缺失键
</Tab>
</Tabs>
提供商专属的实时语音选项见 [Google 提供商](/zh-CN/providers/google) 和
有关特定提供商的实时语音选项，请参见 [Google 提供商](/zh-CN/providers/google) 和
[OpenAI provider](/zh-CN/providers/openai)。
## 流式转写
## 流式转录
`streaming` 会为实时通话音频选择一个实时转写提供商。
`streaming` 为实时通话音频选择一个实时转录提供商。
当前运行时行为：
- `streaming.provider` 是可选的。如果未设置，Voice Call 会使用第一个已注册的实时转录提供商。
- 内置实时转录提供商：Deepgram (`deepgram`)、ElevenLabs (`elevenlabs`)、Mistral (`mistral`)、OpenAI (`openai`) 和 xAI (`xai`)，由它们各自的提供商插件注册。
- 内置实时转录提供商：Deepgram（`deepgram`）、ElevenLabs（`elevenlabs`）、Mistral（`mistral`）、OpenAI（`openai`）和 xAI（`xai`），由各自的提供商插件注册。
- 提供商拥有的原始配置位于 `streaming.providers.<providerId>` 下。
- Twilio 发送已接受的流 `start` 消息后，Voice Call 会立即注册该流，在提供商连接期间通过转录提供商排队处理入站媒体，并且只在实时转录就绪后才开始初始问候语。
- 如果 `streaming.provider` 指向未注册的提供商，或没有任何已注册的提供商，Voice Call 会记录一条警告并跳过媒体流式传输，而不是让整个插件失败。
- Twilio 发送已接受的流 `start` 消息后，Voice Call 会立即注册该流，在提供商连接期间通过转录提供商排队处理入站媒体，并且仅在实时转录就绪后才开始初始问候语。
- 如果 `streaming.provider` 指向未注册的提供商，或者没有任何提供商已注册，Voice Call 会记录警告并跳过媒体流式传输，而不是让整个插件失败。
### 流式传输提供商示例
@ -374,11 +384,9 @@ Gateway 网关启动时会记录 setup-incomplete 警告，其中包含缺失键
</Tab>
</Tabs>
## 通话 TTS
## 通话的 TTS
Voice Call 使用核心 `messages.tts` 配置为通话提供流式传输
语音。你可以在插件配置下用**相同结构**覆盖它，该配置会与
`messages.tts` 深度合并。
Voice Call 使用核心 `messages.tts` 配置为通话流式传输语音。你可以在插件配置下用**相同结构**覆盖它，它会与 `messages.tts` 深度合并。
```json5
{
@ -395,17 +403,16 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式传输
```
<Warning>
**语音通话会忽略 Microsoft speech。** 电话音频需要 PCM；
当前 Microsoft 传输协议未暴露电话 PCM 输出。
**Microsoft speech 会在语音通话中被忽略。** 电话音频需要 PCM；当前 Microsoft 传输未暴露电话 PCM 输出。
</Warning>
行为说明：
- 插件配置中的旧版 `tts.<provider>` 键（`openai`、`elevenlabs`、`microsoft`、`edge`）会由 `openclaw doctor --fix` 修复；提交的配置应使用 `tts.providers.<provider>`。
- 启用 Twilio 媒体流式传输时会使用核心 TTS；否则通话会回退到提供商原生语音。
- 如果 Twilio 媒体流已处于活动状态，Voice Call 不会回退到 TwiML `<Say>`。如果在该状态下电话 TTS 不可用，播放请求会失败，而不是混用两条播放路径。
- 当电话 TTS 回退到次要提供商时，Voice Call 会记录一条带有提供商链（`from`、`to`、`attempts`）的警告，便于调试。
- 当 Twilio 插话或流拆除清空待处理 TTS 队列时，已排队的播放请求会完成结算，而不是让等待播放完成的来电者一直挂起。
- 如果 Twilio 媒体流已处于活动状态，Voice Call 不会回退到 TwiML `<Say>`。如果在该状态下电话 TTS 不可用，播放请求会失败，而不是混合两条播放路径。
- 当电话 TTS 回退到次级提供商时，Voice Call 会记录带有提供商链（`from`、`to`、`attempts`）的警告，便于调试。
- 当 Twilio 插话或流拆除清空待处理 TTS 队列时，已排队的播放请求会完成结算，而不是让主叫方一直等待播放完成。
### TTS 示例
@ -474,7 +481,7 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式传输
## 入站通话
入站策略默认为 `disabled`。要启用入站通话，请设置：
入站策略默认值为 `disabled`。要启用入站通话，请设置：
```json5
{
@ -485,20 +492,14 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式传输
```
<Warning>
`inboundPolicy: "allowlist"` 是一种低保障级别的主叫号码筛选。
插件会规范化提供商提供的 `From` 值，并将其与
`allowFrom` 比较。Webhook 验证会认证提供商投递和
载荷完整性，但它**不会**证明 PSTN/VoIP 主叫号码
所有权。请将 `allowFrom` 视为主叫号码过滤，而不是强主叫方
身份认证。
`inboundPolicy: "allowlist"` 是低保障的主叫号码屏蔽机制。该插件会规范化提供商提供的 `From` 值，并将其与 `allowFrom` 比较。网络钩子验证会认证提供商投递和载荷完整性，但它**不能**证明 PSTN/VoIP 主叫号码所有权。请将 `allowFrom` 视为主叫号码过滤，而不是强主叫身份验证。
</Warning>
自动响应使用智能体系统。使用 `responseModel`、
`responseSystemPrompt` 和 `responseTimeoutMs` 进行调优。
自动响应使用智能体系统。使用 `responseModel`、`responseSystemPrompt` 和 `responseTimeoutMs` 调整。
### 语音输出契约
对于自动响应，Voice Call 会向系统提示追加严格的语音输出契约：
对于自动响应，Voice Call 会将严格的语音输出契约附加到系统提示词：
```text
{"spoken":"..."}
@ -510,37 +511,33 @@ Voice Call 会防御性地提取语音文本：
- 解析直接 JSON、围栏 JSON 或内联 `"spoken"` 键。
- 回退到纯文本，并移除可能的规划/元信息开头段落。
这会让语音播放聚焦于面向来电者的文本，并避免把规划文本泄露到音频中。
这会让语音播放聚焦于面向主叫方的文本，并避免将规划文本泄漏到音频中。
### 会话启动行为
### 对话启动行为
对于出站 `conversation` 通话，首条消息处理与实时
播放状态绑定：
对于出站 `conversation` 通话，首条消息处理与实时播放状态绑定：
- 仅在初始问候语正在主动播报时，才会抑制插话队列清空和自动响应。
- 如果初始播放失败，通话会返回 `listening`，并且初始消息会保持排队以便重试。
- Twilio 流式传输的初始播放会在流连接时启动，没有额外延迟。
- 插话会中止活动播放，并清空已排队但尚未播放的 Twilio TTS 条目。被清空的条目会解析为已跳过，因此后续响应逻辑可以继续，而不会等待永远不会播放的音频。
- 实时语音会话使用实时流自身的开场轮次。Voice Call **不会**为该初始消息发送旧版 `<Say>` TwiML 更新，因此出站 `<Connect><Stream>` 会话会保持附加状态。
- 仅当初始问候语正在主动发声时，才会抑制插话队列清空和自动响应。
- 如果初始播放失败，通话会返回 `listening`，并且初始消息仍会排队等待重试。
- Twilio 流式传输的初始播放会在流连接时开始，不会额外延迟。
- 插话会中止活动播放，并清空已排队但尚未播放的 Twilio TTS 条目。已清空条目会解析为已跳过，因此后续响应逻辑可以继续，而无需等待永远不会播放的音频。
- 实时语音对话使用实时流自身的开场轮次。Voice Call **不会**为该初始消息发布旧版 `<Say>` TwiML 更新，因此出站 `<Connect><Stream>` 会话会保持附着。
### Twilio 流断开宽限期
当 Twilio 媒体流断开连接时，Voice Call 会等待 **2000 ms** 后
自动结束通话：
当 Twilio 媒体流断开时，Voice Call 会等待 **2000 ms** 后再自动结束通话：
- 如果流在该窗口内重新连接，则会取消自动结束。
- 如果该窗口期间流重新连接，自动结束会被取消。
- 如果宽限期后没有流重新注册，则会结束通话，以防止活动通话卡住。
## 过期通话清理器
使用 `staleCallReaperSeconds` 结束从未收到终止
webhook 的通话（例如永不完成的通知模式通话）。默认值
为 `0`（禁用）。
使用 `staleCallReaperSeconds` 结束从未收到终止网络钩子的通话（例如永不完成的通知模式通话）。默认值为 `0`（禁用）。
推荐范围：
- **生产：** 对通知类流程使用 `120`–`300` 秒。
- 保持此值**高于 `maxDurationSeconds`**，以便正常通话可以完成。一个不错的起点是 `maxDurationSeconds + 30–60` 秒。
- 保持该值**高于 `maxDurationSeconds`**，以便正常通话可以完成。一个好的起点是 `maxDurationSeconds + 30–60` 秒。
```json5
{
@ -557,10 +554,9 @@ webhook 的通话（例如永不完成的通知模式通话）。默认值
}
```
## Webhook 安全
## 网络钩子安全
当代理或隧道位于 Gateway 网关 前面时，插件会
重建用于签名验证的公共 URL。这些选项控制信任哪些转发标头：
当代理或隧道位于 Gateway 网关 前面时，该插件会重建公共 URL 以进行签名验证。这些选项控制信任哪些转发标头：
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
允许来自转发标头的主机列表。
@ -569,17 +565,17 @@ webhook 的通话（例如永不完成的通知模式通话）。默认值
在没有允许列表的情况下信任转发标头。
</ParamField>
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
仅当请求远程 IP 与列表匹配时才信任转发标头。
仅当请求远程 IP 匹配列表时才信任转发标头。
</ParamField>
额外保护：
其他保护：
- 已为 Twilio 和 Plivo 启用 Webhook **重放保护**。重放的有效 webhook 请求会被确认，但会跳过副作用。
- Twilio 会话轮次在 `<Gather>` 回调中包含每轮 token，因此过期/重放的语音回调无法满足较新的待处理转录轮次。
- 当缺少提供商所需的签名标头时，未认证的 webhook 请求会在读取正文前被拒绝。
- voice-call webhook 使用共享的预认证正文配置（64 KB / 5 秒），并在签名验证前加入按 IP 计的并发上限。
- Twilio 和 Plivo 已启用网络钩子**重放保护**。重放的有效网络钩子请求会被确认，但会跳过副作用。
- Twilio 对话轮次在 `<Gather>` 回调中包含每轮令牌，因此过期/重放的语音回调无法满足较新的待处理转录轮次。
- 当缺少提供商要求的签名标头时，未经认证的网络钩子请求会在读取正文之前被拒绝。
- voice-call 网络钩子使用共享的预认证正文配置（64 KB / 5 秒），并在签名验证前增加按 IP 的进行中请求上限。
使用稳定公共主机的示例：
具有稳定公共主机的示例：
```json5
{
@ -613,20 +609,15 @@ openclaw voicecall latency # summarize turn latency from lo
openclaw voicecall expose --mode funnel
```
当 Gateway 网关 已在运行时，操作性 `voicecall` 命令会委托给
Gateway 网关 拥有的 voice-call 运行时，这样 CLI 就不会绑定第二个
webhook 服务器。如果无法访问任何 Gateway 网关，这些命令会回退到
独立 CLI 运行时。
当 Gateway 网关 已经运行时，操作性 `voicecall` 命令会委托给 Gateway 网关 拥有的 voice-call 运行时，因此 CLI 不会绑定第二个网络钩子服务器。如果无法访问 Gateway 网关，这些命令会回退到独立 CLI 运行时。
`latency` 会从默认 voice-call 存储路径读取 `calls.jsonl`。
使用 `--file <path>` 指向不同日志，使用 `--last <n>` 将
分析限制为最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的 p50/p90/p99。
`latency` 会从默认 voice-call 存储路径读取 `calls.jsonl`。使用 `--file <path>` 指向不同日志，并使用 `--last <n>` 将分析限制到最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的 p50/p90/p99。
## 智能体工具
工具名称：`voice_call`。
| 操作 | 参数 |
| 操作 | 参数 |
| --------------- | ------------------------------------------ |
| `initiate_call` | `message`, `to?`, `mode?`, `dtmfSequence?` |
| `continue_call` | `callId`, `message` |
@ -635,11 +626,11 @@ webhook 服务器。如果无法访问任何 Gateway 网关，这些命令会回
| `end_call` | `callId` |
| `get_status` | `callId` |
此仓库在 `skills/voice-call/SKILL.md` 提供匹配的 skill 文档。
此仓库在 `skills/voice-call/SKILL.md` 提供了匹配的 Skills 文档。
## Gateway 网关 RPC
| 方法 | 参数 |
| 方法 | 参数 |
| -------------------- | ------------------------------------------ |
| `voicecall.initiate` | `to?`, `message`, `mode?`, `dtmfSequence?` |
| `voicecall.continue` | `callId`, `message` |
@ -648,25 +639,31 @@ webhook 服务器。如果无法访问任何 Gateway 网关，这些命令会回
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
`dtmfSequence` 仅在 `mode: "conversation"` 下有效。通知模式通话
如果需要连接后的按键数字，应在通话存在后使用 `voicecall.dtmf`。
`dtmfSequence` 仅在 `mode: "conversation"` 下有效。通知模式通话如果需要连接后数字，应在通话存在后使用 `voicecall.dtmf`。
## 故障排除
### 设置 webhook 暴露失败
### 设置网络钩子暴露失败
从运行 Gateway 网关的同一环境中运行设置：
从运行 Gateway 网关的同一环境运行设置：
```bash
openclaw voicecall setup
openclaw voicecall setup --json
```
对于 `twilio`、`telnyx` 和 `plivo`，`webhook-exposure` 必须为绿色。已配置的 `publicUrl` 如果指向本地或私有网络空间，仍会失败，因为运营商无法回调这些地址。不要将 `localhost`、`127.0.0.1`、`0.0.0.0`、`10.x`、`172.16.x`-`172.31.x`、`192.168.x`、`169.254.x`、`fc00::/7` 或 `fd00::/8` 用作 `publicUrl`。
对于 `twilio`、`telnyx` 和 `plivo`，`webhook-exposure` 必须为绿色状态。已
配置的 `publicUrl` 如果指向本地或私有网络空间，仍会失败，因为运营商无法回调到这些地址。不要将
`localhost`、`127.0.0.1`、`0.0.0.0`、`10.x`、`172.16.x`-`172.31.x`、
`192.168.x`、`169.254.x`、`fc00::/7` 或 `fd00::/8` 用作 `publicUrl`。
Twilio notify-mode 外呼会在创建呼叫请求中直接发送初始 `<Say>` TwiML，因此第一条语音消息不依赖 Twilio 获取 webhook TwiML。状态回调、对话呼叫、连接前 DTMF、实时流和连接后呼叫控制仍然需要公共 webhook。
Twilio notify-mode 出站呼叫会在
创建呼叫请求中直接发送其初始 `<Say>` TwiML，因此第一条语音消息不依赖于 Twilio
获取 webhook TwiML。状态回调、
会话呼叫、连接前 DTMF、实时流和连接后呼叫
控制仍然需要公共 webhook。
使用一种公共暴露路径：
使用一个公共暴露路径：
```json5
{
@ -693,21 +690,25 @@ openclaw voicecall setup
openclaw voicecall smoke
```
除非你传入 `--yes`，否则 `voicecall smoke` 是一次 dry run。
除非传入 `--yes`，否则 `voicecall smoke` 是一次试运行。
### 提供商凭证失败
检查所选提供商和必需的凭证字段：
检查所选提供商以及必需的凭证字段：
- Twilio：`twilio.accountSid`、`twilio.authToken` 和 `fromNumber`，或 `TWILIO_ACCOUNT_SID`、`TWILIO_AUTH_TOKEN` 和 `TWILIO_FROM_NUMBER`。
- Telnyx：`telnyx.apiKey`、`telnyx.connectionId`、`telnyx.publicKey` 和 `fromNumber`。
- Twilio：`twilio.accountSid`、`twilio.authToken` 和 `fromNumber`，或
`TWILIO_ACCOUNT_SID`、`TWILIO_AUTH_TOKEN` 和 `TWILIO_FROM_NUMBER`。
- Telnyx：`telnyx.apiKey`、`telnyx.connectionId`、`telnyx.publicKey` 和
`fromNumber`。
- Plivo：`plivo.authId`、`plivo.authToken` 和 `fromNumber`。
凭证必须存在于 Gateway 网关主机上。编辑本地 shell profile 不会影响已经运行的 Gateway 网关，直到它重启或重新加载其环境。
凭证必须存在于 Gateway 网关主机上。编辑本地 shell profile
不会影响已经运行的 Gateway 网关，直到它重启或重新加载其
环境。
### 呼叫开始但提供商 webhook 未到达
### 呼叫已开始但提供商 webhook 未到达
确认提供商控制台指向确切的公共 webhook URL：
确认提供商控制台指向准确的公共 webhook URL：
```text
https://voice.example.com/voice/webhook
@ -729,56 +730,71 @@ openclaw logs --follow
- 防火墙或 DNS 将公共主机名路由到了 Gateway 网关以外的位置。
- Gateway 网关重启时未启用 Voice Call 插件。
当反向代理或隧道位于 Gateway 网关前面时，将 `webhookSecurity.allowedHosts` 设置为公共主机名，或对已知代理地址使用 `webhookSecurity.trustedProxyIPs`。仅当代理边界受你控制时，才使用 `webhookSecurity.trustForwardingHeaders`。
当 Gateway 网关前面有反向代理或隧道时，将
`webhookSecurity.allowedHosts` 设置为公共主机名，或对已知代理地址使用
`webhookSecurity.trustedProxyIPs`。仅当代理边界在你的
控制之下时，才使用 `webhookSecurity.trustForwardingHeaders`。
### 签名验证失败
提供商签名会根据 OpenClaw 从传入请求重建的公共 URL 进行检查。如果签名失败：
- 确认提供商 webhook URL 与 `publicUrl` 完全匹配，包括 scheme、host 和 path。
- 对于 ngrok 免费层 URL，当隧道主机名变化时更新 `publicUrl`。
- 确保代理保留原始 host 和 proto 标头，或配置 `webhookSecurity.allowedHosts`。
- 不要在本地测试以外启用 `skipSignatureVerification`。
- 确认提供商 webhook URL 与 `publicUrl` 完全匹配，包括
scheme、host 和 path。
- 对于 ngrok 免费层 URL，在隧道主机名变化时更新 `publicUrl`。
- 确保代理保留原始 host 和 proto 标头，或配置
`webhookSecurity.allowedHosts`。
- 不要在本地测试之外启用 `skipSignatureVerification`。
### Google Meet Twilio 加入失败
Google Meet 使用此插件执行 Twilio 拨入加入。先验证 Voice Call：
Google Meet 使用此插件进行 Twilio 拨入加入。先验证 Voice Call：
```bash
openclaw voicecall setup
openclaw voicecall smoke --to "+15555550123"
```
然后显式验证 Google Meet 传输：
然后显式验证 Google Meet 传输协议：
```bash
openclaw googlemeet setup --transport twilio
```
如果 Voice Call 为绿色，但 Meet 参与者从未加入，请检查 Meet 拨入号码、PIN 和 `--dtmf-sequence`。电话呼叫可以是正常的，而会议可能拒绝或忽略不正确的 DTMF 序列。
如果 Voice Call 为绿色状态，但 Meet 参与者从未加入，请检查 Meet
拨入号码、PIN 和 `--dtmf-sequence`。电话呼叫可以是正常的，而
会议可能会拒绝或忽略不正确的 DTMF 序列。
Google Meet 会将 Meet DTMF 序列和介绍文本传递给 `voicecall.start`。对于 Twilio 呼叫，Voice Call 先提供 DTMF TwiML，重定向回 webhook，然后打开实时媒体流，以便在电话参与者加入会议后生成已保存的介绍。
Google Meet 会将 Meet DTMF 序列和介绍文本传递给 `voicecall.start`。
对于 Twilio 呼叫，Voice Call 会先提供 DTMF TwiML，重定向回
webhook，然后打开实时媒体流，以便在电话参与者加入会议后
生成保存的介绍文本。
使用 `openclaw logs --follow` 查看实时阶段跟踪。健康的 Twilio Meet 加入会按此顺序记录日志：
使用 `openclaw logs --follow` 查看实时阶段跟踪。健康的 Twilio Meet
加入会按以下顺序记录日志：
- Google Meet 将 Twilio 加入委托给 Voice Call。
- Voice Call 存储连接前 DTMF TwiML。
- Twilio 初始 TwiML 在实时处理前被消费并提供。
- Twilio 初始 TwiML 在实时处理之前被消费并提供。
- Voice Call 为 Twilio 呼叫提供实时 TwiML。
- 实时桥接启动，并将初始问候语排入队列。
- 实时桥接启动，并将初始问候语加入队列。
`openclaw voicecall tail` 仍会显示持久化的呼叫记录；它对呼叫状态和转录很有用，但并非每个 webhook/实时转换都会出现在那里。
`openclaw voicecall tail` 仍会显示持久化的呼叫记录；它适用于
呼叫状态和转录文本，但并非每个 webhook/实时转换都会
出现在其中。
### 实时呼叫没有语音
确认只启用了一种音频模式。`realtime.enabled` 和 `streaming.enabled` 不能同时为 true。
确认只启用了一种音频模式。`realtime.enabled` 和
`streaming.enabled` 不能同时为 true。
对于实时 Twilio 呼叫，还要验证：
- 已加载并注册实时提供商插件。
- `realtime.provider` 未设置，或命名了已注册的提供商。
- Gateway 网关进程可以使用提供商 API key。
- `openclaw logs --follow` 显示已提供实时 TwiML、实时桥接已启动，并且初始问候语已排入队列。
- 提供商 API key 可供 Gateway 网关进程使用。
- `openclaw logs --follow` 显示已提供实时 TwiML、实时桥接
已启动，并且初始问候语已加入队列。
## 相关内容

132
docs/zh-CN/tools/acp-agents-setup.md
View File

@ -1,36 +1,36 @@
---
read_when:
- 为 Claude Code / Codex / Gemini CLI 安装或配置 acpx 运行框架
- 安装或配置用于 Claude Code / Codex / Gemini CLI 的 acpx 运行框架
- 启用 plugin-tools 或 OpenClaw-tools MCP 桥接
- 配置 ACP 权限模式
summary: 设置 ACP 智能体：acpx harness 配置、插件设置、权限
title: ACP 智能体 — 设置
x-i18n:
generated_at: "2026-05-02T06:10:01Z"
generated_at: "2026-05-02T07:52:27Z"
model: gpt-5.5
provider: openai
source_hash: 4426219227e77d5dc57039c0c8f7324590388db141689239deaa2441609f4afd
source_hash: 92a53744f13ad4301d40c04dd28bbc28ca9d0a21070c20ddbda55ae9f6673001
source_path: tools/acp-agents-setup.md
workflow: 16
---
有关概览、操作员运行手册和概念，请参阅 [ACP 智能体](/zh-CN/tools/acp-agents)。
概览、操作员运行手册和概念请参阅 [ACP 智能体](/zh-CN/tools/acp-agents)。
以下章节介绍 acpx harness 配置、MCP bridge 的插件设置，以及权限配置。
以下章节涵盖 acpx harness 配置、MCP bridge 的插件设置，以及权限配置。
仅在设置 ACP/acpx 路由时使用本页。对于原生 Codex
仅在你设置 ACP/acpx 路线时使用本页。对于原生 Codex
app-server 运行时配置，请使用 [Codex harness](/zh-CN/plugins/codex-harness)。对于
OpenAI API key 或 Codex OAuth 模型提供商配置，请使用
[OpenAI](/zh-CN/providers/openai)。
Codex 有两条 OpenClaw 路由：
Codex 有两条 OpenClaw 路线：
| 路由 | 配置/命令 | 设置页面 |
| 路线 | 配置/命令 | 设置页面 |
| -------------------------- | ------------------------------------------------------ | --------------------------------------- |
| 原生 Codex app-server | `/codex ...`, `agentRuntime.id: "codex"` | [Codex harness](/zh-CN/plugins/codex-harness) |
| 显式 Codex ACP 适配器 | `/acp spawn codex`, `runtime: "acp", agentId: "codex"` | 本页 |
除非你明确需要 ACP/acpx 行为，否则优先使用原生路由。
除非你明确需要 ACP/acpx 行为，否则优先使用原生路线。
## acpx harness 支持（当前）
@ -51,13 +51,13 @@ Codex 有两条 OpenClaw 路由：
- `pi`
- `qwen`
当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义智能体别名，否则 `agentId` 优先使用这些值。
如果你的本地 Cursor 安装仍以 `agent acp` 暴露 ACP，请在你的 acpx 配置中覆盖 `cursor` 智能体命令，而不是更改内置默认值。
当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义智能体别名，否则优先将这些值用于 `agentId`。
如果你的本地 Cursor 安装仍然以 `agent acp` 暴露 ACP，请在你的 acpx 配置中覆盖 `cursor` 智能体命令，而不是更改内置默认值。
直接使用 acpx CLI 时，也可以通过 `--agent <command>` 指向任意适配器，但这个原始逃生口是 acpx CLI 功能（不是常规 OpenClaw `agentId` 路径）。
直接使用 acpx CLI 也可以通过 `--agent <command>` 指向任意适配器，但该原始逃生口是 acpx CLI 功能（不是常规的 OpenClaw `agentId` 路径）。
模型控制取决于适配器能力。Codex ACP 模型引用会在启动前由
OpenClaw 规范化。其他 harness 需要 ACP `models` 加上
OpenClaw 规范化。其他 harness 需要 ACP `models` 加
`session/set_model` 支持；如果某个 harness 既不暴露该 ACP 能力，
也没有自己的启动模型标志，OpenClaw/acpx 就无法强制选择模型。
@ -101,7 +101,7 @@ OpenClaw 规范化。其他 harness 需要 ACP `models` 加上
}
```
线程绑定配置取决于渠道适配器。Discord 示例：
线程绑定配置特定于渠道适配器。Discord 示例：
```json5
{
@ -123,34 +123,41 @@ OpenClaw 规范化。其他 harness 需要 ACP `models` 加上
}
```
如果线程绑定的 ACP 生成无法工作，请先验证适配器功能标志：
如果线程绑定的 ACP spawn 不工作，请先验证适配器功能标志：
- Discord：`channels.discord.threadBindings.spawnSessions=true`
当前会话绑定不需要创建子线程。它们需要一个活跃的会话上下文，以及一个暴露 ACP 会话绑定的渠道适配器。
当前对话绑定不需要创建子线程。它们需要一个活跃的对话上下文，以及一个暴露 ACP 对话绑定的渠道适配器。
请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。
## acpx 后端的插件设置
全新安装会默认启用内置的 `acpx` 运行时插件，因此 ACP
通常无需手动安装插件即可工作。
打包安装使用官方 `@openclaw/acpx` 运行时插件来支持 ACP。
请先安装并启用它，然后再使用 ACP harness 会话：
从以下命令开始：
```bash
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
```
源码 checkout 也可以在 `pnpm install` 后使用本地工作区插件。
从这里开始：
```text
/acp doctor
```
如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者想
切换到本地开发检出版本，请使用显式插件路径：
如果你禁用了 `acpx`，通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者想
切回打包插件，请使用显式包路径：
```bash
openclaw plugins install acpx
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
```
开发期间安装本地工作区：
开发期间的本地工作区安装：
```bash
openclaw plugins install ./path/to/local/acpx-plugin
@ -164,9 +171,9 @@ openclaw plugins install ./path/to/local/acpx-plugin
### acpx 命令和版本配置
默认情况下，内置的 `acpx` 插件会注册嵌入式 ACP 后端，而不会在
Gateway 网关启动期间生成 ACP 智能体。运行 `/acp doctor` 可执行显式
实时探测。仅在你需要 Gateway 网关于启动时探测已配置智能体时，才设置
默认情况下，`acpx` 插件会注册嵌入式 ACP 后端，而不会在
Gateway 网关启动期间 spawn ACP 智能体。运行 `/acp doctor` 进行显式
实时探测。仅当你需要 Gateway 网关在启动时探测配置的智能体时，才设置
`OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=1`。
在插件配置中覆盖命令或版本：
@ -187,7 +194,7 @@ Gateway 网关启动期间生成 ACP 智能体。运行 `/acp doctor` 可执行
}
```
- `command` 接受绝对路径、相对路径（从 OpenClaw 工作区解析）或命令名称。
- `command` 接受绝对路径、相对路径（从 OpenClaw 工作区解析）或命令名。
- `expectedVersion: "any"` 会禁用严格版本匹配。
- 自定义 `command` 路径会禁用插件本地自动安装。
@ -196,61 +203,62 @@ Gateway 网关启动期间生成 ACP 智能体。运行 `/acp doctor` 可执行
### 自动依赖安装
当你使用 `npm install -g openclaw` 全局安装 OpenClaw 时，acpx
运行时依赖项（特定于平台的二进制文件）会通过 postinstall 钩子自动安装。
运行时依赖（平台特定的二进制文件）会通过 postinstall hook 自动安装。
如果自动安装失败，Gateway 网关仍会正常启动，并通过 `openclaw acp doctor`
报告缺失的依赖项。
报告缺失的依赖。
### 插件工具 MCP bridge
默认情况下，ACPX 会话**不会**向 ACP harness 暴露 OpenClaw 插件注册的工具。
默认情况下，ACPX 会话**不会**向
ACP harness 暴露 OpenClaw 插件注册的工具。
如果你希望 Codex 或 Claude Code 等 ACP 智能体调用已安装的
OpenClaw 插件工具，例如记忆召回/存储，请启用专用 bridge：
OpenClaw 插件工具，例如 memory recall/store，请启用专用 bridge：
```bash
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
```
这会执行以下操作：
它会执行以下操作：
- 将名为 `openclaw-plugin-tools` 的内置 MCP 服务器注入 ACPX 会话
- 将一个名为 `openclaw-plugin-tools` 的内置 MCP server 注入 ACPX 会话
bootstrap。
- 暴露已由安装并启用的 OpenClaw
插件注册的插件工具。
- 保持该功能为显式启用且默认关闭。
- 暴露由已安装且已启用的 OpenClaw
插件已经注册的插件工具。
- 使该功能保持显式启用且默认关闭。
安全和信任说明：
- 这会扩大 ACP harness 工具面。
- 这会扩大 ACP harness 的工具表面。
- ACP 智能体只能访问 Gateway 网关中已处于活动状态的插件工具。
- 请将这视为与允许这些插件在
- 将其视为与允许这些插件在
OpenClaw 本身中执行相同的信任边界。
- 启用前请审查已安装的插件。
- 启用前请审查已安装插件。
自定义 `mcpServers` 仍会像以前一样工作。内置插件工具 bridge 是一项
额外的可选便利功能，不是通用 MCP 服务器配置的替代品。
自定义 `mcpServers` 仍会像以前一样工作。内置 plugin-tools bridge 是一个
额外的可选便利功能，不是通用 MCP server 配置的替代品。
### OpenClaw 工具 MCP bridge
默认情况下，ACPX 会话也**不会**通过
MCP 暴露内置 OpenClaw 工具。当 ACP 智能体需要选定的
内置工具（例如 `cron`）时，请启用单独的核心工具 bridge：
内置工具（例如 `cron`）时，启用单独的 core-tools bridge：
```bash
openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
```
这会执行以下操作：
它会执行以下操作：
- 将名为 `openclaw-tools` 的内置 MCP 服务器注入 ACPX 会话
- 将一个名为 `openclaw-tools` 的内置 MCP server 注入 ACPX 会话
bootstrap。
- 暴露选定的内置 OpenClaw 工具。初始服务器暴露 `cron`。
- 保持核心工具暴露为显式启用且默认关闭。
- 暴露选定的内置 OpenClaw 工具。初始 server 暴露 `cron`。
- 使核心工具暴露保持显式启用且默认关闭。
### 运行时超时配置
内置 `acpx` 插件默认将嵌入式运行时轮次设为 120 秒
超时。这会给 Gemini CLI 等较慢的 harness 足够时间完成
`acpx` 插件默认将嵌入式运行时 turn 的超时设置为 120 秒。
这让 Gemini CLI 等较慢的 harness 有足够时间完成
ACP 启动和初始化。如果你的主机需要不同的
运行时限制，请覆盖它：
@ -262,10 +270,10 @@ openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
### 健康探测智能体配置
当 `/acp doctor` 或可选启用的启动探测检查后端时，内置
当 `/acp doctor` 或可选的启动探测检查后端时，内置
`acpx` 插件会探测一个 harness 智能体。如果设置了 `acp.allowedAgents`，它
默认使用第一个允许的智能体；否则默认使用 `codex`。如果你的
部署需要使用不同的 ACP 智能体进行健康检查，请显式设置探测智能体：
部署需要为健康检查使用不同的 ACP 智能体，请显式设置探测智能体：
```bash
openclaw config set plugins.entries.acpx.config.probeAgent claude
@ -275,27 +283,27 @@ openclaw config set plugins.entries.acpx.config.probeAgent claude
## 权限配置
ACP 会话以非交互方式运行，没有 TTY 可用于批准或拒绝文件写入和 shell 执行权限提示。acpx 插件提供两个配置键，用于控制权限处理方式：
ACP 会话以非交互方式运行，没有 TTY 可用于批准或拒绝文件写入和 shell-exec 权限提示。acpx 插件提供两个配置键，用于控制权限的处理方式：
这些 ACPX harness 权限独立于 OpenClaw exec approvals，也独立于 CLI 后端供应商绕过标志，例如 Claude CLI `--permission-mode bypassPermissions`。ACPX `approve-all` 是 ACP 会话的 harness 级紧急开关。
这些 ACPX harness 权限独立于 OpenClaw exec 批准，也独立于 CLI 后端供应商绕过标志，例如 Claude CLI `--permission-mode bypassPermissions`。ACPX `approve-all` 是 ACP 会话的 harness 级紧急开关。
### `permissionMode`
控制 harness 智能体可以在无提示的情况下执行哪些操作。
控制 harness 智能体可以在不提示的情况下执行哪些操作。
| 值 | 行为 |
| --------------- | ----------------------------------------- |
| `approve-all` | 自动批准所有文件写入和 shell 命令。 |
| `approve-reads` | 仅自动批准读取；写入和执行需要提示。 |
| `deny-all` | 拒绝所有权限提示。 |
| `approve-all` | 自动批准所有文件写入和 shell 命令。 |
| `approve-reads` | 仅自动批准读取；写入和 exec 需要提示。 |
| `deny-all` | 拒绝所有权限提示。 |
### `nonInteractivePermissions`
控制在应显示权限提示但没有可用交互式 TTY 时会发生什么（这始终适用于 ACP 会话）。
控制本应显示权限提示但没有可用交互式 TTY 时会发生什么（ACP 会话始终如此）。
| 值 | 行为 |
| ------ | ------------------------------------------------------------------ |
| `fail` | 使用 `AcpRuntimeError` 中止会话。**（默认）** |
| 值 | 行为 |
| ------ | ----------------------------------------------------------------- |
| `fail` | 以 `AcpRuntimeError` 中止会话。**（默认）** |
| `deny` | 静默拒绝权限并继续（优雅降级）。 |
### 配置
@ -310,9 +318,9 @@ openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
更改这些值后请重启 Gateway 网关。
<Warning>
OpenClaw 默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互式 ACP 会话中，任何触发权限提示的写入或执行都可能以 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` 失败。
OpenClaw 默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互式 ACP 会话中，任何触发权限提示的写入或 exec 都可能因 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` 而失败。
如果你需要限制权限，请将 `nonInteractivePermissions` 设为 `deny`，这样会话会优雅降级而不是崩溃。
如果你需要限制权限，请将 `nonInteractivePermissions` 设置为 `deny`，让会话优雅降级，而不是崩溃。
</Warning>
## 相关内容

595
docs/zh-CN/tools/acp-agents.md
View File

@ -3,64 +3,67 @@ read_when:
- 通过 ACP 运行编码执行框架
- 在消息渠道上设置对话绑定的 ACP 会话
- 将消息渠道对话绑定到持久 ACP 会话
- 故障排除：ACP 后端、插件接入或补全投递
- ACP 后端、插件接入或补全结果传递的故障排除
- 在聊天中操作 /acp 命令
sidebarTitle: ACP agents
summary: 通过 ACP 后端运行外部编码运行框架（Claude Code、Cursor、Gemini CLI、显式 Codex ACP、OpenClaw ACP、OpenCode）
summary: 通过 ACP 后端运行外部编码 harness（Claude Code、Cursor、Gemini CLI、显式 Codex ACP、OpenClaw ACP、OpenCode）
title: ACP 智能体
x-i18n:
generated_at: "2026-05-02T06:11:02Z"
generated_at: "2026-05-02T07:52:47Z"
model: gpt-5.5
provider: openai
source_hash: 36a1c58b22d0f615e20e84fcdb15c39800825ee0bad64c966d6f14d44d3c1458
source_hash: ec2404924cbb4c4cd0d94485bc7d8ea586c0ef5f4380e72d5212c8bd9d868c20
source_path: tools/acp-agents.md
workflow: 16
---
[智能体客户端协议（ACP）](https://agentclientprotocol.com/) 会话
让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、
[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话
让 OpenClaw 通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、
Cursor、Copilot、Droid、OpenClaw ACP、OpenCode、Gemini CLI，以及其他
受支持的 ACPX harness）。
每次 ACP 会话生成都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。
每次 ACP 会话生成都会作为[后台任务](/zh-CN/automation/tasks)跟踪。
<Note>
**ACP 是外部 harness 路径，不是默认的 Codex 路径。** 原生
Codex app-server 插件负责 `/codex ...` 控制项和
**ACP 是外部 harness 路径，不是默认 Codex 路径。** 原生 Codex app-server 插件负责 `/codex ...` 控制和
`agentRuntime.id: "codex"` 嵌入式运行时；ACP 负责
`/acp ...` 控制项和 `sessions_spawn({ runtime: "acp" })` 会话。
`/acp ...` 控制和 `sessions_spawn({ runtime: "acp" })` 会话。
如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的
OpenClaw 渠道对话，请使用
如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 OpenClaw 渠道会话，请使用
[`openclaw mcp serve`](/zh-CN/cli/mcp)，而不是 ACP。
</Note>
## 我需要哪个页面？
## 我应该看哪个页面？
| 你想要… | 使用 | 备注 |
| 你想要… | 使用 | 说明 |
| ----------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 在当前对话中绑定或控制 Codex | `/codex bind`, `/codex threads` | 启用 `codex` 插件时的原生 Codex app-server 路径；包括绑定聊天回复、图片转发、模型/快速模式/权限、停止和引导控制。ACP 是显式回退路径 |
| 通过 OpenClaw 运行 Claude Code、Gemini CLI、显式 Codex ACP，或其他外部 harness | 本页 | 绑定到聊天的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 |
| 将 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端通过 stdio/WebSocket 使用 ACP 与 OpenClaw 通信 |
| 将本地 AI CLI 复用为纯文本回退模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制项、没有 harness 运行时 |
| 在当前对话中绑定或控制 Codex | `/codex bind`、`/codex threads` | 启用 `codex` 插件时的原生 Codex app-server 路径；包括绑定聊天回复、图片转发、模型/快速/权限、停止和 steer 控制。ACP 是显式回退 |
| 通过 OpenClaw 运行 Claude Code、Gemini CLI、显式 Codex ACP，或其他外部 harness | 本页 | 聊天绑定会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 |
| 将 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端通过 stdio/WebSocket 与 OpenClaw 使用 ACP 通信 |
| 将本地 AI CLI 复用为纯文本回退模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具，没有 ACP 控制，没有 harness 运行时 |
## 这能开箱即用吗？
## 这个开箱即用吗？
通常可以。全新安装会默认启用内置的 `acpx` 运行时插件，并附带一个插件本地固定版本的
`acpx` 二进制文件；OpenClaw 会在 Gateway 网关 HTTP 监听器就绪后立即探测并自修复它。运行
`/acp doctor` 进行就绪检查。
是的，安装官方 ACP 运行时插件后即可：
只有在 ACP **确实可用** 时，OpenClaw 才会教智能体如何生成 ACP：必须启用
ACP，分发不能被禁用，当前会话不能被沙箱阻止，并且必须已加载运行时后端。如果不满足这些条件，ACP 插件 Skills 和
`sessions_spawn` ACP 指引会保持隐藏，这样智能体就不会建议不可用的后端。
```bash
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
```
源码检出可以在 `pnpm install` 后使用本地 `extensions/acpx` 工作区插件。运行 `/acp doctor` 进行就绪检查。
只有当 ACP **真正可用**时，OpenClaw 才会向智能体说明 ACP 生成：ACP 必须已启用，dispatch 不能被禁用，当前
会话不能被沙箱阻止，并且必须已加载运行时后端。如果这些条件不满足，ACP 插件 Skills 和
`sessions_spawn` ACP 指导会保持隐藏，这样智能体就不会建议不可用的后端。
<AccordionGroup>
<Accordion title="首次运行注意事项">
- 如果设置了 `plugins.allow`，它就是限制性的插件清单，并且**必须**包含 `acpx`；否则内置默认项会被有意阻止，`/acp doctor` 会报告缺少 allowlist 条目。
- 内置 Codex ACP 适配器会随 `acpx` 插件暂存，并在可行时本地启动。
- 其他目标 harness 适配器在你首次使用时可能仍会按需通过 `npx` 获取。
- 该 harness 的厂商凭证仍必须存在于主机上。
- 如果主机没有 npm 或网络访问权限，首次运行的适配器获取会失败，直到缓存被预热，或适配器以其他方式安装。
- 如果设置了 `plugins.allow`，它就是一个限制性插件清单，且**必须**包含 `acpx`；否则已安装的 ACP 后端会被有意阻止，`/acp doctor` 会报告缺少 allowlist 条目。
- Codex ACP 适配器会随 `acpx` 插件一起预置，并在可行时本地启动。
- 其他目标 harness 适配器首次使用时仍可能按需通过 `npx` 获取。
- 该 harness 的供应商凭证仍必须存在于主机上。
- 如果主机没有 npm 或网络访问，首次运行的适配器获取会失败，直到缓存被预热或通过其他方式安装适配器。
</Accordion>
<Accordion title="运行时前提条件">
@ -68,71 +71,70 @@ ACP，分发不能被禁用，当前会话不能被沙箱阻止，并且必须
后台任务状态、投递、绑定和策略；harness 负责其提供商登录、
模型目录、文件系统行为和原生工具。
在归咎于 OpenClaw 之前，请验证：
在归因于 OpenClaw 之前，请先验证：
- `/acp doctor` 报告后端已启用且健康。
- 设置 `acp.allowedAgents` allowlist 时，目标 id 已被允许。
- 设置了 `acp.allowedAgents` allowlist 时，目标 id 被允许。
- harness 命令可以在 Gateway 网关主机上启动。
- 该 harness 的提供商凭证已存在（`claude`、`codex`、`gemini`、`opencode`、`droid` 等）。
- 所选模型对该 harness 存在，模型 id 不能跨 harness 移植。
- 该 harness 已存在提供商凭证（`claude`、`codex`、`gemini`、`opencode`、`droid` 等）。
- 所选模型存在于该 harness 中，模型 id 不能跨 harness 通用。
- 请求的 `cwd` 存在且可访问，或省略 `cwd` 并让后端使用其默认值。
- 权限模式与工作匹配。非交互式会话无法点击原生权限提示，因此写入/执行密集型编码运行通常需要一个可以无界面继续执行的 ACPX 权限配置文件。
- 权限模式与工作匹配。非交互式会话无法点击原生权限提示，因此写入/执行密集型编码运行通常需要一个可以无头继续执行的 ACPX 权限配置。
</Accordion>
</AccordionGroup>
OpenClaw 插件工具和内置 OpenClaw 工具默认**不会**暴露给
ACP harness。仅当 harness 应直接调用这些工具时，才在
[ACP 智能体 - 设置](/zh-CN/tools/acp-agents-setup) 中启用显式 MCP 桥接。
OpenClaw 插件工具和内置 OpenClaw 工具默认**不会**暴露给 ACP harness。仅当 harness 应直接调用这些工具时，才在
[ACP 智能体——设置](/zh-CN/tools/acp-agents-setup)中启用显式 MCP 桥接。
## 受支持的 harness 目标
## 支持的 harness 目标
使用内置 `acpx` 后端时，可将这些 harness id 用作 `/acp spawn <id>`
或 `sessions_spawn({ runtime: "acp", agentId: "<id>" })` 目标：
使用 `acpx` 后端时，将这些 harness id 用作 `/acp spawn <id>` 或
`sessions_spawn({ runtime: "acp", agentId: "<id>" })` 目标：
| Harness id | 典型后端 | 备注 |
| Harness id | 典型后端 | 说明 |
| ---------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- |
| `claude` | Claude Code ACP 适配器 | 需要主机上有 Claude Code 凭证。 |
| `codex` | Codex ACP 适配器 | 仅在原生 `/codex` 不可用或请求 ACP 时作为显式 ACP 回退。 |
| `copilot` | GitHub Copilot ACP 适配器 | 需要 Copilot CLI/运行时凭证。 |
| `cursor` | Cursor CLI ACP (`cursor-agent acp`) | 如果本地安装暴露了不同的 ACP 入口点，请覆盖 acpx 命令。 |
| `claude` | Claude Code ACP 适配器 | 需要主机上有 Claude Code 凭证。 |
| `codex` | Codex ACP 适配器 | 仅在原生 `/codex` 不可用或请求 ACP 时作为显式 ACP 回退。 |
| `copilot` | GitHub Copilot ACP 适配器 | 需要 Copilot CLI/运行时凭证。 |
| `cursor` | Cursor CLI ACP（`cursor-agent acp`） | 如果本地安装暴露了不同的 ACP 入口点，请覆盖 acpx 命令。 |
| `droid` | Factory Droid CLI | 需要 Factory/Droid 凭证，或 harness 环境中的 `FACTORY_API_KEY`。 |
| `gemini` | Gemini CLI ACP 适配器 | 需要 Gemini CLI 凭证或 API key 设置。 |
| `gemini` | Gemini CLI ACP 适配器 | 需要 Gemini CLI 凭证或 API key 设置。 |
| `iflow` | iFlow CLI | 适配器可用性和模型控制取决于已安装的 CLI。 |
| `kilocode` | Kilo Code CLI | 适配器可用性和模型控制取决于已安装的 CLI。 |
| `kimi` | Kimi/Moonshot CLI | 需要主机上有 Kimi/Moonshot 凭证。 |
| `kiro` | Kiro CLI | 适配器可用性和模型控制取决于已安装的 CLI。 |
| `opencode` | OpenCode ACP 适配器 | 需要 OpenCode CLI/提供商凭证。 |
| `opencode` | OpenCode ACP 适配器 | 需要 OpenCode CLI/提供商凭证。 |
| `openclaw` | 通过 `openclaw acp` 的 OpenClaw Gateway 网关桥接 | 让支持 ACP 的 harness 回连到 OpenClaw Gateway 网关会话。 |
| `pi` | Pi/嵌入式 OpenClaw 运行时 | 用于 OpenClaw 原生 harness 实验。 |
| `qwen` | Qwen Code / Qwen CLI | 需要主机上有兼容 Qwen 的凭证。 |
| `pi` | Pi/嵌入式 OpenClaw 运行时 | 用于 OpenClaw 原生 harness 实验。 |
| `qwen` | Qwen Code / Qwen CLI | 需要主机上有 Qwen 兼容凭证。 |
可以在 acpx 自身中配置自定义 acpx 智能体别名，但 OpenClaw
策略在分发前仍会检查 `acp.allowedAgents` 以及任何
自定义 acpx 智能体别名可以在 acpx 本身中配置，但 OpenClaw 策略在 dispatch 前仍会检查 `acp.allowedAgents` 和任何
`agents.list[].runtime.acp.agent` 映射。
## 操作员运行手册
从聊天发起的快速 `/acp` 流程：
从聊天快速使用 `/acp` 的流程：
<Steps>
<Step title="生成">
`/acp spawn claude --bind here`,
`/acp spawn claude --bind here`、
`/acp spawn gemini --mode persistent --thread auto`，或显式
`/acp spawn codex --bind here`。
</Step>
<Step title="工作">
在绑定的对话或线程中继续（或显式指定会话键）。
在已绑定的对话或话题中继续（或显式指定会话
key）。
</Step>
<Step title="检查状态">
`/acp status`
</Step>
<Step title="调优">
`/acp model <provider/model>`,
`/acp permissions <profile>`,
`/acp model <provider/model>`、
`/acp permissions <profile>`、
`/acp timeout <seconds>`。
</Step>
<Step title="引导">
<Step title="Steer">
不替换上下文：`/acp steer tighten logging and continue`。
</Step>
<Step title="停止">
@ -142,103 +144,103 @@ ACP harness。仅当 harness 应直接调用这些工具时，才在
<AccordionGroup>
<Accordion title="生命周期详情">
- 生成会创建或恢复 ACP 运行时会话，将 ACP 元数据记录到 OpenClaw 会话存储中，并且当运行由父级拥有时可能创建后台任务。
- 即使运行时会话是持久的，父级拥有的 ACP 会话也会被视为后台工作；完成和跨界面投递会通过父任务通知器进行，而不是像普通面向用户的聊天会话那样处理。
- 任务维护会关闭终止态或孤立的父级拥有的一次性 ACP 会话。只要仍存在活动对话绑定，持久 ACP 会话就会保留；没有活动绑定的陈旧持久会话会被关闭，这样在所属任务完成或其任务记录消失后，它们就不能被静默恢复。
- 绑定的后续消息会直接发送到 ACP 会话，直到绑定被关闭、取消聚焦、重置或过期。
- Gateway 网关命令保持本地处理。`/acp ...`、`/status` 和 `/unfocus` 永远不会作为普通提示文本发送给绑定的 ACP harness。
- 当后端支持取消时，`cancel` 会中止当前轮次；它不会删除绑定或会话元数据。
- `close` 会从 OpenClaw 视角结束 ACP 会话并移除绑定。如果 harness 支持恢复，它可能仍会保留自己的上游历史。
- 空闲运行时 worker 在 `acp.runtime.ttlMinutes` 之后符合清理条件；存储的会话元数据仍可用于 `/acp sessions`。
- 生成会创建或恢复一个 ACP 运行时会话，在 OpenClaw 会话存储中记录 ACP 元数据，并且当运行由父级拥有时，可能会创建后台任务。
- 即使运行时会话是持久的，父级拥有的 ACP 会话也会被视为后台工作；完成和跨界面投递会通过父任务通知器进行，而不是像普通的面向用户聊天会话那样处理。
- 任务维护会关闭终态或孤立的父级拥有一次性 ACP 会话。只要仍有活跃对话绑定，持久 ACP 会话就会保留；没有活跃绑定的陈旧持久会话会被关闭，避免其在拥有任务完成或任务记录消失后被静默恢复。
- 绑定后的后续消息会直接发送到 ACP 会话，直到绑定被关闭、取消聚焦、重置或过期。
- Gateway 网关命令保持本地执行。`/acp ...`、`/status` 和 `/unfocus` 永远不会作为普通提示文本发送给已绑定的 ACP harness。
- 当后端支持取消时，`cancel` 会中止活跃轮次；它不会删除绑定或会话元数据。
- `close` 会从 OpenClaw 视角结束 ACP 会话并移除绑定。如果 harness 支持恢复，它仍可能保留自己的上游历史。
- 空闲运行时 worker 可在 `acp.runtime.ttlMinutes` 后被清理；已存储的会话元数据仍可用于 `/acp sessions`。
</Accordion>
<Accordion title="原生 Codex 路由规则">
当启用**原生 Codex
插件**时，应路由到它的自然语言触发语句：
启用时应路由到**原生 Codex
插件**的自然语言触发示例：
- “将这个 Discord 渠道绑定到 Codex。”
- “将这个聊天附加到 Codex 线程 `<id>`。”
- “显示 Codex 线程，然后绑定这个线程。”
- “将此聊天附加到 Codex 话题 `<id>`。”
- “显示 Codex 话题，然后绑定这个。”
原生 Codex 对话绑定是默认的聊天控制路径。
原生 Codex 对话绑定是默认聊天控制路径。
OpenClaw 动态工具仍通过 OpenClaw 执行，而
shell/apply-patch 等 Codex 原生工具会在 Codex 内部执行。
对于 Codex 原生工具事件，OpenClaw 会注入一个按轮次生效的原生
钩子中继，使插件钩子可以阻止 `before_tool_call`、观察
shell/apply-patch 等 Codex 原生工具在 Codex 内部执行。
对于 Codex 原生工具事件，OpenClaw 会注入按轮次的原生
hook relay，使插件钩子可以阻止 `before_tool_call`，观察
`after_tool_call`，并通过 OpenClaw 审批路由 Codex `PermissionRequest` 事件。
Codex `Stop` 钩子会被中继到
OpenClaw `before_agent_finalize`，插件可在那里请求在 Codex 最终确定回答之前再进行一次
模型传递。该中继保持刻意保守：它不会改变 Codex 原生工具
参数，也不会重写 Codex 线程记录。只有在你需要 ACP 运行时/会话模型时，
才使用显式 ACP。嵌入式 Codex
支持边界记录在
[Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
Codex `Stop` 钩子会中继到 OpenClaw `before_agent_finalize`，
插件可以在那里请求在 Codex 最终确定答案之前再进行一次
模型调用。该中继刻意保持保守：它不会修改 Codex 原生工具
参数，也不会重写 Codex 话题记录。只有当你需要 ACP 运行时/会话模型时，
才使用显式 ACP。嵌入式 Codex 支持边界记录在
[Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)中。
</Accordion>
<Accordion title="模型 / 提供商 / 运行时选择速查表">
- `openai-codex/*` — PI Codex OAuth/订阅路由。
- `openai/*` 加 `agentRuntime.id: "codex"` — 原生 Codex 应用服务器嵌入式运行时。
- `openai/*` 加 `agentRuntime.id: "codex"` — 原生 Codex app-server 嵌入式运行时。
- `/codex ...` — 原生 Codex 对话控制。
- `/acp ...` 或 `runtime: "acp"` — 显式 ACP/acpx 控制。
</Accordion>
<Accordion title="ACP 路由自然语言触发语">
应路由到 ACP 运行时的触发语：
<Accordion title="ACP 路由自然语言触发词">
应路由到 ACP 运行时的触发词：
- "Run this as a one-shot Claude Code ACP session and summarize the result."
- "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread."
- "Run Codex through ACP in a background thread."
- “将此作为一次性 Claude Code ACP 会话运行，并总结结果。”
- “在一个线程中使用 Gemini CLI 处理此任务，然后将后续跟进保留在同一线程中。”
- “通过 ACP 在后台线程中运行 Codex。”
OpenClaw 选择 `runtime: "acp"`，解析 harness `agentId`，
在支持时绑定到当前对话或话题串，并将后续消息路由到该会话，直到关闭/过期。
只有在显式使用 ACP/acpx，或原生 Codex 插件不适用于请求的操作时，
Codex 才会走这条路径。
OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，
在支持时绑定到当前对话或线程，并将后续跟进路由到该会话，
直到关闭或过期。只有在明确使用 ACP/acpx，或原生 Codex
插件不适用于请求的操作时，Codex 才会走这条路径。
对于 `sessions_spawn`，只有在 ACP 已启用、请求方未被沙箱隔离，
且已加载 ACP 运行时后端时，才会公布 `runtime: "acp"`。
`acp.dispatch.enabled=false` 会暂停自动 ACP 话题串调度，
但不会隐藏或阻止显式的 `sessions_spawn({ runtime: "acp" })` 调用。
它以 `codex`、`claude`、`droid`、`gemini` 或 `opencode` 等 ACP harness id 为目标。
不要传入来自 `agents_list` 的普通 OpenClaw 配置智能体 id，
除非该条目已显式配置为 `agents.list[].runtime.type="acp"`；
否则请使用默认子智能体运行时。当 OpenClaw 智能体配置了
`runtime.type="acp"` 时，OpenClaw 会使用 `runtime.acp.agent`
作为底层 harness id。
对于 `sessions_spawn`，只有在 ACP
已启用、请求方未处于沙箱隔离状态，且已加载 ACP 运行时
后端时，才会发布 `runtime: "acp"`。`acp.dispatch.enabled=false` 会暂停自动
ACP 线程分派，但不会隐藏或阻止显式
`sessions_spawn({ runtime: "acp" })` 调用。它面向 `codex`、
`claude`、`droid`、`gemini` 或 `opencode` 等 ACP harness id。不要传入来自
`agents_list` 的普通 OpenClaw 配置智能体 id，除非该条目已使用
`agents.list[].runtime.type="acp"` 显式配置；
否则请使用默认子智能体运行时。当 OpenClaw 智能体
配置为 `runtime.type="acp"` 时，OpenClaw 会使用
`runtime.acp.agent` 作为底层 harness id。
</Accordion>
</AccordionGroup>
## ACP 与子智能体
当你需要外部 harness 运行时时使用 ACP。当 `codex`
插件已启用，且需要 Codex 对话绑定/控制时，使用**原生 Codex
应用服务器**。当你需要 OpenClaw 原生的委托运行时，使用**子智能体**。
当你需要外部 harness 运行时时，请使用 ACP。当 `codex`
插件已启用，且你需要 Codex 对话绑定/控制时，请使用**原生 Codex
app-server**。当你需要 OpenClaw 原生委托运行时，请使用**子智能体**。
| 领域 | ACP 会话 | 子智能体运行 |
| 区域 | ACP 会话 | 子智能体运行 |
| ------------- | ------------------------------------- | ---------------------------------- |
| 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 |
| 会话键 | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| 主命令 | `/acp ...` | `/subagents ...` |
| 生成工具 | 带 `runtime:"acp"` 的 `sessions_spawn` | `sessions_spawn`（默认运行时） |
| 主要命令 | `/acp ...` | `/subagents ...` |
| 生成工具 | `sessions_spawn` 搭配 `runtime:"acp"` | `sessions_spawn`（默认运行时） |
另请参阅[子智能体](/zh-CN/tools/subagents)。
## ACP 如何运行 Claude Code
通过 ACP 运行 Claude Code 时，栈如下：
对于通过 ACP 运行的 Claude Code，栈如下：
1. OpenClaw ACP 会话控制平面。
2. 内置 `acpx` 运行时插件。
2. 官方 `@openclaw/acpx` 运行时插件。
3. Claude ACP 适配器。
4. Claude 侧运行时/会话机制。
ACP Claude 是一个带有 ACP 控制、会话恢复、后台任务跟踪，
以及可选对话/话题串绑定的 **harness 会话**。
ACP Claude 是一个 **harness 会话**，具备 ACP 控制、会话恢复、
后台任务跟踪，以及可选的对话/线程绑定。
CLI 后端是独立的纯文本本地回退运行时 — 请参阅
[CLI 后端](/zh-CN/gateway/cli-backends)。
对运维者来说，实用规则是：
对操作人员而言，实用规则是：
- **需要 `/acp spawn`、可绑定会话、运行时控制，或持久 harness 工作？** 使用 ACP。
- **需要通过原始 CLI 进行简单本地文本回退？** 使用 CLI 后端。
@ -247,63 +249,64 @@ CLI 后端是独立的纯文本本地回退运行时 — 请参阅
### 心智模型
- **聊天界面** — 人们持续对话的位置（Discord 渠道、Telegram 话题、iMessage 聊天）。
- **聊天表面** — 人们持续交谈的位置（Discord 渠道、Telegram 话题、iMessage 聊天）。
- **ACP 会话** — OpenClaw 路由到的持久 Codex/Claude/Gemini 运行时状态。
- **子话题串/话题** — 仅由 `--thread ...` 创建的可选额外消息界面。
- **运行时工作区** — harness 运行所在的文件系统位置（`cwd`、仓库检出、后端工作区）。它独立于聊天界面。
- **子线程/话题** — 仅由 `--thread ...` 创建的可选额外消息表面。
- **运行时工作区** — harness 运行所在的文件系统位置（`cwd`、仓库检出、后端工作区）。它独立于聊天表面。
### 当前对话绑定
`/acp spawn <harness> --bind here` 会将当前对话固定到已生成的
ACP 会话 — 不创建子话题串，使用同一聊天界面。OpenClaw 继续负责
传输、认证、安全和投递。该对话中的后续消息会路由到同一会话；
`/new` 和 `/reset` 会在原位置重置会话；`/acp close` 会移除绑定。
`/acp spawn <harness> --bind here` 会将当前对话固定到
生成的 ACP 会话 — 不创建子线程，使用同一个聊天表面。OpenClaw 继续
负责传输、凭证、安全和交付。该对话中的后续消息会路由到
同一个会话；`/new` 和 `/reset` 会原地重置
会话；`/acp close` 会移除绑定。
示例：
```text
/codex bind # 原生 Codex 绑定，将未来消息路由到这里
/codex model gpt-5.4 # 调整已绑定的原生 Codex 话题串
/codex stop # 控制当前活跃的原生 Codex 轮次
/codex model gpt-5.4 # 调整已绑定的原生 Codex 线程
/codex stop # 控制活动的原生 Codex 轮次
/acp spawn codex --bind here # Codex 的显式 ACP 回退
/acp spawn codex --thread auto # 可能创建子话题串/话题并绑定到那里
/acp spawn codex --bind here --cwd /workspace/repo # 同一聊天绑定，Codex 在 /workspace/repo 中运行
/acp spawn codex --thread auto # 可创建子线程/话题并绑定到那里
/acp spawn codex --bind here --cwd /workspace/repo # 相同聊天绑定，Codex 在 /workspace/repo 中运行
```
<AccordionGroup>
<Accordion title="绑定规则与排他性">
<Accordion title="绑定规则和互斥性">
- `--bind here` 和 `--thread ...` 互斥。
- `--bind here` 仅适用于声明支持当前对话绑定的渠道；否则 OpenClaw 会返回清晰的不支持消息。绑定会跨 Gateway 网关重启保留。
- 在 Discord 上，`spawnSessions` 会门控 `--thread auto|here` 的子话题串创建 — 不门控 `--bind here`。
- 如果你在没有 `--cwd` 的情况下生成到另一个 ACP 智能体，OpenClaw 默认继承**目标智能体**的工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会表现为生成错误。
- Gateway 网关管理命令在已绑定对话中保持本地处理 — 即使普通后续文本会路由到已绑定的 ACP 会话，`/acp ...` 命令也由 OpenClaw 处理；只要该界面启用了命令处理，`/status` 和 `/unfocus` 也会保持本地处理。
- `--bind here` 仅适用于声明支持当前对话绑定的渠道；否则 OpenClaw 会返回明确的不支持消息。绑定会在 Gateway 网关重启后保留。
- 在 Discord 上，`spawnSessions` 会限制 `--thread auto|here` 的子线程创建 — 不限制 `--bind here`。
- 如果你在未指定 `--cwd` 的情况下生成到另一个 ACP 智能体，OpenClaw 默认继承**目标智能体**的工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为生成错误浮现。
- Gateway 网关管理命令在绑定对话中保持本地处理 — 即使普通后续文本会路由到绑定的 ACP 会话，`/acp ...` 命令仍由 OpenClaw 处理；只要该表面启用了命令处理，`/status` 和 `/unfocus` 也会保持本地处理。
</Accordion>
<Accordion title="话题串绑定会话">
当某个渠道适配器启用话题串绑定时：
<Accordion title="线程绑定会话">
当渠道适配器启用线程绑定时：
- OpenClaw 将话题串绑定到目标 ACP 会话。
- 该话题串中的后续消息会路由到已绑定的 ACP 会话。
- ACP 输出会投递回同一话题串。
- 取消聚焦/关闭/归档/空闲超时或最大存活时间过期会移除绑定。
- `/acp close`、`/acp cancel`、`/acp status`、`/status` 和 `/unfocus` 是 Gateway 网关命令，不是发给 ACP harness 的提示词。
- OpenClaw 会将一个线程绑定到目标 ACP 会话。
- 该线程中的后续消息会路由到绑定的 ACP 会话。
- ACP 输出会送回同一线程。
- 取消聚焦/关闭/归档/空闲超时或最大时长过期会移除绑定。
- `/acp close`、`/acp cancel`、`/acp status`、`/status` 和 `/unfocus` 是 Gateway 网关命令，不是发给 ACP harness 的提示。
话题串绑定 ACP 所需的功能标志：
线程绑定 ACP 所需功能标志：
- `acp.enabled=true`
- `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停自动 ACP 话题串调度；显式 `sessions_spawn({ runtime: "acp" })` 调用仍可工作）。
- 已启用渠道适配器话题串会话生成（默认值：`true`）：
- `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停自动 ACP 线程分派；显式 `sessions_spawn({ runtime: "acp" })` 调用仍可工作）。
- 已启用渠道适配器线程会话生成（默认值：`true`）：
- Discord：`channels.discord.threadBindings.spawnSessions=true`
- Telegram：`channels.telegram.threadBindings.spawnSessions=true`
话题串绑定支持因适配器而异。如果当前活跃的渠道
适配器不支持话题串绑定，OpenClaw 会返回清晰的
线程绑定支持因适配器而异。如果活动渠道
适配器不支持线程绑定，OpenClaw 会返回明确的
不支持/不可用消息。
</Accordion>
<Accordion title="支持话题串的渠道">
- 任何暴露会话/话题串绑定能力的渠道适配器。
- 当前内置支持：**Discord** 话题串/渠道、**Telegram** 话题（群组/超级群组中的论坛话题，以及私信话题）。
<Accordion title="支持线程的渠道">
- 任何公开会话/线程绑定能力的渠道适配器。
- 当前内置支持：**Discord** 线程/渠道、**Telegram** 话题（群组/超级群组中的论坛话题和私信话题）。
- 插件渠道可以通过同一绑定接口添加支持。
</Accordion>
@ -311,41 +314,42 @@ ACP 会话 — 不创建子话题串，使用同一聊天界面。OpenClaw 继
## 持久渠道绑定
对于非临时工作流，在顶层 `bindings[]` 条目中配置持久 ACP 绑定。
对于非临时工作流，请在顶层 `bindings[]` 条目中
配置持久 ACP 绑定。
### 绑定模型
<ParamField path="bindings[].type" type='"acp"'>
标记持久 ACP 对话绑定。
标记一个持久 ACP 对话绑定。
</ParamField>
<ParamField path="bindings[].match" type="object">
标识目标对话。各渠道形状：
标识目标对话。各渠道形状如下：
- **Discord 渠道/话题串：** `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- **Discord 渠道/线程：** `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- **Telegram 论坛话题：** `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- **BlueBubbles 私信/群组：** `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`。稳定的群组绑定优先使用 `chat_id:*` 或 `chat_identifier:*`。
- **iMessage 私信/群组：** `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`。稳定的群组绑定优先使用 `chat_id:*`。
- **BlueBubbles 私信/群组：** `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`。对于稳定的群组绑定，优先使用 `chat_id:*` 或 `chat_identifier:*`。
- **iMessage 私信/群组：** `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`。对于稳定的群组绑定，优先使用 `chat_id:*`。
</ParamField>
<ParamField path="bindings[].agentId" type="string">
所属 OpenClaw 智能体 id。
</ParamField>
<ParamField path="bindings[].acp.mode" type='"persistent" | "oneshot"'>
可选 ACP 覆盖项。
可选 ACP 覆盖。
</ParamField>
<ParamField path="bindings[].acp.label" type="string">
面向操作员的可选标签。
可选的面向操作人员的标签。
</ParamField>
<ParamField path="bindings[].acp.cwd" type="string">
可选运行时工作目录。
</ParamField>
<ParamField path="bindings[].acp.backend" type="string">
可选后端覆盖项。
可选后端覆盖。
</ParamField>
### 每个智能体的运行时默认值
使用 `agents.list[].runtime` 为每个智能体一次性定义 ACP 默认值：
使用 `agents.list[].runtime` 为每个智能体定义一次 ACP 默认值：
- `agents.list[].runtime.type="acp"`
- `agents.list[].runtime.acp.agent`（harness id，例如 `codex` 或 `claude`）
@ -441,20 +445,21 @@ ACP 会话 — 不创建子话题串，使用同一聊天界面。OpenClaw 继
### 行为
- OpenClaw 会确保已配置的 ACP 会话在使用前存在。
- 该渠道或话题中的消息会路由到已配置的 ACP 会话。
- 在已绑定对话中，`/new` 和 `/reset` 会在原位置重置同一个 ACP 会话键。
- 临时运行时绑定（例如由话题串聚焦流程创建的绑定）在存在时仍会生效。
- 对于没有显式 `cwd` 的跨智能体 ACP 生成，OpenClaw 会从智能体配置中继承目标智能体工作区。
- 缺失的继承工作区路径会回退到后端默认 cwd；非缺失的访问失败会表现为生成错误。
- OpenClaw 会确保配置的 ACP 会话在使用前存在。
- 该渠道或话题中的消息会路由到配置的 ACP 会话。
- 在绑定对话中，`/new` 和 `/reset` 会原地重置同一个 ACP 会话键。
- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍会应用。
- 对于未显式指定 `cwd` 的跨智能体 ACP 生成，OpenClaw 会从智能体配置继承目标智能体工作区。
- 缺失的继承工作区路径会回退到后端默认 cwd；非缺失的访问失败会作为生成错误浮现。
## 启动 ACP 会话
启动 ACP 会话有两种方式：
<Tabs>
<Tab title="来自 sessions_spawn">
使用 `runtime: "acp"` 从智能体轮次或工具调用启动 ACP 会话。
<Tab title="从 sessions_spawn">
使用 `runtime: "acp"` 从智能体轮次或
工具调用启动 ACP 会话。
```json
{
@ -467,11 +472,14 @@ ACP 会话 — 不创建子话题串，使用同一聊天界面。OpenClaw 继
```
<Note>
`runtime` 默认为 `subagent`，因此对于 ACP 会话，请显式设置 `runtime: "acp"`。如果省略 `agentId`，OpenClaw 会在配置后使用 `acp.defaultAgent`。`mode: "session"` 需要 `thread: true`，以保持持久绑定的对话。
`runtime` 默认为 `subagent`，因此对于 ACP 会话要显式设置
`runtime: "acp"`。如果省略 `agentId`，OpenClaw 会在已配置时使用
`acp.defaultAgent`。`mode: "session"` 需要
`thread: true`，以保持一个持久绑定的对话。
</Note>
</Tab>
<Tab title="来自 /acp 命令">
<Tab title="From /acp command">
使用 `/acp spawn` 从聊天中进行显式操作员控制。
```text
@ -500,40 +508,56 @@ ACP 会话 — 不创建子话题串，使用同一聊天界面。OpenClaw 继
发送到 ACP 会话的初始提示。
</ParamField>
<ParamField path="runtime" type='"acp"' required>
对于 ACP 会话，必须是 `"acp"`。
对于 ACP 会话必须是 `"acp"`。
</ParamField>
<ParamField path="agentId" type="string">
ACP 目标 harness ID。如果设置了 `acp.defaultAgent`，则回退到该值。
ACP 目标 harness id。如果已设置，则回退到 `acp.defaultAgent`。
</ParamField>
<ParamField path="thread" type="boolean" default="false">
在支持的位置请求线程绑定流程。
在支持的地方请求线程绑定流程。
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
`"run"` 是一次性的；`"session"` 是持久的。如果 `thread: true` 且省略 `mode`，OpenClaw 可能会根据运行时路径默认采用持久行为。`mode: "session"` 需要 `thread: true`。
`"run"` 是一次性运行；`"session"` 是持久运行。如果 `thread: true` 且
省略 `mode`，OpenClaw 可能会根据运行时路径默认使用持久行为。
`mode: "session"` 需要 `thread: true`。
</ParamField>
<ParamField path="cwd" type="string">
请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP 启动会在配置后继承目标 Agent 工作区；缺失的继承路径会回退到后端默认值，而真实的访问错误会被返回。
请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP spawn
会在配置后继承目标 Agent 工作区；缺失的继承路径会回退到后端默认值，
而真实访问错误会被返回。
</ParamField>
<ParamField path="label" type="string">
用于会话/横幅文本的面向操作员的标签。
用于会话/banner 文本的操作员可见标签。
</ParamField>
<ParamField path="resumeSessionId" type="string">
恢复现有 ACP 会话，而不是创建新会话。该智能体会通过 `session/load` 重放其对话历史。需要 `runtime: "acp"`。
恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load`
重放其对话历史。需要 `runtime: "acp"`。
</ParamField>
<ParamField path="streamTo" type='"parent"'>
`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式传回请求方会话。接受的响应包括 `streamLogPath`，它指向会话作用域的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以 tail 它来查看完整中继历史。
`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式传回请求者会话。
接受的响应包含 `streamLogPath`，它指向一个会话范围的 JSONL 日志
（`<sessionId>.acp-stream.jsonl`），你可以 tail 该日志来查看完整中继历史。
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
在 N 秒后中止 ACP 子回合。`0` 会让该回合使用 Gateway 网关的无超时路径。同一个值会应用于 Gateway 网关运行和 ACP 运行时，因此卡住或配额耗尽的 harness 不会无限期占用父智能体通道。
N 秒后中止 ACP 子轮次。`0` 会让该轮次走 Gateway 网关的无超时路径。
同一个值会应用到 Gateway 网关运行和 ACP 运行时，因此停滞或配额耗尽的
harness 不会无限期占用父智能体通道。
</ParamField>
<ParamField path="model" type="string">
ACP 子会话的显式模型覆盖。Codex ACP 启动会在 `session/new` 之前，将 OpenClaw Codex 引用（例如 `openai-codex/gpt-5.4`）规范化为 Codex ACP 启动配置；`openai-codex/gpt-5.4/high` 这类斜杠形式也会设置 Codex ACP 推理强度。其他 harness 必须声明 ACP `models` 并支持 `session/set_model`；否则 OpenClaw/acpx 会明确失败，而不是静默回退到目标智能体默认值。
ACP 子会话的显式模型覆盖。Codex ACP spawn 会在 `session/new` 之前，
将 `openai-codex/gpt-5.4` 等 OpenClaw Codex 引用规范化为 Codex
ACP 启动配置；`openai-codex/gpt-5.4/high` 这类斜杠形式也会设置
Codex ACP reasoning effort。其他 harness 必须公告 ACP `models` 并支持
`session/set_model`；否则 OpenClaw/acpx 会明确失败，而不是静默回退到
目标智能体默认值。
</ParamField>
<ParamField path="thinking" type="string">
显式思考/推理强度。对于 Codex ACP，`minimal` 映射为低强度，`low`/`medium`/`high`/`xhigh` 直接映射，`off` 会省略推理强度启动覆盖。
显式 thinking/reasoning effort。对于 Codex ACP，`minimal` 会映射为低 effort，
`low`/`medium`/`high`/`xhigh` 会直接映射，`off` 会省略 reasoning-effort
启动覆盖。
</ParamField>
## 启动绑定和线程模式
## Spawn 绑定和线程模式
<Tabs>
<Tab title="--bind here|off">
@ -542,25 +566,25 @@ ACP 会话 — 不创建子话题串，使用同一聊天界面。OpenClaw 继
| `here` | 就地绑定当前活动对话；如果没有活动对话则失败。 |
| `off` | 不创建当前对话绑定。 |
备注：
说明：
- `--bind here` 是“让此渠道或聊天由 Codex 支持”的最简单操作员路径。
- `--bind here` 是“让这个渠道或聊天由 Codex 支撑”的最简单操作员路径。
- `--bind here` 不会创建子线程。
- `--bind here` 仅适用于公开当前对话绑定支持的渠道。
- `--bind here` 仅在暴露当前对话绑定支持的渠道上可用。
- `--bind` 和 `--thread` 不能在同一个 `/acp spawn` 调用中组合使用。
</Tab>
<Tab title="--thread auto|here|off">
| 模式 | 行为 |
| ------ | --------------------------------------------------------------------------------------------------- |
| `auto` | 在活动线程中：绑定该线程。在线程外：在支持时创建/绑定子线程。 |
| `here` | 要求当前处于活动线程；如果不在线程中则失败。 |
| `auto` | 在活动线程中：绑定该线程。在线程之外：在支持时创建/绑定子线程。 |
| `here` | 要求当前活动线程；如果不在线程中则失败。 |
| `off` | 不绑定。会话以未绑定状态启动。 |
备注：
说明：
- 在非线程绑定界面上，默认行为实际上是 `off`。
- 线程绑定启动需要渠道策略支持：
- 在非线程绑定表面上，默认行为实际上是 `off`。
- 线程绑定的 spawn 需要渠道策略支持：
- Discord：`channels.discord.threadBindings.spawnSessions=true`
- Telegram：`channels.telegram.threadBindings.spawnSessions=true`
- 当你想固定当前对话而不创建子线程时，使用 `--bind here`。
@ -568,55 +592,55 @@ ACP 会话 — 不创建子话题串，使用同一聊天界面。OpenClaw 继
</Tab>
</Tabs>
## 交付模型
## 投递模型
ACP 会话可以是交互式工作区，也可以是父级拥有的后台工作。交付路径取决于其形态。
ACP 会话可以是交互式工作区，也可以是父级拥有的后台工作。投递路径取决于这种形态。
<AccordionGroup>
<Accordion title="交互式 ACP 会话">
交互式会话用于在可见聊天界面上持续对话：
<Accordion title="Interactive ACP sessions">
交互式会话旨在持续在可见聊天表面上对话：
- `/acp spawn ... --bind here` 将当前对话绑定到 ACP 会话。
- `/acp spawn ... --thread ...` 将渠道线程/主题绑定到 ACP 会话。
- `/acp spawn ... --bind here` 会将当前对话绑定到 ACP 会话。
- `/acp spawn ... --thread ...` 会将渠道线程/主题绑定到 ACP 会话。
- 持久配置的 `bindings[].type="acp"` 会将匹配的对话路由到同一个 ACP 会话。
绑定对话中的后续消息会直接路由到 ACP 会话，ACP 输出会交付回同一个渠道/线程/主题。
绑定对话中的后续消息会直接路由到 ACP 会话，而 ACP 输出会投递回同一个渠道/线程/主题。
OpenClaw 发送给 harness 的内容：
- 普通绑定后续消息会作为提示文本发送，并且仅在 harness/后端支持时附带附件。
- `/acp` 管理命令和本地 Gateway 网关命令会在 ACP 分派之前被拦截。
- 运行时生成的完成事件会按目标实体化。OpenClaw 智能体会获得 OpenClaw 的内部运行时上下文信封；外部 ACP harness 会获得包含子结果和指令的普通提示。原始 `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` 信封绝不应发送给外部 harness，也不应作为 ACP 用户转录文本持久化。
- 普通绑定后续消息会作为提示文本发送，且仅在 harness/后端支持时附带附件。
- `/acp` 管理命令和本地 Gateway 网关命令会在 ACP 派发前被拦截。
- 运行时生成的完成事件会按目标具体化。OpenClaw 智能体会获得 OpenClaw 的内部运行时上下文信封；外部 ACP harness 会获得包含子结果和指令的普通提示。原始 `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` 信封绝不应发送给外部 harness，也不应作为 ACP 用户转录文本持久化。
- ACP 转录条目使用用户可见的触发文本或普通完成提示。内部事件元数据会尽可能在 OpenClaw 中保持结构化，并且不会被视为用户撰写的聊天内容。
</Accordion>
<Accordion title="父级拥有的一次性 ACP 会话">
由另一个智能体运行启动的一次性 ACP 会话是后台子级，类似于子智能体：
<Accordion title="Parent-owned one-shot ACP sessions">
由另一个智能体运行 spawn 的一次性 ACP 会话是后台子会话，类似于子智能体：
- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。
- 子级在自己的 ACP harness 会话中运行。
- 子回合运行在原生子智能体启动所用的同一个后台通道上，因此缓慢的 ACP harness 不会阻塞无关的主会话工作。
- 完成结果会通过任务完成公告路径报告回来。OpenClaw 会先将内部完成元数据转换为普通 ACP 提示，再发送给外部 harness，因此 harness 不会看到仅限 OpenClaw 的运行时上下文标记。
- 当面向用户的回复有用时，父级会用普通助手语气重写子级结果。
- 子轮次运行在原生子智能体 spawn 使用的同一后台通道上，因此较慢的 ACP harness 不会阻塞无关的主会话工作。
- 完成结果会通过任务完成公告路径回报。OpenClaw 会在发送给外部 harness 前，将内部完成元数据转换为普通 ACP 提示，因此 harness 不会看到仅限 OpenClaw 的运行时上下文标记。
- 当面向用户的回复有用时，父级会用普通助手语气改写子结果。
**不要** 将此路径视为父级和子级之间的点对点聊天。子级已经有返回父级的完成渠道。
**不要**将此路径视为父级和子级之间的点对点聊天。子级已经有返回父级的完成通道。
</Accordion>
<Accordion title="sessions_send 和 A2A 交付">
`sessions_send` 可以在启动后指向另一个会话。对于普通对等会话，OpenClaw 会在注入消息后使用智能体到智能体（A2A）后续路径：
<Accordion title="sessions_send and A2A delivery">
`sessions_send` 可以在 spawn 后以另一个会话为目标。对于普通对等会话，OpenClaw 会在注入消息后使用智能体到智能体（A2A）后续路径：
- 等待目标会话的回复。
- 可选地允许请求方和目标交换有限数量的后续回合。
- 要求目标生成公告消息。
- 将该公告交付到可见渠道或线程。
- 可选地允许请求者和目标交换有界数量的后续轮次。
- 要求目标生成一条公告消息。
- 将该公告投递到可见渠道或线程。
该 A2A 路径是对等发送的回退机制，用于发送方需要可见后续回复的情况。当无关会话可以看到并向 ACP 目标发消息时，例如在宽泛的 `tools.sessions.visibility` 设置下，它会保持启用。
该 A2A 路径是对等发送的回退方案，适用于发送者需要可见后续回复的情况。当无关会话可以看到并给 ACP 目标发消息时，例如在宽泛的 `tools.sessions.visibility` 设置下，它会保持启用。
只有当请求方是其自己父级拥有的一次性 ACP 子级的父级时，OpenClaw 才会跳过 A2A 后续。在这种情况下，在任务完成之上运行 A2A 可能会用子级结果唤醒父级，将父级回复转发回子级，并创建父/子回声循环。对于这种拥有的子级情况，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为完成路径已经负责交付结果。
只有当请求者是其自己父级拥有的一次性 ACP 子级的父级时，OpenClaw 才会跳过 A2A 后续。在这种情况下，在任务完成之上运行 A2A 可能会用子结果唤醒父级，将父级回复转发回子级，并创建父/子回声循环。对于这种拥有的子级情况，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为完成路径已经负责返回结果。
</Accordion>
<Accordion title="恢复现有会话">
使用 `resumeSessionId` 继续之前的 ACP 会话，而不是重新开始。该智能体会通过 `session/load` 重放其对话历史，因此会带着之前所有上下文继续。
<Accordion title="Resume an existing session">
使用 `resumeSessionId` 继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此会带着之前内容的完整上下文继续。
```json
{
@ -629,138 +653,151 @@ ACP 会话可以是交互式工作区，也可以是父级拥有的后台工作
常见用例：
- 将 Codex 会话从你的笔记本交接到你的手机，并告诉你的智能体从你离开的地方继续。
- 继续你先前在 CLI 中交互式启动的编码会话，现在通过你的智能体以无头方式继续。
- 接续因 Gateway 网关重启或空闲超时而中断的工作。
- 将 Codex 会话从你的笔记本交接到你的手机，让你的智能体从你离开的地方继续。
- 继续你之前在 CLI 中以交互方式启动的编码会话，现在通过你的智能体无头运行。
- 接上因 Gateway 网关重启或空闲超时而中断的工作。
备注：
说明：
- `resumeSessionId` 仅在 `runtime: "acp"` 时适用；默认子智能体运行时会忽略这个仅限 ACP 的字段。
- `streamTo` 仅在 `runtime: "acp"` 时适用；默认子智能体运行时会忽略这个仅限 ACP 的字段。
- `resumeSessionId` 是主机本地 ACP/harness 恢复 ID，不是 OpenClaw 渠道会话键；OpenClaw 在分派前仍会检查 ACP 启动策略和目标智能体策略，而 ACP 后端或 harness 负责加载该上游 ID 的授权。
- `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然需要 `thread: true`。
- `resumeSessionId` 是主机本地 ACP/harness 恢复 id，不是 OpenClaw 渠道会话键；OpenClaw 在派发前仍会检查 ACP spawn 策略和目标智能体策略，而 ACP 后端或 harness 拥有加载该上游 id 的授权。
- `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍会正常应用到你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然需要 `thread: true`。
- 目标智能体必须支持 `session/load`（Codex 和 Claude Code 支持）。
- 如果找不到会话 ID，启动会以清晰错误失败，不会静默回退到新会话。
- 如果找不到会话 id，spawn 会以明确错误失败，不会静默回退到新会话。
</Accordion>
<Accordion title="部署后冒烟测试">
<Accordion title="Post-deploy smoke test">
Gateway 网关部署后，运行实时端到端检查，而不是信任单元测试：
1. 验证目标主机上的已部署 Gateway 网关版本和提交。
2. 打开到实时智能体的临时 ACPX 桥接会话。
3. 要求该智能体使用 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"` 和任务 `Reply with exactly LIVE-ACP-SPAWN-OK` 调用 `sessions_spawn`。
1. 在目标主机上验证已部署的 Gateway 网关版本和提交。
2. 打开一个连接到实时智能体的临时 ACPX bridge 会话。
3. 要求该智能体调用 `sessions_spawn`，参数为 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务为 `Reply with exactly LIVE-ACP-SPAWN-OK`。
4. 验证 `accepted=yes`、真实的 `childSessionKey`，且没有验证器错误。
5. 清理临时桥接会话。
5. 清理临时 bridge 会话。
将门禁保持在 `mode: "run"`，并跳过 `streamTo: "parent"`，因为线程绑定的 `mode: "session"` 和流中继路径是独立的更丰富集成流程。
将门禁保持在 `mode: "run"`，并跳过 `streamTo: "parent"`，
线程绑定的 `mode: "session"` 和流式中继路径是单独的、更丰富的集成检查。
</Accordion>
</AccordionGroup>
## 沙箱兼容性
ACP 会话目前运行在主机运行时上，**不是**在 OpenClaw 沙箱内运行。
ACP 会话目前运行在主机运行时上，**不**在 OpenClaw 沙箱内运行。
<Warning>
**安全边界：**
- 外部运行框架可以根据自身 CLI 权限和所选 `cwd` 进行读/写。
- OpenClaw 的沙箱策略**不会**包裹 ACP 运行框架执行。
- OpenClaw 仍会强制执行 ACP 功能门控、允许的智能体、会话所有权、渠道绑定以及 Gateway 网关投递策略。
- 对需要强制沙箱执行的 OpenClaw 原生工作，请使用 `runtime: "subagent"`。
- 外部 harness 可以根据其自身 CLI 权限和所选的 `cwd` 进行读写。
- OpenClaw 的沙箱策略**不会**包裹 ACP harness 执行。
- OpenClaw 仍会强制执行 ACP 功能门控、允许的智能体、会话所有权、渠道绑定和 Gateway 网关投递策略。
- 对于由沙箱强制执行的 OpenClaw 原生工作，请使用 `runtime: "subagent"`。
</Warning>
当前限制：
- 如果请求方会话处于沙箱隔离状态，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 启动都会被阻止。
- 带有 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。
- 如果请求方会话处于沙箱隔离状态，则 ACP 启动会同时阻止 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn`。
- 使用 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。
## 会话目标解析
大多数 `/acp` 操作都接受一个可选会话目标（`session-key`、`session-id` 或 `session-label`）。
大多数 `/acp` 操作都接受可选的会话目标（`session-key`、
`session-id` 或 `session-label`）。
**解析顺序：**
1. 显式目标参数（或 `/acp steer` 的 `--session`）
- 尝试键名
- 然后尝试 UUID 形状的会话 ID
- 然后尝试 UUID 形态的会话 ID
- 然后尝试标签
2. 当前线程绑定（如果此对话/线程已绑定到 ACP 会话）。
3. 当前请求方会话回退。
当前对话绑定和线程绑定都会参与第 2 步。
当前对话绑定和线程绑定都会参与
第 2 步。
如果没有解析出目标，OpenClaw 会返回清晰的错误（`Unable to resolve session target: ...`）。
如果无法解析任何目标，OpenClaw 会返回清晰错误
（`Unable to resolve session target: ...`）。
## ACP 控制
| 命令 | 作用 | 示例 |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
| `/acp spawn` | 创建 ACP 会话；可选当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | 取消目标会话中正在进行的轮次。 | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | 向运行中的会话发送 steer 指令。 | `/acp steer --session support inbox prioritize failing tests` |
| `/acp cancel` | 取消目标会话正在进行的回合。 | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | 向正在运行的会话发送 steer 指令。 | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | 关闭会话并解除线程目标绑定。 | `/acp close` |
| `/acp status` | 显示后端、模式、状态、运行时选项和能力。 | `/acp status` |
| `/acp set-mode` | 设置目标会话的运行时模式。 | `/acp set-mode plan` |
| `/acp set-mode` | 为目标会话设置运行时模式。 | `/acp set-mode plan` |
| `/acp set` | 写入通用运行时配置选项。 | `/acp set model openai/gpt-5.4` |
| `/acp cwd` | 设置运行时工作目录覆盖值。 | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | 设置审批策略配置档。 | `/acp permissions strict` |
| `/acp cwd` | 设置运行时工作目录覆盖项。 | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | 设置审批策略配置文件。 | `/acp permissions strict` |
| `/acp timeout` | 设置运行时超时（秒）。 | `/acp timeout 120` |
| `/acp model` | 设置运行时模型覆盖值。 | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options` | 移除会话运行时选项覆盖值。 | `/acp reset-options` |
| `/acp sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` |
| `/acp doctor` | 后端健康状态、能力和可执行修复项。 | `/acp doctor` |
| `/acp model` | 设置运行时模型覆盖项。 | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options` | 移除会话运行时选项覆盖项。 | `/acp reset-options` |
| `/acp sessions` | 从存储列出最近的 ACP 会话。 | `/acp sessions` |
| `/acp doctor` | 后端健康状况、能力和可执行修复。 | `/acp doctor` |
| `/acp install` | 打印确定性的安装和启用步骤。 | `/acp install` |
`/acp status` 会显示有效运行时选项，以及运行时级别和后端级别的会话标识符。当后端缺少某项能力时，不受支持的控制错误会清晰呈现。`/acp sessions` 会读取当前已绑定会话或请求方会话的存储；目标令牌（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括每个智能体自定义的 `session.store` 根目录。
`/acp status` 会显示有效的运行时选项，以及运行时级别和
后端级别的会话标识符。当后端缺少某项能力时，不受支持的控制错误会
清晰显示。`/acp sessions` 会读取当前已绑定会话或请求方会话的
存储；目标令牌（`session-key`、`session-id` 或 `session-label`）
会通过 Gateway 网关会话发现进行解析，包括自定义的每智能体 `session.store`
根目录。
### 运行时选项映射
`/acp` 提供便捷命令和通用设置器。等效操作：
`/acp` 提供便利命令和通用设置器。等价
操作如下：
| 命令 | 映射到 | 说明 |
| ---------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/acp model <id>` | 运行时配置键 `model` | 对于 Codex ACP，OpenClaw 会将 `openai-codex/<model>` 规范化为适配器模型 ID，并将类似 `openai-codex/gpt-5.4/high` 的斜杠 reasoning 后缀映射到 `reasoning_effort`。 |
| `/acp set thinking <level>` | 运行时配置键 `thinking` | 对于 Codex ACP，OpenClaw 会在适配器支持时发送对应的 `reasoning_effort`。 |
| `/acp permissions <profile>` | 运行时配置键 `approval_policy` | — |
| `/acp timeout <seconds>` | 运行时配置键 `timeout` | — |
| `/acp cwd <path>` | 运行时 cwd 覆盖值 | 直接更新。 |
| `/acp set <key> <value>` | 通用 | `key=cwd` 使用 cwd 覆盖路径。 |
| `/acp reset-options` | 清除所有运行时覆盖值 | — |
| 命令 | 映射到 | 备注 |
| ---------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/acp model <id>` | 运行时配置键 `model` | 对于 Codex ACP，OpenClaw 会将 `openai-codex/<model>` 规范化为适配器模型 ID，并将斜杠推理后缀（如 `openai-codex/gpt-5.4/high`）映射到 `reasoning_effort`。 |
| `/acp set thinking <level>` | 运行时配置键 `thinking` | 对于 Codex ACP，OpenClaw 会在适配器支持时发送对应的 `reasoning_effort`。 |
| `/acp permissions <profile>` | 运行时配置键 `approval_policy` | — |
| `/acp timeout <seconds>` | 运行时配置键 `timeout` | — |
| `/acp cwd <path>` | 运行时 cwd 覆盖项 | 直接更新。 |
| `/acp set <key> <value>` | 通用 | `key=cwd` 使用 cwd 覆盖路径。 |
| `/acp reset-options` | 清除所有运行时覆盖项 | — |
## acpx 运行框架、插件设置和权限
## acpx harness、插件设置和权限
有关 acpx 运行框架配置（Claude Code / Codex / Gemini CLI 别名）、plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP 权限模式，请参阅 [ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)。
有关 acpx harness 配置（Claude Code / Codex / Gemini CLI
别名）、plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP
权限模式，请参阅
[ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)。
## 故障排除
| 现象 | 可能原因 | 修复 |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACP runtime backend is not configured` | 后端插件缺失、已禁用，或被 `plugins.allow` 阻止。 | 安装并启用后端插件；当设置了该允许列表时，在 `plugins.allow` 中包含 `acpx`，然后运行 `/acp doctor`。 |
| `ACP is disabled by policy (acp.enabled=false)` | ACP 已全局禁用。 | 设置 `acp.enabled=true`。 |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 已禁用来自普通线程消息的自动分发。 | 设置 `acp.dispatch.enabled=true` 以恢复自动线程路由；显式 `sessions_spawn({ runtime: "acp" })` 调用仍然有效。 |
| `ACP agent "<id>" is not allowed by policy` | 智能体不在允许列表中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 |
| `/acp doctor` reports backend not ready right after startup | 后端插件缺失、已禁用、被允许/拒绝策略阻止，或其配置的可执行文件不可用。 | 安装/启用后端插件，重新运行 `/acp doctor`；如果它仍不健康，请检查后端安装或策略错误。 |
| Harness command not found | 适配器 CLI 未安装、外部插件缺失，或非 Codex 适配器的首次运行 `npx` 拉取失败。 | 运行 `/acp doctor`，在 Gateway 网关主机上安装/预热适配器，或显式配置 acpx 智能体命令。 |
| Model-not-found from the harness | 模型 ID 对另一个提供商/harness 有效，但对此 ACP 目标无效。 | 使用该 harness 列出的模型，在 harness 中配置模型，或省略覆盖项。 |
| Vendor auth error from the harness | OpenClaw 正常，但目标 CLI/提供商未登录。 | 在 Gateway 网关主机环境中登录或提供所需的提供商密钥。 |
| `Unable to resolve session target: ...` | 键/ID/标签令牌错误。 | 运行 `/acp sessions`，复制精确的键/标签，然后重试。 |
| `--bind here requires running /acp spawn inside an active ... conversation` | 使用 `--bind here` 时没有活动的可绑定会话。 | 移动到目标聊天/渠道后重试，或使用未绑定生成。 |
| `Conversation bindings are unavailable for <channel>.` | 适配器缺少当前会话 ACP 绑定能力。 | 在支持的位置使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或移动到受支持的渠道。 |
| `--thread here requires running /acp spawn inside an active ... thread` | 在非线程上下文中使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 |
| `Only <user-id> can rebind this channel/conversation/thread.` | 另一个用户拥有活动绑定目标。 | 以所有者身份重新绑定，或使用其他会话或线程。 |
| `Thread bindings are unavailable for <channel>.` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或移动到受支持的适配器/渠道。 |
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时在主机侧；请求方会话已沙箱隔离。 | 从沙箱隔离的会话使用 `runtime="subagent"`，或从非沙箱隔离的会话运行 ACP 生成。 |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 使用 `runtime="subagent"` 以获得必需的沙箱隔离，或从非沙箱隔离的会话使用带 `sandbox="inherit"` 的 ACP。 |
| `Cannot apply --model ... did not advertise model support` | 目标 harness 未公开通用 ACP 模型切换能力。 | 使用声明支持 ACP `models`/`session/set_model` 的 harness，使用 Codex ACP 模型引用，或在 harness 有自己的启动标志时直接在其中配置模型。 |
| Missing ACP metadata for bound session | 过期/已删除的 ACP 会话元数据。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 会阻止非交互式 ACP 会话中的写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见 [权限配置](/zh-CN/tools/acp-agents-setup#permission-configuration)。 |
| ACP session fails early with little output | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。对于完整权限，设置 `permissionMode=approve-all`；对于优雅降级，设置 `nonInteractivePermissions=deny`。 |
| ACP session stalls indefinitely after completing work | Harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动终止过期进程。 |
| Harness sees `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` | 内部事件信封泄漏到了 ACP 边界之外。 | 更新 OpenClaw 并重新运行完成流程；外部 harness 应只接收普通的完成提示。 |
| 症状 | 可能原因 | 修复 |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ACP runtime backend is not configured` | 后端插件缺失、已禁用，或被 `plugins.allow` 阻止。 | 安装并启用后端插件；如果设置了允许列表，请在 `plugins.allow` 中包含 `acpx`，然后运行 `/acp doctor`。 |
| `ACP is disabled by policy (acp.enabled=false)` | ACP 已全局禁用。 | 设置 `acp.enabled=true`。 |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 已禁用从普通线程消息进行自动分派。 | 设置 `acp.dispatch.enabled=true` 以恢复自动线程路由；显式的 `sessions_spawn({ runtime: "acp" })` 调用仍然有效。 |
| `ACP agent "<id>" is not allowed by policy` | 智能体 不在允许列表中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 |
| `/acp doctor` reports backend not ready right after startup | 后端插件缺失、已禁用、被允许/拒绝策略阻止，或其配置的可执行文件不可用。 | 安装/启用后端插件，重新运行 `/acp doctor`；如果仍然不健康，请检查后端安装或策略错误。 |
| Harness command not found | 适配器 CLI 未安装、外部插件缺失，或非 Codex 适配器的首次运行 `npx` 拉取失败。 | 运行 `/acp doctor`，在 Gateway 网关主机上安装/预热适配器，或显式配置 acpx 智能体 命令。 |
| Model-not-found from the harness | 模型 ID 对另一个提供商/harness 有效，但对这个 ACP 目标无效。 | 使用该 harness 列出的模型，在 harness 中配置模型，或省略覆盖项。 |
| Vendor auth error from the harness | OpenClaw 正常，但目标 CLI/提供商未登录。 | 在 Gateway 网关主机环境中登录，或提供所需的提供商密钥。 |
| `Unable to resolve session target: ...` | 键/ID/标签标记错误。 | 运行 `/acp sessions`，复制准确的键/标签，然后重试。 |
| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动可绑定对话的情况下使用了 `--bind here`。 | 移动到目标聊天/渠道后重试，或使用未绑定的 spawn。 |
| `Conversation bindings are unavailable for <channel>.` | 适配器缺少当前对话 ACP 绑定能力。 | 在支持的地方使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或移动到受支持的渠道。 |
| `--thread here requires running /acp spawn inside an active ... thread` | 在非线程上下文中使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 |
| `Only <user-id> can rebind this channel/conversation/thread.` | 另一个用户拥有活动绑定目标。 | 以所有者身份重新绑定，或使用其他对话或线程。 |
| `Thread bindings are unavailable for <channel>.` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或移动到受支持的适配器/渠道。 |
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于主机端；请求方 会话 已被沙箱隔离。 | 从沙箱隔离的 会话 中使用 `runtime="subagent"`，或从非沙箱隔离的 会话 运行 ACP spawn。 |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对必需的沙箱隔离使用 `runtime="subagent"`，或从非沙箱隔离的 会话 以 `sandbox="inherit"` 使用 ACP。 |
| `Cannot apply --model ... did not advertise model support` | 目标 harness 未暴露通用 ACP 模型切换。 | 使用声明 ACP `models`/`session/set_model` 的 harness，使用 Codex ACP 模型引用，或如果该 harness 有自己的启动标志，则直接在 harness 中配置模型。 |
| Missing ACP metadata for bound session | ACP 会话元数据陈旧/已删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见[权限配置](/zh-CN/tools/acp-agents-setup#permission-configuration)。 |
| ACP session fails early with little output | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。要获得完整权限，请设置 `permissionMode=approve-all`；要优雅降级，请设置 `nonInteractivePermissions=deny`。 |
| ACP session stalls indefinitely after completing work | Harness 进程已完成，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动终止陈旧进程。 |
| Harness sees `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` | 内部事件信封泄漏到了 ACP 边界之外。 | 更新 OpenClaw 并重新运行完成流程；外部 harness 应该只收到纯完成提示。 |
## 相关内容
## 相关
- [ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)
- [智能体发送](/zh-CN/tools/agent-send)