From cd382e08864037feaec9aede8303049d5ecc5cbf Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 27 Apr 2026 13:51:59 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/memory-qmd.md | 117 ++++-- docs/zh-CN/concepts/session-tool.md | 85 ++-- docs/zh-CN/gateway/doctor.md | 333 +++++++-------- docs/zh-CN/gateway/index.md | 161 ++++---- docs/zh-CN/gateway/troubleshooting.md | 349 ++++++++-------- docs/zh-CN/reference/memory-config.md | 336 +++++++-------- docs/zh-CN/tools/acp-agents.md | 571 +++++++++++++------------- docs/zh-CN/tools/subagents.md | 311 +++++++------- 8 files changed, 1164 insertions(+), 1099 deletions(-) diff --git a/docs/zh-CN/concepts/memory-qmd.md b/docs/zh-CN/concepts/memory-qmd.md index e2c8f8487..5e94ed554 100644 --- a/docs/zh-CN/concepts/memory-qmd.md +++ b/docs/zh-CN/concepts/memory-qmd.md @@ -5,32 +5,32 @@ read_when: summary: 本地优先的搜索 sidecar，支持 BM25、向量、重排序和查询扩展 title: QMD 记忆引擎 x-i18n: - generated_at: "2026-04-27T13:31:44Z" + generated_at: "2026-04-27T13:49:05Z" model: gpt-5.4 provider: openai - source_hash: 10115a298b5966847e037e567efbc8cb2823afe658a408e18a683d1c6baebe99 + source_hash: 1995a2b087c484595b0e0efed7a4ae3987b8fb3ac95e3c41bdf5335ba6240e73 source_path: concepts/memory-qmd.md workflow: 15 --- -[QMD](https://github.com/tobi/qmd) 是一个与 OpenClaw 一起运行的本地优先搜索 sidecar。它将 BM25、向量搜索和重排序整合到单个二进制程序中，还可以为你的工作区记忆文件之外的内容建立索引。 +[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索 sidecar，与 OpenClaw 并行运行。它将 BM25、向量搜索和重排序整合到一个二进制程序中，并且可以为你的工作区记忆文件之外的内容建立索引。 -## 相比内置引擎增加了什么 +## 相比 builtin 它增加了什么 - **重排序和查询扩展**，以获得更好的召回效果。 -- **索引额外目录** —— 项目文档、团队笔记，以及磁盘上的任何内容。 -- **索引会话转录** —— 回忆更早的对话。 -- **完全本地运行** —— 通过可选的 `node-llama-cpp` 运行时包运行，并自动下载 GGUF 模型。 -- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到内置引擎。 +- **为额外目录建立索引** —— 项目文档、团队笔记、磁盘上的任何内容。 +- **为会话转录建立索引** —— 回忆更早的对话。 +- **完全本地运行** —— 配合可选的 `node-llama-cpp` 运行时包运行，并自动下载 GGUF 模型。 +- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到 builtin 引擎。 ## 入门指南 -### 先决条件 +### 前提条件 - 安装 QMD：`npm install -g @tobilu/qmd` 或 `bun install -g @tobilu/qmd` -- 允许扩展的 SQLite 构建版本（macOS 上可使用 `brew install sqlite`）。 -- QMD 必须位于 Gateway 网关的 `PATH` 中。 -- macOS 和 Linux 可开箱即用。Windows 最佳支持方式是通过 WSL2。 +- 支持扩展的 SQLite 构建版本（在 macOS 上可使用 `brew install sqlite`）。 +- QMD 必须在 Gateway 网关的 `PATH` 中。 +- macOS 和 Linux 开箱即用。Windows 最佳支持方式是通过 WSL2。 ### 启用 @@ -42,23 +42,46 @@ x-i18n: } ``` -OpenClaw 会在 `~/.openclaw/agents//qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 的生命周期 —— 集合、更新和嵌入运行都会由它代劳。它会优先使用当前的 QMD collection 和 MCP query 形状，但在需要时仍会回退到备用 collection pattern 标志和较旧的 MCP 工具名称。启动时的协调还会在检测到仍存在同名旧 QMD collection 时，将过时的受管 collection 重新创建为其规范模式。 +OpenClaw 会在 `~/.openclaw/agents//qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 生命周期 —— 集合、更新和嵌入运行都会由它处理。它会优先使用当前的 QMD collection 和 MCP 查询格式，但在需要时仍会回退到备用的 collection pattern 标志和较旧的 MCP 工具名称。启动时的协调过程还会在检测到存在同名旧版 QMD collection 时，将过期的受管集合重新创建为其规范模式。 ## sidecar 的工作方式 -- OpenClaw 会根据你的工作区记忆文件以及所有已配置的 `memory.qmd.paths` 创建 collection，然后在启动时和周期性地运行 `qmd update`（默认每 5 分钟一次）。语义模式还会运行 `qmd embed`。 -- 默认工作区 collection 会跟踪 `MEMORY.md` 和 `memory/` 目录树。小写的 `memory.md` 不会作为根记忆文件建立索引。 -- 启动时刷新会在后台进行，因此不会阻塞聊天启动。 +- OpenClaw 会根据你的工作区记忆文件以及任何已配置的 `memory.qmd.paths` 创建集合，然后在启动时和周期性地运行 `qmd update`（默认每 5 分钟一次）。语义模式还会运行 `qmd embed`。 +- 默认工作区集合会跟踪 `MEMORY.md` 以及 `memory/` 目录树。小写的 `memory.md` 不会作为根记忆文件建立索引。 +- 启动刷新会在后台运行，因此不会阻塞聊天启动。 - 搜索会使用已配置的 `searchMode`（默认：`search`；也支持 `vsearch` 和 `query`）。`search` 仅使用 BM25，因此 OpenClaw 会在该模式下跳过语义向量就绪探测和嵌入维护。如果某个模式失败，OpenClaw 会使用 `qmd query` 重试。 -- 如果 QMD 完全失败，OpenClaw 会回退到内置的 SQLite 引擎。 +- 对于声明支持多 collection 过滤器的 QMD 版本，OpenClaw 会将同源集合分组，在一次 QMD 搜索调用中完成搜索。较旧的 QMD 版本则保留兼容的逐 collection 回退路径。 +- 如果 QMD 完全失败，OpenClaw 会回退到 builtin SQLite 引擎。 -第一次搜索可能会较慢 —— QMD 会在首次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。 +第一次搜索可能较慢 —— QMD 会在第一次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。 +## 搜索性能与兼容性 + +OpenClaw 会让 QMD 搜索路径同时兼容当前版和旧版 QMD 安装。 + +在启动时，OpenClaw 会为每个管理器检查一次已安装的 QMD 帮助文本。如果该二进制程序声明支持多个 collection 过滤器，OpenClaw 就会用一条命令搜索所有同源集合： + +```bash +qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main +``` + +这样可以避免为每个持久记忆 collection 启动一个 QMD 子进程。会话转录集合仍保留在它们自己的源分组中，因此混合的 `memory` + `sessions` 搜索仍然能从两个来源获得结果多样化输入。 + +较旧的 QMD 构建版本只接受一个 collection 过滤器。当 OpenClaw 检测到这类构建时，它会保留兼容路径，分别搜索每个 collection，然后再合并并去重结果。 + +要手动检查已安装的契约，请运行： + +```bash +qmd --help | grep -i collection +``` + +当前的 QMD 帮助文本说明 collection 过滤器可以针对一个或多个集合。旧版帮助通常只描述单个 collection。 + ## 模型覆盖 -QMD 的模型环境变量会从 Gateway 网关进程原样透传，因此你可以在不新增 OpenClaw 配置的情况下全局调优 QMD： +QMD 模型环境变量会从 Gateway 网关进程原样透传，因此你可以全局调整 QMD，而无需添加新的 OpenClaw 配置： ```bash export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf" @@ -66,11 +89,11 @@ export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf" export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" ``` -更改嵌入模型后，请重新运行嵌入，以确保索引与新的向量空间匹配。 +更改嵌入模型后，请重新运行嵌入，以便索引与新的向量空间匹配。 ## 为额外路径建立索引 -将 QMD 指向其他目录，使其可被搜索： +将 QMD 指向其他目录，使其可搜索： ```json5 { @@ -83,11 +106,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" } ``` -来自额外路径的片段会在搜索结果中显示为 `qmd//`。`memory_get` 能识别此前缀，并从正确的 collection 根目录读取内容。 +来自额外路径的片段会在搜索结果中显示为 `qmd//`。`memory_get` 能识别这个前缀，并从正确的 collection 根目录读取内容。 ## 为会话转录建立索引 -启用会话索引以回忆更早的对话： +启用会话索引，以便回忆更早的对话： ```json5 { @@ -100,11 +123,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" } ``` -转录会作为已清理的 User/Assistant 轮次导出到专用的 QMD collection 中，路径为 `~/.openclaw/agents//qmd/sessions/`。 +转录内容会以净化后的 User/Assistant 轮次导出到专用的 QMD collection 中，路径为 `~/.openclaw/agents//qmd/sessions/`。 ## 搜索范围 -默认情况下，QMD 搜索结果会显示在直接会话和渠道会话中（不包括群组）。通过配置 `memory.qmd.scope` 来更改此行为： +默认情况下，QMD 搜索结果会显示在私信和渠道会话中（不包括群组）。可通过配置 `memory.qmd.scope` 来更改： ```json5 { @@ -119,7 +142,7 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" } ``` -当范围规则拒绝一次搜索时，OpenClaw 会记录一条警告，其中包含推导出的渠道和聊天类型，以便更容易调试空结果问题。 +当 scope 拒绝搜索时，OpenClaw 会记录一条警告日志，其中包含推导出的渠道和聊天类型，以便更容易调试空结果问题。 ## 引用 @@ -131,38 +154,52 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" - 通过重排序获得更高质量的结果。 - 搜索工作区之外的项目文档或笔记。 -- 回忆过去的会话对话。 -- 完全本地搜索且无需 API 密钥。 +- 回忆过往会话对话。 +- 完全本地搜索，无需 API 密钥。 -对于更简单的设置，[内置引擎](/zh-CN/concepts/memory-builtin) 在无需额外依赖的情况下也能很好地工作。 +对于更简单的设置，[builtin 引擎](/zh-CN/concepts/memory-builtin) 在无需额外依赖的情况下也能很好地工作。 ## 故障排除 -**找不到 QMD？** 请确认该二进制程序位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建符号链接： +**找不到 QMD？** 请确保该二进制程序位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建一个符号链接： `sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`。 +如果 `qmd --version` 在你的 shell 中可以正常运行，但 OpenClaw 仍然报告 `spawn qmd ENOENT`，则 Gateway 网关进程很可能使用了与你的交互式 shell 不同的 `PATH`。请显式固定该二进制路径： + +```json5 +{ + memory: { + backend: "qmd", + qmd: { + command: "/absolute/path/to/qmd", + }, + }, +} +``` + +在安装了 QMD 的环境中使用 `command -v qmd`，然后再通过 `openclaw memory status --deep` 重新检查。 + **第一次搜索很慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录，通过 `qmd query "test"` 进行预热。 -**仅 BM25 的 QMD 仍在尝试构建 llama.cpp？** 请设置 -`memory.qmd.searchMode = "search"`。OpenClaw 会将该模式视为纯词法搜索，不会运行 QMD 向量状态探测或嵌入维护，并将语义就绪检查留给 `vsearch` 或 `query` 设置。 +**搜索期间出现很多 QMD 子进程？** 如果可能，请升级 QMD。只有当已安装的 QMD 声明支持多个 `-c` 过滤器时，OpenClaw 才会对同源多 collection 搜索使用单个进程；否则，为了保证正确性，它会保留较旧的逐 collection 回退路径。 -**搜索超时？** 请增大 `memory.qmd.limits.timeoutMs`（默认：4000ms）。 -对于较慢的硬件，请设置为 `120000`。 +**仅 BM25 的 QMD 仍在尝试构建 llama.cpp？** 设置 `memory.qmd.searchMode = "search"`。OpenClaw 会将该模式视为纯词法搜索，不会运行 QMD 向量状态探测或嵌入维护，并将语义就绪检查留给 `vsearch` 或 `query` 配置。 -**群聊中结果为空？** 请检查 `memory.qmd.scope` —— 默认仅允许直接会话和渠道会话。 +**搜索超时？** 增加 `memory.qmd.limits.timeoutMs`（默认：4000ms）。对于较慢的硬件，可设置为 `120000`。 -**根记忆搜索突然变得过宽？** 重启 Gateway 网关，或等待下一次启动时协调。OpenClaw 会在检测到同名冲突时，将过时的受管 collection 重新创建为规范的 `MEMORY.md` 和 `memory/` 模式。 +**群聊中结果为空？** 检查 `memory.qmd.scope` —— 默认仅允许私信和渠道会话。 -**工作区可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？** -QMD 遍历当前遵循底层 QMD 扫描器的行为，而不是 OpenClaw 内置的符号链接规则。在 QMD 提供安全的循环遍历或显式排除控制之前，请将临时 monorepo 检出保存在诸如 `.tmp/` 之类的隐藏目录下，或放在已建立索引的 QMD 根目录之外。 +**根记忆搜索突然变得过宽？** 重启 Gateway 网关，或等待下一次启动协调。OpenClaw 在检测到同名冲突时，会将过期的受管集合重新创建为规范的 `MEMORY.md` 和 `memory/` 模式。 + +**工作区可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？** QMD 遍历当前遵循底层 QMD 扫描器的行为，而不是 OpenClaw builtin 的符号链接规则。在 QMD 暴露出防循环遍历或显式排除控制之前，请将临时 monorepo 检出保存在 `.tmp/` 之类的隐藏目录下，或放在已索引 QMD 根目录之外。 ## 配置 -要了解完整配置项（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及所有其他可调参数，请参阅 +有关完整的配置项（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及所有其他可调项，请参见 [记忆配置参考](/zh-CN/reference/memory-config)。 ## 相关内容 - [记忆概览](/zh-CN/concepts/memory) -- [内置记忆引擎](/zh-CN/concepts/memory-builtin) +- [Builtin 记忆引擎](/zh-CN/concepts/memory-builtin) - [Honcho 记忆](/zh-CN/concepts/memory-honcho) diff --git a/docs/zh-CN/concepts/session-tool.md b/docs/zh-CN/concepts/session-tool.md index 3757fbe33..68e4a256b 100644 --- a/docs/zh-CN/concepts/session-tool.md +++ b/docs/zh-CN/concepts/session-tool.md @@ -3,13 +3,13 @@ read_when: - 你想了解智能体拥有哪些会话工具 - 你想配置跨会话访问或生成子智能体 - 你想检查状态或控制已生成的子智能体 -summary: 用于跨会话状态、回忆、消息传递和子智能体编排的 Agent 工具 +summary: 用于跨会话状态、记忆、消息传递和子智能体编排的 Agent 工具 title: 会话工具 x-i18n: - generated_at: "2026-04-27T09:50:14Z" + generated_at: "2026-04-27T13:49:01Z" model: gpt-5.4 provider: openai - source_hash: 18fabe50b05eade5314e664f5afd5a212eabc837f36ab7c6c5bed5199d9e0860 + source_hash: 19c42436ed7123cee35f397d672db1c2e0963cd1299e36d6fff41a56b880149b source_path: concepts/session-tool.md workflow: 15 --- @@ -22,54 +22,67 @@ OpenClaw 为智能体提供了可跨会话工作、检查状态并编排子智 | ------------------ | --------------------------------------------------------------------------- | | `sessions_list` | 列出会话，并支持可选筛选条件（种类、标签、智能体、最近活动时间、预览） | | `sessions_history` | 读取特定会话的转录记录 | -| `sessions_send` | 向另一个会话发送消息，并可选择等待 | +| `sessions_send` | 向另一个会话发送消息，并可选择等待回复 | | `sessions_spawn` | 为后台工作生成一个隔离的子智能体会话 | -| `sessions_yield` | 结束当前轮次，并等待后续的子智能体结果 | +| `sessions_yield` | 结束当前回合，并等待后续的子智能体结果 | | `subagents` | 列出、引导或终止此会话生成的子智能体 | -| `session_status` | 显示一个类似 `/status` 的卡片，并可选择为每个会话设置模型覆盖 | +| `session_status` | 显示一个类似 `/status` 的状态卡片，并可选择为每个会话设置模型覆盖 | -## 列出和读取会话 +这些工具仍受当前工具配置文件以及 allow/deny 策略的约束。`tools.profile: "coding"` 包含完整的会话编排工具集，包括 `sessions_spawn`、`sessions_yield` 和 `subagents`。`tools.profile: "messaging"` 包含跨会话消息传递工具（`sessions_list`、`sessions_history`、`sessions_send`、`session_status`），但不包含子智能体生成功能。若要保留 messaging 配置文件并仍允许原生委派，请添加： -`sessions_list` 会返回会话及其 key、agentId、kind、channel、model、token 计数和时间戳。你可以按种类（`main`、`group`、`cron`、`hook`、`node`）、精确 `label`、精确 `agentId`、搜索文本或最近活动时间（`activeMinutes`）进行筛选。当你需要类似邮箱的分诊视图时，它还可以为每一行请求一个基于可见性范围派生的标题、最后一条消息的预览片段，或有限数量的最近消息。派生标题和预览仅对调用方在已配置会话工具可见性策略下本就可见的会话生成，因此不相关的会话会保持隐藏。 +```json5 +{ + tools: { + profile: "messaging", + alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"], + }, +} +``` -`sessions_history` 获取特定会话的对话转录记录。默认情况下，不包含工具结果——传入 `includeTools: true` 可查看它们。返回的视图是有意限制并经过安全过滤的： +组、提供商、沙箱和每个智能体的策略仍可在配置文件阶段之后移除这些工具。使用受影响会话中的 `/tools` 检查实际生效的工具列表。 -- 在回忆前会规范化 assistant 文本： +## 列出并读取会话 + +`sessions_list` 返回会话及其 key、agentId、kind、channel、model、token 计数和时间戳。你可以按种类（`main`、`group`、`cron`、`hook`、`node`）、精确 `label`、精确 `agentId`、搜索文本或最近活动时间（`activeMinutes`）进行筛选。当你需要类似邮箱的分诊方式时，它还可以请求返回一个基于可见性范围生成的派生标题、最后一条消息的预览片段，或每行限定数量的最近消息。派生标题和预览只会为调用方在已配置的会话工具可见性策略下本就可见的会话生成，因此不相关的会话会保持隐藏。 + +`sessions_history` 获取特定会话的对话转录记录。默认情况下，工具结果会被排除——传入 `includeTools: true` 可查看它们。返回的视图会被有意限制并经过安全过滤： + +- assistant 文本在回忆前会进行规范化处理： - 会移除 thinking 标签 - 会移除 `` / `` 脚手架块 - - 会移除纯文本工具调用 XML 载荷块，例如 `...`、`...`、`...` 和 `...`，包括那些未能正常闭合的截断载荷 + - 会移除纯文本工具调用 XML 载荷块，例如 `...`、`...`、`...` 和 `...`，也包括那些未能正常闭合的截断载荷 - 会移除降级后的工具调用/结果脚手架，例如 `[Tool Call: ...]`、`[Tool Result ...]` 和 `[Historical context ...]` - - 会移除泄漏的模型控制 token，例如 `<|assistant|>`、其他 ASCII `<|...|>` token，以及全角 `<｜...｜>` 变体 + - 会移除泄露的模型控制 token，例如 `<|assistant|>`、其他 ASCII `<|...|>` token 以及全角 `<｜...｜>` 变体 - 会移除格式错误的 MiniMax 工具调用 XML，例如 `` / `` -- 在返回前会对类似凭证/token 的文本进行脱敏 +- 返回前会对类似凭证/token 的文本进行脱敏 - 长文本块会被截断 -- 对于非常大的历史记录，可能会丢弃较旧的行，或用 `[sessions_history omitted: message too large]` 替换超大的行 -- 该工具会报告摘要标记，例如 `truncated`、`droppedMessages`、`contentTruncated`、`contentRedacted` 和 `bytes` +- 超大历史记录可能会丢弃较旧的行，或用 `[sessions_history omitted: message too large]` 替换过大的行 +- 该工具会报告摘要标志，例如 `truncated`、`droppedMessages`、`contentTruncated`、`contentRedacted` 和 `bytes` -这两个工具都接受**会话 key**（如 `"main"`）或之前 list 调用返回的**会话 ID**。 +这两个工具都接受 **session key**（如 `"main"`）或来自先前列表调用的 **session ID**。 -如果你需要精确到字节完全一致的转录记录，请直接检查磁盘上的转录文件，而不要将 `sessions_history` 当作原始转储。 +如果你需要精确到字节、完全一致的转录记录，请直接检查磁盘上的转录文件，而不要把 `sessions_history` 当作原始转储。 ## 发送跨会话消息 -`sessions_send` 将消息发送到另一个会话，并可选择等待响应： +`sessions_send` 会将消息投递到另一个会话，并可选择等待响应： -- **发送后不等待：** 设置 `timeoutSeconds: 0` 以加入队列并立即返回。 -- **等待回复：** 设置超时时间，并内联获取响应。 +- **发后即忘：** 设置 `timeoutSeconds: 0` 以加入队列并立即返回。 +- **等待回复：** 设置超时时间，并以内联方式获取响应。 -目标会话响应后，OpenClaw 可以运行一个**回传循环**，让智能体交替发送消息（最多 5 轮）。目标智能体可回复 `REPLY_SKIP` 以提前停止。 +目标响应后，OpenClaw 可以运行一个**回传循环**，让多个智能体交替发送消息（最多 5 个回合）。目标智能体可以回复 `REPLY_SKIP` 以提前停止。 ## 状态与编排辅助工具 -`session_status` 是适用于当前会话或另一个可见会话的轻量级 `/status` 等效工具。它会报告使用情况、时间、模型/运行时状态，以及存在时所关联的后台任务上下文。与 `/status` 一样，它可以用最新转录中的 usage 条目回填稀疏的 token/cache 计数器，而 `model=default` 会清除每会话覆盖。对调用方当前会话使用 `sessionKey="current"`；像 `openclaw-tui` 这样的可见客户端标签并不是会话 key。 +`session_status` 是适用于当前会话或另一个可见会话的轻量级 `/status` 等效工具。它会报告使用情况、时间、模型/运行时状态，以及存在时关联的后台任务上下文。与 `/status` 一样，它可以从最新的转录 usage 条目中回填稀疏的 token/缓存计数，而 `model=default` 会清除每会话覆盖。对调用方当前会话请使用 `sessionKey="current"`；像 `openclaw-tui` 这样的可见客户端标签不是 session key。 -`sessions_yield` 会有意结束当前轮次，以便你等待的后续事件能作为下一条消息到达。在生成子智能体后，当你希望完成结果作为下一条消息到达，而不是构建轮询循环时，请使用它。 +`sessions_yield` 会有意结束当前回合，以便你正在等待的后续事件能作为下一条消息到达。在生成子智能体后，如果你希望完成结果以下一条消息的形式到达，而不是构建轮询循环，就使用它。 `subagents` 是针对已生成 OpenClaw 子智能体的控制平面辅助工具。它支持： -- `action: "list"` 以检查活动/最近运行 -- `action: "steer"` 以向正在运行的子会话发送后续引导 -- `action: "kill"` 以停止一个子会话或 `all` +- `action: "list"` 用于检查活跃/最近运行 +- `action: "steer"` 用于向正在运行的子智能体发送后续指导 +- `action: "kill"` 用于停止一个子智能体或 `all` ## 生成子智能体 @@ -78,36 +91,36 @@ OpenClaw 为智能体提供了可跨会话工作、检查状态并编排子智 关键选项： - `runtime: "subagent"`（默认）或 `"acp"`，用于外部 harness 智能体。 -- 子会话的 `model` 和 `thinking` 覆盖。 +- 为子会话设置 `model` 和 `thinking` 覆盖。 - `thread: true` 用于将生成绑定到聊天线程（Discord、Slack 等）。 -- `sandbox: "require"` 用于对子会话强制启用沙箱隔离。 -- `context: "fork"` 适用于子会话需要当前请求者转录记录的原生子智能体；省略它或使用 `context: "isolated"` 则创建一个干净的子会话。 +- `sandbox: "require"` 用于对该子会话强制启用沙箱隔离。 +- `context: "fork"` 适用于当子智能体需要当前请求者转录记录时的原生子智能体；如需一个干净的子会话，可省略该项或使用 `context: "isolated"`。 -默认的叶子子智能体不会获得会话工具。当 `maxSpawnDepth >= 2` 时，深度为 1 的编排型子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便它们管理自己的子会话。叶子运行仍然不会获得递归编排工具。 +默认的叶子子智能体不会获得会话工具。当 `maxSpawnDepth >= 2` 时，深度为 1 的编排型子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便它们管理自己的子智能体。叶子运行仍不会获得递归编排工具。 -完成后，公告步骤会将结果发布到请求者的渠道。完成交付会在可用时保留已绑定的线程/主题路由；如果完成来源仅标识了一个渠道，OpenClaw 仍可复用请求者会话存储的路由（`lastChannel` / `lastTo`）来直接交付。 +完成后，公告步骤会将结果发布到请求者的渠道。完成投递会在可用时保留绑定的线程/主题路由；如果完成来源仅标识了一个渠道，OpenClaw 仍可复用请求者会话中存储的路由（`lastChannel` / `lastTo`）进行直接投递。 -有关 ACP 特定行为，请参阅 [ACP Agents](/zh-CN/tools/acp-agents)。 +有关 ACP 特定行为，请参见 [ACP Agents](/zh-CN/tools/acp-agents)。 ## 可见性 -会话工具按作用范围进行限制，以控制智能体可以看到什么： +会话工具带有作用域限制，以限制智能体可以看到的内容： | 级别 | 范围 | | ------- | ---------------------------------------- | | `self` | 仅当前会话 | | `tree` | 当前会话 + 已生成的子智能体 | | `agent` | 此智能体的所有会话 | -| `all` | 所有会话（如果已配置，则包括跨智能体） | +| `all` | 所有会话（若已配置，也包括跨智能体） | -默认值为 `tree`。沙箱隔离会话无论配置如何都会被限制为 `tree`。 +默认值为 `tree`。无论配置如何，沙箱隔离会话都会被限制为 `tree`。 ## 延伸阅读 - [Session Management](/zh-CN/concepts/session) —— 路由、生命周期、维护 - [ACP Agents](/zh-CN/tools/acp-agents) —— 外部 harness 生成 - [Multi-agent](/zh-CN/concepts/multi-agent) —— 多智能体架构 -- [Gateway Configuration](/zh-CN/gateway/configuration) —— 会话工具配置选项 +- [Gateway Configuration](/zh-CN/gateway/configuration) —— 会话工具配置项 ## 相关内容 diff --git a/docs/zh-CN/gateway/doctor.md b/docs/zh-CN/gateway/doctor.md index 849eab87d..faed6ed89 100644 --- a/docs/zh-CN/gateway/doctor.md +++ b/docs/zh-CN/gateway/doctor.md @@ -6,15 +6,15 @@ sidebarTitle: Doctor summary: Doctor 命令：健康检查、配置迁移和修复步骤 title: Doctor x-i18n: - generated_at: "2026-04-27T13:09:03Z" + generated_at: "2026-04-27T13:49:01Z" model: gpt-5.4 provider: openai - source_hash: 38438465d9751bea6bb87b0fa17d06da19f5cc4487189ee5bcb3791c78c00486 + source_hash: 1f3a009131c28a0574ce2bb055beecbb321e1664d1ab5b611c64c3f548cda1c6 source_path: gateway/doctor.md workflow: 15 --- -`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的配置/状态，检查健康状况，并提供可执行的修复步骤。 +`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过期的配置/状态、检查健康状况，并提供可执行的修复步骤。 ## 快速开始 @@ -22,7 +22,7 @@ x-i18n: openclaw doctor ``` -### 无头和自动化模式 +### 无头模式和自动化模式 @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - 不经提示应用推荐的修复（在安全的情况下执行修复 + 重启）。 + 无需提示即可应用推荐的修复（在安全情况下执行修复 + 重启）。 @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - 同时应用激进修复（会覆盖自定义 supervisor 配置）。 + 也会应用激进修复（会覆盖自定义 supervisor 配置）。 @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - 在无提示的情况下运行，并且只应用安全迁移（配置规范化 + 磁盘状态迁移）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态时会自动运行旧版状态迁移。 + 在无提示的情况下运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态时，会自动运行旧版状态迁移。 @@ -67,7 +67,7 @@ openclaw doctor -如果你想在写入前先检查更改，请先打开配置文件： +如果你想在写入前先查看更改，请先打开配置文件： ```bash cat ~/.openclaw/openclaw.json @@ -77,30 +77,30 @@ cat ~/.openclaw/openclaw.json - - git 安装的可选预检更新（仅交互模式）。 + - 针对 git 安装的可选预检更新（仅交互模式）。 - UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。 - 健康检查 + 重启提示。 - - Skills 状态摘要（可用/缺失/被阻止）和插件状态。 + - Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。 - - 旧值的配置规范化。 - - 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 - - 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪情况的浏览器迁移检查。 + - 针对旧版值的配置规范化。 + - 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 + - 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。 - OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。 - Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。 - 针对 OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。 - - 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。 - - 旧版插件清单契约键迁移（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。 + - 旧版磁盘状态迁移（sessions/agent 目录/WhatsApp 凭证）。 + - 旧版插件 manifest 合同键迁移（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。 - 旧版 cron 存储迁移（`jobId`, `schedule.cron`, 顶层 delivery/payload 字段，payload `provider`，简单的 `notify: true` webhook 回退任务）。 - - 将旧版智能体 runtime-policy 迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。 + - 将旧版 agent 运行时策略迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。 - - 会话锁文件检查和过期锁清理。 + - 会话锁文件检查和陈旧锁清理。 - 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支会话转录。 - - 状态完整性和权限检查（会话、转录、状态目录）。 - - 本地运行时检查配置文件权限（chmod 600）。 - - 模型认证健康状况：检查 OAuth 过期情况、可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。 - - 检测额外工作区目录（`~/openclaw`）。 + - 状态完整性和权限检查（sessions、transcripts、状态目录）。 + - 本地运行时的配置文件权限检查（`chmod 600`）。 + - 模型认证健康检查：检查 OAuth 过期情况，可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。 + - 额外工作区目录检测（`~/openclaw`）。 - 在启用沙箱隔离时修复沙箱镜像。 @@ -108,72 +108,72 @@ cat ~/.openclaw/openclaw.json - Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。 - Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。 - 渠道状态警告（从正在运行的 Gateway 网关探测）。 - - Supervisor 配置审计（launchd/systemd/schtasks）并可选择修复。 - - 清理在安装或更新期间捕获了 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值的 Gateway 网关服务嵌入式代理环境。 + - supervisor 配置审计（launchd/systemd/schtasks）和可选修复。 + - 清理在安装或更新期间捕获了 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值的 Gateway 网关服务中的嵌入式代理环境。 - Gateway 网关运行时最佳实践检查（Node 与 Bun、版本管理器路径）。 - Gateway 网关端口冲突诊断（默认 `18789`）。 - 针对开放私信策略的安全警告。 - - Gateway 网关本地令牌模式的认证检查（当不存在令牌来源时提供令牌生成功能；不会覆盖令牌 SecretRef 配置）。 - - 设备配对问题检测（待处理的首次配对请求、待处理的角色/作用域升级、本地设备令牌缓存过期漂移，以及已配对记录的认证漂移）。 + - local token 模式的 Gateway 网关认证检查（在没有 token 来源时提供生成 token；不会覆盖 token SecretRef 配置）。 + - 设备配对问题检测（首次配对请求待处理、角色/作用域升级待处理、陈旧的本地设备 token 缓存漂移，以及已配对记录的认证漂移）。 - Linux 上的 systemd linger 检查。 - 工作区 bootstrap 文件大小检查（上下文文件的截断/接近限制警告）。 - - Shell 补全状态检查和自动安装/升级。 - - Memory 搜索 embedding 提供商就绪性检查（本地模型、远程 API 密钥或 QMD 二进制文件）。 - - 源码安装检查（pnpm 工作区不匹配、缺少 UI 资源、缺少 tsx 二进制文件）。 + - shell 补全状态检查和自动安装/升级。 + - Memory 搜索嵌入提供商就绪状态检查（本地模型、远程 API key 或 QMD 二进制文件）。 + - 源码安装检查（pnpm 工作区不匹配、缺失 UI 资源、缺失 tsx 二进制文件）。 - 写入更新后的配置 + 向导元数据。 ## Dreams UI 回填和重置 -Control UI 的 Dreams 场景包含用于 grounded dreaming 工作流的 **Backfill**、**Reset** 和 **Clear Grounded** 操作。这些操作使用 Gateway 网关风格的 doctor RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。 +Control UI 的 Dreams 场景包含用于 grounded dreaming 工作流的 **Backfill**、**Reset** 和 **Clear Grounded** 操作。这些操作使用 Gateway 网关 doctor 风格的 RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。 它们会做什么： -- **Backfill** 会扫描活动工作区中历史的 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM diary 处理，并将可逆的回填条目写入 `DREAMS.md`。 -- **Reset** 只会从 `DREAMS.md` 中删除那些已标记的回填 diary 条目。 -- **Clear Grounded** 只会删除那些来自历史重放、且尚未积累实时召回或每日支持的 staged grounded-only 短期条目。 +- **Backfill** 会扫描活动工作区中历史的 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM diary 过程，并将可逆的回填条目写入 `DREAMS.md`。 +- **Reset** 只会从 `DREAMS.md` 中移除这些已标记的回填 diary 条目。 +- **Clear Grounded** 只会移除那些来自历史回放、且尚未积累实时 recall 或每日支持的 staged grounded-only 短期条目。 它们本身**不会**做什么： -- 它们不会编辑 `MEMORY.md` -- 它们不会运行完整的 doctor 迁移 -- 除非你先显式运行 staged CLI 路径，否则它们不会自动将 grounded 候选项暂存到实时短期晋升存储中 +- 不会编辑 `MEMORY.md` +- 不会运行完整的 doctor 迁移 +- 不会自动将 grounded 候选项暂存到实时短期提升存储中，除非你先显式运行 staged CLI 路径 -如果你希望 grounded 历史重放影响正常的深度晋升流程，请改用 CLI 流程： +如果你想让 grounded 历史回放影响正常的深度提升流程，请改用以下 CLI 流程： ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -这会将 grounded durable 候选项暂存到短期 dreaming 存储中，同时保留 `DREAMS.md` 作为审查界面。 +这样会将 grounded 持久候选项暂存到短期 dreaming 存储中，同时将 `DREAMS.md` 作为审查界面。 -## 详细行为和原因说明 +## 详细行为和原理 - 如果这是一个 git 检出，并且 doctor 以交互方式运行，它会先提供更新选项（fetch/rebase/build），然后再运行 doctor。 + 如果这是一个 git 检出，并且 doctor 以交互模式运行，它会先提供在运行 doctor 之前更新（fetch/rebase/build）的选项。 - 如果配置包含旧版值结构（例如没有特定渠道覆盖的 `messages.ackReaction`），doctor 会将其规范化为当前 schema。 + 如果配置中包含旧版值结构（例如没有渠道专属覆盖的 `messages.ackReaction`），doctor 会将其规范化为当前 schema。 - 这包括旧版 Talk 扁平字段。当前公开的 Talk 配置为 `talk.provider` + `talk.providers.`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 结构重写到 provider 映射中。 + 这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置为 `talk.provider` + `talk.providers.`。doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 结构重写到提供商映射中。 - 当配置包含已弃用键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。 + 当配置包含已弃用的键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。 - Doctor 将会： + Doctor 会： - 说明发现了哪些旧版键。 - 显示它应用的迁移。 - 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。 - 当 Gateway 网关在启动时检测到旧版配置格式，也会自动运行 doctor 迁移，因此过时配置无需人工干预即可修复。Cron 作业存储迁移由 `openclaw doctor --fix` 处理。 + Gateway 网关在启动时检测到旧版配置格式时也会自动运行 doctor 迁移，因此过期配置无需手动干预即可修复。Cron 任务存储迁移由 `openclaw doctor --fix` 处理。 当前迁移包括： @@ -187,286 +187,289 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - 旧版 `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` - `routing.transcribeAudio` → `tools.media.audio.models` - - `messages.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `messages.tts.providers.` + - `messages.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` - `messages.tts.provider: "edge"` 和 `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` 和 `messages.tts.providers.microsoft` - - `channels.discord.voice.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.voice.tts.providers.` - - `channels.discord.accounts..voice.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.accounts..voice.tts.providers.` - - `plugins.entries.voice-call.config.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `plugins.entries.voice-call.config.tts.providers.` + - `channels.discord.voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.` + - `channels.discord.accounts..voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts..voice.tts.providers.` + - `plugins.entries.voice-call.config.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.` - `plugins.entries.voice-call.config.tts.provider: "edge"` 和 `plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"` 和 `providers.microsoft` - `plugins.entries.voice-call.config.provider: "log"` → `"mock"` - `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber` - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - 对于配置了命名 `accounts` 但仍残留单账户顶层渠道值的渠道，将这些账户范围的值移动到为该渠道选定的提升账户中（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的命名/默认目标） + - 对于具有命名 `accounts` 但仍保留单账户顶层渠道值的渠道，将这些账户级值移动到为该渠道选定的提升账户中（多数渠道使用 `accounts.default`；Matrix 可以保留现有的匹配命名/默认目标） - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents） - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - - 删除 `agents.defaults.llm`；对较慢的 provider/模型超时请使用 `models.providers..timeoutSeconds` + - 移除 `agents.defaults.llm`；慢速提供商/模型超时请使用 `models.providers..timeoutSeconds` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - 删除 `browser.relayBindHost`（旧版扩展 relay 设置） - - 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过将 `api` 设为未来或未知枚举值的 provider，而不是直接失败关闭） + - 移除 `browser.relayBindHost`（旧版扩展 relay 设置） + - 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过那些 `api` 被设置为未来或未知枚举值的提供商，而不是以封闭失败方式直接报错） - Doctor 警告还包括多账户渠道的账户默认值指导： + Doctor 警告还包括多账户渠道的默认账户指引： - - 如果配置了两个或更多 `channels..accounts` 条目，但没有设置 `channels..defaultAccount` 或 `accounts.default`，doctor 会警告回退路由可能会选择意外的账户。 - - 如果 `channels..defaultAccount` 设置为未知账户 ID，doctor 会发出警告并列出已配置的账户 ID。 + - 如果在没有 `channels..defaultAccount` 或 `accounts.default` 的情况下配置了两个或更多 `channels..accounts` 条目，doctor 会警告回退路由可能会选择意外的账户。 + - 如果 `channels..defaultAccount` 被设置为未知账户 ID，doctor 会发出警告并列出已配置的账户 ID。 - 如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会把模型强制路由到错误的 API，或将成本清零。Doctor 会发出警告，以便你移除该覆盖并恢复按模型进行的 API 路由 + 成本。 - + 如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型走错误的 API，或将成本归零。Doctor 会发出警告，以便你移除该覆盖并恢复按模型路由的 API + 成本。 - - 如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型： + + 如果你的浏览器配置仍然指向已移除的 Chrome 扩展路径，doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型： - `browser.profiles.*.driver: "extension"` 会变为 `"existing-session"` - `browser.relayBindHost` 会被移除 当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置文件时，doctor 还会审计主机本地 Chrome MCP 路径： - - 检查同一主机上是否安装了 Google Chrome，以支持默认自动连接配置文件 + - 检查同一主机上是否已安装 Google Chrome，以供默认自动连接配置文件使用 - 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告 - 提醒你在浏览器 inspect 页面中启用远程调试（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`） - Doctor 无法替你启用 Chrome 端设置。主机本地 Chrome MCP 仍然要求： + Doctor 无法为你启用 Chrome 侧设置。主机本地 Chrome MCP 仍然要求： - - Gateway 网关/节点主机上有一个 144+ 的 Chromium 内核浏览器 + - Gateway 网关/节点主机上有 144+ 的 Chromium 内核浏览器 - 浏览器在本地运行 - - 该浏览器已启用远程调试 + - 在该浏览器中启用远程调试 - 在浏览器中批准首次附加同意提示 - 这里的就绪情况仅针对本地附加前置条件。Existing-session 会保留当前的 Chrome MCP 路由限制；像 `responsebody`、PDF 导出、下载拦截和批量操作这样的高级路由仍然需要受管浏览器或原始 CDP 配置文件。 + 这里的就绪状态仅涉及本地附加前置条件。Existing-session 会保留当前 Chrome MCP 路由限制；像 `responsebody`、PDF 导出、下载拦截和批量操作这样的高级路由仍然需要受管浏览器或原始 CDP 配置文件。 - 此检查**不**适用于 Docker、沙箱、remote-browser 或其他无头流程。那些流程将继续使用原始 CDP。 + 此检查**不**适用于 Docker、沙箱、remote-browser 或其他无头流程。这些流程会继续使用原始 CDP。 - 当配置了 OpenAI Codex OAuth 配置文件时，doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈能否校验证书链。如果探测因证书错误失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），doctor 会输出特定平台的修复指导。在 macOS 上，如果你使用的是 Homebrew 安装的 Node，通常的修复方式是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，此探测也会运行。 + 当配置了 OpenAI Codex OAuth 配置文件时，doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈是否能够校验证书链。如果探测因证书错误而失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），doctor 会输出平台特定的修复指引。在 macOS 上使用 Homebrew Node 时，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，探测也会运行。 - 如果你之前在 `models.providers.openai-codex` 下添加过旧版 OpenAI 传输设置，它们可能会遮蔽新版本自动使用的内置 Codex OAuth 提供商路径。Doctor 在发现这些旧传输设置与 Codex OAuth 并存时会发出警告，以便你删除或重写过时的传输覆盖，并恢复内置路由/回退行为。自定义代理和仅标头覆盖仍然受支持，不会触发此警告。 + 如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽较新版本自动使用的内置 Codex OAuth 提供商路径。当 doctor 看到这些旧的传输设置与 Codex OAuth 同时存在时，会发出警告，以便你移除或重写过期的传输覆盖，从而恢复内置路由/回退行为。自定义代理和仅头部覆盖仍受支持，不会触发此警告。 - 当启用了内置 Codex 插件时，doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI runner 解析。当你希望通过 PI 使用 Codex OAuth/订阅认证时，这种组合是有效的，但它很容易与原生 Codex app-server harness 混淆。Doctor 会发出警告，并指向显式 app-server 结构：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。 + 启用内置 Codex 插件时，doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI 运行器解析。当你想通过 PI 使用 Codex OAuth/订阅认证时，这种组合是有效的，但它很容易与原生 Codex app-server harness 混淆。Doctor 会发出警告，并指向显式的 app-server 形式：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。 - Doctor 不会自动修复此问题，因为这两条路线都有效： + Doctor 不会自动修复这一点，因为这两种路由都有效： - - `openai-codex/*` + PI 表示“通过常规 OpenClaw runner 使用 Codex OAuth/订阅认证。” - - `openai/*` + `runtime: "codex"` 表示“通过原生 Codex app-server 运行内嵌回合。” - - `/codex ...` 表示“在聊天中控制或绑定原生 Codex 会话。” + - `openai-codex/*` + PI 表示“通过正常的 OpenClaw 运行器使用 Codex OAuth/订阅认证。” + - `openai/*` + `runtime: "codex"` 表示“通过原生 Codex app-server 运行嵌入式回合。” + - `/codex ...` 表示“从聊天中控制或绑定一个原生 Codex 会话。” - `/acp ...` 或 `runtime: "acp"` 表示“使用外部 ACP/acpx 适配器。” - 如果出现此警告，请选择你原本打算使用的路线，并手动编辑配置。如果 PI Codex OAuth 是有意为之，请保持此警告不变。 + 如果出现此警告，请选择你原本想使用的路由并手动编辑配置。如果是有意使用 PI Codex OAuth，请保持该警告不变。 Doctor 可以将旧版磁盘布局迁移到当前结构： - 会话存储 + 转录： - - 从 `~/.openclaw/sessions/` 迁移到 `~/.openclaw/agents//sessions/` + - 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents//sessions/` - Agent 目录： - - 从 `~/.openclaw/agent/` 迁移到 `~/.openclaw/agents//agent/` + - 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents//agent/` - WhatsApp 认证状态（Baileys）： - - 从旧版 `~/.openclaw/credentials/*.json`（不包括 `oauth.json`） - - 迁移到 `~/.openclaw/credentials/whatsapp//...`（默认账户 ID：`default`） + - 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外） + - 到 `~/.openclaw/credentials/whatsapp//...`（默认账户 ID：`default`） - 这些迁移会以尽力而为且幂等的方式执行；当保留任何旧版文件夹作为备份时，doctor 会发出警告。Gateway 网关/CLI 在启动时也会自动迁移旧版会话 + Agent 目录，因此历史记录/认证/模型会落到按智能体划分的路径中，而无需手动运行 doctor。WhatsApp 认证则刻意只通过 `openclaw doctor` 迁移。Talk provider/provider 映射规范化现在按结构相等性比较，因此仅键顺序不同的差异不再触发重复的无操作 `doctor --fix` 更改。 + 这些迁移采用尽力而为且幂等的方式；当 doctor 将任何旧目录作为备份保留下来时，会发出警告。Gateway 网关/CLI 在启动时也会自动迁移旧版 sessions + agent 目录，因此历史记录/认证/模型会进入每个 agent 的路径，而无需手动运行 doctor。WhatsApp 认证则有意仅通过 `openclaw doctor` 迁移。Talk provider/提供商映射规范化现在按结构相等性比较，因此仅键顺序不同的差异不再触发重复的空操作 `doctor --fix` 更改。 - - Doctor 会扫描所有已安装插件的清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。发现后，它会提供将它们移动到 `contracts` 对象中，并原地重写清单文件。此迁移是幂等的；如果 `contracts` 键已经包含相同值，则只会删除旧版键，而不会重复数据。 + + Doctor 会扫描所有已安装插件的 manifest，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到后，它会建议将它们移入 `contracts` 对象，并原地重写 manifest 文件。该迁移是幂等的；如果 `contracts` 键中已包含相同值，则会移除旧键而不会重复数据。 - Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或在覆盖时使用 `cron.store`），查找调度器仍为兼容性接受的旧作业结构。 + Doctor 还会检查 cron 任务存储（默认是 `~/.openclaw/cron/jobs.json`，或在覆盖时使用 `cron.store`），查找调度器为了兼容性仍然接受的旧任务结构。 - 当前 cron 清理包括： + 当前的 cron 清理包括： - `jobId` → `id` - `schedule.cron` → `schedule.expr` - 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload` - 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery` - payload `provider` delivery 别名 → 显式 `delivery.channel` - - 简单的旧版 `notify: true` webhook 回退作业 → 显式 `delivery.mode="webhook"`，并设置 `delivery.to=cron.webhook` + - 简单的旧版 `notify: true` webhook 回退任务 → 显式 `delivery.mode="webhook"` 且 `delivery.to=cron.webhook` - Doctor 只会在能保证不改变行为的情况下自动迁移 `notify: true` 作业。如果某个作业把旧版 notify 回退和现有的非 webhook 交付模式结合在一起，doctor 会发出警告，并将该作业留给人工检查。 + Doctor 只会在能够不改变行为的情况下自动迁移 `notify: true` 任务。如果某个任务将旧版 notify 回退与现有的非 webhook delivery 模式组合在一起，doctor 会发出警告，并将该任务留给你手动审查。 - Doctor 会扫描每个智能体会话目录中的过期写锁文件——这些文件通常是在会话异常退出时遗留下来的。对于找到的每个锁文件，它会报告：路径、PID、该 PID 是否仍存活、锁的年龄，以及它是否被视为过期（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除过期锁文件；否则它会输出说明，并指示你使用 `--fix` 重新运行。 + Doctor 会扫描每个 agent 会话目录中的陈旧写锁文件——这些文件通常是会话异常退出后遗留的。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍存活、锁年龄，以及是否被视为陈旧（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除陈旧锁文件；否则，它会打印说明并提示你使用 `--fix` 重新运行。 - Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 prompt transcript 重写 bug 创建的重复分支结构：一个包含 OpenClaw 内部运行时上下文的已放弃用户回合，以及一个包含相同可见用户提示的活动同级分支。在 `--fix` / `--repair` 模式下，doctor 会在原文件旁边为每个受影响文件创建备份，并将转录重写为活动分支，这样 Gateway 网关历史记录和 Memory 读取器就不会再看到重复回合。 + Doctor 会扫描 agent 会话 JSONL 文件，查找由 2026.4.24 prompt transcript 重写 bug 产生的重复分支结构：一个被放弃的用户回合包含 OpenClaw 内部运行时上下文，另一个活跃的同级分支包含相同的可见用户提示。在 `--fix` / `--repair` 模式下，doctor 会在原文件旁边备份每个受影响文件，并将转录重写为活跃分支，这样 Gateway 网关历史记录和 Memory 读取器就不会再看到重复回合。 - 状态目录是运行中的核心中枢。如果它消失了，你会丢失会话、凭证、日志和配置（除非你在其他地方有备份）。 + 状态目录是运行中的“脑干”。如果它消失，你将失去会话、凭证、日志和配置（除非你在其他地方有备份）。 Doctor 会检查： - - **状态目录缺失**：警告灾难性的状态丢失，提示重新创建目录，并提醒你它无法恢复缺失数据。 - - **状态目录权限**：验证可写性；会提供修复权限选项（并在检测到所有者/组不匹配时输出 `chown` 提示）。 - - **macOS 云同步状态目录**：当状态路径解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为基于同步的路径可能导致较慢 I/O 以及锁/同步竞争。 - - **Linux SD 或 eMMC 状态目录**：当状态路径解析到 `mmcblk*` 挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入场景下可能更慢、磨损更快。 + - **状态目录缺失**：警告灾难性的状态丢失，提示重新创建目录，并提醒你它无法恢复丢失的数据。 + - **状态目录权限**：验证可写性；提供修复权限的选项（当检测到所有者/组不匹配时，还会给出 `chown` 提示）。 + - **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为基于同步的路径可能导致更慢的 I/O 以及锁/同步竞争。 + - **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入下可能更慢且磨损更快。 - **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史记录并避免 `ENOENT` 崩溃所必需的。 - **转录不匹配**：当最近的会话条目缺少转录文件时发出警告。 - - **主会话 “1-line JSONL”**：当主转录只有一行时标记出来（说明历史没有持续累积）。 - - **多个状态目录**：当多个 home 目录中存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（不同安装之间的历史可能会分裂）。 - - **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态就存储在那里）。 - - **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对组/全体用户可读，会发出警告，并提供收紧到 `600` 的选项。 + - **主会话“单行 JSONL”**：当主转录只有一行时进行标记（历史记录没有持续累积）。 + - **多个状态目录**：当跨 home 目录存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在不同安装之间分裂）。 + - **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态存储在那里）。 + - **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对组/所有用户可读，则发出警告，并提供收紧为 `600` 的选项。 - - Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并能在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已过期，它会建议使用 Anthropic API 密钥或 Anthropic setup-token 路径。只有在交互模式（TTY）下运行时才会显示刷新提示；`--non-interactive` 会跳过刷新尝试。 + + Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已过期，它会建议使用 Anthropic API key 或 Anthropic setup-token 路径。刷新提示只会在交互模式（TTY）下出现；`--non-interactive` 会跳过刷新尝试。 - 当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或者提供商要求你重新登录），doctor 会报告需要重新认证，并输出确切的 `openclaw models auth login --provider ...` 命令供你运行。 + 当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商提示你需要重新登录），doctor 会报告需要重新认证，并打印确切的 `openclaw models auth login --provider ...` 命令供你运行。 - Doctor 还会报告那些由于以下原因而暂时不可用的 auth-profile： + Doctor 还会报告由于以下原因而暂时不可用的 auth-profile： - - 短期冷却（速率限制/超时/认证失败） - - 长时间禁用（计费/额度失败） + - 短暂冷却（速率限制/超时/认证失败） + - 更长期禁用（计费/额度失败） - - 如果设置了 `hooks.gmail.model`，doctor 会根据目录和 allowlist 校验该模型引用，并在它无法解析或不被允许时发出警告。 + + 如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在其无法解析或不被允许时发出警告。 启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。 - Doctor 只会为当前配置中处于活动状态的内置插件，或由其内置清单默认启用的内置插件校验运行时依赖，例如 `plugins.entries.discord.enabled: true`、旧版 `channels.discord.enabled: true`，或默认启用的内置 provider。如果有任何依赖缺失，doctor 会报告这些包，并在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下安装它们。外部插件仍然使用 `openclaw plugins install` / `openclaw plugins update`；doctor 不会为任意插件路径安装依赖。 + Doctor 只会验证当前配置中活跃或由其内置 manifest 默认启用的内置插件的运行时依赖，例如 `plugins.entries.discord.enabled: true`、旧版 `channels.discord.enabled: true`，或默认启用的内置提供商。如果缺少任何依赖，doctor 会报告这些包，并在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下安装它们。外部插件仍然使用 `openclaw plugins install` / `openclaw plugins update`；doctor 不会为任意插件路径安装依赖。 - 在 doctor 修复期间，内置运行时依赖的 npm 安装会在 TTY 会话中显示 spinner 进度，在管道/无头输出中显示周期性的行进度。Gateway 网关和本地 CLI 也可以在导入内置插件之前，按需修复处于活动状态的内置插件运行时依赖。这些安装被限定在插件运行时安装根目录中执行，禁用 scripts，不写入 package lock，并由安装根锁保护，以避免并发 CLI 或 Gateway 网关启动同时修改同一棵 `node_modules` 树。 + 在 doctor 修复期间，内置运行时依赖的 npm 安装会在 TTY 会话中显示旋转进度，在管道/无头输出中显示周期性的行进度。Gateway 网关和本地 CLI 还可以在导入某个活跃的内置插件之前，按需修复其运行时依赖。这些安装被限定在插件运行时安装根目录下，运行时禁用脚本，不写入 package lock，并通过安装根锁进行保护，以避免并发的 CLI 或 Gateway 网关启动同时修改同一个 `node_modules` 树。 - Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供移除它们以及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关的服务，并输出清理提示。带有 profile 名称的 OpenClaw Gateway 网关服务被视为一等公民，不会被标记为“额外”服务。 + Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供移除它们、然后使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类 Gateway 网关服务并输出清理提示。带有 profile 名称的 OpenClaw Gateway 网关服务被视为一等公民，不会被标记为“额外”。 + + 在 Linux 上，如果用户级 Gateway 网关服务缺失，但存在系统级 OpenClaw Gateway 网关服务，doctor 不会自动安装第二个用户级服务。请使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 进行检查；然后删除重复项，或者在系统 supervisor 管理 Gateway 网关生命周期时设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。 + - - 当某个 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时，doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续。在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查会被完全跳过。 + + 当 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时，doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都不是致命错误；错误会被记录，启动会继续。在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查会被完全跳过。 - Doctor 现在会将设备配对状态纳入常规健康检查。 + Doctor 现在会把设备配对状态纳入常规健康检查的一部分。 它会报告： - - 待处理的首次配对请求 - - 已配对设备待处理的角色升级 - - 已配对设备待处理的作用域升级 + - 首次配对请求待处理 + - 已配对设备的角色升级待处理 + - 已配对设备的作用域升级待处理 - 公钥不匹配修复：设备 ID 仍然匹配，但设备身份已不再匹配已批准记录 - - 已配对记录缺少与已批准角色对应的活动令牌 - - 已配对令牌的作用域漂移到了已批准配对基线之外 - - 当前机器的本地缓存设备令牌条目早于 Gateway 网关侧令牌轮换，或携带过期的作用域元数据 + - 已配对记录缺少已批准角色的活动 token + - 已配对 token 的作用域漂移到已批准配对基线之外 + - 当前机器的本地缓存设备 token 条目早于 Gateway 网关侧 token 轮换，或携带过期的作用域元数据 - Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它只会输出精确的下一步操作： + Doctor 不会自动批准配对请求，也不会自动轮换设备 token。它会直接输出精确的下一步操作： - 使用 `openclaw devices list` 检查待处理请求 - - 使用 `openclaw devices approve ` 批准确切请求 - - 使用 `openclaw devices rotate --device --role ` 轮换新的令牌 + - 使用 `openclaw devices approve ` 批准指定请求 + - 使用 `openclaw devices rotate --device --role ` 轮换新的 token - 使用 `openclaw devices remove ` 删除并重新批准过期记录 - 这解决了常见的“已经配对但仍然提示需要配对”的漏洞：doctor 现在会区分首次配对、待处理的角色/作用域升级，以及过期的令牌/设备身份漂移。 + 这填补了常见的“已经配对但仍然提示需要配对”的漏洞：doctor 现在可以区分首次配对、待处理的角色/作用域升级，以及过期 token/设备身份漂移。 - 当某个 provider 对私信开放但没有 allowlist，或某项策略配置存在危险方式时，doctor 会发出警告。 + 当某个提供商对私信开放但没有允许列表，或者某项策略以危险方式配置时，doctor 会发出警告。 - 如果以 systemd 用户服务运行，doctor 会确保已启用 lingering，以便 Gateway 网关在注销后仍保持运行。 + 如果以 systemd 用户服务运行，doctor 会确保启用 lingering，以便 Gateway 网关在注销后继续运行。 - Doctor 会输出默认智能体的工作区状态摘要： + Doctor 会输出默认 agent 的工作区状态摘要： - - **Skills 状态**：统计可用、缺少要求和被 allowlist 阻止的 Skills 数量。 + - **Skills 状态**：统计符合条件、缺少要求以及被允许列表阻止的 Skills。 - **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。 - - **插件状态**：统计已启用/已禁用/出错的插件；列出所有出错插件的插件 ID；报告内置插件能力。 + - **插件状态**：统计已启用/已禁用/出错的插件；列出出错插件的插件 ID；报告内置插件能力。 - **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。 - - **插件诊断**：展示插件注册表在加载时发出的任何警告或错误。 + - **插件诊断**：展示插件注册表在加载时输出的任何警告或错误。 - Doctor 会检查工作区 bootstrap 文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会按文件报告原始字符数与注入后字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，doctor 会输出关于调整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的建议。 + Doctor 会检查工作区 bootstrap 文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过已配置的字符预算。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，doctor 会输出调整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。 - 当 `openclaw doctor --fix` 移除缺失的渠道插件时，它也会移除引用该插件的悬空渠道范围配置：`channels.` 条目、指向该渠道的 heartbeat 目标，以及 `agents.*.models["/*"]` 覆盖。这可以防止 Gateway 网关启动循环：渠道运行时已不存在，但配置仍要求 Gateway 网关绑定到它。 + 当 `openclaw doctor --fix` 移除缺失的渠道插件时，它还会移除引用该插件的悬空渠道作用域配置：`channels.` 条目、命名该渠道的 heartbeat 目标，以及 `agents.*.models["/*"]` 覆盖。这可以防止 Gateway 网关在渠道运行时已不存在、但配置仍要求 Gateway 网关绑定到它时进入启动循环。 - - Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全： + + Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否安装了 Tab 补全： - - 如果 shell profile 使用较慢的动态补全模式（`source <(openclaw completion ...)`），doctor 会将其升级为更快的缓存文件变体。 - - 如果 profile 中已配置补全，但缓存文件缺失，doctor 会自动重新生成缓存。 - - 如果完全没有配置补全，doctor 会提示安装（仅交互模式；`--non-interactive` 时跳过）。 + - 如果 shell profile 使用了较慢的动态补全模式（`source <(openclaw completion ...)`），doctor 会将其升级为更快的缓存文件变体。 + - 如果 profile 中已配置补全但缓存文件缺失，doctor 会自动重新生成缓存。 + - 如果完全没有配置补全，doctor 会提示安装（仅交互模式；`--non-interactive` 下跳过）。 运行 `openclaw completion --write-state` 可手动重新生成缓存。 - - Doctor 会检查本地 Gateway 网关令牌认证的就绪情况。 + + Doctor 会检查本地 Gateway 网关 token 认证的就绪状态。 - - 如果令牌模式需要令牌，而不存在令牌来源，doctor 会提供生成令牌的选项。 - - 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，doctor 会发出警告，并且不会用明文覆盖它。 - - `openclaw doctor --generate-gateway-token` 仅在未配置令牌 SecretRef 时强制生成令牌。 + - 如果 token 模式需要 token 且不存在 token 来源，doctor 会提供生成 token 的选项。 + - 如果 `gateway.auth.token` 由 SecretRef 管理但当前不可用，doctor 会发出警告，并且不会用明文覆盖它。 + - `openclaw doctor --generate-gateway-token` 只会在未配置 token SecretRef 时强制生成 token。 某些修复流程需要检查已配置的凭证，同时又不能削弱运行时快速失败行为。 - - `openclaw doctor --fix` 现在会像 Status 系列命令一样，使用同样的只读 SecretRef 摘要模型来进行有针对性的配置修复。 - - 例如：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的 bot 凭证。 - - 如果 Telegram bot 令牌是通过 SecretRef 配置的，但在当前命令路径中不可用，doctor 会报告该凭证是“已配置但不可用”，并跳过自动解析，而不是崩溃或误报令牌缺失。 + - `openclaw doctor --fix` 现在会像 Status 系列命令一样，使用同样的只读 SecretRef 摘要模型来执行定向配置修复。 + - 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在凭证可用时尝试使用已配置的 bot 凭证。 + - 如果 Telegram bot token 是通过 SecretRef 配置的，但在当前命令路径下不可用，doctor 会报告该凭证为“已配置但不可用”，并跳过自动解析，而不是崩溃或误报 token 缺失。 - Doctor 会执行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。 + Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。 - - Doctor 会检查默认智能体所配置的 Memory 搜索 embedding provider 是否就绪。其行为取决于所配置的后端和 provider： + + Doctor 会检查默认 agent 所配置的 Memory 搜索嵌入提供商是否就绪。其行为取决于已配置的后端和提供商： - - **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会输出修复指导，包括 npm 包和手动二进制路径选项。 - - **显式本地 provider**：检查本地模型文件或已识别的远程/可下载模型 URL 是否存在。如果缺失，会建议切换到远程 provider。 - - **显式远程 provider**（`openai`、`voyage` 等）：验证环境或认证存储中是否存在 API 密钥。缺失时会输出可执行的修复提示。 - - **自动 provider**：先检查本地模型可用性，然后按自动选择顺序尝试每个远程 provider。 + - **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会输出修复指引，包括 npm 包和手动二进制路径选项。 + - **显式本地提供商**：检查本地模型文件或已识别的远程/可下载模型 URL 是否存在。如果不存在，则建议切换到远程提供商。 + - **显式远程提供商**（`openai`、`voyage` 等）：验证环境或 auth 存储中是否存在 API key。如果缺失，则输出可执行的修复提示。 + - **自动提供商**：先检查本地模型可用性，然后按自动选择顺序依次尝试每个远程提供商。 - 当存在缓存的 Gateway 网关探测结果时（检查时 Gateway 网关是健康的），doctor 会将其结果与 CLI 可见配置进行交叉比对，并说明任何差异。Doctor 不会在默认路径上启动新的 embedding ping；如果你想执行实时 provider 检查，请使用深度 Memory 状态命令。 + 当存在缓存的 Gateway 网关探测结果时（检查时 Gateway 网关健康），doctor 会将该结果与 CLI 可见的配置进行交叉比对，并指出任何差异。Doctor 不会在默认路径上发起新的嵌入 ping；如果你想进行实时提供商检查，请使用深度 Memory Status 命令。 - 使用 `openclaw memory status --deep` 可在运行时验证 embedding 就绪情况。 + 使用 `openclaw memory status --deep` 可在运行时验证嵌入就绪状态。 - 如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告带有建议修复方式的警告。 + 如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告带有建议修复方案的警告。 - - Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少或落后于当前默认值（例如 systemd 的 network-online 依赖和重启延迟）。发现不匹配时，它会建议更新，并可将服务文件/任务重写为当前默认值。 + + Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少默认值或使用了过期默认值（例如 systemd 的 network-online 依赖和重启延迟）。发现不匹配时，它会建议更新，并可将服务文件/任务重写为当前默认值。 说明： - - `openclaw doctor` 会在重写 supervisor 配置前进行提示。 + - `openclaw doctor` 会在重写 supervisor 配置前提示确认。 - `openclaw doctor --yes` 会接受默认修复提示。 - `openclaw doctor --repair` 会在无提示的情况下应用推荐修复。 - `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。 - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` 会让 doctor 在 Gateway 网关服务生命周期上保持只读。它仍会报告服务健康状况并运行非服务修复，但会跳过服务安装/启动/重启/bootstrap、supervisor 配置重写和旧版服务清理，因为这些生命周期由外部 supervisor 接管。 - - 如果令牌认证需要令牌，而 `gateway.auth.token` 由 SecretRef 管理，doctor 的服务安装/修复会校验该 SecretRef，但不会将解析得到的明文令牌值持久化到 supervisor 服务环境元数据中。 - - Doctor 会检测由 `.env`/SecretRef 支持的受管服务环境值；如果旧版 LaunchAgent、systemd 或 Windows Scheduled Task 安装曾将其内联嵌入，它会重写服务元数据，使这些值从运行时来源加载，而不是从 supervisor 定义中加载。 - - 如果令牌认证需要令牌，而配置的令牌 SecretRef 未解析，doctor 会阻止安装/修复路径，并提供可执行的指导。 - - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，doctor 会阻止安装/修复，直到显式设置模式。 - - 对于 Linux user-systemd 单元，doctor 的令牌漂移检查现在在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。 - - 当配置最后一次由较新版本写入时，doctor 服务修复会拒绝对来自较旧 OpenClaw 二进制文件的 Gateway 网关服务执行重写、停止或重启。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。 + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` 会让 doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状况并运行非服务修复，但会跳过服务安装/启动/重启/bootstrap、supervisor 配置重写以及旧版服务清理，因为该生命周期由外部 supervisor 管理。 + - 如果 token 认证需要 token，且 `gateway.auth.token` 由 SecretRef 管理，doctor 的服务安装/修复会验证该 SecretRef，但不会将已解析的明文 token 值持久化到 supervisor 服务环境元数据中。 + - Doctor 会检测由较旧的 LaunchAgent、systemd 或 Windows Scheduled Task 安装内联嵌入的受管理 `.env`/SecretRef 支持的服务环境值，并重写服务元数据，使这些值从运行时来源加载，而不是从 supervisor 定义中加载。 + - Doctor 会检测当 `gateway.port` 更改后，服务命令是否仍固定使用旧的 `--port`，并将服务元数据重写为当前端口。 + - 如果 token 认证需要 token，而已配置的 token SecretRef 无法解析，doctor 会阻止安装/修复路径，并提供可执行的指引。 + - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，而 `gateway.auth.mode` 未设置，doctor 会阻止安装/修复，直到显式设置 mode。 + - 对于 Linux 用户级 systemd 单元，doctor 的 token 漂移检查现在同时包含 `Environment=` 和 `EnvironmentFile=` 来源，以便比较服务认证元数据。 + - 当配置最后一次由较新版本写入时，doctor 服务修复会拒绝重写、停止或重启来自较旧 OpenClaw 二进制文件的 Gateway 网关服务。参见[Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。 - 你始终可以通过 `openclaw gateway install --force` 强制执行完整重写。 - Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。 + Doctor 会检查服务运行时（PID、最近退出状态），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。 - 当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径在升级后可能会失效，因为服务不会加载你的 shell init。Doctor 会在系统 Node 安装可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。 + 当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径在升级后可能失效，因为服务不会加载你的 shell 初始化。Doctor 会在可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。 - Doctor 会持久化任何配置变更，并写入向导元数据以记录此次 doctor 运行。 + Doctor 会持久化任何配置更改，并写入向导元数据以记录本次 doctor 运行。 - 如果工作区尚未配置 Memory 系统，doctor 会给出建议；如果工作区尚未纳入 git，它还会输出备份提示。 + 当工作区缺少 Memory 系统时，doctor 会给出建议；如果工作区尚未受 git 管理，它还会输出备份提示。 - 参见 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace) 获取关于工作区结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab）。 + 有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。 diff --git a/docs/zh-CN/gateway/index.md b/docs/zh-CN/gateway/index.md index b9057dbe7..36b994c1b 100644 --- a/docs/zh-CN/gateway/index.md +++ b/docs/zh-CN/gateway/index.md @@ -1,13 +1,13 @@ --- read_when: - 运行或调试 Gateway 网关进程 -summary: Gateway 网关服务、生命周期与运维的操作手册 -title: Gateway 网关操作手册 +summary: Gateway 网关服务、生命周期和运维运行手册 +title: Gateway 网关运行手册 x-i18n: - generated_at: "2026-04-26T04:11:42Z" + generated_at: "2026-04-27T13:48:59Z" model: gpt-5.4 provider: openai - source_hash: 775c7288ce1fa666f65c0fc4ff1fc06b0cd14589fc932af1944ac7eeb126729c + source_hash: 14f3d288c426848bc176291ff084a2b63b00e81739cd02f31fdf517d230d8111 source_path: gateway/index.md workflow: 15 --- @@ -16,16 +16,16 @@ x-i18n: - 以症状为起点的诊断，提供精确的命令步骤和日志特征。 + 以症状为起点的诊断，包含精确的命令步骤和日志特征。 面向任务的设置指南 + 完整配置参考。 - SecretRef 合约、运行时快照行为，以及迁移/重载操作。 + SecretRef 契约、运行时快照行为，以及迁移/重载操作。 - - 精确的 `secrets apply` 目标/路径规则，以及仅引用的 auth-profile 行为。 + + 精确的 `secrets apply` 目标/路径规则，以及仅 ref 的 auth-profile 行为。 @@ -36,7 +36,7 @@ x-i18n: ```bash openclaw gateway --port 18789 -# 将 debug/trace 镜像输出到标准 I/O +# 将 debug/trace 镜像输出到 stdio openclaw gateway --port 18789 --verbose # 强制终止所选端口上的监听器，然后启动 openclaw gateway --force @@ -52,7 +52,7 @@ openclaw status openclaw logs --follow ``` -健康基线：`Runtime: running`、`Connectivity probe: ok`，以及符合你预期的 `Capability: ...`。当你需要读取范围的 RPC 证明，而不仅仅是可达性时，请使用 `openclaw gateway status --require-rpc`。 +健康基线：`Runtime: running`、`Connectivity probe: ok`，以及与你预期一致的 `Capability: ...`。当你需要读作用域的 RPC 证明，而不仅仅是可达性时，请使用 `openclaw gateway status --require-rpc`。 @@ -62,7 +62,7 @@ openclaw logs --follow openclaw channels status --probe ``` -当 Gateway 网关可达时，这会按账号执行实时渠道探测和可选审计。 +在 Gateway 网关可达时，这会运行实时的逐账户渠道探测和可选审计。 如果 Gateway 网关不可达，CLI 会回退为仅配置的渠道摘要， 而不是实时探测输出。 @@ -70,9 +70,9 @@ openclaw channels status --probe -Gateway 网关配置重载会监视当前生效的配置文件路径（从 profile/state 默认值解析，或在设置时使用 `OPENCLAW_CONFIG_PATH`）。 +Gateway 网关配置重载会监视活动配置文件路径（从 profile/state 默认值解析，或在设置时使用 `OPENCLAW_CONFIG_PATH`）。 默认模式为 `gateway.reload.mode="hybrid"`。 -首次成功加载后，运行中的进程会提供当前内存中配置快照；成功重载后会以原子方式替换该快照。 +首次成功加载后，运行中的进程会提供当前内存中配置快照；成功重载时会以原子方式切换该快照。 ## 运行时模型 @@ -81,16 +81,16 @@ Gateway 网关配置重载会监视当前生效的配置文件路径（从 profi - 单一复用端口用于： - WebSocket 控制/RPC - HTTP API，兼容 OpenAI（`/v1/models`、`/v1/embeddings`、`/v1/chat/completions`、`/v1/responses`、`/tools/invoke`） - - 控制 UI 和钩子 + - 控制 UI 和 hooks - 默认绑定模式：`loopback`。 -- 默认要求鉴权。共享密钥设置使用 +- 默认需要身份验证。共享密钥设置使用 `gateway.auth.token` / `gateway.auth.password`（或 - `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`），非 loopback - 反向代理设置可使用 `gateway.auth.mode: "trusted-proxy"`。 + `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`），而非 loopback + 的反向代理设置可以使用 `gateway.auth.mode: "trusted-proxy"`。 ## 兼容 OpenAI 的端点 -OpenClaw 当前最具杠杆效应的兼容性接口是： +OpenClaw 现在最具杠杆效应的兼容性接口是： - `GET /v1/models` - `GET /v1/models/{id}` @@ -108,9 +108,9 @@ OpenClaw 当前最具杠杆效应的兼容性接口是： - `/v1/models` 以智能体为先：它返回 `openclaw`、`openclaw/default` 和 `openclaw/`。 - `openclaw/default` 是稳定别名，始终映射到已配置的默认智能体。 -- 当你需要后端提供商/模型覆盖时，使用 `x-openclaw-model`；否则将继续由所选智能体的常规模型和嵌入设置控制。 +- 当你想要后端提供商/模型覆盖时，请使用 `x-openclaw-model`；否则，所选智能体的常规模型和嵌入设置仍会保持控制。 -所有这些都运行在主 Gateway 网关端口上，并与 Gateway 网关其余 HTTP API 使用相同的受信任操作员鉴权边界。 +以上所有接口都运行在主 Gateway 网关端口上，并与 Gateway 网关其余 HTTP API 使用相同的可信操作员身份验证边界。 ### 端口和绑定优先级 @@ -119,10 +119,12 @@ OpenClaw 当前最具杠杆效应的兼容性接口是： | Gateway 网关端口 | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` | | 绑定模式 | CLI/override → `gateway.bind` → `loopback` | -当 Gateway 网关启动为非 loopback 绑定植入本地 -控制 UI 源时，也会使用相同的实际端口和绑定。例如，`--bind lan --port 3000` -会在运行时校验开始前植入 `http://localhost:3000` 和 `http://127.0.0.1:3000`。请将任何远程浏览器源（例如 HTTPS 代理 URL）显式添加到 -`gateway.controlUi.allowedOrigins`。 +已安装的 Gateway 网关服务会在 supervisor 元数据中记录解析后的 `--port`。更改 `gateway.port` 后，请运行 `openclaw doctor --fix` 或 `openclaw gateway install --force`，这样 launchd/systemd/schtasks 才会在新端口上启动进程。 + +Gateway 网关启动时，在为非 loopback 绑定预填充本地 +控制 UI origins 时，会使用相同的生效端口和绑定。例如，`--bind lan --port 3000` +会在运行时验证之前预填充 `http://localhost:3000` 和 `http://127.0.0.1:3000`。请将任何远程浏览器 origins，例如 HTTPS 代理 URL，显式添加到 +`gateway.controlUi.allowedOrigins` 中。 ### 热重载模式 @@ -130,8 +132,8 @@ OpenClaw 当前最具杠杆效应的兼容性接口是： | --------------------- | ------------------------------------------ | | `off` | 不重载配置 | | `hot` | 仅应用可安全热更新的更改 | -| `restart` | 在需要重启的更改时重启 | -| `hybrid`（默认） | 安全时热应用，需要时重启 | +| `restart` | 在需要重启的更改上执行重启 | +| `hybrid` (default) | 安全时热应用，需要时重启 | ## 操作员命令集 @@ -147,15 +149,15 @@ openclaw logs --follow openclaw doctor ``` -`gateway status --deep` 用于额外的服务发现（LaunchDaemons/systemd 系统 -单元/schtasks），而不是更深入的 RPC 健康探测。 +`gateway status --deep` 用于额外的服务发现（LaunchDaemons/systemd system +units/schtasks），而不是更深入的 RPC 健康探测。 ## 多个 Gateway 网关（同一主机） -大多数安装应在每台机器上运行一个 Gateway 网关。单个 Gateway 网关可以承载多个 +大多数安装应当每台机器运行一个 Gateway 网关。单个 Gateway 网关可以托管多个 智能体和渠道。 -只有在你明确需要隔离或救援机器人时，才需要多个 Gateway 网关。 +只有在你有意需要隔离或救援机器人时，才需要多个 Gateway 网关。 有用的检查： @@ -164,12 +166,12 @@ openclaw gateway status --deep openclaw gateway probe ``` -预期结果： +预期表现： - `gateway status --deep` 可能报告 `Other gateway-like services detected (best effort)` - 并在仍存在过期的 launchd/systemd/schtasks 安装时输出清理提示。 -- 当超过一个目标有响应时，`gateway probe` 可能警告 `multiple reachable gateways`。 -- 如果这是有意的，请为每个 Gateway 网关隔离端口、配置/state 和工作区根目录。 + 并在仍存在陈旧的 launchd/systemd/schtasks 安装时打印清理提示。 +- 当多个目标都有响应时，`gateway probe` 可能警告 `multiple reachable gateways`。 +- 如果这是有意行为，请为每个 Gateway 网关隔离端口、配置/状态和工作区根目录。 每个实例的检查清单： @@ -190,22 +192,18 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b opencla ## VoiceClaw 实时大脑端点 OpenClaw 在 -`/voiceclaw/realtime` 公开了一个兼容 VoiceClaw 的实时 WebSocket 端点。当 VoiceClaw 桌面客户端需要 -直接与实时 OpenClaw 大脑通信，而不是经过单独的中继 +`/voiceclaw/realtime` 暴露了一个兼容 VoiceClaw 的实时 WebSocket 端点。当 VoiceClaw 桌面客户端应当直接连接到实时 OpenClaw 大脑，而不是经过单独的 relay 进程时，请使用它。 -该端点使用 Gemini Live 处理实时音频，并通过将 OpenClaw 工具直接暴露给 Gemini Live -来调用 OpenClaw 作为大脑。工具调用会立即返回 -`working` 结果，以保持语音轮次响应迅速，然后 OpenClaw -异步执行实际工具，并将结果重新注入实时会话。请在 -Gateway 网关进程环境中设置 `GEMINI_API_KEY`。如果 -Gateway 网关鉴权已启用，桌面客户端会在其第一个 `session.config` 消息中发送网关 token 或 password。 +该端点使用 Gemini Live 处理实时音频，并通过将 OpenClaw 工具直接暴露给 Gemini Live，调用 OpenClaw 作为大脑。工具调用会立即返回 +`working` 结果，以保持语音轮次响应迅速；然后 OpenClaw 会异步执行实际工具，并将结果注入回实时会话。请在 Gateway 网关进程环境中设置 `GEMINI_API_KEY`。如果 +Gateway 网关身份验证已启用，桌面客户端会在其第一个 `session.config` 消息中发送 Gateway 网关 token 或 password。 -实时大脑访问会运行经所有者授权的 OpenClaw 智能体命令。请将 -`gateway.auth.mode: "none"` 仅限于 loopback 的测试实例。非本地 -实时大脑连接需要 Gateway 网关鉴权。 +实时大脑访问会运行由所有者授权的 OpenClaw 智能体命令。请将 +`gateway.auth.mode: "none"` 限制为仅 loopback 的测试实例。非本地 +实时大脑连接需要 Gateway 网关身份验证。 -对于隔离的测试 Gateway 网关，请运行具有独立端口、配置 +对于隔离的测试 Gateway 网关，请运行一个具有独立端口、配置 和状态的单独实例： ```bash @@ -231,22 +229,22 @@ ws://127.0.0.1:19789/voiceclaw/realtime ssh -N -L 18789:127.0.0.1:18789 user@host ``` -然后让客户端在本地连接到 `ws://127.0.0.1:18789`。 +然后在本地将客户端连接到 `ws://127.0.0.1:18789`。 -SSH 隧道不会绕过 Gateway 网关鉴权。对于共享密钥鉴权，客户端即使 -通过隧道仍必须发送 `token`/`password`。对于带身份信息的模式， -请求仍必须满足对应的鉴权路径。 +SSH 隧道不会绕过 Gateway 网关身份验证。对于共享密钥身份验证，客户端即使 +通过隧道，仍然必须发送 `token`/`password`。对于携带身份的模式， +请求仍然必须满足该身份验证路径。 参见：[Remote Gateway](/zh-CN/gateway/remote)、[Authentication](/zh-CN/gateway/authentication)、[Tailscale](/zh-CN/gateway/tailscale)。 ## 监督与服务生命周期 -对于接近生产环境的可靠性，请使用受监督的运行方式。 +对于接近生产环境的可靠性，请使用受监督运行。 - + ```bash openclaw gateway install @@ -255,13 +253,13 @@ openclaw gateway restart openclaw gateway stop ``` -重启时请使用 `openclaw gateway restart`。不要连用 `openclaw gateway stop` 和 `openclaw gateway start`；在 macOS 上，`gateway stop` 会先有意禁用 LaunchAgent，然后再停止它。 +重启时请使用 `openclaw gateway restart`。不要将 `openclaw gateway stop` 和 `openclaw gateway start` 串联使用；在 macOS 上，`gateway stop` 会先有意禁用 LaunchAgent，然后再停止它。 -LaunchAgent 标签为 `ai.openclaw.gateway`（默认）或 `ai.openclaw.`（命名 profile）。`openclaw doctor` 会审计并修复服务配置漂移。 +LaunchAgent 标签是 `ai.openclaw.gateway`（默认）或 `ai.openclaw.`（命名 profile）。`openclaw doctor` 会审计并修复服务配置漂移。 - + ```bash openclaw gateway install @@ -269,13 +267,13 @@ systemctl --user enable --now openclaw-gateway[-].service openclaw gateway status ``` -如需在注销后仍持续运行，请启用 lingering： +如需在注销后继续保持运行，请启用 lingering： ```bash sudo loginctl enable-linger ``` -当你需要自定义安装路径时，可使用手动用户单元示例： +当你需要自定义安装路径时，可使用手动 user-unit 示例： ```ini [Unit] @@ -298,7 +296,7 @@ WantedBy=default.target - + ```powershell openclaw gateway install @@ -308,24 +306,25 @@ openclaw gateway stop ``` Windows 原生托管启动使用名为 `OpenClaw Gateway` -的计划任务（对于命名 profile，则为 `OpenClaw Gateway ()`）。如果计划任务创建被拒绝， -OpenClaw 会回退到每用户启动文件夹启动器，该启动器指向状态目录中的 `gateway.cmd`。 +的计划任务（对于命名 profile，则为 `OpenClaw Gateway ()`）。如果创建计划任务被拒绝，OpenClaw 会回退到每用户 Startup 文件夹启动器，该启动器指向状态目录中的 `gateway.cmd`。 - + -对于多用户/始终在线的主机，请使用系统单元。 +对多用户/始终开启的主机，请使用 system unit。 ```bash sudo systemctl daemon-reload sudo systemctl enable --now openclaw-gateway[-].service ``` -使用与用户单元相同的服务主体，但将其安装到 -`/etc/systemd/system/openclaw-gateway[-].service` 下，并在你的 `openclaw` 二进制文件位于其他位置时调整 +使用与 user unit 相同的服务主体，但将其安装到 +`/etc/systemd/system/openclaw-gateway[-].service` 下，并在你的 `openclaw` 二进制位于其他位置时调整 `ExecStart=`。 +不要同时让 `openclaw doctor --fix` 为相同的 profile/端口安装用户级 Gateway 网关服务。当 Doctor 发现系统级 OpenClaw Gateway 网关服务时，会拒绝该自动安装；当 system unit 负责生命周期时，请使用 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。 + @@ -337,34 +336,34 @@ openclaw --dev gateway --allow-unconfigured openclaw --dev status ``` -默认包含隔离的 state/config，以及基础 Gateway 网关端口 `19001`。 +默认值包括隔离的状态/配置和基础 Gateway 网关端口 `19001`。 -## 协议快速参考（操作员视角） +## 协议快速参考（操作员视图） - 第一个客户端帧必须是 `connect`。 - Gateway 网关返回 `hello-ok` 快照（`presence`、`health`、`stateVersion`、`uptimeMs`、limits/policy）。 - `hello-ok.features.methods` / `events` 是保守的发现列表，而不是 - 每个可调用辅助路由的自动生成清单。 + 每个可调用 helper route 的生成式转储。 - 请求：`req(method, params)` → `res(ok/payload|error)`。 - 常见事件包括 `connect.challenge`、`agent`、`chat`、 `session.message`、`session.tool`、`sessions.changed`、`presence`、`tick`、 - `health`、`heartbeat`、配对/审批生命周期事件以及 `shutdown`。 + `health`、`heartbeat`、pairing/approval 生命周期事件，以及 `shutdown`。 智能体运行分为两个阶段： 1. 立即接受确认（`status:"accepted"`） -2. 最终完成响应（`status:"ok"|"error"`），期间会流式发送 `agent` 事件。 +2. 最终完成响应（`status:"ok"|"error"`），其间会流式传输 `agent` 事件。 -完整协议文档参见：[Gateway Protocol](/zh-CN/gateway/protocol)。 +完整协议文档见：[Gateway Protocol](/zh-CN/gateway/protocol)。 ## 运维检查 ### 存活性 - 打开 WS 并发送 `connect`。 -- 预期收到带快照的 `hello-ok` 响应。 +- 预期收到带有快照的 `hello-ok` 响应。 -### 就绪性 +### 就绪状态 ```bash openclaw gateway status @@ -372,26 +371,26 @@ openclaw channels status --probe openclaw health ``` -### 间隙恢复 +### 缺口恢复 -事件不会重放。出现序列间隙时，请在继续前刷新状态（`health`、`system-presence`）。 +事件不会重放。出现序列缺口时，请先刷新状态（`health`、`system-presence`），再继续。 ## 常见故障特征 | 特征 | 可能问题 | | -------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `refusing to bind gateway ... without auth` | 非 loopback 绑定，但没有有效的 Gateway 网关鉴权路径 | +| `refusing to bind gateway ... without auth` | 非 loopback 绑定，但没有有效的 Gateway 网关身份验证路径 | | `another gateway instance is already listening` / `EADDRINUSE` | 端口冲突 | -| `Gateway start blocked: set gateway.mode=local` | 配置被设为远程模式，或受损配置中缺少本地模式标记 | -| `unauthorized` during connect | 客户端与 Gateway 网关之间的鉴权不匹配 | +| `Gateway start blocked: set gateway.mode=local` | 配置被设置为 remote mode，或损坏配置中缺少 local-mode 标记 | +| `unauthorized` during connect | 客户端与 Gateway 网关之间的身份验证不匹配 | -如需完整诊断步骤，请使用 [Gateway 故障排除](/zh-CN/gateway/troubleshooting)。 +如需完整的诊断步骤，请使用 [Gateway 故障排除](/zh-CN/gateway/troubleshooting)。 ## 安全保证 - 当 Gateway 网关不可用时，Gateway 网关协议客户端会快速失败（不会隐式回退到直连渠道）。 -- 无效的或非 `connect` 的首帧会被拒绝并关闭连接。 -- 优雅关闭会在 socket 关闭前发送 `shutdown` 事件。 +- 无效的首帧或非 `connect` 首帧会被拒绝并关闭连接。 +- 优雅关闭会在 socket 关闭前发出 `shutdown` 事件。 --- @@ -402,7 +401,7 @@ openclaw health - [配置](/zh-CN/gateway/configuration) - [健康状态](/zh-CN/gateway/health) - [Doctor](/zh-CN/gateway/doctor) -- [鉴权](/zh-CN/gateway/authentication) +- [身份验证](/zh-CN/gateway/authentication) ## 相关 diff --git a/docs/zh-CN/gateway/troubleshooting.md b/docs/zh-CN/gateway/troubleshooting.md index 4488f7f01..a02b39950 100644 --- a/docs/zh-CN/gateway/troubleshooting.md +++ b/docs/zh-CN/gateway/troubleshooting.md @@ -1,20 +1,20 @@ --- read_when: - - 故障排除中心将你引导到这里以进行更深入的诊断 - - 你需要按稳定症状划分、包含精确命令的操作手册章节 + - 故障排除中心将你指引到这里，以进行更深入的诊断 + - 你需要基于稳定症状的运行手册章节，并包含精确命令 sidebarTitle: Troubleshooting -summary: 适用于 Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除操作手册 +summary: Gateway 网关、渠道、自动化、节点和浏览器的深入故障排除运行手册 title: 故障排除 x-i18n: - generated_at: "2026-04-27T12:52:49Z" + generated_at: "2026-04-27T13:49:00Z" model: gpt-5.4 provider: openai - source_hash: 7ebc72b537f34dfb0dcc8b2e56014bc6a573f46835b65b9953e2edfe403bc5ca + source_hash: 3a78c619b3a80588d09162666754f9b99cfb2454884675fb7c23bb9854bd0b27 source_path: gateway/troubleshooting.md workflow: 15 --- -本页是深度操作手册。如果你想先走快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 +这是深入运行手册页面。如果你想先使用快速分流流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 ## 命令阶梯 @@ -30,15 +30,15 @@ openclaw channels status --probe 预期的健康信号： -- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok` 和一行 `Capability: ...`。 -- `openclaw doctor` 报告没有阻塞性的配置/服务问题。 -- `openclaw channels status --probe` 显示每个账号的实时传输协议状态，并在支持的情况下显示探测/审计结果，例如 `works` 或 `audit ok`。 +- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok`，以及一行 `Capability: ...`。 +- `openclaw doctor` 报告没有阻塞性的配置或服务问题。 +- `openclaw channels status --probe` 显示每个账号的实时传输状态，并在支持的情况下显示探测/审计结果，例如 `works` 或 `audit ok`。 -## 安装分裂与较新配置保护 +## 安装分裂和较新配置保护 -当 Gateway 网关服务在更新后意外停止，或日志显示某个 `openclaw` 二进制版本早于最后写入 `openclaw.json` 的版本时，请使用本节。 +当 Gateway 网关服务在更新后意外停止，或者日志显示某个 `openclaw` 二进制版本早于最近一次写入 `openclaw.json` 的版本时，请使用这一节。 -OpenClaw 会使用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍然可以检查由较新版本 OpenClaw 写入的配置，但进程和服务变更不会继续由较旧二进制执行。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制重新安装服务、服务模式下的 Gateway 网关启动，以及 `gateway --force` 端口清理。 +OpenClaw 会用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍然可以检查由较新 OpenClaw 写入的配置，但进程和服务变更会拒绝由较旧二进制继续执行。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制重装服务、以服务模式启动 Gateway 网关，以及 `gateway --force` 端口清理。 ```bash which openclaw @@ -49,10 +49,10 @@ openclaw config get meta.lastTouchedVersion - 修复 `PATH`，使 `openclaw` 解析到较新的安装，然后重新运行该操作。 + 修复 `PATH`，让 `openclaw` 解析到较新的安装，然后重新运行该操作。 - 从较新的安装重新安装目标 Gateway 网关服务： + 从较新的安装中重新安装预期的 Gateway 网关服务： ```bash openclaw gateway install --force @@ -60,18 +60,18 @@ openclaw config get meta.lastTouchedVersion ``` - - 移除仍指向旧 `openclaw` 二进制的过期系统包或旧包装器条目。 + + 移除仍然指向旧 `openclaw` 二进制的过时系统包或旧包装器条目。 -仅在有意降级或紧急恢复时，为单次命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常运行时请保持未设置。 +仅在有意降级或紧急恢复时，为单条命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常运行时不要设置它。 -## Anthropic 429：长上下文需要额外使用额度 +## Anthropic 429：长上下文需要额外用量 -当日志/错误中包含以下内容时，请使用本节：`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。 +当日志或错误中包含以下内容时，请使用这一节：`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。 ```bash openclaw logs --follow @@ -79,39 +79,39 @@ openclaw models status openclaw config get agents.defaults.models ``` -重点检查： +检查以下内容： -- 所选 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。 +- 所选 Anthropic Opus/Sonnet 模型启用了 `params.context1m: true`。 - 当前 Anthropic 凭证不具备长上下文使用资格。 -- 请求仅在需要 1M beta 路径的长会话/模型运行中失败。 +- 只有需要 1M beta 路径的长会话或模型运行请求失败。 修复选项： - 为该模型禁用 `context1m`，以回退到普通上下文窗口。 + 为该模型禁用 `context1m`，回退到普通上下文窗口。 使用具备长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API 密钥。 - 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时继续运行。 + 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时运行仍可继续。 相关内容： - [Anthropic](/zh-CN/providers/anthropic) -- [令牌使用与成本](/zh-CN/reference/token-use) +- [Token 使用量和成本](/zh-CN/reference/token-use) - [为什么我会看到来自 Anthropic 的 HTTP 429？](/zh-CN/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## 本地兼容 OpenAI 的后端可通过直接探测，但智能体运行失败 +## 本地 OpenAI 兼容后端可通过直接探测，但智能体运行失败 -当出现以下情况时，请使用本节： +当出现以下情况时，请使用这一节： - `curl ... /v1/models` 可用 - 很小的直接 `/v1/chat/completions` 调用可用 -- OpenClaw 模型运行仅在正常智能体轮次中失败 +- OpenClaw 模型运行只在正常智能体轮次中失败 ```bash curl http://127.0.0.1:1234/v1/models @@ -122,27 +122,28 @@ openclaw infer model run --model --prompt "hi" --json openclaw logs --follow ``` -重点检查： +检查以下内容： -- 直接的小请求成功，但 OpenClaw 运行仅在较大提示词下失败 -- 即使直接 `/v1/chat/completions` 使用相同的裸模型 ID 可以工作，仍出现 `model_not_found` 或 404 错误 -- 后端报错 `messages[].content` 应为字符串 -- 在兼容 OpenAI 的本地后端上，间歇性出现 `incomplete turn detected ... stopReason=stop payloads=0` 警告 -- 后端崩溃仅在较大的提示词 token 数或完整智能体运行时提示词下出现 +- 直接的小请求成功，但 OpenClaw 运行只在较大提示词时失败 +- 出现 `model_not_found` 或 404 错误，即使直接 `/v1/chat/completions` + 用同一个裸模型 id 也能工作 +- 后端报错称 `messages[].content` 应为字符串 +- 使用 OpenAI 兼容本地后端时，间歇出现 `incomplete turn detected ... stopReason=stop payloads=0` 警告 +- 后端崩溃只会在较大的提示词 token 数或完整 Agent Runtimes 提示词下出现 - - 本地 MLX/vLLM 风格服务器上的 `model_not_found` → 验证 `baseUrl` 包含 `/v1`，对于 `/v1/chat/completions` 后端，`api` 为 `"openai-completions"`，并且 `models.providers..models[].id` 是提供商本地的裸 ID。使用带提供商前缀的形式选择它一次，例如 `mlx/mlx-community/Qwen3-30B-A3B-6bit`；目录条目中仍保留为 `mlx-community/Qwen3-30B-A3B-6bit`。 + - 本地 MLX/vLLM 风格服务器出现 `model_not_found` → 确认 `baseUrl` 包含 `/v1`，对于 `/v1/chat/completions` 后端，`api` 为 `"openai-completions"`，并且 `models.providers..models[].id` 是提供商本地的裸 id。使用带提供商前缀的名称选择它一次，例如 `mlx/mlx-community/Qwen3-30B-A3B-6bit`；目录项本身保持为 `mlx-community/Qwen3-30B-A3B-6bit`。 - `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化 Chat Completions 内容片段。修复方法：设置 `models.providers..models[].compat.requiresStringContent: true`。 - - `incomplete turn detected ... stopReason=stop payloads=0` → 后端完成了 Chat Completions 请求，但该轮没有返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；持续失败通常意味着后端正在发出空/非文本内容，或抑制了最终答案文本。 - - 直接的小请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建中的 Gemma）→ OpenClaw 传输协议很可能已经正确；是后端在更大的智能体运行时提示词形态下失败。 - - 禁用工具后失败减少但未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型/服务器容量不足或后端 bug。 + - `incomplete turn detected ... stopReason=stop payloads=0` → 后端完成了 Chat Completions 请求，但这一轮没有返回用户可见的 assistant 文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；若持续失败，通常意味着后端正在输出空内容/非文本内容，或抑制最终答案文本。 + - 直接的小请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建中的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端在处理更大的 Agent Runtimes 提示词形态时的能力。 + - 禁用工具后失败有所减少但未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型/服务器容量限制或后端缺陷。 - 1. 对仅支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。 - 2. 对无法可靠处理 OpenClaw 工具 schema Surface 的模型/后端设置 `compat.supportsTools: false`。 - 3. 尽可能降低提示词压力：更小的工作区引导内容、更短的会话历史、更轻量的本地模型，或使用长上下文支持更强的后端。 - 4. 如果直接的小请求始终成功，但 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并携带已接受的载荷形态到上游提交复现。 + 1. 对仅支持字符串内容的 Chat Completions 后端，设置 `compat.requiresStringContent: true`。 + 2. 对无法可靠处理 OpenClaw 工具 schema 接口的模型/后端，设置 `compat.supportsTools: false`。 + 3. 尽可能降低提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用对长上下文支持更强的后端。 + 4. 如果直接的小请求持续通过，但 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并用已接受的负载形态在那里提交复现报告。 @@ -150,11 +151,11 @@ openclaw logs --follow - [配置](/zh-CN/gateway/configuration) - [本地模型](/zh-CN/gateway/local-models) -- [兼容 OpenAI 的端点](/zh-CN/gateway/configuration-reference#openai-compatible-endpoints) +- [OpenAI 兼容端点](/zh-CN/gateway/configuration-reference#openai-compatible-endpoints) -## 无回复 +## 没有回复 -如果渠道已启动但没有任何响应，在重新连接任何内容之前，先检查路由和策略。 +如果渠道已连接但没有任何响应，请先检查路由和策略，再重新连接任何内容。 ```bash openclaw status @@ -164,17 +165,17 @@ openclaw config get channels openclaw logs --follow ``` -重点检查： +检查以下内容： -- 私信发送方仍在等待配对。 +- 私信发送者的配对仍在等待中。 - 群组提及门控（`requireMention`、`mentionPatterns`）。 -- 渠道/群组允许列表不匹配。 +- 渠道/群组 allowlist 不匹配。 常见特征： -- `drop guild message (mention required` → 群消息在被提及之前会被忽略。 -- `pairing request` → 发送方需要批准。 -- `blocked` / `allowlist` → 发送方/渠道被策略过滤。 +- `drop guild message (mention required` → 群组消息在被提及之前会被忽略。 +- `pairing request` → 发送者需要批准。 +- `blocked` / `allowlist` → 发送者/渠道被策略过滤。 相关内容： @@ -182,9 +183,9 @@ openclaw logs --follow - [群组](/zh-CN/channels/groups) - [配对](/zh-CN/channels/pairing) -## 仪表板 Control UI 连接问题 +## Dashboard 控制 UI 连接性 -当仪表板/Control UI 无法连接时，请验证 URL、认证模式和安全上下文假设。 +当 dashboard/control UI 无法连接时，请验证 URL、认证模式和安全上下文假设。 ```bash openclaw gateway status @@ -194,41 +195,41 @@ openclaw doctor openclaw gateway status --json ``` -重点检查： +检查以下内容： -- 正确的探测 URL 和仪表板 URL。 +- 正确的探测 URL 和 dashboard URL。 - 客户端与 Gateway 网关之间的认证模式/令牌不匹配。 -- 在需要设备身份时却使用了 HTTP。 +- 在需要设备身份的场景中使用了 HTTP。 - - `device identity required` → 非安全上下文，或缺少设备认证。 - - `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 浏览器来源连接，但未显式加入允许列表）。 - - `device nonce required` / `device nonce mismatch` → 客户端未完成基于质询的设备认证流程（`connect.challenge` + `device.nonce`）。 - - `device signature invalid` / `device signature expired` → 客户端为当前握手签名了错误的载荷（或使用了过期时间戳）。 - - `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可使用缓存的设备令牌执行一次可信重试。 - - 该缓存令牌重试会复用与已配对设备令牌一同存储的缓存范围集。显式 `deviceToken` / 显式 `scopes` 调用方则保持其请求的范围集不变。 + - `device identity required` → 非安全上下文或缺少设备认证。 + - `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正在从非 loopback 浏览器来源连接，而未显式加入 allowlist）。 + - `device nonce required` / `device nonce mismatch` → 客户端没有完成基于质询的设备认证流程（`connect.challenge` + `device.nonce`）。 + - `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的负载（或使用了过期时间戳）。 + - `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备令牌进行一次可信重试。 + - 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的作用域集合。 - 在该重试路径之外，连接认证优先级依次为：显式共享令牌/密码、显式 `deviceToken`、已存储设备令牌、bootstrap 令牌。 - - 在异步 Tailscale Serve Control UI 路径上，相同 `{scope, ip}` 的失败尝试会在限流器记录失败前被串行化。因此，同一客户端同时进行两次错误重试时，第二次尝试可能返回 `retry later`，而不是出现两次普通不匹配。 - - 来自浏览器来源 loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自相同规范化 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源会使用单独的桶。 - - 在该重试之后反复出现 `unauthorized` → 共享令牌/设备令牌已漂移；请刷新令牌配置，并在需要时重新批准/轮换设备令牌。 - - `gateway connect failed:` → 宿主机/端口/URL 目标错误。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前先被串行化。因此，同一客户端的两个错误并发重试中，第二次可能返回 `retry later`，而不是两个普通的不匹配错误。 + - 浏览器来源的 loopback 客户端出现 `too many failed authentication attempts (retry later)` → 来自同一归一化 `Origin` 的重复失败会被暂时锁定；另一个 localhost 来源会使用单独的桶。 + - 在该重试之后仍反复出现 `unauthorized` → 共享令牌/设备令牌发生漂移；如有需要，刷新令牌配置并重新批准/轮换设备令牌。 + - `gateway connect failed:` → 主机/端口/URL 目标错误。 -### 认证详情代码速查表 +### 认证详细代码速查表 -使用失败 `connect` 响应中的 `error.details.code` 选择下一步操作： +使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作： -| 详情代码 | 含义 | 建议操作 | +| 详细代码 | 含义 | 推荐操作 | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享令牌。 | 在客户端中粘贴/设置令牌后重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 | -| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存令牌重试会复用已存储的已批准范围；显式 `deviceToken` / `scopes` 调用方则保持其请求的范围不变。如果仍然失败，请运行 [令牌漂移恢复清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 | -| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备令牌已过期或已撤销。 | 使用 [devices CLI](/zh-CN/cli/devices) 轮换/重新批准设备令牌，然后重新连接。 | -| `PAIRING_REQUIRED` | 设备身份需要批准。请检查 `error.details.reason`，其值可能为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve `。范围/角色升级在你审核所请求的访问权限后也使用相同流程。 | +| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享令牌。 | 在客户端中粘贴/设置令牌后重试。对于 dashboard 路径：运行 `openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 | +| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许进行一次可信重试。缓存令牌重试会复用已存储的批准作用域；显式 `deviceToken` / `scopes` 调用方则保留所请求的作用域。如果仍然失败，请运行[令牌漂移恢复清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 | +| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备令牌已过期或被撤销。 | 使用 [devices CLI](/zh-CN/cli/devices) 轮换/重新批准设备令牌，然后重新连接。 | +| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason`，其值可能为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后运行 `openclaw devices approve `。在你审查所请求访问后，作用域/角色升级使用相同流程。 | -使用共享 Gateway 网关令牌/密码认证的直接 loopback 后端 RPC 不应依赖 CLI 的已配对设备范围基线。如果子智能体或其他内部调用仍因 `scope-upgrade` 失败，请验证调用方是否使用 `client.id: "gateway-client"` 和 `client.mode: "backend"`，并且没有强制显式 `deviceIdentity` 或设备令牌。 +使用共享 Gateway 网关令牌/密码进行身份验证的直接 loopback 后端 RPC，不应依赖 CLI 的已配对设备作用域基线。如果子智能体或其他内部调用仍因 `scope-upgrade` 失败，请验证调用方正在使用 `client.id: "gateway-client"` 和 `client.mode: "backend"`，且没有强制指定显式 `deviceIdentity` 或设备令牌。 设备认证 v2 迁移检查： @@ -239,36 +240,36 @@ openclaw doctor openclaw gateway status ``` -如果日志显示 nonce/签名错误，请更新连接的客户端并验证： +如果日志显示 nonce/签名错误，请更新发起连接的客户端并验证以下内容： 客户端等待 Gateway 网关发出的 `connect.challenge`。 - - 客户端对绑定 challenge 的载荷进行签名。 + + 客户端对绑定 challenge 的负载进行签名。 - 客户端发送 `connect.params.device.nonce`，并使用相同的 challenge nonce。 + 客户端使用相同的 challenge nonce 发送 `connect.params.device.nonce`。 -如果 `openclaw devices rotate` / `revoke` / `remove` 意外被拒绝： +如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝： -- 已配对设备令牌会话只能管理**它们自己的**设备，除非调用方同时拥有 `operator.admin` -- `openclaw devices rotate --scope ...` 只能请求调用方会话当前已持有的运维人员范围 +- 已配对设备令牌会话只能管理**它们自己的**设备，除非调用方还具有 `operator.admin` +- `openclaw devices rotate --scope ...` 只能请求调用方会话已经持有的 operator 作用域 相关内容： - [配置](/zh-CN/gateway/configuration)（Gateway 网关认证模式） - [Control UI](/zh-CN/web/control-ui) -- [Devices](/zh-CN/cli/devices) +- [设备](/zh-CN/cli/devices) - [远程访问](/zh-CN/gateway/remote) -- [可信代理认证](/zh-CN/gateway/trusted-proxy-auth) +- [Trusted proxy auth](/zh-CN/gateway/trusted-proxy-auth) ## Gateway 网关服务未运行 -当服务已安装但进程无法持续运行时，请使用本节。 +当服务已安装但进程无法保持运行时，请使用这一节。 ```bash openclaw gateway status @@ -278,9 +279,9 @@ openclaw doctor openclaw gateway status --deep # 也扫描系统级服务 ``` -重点检查： +检查以下内容： -- 带退出提示的 `Runtime: stopped`。 +- `Runtime: stopped` 及其退出提示。 - 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。 - 端口/监听器冲突。 - 使用 `--deep` 时发现的额外 launchd/systemd/schtasks 安装。 @@ -288,22 +289,24 @@ openclaw gateway status --deep # 也扫描系统级服务 - - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被破坏并丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。 - - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下绑定到非 loopback 地址（令牌/密码，或在已配置时使用 trusted-proxy）。 + - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或配置文件被覆盖并丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径为 `~/.openclaw/openclaw.json`。 + - `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 Gateway 网关认证路径（令牌/密码，或在已配置时使用 trusted-proxy）。 - `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。 - - `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数环境应保持每台机器一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置/状态/工作区。请参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。 + - `Other gateway-like services detected (best effort)` → 存在过时或并行的 launchd/systemd/schtasks 单元。大多数配置每台机器只应保留一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。 + - Doctor 中出现 `System-level OpenClaw gateway service detected` → 存在 systemd 系统单元，而用户级服务缺失。在允许 Doctor 安装用户服务之前，请先移除或禁用重复项；如果系统单元就是预期的管理器，则设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。 + - `Gateway service port does not match current gateway config` → 已安装的管理器仍固定旧的 `--port`。运行 `openclaw doctor --fix` 或 `openclaw gateway install --force`，然后重启 Gateway 网关服务。 相关内容： -- [后台执行与进程工具](/zh-CN/gateway/background-process) +- [后台执行和进程工具](/zh-CN/gateway/background-process) - [配置](/zh-CN/gateway/configuration) - [Doctor](/zh-CN/gateway/doctor) -## Gateway 网关恢复了最后已知良好配置 +## Gateway 网关恢复了最后已知正常配置 -当 Gateway 网关能够启动，但日志显示它恢复了 `openclaw.json` 时，请使用本节。 +当 Gateway 网关启动了，但日志显示它恢复了 `openclaw.json` 时，请使用这一节。 ```bash openclaw logs --follow @@ -312,23 +315,23 @@ openclaw config validate openclaw doctor ``` -重点检查： +检查以下内容： - `Config auto-restored from last-known-good` - `gateway: invalid config was restored from last-known-good backup` - `config reload restored last-known-good config after invalid-config` -- 活动配置旁边带时间戳的 `openclaw.json.clobbered.*` 文件 -- 主智能体系统事件，且其开头为 `Config recovery warning` +- 活动配置旁边存在带时间戳的 `openclaw.json.clobbered.*` 文件 +- 主智能体系统事件以 `Config recovery warning` 开头 - 被拒绝的配置在启动或热重载期间未通过验证。 - - OpenClaw 将被拒绝的载荷保留为 `.clobbered.*`。 - - 活动配置已从最后一次通过验证的最后已知良好副本恢复。 + - OpenClaw 将被拒绝的负载保留为 `.clobbered.*`。 + - 活动配置已从最后一次通过验证的最后已知正常副本中恢复。 - 下一次主智能体轮次会收到警告，不要盲目重写被拒绝的配置。 - - 如果所有验证问题都位于 `plugins.entries....` 下，OpenClaw 不会恢复整个文件。插件本地失败会保持显式报错，而无关的用户设置仍保留在活动配置中。 + - 如果所有验证问题都在 `plugins.entries....` 下，OpenClaw 不会恢复整个文件。插件局部失败会保持显式报错，而无关的用户设置仍保留在活动配置中。 - + ```bash CONFIG="$(openclaw config file)" ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head @@ -338,17 +341,17 @@ openclaw doctor ``` - - 存在 `.clobbered.*` → 外部直接编辑或启动读取已被恢复。 - - 存在 `.rejected.*` → OpenClaw 自有的配置写入在提交前未通过 schema 或覆盖检查。 - - `Config write rejected:` → 该写入尝试删除必需结构、大幅缩小文件，或持久化无效配置。 - - `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为已损坏，因为与最后已知良好备份相比，它丢失了字段或文件大小明显下降。 - - `Config last-known-good promotion skipped` → 候选配置包含了被脱敏的密钥占位符，例如 `***`。 + - 存在 `.clobbered.*` → 外部直接编辑或启动读取内容已被恢复。 + - 存在 `.rejected.*` → OpenClaw 自身的配置写入在提交前因 schema 或覆盖检查失败。 + - `Config write rejected:` → 该写入试图删除必需结构、明显缩小文件，或持久化无效配置。 + - `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为被覆盖，因为与最后已知正常备份相比它丢失了字段或体积变小。 + - `Config last-known-good promotion skipped` → 候选配置中包含 `***` 之类已脱敏的密钥占位符。 1. 如果恢复后的活动配置正确，就保留它。 - 2. 只从 `.clobbered.*` 或 `.rejected.*` 中复制你想要的键，然后使用 `openclaw config set` 或 `config.patch` 应用。 + 2. 仅从 `.clobbered.*` 或 `.rejected.*` 中复制你打算保留的键，然后使用 `openclaw config set` 或 `config.patch` 应用。 3. 重启前运行 `openclaw config validate`。 - 4. 如果手动编辑，请保留完整的 JSON5 配置，而不是只保留你想修改的局部对象。 + 4. 如果你手动编辑，请保留完整的 JSON5 配置，而不只是你想改动的那个局部对象。 @@ -361,7 +364,7 @@ openclaw doctor ## Gateway 网关探测警告 -当 `openclaw gateway probe` 能探测到某些目标，但仍打印警告块时，请使用本节。 +当 `openclaw gateway probe` 能探测到目标，但仍然打印警告块时，请使用这一节。 ```bash openclaw gateway probe @@ -369,28 +372,28 @@ openclaw gateway probe --json openclaw gateway probe --ssh user@gateway-host ``` -重点检查： +检查以下内容： - JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。 -- 警告是否与 SSH 回退、多个 Gateway 网关、缺少范围或未解析的认证引用有关。 +- 警告是否与 SSH 回退、多个 Gateway 网关、缺少作用域或无法解析的认证引用有关。 常见特征： -- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了直接配置/loopback 目标。 -- `multiple reachable gateways detected` → 有多个目标响应。通常这意味着有意的多 Gateway 网关部署，或存在过期/重复监听器。 -- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受范围限制；请配对设备身份，或使用带有 `operator.read` 的凭证。 -- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关有响应，但此客户端仍需完成配对/批准后才能获得正常运维访问。 +- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了直接配置目标/loopback 目标。 +- `multiple reachable gateways detected` → 超过一个目标有响应。通常这意味着有意配置了多个 Gateway 网关，或存在过时/重复监听器。 +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份或使用具有 `operator.read` 的凭证。 +- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关有响应，但该客户端在获得正常 operator 访问前仍需要配对/批准。 - 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在此命令路径中，失败目标所需的认证材料不可用。 相关内容： - [Gateway 网关](/zh-CN/cli/gateway) -- [同一宿主机上的多个 Gateway 网关](/zh-CN/gateway#multiple-gateways-same-host) +- [同一主机上的多个 Gateway 网关](/zh-CN/gateway#multiple-gateways-same-host) - [远程访问](/zh-CN/gateway/remote) ## 渠道已连接，但消息不流动 -如果渠道状态显示已连接，但消息流完全中断，请重点检查策略、权限和渠道特定的投递规则。 +如果渠道状态显示已连接，但消息流已停止，请重点检查策略、权限和渠道特定的投递规则。 ```bash openclaw channels status --probe @@ -400,16 +403,16 @@ openclaw logs --follow openclaw config get channels ``` -重点检查： +检查以下内容： - 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。 -- 群组允许列表与提及要求。 -- 缺失的渠道 API 权限/范围。 +- 群组 allowlist 和提及要求。 +- 缺失的渠道 API 权限/作用域。 常见特征： - `mention required` → 消息因群组提及策略而被忽略。 -- `pairing` / 待批准跟踪 → 发送方尚未获得批准。 +- `pairing` / 待批准跟踪 → 发送者尚未获批。 - `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → 渠道认证/权限问题。 相关内容： @@ -419,9 +422,9 @@ openclaw config get channels - [Telegram](/zh-CN/channels/telegram) - [WhatsApp](/zh-CN/channels/whatsapp) -## Cron 与 heartbeat 投递 +## Cron 和心跳投递 -如果 cron 或 heartbeat 未运行或未投递，请先验证调度器状态，再检查投递目标。 +如果 cron 或心跳未运行或未投递，请先验证调度器状态，再检查投递目标。 ```bash openclaw cron status @@ -431,33 +434,33 @@ openclaw system heartbeat last openclaw logs --follow ``` -重点检查： +检查以下内容： -- Cron 已启用，且存在下一次唤醒时间。 +- cron 已启用，且存在下一次唤醒时间。 - 作业运行历史状态（`ok`、`skipped`、`error`）。 -- Heartbeat 跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 +- 心跳跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。 - `cron: timer tick failed` → 调度器 tick 失败；请检查文件/日志/运行时错误。 - - `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于非活跃时段窗口之外。 + - `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于活跃时段窗口之外。 - `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / Markdown 标题，因此 OpenClaw 会跳过模型调用。 - - `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但本次 tick 没有任何任务到期。 - - `heartbeat: unknown accountId` → heartbeat 投递目标的账号 ID 无效。 - - `heartbeat skipped` 且 `reason=dm-blocked` → heartbeat 目标被解析为私信式目标，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖值）设置为 `block`。 + - `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但在这次 tick 中没有任务到期。 + - `heartbeat: unknown accountId` → 心跳投递目标的账号 id 无效。 + - `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标被解析为私信风格目的地，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖配置）被设置为 `block`。 相关内容： - [Heartbeat](/zh-CN/gateway/heartbeat) -- [定时任务](/zh-CN/automation/cron-jobs) -- [定时任务：故障排除](/zh-CN/automation/cron-jobs#troubleshooting) +- [计划任务](/zh-CN/automation/cron-jobs) +- [计划任务：故障排除](/zh-CN/automation/cron-jobs#troubleshooting) ## 节点已配对，但工具失败 -如果节点已配对，但工具失败，请分别检查前台状态、权限和批准状态。 +如果节点已配对但工具失败，请分别检查前台状态、权限和批准状态。 ```bash openclaw nodes status @@ -467,28 +470,28 @@ openclaw logs --follow openclaw status ``` -重点检查： +检查以下内容： - 节点在线，并具有预期能力。 -- 摄像头/麦克风/位置/屏幕的 OS 权限授予情况。 -- Exec 批准和允许列表状态。 +- 相机/麦克风/位置/屏幕的操作系统权限已授予。 +- exec 批准和 allowlist 状态。 常见特征： - `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须位于前台。 -- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少 OS 权限。 +- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。 - `SYSTEM_RUN_DENIED: approval required` → exec 批准待处理。 -- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表拦截。 +- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 拦截。 相关内容： - [Exec 批准](/zh-CN/tools/exec-approvals) - [节点故障排除](/zh-CN/nodes/troubleshooting) -- [Nodes](/zh-CN/nodes/index) +- [节点](/zh-CN/nodes/index) ## 浏览器工具失败 -当浏览器工具操作失败，但 Gateway 网关本身是健康的，请使用本节。 +当浏览器工具操作失败，但 Gateway 网关本身运行正常时，请使用这一节。 ```bash openclaw browser status @@ -498,39 +501,39 @@ openclaw logs --follow openclaw doctor ``` -重点检查： +检查以下内容： - 是否设置了 `plugins.allow`，且其中包含 `browser`。 - 浏览器可执行文件路径是否有效。 -- CDP 配置文件是否可达。 -- 对于 `existing-session` / `user` 配置文件，本地 Chrome 是否可用。 +- CDP 配置文件是否可访问。 +- `existing-session` / `user` 配置文件所需的本地 Chrome 是否可用。 - `unknown command "browser"` 或 `unknown command 'browser'` → 内置浏览器插件被 `plugins.allow` 排除。 - - 在 `browser.enabled=true` 时浏览器工具缺失 / 不可用 → `plugins.allow` 排除了 `browser`，因此插件从未加载。 + - 浏览器工具缺失 / 不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此插件从未加载。 - `Failed to start Chrome CDP on port` → 浏览器进程启动失败。 - `browser.executablePath not found` → 配置的路径无效。 - - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不支持的协议，例如 `file:` 或 `ftp:`。 - - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口无效或超出范围。 - - `Playwright is not available in this gateway build; '' is unsupported.` → 当前 Gateway 网关安装缺少内置浏览器插件所需的 `playwright-core` 运行时依赖；请运行 `openclaw doctor --fix`，然后重启 Gateway 网关。ARIA 快照和基本页面截图仍可工作，但导航、AI 快照、基于 CSS 选择器的元素截图和 PDF 导出仍不可用。 + - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议，例如 `file:` 或 `ftp:`。 + - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。 + - `Playwright is not available in this gateway build; '' is unsupported.` → 当前 Gateway 网关安装缺少内置浏览器插件所需的 `playwright-core` 运行时依赖；请运行 `openclaw doctor --fix`，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍然可用，但导航、AI 快照、基于 CSS 选择器的元素截图以及 PDF 导出仍不可用。 - - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 还无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器打开，批准第一次附加提示，然后重试。如果不需要登录态，优先使用受管的 `openclaw` 配置文件。 + - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 尚无法附加到所选浏览器数据目录。请打开浏览器检查页面，启用远程调试，保持浏览器打开，批准第一次附加提示，然后重试。如果不需要已登录状态，优先使用受管的 `openclaw` 配置文件。 - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。 - - `Remote CDP for profile "" is not reachable` → 配置的远程 CDP 端点从 Gateway 网关宿主机不可达。 - - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可达目标，或 HTTP 端点已响应，但 CDP WebSocket 仍无法打开。 + - `Remote CDP for profile "" is not reachable` → 从 Gateway 网关主机无法访问配置的远程 CDP 端点。 + - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可访问目标，或者 HTTP 端点虽有响应，但 CDP WebSocket 仍无法打开。 - `fullPage is not supported for element screenshots` → 截图请求将 `--full-page` 与 `--ref` 或 `--element` 混用。 - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 截图调用必须使用页面捕获或快照 `--ref`，不能使用 CSS `--element`。 - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要使用快照引用，而不是 CSS 选择器。 - - `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件上每次调用只能发送一个上传文件。 - - `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件上的对话框钩子不支持超时覆盖。 - - `existing-session type does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:type` 不要传 `timeoutMs`，或者在需要自定义超时时使用受管/CDP 浏览器配置文件。 - - `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:evaluate` 不要传 `timeoutMs`，或者在需要自定义超时时使用受管/CDP 浏览器配置文件。 - - `response body is not supported for existing-session profiles yet.` → `responsebody` 仍然需要受管浏览器或原始 CDP 配置文件。 - - attach-only 或远程 CDP 配置文件上的视口 / 深色模式 / 语言区域 / 离线覆盖值过期残留 → 运行 `openclaw browser stop --browser-profile ` 以关闭当前活动控制会话，并释放 Playwright/CDP 仿真状态，而无需重启整个 Gateway 网关。 + - `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件中，每次调用只能上传一个文件。 + - `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件中的对话框钩子不支持超时覆盖。 + - `existing-session type does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:type`，请省略 `timeoutMs`，或者在需要自定义超时时使用受管/CDP 浏览器配置文件。 + - `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:evaluate`，请省略 `timeoutMs`，或者在需要自定义超时时使用受管/CDP 浏览器配置文件。 + - `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍需要受管浏览器或原始 CDP 配置文件。 + - attach-only 或远程 CDP 配置文件上的视口 / 深色模式 / 区域设置 / 离线覆盖状态陈旧 → 运行 `openclaw browser stop --browser-profile `，关闭当前活动控制会话并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。 @@ -539,12 +542,12 @@ openclaw doctor - [浏览器（OpenClaw 托管）](/zh-CN/tools/browser) - [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting) -## 如果你升级后突然出了问题 +## 如果你升级后突然出问题了 -大多数升级后的故障都来自配置漂移，或者更严格的默认值现在开始生效。 +大多数升级后的故障都来自配置漂移，或现在开始强制执行更严格的默认值。 - + ```bash openclaw gateway status openclaw config get gateway.mode @@ -552,10 +555,10 @@ openclaw doctor openclaw config get gateway.auth.mode ``` - 检查内容： + 要检查的内容： - - 如果 `gateway.mode=remote`，CLI 调用可能在访问远程端，而你的本地服务实际上是正常的。 - - 显式 `--url` 调用不会回退到已存储凭证。 + - 如果 `gateway.mode=remote`，CLI 调用可能正在指向远程端，而你的本地服务其实是正常的。 + - 显式 `--url` 调用不会回退到已存储的凭证。 常见特征： @@ -563,7 +566,7 @@ openclaw doctor - `unauthorized` → 端点可达，但认证错误。 - + ```bash openclaw config get gateway.bind openclaw config get gateway.auth.mode @@ -572,18 +575,18 @@ openclaw doctor openclaw logs --follow ``` - 检查内容： + 要检查的内容： - 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享令牌/密码认证，或正确配置的非 loopback `trusted-proxy` 部署。 - - 像 `gateway.token` 这样的旧键不会替代 `gateway.auth.token`。 + - 旧键名（如 `gateway.token`）不能替代 `gateway.auth.token`。 常见特征： - `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径。 - - `Connectivity probe: failed` 且运行时正在运行 → Gateway 网关仍存活，但以当前认证/URL 无法访问。 + - `Connectivity probe: failed`，但运行时正在运行 → Gateway 网关存活，但当前认证/URL 无法访问。 - + ```bash openclaw devices list openclaw pairing list --channel [--account ] @@ -591,20 +594,20 @@ openclaw doctor openclaw doctor ``` - 检查内容： + 要检查的内容： - - 仪表板/节点的待批准设备。 - - 策略或身份变更后的待批准私信配对。 + - dashboard/节点是否有待批准的设备请求。 + - 在策略或身份变更之后，私信是否有待批准的配对请求。 常见特征： - - `device identity required` → 设备认证未满足。 - - `pairing required` → 发送方/设备必须先获得批准。 + - `device identity required` → 未满足设备认证要求。 + - `pairing required` → 发送者/设备必须先获批。 -如果经过检查后，服务配置与运行时仍然不一致，请从同一配置文件/状态目录重新安装服务元数据： +如果在完成检查后，服务配置与运行时仍然不一致，请从同一个配置文件/状态目录重新安装服务元数据： ```bash openclaw gateway install --force @@ -614,11 +617,11 @@ openclaw gateway restart 相关内容： - [认证](/zh-CN/gateway/authentication) -- [后台执行与进程工具](/zh-CN/gateway/background-process) +- [后台执行和进程工具](/zh-CN/gateway/background-process) - [Gateway 网关托管配对](/zh-CN/gateway/pairing) ## 相关内容 - [Doctor](/zh-CN/gateway/doctor) - [常见问题](/zh-CN/help/faq) -- [Gateway 网关操作手册](/zh-CN/gateway) +- [Gateway 网关运行手册](/zh-CN/gateway) diff --git a/docs/zh-CN/reference/memory-config.md b/docs/zh-CN/reference/memory-config.md index e1a7b6b7f..2b4cd9c7d 100644 --- a/docs/zh-CN/reference/memory-config.md +++ b/docs/zh-CN/reference/memory-config.md @@ -8,19 +8,19 @@ sidebarTitle: Memory config summary: Memory 搜索、嵌入提供商、QMD、混合搜索和多模态索引的所有配置项 title: Memory 配置参考 x-i18n: - generated_at: "2026-04-27T13:31:48Z" + generated_at: "2026-04-27T13:49:01Z" model: gpt-5.4 provider: openai - source_hash: fe0810e389ad4e8eb4671ea64eb2211887700684b4b781992fe184dc12a958d2 + source_hash: f22a728c26a4d7aba155c108b7aad719418fd2dedfa370f339907dc3325e24af source_path: reference/memory-config.md workflow: 15 --- -此页面列出了 OpenClaw Memory 搜索的每一个配置项。有关概念性概览，请参阅： +此页面列出了 OpenClaw Memory 搜索的每一个配置项。有关概念概览，请参阅： - Memory 的工作原理。 + Memory 的工作方式。 默认的 SQLite 后端。 @@ -29,7 +29,7 @@ x-i18n: 本地优先的 sidecar。 - 搜索流水线与调优。 + 搜索流水线和调优。 用于交互式会话的 Memory 子智能体。 @@ -39,89 +39,89 @@ x-i18n: 除非另有说明，所有 Memory 搜索设置都位于 `openclaw.json` 中的 `agents.defaults.memorySearch` 下。 -如果你要查找 **active memory** 功能开关和子智能体配置，它位于 `plugins.entries.active-memory` 下，而不是 `memorySearch`。 +如果你要查找 **active memory** 的功能开关和子智能体配置，这些内容位于 `plugins.entries.active-memory` 下，而不是 `memorySearch` 下。 Active memory 使用双门控模型： -1. 必须启用该插件，并且目标是当前智能体 id -2. 该请求必须是符合条件的交互式持久聊天会话 +1. 必须启用该插件，并将其目标设为当前智能体 id +2. 该请求必须是符合条件的交互式持久化聊天会话 -有关激活模型、插件自有配置、转录持久化和安全上线模式，请参阅 [Active Memory](/zh-CN/concepts/active-memory)。 +有关激活模型、插件自有配置、转录持久化和安全发布模式，请参阅 [Active Memory](/zh-CN/concepts/active-memory)。 --- ## 提供商选择 -| 键 | 类型 | 默认值 | 说明 | -| ---------- | --------- | -------------- | ------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | 自动检测 | 嵌入适配器 ID：`bedrock`、`gemini`、`github-copilot`、`local`、`mistral`、`ollama`、`openai`、`voyage` | -| `model` | `string` | 提供商默认值 | 嵌入模型名称 | -| `fallback` | `string` | `"none"` | 当主提供商失败时使用的回退适配器 ID | -| `enabled` | `boolean` | `true` | 启用或禁用 Memory 搜索 | +| 键名 | 类型 | 默认值 | 说明 | +| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | 自动检测 | 嵌入适配器 ID：`bedrock`、`gemini`、`github-copilot`、`local`、`mistral`、`ollama`、`openai`、`voyage` | +| `model` | `string` | 提供商默认值 | 嵌入模型名称 | +| `fallback` | `string` | `"none"` | 当主适配器失败时使用的回退适配器 ID | +| `enabled` | `boolean` | `true` | 启用或禁用 Memory 搜索 | ### 自动检测顺序 -当未设置 `provider` 时，OpenClaw 会选择第一个可用项： +当未设置 `provider` 时，OpenClaw 会选择第一个可用的提供商： - 如果已配置 `memorySearch.local.modelPath` 且该文件存在，则选中。 + 如果已配置 `memorySearch.local.modelPath` 且文件存在，则选择该提供商。 - 如果可以解析到 GitHub Copilot token（环境变量或 auth profile），则选中。 + 如果可以解析到 GitHub Copilot token（环境变量或认证配置文件），则选择该提供商。 - 如果可以解析到 OpenAI 密钥，则选中。 + 如果可以解析到 OpenAI key，则选择该提供商。 - 如果可以解析到 Gemini 密钥，则选中。 + 如果可以解析到 Gemini key，则选择该提供商。 - 如果可以解析到 Voyage 密钥，则选中。 + 如果可以解析到 Voyage key，则选择该提供商。 - 如果可以解析到 Mistral 密钥，则选中。 + 如果可以解析到 Mistral key，则选择该提供商。 - 如果 AWS SDK 凭证链可以解析成功（实例角色、访问密钥、profile、SSO、web identity 或共享配置），则选中。 + 如果 AWS SDK 凭证链可以成功解析（实例角色、访问密钥、profile、SSO、web identity 或共享配置），则选择该提供商。 -支持 `ollama`，但不会自动检测到它（请显式设置）。 +支持 `ollama`，但不会自动检测（需要显式设置）。 -### API 密钥解析 +### API key 解析 -远程嵌入需要 API 密钥。Bedrock 则改为使用 AWS SDK 默认凭证链（实例角色、SSO、访问密钥）。 +远程嵌入需要 API key。Bedrock 则使用 AWS SDK 默认凭证链（实例角色、SSO、访问密钥）。 -| 提供商 | 环境变量 | 配置键 | -| --------------- | -------------------------------------------------- | --------------------------------- | -| Bedrock | AWS 凭证链 | 不需要 API 密钥 | -| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | -| GitHub Copilot | `COPILOT_GITHUB_TOKEN`、`GH_TOKEN`、`GITHUB_TOKEN` | 通过设备登录的 auth profile | -| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | -| Ollama | `OLLAMA_API_KEY`（占位符） | -- | -| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | -| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | +| 提供商 | 环境变量 | 配置键 | +| -------------- | -------------------------------------------------- | -------------------------------- | +| Bedrock | AWS 凭证链 | 不需要 API key | +| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | +| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | 通过设备登录的认证配置文件 | +| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | +| Ollama | `OLLAMA_API_KEY`（占位符） | -- | +| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | +| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | -Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 +Codex OAuth 仅覆盖 chat/completions，不满足 embedding 请求的要求。 --- ## 远程端点配置 -用于自定义兼容 OpenAI 的端点或覆盖提供商默认值： +用于自定义 OpenAI 兼容端点或覆盖提供商默认值： - 自定义 API 基础 URL。 + 自定义 API base URL。 - 覆盖 API 密钥。 + 覆盖 API key。 - 额外的 HTTP 标头（与提供商默认值合并）。 + 额外的 HTTP headers（会与提供商默认值合并）。 ```json5 @@ -143,28 +143,28 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 --- -## 提供商专用配置 +## 提供商专属配置 - | 键 | 类型 | 默认值 | 说明 | + | 键名 | 类型 | 默认值 | 说明 | | ---------------------- | -------- | ---------------------- | ------------------------------------------ | | `model` | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2-preview` | - | `outputDimensionality` | `number` | `3072` | 对于 Embedding 2：768、1536 或 3072 | + | `outputDimensionality` | `number` | `3072` | 对于 Embedding 2：可为 768、1536 或 3072 | - 更改模型或 `outputDimensionality` 会触发自动的完整重新索引。 + 更改模型或 `outputDimensionality` 会触发自动全量重建索引。 - - 兼容 OpenAI 的嵌入端点可以选择启用提供商专用的 `input_type` 请求字段。这对于需要为查询嵌入和文档嵌入使用不同标签的非对称嵌入模型很有用。 + + OpenAI 兼容嵌入端点可以选择启用提供商专属的 `input_type` 请求字段。这对于需要为查询嵌入和文档嵌入使用不同标签的非对称嵌入模型很有用。 - | 键 | 类型 | 默认值 | 说明 | - | ------------------- | -------- | ------ | --------------------------------------------------- | - | `inputType` | `string` | 未设置 | 查询嵌入和文档嵌入共享的 `input_type` | - | `queryInputType` | `string` | 未设置 | 查询时的 `input_type`；覆盖 `inputType` | - | `documentInputType` | `string` | 未设置 | 索引/文档的 `input_type`；覆盖 `inputType` | + | 键名 | 类型 | 默认值 | 说明 | + | ------------------- | -------- | ------ | ------------------------------------------------- | + | `inputType` | `string` | 未设置 | 查询嵌入和文档嵌入共用的 `input_type` | + | `queryInputType` | `string` | 未设置 | 查询时的 `input_type`；会覆盖 `inputType` | + | `documentInputType` | `string` | 未设置 | 索引/文档的 `input_type`；会覆盖 `inputType` | ```json5 { @@ -185,11 +185,11 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 } ``` - 更改这些值会影响提供商批量索引的嵌入缓存标识；当上游模型对这些标签有不同处理时，应随后执行一次 Memory 重新索引。 + 更改这些值会影响提供商批量索引的嵌入缓存标识；如果上游模型会区别对待这些标签，则更改后应执行一次 Memory 重建索引。 - Bedrock 使用 AWS SDK 默认凭证链——不需要 API 密钥。如果 OpenClaw 运行在带有 Bedrock 权限实例角色的 EC2 上，只需设置提供商和模型： + Bedrock 使用 AWS SDK 默认凭证链——不需要 API key。如果 OpenClaw 运行在启用了 Bedrock 实例角色的 EC2 上，只需设置提供商和模型： ```json5 { @@ -204,29 +204,29 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 } ``` - | 键 | 类型 | 默认值 | 说明 | + | 键名 | 类型 | 默认值 | 说明 | | ---------------------- | -------- | ------------------------------ | ---------------------------- | | `model` | `string` | `amazon.titan-embed-text-v2:0` | 任意 Bedrock 嵌入模型 ID | | `outputDimensionality` | `number` | 模型默认值 | 对于 Titan V2：256、512 或 1024 | - **支持的模型**（含系列检测和维度默认值）： + **支持的模型**（包含家族检测和默认维度）： - | 模型 ID | 提供商 | 默认维度 | 可配置维度 | - | ------------------------------------------ | ----------- | -------- | -------------------- | - | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256、512、1024 | - | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | - | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | - | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | - | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256、384、1024、3072 | - | `cohere.embed-english-v3` | Cohere | 1024 | -- | - | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | - | `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | - | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | - | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | + | 模型 ID | 提供商 | 默认维度 | 可配置维度 | + | ------------------------------------------- | ---------- | -------- | -------------------- | + | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256、512、1024 | + | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | + | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | + | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | + | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256、384、1024、3072 | + | `cohere.embed-english-v3` | Cohere | 1024 | -- | + | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | + | `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | + | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | + | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | 带吞吐量后缀的变体（例如 `amazon.titan-embed-text-v1:2:8k`）会继承基础模型的配置。 - **认证：**Bedrock 认证使用标准 AWS SDK 凭证解析顺序： + **认证：** Bedrock 认证使用标准 AWS SDK 凭证解析顺序： 1. 环境变量（`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`） 2. SSO token 缓存 @@ -234,9 +234,9 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 4. 共享凭证和配置文件 5. ECS 或 EC2 元数据凭证 - 区域从 `AWS_REGION`、`AWS_DEFAULT_REGION`、`amazon-bedrock` 提供商的 `baseUrl` 中解析，或默认使用 `us-east-1`。 + 区域从 `AWS_REGION`、`AWS_DEFAULT_REGION`、`amazon-bedrock` 提供商的 `baseUrl` 解析；若都未设置，则默认为 `us-east-1`。 - **IAM 权限：**IAM 角色或用户需要： + **IAM 权限：** IAM 角色或用户需要： ```json { @@ -246,7 +246,7 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 } ``` - 为实现最小权限原则，请将 `InvokeModel` 限定到具体模型： + 为遵循最小权限原则，可将 `InvokeModel` 限定到特定模型： ``` arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 @@ -254,13 +254,13 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 - | 键 | 类型 | 默认值 | 说明 | - | --------------------- | ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | `local.modelPath` | `string` | 自动下载 | GGUF 模型文件的路径 | - | `local.modelCacheDir` | `string` | node-llama-cpp 默认值 | 已下载模型的缓存目录 | - | `local.contextSize` | `number \| "auto"` | `4096` | 嵌入上下文的上下文窗口大小。4096 可覆盖典型分块（128–512 token），同时限制非权重 VRAM 占用。在资源受限的主机上可降至 1024–2048。`"auto"` 使用模型训练时的最大值——不建议用于 8B+ 模型（Qwen3-Embedding-8B：40 960 token → 约 32 GB VRAM，而 4096 时约为 8.8 GB）。 | + | 键名 | 类型 | 默认值 | 说明 | + | --------------------- | ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | `local.modelPath` | `string` | 自动下载 | GGUF 模型文件的路径 | + | `local.modelCacheDir` | `string` | node-llama-cpp 默认值 | 已下载模型的缓存目录 | + | `local.contextSize` | `number \| "auto"` | `4096` | 嵌入上下文的上下文窗口大小。4096 可覆盖典型分块（128–512 tokens），同时限制非权重部分的 VRAM 占用。在资源受限的主机上可降低到 1024–2048。`"auto"` 使用模型训练时的最大值——对于 8B+ 模型不推荐（Qwen3-Embedding-8B：40 960 tokens → 约 32 GB VRAM，而设为 4096 时约为 8.8 GB）。 | - 默认模型：`embeddinggemma-300m-qat-Q8_0.gguf`（约 0.6 GB，自动下载）。需要原生构建：`pnpm approve-builds`，然后执行 `pnpm rebuild node-llama-cpp`。 + 默认模型：`embeddinggemma-300m-qat-Q8_0.gguf`（约 0.6 GB，会自动下载）。需要原生构建：`pnpm approve-builds`，然后执行 `pnpm rebuild node-llama-cpp`。 使用独立 CLI 验证 Gateway 网关所使用的同一提供商路径： @@ -269,7 +269,7 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 openclaw memory index --force --agent main ``` - 如果 `provider` 为 `auto`，只有当 `local.modelPath` 指向现有本地文件时，才会选择 `local`。`hf:` 和 HTTP(S) 模型引用仍然可以在 `provider: "local"` 时显式使用，但在模型尚未落盘可用之前，它们不会让 `auto` 优先选择 local。 + 如果 `provider` 为 `auto`，只有当 `local.modelPath` 指向一个已存在的本地文件时，才会选择 `local`。`hf:` 和 HTTP(S) 模型引用仍可在显式设置 `provider: "local"` 时使用，但在模型尚未落盘可用之前，它们不会让 `auto` 优先选择 local。 @@ -277,9 +277,9 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 ### 内联嵌入超时 - 覆盖 Memory 索引期间内联嵌入批次的超时时间。 + 覆盖 Memory 索引期间内联嵌入批处理的超时时间。 -未设置时使用提供商默认值：对于 `local`、`ollama` 和 `lmstudio` 等本地/自托管提供商为 600 秒，对于托管提供商为 120 秒。当本地 CPU 密集型嵌入批次运行正常但速度较慢时，可增大此值。 +未设置时使用提供商默认值：对于 `local`、`ollama` 和 `lmstudio` 等本地/自托管提供商为 600 秒，对于托管提供商为 120 秒。当本地 CPU 密集型嵌入批处理运行正常但速度较慢时，可增大该值。 --- @@ -288,27 +288,27 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 全部位于 `memorySearch.query.hybrid` 下： -| 键 | 类型 | 默认值 | 说明 | +| 键名 | 类型 | 默认值 | 说明 | | --------------------- | --------- | ------ | ---------------------------- | | `enabled` | `boolean` | `true` | 启用 BM25 + 向量混合搜索 | | `vectorWeight` | `number` | `0.7` | 向量分数的权重（0-1） | | `textWeight` | `number` | `0.3` | BM25 分数的权重（0-1） | -| `candidateMultiplier` | `number` | `4` | 候选池大小乘数 | +| `candidateMultiplier` | `number` | `4` | 候选池大小倍数 | - | 键 | 类型 | 默认值 | 说明 | - | ------------- | --------- | ------ | -------------------------------- | - | `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排序 | - | `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 | + | 键名 | 类型 | 默认值 | 说明 | + | ------------- | --------- | ------ | --------------------------------- | + | `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排序 | + | `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 | - | 键 | 类型 | 默认值 | 说明 | - | ---------------------------- | --------- | ------ | ----------------------- | - | `temporalDecay.enabled` | `boolean` | `false` | 启用时效性加权 | - | `temporalDecay.halfLifeDays` | `number` | `30` | 分数每 N 天减半 | + | 键名 | 类型 | 默认值 | 说明 | + | ---------------------------- | --------- | ------ | ------------------------- | + | `temporalDecay.enabled` | `boolean` | `false` | 启用时效性加权 | + | `temporalDecay.halfLifeDays` | `number` | `30` | 分数每 N 天衰减一半 | - 常青文件（`MEMORY.md`、`memory/` 中无日期的文件）永不衰减。 + 常青文件（`MEMORY.md`、`memory/` 中无日期的文件）永远不会衰减。 @@ -336,11 +336,11 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 --- -## 额外 Memory 路径 +## 其他 Memory 路径 -| 键 | 类型 | 说明 | +| 键名 | 类型 | 说明 | | ------------ | ---------- | ------------------------------ | -| `extraPaths` | `string[]` | 要索引的其他目录或文件 | +| `extraPaths` | `string[]` | 要建立索引的其他目录或文件 | ```json5 { @@ -354,24 +354,24 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 } ``` -路径可以是绝对路径或相对于工作区的路径。目录会递归扫描其中的 `.md` 文件。符号链接的处理取决于当前后端：内置引擎会忽略符号链接，而 QMD 会遵循底层 QMD 扫描器的行为。 +路径可以是绝对路径，也可以是相对于工作区的路径。目录会递归扫描其中的 `.md` 文件。符号链接的处理取决于当前使用的后端：内置引擎会忽略符号链接，而 QMD 会遵循底层 QMD 扫描器的行为。 -对于按智能体范围的跨智能体转录搜索，请使用 `agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。这些额外集合沿用相同的 `{ path, name, pattern? }` 结构，但会按每个智能体合并，并且当路径指向当前工作区之外时，可以保留显式共享名称。如果同一解析后路径同时出现在 `memory.qmd.paths` 和 `memorySearch.qmd.extraCollections` 中，QMD 会保留第一项并跳过重复项。 +对于按智能体范围进行的跨智能体转录搜索，请使用 `agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。这些额外集合遵循相同的 `{ path, name, pattern? }` 结构，但会按智能体进行合并，并且当路径指向当前工作区之外时，可以保留显式共享名称。如果同一个解析后的路径同时出现在 `memory.qmd.paths` 和 `memorySearch.qmd.extraCollections` 中，QMD 会保留第一项并跳过重复项。 --- ## 多模态 Memory（Gemini） -使用 Gemini Embedding 2 在 Markdown 之外同时索引图像和音频： +使用 Gemini Embedding 2 在建立 Markdown 索引的同时为图片和音频建立索引： -| 键 | 类型 | 默认值 | 说明 | -| ------------------------- | ---------- | ---------- | ----------------------------------- | -| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 | -| `multimodal.modalities` | `string[]` | -- | `["image"]`、`["audio"]` 或 `["all"]` | -| `multimodal.maxFileBytes` | `number` | `10000000` | 可索引文件的最大大小 | +| 键名 | 类型 | 默认值 | 说明 | +| ------------------------- | ---------- | ---------- | -------------------------------------- | +| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 | +| `multimodal.modalities` | `string[]` | -- | `["image"]`、`["audio"]` 或 `["all"]` | +| `multimodal.maxFileBytes` | `number` | `10000000` | 建立索引时允许的最大文件大小 | -仅适用于 `extraPaths` 中的文件。默认 Memory 根目录仍仅支持 Markdown。需要 `gemini-embedding-2-preview`。`fallback` 必须为 `"none"`。 +仅适用于 `extraPaths` 中的文件。默认 Memory 根目录仍然只支持 Markdown。需要 `gemini-embedding-2-preview`。`fallback` 必须为 `"none"`。 支持的格式：`.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.heic`、`.heif`（图像）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音频）。 @@ -380,54 +380,54 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 ## 嵌入缓存 -| 键 | 类型 | 默认值 | 说明 | -| ------------------ | --------- | ------- | ------------------------------ | +| 键名 | 类型 | 默认值 | 说明 | +| ------------------ | --------- | ------ | ------------------------------ | | `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存分块嵌入 | -| `cache.maxEntries` | `number` | `50000` | 最大缓存嵌入条目数 | +| `cache.maxEntries` | `number` | `50000` | 缓存的嵌入最大条目数 | -可防止在重新索引或转录更新期间对未变更文本重复生成嵌入。 +可防止在重建索引或更新转录时，对未变更的文本重复执行嵌入。 --- ## 批量索引 -| 键 | 类型 | 默认值 | 说明 | -| ----------------------------- | --------- | ------- | ------------------------ | -| `remote.batch.enabled` | `boolean` | `false` | 启用批量嵌入 API | -| `remote.batch.concurrency` | `number` | `2` | 并行批处理作业数 | -| `remote.batch.wait` | `boolean` | `true` | 等待批处理完成 | -| `remote.batch.pollIntervalMs` | `number` | -- | 轮询间隔 | -| `remote.batch.timeoutMinutes` | `number` | -- | 批处理超时时间 | +| 键名 | 类型 | 默认值 | 说明 | +| ----------------------------- | --------- | ------ | ---------------------- | +| `remote.batch.enabled` | `boolean` | `false` | 启用批量嵌入 API | +| `remote.batch.concurrency` | `number` | `2` | 并行批处理任务数 | +| `remote.batch.wait` | `boolean` | `true` | 等待批处理完成 | +| `remote.batch.pollIntervalMs` | `number` | -- | 轮询间隔 | +| `remote.batch.timeoutMinutes` | `number` | -- | 批处理超时时间 | -适用于 `openai`、`gemini` 和 `voyage`。对于大规模回填，OpenAI 批处理通常最快且最便宜。 +适用于 `openai`、`gemini` 和 `voyage`。对于大规模回填，OpenAI 批处理通常速度最快、成本最低。 -这与 `sync.embeddingBatchTimeoutSeconds` 是分开的；后者控制内联嵌入调用，供本地/自托管提供商使用，以及在未启用提供商批量 API 时供托管提供商使用。 +这与 `sync.embeddingBatchTimeoutSeconds` 是分开的；后者控制内联嵌入调用，用于本地/自托管提供商，以及在未启用提供商批处理 API 时的托管提供商。 --- ## 会话 Memory 搜索（实验性） -对会话转录建立索引，并通过 `memory_search` 提供结果： +为会话转录建立索引，并通过 `memory_search` 提供结果： -| 键 | 类型 | 默认值 | 说明 | -| ----------------------------- | ---------- | ------------ | ------------------------------------- | -| `experimental.sessionMemory` | `boolean` | `false` | 启用会话索引 | -| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含转录 | -| `sync.sessions.deltaBytes` | `number` | `100000` | 触发重新索引的字节阈值 | -| `sync.sessions.deltaMessages` | `number` | `50` | 触发重新索引的消息阈值 | +| 键名 | 类型 | 默认值 | 说明 | +| ----------------------------- | ---------- | ------------ | ----------------------------------- | +| `experimental.sessionMemory` | `boolean` | `false` | 启用会话索引 | +| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含转录 | +| `sync.sessions.deltaBytes` | `number` | `100000` | 触发重建索引的字节阈值 | +| `sync.sessions.deltaMessages` | `number` | `50` | 触发重建索引的消息阈值 | -会话索引需要显式启用，并且异步运行。结果可能会有轻微延迟。会话日志存储在磁盘上，因此请将文件系统访问视为信任边界。 +会话索引需要显式启用，并以异步方式运行。结果可能会略有滞后。会话日志存储在磁盘上，因此请将文件系统访问视为信任边界。 --- ## SQLite 向量加速（sqlite-vec） -| 键 | 类型 | 默认值 | 说明 | -| ---------------------------- | --------- | -------- | --------------------------------- | -| `store.vector.enabled` | `boolean` | `true` | 使用 sqlite-vec 执行向量查询 | -| `store.vector.extensionPath` | `string` | 内置 | 覆盖 sqlite-vec 路径 | +| 键名 | 类型 | 默认值 | 说明 | +| ---------------------------- | --------- | -------- | ----------------------------- | +| `store.vector.enabled` | `boolean` | `true` | 使用 sqlite-vec 执行向量查询 | +| `store.vector.extensionPath` | `string` | 内置 | 覆盖 sqlite-vec 路径 | 当 sqlite-vec 不可用时，OpenClaw 会自动回退到进程内余弦相似度计算。 @@ -435,7 +435,7 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 ## 索引存储 -| 键 | 类型 | 默认值 | 说明 | +| 键名 | 类型 | 默认值 | 说明 | | --------------------- | -------- | ------------------------------------- | ------------------------------------- | | `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支持 `{agentId}` token） | | `store.fts.tokenizer` | `string` | `unicode61` | FTS5 分词器（`unicode61` 或 `trigram`） | @@ -446,47 +446,47 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。 设置 `memory.backend = "qmd"` 以启用。所有 QMD 设置都位于 `memory.qmd` 下： -| 键 | 类型 | 默认值 | 说明 | -| ------------------------ | --------- | -------- | -------------------------------------------- | -| `command` | `string` | `qmd` | QMD 可执行文件路径 | -| `searchMode` | `string` | `search` | 搜索命令：`search`、`vsearch`、`query` | -| `includeDefaultMemory` | `boolean` | `true` | 自动索引 `MEMORY.md` + `memory/**/*.md` | -| `paths[]` | `array` | -- | 额外路径：`{ name, path, pattern? }` | -| `sessions.enabled` | `boolean` | `false` | 索引会话转录 | -| `sessions.retentionDays` | `number` | -- | 转录保留期 | -| `sessions.exportDir` | `string` | -- | 导出目录 | +| 键名 | 类型 | 默认值 | 说明 | +| ------------------------ | --------- | -------- | ------------------------------------------------------------------------------------ | +| `command` | `string` | `qmd` | QMD 可执行文件路径；当服务的 `PATH` 与你的 shell 不同时，请设置绝对路径 | +| `searchMode` | `string` | `search` | 搜索命令：`search`、`vsearch`、`query` | +| `includeDefaultMemory` | `boolean` | `true` | 自动索引 `MEMORY.md` + `memory/**/*.md` | +| `paths[]` | `array` | -- | 额外路径：`{ name, path, pattern? }` | +| `sessions.enabled` | `boolean` | `false` | 为会话转录建立索引 | +| `sessions.retentionDays` | `number` | -- | 转录保留期 | +| `sessions.exportDir` | `string` | -- | 导出目录 | -`searchMode: "search"` 仅为词法/BM25 搜索。OpenClaw 不会为该模式运行语义向量就绪性探测或 QMD 嵌入维护，包括在执行 `memory status --deep` 期间；`vsearch` 和 `query` 仍然要求 QMD 向量已就绪且嵌入可用。 +`searchMode: "search"` 仅为词法/BM25 模式。对于该模式，OpenClaw 不会运行语义向量就绪探测，也不会执行 QMD 嵌入维护，包括在 `memory status --deep` 期间；`vsearch` 和 `query` 则仍然需要 QMD 向量就绪状态和嵌入。 -OpenClaw 优先使用当前的 QMD collection 和 MCP 查询格式，但也会在需要时尝试兼容的 collection pattern 标志和较旧的 MCP 工具名称，以保持旧版 QMD 仍可用。 +OpenClaw 优先使用当前的 QMD collection 和 MCP query 结构，但也会在需要时尝试兼容的 collection pattern flags 和较旧的 MCP 工具名称，以保持对旧版 QMD 的兼容。当 QMD 声明支持多个 collection 过滤器时，同源 collections 会通过一个 QMD 进程进行搜索；较旧的 QMD 构建则继续使用按 collection 分开的兼容路径。同源表示持久 Memory collections 会被归为一组，而会话转录 collections 会保持为单独一组，以便来源多样化仍然同时包含这两类输入。 -QMD 模型覆盖应保留在 QMD 侧，而不是放在 OpenClaw 配置中。如果你需要全局覆盖 QMD 的模型，请在 Gateway 网关运行时环境中设置环境变量，例如 `QMD_EMBED_MODEL`、`QMD_RERANK_MODEL` 和 `QMD_GENERATE_MODEL`。 +QMD 模型覆盖保持在 QMD 侧，而不是 OpenClaw 配置侧。如果你需要全局覆盖 QMD 的模型，请在 Gateway 网关运行时环境中设置环境变量，例如 `QMD_EMBED_MODEL`、`QMD_RERANK_MODEL` 和 `QMD_GENERATE_MODEL`。 - | 键 | 类型 | 默认值 | 说明 | - | ------------------------- | --------- | ------- | -------------------------------- | - | `update.interval` | `string` | `5m` | 刷新间隔 | - | `update.debounceMs` | `number` | `15000` | 文件变更防抖 | - | `update.onBoot` | `boolean` | `true` | 启动时刷新 | - | `update.waitForBootSync` | `boolean` | `false` | 在刷新完成前阻塞启动 | - | `update.embedInterval` | `string` | -- | 单独的嵌入执行周期 | - | `update.commandTimeoutMs` | `number` | -- | QMD 命令超时时间 | - | `update.updateTimeoutMs` | `number` | -- | QMD 更新操作超时时间 | - | `update.embedTimeoutMs` | `number` | -- | QMD 嵌入操作超时时间 | + | 键名 | 类型 | 默认值 | 说明 | + | ------------------------- | --------- | ------- | ---------------------------- | + | `update.interval` | `string` | `5m` | 刷新间隔 | + | `update.debounceMs` | `number` | `15000` | 文件变更去抖动 | + | `update.onBoot` | `boolean` | `true` | 启动时刷新 | + | `update.waitForBootSync` | `boolean` | `false` | 启动时阻塞直到刷新完成 | + | `update.embedInterval` | `string` | -- | 单独的嵌入执行频率 | + | `update.commandTimeoutMs` | `number` | -- | QMD 命令超时时间 | + | `update.updateTimeoutMs` | `number` | -- | QMD 更新操作超时时间 | + | `update.embedTimeoutMs` | `number` | -- | QMD 嵌入操作超时时间 | - | 键 | 类型 | 默认值 | 说明 | - | ------------------------- | -------- | ------- | -------------------------- | - | `limits.maxResults` | `number` | `6` | 最大搜索结果数 | - | `limits.maxSnippetChars` | `number` | -- | 限制摘要长度 | - | `limits.maxInjectedChars` | `number` | -- | 限制注入的总字符数 | - | `limits.timeoutMs` | `number` | `4000` | 搜索超时时间 | + | 键名 | 类型 | 默认值 | 说明 | + | ------------------------- | -------- | ------ | ------------------------ | + | `limits.maxResults` | `number` | `6` | 最大搜索结果数 | + | `limits.maxSnippetChars` | `number` | -- | 限制摘要长度 | + | `limits.maxInjectedChars` | `number` | -- | 限制注入的总字符数 | + | `limits.timeoutMs` | `number` | `4000` | 搜索超时时间 | - 控制哪些会话可以接收 QMD 搜索结果。其 schema 与 [`session.sendPolicy`](/zh-CN/gateway/config-agents#session) 相同： + 控制哪些会话可以接收 QMD 搜索结果。结构与 [`session.sendPolicy`](/zh-CN/gateway/config-agents#session) 相同： ```json5 { @@ -501,9 +501,9 @@ QMD 模型覆盖应保留在 QMD 侧，而不是放在 OpenClaw 配置中。如 } ``` - 已发布的默认配置允许 direct 和 channel 会话，同时仍然拒绝群组。 + 随附默认配置允许 direct 和 channel 会话，同时仍然拒绝群组。 - 默认仅限私信。`match.keyPrefix` 匹配规范化后的会话键；`match.rawKeyPrefix` 匹配原始键，包括 `agent::`。 + 默认仅限私信。`match.keyPrefix` 匹配规范化后的会话键；`match.rawKeyPrefix` 匹配包含 `agent::` 的原始键。 @@ -545,17 +545,17 @@ QMD 模型覆盖应保留在 QMD 侧，而不是放在 OpenClaw 配置中。如 Dreaming 配置位于 `plugins.entries.memory-core.config.dreaming` 下，而不是 `agents.defaults.memorySearch` 下。 -Dreaming 作为一次计划任务扫描运行，并将内部的 light/deep/REM 阶段作为实现细节使用。 +Dreaming 作为一次计划中的完整扫描运行，并将内部的 light/deep/REM 阶段作为实现细节使用。 有关概念行为和斜杠命令，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。 ### 用户设置 -| 键 | 类型 | 默认值 | 说明 | -| ----------- | --------- | ------------- | ----------------------------------------- | -| `enabled` | `boolean` | `false` | 完全启用或禁用 Dreaming | -| `frequency` | `string` | `0 3 * * *` | 完整 Dreaming 扫描的可选 cron 周期 | -| `model` | `string` | 默认模型 | 可选的 Dream Diary 子智能体模型覆盖 | +| 键名 | 类型 | 默认值 | 说明 | +| ----------- | --------- | ------------ | ---------------------------------- | +| `enabled` | `boolean` | `false` | 完全启用或禁用 Dreaming | +| `frequency` | `string` | `0 3 * * *` | 完整 Dreaming 扫描的可选 cron 频率 | +| `model` | `string` | 默认模型 | 可选的 Dream Diary 子智能体模型覆盖 | ### 示例 @@ -582,8 +582,8 @@ Dreaming 作为一次计划任务扫描运行，并将内部的 light/deep/REM ``` -- Dreaming 将机器状态写入 `memory/.dreams/`。 -- Dreaming 将人类可读的叙事输出写入 `DREAMS.md`（或现有的 `dreams.md`）。 +- Dreaming 会将机器状态写入 `memory/.dreams/`。 +- Dreaming 会将人类可读的叙事输出写入 `DREAMS.md`（或现有的 `dreams.md`）。 - `dreaming.model` 使用现有的插件子智能体信任门控；启用它之前，请先设置 `plugins.entries.memory-core.subagent.allowModelOverride: true`。 - light/deep/REM 阶段策略和阈值属于内部行为，不是面向用户的配置。 diff --git a/docs/zh-CN/tools/acp-agents.md b/docs/zh-CN/tools/acp-agents.md index 09909ef6c..865eb8c15 100644 --- a/docs/zh-CN/tools/acp-agents.md +++ b/docs/zh-CN/tools/acp-agents.md @@ -3,119 +3,120 @@ read_when: - 通过 ACP 运行编码 harness - 在消息渠道上设置绑定到会话的 ACP 会话 - 将消息渠道会话绑定到持久化 ACP 会话 - - 排查 ACP 后端、插件接线或完成结果投递问题 - - 在聊天中操作 `/acp` 命令 + - 排查 ACP 后端、插件接线或补全交付问题 + - 在聊天中使用 /acp 命令 sidebarTitle: ACP agents summary: 通过 ACP 后端运行外部编码 harness（Claude Code、Cursor、Gemini CLI、显式 Codex ACP、OpenClaw ACP、OpenCode） title: ACP 智能体 x-i18n: - generated_at: "2026-04-26T07:51:28Z" + generated_at: "2026-04-27T13:49:06Z" model: gpt-5.4 provider: openai - source_hash: e3b8550be4cf0da2593b0770e302833e1722820d3c922e5508a253685cd0cb6b + source_hash: 399aed931ad19c681049e1345d4636e73a47dfd0448e2699d95e8ce0184f60ed source_path: tools/acp-agents.md workflow: 15 --- -[Agent Client Protocol (ACP)](https://agentclientprotocol.com/) 会话 +[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)。 -**ACP 是外部 harness 路径，不是默认的 Codex 路径。** -原生 Codex 应用服务器插件负责 `/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 渠道会话，请使用 -[`openclaw mcp serve`](/zh-CN/cli/mcp)，而不是 ACP。 +[`openclaw mcp serve`](/zh-CN/cli/mcp) 而不是 ACP。 -## 我需要哪一页？ +## 我该看哪个页面？ | 你想要… | 使用这个 | 说明 | | ----------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 在当前会话中绑定或控制 Codex | `/codex bind`、`/codex threads` | 当启用 `codex` 插件时使用原生 Codex 应用服务器路径；包括绑定聊天回复、图像转发、模型/fast/permissions、停止和 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 使用 ACP 与 OpenClaw 通信 | -| 复用本地 AI CLI 作为纯文本回退模型 | [CLI Backends](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有 harness 运行时 | +| 在当前会话中绑定或控制 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 向 OpenClaw 发送 ACP | +| 复用本地 AI CLI 作为纯文本回退模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有 harness 运行时 | -## 开箱即用吗？ +## 这能开箱即用吗？ -通常可以。全新安装默认启用了内置的 `acpx` 运行时插件， -并带有插件本地固定版本的 `acpx` 二进制，OpenClaw 会在启动时探测它 -并执行自修复。运行 `/acp doctor` 可进行就绪检查。 +通常可以。全新安装默认启用内置的 `acpx` 运行时插件， +并带有插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测它 +并自行修复。运行 `/acp doctor` 可进行就绪检查。 -只有当 ACP **真正可用** 时，OpenClaw 才会向智能体介绍 ACP 启动功能： -ACP 必须已启用、分发不能被禁用、当前会话不能被沙箱阻止，并且必须已加载 -一个运行时后端。如果这些条件不满足，ACP 插件 Skills 和 -`sessions_spawn` 的 ACP 指南会保持隐藏，这样智能体就不会建议 +只有在 ACP **确实可用** 时，OpenClaw 才会向智能体介绍 ACP 启动功能： +ACP 必须已启用、分发不能被禁用、当前 +会话不能被沙箱隔离阻止，并且必须已加载运行时后端。 +如果这些条件不满足，ACP 插件 Skills 和 +`sessions_spawn` ACP 指引会保持隐藏，这样智能体就不会建议 一个不可用的后端。 - - - 如果设置了 `plugins.allow`，它就是一个限制性的插件清单，并且**必须**包含 `acpx`；否则内置默认值会被有意阻止，`/acp doctor` 会报告缺少允许列表条目。 + + - 如果设置了 `plugins.allow`，它就是一个限制性的插件清单，并且**必须**包含 `acpx`；否则内置默认项会被有意阻止，`/acp doctor` 会报告缺少 allowlist 条目。 - 目标 harness 适配器（Codex、Claude 等）可能会在你首次使用时通过 `npx` 按需拉取。 - - 该 harness 的供应商认证仍然必须存在于主机上。 - - 如果主机没有 npm 或网络访问能力，首次运行的适配器拉取会失败，直到缓存被预热或适配器以其他方式安装为止。 + - 该 harness 对应的供应商认证仍然必须存在于主机上。 + - 如果主机没有 npm 或网络访问能力，首次运行时的适配器拉取会失败，直到预热缓存或通过其他方式安装适配器。 ACP 会启动一个真实的外部 harness 进程。OpenClaw 负责路由、 - 后台任务状态、投递、绑定和策略；harness - 负责其 provider 登录、模型目录、文件系统行为以及 + 后台任务状态、交付、绑定和策略；harness + 负责它自己的提供商登录、模型目录、文件系统行为以及 原生工具。 在责怪 OpenClaw 之前，请先确认： - `/acp doctor` 报告后端已启用且健康。 - - 当设置了 `acp.allowedAgents` 允许列表时，目标 id 在允许范围内。 + - 当设置了 `acp.allowedAgents` allowlist 时，目标 id 在允许范围内。 - harness 命令可以在 Gateway 网关主机上启动。 - - 该 harness 所需的 provider 认证已存在（`claude`、`codex`、`gemini`、`opencode`、`droid` 等）。 - - 所选模型确实存在于该 harness 中——模型 id 在不同 harness 之间并不通用。 + - 该 harness 所需的提供商认证已存在（`claude`、`codex`、`gemini`、`opencode`、`droid` 等）。 + - 所选模型对该 harness 确实存在——模型 id 不能在不同 harness 之间通用。 - 请求的 `cwd` 存在且可访问，或者省略 `cwd` 让后端使用其默认值。 - - 权限模式与工作类型匹配。非交互会话无法点击原生权限提示，因此大量写入/exec 的编码运行通常需要一个可以无头继续执行的 ACPX 权限配置文件。 + - 权限模式与工作内容相匹配。非交互式会话无法点击原生权限提示，因此大量写入/执行的编码运行通常需要一个能够无头继续执行的 ACPX 权限配置。 -默认情况下，OpenClaw 插件工具和内置 OpenClaw 工具**不会** -暴露给 ACP harness。只有在 harness -确实应直接调用这些工具时，才在 +默认情况下，OpenClaw 插件工具和内置 OpenClaw 工具**不会**暴露给 +ACP harness。只有在 harness +应该直接调用这些工具时，才在 [ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup) 中启用显式 MCP 桥接。 ## 支持的 harness 目标 -使用内置 `acpx` 后端时，可将这些 harness id 用作 `/acp spawn ` -或 `sessions_spawn({ runtime: "acp", agentId: "" })` 的目标： +使用内置 `acpx` 后端时，可将以下 harness id 用作 `/acp spawn ` +或 `sessions_spawn({ runtime: "acp", agentId: "" })` 目标： | Harness id | 典型后端 | 说明 | | ---------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- | -| `claude` | Claude Code ACP 适配器 | 需要主机上已有 Claude Code 认证。 | -| `codex` | Codex ACP 适配器 | 仅在原生 `/codex` 不可用或明确要求 ACP 时，作为显式 ACP 回退。 | +| `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 密钥设置。 | | `iflow` | iFlow CLI | 适配器可用性和模型控制取决于已安装的 CLI。 | | `kilocode` | Kilo Code CLI | 适配器可用性和模型控制取决于已安装的 CLI。 | -| `kimi` | Kimi/Moonshot CLI | 需要主机上已有 Kimi/Moonshot 认证。 | +| `kimi` | Kimi/Moonshot CLI | 需要主机上有 Kimi/Moonshot 认证。 | | `kiro` | Kiro CLI | 适配器可用性和模型控制取决于已安装的 CLI。 | -| `opencode` | OpenCode ACP 适配器 | 需要 OpenCode CLI/provider 认证。 | -| `openclaw` | 通过 `openclaw acp` 实现的 OpenClaw Gateway 网关桥接 | 允许一个支持 ACP 的 harness 反向连接到一个 OpenClaw Gateway 网关会话。 | +| `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 的认证。 | +| `qwen` | Qwen Code / Qwen CLI | 需要主机上有兼容 Qwen 的认证。 | -可以在 acpx 自身中配置自定义 acpx 智能体别名，但 OpenClaw -策略仍然会检查 `acp.allowedAgents`，以及 -任何 `agents.list[].runtime.acp.agent` 映射，然后才进行分发。 +可以在 acpx 本身中配置自定义 acpx 智能体别名，但 OpenClaw +策略仍会在分发前检查 `acp.allowedAgents` 以及任何 +`agents.list[].runtime.acp.agent` 映射。 -## 操作手册 +## 运维操作手册 -在聊天中使用 `/acp` 的快速流程： +在聊天中快速使用 `/acp` 的流程： @@ -124,8 +125,8 @@ ACP 必须已启用、分发不能被禁用、当前会话不能被沙箱阻止 `/acp spawn codex --bind here`。 - 在已绑定的会话或线程中继续（或者显式指定会话 - 键）。 + 继续在已绑定的会话或线程中工作（或者显式 + 指定会话 key）。 `/acp status` @@ -145,61 +146,62 @@ ACP 必须已启用、分发不能被禁用、当前会话不能被沙箱阻止 - - 启动会创建或恢复一个 ACP 运行时会话，在 OpenClaw 会话存储中记录 ACP 元数据，并且在该运行由父级拥有时可能会创建一个后台任务。 - - 绑定后的后续消息会直接发送到 ACP 会话，直到绑定被关闭、取消聚焦、重置或过期。 + - 启动会创建或恢复一个 ACP 运行时会话，在 OpenClaw 会话存储中记录 ACP 元数据，并且当该运行由父级拥有时，可能会创建一个后台任务。 + - 绑定后的后续消息会直接发送到 ACP 会话，直到绑定被关闭、失焦、重置或过期。 - Gateway 网关命令会保留在本地。`/acp ...`、`/status` 和 `/unfocus` 永远不会作为普通提示文本发送给已绑定的 ACP harness。 - - `cancel` 会在后端支持取消时中止当前轮次；它不会删除绑定或会话元数据。 - - `close` 会从 OpenClaw 的视角结束 ACP 会话并移除绑定。如果 harness 支持恢复，它仍可能保留自己的上游历史。 - - 空闲运行时工作进程会在 `acp.runtime.ttlMinutes` 之后进入可清理状态；已存储的会话元数据仍可通过 `/acp sessions` 查看。 + - 当后端支持取消时，`cancel` 会中止当前活动轮次；它不会删除绑定或会话元数据。 + - `close` 会从 OpenClaw 的视角结束 ACP 会话并移除绑定。如果 harness 支持恢复，它仍可能保留自己的上游历史记录。 + - 空闲运行时工作进程在 `acp.runtime.ttlMinutes` 之后可能会被清理；存储的会话元数据仍可通过 `/acp sessions` 使用。 - 当原生 Codex - 插件已启用时，应路由到**原生 Codex 插件**的自然语言触发词： + 当 **原生 Codex 插件** 已启用时，应路由到它的自然语言触发词： - - “把这个 Discord 频道绑定到 Codex。” + - “把这个 Discord 渠道绑定到 Codex。” - “把这个聊天附加到 Codex 线程 ``。” - - “显示 Codex 线程，然后绑定这个。” + - “显示 Codex 线程，然后绑定这一条。” 原生 Codex 会话绑定是默认的聊天控制路径。 OpenClaw 动态工具仍通过 OpenClaw 执行，而 - Codex 原生工具（如 shell/apply-patch）则在 Codex 内执行。 - 对于 Codex 原生工具事件，OpenClaw 会按轮次注入一个原生 - hook 中继，使插件钩子能够阻止 `before_tool_call`、观察 - `after_tool_call`，并将 Codex `PermissionRequest` 事件 - 通过 OpenClaw 审批进行路由。Codex `Stop` 钩子会被中继到 - OpenClaw `before_agent_finalize`，插件可在其中请求模型在 Codex 最终输出答案前 - 再进行一次传递。该中继保持刻意保守： - 它不会修改 Codex 原生工具参数，也不会重写 Codex 线程记录。只有当你想使用 ACP 运行时/会话模型时， - 才应使用显式 ACP。内嵌 Codex - 支持边界记录于 + Codex 原生工具（如 shell/apply-patch）则在 Codex 内部执行。 + 对于 Codex 原生工具事件，OpenClaw 会注入每轮次的原生 + hook 中继，这样插件钩子就可以阻止 `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)。 - + - `openai-codex/*` — PI Codex OAuth/订阅路径。 - - `openai/*` 加 `agentRuntime.id: "codex"` — 原生 Codex 应用服务器内嵌运行时。 + - `openai/*` 加上 `agentRuntime.id: "codex"` — 原生 Codex app-server 内嵌运行时。 - `/codex ...` — 原生 Codex 会话控制。 - `/acp ...` 或 `runtime: "acp"` — 显式 ACP/acpx 控制。 - + 应路由到 ACP 运行时的触发词： - “把这个任务作为一次性 Claude Code ACP 会话运行，并总结结果。” - - “对此任务使用 Gemini CLI 在线程中运行，然后将后续内容继续保留在同一个线程中。” + - “针对这个任务使用 Gemini CLI 在线程中运行，然后把后续跟进保留在同一线程里。” - “通过 ACP 在线程后台运行 Codex。” OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`， - 在支持时绑定到当前会话或线程，并且 - 将后续消息路由到该会话，直到关闭/过期。只有在显式要求 ACP/acpx - 或原生 Codex 插件对所请求操作不可用时，Codex 才会走这条路径。 + 在支持时绑定到当前会话或线程，并 + 将后续消息路由到该会话，直到关闭/过期。只有当明确指定 ACP/acpx + 或所请求操作的原生 Codex + 插件不可用时，Codex 才会走这一路径。 对于 `sessions_spawn`，只有在 ACP - 已启用、请求方未被沙箱隔离，且 ACP 运行时 - 后端已加载时，才会公布 `runtime: "acp"`。 - 它面向 `codex`、 - `claude`、`droid`、`gemini` 或 `opencode` 这类 ACP harness id。不要传入来自 - `agents_list` 的普通 OpenClaw 配置智能体 id，除非该条目 - 明确配置了 `agents.list[].runtime.type="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。 @@ -207,111 +209,111 @@ ACP 必须已启用、分发不能被禁用、当前会话不能被沙箱阻止 -## ACP 与子智能体的区别 +## ACP 与子智能体 -当你需要外部 harness 运行时时，请使用 ACP。当 `codex` -插件已启用，并且你需要 Codex 会话绑定/控制时，请使用**原生 Codex -应用服务器**。当你需要 OpenClaw 原生的 +当你需要外部 harness 运行时时，请使用 ACP。当启用 `codex` +插件时，如需 Codex 会话绑定/控制，请使用**原生 Codex +app-server**。当你需要 OpenClaw 原生的 委派运行时，请使用**子智能体**。 | 区域 | ACP 会话 | 子智能体运行 | | ------------- | ------------------------------------- | ---------------------------------- | | 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 | | 会话键 | `agent::acp:` | `agent::subagent:` | -| 主命令 | `/acp ...` | `/subagents ...` | -| 启动工具 | `sessions_spawn` 配合 `runtime:"acp"` | `sessions_spawn`（默认运行时） | +| 主要命令 | `/acp ...` | `/subagents ...` | +| 启动工具 | 带 `runtime:"acp"` 的 `sessions_spawn` | `sessions_spawn`（默认运行时） | -另请参见 [子智能体](/zh-CN/tools/subagents)。 +另请参阅[子智能体](/zh-CN/tools/subagents)。 ## ACP 如何运行 Claude Code -对于通过 ACP 运行 Claude Code，其栈如下： +对于通过 ACP 运行的 Claude Code，栈结构如下： 1. OpenClaw ACP 会话控制平面。 2. 内置 `acpx` 运行时插件。 3. Claude ACP 适配器。 4. Claude 侧运行时/会话机制。 -ACP Claude 是一个**harness 会话**，具备 ACP 控制、会话恢复、 -后台任务跟踪，以及可选的会话/线程绑定。 +ACP Claude 是一个**harness 会话**，具有 ACP 控制、会话恢复、 +后台任务跟踪以及可选的会话/线程绑定。 -CLI 后端则是独立的纯文本本地回退运行时——参见 -[CLI Backends](/zh-CN/gateway/cli-backends)。 +CLI 后端是独立的纯文本本地回退运行时——请参见 +[CLI 后端](/zh-CN/gateway/cli-backends)。 -对于操作员来说，实际规则是： +对运维人员来说，实际规则是： -- **想要 `/acp spawn`、可绑定会话、运行时控制，或持久化 harness 工作？** 用 ACP。 -- **想要通过原始 CLI 实现简单的本地文本回退？** 用 CLI 后端。 +- **想要 `/acp spawn`、可绑定会话、运行时控制或持久化 harness 工作？** 使用 ACP。 +- **想要通过原始 CLI 获得简单的本地文本回退？** 使用 CLI 后端。 ## 绑定会话 ### 心智模型 -- **聊天界面**——人们持续交流的地方（Discord 频道、Telegram 话题、iMessage 聊天）。 -- **ACP 会话**——OpenClaw 路由到的持久化 Codex/Claude/Gemini 运行时状态。 -- **子线程/话题**——仅在使用 `--thread ...` 时创建的可选额外消息界面。 -- **运行时工作区**——harness 运行所在的文件系统位置（`cwd`、仓库检出、后端工作区）。它独立于聊天界面。 +- **聊天界面**——人们持续交流的地方（Discord 渠道、Telegram 话题、iMessage 聊天）。 +- **ACP 会话**——OpenClaw 路由到的持久 Codex/Claude/Gemini 运行时状态。 +- **子线程/话题**——仅在使用 `--thread ...` 时创建的可选附加消息界面。 +- **运行时工作区**——harness 运行所在的文件系统位置（`cwd`、仓库检出目录、后端工作区）。它独立于聊天界面。 ### 当前会话绑定 -`/acp spawn --bind here` 会将当前会话固定绑定到 -已启动的 ACP 会话——不创建子线程，使用同一个聊天界面。OpenClaw 继续 -负责传输、认证、安全性和投递。该会话中的后续消息会路由到同一个 -会话；`/new` 和 `/reset` 会原地重置该 +`/acp spawn --bind here` 会将当前会话固定到 +已启动的 ACP 会话——不创建子线程，使用相同的聊天界面。OpenClaw 继续 +负责传输、认证、安全和交付。该会话中的后续消息 +会路由到同一个会话；`/new` 和 `/reset` 会就地重置该 会话；`/acp close` 会移除绑定。 示例： ```text -/codex bind # 原生 Codex 绑定，后续消息路由到这里 +/codex bind # 原生 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 # 为 Codex 显式使用 ACP 回退 +/acp spawn codex --thread auto # 可能会创建子线程/话题并绑定到那里 /acp spawn codex --bind here --cwd /workspace/repo # 相同聊天绑定，Codex 在 /workspace/repo 中运行 ``` - + - `--bind here` 和 `--thread ...` 互斥。 - - `--bind here` 仅适用于声明支持当前会话绑定的渠道；否则 OpenClaw 会返回明确的不支持消息。绑定会在 Gateway 网关重启后继续保留。 - - 在 Discord 上，只有当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions`——对于 `--bind here` 则不需要。 - - 如果你在未指定 `--cwd` 的情况下启动到另一个 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误直接显示。 - - Gateway 网关管理命令会保留在绑定会话本地——即使普通后续文本会被路由到已绑定的 ACP 会话，`/acp ...` 命令仍由 OpenClaw 处理；只要该界面启用了命令处理，`/status` 和 `/unfocus` 也始终保留在本地。 + - `--bind here` 仅适用于声明支持当前会话绑定的渠道；否则 OpenClaw 会返回清晰的不支持消息。绑定会在 Gateway 网关重启后持续存在。 + - 在 Discord 上，仅当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才要求 `spawnAcpSessions`——对于 `--bind here` 则不需要。 + - 如果你在未指定 `--cwd` 的情况下启动到不同的 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误直接显示。 + - Gateway 网关管理命令在已绑定会话中仍保留在本地——即使普通后续文本会路由到已绑定的 ACP 会话，`/acp ...` 命令仍由 OpenClaw 处理；只要该界面启用了命令处理，`/status` 和 `/unfocus` 也始终保留在本地。 当某个渠道适配器启用了线程绑定时： - OpenClaw 会将一个线程绑定到目标 ACP 会话。 - 该线程中的后续消息会路由到已绑定的 ACP 会话。 - - ACP 输出会投递回同一个线程。 - - 取消聚焦/关闭/归档/空闲超时或最大存活期到期都会移除绑定。 - - `/acp close`、`/acp cancel`、`/acp status`、`/status` 和 `/unfocus` 是 Gateway 网关命令，不是发给 ACP harness 的提示。 + - ACP 输出会回传到同一个线程。 + - 失焦/关闭/归档/空闲超时或最大时长到期时，会移除该绑定。 + - `/acp close`、`/acp cancel`、`/acp status`、`/status` 和 `/unfocus` 是 Gateway 网关命令，不会作为提示发送给 ACP harness。 线程绑定 ACP 所需的功能标志： - `acp.enabled=true` - - `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停 ACP 分发）。 - - 渠道适配器 ACP 线程启动标志已启用（依适配器而定）： + - `acp.dispatch.enabled` 默认开启（设置为 `false` 可暂停自动 ACP 线程分发；显式的 `sessions_spawn({ runtime: "acp" })` 调用仍可使用）。 + - 已启用渠道适配器的 ACP 线程启动标志（适配器专属）： - Discord：`channels.discord.threadBindings.spawnAcpSessions=true` - Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true` - 线程绑定支持因适配器而异。如果当前渠道 - 适配器不支持线程绑定，OpenClaw 会返回明确的 + 线程绑定支持取决于具体适配器。如果当前渠道 + 适配器不支持线程绑定，OpenClaw 会返回清晰的 不支持/不可用消息。 - 任何暴露会话/线程绑定能力的渠道适配器。 - - 当前内置支持：**Discord** 线程/频道、**Telegram** 话题（群组/超级群组中的论坛话题以及私信话题）。 - - 插件渠道也可以通过相同的绑定接口添加支持。 + - 当前内置支持：**Discord** 线程/渠道、**Telegram** 话题（群组/超级群组中的论坛话题以及私信话题）。 + - 插件渠道也可通过相同的绑定接口添加支持。 ## 持久化渠道绑定 -对于非临时工作流，请在 -顶层 `bindings[]` 条目中配置持久化 ACP 绑定。 +对于非临时工作流，请在顶层 `bindings[]` 条目中 +配置持久化 ACP 绑定。 ### 绑定模型 @@ -319,27 +321,27 @@ CLI 后端则是独立的纯文本本地回退运行时——参见 标记一个持久化 ACP 会话绑定。 - 标识目标会话。各渠道的结构如下： + 标识目标会话。按渠道区分的结构如下： -- **Discord 频道/线程：** `match.channel="discord"` + `match.peer.id=""` +- **Discord 渠道/线程：** `match.channel="discord"` + `match.peer.id=""` - **Telegram 论坛话题：** `match.channel="telegram"` + `match.peer.id=":topic:"` -- **BlueBubbles 私信/群组：** `match.channel="bluebubbles"` + `match.peer.id=""`。对于稳定的群组绑定，优先使用 `chat_id:*` 或 `chat_identifier:*`。 -- **iMessage 私信/群组：** `match.channel="imessage"` + `match.peer.id=""`。对于稳定的群组绑定，优先使用 `chat_id:*`。 +- **BlueBubbles 私信/群组：** `match.channel="bluebubbles"` + `match.peer.id=""`。稳定的群组绑定优先使用 `chat_id:*` 或 `chat_identifier:*`。 +- **iMessage 私信/群组：** `match.channel="imessage"` + `match.peer.id=""`。稳定的群组绑定优先使用 `chat_id:*`。 所属的 OpenClaw 智能体 id。 - 可选的 ACP 覆盖值。 + 可选的 ACP 覆盖设置。 - 可选的面向操作员标签。 + 面向运维人员的可选标签。 可选的运行时工作目录。 - 可选的后端覆盖值。 + 可选的后端覆盖设置。 ### 每个智能体的运行时默认值 @@ -441,24 +443,24 @@ CLI 后端则是独立的纯文本本地回退运行时——参见 ### 行为 - OpenClaw 会在使用前确保已配置的 ACP 会话存在。 -- 该频道或话题中的消息会被路由到已配置的 ACP 会话。 -- 在已绑定的会话中，`/new` 和 `/reset` 会原地重置同一个 ACP 会话键。 -- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然会生效。 -- 对于跨智能体 ACP 启动，如果未显式指定 `cwd`，OpenClaw 会从智能体配置中继承目标智能体工作区。 -- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失型访问失败会作为启动错误直接显示。 +- 该渠道或话题中的消息会路由到已配置的 ACP 会话。 +- 在已绑定的会话中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话键。 +- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然适用。 +- 对于没有显式 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置继承目标智能体的工作区。 +- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失类访问失败则会作为启动错误直接显示。 ## 启动 ACP 会话 -启动 ACP 会话有两种方式： +有两种方式可以启动 ACP 会话： - + 使用 `runtime: "acp"` 从智能体轮次或 - 工具调用中启动一个 ACP 会话。 + 工具调用中启动 ACP 会话。 ```json { - "task": "Open the repo and summarize failing tests", + "task": "打开仓库并总结失败的测试", "runtime": "acp", "agentId": "codex", "thread": true, @@ -467,15 +469,15 @@ CLI 后端则是独立的纯文本本地回退运行时——参见 ``` - `runtime` 默认为 `subagent`，因此对于 ACP 会话需要显式设置 `runtime: "acp"`。 - 如果省略 `agentId`，OpenClaw 会在已配置时使用 + `runtime` 默认是 `subagent`，因此对于 ACP 会话需要显式设置 + `runtime: "acp"`。如果省略 `agentId`，OpenClaw 会在已配置时使用 `acp.defaultAgent`。`mode: "session"` 需要 - `thread: true` 才能保持一个持久化的绑定会话。 + `thread: true` 才能保持持久化的绑定会话。 - - 使用 `/acp spawn` 从聊天中进行显式的操作员控制。 + + 使用 `/acp spawn` 在聊天中进行显式运维控制。 ```text /acp spawn codex --mode persistent --thread auto @@ -492,7 +494,7 @@ CLI 后端则是独立的纯文本本地回退运行时——参见 - `--cwd ` - `--label ` - 参见 [Slash commands](/zh-CN/tools/slash-commands)。 + 参见[斜杠命令](/zh-CN/tools/slash-commands)。 @@ -503,82 +505,83 @@ CLI 后端则是独立的纯文本本地回退运行时——参见 发送到 ACP 会话的初始提示。 - 对于 ACP 会话，必须为 `"acp"`。 + 对于 ACP 会话，必须是 `"acp"`。 - ACP 目标 harness id。如果已设置，则会回退到 `acp.defaultAgent`。 + ACP 目标 harness id。如果已设置，则回退到 `acp.defaultAgent`。 在支持时请求线程绑定流程。 - `"run"` 是一次性；`"session"` 是持久化。如果 `thread: true` 且 + `"run"` 是一次性运行；`"session"` 是持久化会话。如果 `thread: true` 且 省略了 `mode`，OpenClaw 可能会根据 - 运行时路径默认采用持久化行为。`mode: "session"` 需要 `thread: true`。 + 运行时路径默认使用持久化行为。`mode: "session"` 要求 `thread: true`。 请求的运行时工作目录（由后端/运行时 策略验证）。如果省略，ACP 启动会在已配置时继承目标智能体工作区； 缺失的继承路径会回退到后端 - 默认值，而真实访问错误会直接返回。 + 默认值，而真实的访问错误会直接返回。 - 在会话/横幅文本中使用的面向操作员标签。 + 用于会话/横幅文本中的面向运维人员标签。 - 恢复现有 ACP 会话，而不是创建一个新会话。 + 恢复现有 ACP 会话，而不是创建新会话。该 智能体会通过 `session/load` 重放其会话历史。 需要 `runtime: "acp"`。 - `"parent"` 会将初始 ACP 运行的进度摘要以系统事件形式流式返回到 - 请求方会话。接受的响应中可能包含 - 指向会话范围 JSONL 日志 - （`.acp-stream.jsonl`）的 `streamLogPath`，你可以跟踪它以查看完整中继历史。 + `"parent"` 会将初始 ACP 运行进度摘要作为系统事件 + 回传到请求方会话。接受的响应可能包含 + 指向会话级 JSONL 日志的 `streamLogPath` + （`.acp-stream.jsonl`），你可以跟踪它以查看完整的中继历史。 - 在 N 秒后中止 ACP 子轮次。`0` 会让该轮次走 - Gateway 网关的无超时路径。相同的值会同时应用到 Gateway 网关 - 运行和 ACP 运行时，这样卡住/配额耗尽的 harness 就不会 + 在 N 秒后中止 ACP 子轮次。`0` 会让该轮次保持在 + Gateway 网关的无超时路径上。相同的值会同时应用到 Gateway 网关 + 运行和 ACP 运行时，因此卡住或配额耗尽的 harness 不会 无限期占用父智能体通道。 - 对 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` 并支持 + 对 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 会明确失败，而不是 静默回退到目标智能体默认值。 - 显式的 thinking/推理强度。对于 Codex ACP，`minimal` 映射为 - 低强度，`low`/`medium`/`high`/`xhigh` 直接映射，而 `off` - 则省略推理强度启动覆盖。 + 显式思考/推理强度。对于 Codex ACP，`minimal` 会映射为 + 低强度，`low`/`medium`/`high`/`xhigh` 会直接映射，而 `off` + 会省略推理强度启动覆盖。 -## 启动绑定与线程模式 +## 启动绑定和线程模式 | 模式 | 行为 | | ------ | ---------------------------------------------------------------------- | - | `here` | 原地绑定当前活动会话；如果当前没有活动会话则失败。 | + | `here` | 就地绑定当前活动会话；如果当前没有活动会话则失败。 | | `off` | 不创建当前会话绑定。 | 说明： - - `--bind here` 是“让这个频道或聊天由 Codex 支持”的最简单操作员路径。 + - `--bind here` 是运维人员实现“让这个渠道或聊天由 Codex 支持”的最简单路径。 - `--bind here` 不会创建子线程。 - - `--bind here` 仅在暴露当前会话绑定支持的渠道上可用。 - - `--bind` 和 `--thread` 不能在同一次 `/acp spawn` 调用中同时使用。 + - `--bind here` 仅适用于暴露当前会话绑定支持的渠道。 + - `--bind` 和 `--thread` 不能在同一个 `/acp spawn` 调用中组合使用。 | 模式 | 行为 | | ------ | --------------------------------------------------------------------------------------------------- | | `auto` | 在活动线程中：绑定该线程。在线程外：在支持时创建/绑定一个子线程。 | - | `here` | 要求当前处于活动线程中；如果不在线程中则失败。 | + | `here` | 要求当前处于活动线程中；否则失败。 | | `off` | 不绑定。会话以未绑定状态启动。 | 说明： @@ -587,185 +590,185 @@ CLI 后端则是独立的纯文本本地回退运行时——参见 - 线程绑定启动需要渠道策略支持： - Discord：`channels.discord.threadBindings.spawnAcpSessions=true` - Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true` - - 如果你想固定当前会话而不创建子线程，请使用 `--bind here`。 + - 当你想固定当前会话而不创建子线程时，请使用 `--bind here`。 -## 投递模型 +## 交付模型 ACP 会话既可以是交互式工作区，也可以是由父级拥有的 -后台工作。投递路径取决于其形态。 +后台工作。交付路径取决于其形态。 - 交互式会话的设计目标是在一个可见的聊天 - 界面中持续对话： + 交互式会话旨在持续在可见聊天 + 界面上交流： - `/acp spawn ... --bind here` 会将当前会话绑定到 ACP 会话。 - - `/acp spawn ... --thread ...` 会将某个渠道线程/话题绑定到 ACP 会话。 + - `/acp spawn ... --thread ...` 会将渠道线程/话题绑定到 ACP 会话。 - 持久化配置的 `bindings[].type="acp"` 会将匹配的会话路由到同一个 ACP 会话。 - 在已绑定会话中的后续消息会直接路由到 - ACP 会话，而 ACP 输出会被投递回同一个 - 频道/线程/话题。 + 已绑定会话中的后续消息会直接路由到 + ACP 会话，ACP 输出也会回传到同一个 + 渠道/线程/话题。 OpenClaw 发送给 harness 的内容： - - 普通的绑定后续消息会作为提示文本发送，外加附件——但仅在 harness/后端支持它们时才会附带。 - - `/acp` 管理命令和本地 Gateway 网关命令会在 ACP 分发之前被拦截。 - - 运行时生成的完成事件会按目标具体化。OpenClaw 智能体会收到 OpenClaw 的内部 runtime-context 信封；外部 ACP harness 会收到一个普通提示，其中包含子结果和指令。原始 `<<>>` 信封绝不应发送给外部 harness，也不应作为 ACP 用户转录文本持久化。 - - ACP 转录条目使用用户可见的触发文本或普通完成提示。在可能的情况下，内部事件元数据会在 OpenClaw 中保持结构化，不会被视为用户撰写的聊天内容。 + - 普通的已绑定后续消息会作为提示文本发送，附件仅在 harness/后端支持时一并发送。 + - `/acp` 管理命令和本地 Gateway 网关命令会在 ACP 分发前被拦截。 + - 运行时生成的 completion 事件会按目标具体实现。OpenClaw 智能体会收到 OpenClaw 的内部运行时上下文 envelope；外部 ACP harness 会收到带有子结果和指令的纯提示。原始 `<<>>` envelope 绝不能发送给外部 harness，也不能作为 ACP 用户 transcript 文本持久化。 + - ACP transcript 条目使用用户可见的触发文本或纯 completion 提示。内部事件元数据会尽可能以结构化形式保留在 OpenClaw 中，不会被视为用户编写的聊天内容。 - 由另一个智能体运行所启动的一次性 ACP 会话是后台 - 子级，类似于子智能体： + 由另一个智能体运行启动的一次性 ACP 会话属于后台 + 子项，类似于子智能体： - 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。 - - 子级在它自己的 ACP harness 会话中运行。 - - 子级轮次运行在与原生子智能体启动相同的后台通道上，因此缓慢的 ACP harness 不会阻塞无关的主会话工作。 - - 完成会通过任务完成通知路径回传。OpenClaw 会在发送给外部 harness 之前，将内部完成元数据转换为普通 ACP 提示，因此 harness 不会看到 OpenClaw 专用的运行时上下文标记。 - - 当需要面向用户的回复时，父级会用正常助手口吻重写子级结果。 + - 子项在它自己的 ACP harness 会话中运行。 + - 子轮次运行在与原生子智能体启动相同的后台通道上，因此缓慢的 ACP harness 不会阻塞无关的主会话工作。 + - 完成情况会通过任务完成通告路径回报。OpenClaw 会在发送到外部 harness 之前，将内部完成元数据转换为纯 ACP 提示，因此 harness 不会看到 OpenClaw 专用的运行时上下文标记。 + - 当需要面向用户的回复时，父级会以普通 assistant 语气重写子结果。 **不要**将此路径视为父级 - 与子级之间的点对点聊天。子级已经拥有一条回传给 + 与子项之间的点对点聊天。子项已经有一个回传到 父级的完成通道。 - - `sessions_send` 可以在启动之后以另一个会话为目标。对于普通 - 对等会话，OpenClaw 会在注入消息后使用一条智能体到智能体（A2A）跟进路径： + + `sessions_send` 可以在启动后以另一个会话为目标。对于普通 + 对等会话，OpenClaw 在注入消息后会使用 + agent-to-agent（A2A）后续路径： - 等待目标会话的回复。 - - 可选地让请求方和目标交换有限数量的后续轮次。 - - 要求目标生成一条通知消息。 - - 将该通知投递到可见频道或线程。 + - 可选地让请求方和目标交换有限轮数的后续消息。 + - 要求目标生成一条通告消息。 + - 将该通告投递到可见渠道或线程。 - 对于发送方需要一个 - 可见跟进的对等发送场景，这条 A2A 路径是一种回退方案。当一个无关会话能够 - 看到并向 ACP 目标发送消息时，它仍然会保持启用，例如在宽泛的 + 该 A2A 路径是对等发送时的一种回退方案，适用于发送方需要一个 + 可见后续回复的情况。当一个无关会话能够 + 查看并向 ACP 目标发送消息时，它仍然保持启用，例如在宽松的 `tools.sessions.visibility` 设置下。 - 只有当请求方是其自身父级拥有的一次性 ACP 子级的 - 父级时，OpenClaw 才会跳过 A2A 跟进。在这种情况下， - 在任务完成之上再运行 A2A 可能会用 - 子级结果唤醒父级，再把父级回复转发回子级，从而 - 形成父子回声循环。对于这种已拥有子级的情况，`sessions_send` 结果会报告 + 仅当请求方是其自有的父级拥有的一次性 ACP 子项的 + 父级时，OpenClaw 才会跳过 A2A 后续路径。在这种情况下， + 如果在任务完成之上再运行 A2A，可能会用 + 子项结果唤醒父级，再将父级回复转发回子项， + 从而形成父级/子项回声循环。对于该自有子项情况，`sessions_send` 结果会报告 `delivery.status="skipped"`， - 因为完成路径已经负责处理该结果。 + 因为完成路径已经负责处理结果。 - 使用 `resumeSessionId` 继续一个先前的 ACP 会话，而不是 - 重新开始。智能体会通过 - `session/load` 重放其会话历史，因此它可以带着此前的完整上下文继续。 + 使用 `resumeSessionId` 可以继续之前的 ACP 会话，而不是 + 从头开始。该智能体会通过 + `session/load` 重放其会话历史，因此它会带着此前全部上下文继续工作。 ```json { - "task": "Continue where we left off — fix the remaining test failures", + "task": "从上次停下的地方继续——修复剩余的测试失败", "runtime": "acp", "agentId": "codex", "resumeSessionId": "" } ``` - 常见使用场景： + 常见用例： - - 将一个 Codex 会话从你的笔记本交接到手机——告诉你的智能体从你停下的地方继续。 - - 继续你之前在 CLI 中以交互方式开始、现在要通过智能体无头继续的编码会话。 - - 接续因 Gateway 网关重启或空闲超时而中断的工作。 + - 将一个 Codex 会话从你的笔记本电脑交接到手机——告诉你的智能体从你停下的地方继续。 + - 继续一个你先前在 CLI 中以交互方式启动、现在想通过智能体以无头方式继续的编码会话。 + - 继续处理因 Gateway 网关重启或空闲超时而中断的工作。 说明： - - `resumeSessionId` 需要 `runtime: "acp"`——如果与子智能体运行时一起使用会返回错误。 - - `resumeSessionId` 会恢复上游 ACP 会话历史；`thread` 和 `mode` 仍会正常应用到你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然要求 `thread: true`。 + - `resumeSessionId` 需要 `runtime: "acp"`——如果与子智能体运行时一起使用，会返回错误。 + - `resumeSessionId` 会恢复上游 ACP 会话历史；`thread` 和 `mode` 仍会正常应用到你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍要求 `thread: true`。 - 目标智能体必须支持 `session/load`（Codex 和 Claude Code 支持）。 - - 如果找不到该会话 id，启动会以明确错误失败——不会静默回退到新会话。 + - 如果找不到该会话 id，启动会以清晰错误失败——不会静默回退到新会话。 - 在 Gateway 网关部署之后，请运行一次实时端到端检查，而不要 - 只依赖单元测试： + Gateway 网关部署后，请运行一次真实的端到端检查，而不是 + 只相信单元测试： - 1. 在目标主机上验证已部署的 Gateway 网关版本和提交。 - 2. 打开一个指向实时智能体的临时 ACPX 桥接会话。 - 3. 要求该智能体调用 `sessions_spawn`，参数为 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务内容为 `Reply with exactly LIVE-ACP-SPAWN-OK`。 - 4. 验证 `accepted=yes`、存在真实的 `childSessionKey`，且没有验证器错误。 + 1. 验证目标主机上已部署的 Gateway 网关版本和提交。 + 2. 打开一个临时 ACPX 桥接会话，连接到一个在线智能体。 + 3. 要求该智能体调用 `sessions_spawn`，并设置 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务内容为 `Reply with exactly LIVE-ACP-SPAWN-OK`。 + 4. 验证 `accepted=yes`、存在真实的 `childSessionKey`，并且没有校验器错误。 5. 清理该临时桥接会话。 - 请将关卡保持在 `mode: "run"`，并跳过 `streamTo: "parent"`—— - 线程绑定的 `mode: "session"` 和流式中继路径属于另外的、 - 更丰富的集成验证阶段。 + 将门槛保持在 `mode: "run"`，并跳过 `streamTo: "parent"`—— + 线程绑定的 `mode: "session"` 和流中继路径属于单独的、 + 更丰富的集成验证流程。 ## 沙箱兼容性 -ACP 会话目前运行在主机运行时上，**不在** -OpenClaw 沙箱内部。 +ACP 会话当前运行在主机运行时上，**不会**在 +OpenClaw 沙箱中运行。 **安全边界：** - 外部 harness 可以根据其自身 CLI 权限和所选 `cwd` 进行读写。 -- OpenClaw 的沙箱策略**不会**包裹 ACP harness 执行。 -- OpenClaw 仍会强制执行 ACP 功能门控、允许的智能体、会话所有权、渠道绑定和 Gateway 网关投递策略。 -- 对于需要强制沙箱隔离的 OpenClaw 原生工作，请使用 `runtime: "subagent"`。 +- OpenClaw 的沙箱策略**不会**包装 ACP harness 执行。 +- OpenClaw 仍会强制执行 ACP 功能门禁、允许的智能体、会话所有权、渠道绑定以及 Gateway 网关交付策略。 +- 对于受沙箱强制约束的 OpenClaw 原生工作，请使用 `runtime: "subagent"`。 当前限制： -- 如果请求方会话已被沙箱隔离，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 启动都会被阻止。 -- `sessions_spawn` 配合 `runtime: "acp"` 不支持 `sandbox: "require"`。 +- 如果请求方会话处于沙箱隔离状态，ACP 启动会被阻止，这同时适用于 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn`。 +- 带 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。 ## 会话目标解析 -大多数 `/acp` 操作都接受一个可选的会话目标（`session-key`、 +大多数 `/acp` 操作都接受一个可选会话目标（`session-key`、 `session-id` 或 `session-label`）。 **解析顺序：** 1. 显式目标参数（或 `/acp steer` 的 `--session`） - 先尝试 key - - 然后尝试 UUID 形态的 session id - - 再尝试 label -2. 当前线程绑定（如果当前会话/线程已绑定到某个 ACP 会话）。 -3. 当前请求方会话回退值。 + - 再尝试 UUID 形状的 session id + - 然后尝试 label +2. 当前线程绑定（如果此会话/线程已绑定到某个 ACP 会话）。 +3. 当前请求方会话回退。 当前会话绑定和线程绑定都会参与 -第 2 步。 +步骤 2。 -如果无法解析出目标，OpenClaw 会返回明确错误 +如果无法解析任何目标，OpenClaw 会返回清晰错误 （`Unable to resolve session target: ...`）。 ## ACP 控制 | 命令 | 作用 | 示例 | | -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | -| `/acp spawn` | 创建 ACP 会话；可选当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` | +| `/acp spawn` | 创建 ACP 会话；可选当前会话绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` | | `/acp cancel` | 取消目标会话中正在进行的轮次。 | `/acp cancel agent:codex:acp:` | -| `/acp steer` | 向正在运行的会话发送引导指令。 | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | 关闭会话并解除线程目标绑定。 | `/acp close` | -| `/acp status` | 显示后端、模式、状态、运行时选项、能力。 | `/acp status` | +| `/acp 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` | 通用运行时配置选项写入。 | `/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` 会读取当前绑定或请求方会话的 +后端级别的会话标识符。当某个后端缺少某项能力时，不支持控制的错误会清晰显示。`/acp sessions` 会为当前已绑定或请求方会话读取 存储；目标令牌 （`session-key`、`session-id` 或 `session-label`）会通过 -Gateway 网关会话发现进行解析，其中包括自定义的按智能体划分的 `session.store` +Gateway 网关会话发现机制解析，包括自定义的每智能体 `session.store` 根目录。 ### 运行时选项映射 @@ -775,18 +778,18 @@ Gateway 网关会话发现进行解析，其中包括自定义的按智能体划 | 命令 | 映射到 | 说明 | | ---------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `/acp model ` | 运行时配置键 `model` | 对于 Codex ACP，OpenClaw 会将 `openai-codex/` 标准化为适配器模型 id，并将斜杠推理后缀（例如 `openai-codex/gpt-5.4/high`）映射为 `reasoning_effort`。 | -| `/acp set thinking ` | 运行时配置键 `thinking` | 对于 Codex ACP，在适配器支持时，OpenClaw 会发送相应的 `reasoning_effort`。 | +| `/acp model ` | 运行时配置键 `model` | 对于 Codex ACP，OpenClaw 会将 `openai-codex/` 规范化为适配器模型 id，并将斜杠推理后缀（例如 `openai-codex/gpt-5.4/high`）映射为 `reasoning_effort`。 | +| `/acp set thinking ` | 运行时配置键 `thinking` | 对于 Codex ACP，在适配器支持时，OpenClaw 会发送对应的 `reasoning_effort`。 | | `/acp permissions ` | 运行时配置键 `approval_policy` | — | | `/acp timeout ` | 运行时配置键 `timeout` | — | -| `/acp cwd ` | 运行时 `cwd` 覆盖值 | 直接更新。 | +| `/acp cwd ` | 运行时 `cwd` 覆盖 | 直接更新。 | | `/acp set ` | 通用 | `key=cwd` 使用 `cwd` 覆盖路径。 | -| `/acp reset-options` | 清除所有运行时覆盖值 | — | +| `/acp reset-options` | 清除所有运行时覆盖 | — | ## acpx harness、插件设置和权限 -有关 acpx harness 配置（Claude Code / Codex / Gemini CLI -别名）、插件工具和 OpenClaw 工具的 MCP 桥接，以及 ACP +关于 acpx harness 配置（Claude Code / Codex / Gemini CLI +别名）、plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP 权限模式，请参见 [ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)。 @@ -794,34 +797,34 @@ Gateway 网关会话发现进行解析，其中包括自定义的按智能体划 | 症状 | 可能原因 | 修复方法 | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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`。 | -| `ACP agent "" is not allowed by policy` | 智能体不在允许列表中。 | 使用被允许的 `agentId`，或更新 `acp.allowedAgents`。 | -| `/acp doctor` 在启动后立刻报告后端未就绪 | 插件依赖探测或自修复仍在运行。 | 稍等片刻后重新运行 `/acp doctor`；如果仍不健康，请检查后端安装错误以及插件允许/拒绝策略。 | -| 找不到 harness 命令 | 适配器 CLI 未安装，或首次运行的 `npx` 拉取失败。 | 在 Gateway 网关主机上安装/预热适配器，或显式配置 acpx 智能体命令。 | -| harness 返回找不到模型 | 该模型 id 对另一个 provider/harness 有效，但不适用于当前 ACP 目标。 | 使用该 harness 列出的模型、在 harness 中配置该模型，或省略该覆盖值。 | -| harness 返回供应商认证错误 | OpenClaw 本身正常，但目标 CLI/provider 未登录。 | 在 Gateway 网关主机环境中登录或提供所需的 provider 密钥。 | -| `Unable to resolve session target: ...` | key/id/label 令牌错误。 | 运行 `/acp sessions`，复制准确的 key/label 后重试。 | -| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动且可绑定会话的情况下使用了 `--bind here`。 | 移动到目标聊天/频道后重试，或使用不绑定的启动方式。 | -| `Conversation bindings are unavailable for .` | 适配器缺少当前会话 ACP 绑定能力。 | 在支持时使用 `/acp spawn ... --thread ...`、配置顶层 `bindings[]`，或切换到受支持的渠道。 | +| `ACP runtime backend is not configured` | 后端插件缺失、被禁用，或被 `plugins.allow` 阻止。 | 安装并启用后端插件；如果设置了 `plugins.allow` allowlist，请将 `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 "" is not allowed by policy` | 智能体不在 allowlist 中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 | +| 启动后立刻运行 `/acp doctor` 报告后端未就绪 | 插件依赖探测或自修复仍在运行。 | 稍等片刻后重新运行 `/acp doctor`；如果仍然不健康，请检查后端安装错误以及插件 allow/deny 策略。 | +| 找不到 harness 命令 | 适配器 CLI 未安装，或首次运行时的 `npx` 拉取失败。 | 在 Gateway 网关主机上安装/预热该适配器，或显式配置 acpx 智能体命令。 | +| harness 报告找不到模型 | 该模型 id 对其他提供商/harness 有效，但对当前 ACP 目标无效。 | 使用该 harness 列出的模型，在 harness 中配置该模型，或省略该覆盖项。 | +| harness 返回提供商认证错误 | OpenClaw 本身健康，但目标 CLI/提供商未登录。 | 在 Gateway 网关主机环境中登录，或提供所需的提供商密钥。 | +| `Unable to resolve session target: ...` | key/id/label 令牌错误。 | 运行 `/acp sessions`，复制准确的 key/label，然后重试。 | +| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动且可绑定会话的情况下使用了 `--bind here`。 | 移动到目标聊天/渠道后重试，或使用不绑定的启动方式。 | +| `Conversation bindings are unavailable for .` | 适配器缺少当前会话 ACP 绑定能力。 | 在支持时使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或切换到受支持的渠道。 | | `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 | -| `Only can rebind this channel/conversation/thread.` | 当前绑定目标归另一位用户所有。 | 由所有者重新绑定，或使用不同的会话或线程。 | +| `Only can rebind this channel/conversation/thread.` | 当前绑定目标属于其他用户。 | 由所有者重新绑定，或使用其他会话或线程。 | | `Thread bindings are unavailable for .` | 适配器缺少线程绑定能力。 | 使用 `--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 有自己的启动标志，则直接在其中配置模型。 | -| 已绑定会话缺少 ACP 元数据 | ACP 会话元数据已过期或被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止了写入/exec。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见[权限配置](/zh-CN/tools/acp-agents-setup#permission-configuration)。 | -| ACP 会话很早失败且几乎没有输出 | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。若要授予完整权限，设置 `permissionMode=approve-all`；若要优雅降级，设置 `nonInteractivePermissions=deny`。 | -| ACP 会话在完成工作后无限期卡住 | harness 进程已结束，但 ACP 会话没有报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动杀掉过期进程。 | -| harness 看到了 `<<>>` | 内部事件信封泄露到了 ACP 边界之外。 | 更新 OpenClaw 并重新运行完成流程；外部 harness 应只接收普通完成提示。 | +| `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 有自己的启动标志，则直接在其中配置模型。 | +| 已绑定会话缺少 ACP 元数据 | 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 会话很早失败且输出很少 | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完全权限，设置 `permissionMode=approve-all`；如需优雅降级，设置 `nonInteractivePermissions=deny`。 | +| ACP 会话在完成工作后无限期卡住 | harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动杀掉陈旧进程。 | +| harness 看到了 `<<>>` | 内部事件 envelope 泄漏到了 ACP 边界之外。 | 更新 OpenClaw 并重新运行 completion 流程；外部 harness 应只接收纯 completion 提示。 | ## 相关内容 - [ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup) - [智能体发送](/zh-CN/tools/agent-send) -- [CLI Backends](/zh-CN/gateway/cli-backends) +- [CLI 后端](/zh-CN/gateway/cli-backends) - [Codex harness](/zh-CN/plugins/codex-harness) - [多智能体沙箱工具](/zh-CN/tools/multi-agent-sandbox-tools) - [`openclaw acp`（桥接模式）](/zh-CN/cli/acp) diff --git a/docs/zh-CN/tools/subagents.md b/docs/zh-CN/tools/subagents.md index 05e04aec0..88eb0a38d 100644 --- a/docs/zh-CN/tools/subagents.md +++ b/docs/zh-CN/tools/subagents.md @@ -1,37 +1,37 @@ --- read_when: - - 你希望通过智能体进行后台或并行工作 + - 你想通过智能体进行后台或并行工作 - 你正在更改 `sessions_spawn` 或子智能体工具策略 - - 你正在实现或排查与线程绑定的子智能体会话 + - 你正在实现或排查线程绑定的子智能体会话 sidebarTitle: Sub-agents -summary: 启动隔离的后台智能体运行，并将结果回报到请求者聊天中 +summary: 启动隔离的后台智能体运行，并将结果回传到请求者聊天中 title: 子智能体 x-i18n: - generated_at: "2026-04-27T06:15:55Z" + generated_at: "2026-04-27T13:49:03Z" model: gpt-5.4 provider: openai - source_hash: eb320f4b2bd2b4d0462344a4b1ce119855beab84e3dc0922c36db5b496f86285 + source_hash: 20a23dc45659647062725e6959247299546ebf1027525dc21587012cd7f23e1f source_path: tools/subagents.md workflow: 15 --- -子智能体是从现有智能体运行中派生出的后台智能体运行。 -它们在自己的会话（`agent::subagent:`）中运行，并且在完成后，**announce** 它们的结果回到请求者聊天渠道。每次子智能体运行都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。 +子智能体是从现有智能体运行中派生出来的后台智能体运行。 +它们在各自独立的会话中运行（`agent::subagent:`），并且在完成后，会将结果**通知**回请求者聊天渠道。每个子智能体运行都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。 主要目标： -- 并行处理“研究 / 长任务 / 慢工具”类工作，而不阻塞主运行。 -- 默认保持子智能体隔离（会话分离 + 可选的沙箱隔离）。 -- 让工具暴露面不易被误用：默认情况下，子智能体**不会**获得会话工具。 +- 在不阻塞主运行的情况下，并行处理“研究 / 长任务 / 慢工具”类工作。 +- 默认保持子智能体隔离（会话分离 + 可选沙箱隔离）。 +- 让工具使用面尽量不易被误用：子智能体默认**不会**获得会话工具。 - 支持可配置的嵌套深度，以适配编排器模式。 -**成本说明：** 默认情况下，每个子智能体都有自己的上下文和 token 使用量。对于高负载或重复性任务，请为子智能体设置更便宜的模型，并让主智能体继续使用更高质量的模型。可通过 `agents.defaults.subagents.model` 或按智能体覆盖进行配置。当子智能体确实需要请求者当前的对话记录时，智能体可以在那一次派生中请求 `context: "fork"`。 +**成本说明：** 默认情况下，每个子智能体都有自己的上下文和 token 使用量。对于高负载或重复性任务，建议为子智能体设置更便宜的模型，同时让主智能体继续使用质量更高的模型。可通过 `agents.defaults.subagents.model` 或按智能体覆盖来配置。若子智能体确实需要请求者当前的对话记录，智能体可以在该次派生时请求 `context: "fork"`。 ## 斜杠命令 -使用 `/subagents` 检查或控制**当前会话**的子智能体运行： +使用 `/subagents` 查看或控制**当前会话**的子智能体运行： ```text /subagents list @@ -43,11 +43,12 @@ x-i18n: /subagents spawn [--model ] [--thinking ] ``` -`/subagents info` 会显示运行元数据（状态、时间戳、会话 id、转录路径、清理设置）。使用 `sessions_history` 可获得有边界且经过安全过滤的回顾视图；当你需要原始完整转录时，请检查磁盘上的转录路径。 +`/subagents info` 会显示运行元数据（状态、时间戳、会话 id、转录路径、清理情况）。使用 `sessions_history` 获取有边界且经过安全过滤的回溯视图；当你需要原始完整转录时，请检查磁盘上的转录路径。 ### 线程绑定控制 -这些命令适用于支持持久线程绑定的渠道。请参见下方的[支持线程的渠道](#thread-supporting-channels)。 +这些命令适用于支持持久线程绑定的渠道。 +请参阅下方的[支持线程的渠道](#thread-supporting-channels)。 ```text /focus @@ -59,59 +60,61 @@ x-i18n: ### 派生行为 -`/subagents spawn` 会以用户命令（而不是内部中继）的形式启动后台子智能体，并在运行结束时向请求者聊天发送一条最终完成更新。 +`/subagents spawn` 会以用户命令（而非内部中继）的方式启动一个后台子智能体，并在运行完成后，将一条最终完成更新发送回请求者聊天。 - + - 派生命令是非阻塞的；它会立即返回一个运行 id。 - - 完成后，子智能体会将摘要/结果消息 announce 回请求者聊天渠道。 - - 完成采用推送方式。一旦派生完成，**不要**只是为了等待它结束而循环轮询 `/subagents list`、`sessions_list` 或 `sessions_history`；仅在调试或干预时按需检查状态。 - - 完成时，OpenClaw 会尽最大努力关闭该子智能体会话打开的已跟踪浏览器标签页/进程，然后 announce 清理流程才会继续。 + - 完成后，子智能体会将摘要/结果消息通知回请求者聊天渠道。 + - 完成通知是基于推送的。一旦派生完成，**不要**仅为了等待其结束而循环轮询 `/subagents list`、`sessions_list` 或 `sessions_history`；仅在调试或干预时按需查看状态。 + - 完成时，OpenClaw 会尽最大努力关闭该子智能体会话所打开并被跟踪的浏览器标签页/进程，然后再继续执行通知清理流程。 - - - OpenClaw 会先尝试使用稳定的幂等键进行直接 `agent` 交付。 - - 如果直接交付失败，则回退到队列路由。 - - 如果队列路由仍不可用，announce 会以较短的指数退避方式重试，直到最终放弃。 - - 完成交付会保留已解析的请求者路由：如果可用，线程绑定或对话绑定的完成路由优先；如果完成来源只提供渠道，OpenClaw 会从请求者会话的已解析路由（`lastChannel` / `lastTo` / `lastAccountId`）中补全缺失的目标/账号，以便直接交付仍然可用。 + + - OpenClaw 会先使用稳定的幂等键尝试直接 `agent` 投递。 + - 若直接投递失败，则回退到队列路由。 + - 若队列路由仍不可用，则会在最终放弃前，使用短周期指数退避重试通知。 + - 完成交付会保留已解析的请求者路由：若可用，线程绑定或会话绑定的完成路由优先生效；如果完成来源仅提供渠道，OpenClaw 会从请求者会话的已解析路由（`lastChannel` / `lastTo` / `lastAccountId`）中补齐缺失的 target/account，从而仍可进行直接投递。 - 发送回请求者会话的完成交接内容是运行时生成的内部上下文（不是用户编写的文本），其中包括： + 交回请求者会话的完成交接数据是运行时生成的内部上下文（不是用户编写的文本），其中包括： - - `Result` — 最新可见的 `assistant` 回复文本；否则为已清理的最新 tool/toolResult 文本。终态失败运行不会复用已捕获的回复文本。 - - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`。 - - 精简的运行时/token 统计信息。 - - 一条交付说明，告知请求者智能体用普通助手语气重写，而不是转发原始内部元数据。 + - `Result` —— 最新可见的 `assistant` 回复文本；若没有，则使用经过清理的最新 `tool`/`toolResult` 文本。终态失败的运行不会复用已捕获的回复文本。 + - `Status` —— `completed successfully` / `failed` / `timed out` / `unknown`。 + - 紧凑的运行时/token 统计信息。 + - 一条交付指令，告诉请求者智能体要用正常的助手口吻重写，而不是转发原始内部元数据。 - `--model` 和 `--thinking` 会覆盖该次运行的默认值。 - - 使用 `info`/`log` 可在完成后检查详细信息和输出。 - - `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久的线程绑定会话，请使用 `sessions_spawn` 并设置 `thread: true` 和 `mode: "session"`。 - - 对于 ACP harness 会话（Claude Code、Gemini CLI、OpenCode 或显式的 Codex ACP/acpx），当工具声明该运行时时，请使用 `sessions_spawn` 并设置 `runtime: "acp"`。调试完成或智能体到智能体循环时，请参见 [ACP 交付模型](/zh-CN/tools/acp-agents#delivery-model)。当启用 `codex` 插件时，除非用户明确要求 ACP/acpx，否则 Codex 聊天/线程控制应优先使用 `/codex ...` 而不是 ACP。 - - 只有在 ACP 已启用、请求者未处于沙箱隔离中，并且已加载诸如 `acpx` 之类的后端插件时，OpenClaw 才会显示 `runtime: "acp"`。`runtime: "acp"` 需要一个外部 ACP harness id，或一个带有 `runtime.type="acp"` 的 `agents.list[]` 条目；对于 `agents_list` 中普通 OpenClaw 配置的智能体，请使用默认子智能体运行时。 + - 使用 `info`/`log` 可在完成后查看详细信息和输出。 + - `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久的线程绑定会话，请使用 `sessions_spawn`，并设置 `thread: true` 和 `mode: "session"`。 + - 对于 ACP harness 会话（Claude Code、Gemini CLI、OpenCode，或显式的 Codex ACP/acpx），当工具声明该运行时时，请使用 `sessions_spawn` 并设置 `runtime: "acp"`。在调试完成通知或智能体间循环时，请参阅 [ACP 交付模型](/zh-CN/tools/acp-agents#delivery-model)。当启用 `codex` 插件时，Codex 聊天/线程控制应优先使用 `/codex ...`，除非用户明确要求 ACP/acpx。 + - 只有在 ACP 已启用、请求者未处于沙箱中，且已加载 `acpx` 这类后端插件时，OpenClaw 才会显示 `runtime: "acp"`。`runtime: "acp"` 需要一个外部 ACP harness id，或一个带有 `runtime.type="acp"` 的 `agents.list[]` 条目；对于来自 `agents_list` 的普通 OpenClaw 配置智能体，请使用默认的子智能体运行时。 ## 上下文模式 -原生子智能体默认以隔离方式启动，除非调用方明确要求分叉当前转录。 +原生子智能体默认以隔离方式启动，除非调用方明确要求 fork 当前对话记录。 -| 模式 | 何时使用 | 行为 | -| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------- | -| `isolated` | 全新的研究、独立实现、慢工具工作，或任何可以在任务文本中简要说明的内容 | 创建一个干净的子转录。这是默认模式，并能将 token 使用量保持更低。 | -| `fork` | 工作依赖当前对话、先前的工具结果，或请求者转录中已有的细致说明时 | 在子智能体启动前，将请求者转录分支到子会话中。 | +| 模式 | 适用场景 | 行为 | +| ---------- | -------- | ---- | +| `isolated` | 全新研究、独立实现、慢工具工作，或任何可以通过任务文本简要说明的工作 | 创建一个干净的子级转录。这是默认值，并且能将 token 使用量保持得更低。 | +| `fork` | 工作依赖当前对话、先前工具结果，或请求者转录中已有的细致指令 | 在子级启动前，将请求者转录分支到子会话中。 | -请谨慎使用 `fork`。它适用于对上下文敏感的委派，而不是替代清晰任务提示的方式。 +请谨慎使用 `fork`。它用于对上下文敏感的委派，而不是替代清晰的任务提示编写。 ## 工具：`sessions_spawn` -在全局 `subagent` 通道上以 `deliver: false` 启动一个子智能体运行，然后执行 announce 步骤，并将 announce 回复发送到请求者聊天渠道。 +在全局 `subagent` 通道上以 `deliver: false` 启动一个子智能体运行，然后执行通知步骤，并将通知回复发布到请求者聊天渠道。 + +其可用性取决于调用方的有效工具策略。`coding` 和 `full` 配置文件默认暴露 `sessions_spawn`。`messaging` 配置文件则不会；请添加 `tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]`，或者为需要委派工作的智能体使用 `tools.profile: "coding"`。渠道/分组、提供商、沙箱隔离以及按智能体设置的允许/拒绝策略，仍然可以在配置文件阶段之后移除此工具。可在同一会话中使用 `/tools` 来确认实际生效的工具列表。 **默认值：** -- **模型：** 继承调用方，除非你设置了 `agents.defaults.subagents.model`（或按智能体设置 `agents.list[].subagents.model`）；显式的 `sessions_spawn.model` 仍然优先。 -- **Thinking：** 继承调用方，除非你设置了 `agents.defaults.subagents.thinking`（或按智能体设置 `agents.list[].subagents.thinking`）；显式的 `sessions_spawn.thinking` 仍然优先。 -- **运行超时：** 如果省略 `sessions_spawn.runTimeoutSeconds`，OpenClaw 会在已设置时使用 `agents.defaults.subagents.runTimeoutSeconds`；否则回退到 `0`（无超时）。 +- **模型：** 继承调用方，除非你设置了 `agents.defaults.subagents.model`（或按智能体设置 `agents.list[].subagents.model`）；显式设置的 `sessions_spawn.model` 仍然优先生效。 +- **Thinking：** 继承调用方，除非你设置了 `agents.defaults.subagents.thinking`（或按智能体设置 `agents.list[].subagents.thinking`）；显式设置的 `sessions_spawn.thinking` 仍然优先生效。 +- **运行超时：** 如果省略 `sessions_spawn.runTimeoutSeconds`，OpenClaw 会在已设置时使用 `agents.defaults.subagents.runTimeoutSeconds`；否则回退为 `0`（无超时）。 ### 工具参数 @@ -122,19 +125,19 @@ x-i18n: 可选的人类可读标签。 - 当 `subagents.allowAgents` 允许时，在另一个智能体 id 下派生。 + 当 `subagents.allowAgents` 允许时，可在另一个智能体 id 下派生。 - `acp` 仅用于外部 ACP harness（`claude`、`droid`、`gemini`、`opencode`，或显式请求的 Codex ACP/acpx），以及 `agents.list[]` 中 `runtime.type` 为 `acp` 的条目。 + `acp` 仅用于外部 ACP harness（`claude`、`droid`、`gemini`、`opencode`，或显式请求的 Codex ACP/acpx），以及那些 `runtime.type` 为 `acp` 的 `agents.list[]` 条目。 - 仅 ACP 使用。当 `runtime: "acp"` 时恢复现有 ACP harness 会话；对于原生子智能体派生会被忽略。 + 仅限 ACP。当 `runtime: "acp"` 时恢复一个现有 ACP harness 会话；对于原生子智能体派生会忽略。 - 仅 ACP 使用。当 `runtime: "acp"` 时将 ACP 运行输出流式传输到父会话；对于原生子智能体派生请省略。 + 仅限 ACP。当 `runtime: "acp"` 时，将 ACP 运行输出流式传输到父会话；对于原生子智能体派生请省略。 - 覆盖子智能体模型。无效值会被跳过，子智能体将使用默认模型运行，并在工具结果中给出警告。 + 覆盖子智能体模型。无效值会被跳过，子智能体将使用默认模型运行，并在工具结果中附带警告。 覆盖子智能体运行的 thinking 级别。 @@ -143,47 +146,51 @@ x-i18n: 默认在已设置时使用 `agents.defaults.subagents.runTimeoutSeconds`，否则为 `0`。设置后，子智能体运行会在 N 秒后中止。 - 当为 `true` 时，请求为该子智能体会话启用渠道线程绑定。 + 当为 `true` 时，会为该子智能体会话请求渠道线程绑定。 - 如果 `thread: true` 且省略 `mode`，默认会变为 `session`。`mode: "session"` 需要 `thread: true`。 + 如果 `thread: true` 且省略 `mode`，默认值会变为 `session`。`mode: "session"` 需要 `thread: true`。 - `"delete"` 会在 announce 后立即归档（仍会通过重命名保留转录）。 + `"delete"` 会在通知后立即归档（仍会通过重命名保留转录）。 - `require` 会在目标子运行时未处于沙箱隔离时拒绝派生。 + `require` 会在目标子级运行时未启用沙箱隔离时拒绝派生。 - `fork` 会将请求者当前转录分支到子会话。仅适用于原生子智能体。仅当子智能体需要当前转录时才使用 `fork`。 + `fork` 会将请求者当前转录分支到子会话中。仅适用于原生子智能体。只有在子级需要当前转录时才应使用 `fork`。 -`sessions_spawn` **不**接受渠道交付参数（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。如需交付，请从派生出的运行中使用 `message`/`sessions_send`。 +`sessions_spawn` **不**接受渠道交付参数（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。如需交付，请从派生运行中使用 `message`/`sessions_send`。 ## 线程绑定会话 -当某个渠道启用线程绑定时，子智能体可以保持绑定到某个线程，因此该线程中的后续用户消息会持续路由到同一个子智能体会话。 +当某个渠道启用了线程绑定时，子智能体可以持续绑定到一个线程，这样该线程中的后续用户消息就会持续路由到同一个子智能体会话。 ### 支持线程的渠道 -**Discord** 目前是唯一受支持的渠道。它支持持久的线程绑定子智能体会话（`sessions_spawn` 配合 `thread: true`）、手动线程控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及适配器键 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSubagentSessions`。 +目前只有 **Discord** 支持。它支持持久的线程绑定子智能体会话（`sessions_spawn` 配合 `thread: true`）、手动线程控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及适配器键 +`channels.discord.threadBindings.enabled`、 +`channels.discord.threadBindings.idleHours`、 +`channels.discord.threadBindings.maxAgeHours` 和 +`channels.discord.threadBindings.spawnSubagentSessions`。 ### 快速流程 - 使用 `sessions_spawn` 并设置 `thread: true`（以及可选的 `mode: "session"`）。 + 使用 `sessions_spawn` 并设置 `thread: true`（可选再加上 `mode: "session"`）。 - OpenClaw 会在当前渠道中创建一个线程，或将线程绑定到该会话目标。 + OpenClaw 会在当前渠道中创建一个线程，或将某个线程绑定到该会话目标。 - 该线程中的回复和后续消息会被路由到已绑定的会话。 + 该线程中的回复和后续消息会被路由到绑定的会话。 - 使用 `/session idle` 检查/更新非活动自动取消聚焦，并使用 `/session max-age` 控制硬性上限。 + 使用 `/session idle` 查看/更新非活动自动取消聚焦设置，并使用 `/session max-age` 控制硬性时长上限。 使用 `/unfocus` 手动解除绑定。 @@ -192,52 +199,52 @@ x-i18n: ### 手动控制 -| 命令 | 效果 | -| ------------------ | ----------------------------------------- | -| `/focus ` | 将当前线程（或创建一个线程）绑定到某个子智能体/会话目标 | -| `/unfocus` | 移除当前已绑定线程的绑定 | +| 命令 | 效果 | +| ------------------ | --------------------------------------------------------------------- | +| `/focus ` | 将当前线程绑定到某个子智能体/会话目标（或创建一个线程） | +| `/unfocus` | 移除当前已绑定线程的绑定 | | `/agents` | 列出活动运行和绑定状态（`thread:` 或 `unbound`） | -| `/session idle` | 检查/更新空闲自动取消聚焦（仅适用于已聚焦的绑定线程） | -| `/session max-age` | 检查/更新硬性上限（仅适用于已聚焦的绑定线程） | +| `/session idle` | 查看/更新空闲自动取消聚焦设置（仅适用于已聚焦的绑定线程） | +| `/session max-age` | 查看/更新硬性时长上限（仅适用于已聚焦的绑定线程） | ### 配置开关 - **全局默认值：** `session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 -- **渠道覆盖和派生自动绑定键** 为适配器特定。请参见上方的[支持线程的渠道](#thread-supporting-channels)。 +- **渠道覆盖和派生自动绑定键** 为适配器专属。请参阅上方的[支持线程的渠道](#thread-supporting-channels)。 -当前适配器详情请参见[配置参考](/zh-CN/gateway/configuration-reference)和[斜杠命令](/zh-CN/tools/slash-commands)。 +当前适配器的详细信息请参阅[配置参考](/zh-CN/gateway/configuration-reference)和[斜杠命令](/zh-CN/tools/slash-commands)。 -### 允许列表 +### Allowlist - 可通过 `agentId` 指定的智能体 id 列表（`["*"]` 表示允许任意）。默认值：仅请求者智能体。 + 可通过 `agentId` 定位的智能体 id 列表（`["*"]` 表示允许任意智能体）。默认值：仅请求者智能体。 - 当请求者智能体未设置自己的 `subagents.allowAgents` 时使用的默认目标智能体允许列表。 + 当请求者智能体未设置自己的 `subagents.allowAgents` 时，使用的默认目标智能体 Allowlist。 - 阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置档案）。按智能体覆盖：`agents.list[].subagents.requireAgentId`。 + 阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置）。按智能体覆盖：`agents.list[].subagents.requireAgentId`。 -如果请求者会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些会在非沙箱环境中运行的目标。 +如果请求者会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将在非沙箱环境下运行的目标。 ### 发现 -使用 `agents_list` 查看当前哪些智能体 id 允许用于 `sessions_spawn`。响应中包含每个列出智能体的生效模型和嵌入式运行时元数据，因此调用方可以区分 PI、Codex app-server 以及其他已配置的原生运行时。 +使用 `agents_list` 查看当前哪些智能体 id 被允许用于 `sessions_spawn`。响应中包含每个列出智能体的有效模型和嵌入式运行时元数据，以便调用方区分 PI、Codex app-server 以及其他已配置的原生运行时。 ### 自动归档 -- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes`（默认 `60`）后自动归档。 -- 归档使用 `sessions.delete`，并将转录重命名为 `*.deleted.`（同一文件夹）。 -- `cleanup: "delete"` 会在 announce 后立即归档（仍会通过重命名保留转录）。 -- 自动归档是尽力而为；如果 Gateway 网关重启，待处理的定时器会丢失。 -- `runTimeoutSeconds` **不会**自动归档；它只会停止运行。会话会保留直到自动归档执行。 +- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes`（默认 `60`）之后自动归档。 +- 归档使用 `sessions.delete`，并将转录重命名为 `*.deleted.`（同一文件夹内）。 +- `cleanup: "delete"` 会在通知后立即归档（仍通过重命名保留转录）。 +- 自动归档采用尽力而为策略；如果 Gateway 网关重启，待处理定时器会丢失。 +- `runTimeoutSeconds` **不会**触发自动归档；它只会停止运行。会话会保留，直到自动归档执行。 - 自动归档同样适用于深度 1 和深度 2 的会话。 -- 浏览器清理与归档清理是分开的：当运行结束时，即使保留转录/会话记录，也会尽力关闭该会话跟踪到的浏览器标签页/进程。 +- 浏览器清理与归档清理分开：即使保留转录/会话记录，在运行完成时，已跟踪的浏览器标签页/进程也会尽力关闭。 ## 嵌套子智能体 -默认情况下，子智能体不能再派生自己的子智能体（`maxSpawnDepth: 1`）。将 `maxSpawnDepth: 2` 设为启用一层嵌套——**编排器模式**：主智能体 → 编排器子智能体 → 工作子子智能体。 +默认情况下，子智能体不能再派生自己的子智能体（`maxSpawnDepth: 1`）。设置 `maxSpawnDepth: 2` 可启用一层嵌套——即**编排器模式**：主智能体 → 编排子智能体 → 工作子子智能体。 ```json5 { @@ -245,9 +252,9 @@ x-i18n: defaults: { subagents: { maxSpawnDepth: 2, // 允许子智能体派生子级（默认：1） - maxChildrenPerAgent: 5, // 每个智能体会话的最大活动子级数（默认：5） + maxChildrenPerAgent: 5, // 每个智能体会话最多活动子级数量（默认：5） maxConcurrent: 8, // 全局并发通道上限（默认：8） - runTimeoutSeconds: 900, // sessions_spawn 在省略时的默认超时（0 = 无超时） + runTimeoutSeconds: 900, // 省略时 sessions_spawn 的默认超时（0 = 无超时） }, }, }, @@ -256,112 +263,112 @@ x-i18n: ### 深度级别 -| 深度 | 会话键形态 | 角色 | 可以派生？ | -| ---- | ------------------------------------------ | --------------------------------------------- | --------------------------- | -| 0 | `agent::main` | 主智能体 | 始终可以 | -| 1 | `agent::subagent:` | 子智能体（在允许深度 2 时为编排器） | 仅当 `maxSpawnDepth >= 2` 时 | -| 2 | `agent::subagent::subagent:` | 子子智能体（叶子工作节点） | 永不 | +| 深度 | 会话键形态 | 角色 | 可以派生？ | +| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | +| 0 | `agent::main` | 主智能体 | 始终可以 | +| 1 | `agent::subagent:` | 子智能体（当允许深度 2 时可作为编排器） | 仅当 `maxSpawnDepth >= 2` | +| 2 | `agent::subagent::subagent:` | 子子智能体（叶子工作节点） | 永不允许 | -### announce 链 +### 通知链 -结果会沿链路向上回传： +结果会沿链路向上返回： -1. 深度 2 工作节点完成 → announce 给其父级（深度 1 编排器）。 -2. 深度 1 编排器收到 announce，汇总结果，完成后 → announce 给主智能体。 -3. 主智能体收到 announce 并交付给用户。 +1. 深度 2 的工作节点完成 → 通知其父级（深度 1 编排器）。 +2. 深度 1 编排器收到通知，综合结果并完成 → 通知主智能体。 +3. 主智能体收到通知并交付给用户。 -每一层只能看到其直接子级的 announce。 +每一层只会看到其直接子级发来的通知。 -**操作建议：** 只启动一次子级工作并等待完成事件，不要围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` sleep 命令构建轮询循环。`sessions_list` 和 `/subagents list` 会让子会话关系聚焦于活跃工作——活跃子级保持附着，已结束子级会在一个较短的最近窗口内保持可见，而仅存于存储中的陈旧子级链接在其新鲜度窗口过后会被忽略。这样可防止旧的 `spawnedBy` / `parentSessionKey` 元数据在重启后复活“幽灵子级”。如果某个子级完成事件在你已经发送最终答案之后才到达，正确的后续处理是精确的静默 token `NO_REPLY` / `no_reply`。 +**操作指引：** 启动子级工作一次后，等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` sleep 命令构建轮询循环。`sessions_list` 和 `/subagents list` 会将子会话关系聚焦在实时工作上——活动子级保持附着，已结束子级在短暂的最近窗口内仍然可见，而仅存在于存储中的陈旧子级链接会在其新鲜度窗口后被忽略。这可以防止旧的 `spawnedBy` / `parentSessionKey` 元数据在重启后重新唤起幽灵子级。如果某个子级完成事件在你已经发送最终回答之后才到达，正确的后续操作是精确的静默 token `NO_REPLY` / `no_reply`。 ### 按深度划分的工具策略 -- 角色和控制范围会在派生时写入会话元数据。这样可防止扁平化或恢复后的会话键意外重新获得编排器权限。 +- 角色和控制范围会在派生时写入会话元数据。这样可以避免扁平化或恢复后的会话键意外重新获得编排器权限。 - **深度 1（编排器，当 `maxSpawnDepth >= 2` 时）：** 获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子级。其他会话/系统工具仍然被拒绝。 - **深度 1（叶子节点，当 `maxSpawnDepth == 1` 时）：** 没有会话工具（当前默认行为）。 -- **深度 2（叶子工作节点）：** 没有会话工具——在深度 2 下，`sessions_spawn` 始终被拒绝。不能继续派生子级。 +- **深度 2（叶子工作节点）：** 没有会话工具——在深度 2 时始终拒绝 `sessions_spawn`。不能继续派生更深层子级。 -### 每个智能体的派生上限 +### 按智能体划分的派生数量限制 -每个智能体会话（任意深度）同一时间最多只能有 `maxChildrenPerAgent`（默认 `5`）个活动子级。这可防止单个编排器失控式扇出。 +每个智能体会话（任意深度）同时最多只能有 `maxChildrenPerAgent` 个活动子级（默认 `5`）。这可防止单个编排器失控式扇出。 ### 级联停止 -停止深度 1 编排器会自动停止其所有深度 2 子级： +停止一个深度 1 编排器会自动停止其所有深度 2 子级： -- 在主聊天中执行 `/stop` 会停止所有深度 1 智能体，并级联到它们的深度 2 子级。 -- `/subagents kill ` 会停止某个特定子智能体，并级联到其子级。 +- 在主聊天中使用 `/stop` 会停止所有深度 1 智能体，并级联停止它们的深度 2 子级。 +- `/subagents kill ` 会停止指定子智能体，并级联停止其子级。 - `/subagents kill all` 会停止请求者的所有子智能体，并执行级联停止。 -## 认证 +## 身份验证 -子智能体认证按**智能体 id** 解析，而不是按会话类型： +子智能体认证按**智能体 id** 解析，而不是按会话类型解析： - 子智能体会话键为 `agent::subagent:`。 - 认证存储从该智能体的 `agentDir` 加载。 -- 主智能体的认证配置档案会作为**后备**合并进来；若有冲突，智能体配置档案优先于主配置档案。 +- 主智能体的认证配置文件会作为**回退项**合并进来；若发生冲突，智能体配置文件会覆盖主配置文件。 -这种合并是增量式的，因此主配置档案始终可作为后备使用。目前尚不支持按智能体完全隔离的认证。 +这种合并是增量式的，因此主配置文件始终可作为回退项使用。当前尚不支持按智能体完全隔离的认证。 -## announce +## 通知 -子智能体通过 announce 步骤回报结果： +子智能体通过通知步骤回报结果： -- announce 步骤在子智能体会话内运行（而不是请求者会话）。 -- 如果子智能体的回复精确等于 `ANNOUNCE_SKIP`，则不会发布任何内容。 -- 如果最新 assistant 文本是精确的静默 token `NO_REPLY` / `no_reply`，则即使之前存在可见进度，announce 输出也会被抑制。 +- 通知步骤在子智能体会话内部运行（而不是在请求者会话中）。 +- 如果子智能体精确回复 `ANNOUNCE_SKIP`，则不会发布任何内容。 +- 如果最新的 assistant 文本是精确的静默 token `NO_REPLY` / `no_reply`，则即使之前存在可见进度，也会抑制通知输出。 -交付取决于请求者深度： +交付方式取决于请求者深度： - 顶层请求者会话使用带外部交付的后续 `agent` 调用（`deliver=true`）。 -- 嵌套的请求者子智能体会话接收内部后续注入（`deliver=false`），以便编排器在会话内综合子级结果。 -- 如果嵌套的请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者。 +- 嵌套请求者子智能体会话接收内部后续注入（`deliver=false`），以便编排器能在会话内综合子级结果。 +- 如果嵌套请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者。 -对于顶层请求者会话，完成模式的直接交付会先解析任何已绑定的对话/线程路由和 hook 覆盖，然后从请求者会话中存储的路由补齐缺失的渠道目标字段。这样即使完成来源只标识了渠道，也能确保完成消息发往正确的聊天/话题。 +对于顶层请求者会话，完成模式下的直接交付会先解析任意已绑定的会话/线程路由和 hook 覆盖，然后用请求者会话已存储的路由信息补齐缺失的渠道目标字段。这样即使完成来源只标识了渠道，也能将完成通知保持在正确的聊天/话题中。 -在构建嵌套完成结果时，子级完成聚合被限定在当前请求者运行范围内，从而防止先前运行的陈旧子级输出泄漏到当前 announce 中。若渠道适配器支持，announce 回复会保留线程/话题路由。 +在构建嵌套完成结果时，子级完成聚合会限定在当前请求者运行范围内，防止过往运行中陈旧的子级输出泄漏到当前通知中。通知回复在渠道适配器可用时会保留线程/话题路由。 -### announce 上下文 +### 通知上下文 -announce 上下文会被规范化为稳定的内部事件块： +通知上下文会被规范化为稳定的内部事件块： -| 字段 | 来源 | -| ------------ | -------------------------------------------------------------------- | -| Source | `subagent` 或 `cron` | -| Session ids | 子会话键/id | -| Type | announce 类型 + 任务标签 | -| Status | 从运行时结果派生（`success`、`error`、`timeout` 或 `unknown`）——**不是**从模型文本推断 | -| Result content | 最新可见的 assistant 文本，否则为已清理的最新 tool/toolResult 文本 | -| Follow-up | 描述何时回复、何时保持静默的说明 | +| 字段 | 来源 | +| -------------- | ------------------------------------------------------------------------------------------------------------- | +| Source | `subagent` 或 `cron` | +| Session ids | 子级会话键/id | +| Type | 通知类型 + 任务标签 | +| Status | 从运行时结果派生（`success`、`error`、`timeout` 或 `unknown`）——**不是**从模型文本推断 | +| Result content | 最新可见 assistant 文本；若没有，则使用经清理的最新 `tool`/`toolResult` 文本 | +| Follow-up | 描述何时应回复、何时保持静默的指令 | -终态失败的运行会报告失败状态，而不会回放已捕获的回复文本。超时时，如果子级只执行到了工具调用阶段，announce 可以将该历史压缩为简短的部分进度摘要，而不是回放原始工具输出。 +终态失败的运行会报告失败状态，而不会重放已捕获的回复文本。超时时，如果子级仅执行到了工具调用阶段，通知可以将该历史压缩成简短的部分进度摘要，而不是重放原始工具输出。 ### 统计行 -announce 负载在末尾包含一行统计信息（即使被包装也会保留）： +通知负载在末尾包含一行统计信息（即使被包裹也会包含）： - 运行时长（例如 `runtime 5m12s`）。 -- Token 使用量（输入/输出/总计）。 -- 在配置了模型定价时的预估成本（`models.providers.*.models[].cost`）。 -- `sessionKey`、`sessionId` 和转录路径，以便主智能体可通过 `sessions_history` 获取历史记录，或在磁盘上检查文件。 +- Token 使用量（输入/输出/总量）。 +- 若已配置模型定价，则包含预估成本（`models.providers.*.models[].cost`）。 +- `sessionKey`、`sessionId` 和转录路径，以便主智能体通过 `sessions_history` 获取历史记录，或在磁盘上检查文件。 -内部元数据仅用于编排；面向用户的回复应使用普通助手语气重写。 +内部元数据仅用于编排；面向用户的回复应以正常助手口吻重写。 ### 为什么优先使用 `sessions_history` `sessions_history` 是更安全的编排路径： -- assistant 回溯会先被规范化：去除 thinking 标签；去除 `` / `` 脚手架；去除纯文本工具调用 XML 负载块（``、``、``、``），包括那些从未完整闭合的截断负载；去除降级后的工具调用/结果脚手架和历史上下文标记；去除泄漏的模型控制 token（`<|assistant|>`、其他 ASCII `<|...|>`、全角 `<｜...｜>`）；去除格式错误的 MiniMax 工具调用 XML。 +- 会先规范化 assistant 回溯：剥离 thinking 标签；剥离 `` / `` 脚手架；剥离纯文本工具调用 XML 负载块（``、``、``、``），包括那些未能正常闭合的截断负载；剥离已降级的工具调用/结果脚手架和历史上下文标记；剥离泄露的模型控制 token（`<|assistant|>`、其他 ASCII `<|...|>`、全角 `<｜...｜>`）；剥离格式错误的 MiniMax 工具调用 XML。 - 类似凭证/token 的文本会被脱敏。 - 长内容块可能会被截断。 -- 对于非常大的历史记录，可能会丢弃较早的条目，或者用 `[sessions_history omitted: message too large]` 替换过大的条目。 -- 当你需要逐字节的完整转录时，可回退到检查磁盘上的原始转录。 +- 非常大的历史记录可能会丢弃较早的行，或将超大单行替换为 `[sessions_history omitted: message too large]`。 +- 当你需要完整逐字节转录时，回退方案是直接检查磁盘上的原始转录。 ## 工具策略 -子智能体首先使用与父智能体或目标智能体相同的配置档案和工具策略流水线。之后，OpenClaw 会应用子智能体限制层。 +子智能体首先沿用父智能体或目标智能体相同的配置文件和工具策略流水线。之后，OpenClaw 会应用子智能体限制层。 在没有限制性 `tools.profile` 的情况下，子智能体会获得**除会话工具和系统工具之外的所有工具**： @@ -370,9 +377,9 @@ announce 负载在末尾包含一行统计信息（即使被包装也会保留 - `sessions_send` - `sessions_spawn` -这里的 `sessions_history` 也仍然是有界、已清理的回顾视图——它不是原始转录转储。 +此处的 `sessions_history` 仍然是一个有边界、经过清理的回溯视图——它不是原始转录转储。 -当 `maxSpawnDepth >= 2` 时，深度 1 编排器子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便管理其子级。 +当 `maxSpawnDepth >= 2` 时，深度 1 的编排子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便管理其子级。 ### 通过配置覆盖 @@ -388,9 +395,9 @@ announce 负载在末尾包含一行统计信息（即使被包装也会保留 tools: { subagents: { tools: { - // deny 优先 + // deny 优先生效 deny: ["gateway", "cron"], - // 如果设置了 allow，则变为仅允许这些（deny 仍然优先） + // 如果设置了 allow，它就会变成仅允许列表（deny 仍然优先生效） // allow: ["read", "exec", "process"] }, }, @@ -398,7 +405,7 @@ announce 负载在末尾包含一行统计信息（即使被包装也会保留 } ``` -`tools.subagents.tools.allow` 是最终的仅允许过滤器。它可以缩小已经解析出的工具集合，但不能**重新加入**被 `tools.profile` 移除的工具。例如，`tools.profile: "coding"` 包含 `web_search`/`web_fetch`，但不包含 `browser` 工具。若要让 coding 配置档案的子智能体使用浏览器自动化，请在配置档案阶段加入 browser： +`tools.subagents.tools.allow` 是最终的仅允许过滤器。它可以收窄已经解析出的工具集，但不能**重新加入**已被 `tools.profile` 移除的工具。例如，`tools.profile: "coding"` 包含 `web_search`/`web_fetch`，但不包含 `browser` 工具。若要让 coding 配置文件下的子智能体使用浏览器自动化，请在配置文件阶段加入 `browser`： ```json5 { @@ -409,7 +416,7 @@ announce 负载在末尾包含一行统计信息（即使被包装也会保留 } ``` -当只有某一个智能体应获得浏览器自动化能力时，请使用按智能体配置的 `agents.list[].tools.alsoAllow: ["browser"]`。 +如果只希望某一个智能体获得浏览器自动化，请使用按智能体配置的 `agents.list[].tools.alsoAllow: ["browser"]`。 ## 并发 @@ -420,31 +427,31 @@ announce 负载在末尾包含一行统计信息（即使被包装也会保留 ## 存活性与恢复 -OpenClaw 不会将缺少 `endedAt` 视为子智能体仍然存活的永久性证据。超过陈旧运行窗口但尚未结束的运行，将不再在 `/subagents list`、状态摘要、后代完成门控以及每会话并发检查中计为活动/待处理。 +OpenClaw 不会将缺少 `endedAt` 视为子智能体仍然存活的永久性证据。早于陈旧运行窗口、且未结束的运行，在 `/subagents list`、状态摘要、后代完成门控以及按会话统计的并发检查中，将不再计入活动/待处理状态。 -在 Gateway 网关重启后，陈旧的、未结束的已恢复运行会被清理，除非其子会话被标记为 `abortedLastRun: true`。这些因重启而中止的子会话仍可通过子智能体孤儿恢复流程进行恢复，该流程会先发送一条合成的恢复消息，然后再清除此中止标记。 +在 Gateway 网关重启后，陈旧且未结束的已恢复运行会被清理，除非其子会话被标记为 `abortedLastRun: true`。这些因重启而中止的子会话仍可通过子智能体孤儿恢复流程进行恢复，该流程会先发送一条合成的恢复消息，然后再清除中止标记。 -如果子智能体派生因 Gateway 网关 `PAIRING_REQUIRED` / `scope-upgrade` 失败，请先检查 RPC 调用方，再修改配对状态。内部 `sessions_spawn` 协调应通过直接 loopback 共享 token/密码认证，以 `client.id: "gateway-client"` 和 `client.mode: "backend"` 连接；该路径不依赖 CLI 的已配对设备作用域基线。远程调用方、显式的 `deviceIdentity`、显式设备 token 路径，以及浏览器/node 客户端，仍然需要正常的设备批准才能进行作用域升级。 +如果子智能体派生因 Gateway 网关 `PAIRING_REQUIRED` / `scope-upgrade` 失败，在编辑配对状态前，请先检查 RPC 调用方。内部 `sessions_spawn` 协调应通过直接 loopback shared-token/password 身份验证，使用 `client.id: "gateway-client"` 和 `client.mode: "backend"` 进行连接；该路径不依赖 CLI 的已配对设备作用域基线。远程调用方、显式 `deviceIdentity`、显式设备 token 路径以及浏览器/node 客户端，仍然需要正常的设备批准才能完成作用域升级。 ## 停止 -- 在请求者聊天中发送 `/stop` 会中止请求者会话，并停止所有由其派生的活动子智能体运行，同时级联停止嵌套子级。 -- `/subagents kill ` 会停止指定的子智能体，并级联停止其子级。 +- 在请求者聊天中发送 `/stop` 会中止请求者会话，并停止由其派生的所有活动子智能体运行，同时级联到嵌套子级。 +- `/subagents kill ` 会停止指定子智能体，并级联停止其子级。 ## 限制 -- 子智能体 announce 是**尽力而为**的。如果 Gateway 网关重启，待处理的“announce 回传”工作将会丢失。 -- 子智能体仍然共享同一个 Gateway 网关进程资源；请将 `maxConcurrent` 视为一个安全阀。 +- 子智能体通知回传是**尽力而为**的。如果 Gateway 网关重启，待处理的“通知回传”工作会丢失。 +- 子智能体仍共享同一个 Gateway 网关进程资源；请将 `maxConcurrent` 视为安全阀。 - `sessions_spawn` 始终是非阻塞的：它会立即返回 `{ status: "accepted", runId, childSessionKey }`。 -- 子智能体上下文只会注入 `AGENTS.md` + `TOOLS.md`（不会注入 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。 -- 最大嵌套深度为 5（`maxSpawnDepth` 范围：1–5）。大多数用例推荐使用深度 2。 +- 子智能体上下文只会注入 `AGENTS.md` + `TOOLS.md`（不包括 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。 +- 最大嵌套深度为 5（`maxSpawnDepth` 范围：1–5）。大多数用例建议使用深度 2。 - `maxChildrenPerAgent` 限制每个会话的活动子级数量（默认 `5`，范围 `1–20`）。 ## 相关内容 - [ACP 智能体](/zh-CN/tools/acp-agents) -- [智能体发送](/zh-CN/tools/agent-send) +- [Agent send](/zh-CN/tools/agent-send) - [后台任务](/zh-CN/automation/tasks) - [多智能体沙箱工具](/zh-CN/tools/multi-agent-sandbox-tools)