diff --git a/docs/zh-CN/cli/infer.md b/docs/zh-CN/cli/infer.md index cbfa36ca5..ea7d13435 100644 --- a/docs/zh-CN/cli/infer.md +++ b/docs/zh-CN/cli/infer.md @@ -2,38 +2,38 @@ read_when: - 添加或修改 `openclaw infer` 命令 - 设计稳定的无头能力自动化 -summary: 面向提供商支持的模型、图像、音频、TTS、视频、网页和嵌入工作流的 infer-first CLI -title: 推理 CLI +summary: 面向由提供商支持的模型、图像、音频、TTS、视频、网页和嵌入工作流的推断优先 CLI +title: 推断 CLI x-i18n: - generated_at: "2026-04-27T22:06:15Z" + generated_at: "2026-04-27T22:22:36Z" model: gpt-5.4 provider: openai - source_hash: 704f9ea60adb1b509f0b4f74ae79ffb70f12915a7e8a45d43ca28f5ac7d70af1 + source_hash: 5f9dc003af66692fe85d11c74ef952b72668aa7c715090b92ca5511f680a963d source_path: cli/infer.md workflow: 15 --- -`openclaw infer` 是提供商支持的推理工作流的规范无头入口。 +`openclaw infer` 是用于由提供商支持的推断工作流的规范无头入口。 -它有意暴露的是能力家族，而不是原始的 Gateway 网关 RPC 名称，也不是原始的智能体工具 id。 +它有意暴露的是能力族，而不是原始 Gateway 网关 RPC 名称，也不是原始智能体工具 id。 -## 将 infer 变成一个 Skills +## 将 infer 变成一个 skill -把下面这段内容复制粘贴给一个智能体： +将以下内容复制并粘贴给一个智能体： ```text -Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`. -Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings. +阅读 https://docs.openclaw.ai/cli/infer，然后创建一个 skill，将我的常见工作流路由到 `openclaw infer`。 +重点关注模型运行、图像生成、视频生成、音频转录、TTS、网页搜索和嵌入。 ``` -一个基于 infer 的优秀 Skills 应该： +一个基于 infer 的优秀 skill 应该： - 将常见用户意图映射到正确的 infer 子命令 -- 包含其所覆盖工作流的一些规范 infer 示例 +- 包含它所覆盖工作流的一些规范 infer 示例 - 在示例和建议中优先使用 `openclaw infer ...` -- 避免在 Skills 正文中重新记录完整的 infer 功能面 +- 避免在 skill 正文中重复记录整个 infer 功能面 -典型的 infer 导向 Skills 覆盖范围： +典型的面向 infer 的 skill 覆盖范围： - `openclaw infer model run` - `openclaw infer image generate` @@ -44,17 +44,17 @@ Focus on model runs, image generation, video generation, audio transcription, TT ## 为什么使用 infer -`openclaw infer` 为 OpenClaw 中由提供商支持的推理任务提供了一个统一的 CLI。 +`openclaw infer` 为 OpenClaw 内部由提供商支持的推断任务提供了一个统一的 CLI。 -优势： +优点： -- 使用 OpenClaw 中已配置的提供商和模型，而不是为每个后端单独接入一次性包装器。 -- 将模型、图像、音频转录、TTS、视频、网页和嵌入工作流统一放在同一棵命令树下。 +- 使用 OpenClaw 中已经配置好的提供商和模型，而不是为每个后端单独接入一次性包装器。 +- 将模型、图像、音频转录、TTS、视频、网页和嵌入工作流统一到一个命令树下。 - 为脚本、自动化和智能体驱动的工作流使用稳定的 `--json` 输出结构。 -- 当任务本质上是“运行推理”时，优先使用 OpenClaw 的第一方入口。 -- 对于大多数 infer 命令，使用常规本地路径而无需运行 Gateway 网关。 +- 当任务本质上是“运行推断”时，优先使用 OpenClaw 的第一方入口。 +- 对于大多数 infer 命令，使用常规本地路径而无需依赖 Gateway 网关。 -对于端到端提供商检查，在较低层提供商测试已通过后，优先使用 `openclaw infer ...`。它会在发起提供商请求之前，覆盖已发布的 CLI、配置加载、默认智能体解析、内置插件激活、运行时依赖修复以及共享能力运行时。 +对于端到端的提供商检查，在更底层的提供商测试通过后，优先使用 `openclaw infer ...`。它会在发出提供商请求之前，覆盖已发布的 CLI、配置加载、默认智能体解析、内置插件激活、运行时依赖修复以及共享能力运行时。 ## 命令树 @@ -109,37 +109,37 @@ Focus on model runs, image generation, video generation, audio transcription, TT ## 常见任务 -下表将常见推理任务映射到对应的 infer 命令。 +下表将常见推断任务映射到对应的 infer 命令。 | 任务 | 命令 | 说明 | | ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- | -| 运行文本/模型提示词 | `openclaw infer model run --prompt "..." --json` | 默认使用常规本地路径 | -| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 如果从现有文件开始，使用 `image edit` | -| 描述图像文件 | `openclaw infer image describe --file ./image.png --json` | `--model` 必须是支持图像的 `` | +| 运行文本/模型提示 | `openclaw infer model run --prompt "..." --json` | 默认使用常规本地路径 | +| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 从现有文件开始时使用 `image edit` | +| 描述图像文件 | `openclaw infer image describe --file ./image.png --json` | `--model` 必须是具备图像能力的 `` | | 转录音频 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` 必须是 `` | | 合成语音 | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` 面向 Gateway 网关 | -| 生成视频 | `openclaw infer video generate --prompt "..." --json` | 支持诸如 `--resolution` 之类的提供商提示参数 | +| 生成视频 | `openclaw infer video generate --prompt "..." --json` | 支持如 `--resolution` 之类的提供商提示 | | 描述视频文件 | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` 必须是 `` | | 搜索网页 | `openclaw infer web search --query "..." --json` | | -| 抓取网页 | `openclaw infer web fetch --url https://example.com --json` | | +| 获取网页 | `openclaw infer web fetch --url https://example.com --json` | | | 创建嵌入 | `openclaw infer embedding create --text "..." --json` | | ## 行为 - `openclaw infer ...` 是这些工作流的主要 CLI 入口。 -- 当输出将被另一个命令或脚本消费时，使用 `--json`。 +- 当输出将被其他命令或脚本消费时，使用 `--json`。 - 当需要特定后端时，使用 `--provider` 或 `--model provider/model`。 - 对于 `image describe`、`audio transcribe` 和 `video describe`，`--model` 必须使用 `` 形式。 -- 对于 `image describe`，显式传入 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/` 会运行一次受限的 Codex app-server 图像理解回合；`openai-codex/` 使用 OpenAI Codex OAuth provider 路径。 +- 对于 `image describe`，显式提供 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/` 会运行一个受限的 Codex app-server 图像理解轮次；`openai-codex/` 使用 OpenAI Codex OAuth provider 路径。 - 无状态执行命令默认走本地。 - 由 Gateway 网关管理状态的命令默认走 Gateway 网关。 -- 常规本地路径不要求 Gateway 网关正在运行。 -- 本地 `model run` 是精简的一次性提供商补全。它会解析已配置的智能体模型和凭证，但不会启动聊天智能体回合、加载工具，也不会打开内置 MCP 服务器。 -- `model run --gateway` 仍然使用 Gateway 网关智能体运行时，因此它可以覆盖与普通 Gateway 网关支持回合同样的路由运行时路径。通过该运行时打开的 MCP 服务器会在回复后被回收，因此重复的脚本调用不会让 stdio MCP 子进程持续存活。 +- 常规本地路径不要求 Gateway 网关处于运行状态。 +- 本地 `model run` 是精简的一次性提供商补全。它会解析已配置的智能体模型和认证信息，但不会启动聊天智能体轮次、加载工具或打开内置 MCP 服务器。 +- `model run --gateway` 仍然使用 Gateway 网关智能体运行时，因此它可以覆盖与普通 Gateway 网关支持轮次相同的路由运行时路径。通过该运行时打开的 MCP 服务器会在回复后被回收，因此重复执行脚本调用不会让 stdio MCP 子进程持续存活。 ## 模型 -使用 `model` 执行由提供商支持的文本推理，以及模型/提供商检查。 +对由提供商支持的文本推断以及模型/提供商检查，使用 `model`。 ```bash openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json @@ -148,7 +148,7 @@ openclaw infer model providers --json openclaw infer model inspect --name gpt-5.5 --json ``` -使用完整的 `` 引用来对特定提供商进行冒烟测试，而无需启动 Gateway 网关或加载完整的智能体工具面： +使用完整的 `` 引用来对特定提供商执行冒烟测试，而无需启动 Gateway 网关或加载完整的智能体工具功能面： ```bash openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --json @@ -161,13 +161,14 @@ openclaw infer model run --local --model openai/gpt-4.1 --prompt "Reply with exa 说明： -- 本地 `model run` 是最窄的 CLI 冒烟检查方式，可用于验证提供商/模型/凭证健康状态，因为它只会把提供的提示词发送给所选模型。 -- 当你需要测试 Gateway 网关路由、智能体运行时设置或 Gateway 网关管理的提供商状态，而不是精简的本地补全路径时，使用 `model run --gateway`。 -- `model auth login`、`model auth logout` 和 `model auth status` 用于管理已保存的提供商凭证状态。 +- 本地 `model run` 是用于检查提供商/模型/认证健康状态的最窄 CLI 冒烟测试，因为它只会将提供的提示发送给选定模型。 +- 当提供商未返回文本输出时，本地 `model run` 会以非零状态退出，因此不可达的本地提供商和空补全不会被误判为成功探测。 +- 当你需要测试 Gateway 网关路由、智能体运行时设置或由 Gateway 网关管理的提供商状态，而不是精简的本地补全路径时，使用 `model run --gateway`。 +- `model auth login`、`model auth logout` 和 `model auth status` 用于管理已保存的提供商认证状态。 ## 图像 -使用 `image` 执行生成、编辑和描述。 +对生成、编辑和描述使用 `image`。 ```bash openclaw infer image generate --prompt "friendly lobster illustration" --json @@ -184,10 +185,10 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j 说明： - 从现有输入文件开始时，使用 `image edit`。 -- 对于支持参考图像编辑几何提示的提供商/模型，在 `image edit` 中使用 `--size`、`--aspect-ratio` 或 `--resolution`。 -- 对于透明背景的 OpenAI PNG 输出，结合 `--model openai/gpt-image-1.5` 使用 `--output-format png --background transparent`；`--openai-background` 仍然可作为 OpenAI 专用别名使用。未声明支持背景参数的提供商会将该提示报告为已忽略的覆盖项。 -- 使用 `image providers --json` 来验证哪些内置图像提供商可被发现、已配置、已选中，以及每个提供商暴露了哪些生成/编辑能力。 -- 使用 `image generate --model --json` 作为图像生成变更最窄的在线 CLI 冒烟检查。例如： +- 对于支持在参考图像编辑中使用几何提示的提供商/模型，可在 `image edit` 中使用 `--size`、`--aspect-ratio` 或 `--resolution`。 +- 对于透明背景的 OpenAI PNG 输出，结合 `--model openai/gpt-image-1.5` 使用 `--output-format png --background transparent`；`--openai-background` 仍可作为 OpenAI 专用别名使用。不声明背景支持的提供商会将该提示报告为被忽略的覆盖项。 +- 使用 `image providers --json` 来确认哪些内置图像提供商可被发现、已配置、已选中，以及各提供商暴露了哪些生成/编辑能力。 +- 将 `image generate --model --json` 用作图像生成变更的最窄实时 CLI 冒烟测试。示例： ```bash openclaw infer image providers --json @@ -198,14 +199,14 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j --json ``` - JSON 响应会报告 `ok`、`provider`、`model`、`attempts` 以及写出的输出路径。设置 `--output` 时，最终扩展名可能会遵循提供商返回的 MIME 类型。 + JSON 响应会报告 `ok`、`provider`、`model`、`attempts` 和写入的输出路径。设置了 `--output` 时，最终扩展名可能会跟随提供商返回的 MIME 类型。 -- 对于 `image describe`，`--model` 必须是支持图像的 ``。 -- 对于本地 Ollama 视觉模型，先拉取模型，并将 `OLLAMA_API_KEY` 设为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。 +- 对于 `image describe`，`--model` 必须是具备图像能力的 ``。 +- 对于本地 Ollama 视觉模型，先拉取模型，并将 `OLLAMA_API_KEY` 设置为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。 ## 音频 -使用 `audio` 执行文件转录。 +对文件转录使用 `audio`。 ```bash openclaw infer audio transcribe --file ./memo.m4a --json @@ -220,7 +221,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso ## TTS -使用 `tts` 执行语音合成和 TTS 提供商状态管理。 +对语音合成和 TTS 提供商状态使用 `tts`。 ```bash openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json @@ -236,7 +237,7 @@ openclaw infer tts status --json ## 视频 -使用 `video` 执行生成和描述。 +对生成和描述使用 `video`。 ```bash openclaw infer video generate --prompt "cinematic sunset over the ocean" --json @@ -247,12 +248,12 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js 说明： -- `video generate` 接受 `--size`、`--aspect-ratio`、`--resolution`、`--duration`、`--audio`、`--watermark` 和 `--timeout-ms`，并将它们转发给视频生成运行时。 +- `video generate` 接受 `--size`、`--aspect-ratio`、`--resolution`、`--duration`、`--audio`、`--watermark` 和 `--timeout-ms`，并将它们转发到视频生成运行时。 - 对于 `video describe`，`--model` 必须是 ``。 ## 网页 -使用 `web` 执行搜索和抓取工作流。 +对搜索和抓取工作流使用 `web`。 ```bash openclaw infer web search --query "OpenClaw docs" --json @@ -263,11 +264,11 @@ openclaw infer web providers --json 说明： -- 使用 `web providers` 来检查可用、已配置和已选中的提供商。 +- 使用 `web providers` 检查可用、已配置和已选中的提供商。 ## 嵌入 -使用 `embedding` 进行向量创建和嵌入提供商检查。 +对向量创建和嵌入提供商检查使用 `embedding`。 ```bash openclaw infer embedding create --text "friendly lobster" --json @@ -277,7 +278,7 @@ openclaw infer embedding providers --json ## JSON 输出 -Infer 命令会在共享封装下规范化 JSON 输出： +Infer 命令会在共享信封结构下规范化 JSON 输出： ```json { @@ -302,7 +303,7 @@ Infer 命令会在共享封装下规范化 JSON 输出： - `outputs` - `error` -对于生成媒体的命令，`outputs` 包含由 OpenClaw 写入的文件。对于自动化，请使用该数组中的 `path`、`mimeType`、`size` 以及任何媒体特定的尺寸信息，而不要解析面向人类可读的 stdout。 +对于生成媒体的命令，`outputs` 包含由 OpenClaw 写入的文件。在自动化中，请使用该数组中的 `path`、`mimeType`、`size` 以及任何媒体特有尺寸信息，而不是解析人类可读的 stdout。 ## 常见陷阱 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 17fee5621..8c13aed0b 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,76 +2,76 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: 核心 OpenClaw 键名、默认值及专用子系统参考链接的 Gateway 网关配置参考 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-27T12:51:49Z" + generated_at: "2026-04-27T22:22:37Z" model: gpt-5.4 provider: openai - source_hash: d3c9d69ac5fe9c32a19bb92e05927a3ec919c3d4112b809f9d886a83746d37c8 + source_hash: 08e5302ef65a8464dcb1babb9fa01d3084bc1a622632b60f144997266cf174af source_path: gateway/configuration-reference.md workflow: 15 --- -`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参见 [配置](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 -本页涵盖 OpenClaw 的主要配置界面，并在子系统拥有更深入的独立参考时提供跳转链接。由渠道和插件拥有的命令目录，以及深层 memory/QMD 调节项，位于各自页面而不是本页。 +涵盖主要的 OpenClaw 配置面，并在子系统拥有更深入的独立参考时链接到对应页面。渠道和插件自有的命令目录，以及更深层的 memory/QMD 细节配置，位于各自的页面，而不是本页。 -代码事实来源： +代码事实依据： - `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 -- `config.schema.lookup` 会返回单个按路径限定的 schema 节点，供下钻工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 界面验证配置文档基线哈希 +- `config.schema.lookup` 会返回一个按路径范围限定的 schema 节点，用于下钻工具 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希 -智能体查找路径：在编辑前，使用 `gateway` 工具操作 `config.schema.lookup` 获取精确到字段级别的文档和约束。使用 [配置](/zh-CN/gateway/configuration) 获取面向任务的指导，使用本页查看更广泛的字段映射、默认值和子系统参考链接。 +智能体查找路径：在编辑前，使用 `gateway` 工具操作 `config.schema.lookup` 获取精确到字段级别的文档和约束。面向任务的指导请使用 [Configuration](/zh-CN/gateway/configuration)，而本页用于查看更广泛的字段映射、默认值以及子系统参考链接。 -专门的深入参考： +专用深度参考： -- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 -- [斜杠命令](/zh-CN/tools/slash-commands)，用于查看当前内置 + 内置变体命令目录 -- 对应的渠道/插件页面，用于查看渠道专属命令界面 +- [Memory configuration reference](/zh-CN/reference/memory-config) 用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 +- [Slash commands](/zh-CN/tools/slash-commands) 用于当前内置 + 捆绑命令目录 +- 各所属渠道/插件页面用于渠道专属命令界面 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— 省略时，OpenClaw 会使用安全默认值。 --- ## 渠道 -各渠道配置键已移至独立页面 —— 请参见 -[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`， -其中包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他 -内置渠道（身份验证、访问控制、多账户、提及门控）。 +每个渠道的配置键已移至专用页面 —— 请参见 +[Configuration — channels](/zh-CN/gateway/config-channels) 了解 `channels.*`， +包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 及其他 +内置渠道（认证、访问控制、多账号、提及门控）。 -## 智能体默认值、多智能体、会话和消息 +## 智能体默认值、多智能体、会话与消息 -已移至独立页面 —— 请参见 -[配置 — 智能体](/zh-CN/gateway/config-agents)，了解： +已移至专用页面 —— 请参见 +[Configuration — agents](/zh-CN/gateway/config-agents) 了解： -- `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱） -- `multiAgent.*`（多智能体路由和绑定） +- `agents.defaults.*`（工作区、模型、思考、心跳、memory、媒体、Skills、沙箱） +- `multiAgent.*`（多智能体路由与绑定） - `session.*`（会话生命周期、压缩、清理） - `messages.*`（消息投递、TTS、Markdown 渲染） - `talk.*`（Talk 模式） - - `talk.speechLocale`：用于 iOS/macOS 上 Talk 语音识别的可选 BCP 47 locale id - - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送 transcript 之前保持平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`） + - `talk.speechLocale`：可选的 BCP 47 locale id，用于 iOS/macOS 上 Talk 语音识别 + - `talk.silenceTimeoutMs`：未设置时，Talk 会保留平台默认的停顿窗口后再发送转录文本（`macOS 和 Android 为 700 ms，iOS 为 900 ms`） ## 工具和自定义提供商 -工具策略、实验性开关、由提供商支持的工具配置，以及自定义 -提供商 / base-URL 设置已移至独立页面 —— 请参见 -[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 +工具策略、实验性开关、由 provider 支持的工具配置，以及自定义 +provider / base-URL 设置已移至专用页面 —— 请参见 +[Configuration — tools and custom providers](/zh-CN/gateway/config-tools)。 ## MCP 由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下， -由内置 Pi 和其他运行时适配器使用。`openclaw mcp list`、 -`show`、`set` 和 `unset` 命令管理该配置块，而不会在配置编辑期间连接到 +供嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、 +`show`、`set` 和 `unset` 命令可管理此配置块，并且在编辑配置时不会连接到 目标服务器。 ```json5 { mcp: { - // 可选。默认值：600000 ms（10 分钟）。设为 0 可禁用空闲驱逐。 + // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction. sessionIdleTtlMs: 600000, servers: { docs: { @@ -90,19 +90,19 @@ x-i18n: } ``` -- `mcp.servers`：供暴露已配置 MCP 工具的运行时使用的命名 stdio 或远程 MCP 服务器定义。 +- `mcp.servers`：为暴露已配置 MCP 工具的运行时提供命名的 stdio 或远程 MCP 服务器定义。 远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`； `type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 - `openclaw doctor --fix` 会将其规范化为标准的 `transport` 字段。 -- `mcp.sessionIdleTtlMs`：会话范围内置 MCP 运行时的空闲 TTL。 - 一次性内置运行会请求在运行结束时清理；此 TTL 是 + `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。 +- `mcp.sessionIdleTtlMs`：面向会话作用域的内置 MCP 运行时的空闲 TTL。 + 一次性嵌入式运行会请求在运行结束时清理；此 TTL 是 长生命周期会话和未来调用方的兜底机制。 -- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。 - 下一次工具发现/使用时会根据新配置重新创建它们，因此移除的 - `mcp.servers` 条目会立即被回收，而不是等待空闲 TTL。 +- `mcp.*` 下的更改会通过释放已缓存的会话 MCP 运行时来热应用。 + 下一次工具发现/使用时会根据新配置重新创建它们，因此已移除的 + `mcp.servers` 条目会立即被回收，而不是等待空闲 TTL 到期。 -请参见 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 -[CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays) 了解运行时行为。 +运行时行为请参见 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 +[CLI backends](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。 ## Skills @@ -119,7 +119,7 @@ x-i18n: }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或明文字符串 + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -131,11 +131,11 @@ x-i18n: - `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。 - `load.extraDirs`：额外的共享 skill 根目录（优先级最低）。 -- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 +- `install.preferBrew`：为 true 时，若检测到 `brew` 可用，则优先使用 Homebrew 安装器，随后才回退到其他安装器类型。 - `install.nodeManager`：用于 `metadata.openclaw.install` - 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使某个 skill 已内置/安装，也会禁用它。 -- `entries..apiKey`：为声明了主环境变量的 Skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 + 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 skill 已内置/已安装，也会将其禁用。 +- `entries..apiKey`：为声明了主环境变量的 skills 提供便捷配置（明文字符串或 SecretRef 对象）。 --- @@ -164,42 +164,42 @@ x-i18n: ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，其中包括无 manifest 的 Claude 默认布局 bundle。 +- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 - **配置更改需要重启 Gateway 网关。** -- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时）。 -- `plugins.entries..env`：插件范围的环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持的 bundle 提供的钩子目录。 -- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end` 等类型化钩子中读取原始会话内容。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件，使其可为后台子智能体运行请求按次 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的标准 `provider/model` 目标可选允许列表。仅当你有意允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。 -- 渠道插件的账户/运行时设置位于 `channels.` 下，应由对应插件 manifest 的 `channelConfigs` 元数据描述，而不是由中心化的 OpenClaw 选项注册表描述。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。 +- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 +- `plugins.entries..env`：插件作用域的环境变量映射。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持的 bundle 提供的 hook 目录。 +- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可以从 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end` 等类型化钩子中读取原始会话内容。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件，以允许其为后台子智能体运行请求每次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：面向受信任子智能体覆盖的标准 `provider/model` 目标可选允许列表。仅当你有意允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（若可用，则由原生 OpenClaw 插件 schema 验证）。 +- 渠道插件的账号/运行时设置位于 `channels.` 下，应该由所属插件 manifest 的 `channelConfigs` 元数据描述，而不是由中心化的 OpenClaw 选项注册表描述。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取 provider 设置。 - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - - `baseUrl`：Firecrawl API 基础 URL（默认：`https://api.firecrawl.dev`）。 - - `onlyMainContent`：仅提取页面主体内容（默认：`true`）。 - - `maxAgeMs`：最大缓存时长（毫秒，默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时时间（秒，默认：`60`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - - `enabled`：启用 X Search 提供商。 + - `baseUrl`：Firecrawl API 基础 URL（默认值：`https://api.firecrawl.dev`）。 + - `onlyMainContent`：仅提取页面主体内容（默认值：`true`）。 + - `maxAgeMs`：缓存最大保留时间（毫秒）（默认值：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时秒数（默认值：`60`）。 +- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web search）设置。 + - `enabled`：启用 X Search provider。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 - `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。各阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `enabled`：dreaming 总开关（默认 `false`）。 - - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 + - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认值为 `"0 3 * * *"`）。 - `model`：可选的 Dream Diary 子智能体模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；请配合 `allowedModels` 使用以限制目标。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整的 memory 配置位于 [内存配置参考](/zh-CN/reference/memory-config)： +- 完整 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供内置 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动 context engine 插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 +- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择激活的 memory 插件 id，或使用 `"none"` 禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择激活的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 -请参见 [插件](/zh-CN/tools/plugin)。 +请参见 [Plugins](/zh-CN/tools/plugin)。 --- @@ -212,8 +212,8 @@ x-i18n: evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问中启用 - // allowPrivateNetwork: true, // 旧版别名 + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -250,36 +250,44 @@ x-i18n: ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `tabCleanup` 会在空闲一段时间后，或当某个会话超过其上限时，回收已跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为禁用这些单独的清理模式。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此浏览器导航默认保持严格模式。 +- `tabCleanup` 会在空闲一段时间后，或当某个会话超过上限时，回收已跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 0 可分别禁用这些单独的清理模式。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认为禁用，因此浏览器导航默认保持严格模式。 - 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止策略约束。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止规则约束。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 来配置显式例外。 -- 远程配置为仅附加模式（禁用 start/stop/reset）。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 来设置显式例外。 +- 远程配置文件仅支持附加模式（禁用启动/停止/重置）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；当你的提供商直接提供 DevTools WebSocket URL 时，请使用 WS(S)。 + 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；使用 WS(S) + 则适用于你的提供商直接给出 DevTools WebSocket URL 的情况。 - `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 - `attachOnly` CDP 的可达性检查以及打开标签页请求。受管 local loopback - 配置会保留本地 CDP 默认值。 -- 如果某个外部管理的 CDP 服务可通过 loopback 访问，请将该配置的 - `attachOnly: true` 设为 true；否则 OpenClaw 会将该 loopback 端口视为本地受管浏览器配置，并可能报告本地端口占用错误。 -- `existing-session` 配置使用 Chrome MCP 而不是 CDP，并且可以附加到所选主机上，或通过已连接的浏览器节点附加。 -- `existing-session` 配置可设置 `userDataDir`，以定位特定的 - Chromium 内核浏览器配置，例如 Brave 或 Edge。 -- `existing-session` 配置保留当前 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动的操作而非 CSS 选择器定位、单文件上传钩子、 - 不支持对话框超时覆盖、不支持 `wait --load networkidle`，并且不支持 + `attachOnly` CDP 的可达性检查以及标签页打开请求。受管的 local loopback + 配置文件仍使用本地 CDP 默认值。 +- 如果某个外部管理的 CDP 服务可通过 loopback 访问，请将该 + 配置文件的 `attachOnly: true` 打开；否则 OpenClaw 会将该 loopback 端口视为 + 本地受管浏览器配置文件，并可能报告本地端口占用错误。 +- `existing-session` 配置文件使用 Chrome MCP 而非 CDP，并且可附加到 + 所选主机上，或通过已连接的浏览器节点附加。 +- `existing-session` 配置文件可设置 `userDataDir`，以指定特定的 + 基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 +- `existing-session` 配置文件保留当前 Chrome MCP 的路由限制： + 使用 snapshot/ref 驱动的操作而非 CSS 选择器定位、单文件上传 + hooks、不支持对话框超时覆盖、不支持 `wait --load networkidle`，并且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地受管 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下才显式设置 `cdpUrl`。 -- 本地受管配置可设置 `executablePath` 以覆盖该配置的全局 - `browser.executablePath`。用它可以让一个配置运行在 Chrome 中，另一个运行在 Brave 中。 -- 本地受管配置在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 检查启动后的 CDP websocket 就绪状态。在较慢的主机上，如果 Chrome 已成功启动但就绪检查与启动过程发生竞争，请提高这些值。这两个值都必须是大于 0 且不超过 `120000` ms 的整数；无效配置值会被拒绝。 -- 自动检测顺序：默认浏览器（若为 Chromium 内核）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- `browser.executablePath` 和 `browser.profiles..executablePath` 都支持在 Chromium 启动前将 `~` 和 `~/...` 展开为你操作系统的主目录。 - `existing-session` 配置中的每配置 `userDataDir` 也会执行波浪号展开。 -- 控制服务：仅限 loopback（端口从 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会将额外启动标志附加到本地 Chromium 启动参数中（例如 +- 本地受管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下才显式设置 `cdpUrl`。 +- 本地受管配置文件可设置 `executablePath`，以覆盖该配置文件的全局 + `browser.executablePath`。你可以用它让一个配置文件运行在 + Chrome 中，另一个运行在 Brave 中。 +- 本地受管配置文件在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP + 发现，并使用 `browser.localCdpReadyTimeoutMs` 检查启动后的 CDP websocket 就绪状态。 + 在较慢的主机上，如果 Chrome 已成功启动但就绪检查与启动过程发生竞争，请提高这些值。 + 这两个值都必须是大于 0 且不超过 `120000` ms 的整数；无效配置值会被拒绝。 +- 自动检测顺序：默认浏览器（若基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- `browser.executablePath` 和 `browser.profiles..executablePath` 都 + 支持在 Chromium 启动前将 `~` 和 `~/...` 展开为你的操作系统主目录。 + `existing-session` 配置文件中的每配置文件 `userDataDir` 也支持波浪线展开。 +- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认值为 `18791`）。 +- `extraArgs` 会向本地 Chromium 启动追加额外的启动标志（例如 `--disable-gpu`、窗口大小设置或调试标志）。 --- @@ -292,14 +300,14 @@ x-i18n: seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji、短文本、图片 URL 或 data URI + avatar: "CB", // emoji, short text, image URL, or data URI }, }, } ``` - `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 身份覆盖。默认回退到活动智能体身份。 +- `assistant`：Control UI 身份覆盖。回退到当前激活智能体身份。 --- @@ -314,8 +322,8 @@ x-i18n: auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth + // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -333,9 +341,9 @@ x-i18n: basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL - // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必需 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host 标头来源回退模式 + // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs + // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -346,20 +354,20 @@ x-i18n: // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // 可选。默认 false。 + // Optional. Default false. allowRealIpFallback: false, nodes: { pairing: { - // 可选。默认未设置/禁用。 + // Optional. Default unset/disabled. autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"], }, allowCommands: ["canvas.navigate"], denyCommands: ["system.run"], }, tools: { - // 额外的 /tools/invoke HTTP 拒绝列表 + // Additional /tools/invoke HTTP denies deny: ["browser"], - // 从默认 HTTP 拒绝列表中移除工具 + // Remove tools from the default HTTP deny list allow: ["gateway"], }, push: { @@ -379,44 +387,44 @@ x-i18n: - `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 - `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 说明**：默认的 `loopback` 绑定会在容器内部监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有网络接口。 -- **身份验证**：默认必需。非 loopback 绑定要求 Gateway 网关身份验证。实际中这意味着共享 token/password，或设置 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设为 `token` 或 `password`。若两者同时配置且未设置 mode，启动以及服务安装/修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无鉴权模式。仅用于受信任的本地 local loopback 设置；新手引导提示不会提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将身份验证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 代理来源；同主机 loopback 反向代理不满足 trusted-proxy 鉴权要求。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 身份验证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头鉴权；它们仍遵循 Gateway 网关的常规 HTTP 鉴权模式。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的鉴权失败限流器。按客户端 IP 和鉴权范围应用（共享密钥和设备 token 分别独立跟踪）。被拦截的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录之前进行串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都作为普通不匹配竞争通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你有意也要对 localhost 流量进行限流（例如测试环境或严格代理部署），请设为 `false`。 -- 来自浏览器来源的 WS 鉴权尝试始终会在禁用 loopback 豁免的情况下限流（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些浏览器来源锁定会按规范化后的 `Origin` - 值隔离，因此来自某个 localhost 来源的重复失败不会自动 - 锁定另一个来源。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公网，需要身份验证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。预期从非 loopback 来源访问浏览器客户端时必须设置。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 标头来源策略的部署启用 Host 标头来源回退。 +- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关不可访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必须启用。非 loopback bind 需要 Gateway 网关认证。实际使用中，这意味着共享 token/password，或带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成一个 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设置为 `token` 或 `password`。当两者都已配置但未设置 mode 时，启动以及服务安装/修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供此选项，这是有意为之。 +- `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求 **非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 身份认证要求。内部同主机调用方可以使用 `gateway.auth.password` 作为本地直接回退；`gateway.auth.token` 仍与 trusted-proxy 模式互斥。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可满足 Control UI/WebSocket 认证要求（通过 `tailscale whois` 验证）。HTTP API 端点 **不会** 使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥与设备 token 分别独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前串行化。因此，同一客户端并发发起的错误尝试，可能会在第二个请求时触发限流器，而不是两个请求都作为普通不匹配并发通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；如果你有意希望连 localhost 流量也受到限流（用于测试环境或严格代理部署），请将其设为 `false`。 +- 来自浏览器源的 WS 认证尝试始终会启用限流，且不会豁免 loopback（作为抵御基于浏览器的 localhost 暴力破解的纵深防御）。 +- 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` + 值进行隔离，因此来自某个 localhost origin 的重复失败不会自动 + 锁定另一个 origin。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开，需要认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当浏览器客户端将从非 loopback 源发起连接时，这是必需项。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头 origin 策略的部署启用 Host 头 origin 回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量级别的 break-glass 覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍然仅允许在 loopback 上使用明文。没有对应的 `openclaw.json` 配置项，且诸如 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 之类的浏览器私有网络配置也不会影响 Gateway 网关 WebSocket 客户端。 -- `gateway.remote.token` / `.password`：远程客户端凭证字段。它们本身不会配置 Gateway 网关身份验证。 -- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后使用。该 URL 必须与编译进 iOS 构建的 relay URL 匹配。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值：`10000`。 -- 基于 relay 的注册会委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将按注册范围限定的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃生开关，用于 loopback HTTP relay URL。生产 relay URL 应保持使用 HTTPS。 -- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧套接字阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账户最多的健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：每渠道的健康监控重启退出设置，同时保留全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账户渠道中的每账户覆盖。设置后，其优先级高于渠道级覆盖。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量中的紧急覆盖开关，允许向受信任私有网络 IP 使用明文 `ws://`；默认仍然仅允许对 loopback 使用明文。没有对应的 `openclaw.json` 配置项，而诸如 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 之类的浏览器私有网络配置也不会影响 Gateway 网关 WebSocket 客户端。 +- `gateway.remote.token` / `.password`：远程客户端凭据字段。它们本身不会配置 Gateway 网关认证。 +- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。 +- 基于 relay 的注册会委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个基于注册范围的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发环境的逃生开关，允许 loopback HTTP relay URL。生产环境 relay URL 应保持为 HTTPS。 +- `gateway.channelHealthCheckMinutes`：渠道健康监视器间隔，单位为分钟。设为 `0` 可全局禁用健康监视器重启。默认值：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。应保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内允许的最大健康监视器重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：针对渠道的健康监视器重启单独退出选项，同时保留全局监视器启用状态。 +- `channels..accounts..healthMonitor.enabled`：针对多账号渠道的按账号覆盖。设置后，其优先级高于渠道级覆盖。 - 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可将 `gateway.remote.*` 用作回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，则会以关闭失败方式处理（不会使用远程回退来掩盖问题）。 -- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你可控的代理。loopback 条目对于同主机代理/本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求满足 `gateway.auth.mode: "trusted-proxy"` 的条件。 -- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，Gateway 网关接受 `X-Real-IP`。默认值为 `false`，以保持关闭失败行为。 -- `gateway.nodes.pairing.autoApproveCidrs`：用于自动批准首次节点设备配对且未请求任何 scope 的可选 CIDR/IP 允许列表。未设置时禁用。这不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、scope、元数据或公钥升级。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未能解析，则会以失败关闭方式处理（不会由远程回退进行掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。仅列出你控制的代理。loopback 条目对于同主机代理/本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们 **不会** 使 loopback 请求具备 `gateway.auth.mode: "trusted-proxy"` 的适用资格。 +- `allowRealIpFallback`：为 `true` 时，若缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以保持失败关闭行为。 +- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准首次节点设备配对，且该配对未请求任何作用域。未设置时为禁用状态。它不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 - `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局允许/拒绝整形。 -- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名（在默认拒绝列表基础上扩展）。 -- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名。 +- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。 +- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 @@ -428,14 +436,14 @@ x-i18n: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空允许列表会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false` 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。 -- 可选的响应加固标头： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） +- 可选的响应加固头： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一主机上运行多个 Gateway 网关时，请使用不同的端口和状态目录： +在同一主机上运行多个 Gateway 网关时，请使用唯一的端口和状态目录： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -445,7 +453,7 @@ openclaw gateway --port 19001 便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。 -请参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 +请参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。 ### `gateway.tls` @@ -463,11 +471,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅适用于本地/开发环境。 +- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。 +- `autoGenerate`：在未配置显式文件时自动生成本地自签名证书/密钥对；仅用于本地/开发环境。 - `certPath`：TLS 证书文件的文件系统路径。 - `keyPath`：TLS 私钥文件的文件系统路径；应限制访问权限。 -- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 +- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。 ### `gateway.reload` @@ -483,13 +491,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制配置编辑在运行时如何应用。 +- `mode`：控制运行时如何应用配置编辑。 - `"off"`：忽略实时编辑；更改需要显式重启。 - `"restart"`：配置变更时始终重启 Gateway 网关进程。 - `"hot"`：在不重启的情况下于进程内应用更改。 - - `"hybrid"`（默认）：先尝试热重载；必要时回退为重启。 -- `debounceMs`：应用配置变更前的防抖窗口（毫秒，非负整数）。 -- `deferralTimeoutMs`：可选的最大等待时间（毫秒），用于等待进行中的操作后再强制重启。省略或设为 `0` 表示无限期等待，并定期记录“仍在等待中”的警告。 + - `"hybrid"`（默认）：先尝试热重载；如果需要则回退为重启。 +- `debounceMs`：应用配置更改前的防抖窗口（毫秒）（非负整数）。 +- `deferralTimeoutMs`：可选的最大等待时间（毫秒），用于等待正在进行的操作完成，超时后强制重启。省略或设为 `0` 表示无限期等待，并定期记录“仍在等待”的警告。 --- @@ -526,47 +534,47 @@ openclaw gateway --port 19001 } ``` -身份验证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 +认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 拒绝使用查询字符串中的 hook token。 -验证和安全说明： +验证与安全说明： -- `hooks.enabled=true` 要求 `hooks.token` 为非空。 -- `hooks.token` 必须与 `gateway.auth.token` **不同**；拒绝复用 Gateway 网关 token。 -- `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 -- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果某个映射或预设使用模板化 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 且 `hooks.allowRequestSessionKey=true`。静态映射键不需要此显式启用。 +- `hooks.enabled=true` 要求提供非空的 `hooks.token`。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。 +- `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 +- 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 +- 如果某个映射或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 并启用 `hooks.allowRequestSessionKey=true`。静态映射键不需要该显式启用项。 **端点：** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - 只有当 `hooks.allowRequestSessionKey=true` 时，才接受请求负载中的 `sessionKey`（默认：`false`）。 + - 仅当 `hooks.allowRequestSessionKey=true` 时，才接受请求负载中的 `sessionKey`（默认：`false`）。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - - 模板渲染后的映射 `sessionKey` 值被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 + - 模板渲染后的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 - `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 匹配通用路径的某个负载字段。 +- `match.source` 匹配通用路径中的某个负载字段。 - 像 `{{messages[0].subject}}` 这样的模板会从负载中读取。 -- `transform` 可以指向返回 hook action 的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且必须位于 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 -- `agentId` 路由到特定智能体；未知 id 会回退到默认值。 +- `transform` 可以指向一个返回 hook 动作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且必须保留在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 +- `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 -- `defaultSessionKey`：可选的固定会话键，用于未显式指定 `sessionKey` 的 hook 智能体运行。 -- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及由模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或预设使用模板化 `sessionKey` 时，它就成为必需项。 -- `deliver: true` 会将最终回复发送到渠道；`channel` 默认为 `last`。 -- `model`：覆盖本次 hook 运行的 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的 hook 智能体运行。 +- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或 preset 使用模板化 `sessionKey` 时，它会变为必填项。 +- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 +- `model` 会为本次 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须被允许）。 ### Gmail 集成 -- 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 -- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 约束到与 Gmail 命名空间匹配，例如 `["hook:", "hook:gmail:"]`。 -- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该预设，而不是使用默认的模板化值。 +- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 +- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 限制为匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 +- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该 preset，而不要使用模板化默认值。 ```json5 { @@ -589,35 +597,35 @@ openclaw gateway --port 19001 } ``` -- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 -- 不要在 Gateway 网关旁边单独运行另一个 `gog gmail watch serve`。 +- 配置完成后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。如需禁用，请设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1`。 +- 不要在 Gateway 网关之外另外运行一个独立的 `gog gmail watch serve`。 --- -## Canvas host +## Canvas 主机 ```json5 { canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // 或 OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- 通过 Gateway 网关端口下的 HTTP 提供由智能体可编辑的 HTML/CSS/JS 和 A2UI： +- 在 Gateway 网关端口下通过 HTTP 提供可由智能体编辑的 HTML/CSS/JS 和 A2UI： - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- 仅本地：保持 `gateway.bind: "loopback"`（默认）。 -- 非 loopback 绑定：canvas 路由和其他 Gateway 网关 HTTP 界面一样，需要 Gateway 网关身份验证（token/password/trusted-proxy）。 -- 节点 WebView 通常不会发送鉴权标头；在节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告节点范围的 capability URL。 -- Capability URL 绑定到活动节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。 -- 会向所提供的 HTML 中注入 live-reload 客户端。 -- 为空时会自动创建起始 `index.html`。 +- 仅限本地：请保持 `gateway.bind: "loopback"`（默认）。 +- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 表面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。 +- 节点 WebView 通常不会发送认证头；节点完成配对并连接后，Gateway 网关会通告节点作用域的能力 URL，用于访问 canvas/A2UI。 +- 能力 URL 绑定到当前活动的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。 +- 会将 live-reload 客户端注入到所提供的 HTML 中。 +- 为空时会自动创建初始 `index.html`。 - 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 - 更改需要重启 Gateway 网关。 -- 对于大型目录或出现 `EMFILE` 错误时，请禁用实时重载。 +- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 --- @@ -635,9 +643,9 @@ openclaw gateway --port 19001 } ``` -- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 +- `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。 - `full`：包含 `cliPath` + `sshPort`。 -- 主机名默认使用系统主机名（当其是有效 DNS 标签时），否则回退为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 +- 主机名在其为有效 DNS 标签时默认使用系统主机名，否则回退为 `openclaw`。可使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 ### 广域（DNS-SD） @@ -649,7 +657,7 @@ openclaw gateway --port 19001 } ``` -在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若要实现跨网络设备发现，请与 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS 搭配使用。 +会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 设置：`openclaw dns setup --apply`。 @@ -674,10 +682,10 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境中缺少相应键时，才会应用内联环境变量。 +- 仅当进程环境中缺少该键时，才会应用内联环境变量。 - `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 - `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 -- 完整优先级请参见 [环境](/zh-CN/help/environment)。 +- 完整优先级请参见 [Environment](/zh-CN/help/environment)。 ### 环境变量替换 @@ -692,9 +700,9 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/空环境变量会在加载配置时抛出错误。 -- 使用 `$${VAR}` 来表示字面量 `${VAR}`。 -- 对 `$include` 同样有效。 +- 缺失或为空的变量会在配置加载时抛出错误。 +- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 +- 适用于 `$include`。 --- @@ -704,25 +712,25 @@ SecretRef 是增量式的：明文值仍然可用。 ### `SecretRef` -使用一种对象形式： +使用以下对象结构： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } ``` -校验规则： +验证规则： - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`） - `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` 的 id 不得包含 `.` 或 `..` 这类以斜杠分隔的路径段（例如 `a/../b` 会被拒绝） +- `source: "exec"` 的 id 不得包含 `.` 或 `..` 这类按斜杠分隔的路径段（例如 `a/../b` 会被拒绝） -### 支持的凭证界面 +### 支持的凭据表面 -- 标准矩阵：[SecretRef 凭证界面](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。 -- `auth-profiles.json` 中的引用也包含在运行时解析和审计覆盖范围内。 +- 标准矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 作用于受支持的 `openclaw.json` 凭据路径。 +- `auth-profiles.json` 引用也包含在运行时解析和审计覆盖范围内。 ### Secret 提供商配置 @@ -730,7 +738,7 @@ SecretRef 是增量式的：明文值仍然可用。 { secrets: { providers: { - default: { source: "env" }, // 可选的显式 env 提供商 + default: { source: "env" }, // optional explicit env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -754,18 +762,18 @@ SecretRef 是增量式的：明文值仍然可用。 说明： -- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 -- 当 Windows ACL 验证不可用时，file 和 exec 提供商路径会以关闭失败方式处理。仅对无法验证但你信任的路径设置 `allowInsecurePath: true`。 -- `exec` 提供商要求 `command` 为绝对路径，并通过 stdin/stdout 使用协议负载。 -- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍会验证解析后的目标路径。 -- 如果配置了 `trustedDirs`，受信任目录检查会作用于解析后的目标路径。 +- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- 当无法验证 Windows ACL 时，file 和 exec provider 路径会以失败关闭方式处理。仅在受信任且无法验证的路径上设置 `allowInsecurePath: true`。 +- `exec` provider 要求 `command` 为绝对路径，并通过 stdin/stdout 使用协议负载。 +- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍验证解析后的目标路径。 +- 如果配置了 `trustedDirs`，则受信任目录检查会应用于解析后的目标路径。 - `exec` 子进程环境默认最小化；请使用 `passEnv` 显式传递所需变量。 -- Secret 引用会在激活时解析为内存快照，之后请求路径只读取该快照。 -- 激活期间会应用活动界面过滤：已启用界面上的未解析引用会导致启动/重载失败，而非活动界面会被跳过并记录诊断信息。 +- Secret 引用会在激活时解析为内存中的快照，随后请求路径仅从该快照中读取。 +- 激活期间会应用活跃表面过滤：启用表面上的未解析引用会导致启动/重载失败，而非活跃表面会被跳过并记录诊断信息。 --- -## 身份验证存储 +## 凭证存储 ```json5 { @@ -783,13 +791,13 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 每个智能体的配置存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持值级引用（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- OAuth 模式配置（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清除。 +- 每个智能体的 profile 存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持值级别引用（静态凭据模式中，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- OAuth 模式的 profile（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭据。 +- 静态运行时凭据来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会清理掉。 - 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。 - 请参见 [OAuth](/zh-CN/concepts/oauth)。 -- Secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [Secrets 管理](/zh-CN/gateway/secrets)。 +- Secrets 运行时行为以及 `audit/configure/apply` 工具：请参见 [Secrets Management](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -811,20 +819,19 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `billingBackoffHours`：当某个配置因真实的 - 计费/余额不足错误失败时使用的基础退避时间（小时，默认：`5`）。即使响应为 `401`/`403`，显式计费文本 - 仍可能落入这里，但提供商专属文本 - 匹配器仍仅限于其所属提供商（例如 OpenRouter - `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或 +- `billingBackoffHours`：当某个 profile 因真实的 + 计费/余额不足错误而失败时的基础退避时长（小时）（默认值：`5`）。即使在 `401`/`403` 响应上，显式计费文本 + 仍可能归入此类，但 provider 特定的文本匹配器仍限定在拥有它们的 provider 范围内（例如 OpenRouter 的 + `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 organization/workspace 支出上限消息则仍归入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按提供商划分的计费退避时间覆盖（小时）。 -- `billingMaxHours`：计费退避指数增长的上限（小时，默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时间（分钟，默认：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限（分钟，默认：`60`）。 -- `failureWindowHours`：用于退避计数器的滚动时间窗口（小时，默认：`24`）。 -- `overloadedProfileRotations`：针对过载错误，在切换到模型回退之前，同一提供商 auth-profile 最多轮换次数（默认：`1`）。诸如 `ModelNotReadyException` 之类的提供商繁忙形态归入此项。 -- `overloadedBackoffMs`：在重试过载提供商/配置轮换之前的固定延迟（毫秒，默认：`0`）。 -- `rateLimitedProfileRotations`：针对限流错误，在切换到模型回退之前，同一提供商 auth-profile 最多轮换次数（默认：`1`）。该限流桶包括提供商特定文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 +- `billingBackoffHoursByProvider`：按 provider 覆盖计费退避小时数的可选配置。 +- `billingMaxHours`：计费退避指数增长的小时上限（默认值：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时长（分钟）（默认值：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认值：`60`）。 +- `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认值：`24`）。 +- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退之前，同一 provider 内允许的最大 auth-profile 轮换次数（默认值：`1`）。诸如 `ModelNotReadyException` 之类的 provider 忙碌形态会归入此类。 +- `overloadedBackoffMs`：在重试 overloaded provider/profile 轮换之前的固定延迟（默认值：`0`）。 +- `rateLimitedProfileRotations`：对于限流错误，在切换到模型回退之前，同一 provider 内允许的最大 auth-profile 轮换次数（默认值：`1`）。该限流桶包括 provider 形态文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -846,8 +853,8 @@ SecretRef 是增量式的：明文值仍然可用。 - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 设置 `logging.file` 可使用稳定路径。 - 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：轮转前活动日志文件的最大大小（字节，正整数；默认：`104857600` = 100 MB）。OpenClaw 会在活动文件旁边最多保留五个带编号的归档文件。 -- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录以及持久化会话 transcript 文本进行尽力脱敏。 +- `maxFileBytes`：轮转前活动日志文件的最大大小（字节）（正整数；默认值：`104857600` = 100 MB）。OpenClaw 会在活动文件旁最多保留五个带编号的归档文件。 +- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录以及持久化会话转录文本进行尽力脱敏。 --- @@ -896,24 +903,24 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - `enabled`：instrumentation 输出的总开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持通配符，如 `"telegram.*"` 或 `"*"`）。 -- `stuckSessionWarnMs`：当会话持续处于 processing 状态时，用于发出卡住会话警告的年龄阈值（毫秒）。 -- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。完整配置、信号目录和隐私模型请参见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 +- `flags`：启用定向日志输出的标志字符串数组（支持如 `"telegram.*"` 或 `"*"` 这样的通配符）。 +- `stuckSessionWarnMs`：当会话仍处于处理中状态时，发出卡住会话警告的时间阈值（毫秒）。 +- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。完整配置、信号目录和隐私模型请参见 [OpenTelemetry export](/zh-CN/gateway/opentelemetry)。 - `otel.endpoint`：用于 OTel 导出的 collector URL。 -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的按信号划分的 OTLP 端点。设置后，它们会仅对对应信号覆盖 `otel.endpoint`。 +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的按信号划分的 OTLP 端点。设置后，它们仅针对对应信号覆盖 `otel.endpoint`。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据标头。 +- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据头。 - `otel.serviceName`：资源属性中的服务名称。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 -- `otel.sampleRate`：trace 采样率 `0`–`1`。 -- `otel.flushIntervalMs`：定期刷新 telemetry 的间隔（毫秒）。 -- `otel.captureContent`：选择性启用 OTEL span 属性中的原始内容捕获。默认关闭。布尔值 `true` 会捕获非 system 的消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于最新实验性 GenAI span 提供商属性的环境变量开关。默认情况下，为了兼容性，span 会保留旧版 `gen_ai.system` 属性；GenAI metrics 使用有界语义属性。 -- `OPENCLAW_OTEL_PRELOADED=1`：适用于已注册全局 OpenTelemetry SDK 的宿主环境的环境变量开关。OpenClaw 随后会跳过由插件拥有的 SDK 启动/关闭流程，同时保持诊断监听器处于活动状态。 -- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：当对应配置键未设置时使用的按信号划分的端点环境变量。 -- `cacheTrace.enabled`：为内置运行记录缓存跟踪快照（默认：`false`）。 -- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认均为 `true`）。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 logs 导出。 +- `otel.sampleRate`：trace 采样率，范围 `0`–`1`。 +- `otel.flushIntervalMs`：周期性刷新遥测数据的时间间隔（毫秒）。 +- `otel.captureContent`：选择启用将原始内容捕获为 OTEL span 属性。默认关闭。布尔值 `true` 会捕获非 system 的消息/工具内容；对象形式则允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：环境开关，用于启用最新实验性 GenAI span provider 属性。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI metrics 则使用有界语义属性。 +- `OPENCLAW_OTEL_PRELOADED=1`：环境开关，用于那些已经注册了全局 OpenTelemetry SDK 的主机。此时 OpenClaw 会跳过插件自有的 SDK 启动/关闭流程，同时保持诊断监听器处于活动状态。 +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：当对应配置键未设置时使用的按信号划分端点环境变量。 +- `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认：`false`）。 +- `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含哪些内容（默认均为：`true`）。 --- @@ -938,9 +945,9 @@ SecretRef 是增量式的：明文值仍然可用。 - `channel`：用于 npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 - `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。 - `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 -- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟（小时，默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：稳定渠道发布扩散窗口的额外时长（小时，默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查运行的频率（小时，默认：`1`；最大：`24`）。 +- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟（小时）（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：stable 渠道额外发布扩散窗口（小时）（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行的频率（小时）（默认：`1`；最大：`24`）。 --- @@ -973,22 +980,22 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：ACP 功能的全局开关（默认：`true`；设为 `false` 可隐藏 ACP 调度和生成入口）。 -- `dispatch.enabled`：ACP 会话轮次调度的独立开关（默认：`true`）。设为 `false` 可保留 ACP 命令可用，但阻止执行。 +- `enabled`：全局 ACP 功能开关（默认：`true`；设为 `false` 可隐藏 ACP 调度和派生相关入口）。 +- `dispatch.enabled`：ACP 会话轮次调度的独立开关（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 - `backend`：默认 ACP 运行时后端 id（必须与已注册的 ACP 运行时插件匹配）。 - 如果设置了 `plugins.allow`，请包含后端插件 id（例如 `acpx`），否则内置默认插件将不会加载。 -- `defaultAgent`：当生成未指定显式目标时，ACP 的后备目标智能体 id。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示不施加额外限制。 -- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。 + 如果设置了 `plugins.allow`，请包含该后端插件 id（例如 `acpx`），否则内置默认插件不会加载。 +- `defaultAgent`：当派生未指定显式目标时，ACP 的回退目标智能体 id。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；空值表示不做额外限制。 +- `maxConcurrentSessions`：ACP 会话最大并发活动数。 - `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。 - `stream.maxChunkChars`：分割流式分块投影前的最大分块大小。 -- `stream.repeatSuppression`：每轮抑制重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 递增流式传输；`"final_only"` 则缓冲到轮次终止事件后再输出。 +- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。 +- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终止事件后再输出。 - `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。 - `stream.maxOutputChars`：每个 ACP 轮次投影的智能体输出最大字符数。 - `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行最大字符数。 -- `stream.tagVisibility`：tag 名称到布尔可见性覆盖的记录，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话工作进程在符合清理条件前的空闲 TTL（分钟）。 +- `stream.tagVisibility`：记录 tag 名称到布尔可见性覆盖的映射，用于流式事件。 +- `runtime.ttlMinutes`：ACP 会话 worker 空闲后可被清理的 TTL（分钟）。 - `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 --- @@ -1006,9 +1013,9 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换的有趣/季节性标语。 - - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 + - `"random"`（默认）：轮换的趣味/季节性标语。 + - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`：不显示标语文本（仍会显示 banner 标题/版本）。 - 若要隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -1033,15 +1040,15 @@ SecretRef 是增量式的：明文值仍然可用。 ## 身份 -请参见 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下 `agents.list` 的身份字段。 +请参见 [Agent defaults](/zh-CN/gateway/config-agents#agent-defaults) 下 `agents.list` 的身份字段。 --- -## Bridge protocol（旧版节点，历史参考）（旧版，已移除） +## Bridge protocol（旧版节点，历史参考） -当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以剥离未知键）。 +当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前会导致验证失败；`openclaw doctor --fix` 可删除未知键）。 - + ```json { @@ -1067,23 +1074,23 @@ SecretRef 是增量式的：明文值仍然可用。 { cron: { enabled: true, - maxConcurrentRuns: 2, // cron 调度 + 隔离的 cron 智能体轮次执行 - webhook: "https://example.invalid/legacy", // 已弃用，用于已存储 notify:true 任务的后备项 - webhookToken: "replace-with-dedicated-token", // 用于出站 webhook 鉴权的可选 bearer token - sessionRetention: "24h", // 时长字符串或 false + maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution + webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs + webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth + sessionRetention: "24h", // duration string or false runLog: { - maxBytes: "2mb", // 默认 2_000_000 字节 - keepLines: 2000, // 默认 2000 + maxBytes: "2mb", // default 2_000_000 bytes + keepLines: 2000, // default 2000 }, }, } ``` -- `sessionRetention`：完成的隔离 cron 运行会话在从 `sessions.json` 清理前保留多长时间。也控制已归档已删除 cron transcript 的清理。默认：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在清理前的最大大小。默认：`2_000_000` 字节。 +- `sessionRetention`：在从 `sessions.json` 清理前，已完成的隔离 cron 运行会话保留多长时间。也控制已归档、已删除 cron 转录的清理。默认：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发清理前的最大大小。默认：`2_000_000` 字节。 - `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认：`2000`。 -- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略则不会发送鉴权标头。 -- `webhook`：已弃用的旧版后备 webhook URL（http/https），仅用于仍然带有 `notify: true` 的已存储任务。 +- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略则不会发送认证头。 +- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储作业。 ### `cron.retry` @@ -1099,11 +1106,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `maxAttempts`：一次性任务在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试的退避延迟数组（毫秒，默认：`[30000, 60000, 300000]`；1–10 项）。 -- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则会重试所有瞬时错误类型。 +- `maxAttempts`：一次性作业在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试所用的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时表示重试所有瞬时类型。 -仅适用于一次性 cron 任务。周期性任务使用单独的失败处理方式。 +仅适用于一次性 cron 作业。重复性作业使用独立的失败处理机制。 ### `cron.failureAlert` @@ -1122,12 +1129,12 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：启用 cron 任务失败告警（默认：`false`）。 -- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。 -- `cooldownMs`：同一任务重复告警之间的最小间隔（毫秒，非负整数）。 +- `enabled`：启用 cron 作业失败告警（默认：`false`）。 +- `after`：在触发告警之前连续失败的次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复告警之间的最小间隔（毫秒）（非负整数）。 - `includeSkipped`：是否将连续跳过的运行计入告警阈值（默认：`false`）。跳过的运行会单独跟踪，不影响执行错误退避。 -- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发送 POST。 -- `accountId`：用于限定告警投递范围的可选账户或渠道 id。 +- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发起 POST。 +- `accountId`：用于限定告警投递范围的可选账号或渠道 id。 ### `cron.failureDestination` @@ -1144,16 +1151,16 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 所有任务共享的 cron 失败通知默认目标。 +- 所有作业的 cron 失败通知默认目标。 - `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。 -- `channel`：announce 投递的渠道覆盖。`"last"` 会复用最后一次已知投递渠道。 -- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必需。 -- `accountId`：可选的投递账户覆盖。 -- 每个任务的 `delivery.failureDestination` 会覆盖此全局默认值。 -- 当全局和每任务失败目标都未设置时，已经通过 `announce` 投递的任务会在失败时回退到该主 announce 目标。 -- `delivery.failureDestination` 仅对 `sessionTarget="isolated"` 的任务受支持，除非该任务的主 `delivery.mode` 为 `"webhook"`。 +- `channel`：announce 投递的渠道覆盖。`"last"` 会复用上次已知的投递渠道。 +- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。 +- `accountId`：可选的投递账号覆盖。 +- 每个作业的 `delivery.failureDestination` 会覆盖这个全局默认值。 +- 当全局和每作业失败目标都未设置时，已经通过 `announce` 投递的作业在失败时会回退到其主 announce 目标。 +- `delivery.failureDestination` 仅对 `sessionTarget="isolated"` 的作业受支持，除非该作业的主 `delivery.mode` 为 `"webhook"`。 -请参见 [Cron 任务](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 +请参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 --- @@ -1161,34 +1168,34 @@ SecretRef 是增量式的：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| Variable | 描述 | -| ------------------ | ------------------------------------- | -| `{{Body}}` | 完整的入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） | -| `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 id | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新建会话时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频 transcript | -| `{{Prompt}}` | CLI 条目的已解析媒体 prompt | -| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力而为） | -| `{{GroupMembers}}` | 群组成员预览（尽力而为） | -| `{{SenderName}}` | 发送者显示名称（尽力而为） | -| `{{SenderE164}}` | 发送者电话号码（尽力而为） | -| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | +| Variable | 说明 | +| ------------------ | ---- | +| `{{Body}}` | 完整的入站消息正文 | +| `{{RawBody}}` | 原始正文（不含历史记录/发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 id | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 新会话创建时为 `"true"` | +| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image/audio/document/…） | +| `{{Transcript}}` | 音频转录文本 | +| `{{Prompt}}` | CLI 条目的已解析媒体提示词 | +| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名称（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| `{{Provider}}` | provider 提示（whatsapp、telegram、discord 等） | --- ## 配置包含（`$include`） -将配置拆分为多个文件： +将配置拆分到多个文件中： ```json5 // ~/.openclaw/openclaw.json @@ -1203,20 +1210,20 @@ SecretRef 是增量式的：明文值仍然可用。 **合并行为：** -- 单文件：替换所在的整个对象。 +- 单个文件：替换所在的对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在包含内容之后合并（覆盖包含值）。 -- 嵌套包含：最多支持 10 层。 -- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许。 -- 当 OpenClaw 持有的写入仅更改单个由单文件 include 支持的顶层部分时，会透传写入该被包含文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。 -- 对于根级 include、include 数组，以及带有同级覆盖的 include，OpenClaw 持有的写入是只读的；此类写入会以关闭失败方式处理，而不是将配置拍平成单个文件。 -- 错误：对缺失文件、解析错误和循环包含提供清晰提示。 +- 同级键：在包含项之后合并（覆盖包含的值）。 +- 嵌套包含：最多 10 层深。 +- 路径：相对于包含它的文件解析，但必须保留在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许使用。 +- 仅更改由单文件 include 支持的某个顶层 section 的 OpenClaw 自有写入操作，会直接写回该包含文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。 +- 根级 include、include 数组，以及带同级覆盖的 include 对 OpenClaw 自有写入操作而言是只读的；这些写入会以失败关闭方式处理，而不是将配置扁平化。 +- 错误：对缺失文件、解析错误和循环包含提供清晰的错误消息。 --- -_相关：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ +_相关内容：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ ## 相关 -- [配置](/zh-CN/gateway/configuration) -- [配置示例](/zh-CN/gateway/configuration-examples) +- [Configuration](/zh-CN/gateway/configuration) +- [Configuration examples](/zh-CN/gateway/configuration-examples) diff --git a/docs/zh-CN/gateway/doctor.md b/docs/zh-CN/gateway/doctor.md index faed6ed89..114445eb0 100644 --- a/docs/zh-CN/gateway/doctor.md +++ b/docs/zh-CN/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - 添加或修改 Doctor 迁移 - - 引入破坏性配置更改 + - 引入破坏性配置变更 sidebarTitle: Doctor summary: Doctor 命令：健康检查、配置迁移和修复步骤 title: Doctor x-i18n: - generated_at: "2026-04-27T13:49:01Z" + generated_at: "2026-04-27T22:22:33Z" model: gpt-5.4 provider: openai - source_hash: 1f3a009131c28a0574ce2bb055beecbb321e1664d1ab5b611c64c3f548cda1c6 + source_hash: 5af15cf2f9616286d601518872b736c9e07d5aabb4943c483bd35aa9e3bdc77a source_path: gateway/doctor.md workflow: 15 --- -`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过期的配置/状态、检查健康状况，并提供可执行的修复步骤。 +`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的配置/状态，检查健康状况，并提供可执行的修复步骤。 ## 快速开始 @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - 接受默认选项而不提示（包括在适用时的重启/服务/沙箱修复步骤）。 + 接受默认选项而不提示（在适用时，包括重启/服务/沙箱修复步骤）。 @@ -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 ``` - 在无提示的情况下运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态时，会自动运行旧版状态迁移。 + 无提示运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。会跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态时，会自动运行旧版状态迁移。 @@ -62,7 +62,7 @@ openclaw doctor openclaw doctor --deep ``` - 扫描系统服务以查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。 + 扫描系统服务以查找额外的 Gateway 网关安装（`launchd`/`systemd`/`schtasks`）。 @@ -73,76 +73,76 @@ openclaw doctor cat ~/.openclaw/openclaw.json ``` -## 它会做什么（摘要） +## 它会执行什么操作（摘要） - - 针对 git 安装的可选预检更新（仅交互模式）。 + - 为 git 安装提供可选的预检更新（仅交互模式）。 - UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。 - 健康检查 + 重启提示。 - - Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。 + - Skills 状态摘要（可用/缺失/被阻止）和插件状态。 - - 针对旧版值的配置规范化。 - - 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 + - 旧版值的配置规范化。 + - 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 - 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。 - - OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。 + - OpenCode provider 覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。 - Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。 - - 针对 OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。 - - 旧版磁盘状态迁移（sessions/agent 目录/WhatsApp 凭证）。 - - 旧版插件 manifest 合同键迁移（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。 - - 旧版 cron 存储迁移（`jobId`, `schedule.cron`, 顶层 delivery/payload 字段，payload `provider`，简单的 `notify: true` webhook 回退任务）。 - - 将旧版 agent 运行时策略迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。 + - OpenAI Codex OAuth 配置的 OAuth TLS 前置条件检查。 + - 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。 + - 旧版插件清单契约键迁移（`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`。 - - 会话锁文件检查和陈旧锁清理。 - - 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支会话转录。 - - 状态完整性和权限检查（sessions、transcripts、状态目录）。 + - 会话锁文件检查和过时锁清理。 + - 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支的会话转录。 + - 状态完整性和权限检查（会话、转录、状态目录）。 - 本地运行时的配置文件权限检查（`chmod 600`）。 - - 模型认证健康检查：检查 OAuth 过期情况，可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。 + - 模型认证健康状况：检查 OAuth 过期时间、可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。 - 额外工作区目录检测（`~/openclaw`）。 - - 在启用沙箱隔离时修复沙箱镜像。 + - 在启用沙箱隔离时执行沙箱镜像修复。 - 旧版服务迁移和额外 Gateway 网关检测。 - Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。 - - Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。 + - 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`）。 - 针对开放私信策略的安全警告。 - - local token 模式的 Gateway 网关认证检查（在没有 token 来源时提供生成 token；不会覆盖 token SecretRef 配置）。 - - 设备配对问题检测（首次配对请求待处理、角色/作用域升级待处理、陈旧的本地设备 token 缓存漂移，以及已配对记录的认证漂移）。 + - 本地令牌模式的 Gateway 网关认证检查（当不存在令牌来源时提供令牌生成功能；不会覆盖 token SecretRef 配置）。 + - 设备配对问题检测（首次配对请求待处理、角色/作用域升级待处理、本地设备令牌缓存漂移过时，以及已配对记录的认证漂移）。 - - Linux 上的 systemd linger 检查。 - - 工作区 bootstrap 文件大小检查（上下文文件的截断/接近限制警告）。 + - Linux 上的 `systemd linger` 检查。 + - 工作区 bootstrap 文件大小检查（上下文文件的截断/接近上限警告）。 - shell 补全状态检查和自动安装/升级。 - - Memory 搜索嵌入提供商就绪状态检查（本地模型、远程 API key 或 QMD 二进制文件）。 - - 源码安装检查（pnpm 工作区不匹配、缺失 UI 资源、缺失 tsx 二进制文件）。 + - Memory 搜索 embedding 提供商就绪状态检查（本地模型、远程 API 密钥或 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** 只会移除那些来自历史回放、且尚未积累实时 recall 或每日支持的 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 迁移 -- 不会自动将 grounded 候选项暂存到实时短期提升存储中，除非你先显式运行 staged CLI 路径 +- 不会自动将 grounded 候选项暂存到实时短期提升存储中，除非你先明确运行 staged CLI 路径 如果你想让 grounded 历史回放影响正常的深度提升流程，请改用以下 CLI 流程： @@ -150,30 +150,30 @@ Control UI 的 Dreams 场景包含用于 grounded dreaming 工作流的 **Backfi openclaw memory rem-backfill --path ./memory --stage-short-term ``` -这样会将 grounded 持久候选项暂存到短期 dreaming 存储中，同时将 `DREAMS.md` 作为审查界面。 +这会将 grounded 持久候选项暂存到短期 dreaming 存储中，同时将 `DREAMS.md` 作为审查界面。 -## 详细行为和原理 +## 详细行为和原因说明 - 如果这是一个 git 检出，并且 doctor 以交互模式运行，它会先提供在运行 doctor 之前更新（fetch/rebase/build）的选项。 + 如果这是一个 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` 结构重写到提供商映射中。 + 这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置为 `talk.provider` + `talk.providers.`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 结构重写到提供商映射中。 当配置包含已弃用的键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。 - Doctor 会： + Doctor 将会： - 说明发现了哪些旧版键。 - 显示它应用的迁移。 - 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。 - Gateway 网关在启动时检测到旧版配置格式时也会自动运行 doctor 迁移，因此过期配置无需手动干预即可修复。Cron 任务存储迁移由 `openclaw doctor --fix` 处理。 + 当 Gateway 网关在启动时检测到旧版配置格式，也会自动运行 doctor 迁移，因此过时配置无需手动干预即可修复。Cron 任务存储迁移由 `openclaw doctor --fix` 处理。 当前迁移包括： @@ -187,273 +187,273 @@ 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`；慢速提供商/模型超时请使用 `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` 被设置为未来或未知枚举值的提供商，而不是以封闭失败方式直接报错） + - 删除 `browser.relayBindHost`（旧版扩展 relay 设置） + - 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 设置为未来或未知枚举值的提供商，而不是直接失败关闭） - Doctor 警告还包括多账户渠道的默认账户指引： + Doctor 警告还包括针对多账户渠道的默认账户指导： - - 如果在没有 `channels..defaultAccount` 或 `accounts.default` 的情况下配置了两个或更多 `channels..accounts` 条目，doctor 会警告回退路由可能会选择意外的账户。 + - 如果配置了两个或更多 `channels..accounts` 条目，但没有 `channels..defaultAccount` 或 `accounts.default`，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 路径： + 当你使用 `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`） + - 提醒你在浏览器检查页面启用远程调试（例如 `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 会输出特定于平台的修复指导。在使用 Homebrew Node 的 macOS 上，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，该探测也会运行。 - - 如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽较新版本自动使用的内置 Codex OAuth 提供商路径。当 doctor 看到这些旧的传输设置与 Codex OAuth 同时存在时，会发出警告，以便你移除或重写过期的传输覆盖，从而恢复内置路由/回退行为。自定义代理和仅头部覆盖仍受支持，不会触发此警告。 + + 如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽新版本自动使用的内置 Codex OAuth provider 路径。当 doctor 在 Codex OAuth 旁边看到这些旧传输设置时，会发出警告，以便你移除或重写过时的传输覆盖，并恢复内置的路由/回退行为。自定义代理和仅标头覆盖仍受支持，不会触发此警告。 - 启用内置 Codex 插件时，doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI 运行器解析。当你想通过 PI 使用 Codex OAuth/订阅认证时，这种组合是有效的，但它很容易与原生 Codex app-server harness 混淆。Doctor 会发出警告，并指向显式的 app-server 形式：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。 + 当启用内置 Codex 插件时，doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认的 PI runner 解析。当你希望通过 PI 使用 Codex OAuth/订阅认证时，这种组合是有效的，但它很容易与原生 Codex app-server harness 混淆。Doctor 会发出警告，并指向明确的 app-server 形态：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。 - Doctor 不会自动修复这一点，因为这两种路由都有效： + Doctor 不会自动修复这一点，因为这两条路径都有效： - - `openai-codex/*` + PI 表示“通过正常的 OpenClaw 运行器使用 Codex OAuth/订阅认证。” - - `openai/*` + `runtime: "codex"` 表示“通过原生 Codex app-server 运行嵌入式回合。” - - `/codex ...` 表示“从聊天中控制或绑定一个原生 Codex 会话。” + - `openai-codex/*` + PI 表示“通过普通 OpenClaw runner 使用 Codex OAuth/订阅认证。” + - `openai/*` + `runtime: "codex"` 表示“通过原生 Codex app-server 运行嵌入式轮次。” + - `/codex ...` 表示“从聊天中控制或绑定原生 Codex 对话。” - `/acp ...` 或 `runtime: "acp"` 表示“使用外部 ACP/acpx 适配器。” - 如果出现此警告，请选择你原本想使用的路由并手动编辑配置。如果是有意使用 PI Codex OAuth，请保持该警告不变。 + 如果出现此警告，请选择你原本想使用的路径并手动编辑配置。如果有意使用 PI Codex OAuth，请保持该警告原样不动。 - Doctor 可以将旧版磁盘布局迁移到当前结构： + Doctor 可以将较旧的磁盘布局迁移到当前结构： - 会话存储 + 转录： - - 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents//sessions/` - - Agent 目录： - - 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents//agent/` + - 从 `~/.openclaw/sessions/` 迁移到 `~/.openclaw/agents//sessions/` + - 智能体目录： + - 从 `~/.openclaw/agent/` 迁移到 `~/.openclaw/agents//agent/` - WhatsApp 认证状态（Baileys）： - 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外） - - 到 `~/.openclaw/credentials/whatsapp//...`（默认账户 ID：`default`） + - 迁移到 `~/.openclaw/credentials/whatsapp//...`（默认账户 ID：`default`） - 这些迁移采用尽力而为且幂等的方式；当 doctor 将任何旧目录作为备份保留下来时，会发出警告。Gateway 网关/CLI 在启动时也会自动迁移旧版 sessions + agent 目录，因此历史记录/认证/模型会进入每个 agent 的路径，而无需手动运行 doctor。WhatsApp 认证则有意仅通过 `openclaw doctor` 迁移。Talk provider/提供商映射规范化现在按结构相等性比较，因此仅键顺序不同的差异不再触发重复的空操作 `doctor --fix` 更改。 + 这些迁移尽力而为，并且是幂等的；如果 doctor 保留了任何旧版文件夹作为备份，它会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + 智能体目录，因此历史记录/认证/模型会落到每个智能体的路径下，而无需手动运行 doctor。WhatsApp 认证有意仅通过 `openclaw doctor` 迁移。Talk provider/provider 映射规范化现在按结构相等性进行比较，因此仅键顺序不同将不再触发重复的无操作 `doctor --fix` 更改。 - - Doctor 会扫描所有已安装插件的 manifest，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到后，它会建议将它们移入 `contracts` 对象，并原地重写 manifest 文件。该迁移是幂等的；如果 `contracts` 键中已包含相同值，则会移除旧键而不会重复数据。 + + Doctor 会扫描所有已安装的插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。发现后，它会提供将它们移动到 `contracts` 对象中，并原地重写清单文件。此迁移是幂等的；如果 `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` + - payload `provider` 交付别名 → 显式 `delivery.channel` + - 简单旧版 `notify: true` webhook 回退任务 → 显式 `delivery.mode="webhook"` 且 `delivery.to=cron.webhook` - Doctor 只会在能够不改变行为的情况下自动迁移 `notify: true` 任务。如果某个任务将旧版 notify 回退与现有的非 webhook delivery 模式组合在一起，doctor 会发出警告，并将该任务留给你手动审查。 + 只有在不改变行为的情况下，Doctor 才会自动迁移 `notify: true` 任务。如果某个任务将旧版 notify 回退与现有的非 webhook 交付模式组合使用，doctor 会发出警告，并将该任务留给你手动审查。 - Doctor 会扫描每个 agent 会话目录中的陈旧写锁文件——这些文件通常是会话异常退出后遗留的。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍存活、锁年龄，以及是否被视为陈旧（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除陈旧锁文件；否则，它会打印说明并提示你使用 `--fix` 重新运行。 + Doctor 会扫描每个智能体会话目录中的过时写锁文件——即会话异常退出后遗留的文件。对于发现的每个锁文件，它会报告：路径、PID、该 PID 是否仍存活、锁的存在时长，以及它是否被视为过时（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动删除过时锁文件；否则它会输出说明，并指示你使用 `--fix` 重新运行。 - Doctor 会扫描 agent 会话 JSONL 文件，查找由 2026.4.24 prompt transcript 重写 bug 产生的重复分支结构：一个被放弃的用户回合包含 OpenClaw 内部运行时上下文，另一个活跃的同级分支包含相同的可见用户提示。在 `--fix` / `--repair` 模式下，doctor 会在原文件旁边备份每个受影响文件，并将转录重写为活跃分支，这样 Gateway 网关历史记录和 Memory 读取器就不会再看到重复回合。 + Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 prompt transcript 重写 bug 产生的重复分支结构：一个被放弃的用户轮次包含 OpenClaw 内部运行时上下文，同时一个活跃的同级分支包含相同的可见用户提示。在 `--fix` / `--repair` 模式下，doctor 会在原文件旁边备份每个受影响的文件，并将转录重写为活跃分支，这样 Gateway 网关历史记录和 Memory 读取器就不会再看到重复轮次。 - 状态目录是运行中的“脑干”。如果它消失，你将失去会话、凭证、日志和配置（除非你在其他地方有备份）。 + 状态目录是运行层面的中枢。如果它消失了，你将丢失会话、凭证、日志和配置（除非你在其他地方有备份）。 Doctor 会检查： - **状态目录缺失**：警告灾难性的状态丢失，提示重新创建目录，并提醒你它无法恢复丢失的数据。 - - **状态目录权限**：验证可写性；提供修复权限的选项（当检测到所有者/组不匹配时，还会给出 `chown` 提示）。 + - **状态目录权限**：验证是否可写；提供修复权限的选项（并在检测到所有者/组不匹配时输出 `chown` 提示）。 - **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为基于同步的路径可能导致更慢的 I/O 以及锁/同步竞争。 - - **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入下可能更慢且磨损更快。 + - **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为由 SD 或 eMMC 支持的随机 I/O 在会话和凭证写入时可能更慢且磨损更快。 - **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史记录并避免 `ENOENT` 崩溃所必需的。 - **转录不匹配**：当最近的会话条目缺少转录文件时发出警告。 - - **主会话“单行 JSONL”**：当主转录只有一行时进行标记（历史记录没有持续累积）。 - - **多个状态目录**：当跨 home 目录存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在不同安装之间分裂）。 - - **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态存储在那里）。 - - **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对组/所有用户可读，则发出警告，并提供收紧为 `600` 的选项。 + - **主会话“单行 JSONL”**：当主转录只有一行时标记出来（历史记录未持续累积）。 + - **多个状态目录**：当多个主目录下存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向别处时发出警告（历史记录可能在不同安装之间分裂）。 + - **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态保存在那里）。 + - **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对组/全体用户可读，则发出警告，并提供将权限收紧到 `600` 的选项。 - - Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已过期，它会建议使用 Anthropic API key 或 Anthropic setup-token 路径。刷新提示只会在交互模式（TTY）下出现；`--non-interactive` 会跳过刷新尝试。 + + Doctor 会检查认证存储中的 OAuth 配置，在令牌即将过期/已过期时发出警告，并可在安全时刷新它们。如果 Anthropic OAuth/令牌配置已过时，它会建议使用 Anthropic API 密钥或 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 还会报告因以下原因而暂时不可用的认证配置： - - 短暂冷却（速率限制/超时/认证失败） - - 更长期禁用（计费/额度失败） + - 短时间冷却（速率限制/超时/认证失败） + - 较长时间禁用（账单/额度失败） - 如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在其无法解析或不被允许时发出警告。 + 如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证该模型引用，并在它无法解析或不被允许时发出警告。 启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。 - 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 仅验证当前配置中处于活动状态或由其内置清单默认启用的内置插件的运行时依赖，例如 `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 修复期间，内置运行时依赖的 npm 安装会在 TTY 会话中显示旋转进度，在管道/无头输出中显示周期性的行进度。Gateway 网关和本地 CLI 还可以在导入某个活跃的内置插件之前，按需修复其运行时依赖。这些安装被限定在插件运行时安装根目录下，运行时禁用脚本，不写入 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 网关服务，并输出清理提示。带有配置名的 OpenClaw Gateway 网关服务被视为一等公民，不会被标记为“额外”。 - 在 Linux 上，如果用户级 Gateway 网关服务缺失，但存在系统级 OpenClaw Gateway 网关服务，doctor 不会自动安装第二个用户级服务。请使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 进行检查；然后删除重复项，或者在系统 supervisor 管理 Gateway 网关生命周期时设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。 + 在 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 仍然匹配，但设备身份已不再匹配已批准记录 - - 已配对记录缺少已批准角色的活动 token - - 已配对 token 的作用域漂移到已批准配对基线之外 - - 当前机器的本地缓存设备 token 条目早于 Gateway 网关侧 token 轮换，或携带过期的作用域元数据 + - 待处理的首次配对请求 + - 已配对设备待处理的角色升级 + - 已配对设备待处理的作用域升级 + - 当设备 ID 仍匹配但设备身份不再匹配已批准记录时的公钥不匹配修复 + - 已配对记录中缺少已批准角色的活动令牌 + - 作用域漂移超出已批准配对基线的已配对令牌 + - 当前机器上的本地缓存设备令牌条目早于 Gateway 网关侧令牌轮换，或携带过时作用域元数据 - Doctor 不会自动批准配对请求，也不会自动轮换设备 token。它会直接输出精确的下一步操作： + Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它会改为输出精确的下一步操作： - 使用 `openclaw devices list` 检查待处理请求 - - 使用 `openclaw devices approve ` 批准指定请求 - - 使用 `openclaw devices rotate --device --role ` 轮换新的 token - - 使用 `openclaw devices remove ` 删除并重新批准过期记录 + - 使用 `openclaw devices approve ` 批准精确请求 + - 使用 `openclaw devices rotate --device --role ` 轮换新的令牌 + - 使用 `openclaw devices remove ` 删除并重新批准过时记录 - 这填补了常见的“已经配对但仍然提示需要配对”的漏洞：doctor 现在可以区分首次配对、待处理的角色/作用域升级，以及过期 token/设备身份漂移。 + 这样就堵住了常见的“明明已经配对但仍然提示需要配对”的漏洞：doctor 现在可以区分首次配对、待处理的角色/作用域升级，以及过时的令牌/设备身份漂移。 - 当某个提供商对私信开放但没有允许列表，或者某项策略以危险方式配置时，doctor 会发出警告。 + 当某个 provider 对私信开放但没有允许列表，或者某项策略以危险方式配置时，doctor 会发出警告。 - 如果以 systemd 用户服务运行，doctor 会确保启用 lingering，以便 Gateway 网关在注销后继续运行。 + 如果作为 systemd 用户服务运行，doctor 会确保已启用 lingering，以便 Gateway 网关在注销后仍保持运行。 - Doctor 会输出默认 agent 的工作区状态摘要： + Doctor 会打印默认智能体的工作区状态摘要： - - **Skills 状态**：统计符合条件、缺少要求以及被允许列表阻止的 Skills。 - - **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。 - - **插件状态**：统计已启用/已禁用/出错的插件；列出出错插件的插件 ID；报告内置插件能力。 + - **Skills 状态**：统计可用、缺少要求和被允许列表阻止的 Skills 数量。 + - **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区同时存在时发出警告。 + - **插件状态**：统计已启用/已禁用/出错的插件数量；列出所有出错插件的插件 ID；报告 bundle 插件能力。 - **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。 - - **插件诊断**：展示插件注册表在加载时输出的任何警告或错误。 + - **插件诊断**：显示插件注册表在加载时发出的任何警告或错误。 - 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.` 条目、指定该渠道的心跳目标，以及 `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 配置文件使用了较慢的动态补全模式（`source <(openclaw completion ...)`），doctor 会将其升级为更快的缓存文件变体。 + - 如果补全已在配置文件中配置，但缓存文件缺失，doctor 会自动重新生成缓存。 + - 如果根本没有配置补全，doctor 会提示安装它（仅交互模式；使用 `--non-interactive` 时跳过）。 运行 `openclaw completion --write-state` 可手动重新生成缓存。 - - Doctor 会检查本地 Gateway 网关 token 认证的就绪状态。 + + Doctor 会检查本地 Gateway 网关令牌认证的就绪状态。 - - 如果 token 模式需要 token 且不存在 token 来源，doctor 会提供生成 token 的选项。 - - 如果 `gateway.auth.token` 由 SecretRef 管理但当前不可用，doctor 会发出警告，并且不会用明文覆盖它。 - - `openclaw doctor --generate-gateway-token` 只会在未配置 token SecretRef 时强制生成 token。 + - 如果令牌模式需要令牌且不存在令牌来源，doctor 会提供生成令牌的选项。 + - 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，doctor 会发出警告，并且不会用明文覆盖它。 + - 仅当未配置 token SecretRef 时，`openclaw doctor --generate-gateway-token` 才会强制生成令牌。 - + 某些修复流程需要检查已配置的凭证，同时又不能削弱运行时快速失败行为。 - - `openclaw doctor --fix` 现在会像 Status 系列命令一样，使用同样的只读 SecretRef 摘要模型来执行定向配置修复。 - - 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在凭证可用时尝试使用已配置的 bot 凭证。 - - 如果 Telegram bot token 是通过 SecretRef 配置的，但在当前命令路径下不可用，doctor 会报告该凭证为“已配置但不可用”，并跳过自动解析，而不是崩溃或误报 token 缺失。 + - `openclaw doctor --fix` 现在对定向配置修复使用与 status 系列命令相同的只读 SecretRef 摘要模型。 + - 示例：Telegram `allowFrom` / `groupAllowFrom` 的 `@username` 修复会在可用时尝试使用已配置的机器人凭证。 + - 如果 Telegram 机器人令牌通过 SecretRef 配置，但在当前命令路径中不可用，doctor 会报告该凭证“已配置但不可用”，并跳过自动解析，而不是崩溃或错误地将令牌报告为缺失。 Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。 - Doctor 会检查默认 agent 所配置的 Memory 搜索嵌入提供商是否就绪。其行为取决于已配置的后端和提供商： + Doctor 会检查为默认智能体配置的 Memory 搜索 embedding provider 是否已就绪。行为取决于配置的后端和 provider： - - **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会输出修复指引，包括 npm 包和手动二进制路径选项。 - - **显式本地提供商**：检查本地模型文件或已识别的远程/可下载模型 URL 是否存在。如果不存在，则建议切换到远程提供商。 - - **显式远程提供商**（`openai`、`voyage` 等）：验证环境或 auth 存储中是否存在 API key。如果缺失，则输出可执行的修复提示。 - - **自动提供商**：先检查本地模型可用性，然后按自动选择顺序依次尝试每个远程提供商。 + - **QMD 后端**：探测 `qmd` 二进制是否可用且可启动。如果不可用，会输出修复指导，包括 npm 软件包和手动二进制路径选项。 + - **显式本地 provider**：检查本地模型文件或已识别的远程/可下载模型 URL 是否存在。如果缺失，会建议切换到远程 provider。 + - **显式远程 provider**（`openai`、`voyage` 等）：验证环境变量或认证存储中是否存在 API 密钥。如果缺失，会输出可执行的修复提示。 + - **自动 provider**：先检查本地模型可用性，然后按自动选择顺序依次尝试各个远程 provider。 - 当存在缓存的 Gateway 网关探测结果时（检查时 Gateway 网关健康），doctor 会将该结果与 CLI 可见的配置进行交叉比对，并指出任何差异。Doctor 不会在默认路径上发起新的嵌入 ping；如果你想进行实时提供商检查，请使用深度 Memory Status 命令。 + 当存在缓存的 Gateway 网关探测结果时（检查时 Gateway 网关是健康的），doctor 会将其结果与 CLI 可见配置进行交叉比对，并标注任何不一致。Doctor 在默认路径上不会启动新的 embedding ping；如果你想进行实时 provider 检查，请使用深度 Memory 状态命令。 - 使用 `openclaw memory status --deep` 可在运行时验证嵌入就绪状态。 + 使用 `openclaw memory status --deep` 可在运行时验证 embedding 就绪状态。 - 如果 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 --yes` 会接受默认修复提示。 - - `openclaw doctor --repair` 会在无提示的情况下应用推荐修复。 + - `openclaw doctor --repair` 会在无提示的情况下应用建议修复。 - `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。 - - `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_SERVICE_REPAIR_POLICY=external` 会使 doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状况并运行非服务修复，但会跳过服务安装/启动/重启/bootstrap、supervisor 配置重写以及旧版服务清理，因为该生命周期由外部 supervisor 管理。 + - 如果令牌认证需要令牌且 `gateway.auth.token` 由 SecretRef 管理，doctor 服务安装/修复会验证 SecretRef，但不会将解析出的明文令牌值持久化到 supervisor 服务环境元数据中。 + - Doctor 会检测较旧的 LaunchAgent、systemd 或 Windows Scheduled Task 安装内联嵌入的托管 `.env`/SecretRef 支持的服务环境值，并重写服务元数据，使这些值从运行时来源加载，而不是从 supervisor 定义中加载。 + - 当 `gateway.port` 更改后，如果服务命令仍固定旧的 `--port`，doctor 会检测到这一点，并将服务元数据重写为当前端口。 + - 如果令牌认证需要令牌且配置的 token 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 gateway install --force` 强制执行完整重写。 @@ -461,13 +461,16 @@ openclaw memory rem-backfill --path ./memory --stage-short-term Doctor 会检查服务运行时（PID、最近退出状态），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。 - 当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径在升级后可能失效，因为服务不会加载你的 shell 初始化。Doctor 会在可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。 + 当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径可能会在升级后失效，因为服务不会加载你的 shell 初始化。Doctor 会在可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。 + + 新安装或修复后的服务会保留显式环境根目录（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）和稳定的用户二进制目录，但推测得到的版本管理器回退目录只有在这些目录实际存在于磁盘上时，才会写入服务 PATH。这使生成的 supervisor PATH 与 doctor 后续运行的相同最小 PATH 审计保持一致。 + - Doctor 会持久化任何配置更改，并写入向导元数据以记录本次 doctor 运行。 + Doctor 会持久化所有配置更改，并写入向导元数据以记录本次 doctor 运行。 - 当工作区缺少 Memory 系统时，doctor 会给出建议；如果工作区尚未受 git 管理，它还会输出备份提示。 + 当工作区缺少 Memory 系统时，Doctor 会建议使用一个工作区 Memory 系统；如果工作区尚未置于 git 管理下，它还会输出备份提示。 有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。 diff --git a/docs/zh-CN/gateway/trusted-proxy-auth.md b/docs/zh-CN/gateway/trusted-proxy-auth.md index c645544cf..40997f9bd 100644 --- a/docs/zh-CN/gateway/trusted-proxy-auth.md +++ b/docs/zh-CN/gateway/trusted-proxy-auth.md @@ -1,77 +1,77 @@ --- read_when: - 在身份感知代理后运行 OpenClaw - - 在 OpenClaw 前面使用 OAuth 设置 Pomerium、Caddy 或 nginx + - 在 OpenClaw 前面设置带有 OAuth 的 Pomerium、Caddy 或 nginx - 修复反向代理设置中的 WebSocket 1008 未授权错误 - - 决定在哪里设置 HSTS 和其他 HTTP 强化标头 + - 决定在哪里设置 HSTS 和其他 HTTP 加固标头 sidebarTitle: Trusted proxy auth summary: 将 Gateway 网关身份验证委托给受信任的反向代理（Pomerium、Caddy、nginx + OAuth） -title: 受信任代理身份验证 +title: 受信任的代理身份验证 x-i18n: - generated_at: "2026-04-26T08:13:22Z" + generated_at: "2026-04-27T22:22:36Z" model: gpt-5.4 provider: openai - source_hash: 64e0f4dee942aedec548135f0408e7773e7b498f8262af13a4d0eff262cae646 + source_hash: 863a448f84d1bc5bf2a5a07a894bcc1bb7e724826ba9cec3fa135338af8dd3eb source_path: gateway/trusted-proxy-auth.md workflow: 15 --- -**安全敏感功能。** 此模式会将身份验证完全委托给你的反向代理。配置错误可能会让未经授权的访问暴露你的 Gateway 网关。启用前请仔细阅读本页。 +**安全敏感功能。** 此模式会将身份验证完全委托给你的反向代理。配置错误可能会让你的 Gateway 网关暴露给未授权访问。在启用前请仔细阅读本页。 ## 何时使用 在以下情况下使用 `trusted-proxy` 身份验证模式： -- 你在**身份感知代理**后运行 OpenClaw（Pomerium、Caddy + OAuth、nginx + oauth2-proxy、Traefik + forward auth）。 +- 你在**身份感知代理**（Pomerium、Caddy + OAuth、nginx + oauth2-proxy、Traefik + forward auth）后运行 OpenClaw。 - 你的代理处理所有身份验证，并通过标头传递用户身份。 -- 你处于 Kubernetes 或容器环境中，并且代理是访问 Gateway 网关的唯一入口。 +- 你处于 Kubernetes 或容器环境中，并且该代理是访问 Gateway 网关的唯一路径。 - 你遇到了 WebSocket `1008 unauthorized` 错误，因为浏览器无法在 WS 负载中传递令牌。 -## 何时**不要**使用 +## 何时不要使用 - 如果你的代理不验证用户身份（只是 TLS 终止器或负载均衡器）。 - 如果存在任何绕过代理直接访问 Gateway 网关的路径（防火墙漏洞、内部网络访问）。 -- 如果你不确定你的代理是否会正确剥离/覆盖转发标头。 -- 如果你只需要个人单用户访问（可考虑使用 Tailscale Serve + loopback，以获得更简单的设置）。 +- 如果你不确定你的代理是否正确剥离/覆盖转发标头。 +- 如果你只需要个人单用户访问（可考虑使用 Tailscale Serve + loopback 以获得更简单的设置）。 ## 工作原理 - 你的反向代理会验证用户身份（OAuth、OIDC、SAML 等）。 + 你的反向代理验证用户身份（OAuth、OIDC、SAML 等）。 - 代理会添加一个包含已验证用户身份的标头（例如 `x-forwarded-user: nick@example.com`）。 + 代理添加一个包含已验证用户身份的标头（例如 `x-forwarded-user: nick@example.com`）。 - OpenClaw 会检查请求是否来自**受信任的代理 IP**（在 `gateway.trustedProxies` 中配置）。 + OpenClaw 检查请求是否来自**受信任的代理 IP**（在 `gateway.trustedProxies` 中配置）。 - OpenClaw 会从已配置的标头中提取用户身份。 + OpenClaw 从已配置的标头中提取用户身份。 - 如果一切检查通过，则请求会被授权。 + 如果所有检查都通过，则请求会被授权。 ## Control UI 配对行为 -当 `gateway.auth.mode = "trusted-proxy"` 处于启用状态，且请求通过了受信任代理检查时，Control UI WebSocket 会话可以在没有设备配对身份的情况下连接。 +当 `gateway.auth.mode = "trusted-proxy"` 处于活动状态，且请求通过了 trusted-proxy 检查时，Control UI WebSocket 会话可以在没有设备配对身份的情况下连接。 影响： - 在此模式下，配对不再是 Control UI 访问的主要门槛。 -- 你的反向代理身份验证策略和 `allowUsers` 将成为实际的访问控制。 -- 让 Gateway 网关入口仅对受信任代理 IP 开放（`gateway.trustedProxies` + 防火墙）。 +- 你的反向代理身份验证策略和 `allowUsers` 会成为实际的访问控制。 +- 仅允许来自受信任代理 IP 的 Gateway 网关入口访问（`gateway.trustedProxies` + 防火墙）。 ## 配置 ```json5 { gateway: { - // 受信任代理身份验证要求请求来自非 loopback 的受信任代理来源 + // trusted-proxy 身份验证要求请求来自非 loopback 的受信任代理来源 bind: "lan", // 关键：这里只添加你的代理 IP @@ -80,7 +80,7 @@ x-i18n: auth: { mode: "trusted-proxy", trustedProxy: { - // 包含已验证用户身份的标头（必需） + // 包含已验证用户身份的标头（必填） userHeader: "x-forwarded-user", // 可选：必须存在的标头（代理验证） @@ -97,11 +97,11 @@ x-i18n: **重要运行时规则** -- 受信任代理身份验证会拒绝来自 loopback 源的请求（`127.0.0.1`、`::1`、loopback CIDR）。 -- 同主机 loopback 反向代理**不**满足受信任代理身份验证要求。 -- 对于同主机 loopback 代理设置，请改用令牌/密码身份验证，或通过 OpenClaw 可以验证的非 loopback 受信任代理地址进行路由。 -- 非 loopback 的 Control UI 部署仍需要显式设置 `gateway.controlUi.allowedOrigins`。 -- **转发标头证据会覆盖 loopback 本地性。** 如果请求到达于 loopback，但携带的 `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto` 标头指向非本地来源，那么这些证据会使 loopback 本地性声明失效。该请求会被视为远程请求，用于配对、受信任代理身份验证以及 Control UI 设备身份门控。这可防止同主机 loopback 代理将转发标头身份“洗白”进受信任代理身份验证。 +- Trusted-proxy 身份验证会拒绝来自 loopback 源的请求（`127.0.0.1`、`::1`、loopback CIDR）。 +- 同主机 loopback 反向代理**不满足** trusted-proxy 身份验证要求。 +- 对于同主机 loopback 代理设置，请改用 token/password 身份验证，或通过 OpenClaw 可验证的非 loopback 受信任代理地址进行路由。 +- 非 loopback 的 Control UI 部署仍然需要显式设置 `gateway.controlUi.allowedOrigins`。 +- **转发标头证据会覆盖 loopback 本地性。** 如果请求到达于 loopback，但携带了指向非本地来源的 `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto` 标头，则这些证据会使 loopback 本地性声明失效。该请求会被视为远程请求，用于配对、trusted-proxy 身份验证和 Control UI 设备身份门禁。这可防止同主机 loopback 代理将转发标头身份“洗白”后注入 trusted-proxy 身份验证。 ### 配置参考 @@ -122,16 +122,16 @@ x-i18n: 用户身份允许列表。为空表示允许所有已验证用户。 -## TLS 终止与 HSTS +## TLS 终止和 HSTS -使用一个 TLS 终止点，并在那里应用 HSTS。 +使用单一 TLS 终止点，并在那里应用 HSTS。 - 当你的反向代理为 `https://control.example.com` 处理 HTTPS 时，请在该域名的代理处设置 `Strict-Transport-Security`。 + 当你的反向代理为 `https://control.example.com` 处理 HTTPS 时，在该域名的代理上设置 `Strict-Transport-Security`。 - 非常适合面向互联网的部署。 - - 将证书和 HTTP 强化策略集中在同一处。 + - 将证书和 HTTP 加固策略集中在一个地方。 - OpenClaw 可以在代理后继续使用 loopback HTTP。 标头值示例： @@ -157,24 +157,24 @@ x-i18n: } ``` - `strictTransportSecurity` 接受字符串类型的标头值，或使用 `false` 来显式禁用。 + `strictTransportSecurity` 接受一个字符串标头值，或用 `false` 显式禁用。 ### 发布指导 -- 开始时先使用较短的 max age（例如 `max-age=300`）来验证流量。 -- 只有在确信无误后，再增加到长期值（例如 `max-age=31536000`）。 -- 仅当每个子域都已准备好支持 HTTPS 时，才添加 `includeSubDomains`。 +- 开始时先使用较短的最大存活时间（例如 `max-age=300`）来验证流量。 +- 仅在你有足够把握后，再增加到长期值（例如 `max-age=31536000`）。 +- 只有在每个子域都已支持 HTTPS 时，才添加 `includeSubDomains`。 - 仅当你有意满足整个域名集合的 preload 要求时，才使用 preload。 -- 仅限 loopback 的本地开发不会从 HSTS 中获益。 +- 仅限 loopback 的本地开发无法从 HSTS 中受益。 ## 代理设置示例 - Pomerium 通过 `x-pomerium-claim-email`（或其他声明标头）传递身份，并通过 `x-pomerium-jwt-assertion` 传递 JWT。 + Pomerium 在 `x-pomerium-claim-email`（或其他 claim 标头）中传递身份，并在 `x-pomerium-jwt-assertion` 中传递 JWT。 ```json5 { @@ -240,7 +240,7 @@ x-i18n: - oauth2-proxy 会验证用户身份，并通过 `x-auth-request-email` 传递身份。 + oauth2-proxy 验证用户身份，并在 `x-auth-request-email` 中传递身份。 ```json5 { @@ -291,20 +291,20 @@ x-i18n: -## 混合令牌配置 +## 混合 token 配置 -当 `gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）与 `trusted-proxy` 模式同时启用时，OpenClaw 会拒绝这种有歧义的配置。混合令牌配置可能导致 loopback 请求在错误的身份验证路径上被静默验证通过。 +当 `gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）与 `trusted-proxy` 模式同时启用时，OpenClaw 会拒绝这种存在歧义的配置。混合 token 配置可能会导致 loopback 请求在错误的身份验证路径上被静默验证。 如果你在启动时看到 `mixed_trusted_proxy_token` 错误： -- 在使用 trusted-proxy 模式时移除共享令牌，或者 -- 如果你打算使用基于令牌的身份验证，请将 `gateway.auth.mode` 切换为 `"token"`。 +- 在使用 trusted-proxy 模式时移除共享 token，或 +- 如果你打算使用基于 token 的身份验证，则将 `gateway.auth.mode` 切换为 `"token"`。 -loopback 的受信任代理身份验证也会以失败关闭方式处理：同主机调用方必须通过受信任代理提供已配置的身份标头，而不是被静默验证通过。 +Loopback trusted-proxy 身份标头仍会以失败关闭的方式处理：同主机调用方不会被静默认证为代理用户。绕过代理的 OpenClaw 内部调用方可以改用 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` 进行身份验证。在 trusted-proxy 模式中，仍然有意不支持 token 回退。 ## Operator scopes 标头 -受信任代理身份验证是一种**携带身份信息的** HTTP 模式，因此调用方可以选择通过 `x-openclaw-scopes` 声明 operator scope。 +Trusted-proxy 身份验证是一种**携带身份信息的** HTTP 模式，因此调用方可以选择使用 `x-openclaw-scopes` 声明 operator scopes。 示例： @@ -314,38 +314,39 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同 行为： -- 当该标头存在时，OpenClaw 会采用所声明的 scope 集合。 -- 当该标头存在但为空时，请求声明的是**无** operator scope。 -- 当该标头缺失时，普通的携带身份信息 HTTP API 会回退到标准的 operator 默认 scope 集合。 -- Gateway 网关身份验证的**插件 HTTP 路由**默认更窄：当 `x-openclaw-scopes` 缺失时，其运行时 scope 会回退到 `operator.write`。 -- 来自浏览器源的 HTTP 请求即使在受信任代理身份验证成功后，仍然必须通过 `gateway.controlUi.allowedOrigins`（或有意启用的 Host 标头回退模式）。 +- 当该标头存在时，OpenClaw 会采用声明的作用域集合。 +- 当该标头存在但为空时，请求声明**没有** operator scopes。 +- 当该标头不存在时，普通的身份承载型 HTTP API 会回退到标准的 operator 默认作用域集合。 +- Gateway-auth **插件 HTTP 路由**默认更加收敛：当 `x-openclaw-scopes` 缺失时，其运行时作用域会回退到 `operator.write`。 +- 来自浏览器源的 HTTP 请求即使已通过 trusted-proxy 身份验证，仍必须通过 `gateway.controlUi.allowedOrigins`（或刻意启用的 Host 标头回退模式）检查。 -实用规则：当你希望某个受信任代理请求比默认值更窄，或者某个 Gateway 网关身份验证插件路由需要比写入 scope 更强的权限时，请显式发送 `x-openclaw-scopes`。 +实践规则：当你希望 trusted-proxy 请求比默认值更收敛，或者 gateway-auth 插件路由需要比写作用域更强的权限时，请显式发送 `x-openclaw-scopes`。 ## 安全检查清单 -启用受信任代理身份验证前，请确认： +在启用 trusted-proxy 身份验证之前，请确认： -- [ ] **代理是唯一入口**：Gateway 网关端口已通过防火墙限制，除你的代理外其他来源均无法访问。 -- [ ] **trustedProxies 最小化**：只包含你实际使用的代理 IP，而不是整个子网。 -- [ ] **没有 loopback 代理来源**：对于来自 loopback 源的请求，受信任代理身份验证会以失败关闭方式处理。 -- [ ] **代理会剥离标头**：你的代理会覆盖（而不是追加）来自客户端的 `x-forwarded-*` 标头。 +- [ ] **代理是唯一访问路径**：Gateway 网关端口已通过防火墙限制，只允许你的代理访问。 +- [ ] **trustedProxies 保持最小化**：只填入你的实际代理 IP，而不是整个子网。 +- [ ] **没有 loopback 代理来源**：trusted-proxy 身份验证会对来自 loopback 源的请求以失败关闭方式处理。 +- [ ] **代理会剥离标头**：你的代理会覆盖（而不是附加）来自客户端的 `x-forwarded-*` 标头。 - [ ] **TLS 终止**：你的代理处理 TLS；用户通过 HTTPS 连接。 -- [ ] **allowedOrigins 已显式设置**：非 loopback 的 Control UI 使用显式的 `gateway.controlUi.allowedOrigins`。 +- [ ] **allowedOrigins 是显式的**：非 loopback 的 Control UI 使用显式的 `gateway.controlUi.allowedOrigins`。 - [ ] **已设置 allowUsers**（推荐）：限制为已知用户，而不是允许任何已验证用户。 -- [ ] **没有混合令牌配置**：不要同时设置 `gateway.auth.token` 和 `gateway.auth.mode: "trusted-proxy"`。 +- [ ] **没有混合 token 配置**：不要同时设置 `gateway.auth.token` 和 `gateway.auth.mode: "trusted-proxy"`。 +- [ ] **本地密码回退保持私有**：如果你为内部直接调用方配置了 `gateway.auth.password`，请保持 Gateway 网关端口处于防火墙保护之下，这样非代理的远程客户端就无法直接访问它。 ## 安全审计 -`openclaw security audit` 会将受信任代理身份验证标记为**严重**级别发现。这是有意为之——它是在提醒你：你正在将安全性委托给你的代理配置。 +`openclaw security audit` 会将 trusted-proxy 身份验证标记为**严重**级别的问题。这是有意设计的——它是在提醒你：你正在将安全性委托给你的代理设置。 -审计会检查： +审计会检查以下内容： -- 基础 `gateway.trusted_proxy_auth` 警告/严重提醒 +- 基础的 `gateway.trusted_proxy_auth` 警告/严重提醒 - 缺少 `trustedProxies` 配置 - 缺少 `userHeader` 配置 -- `allowUsers` 为空（允许任何已验证用户） -- 在暴露的 Control UI 表面上，浏览器来源策略为通配符或缺失 +- 空的 `allowUsers`（允许任何已验证用户） +- 在暴露的 Control UI 表面上使用通配符或缺失的浏览器来源策略 ## 故障排除 @@ -364,11 +365,11 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同 请检查： - 代理是否从 `127.0.0.1` / `::1` 发起连接？ - - 你是否正在尝试将 trusted-proxy 身份验证用于同主机 loopback 反向代理？ + - 你是否正在尝试将 trusted-proxy 身份验证与同主机 loopback 反向代理一起使用？ 修复方法： - - 对同主机 loopback 代理设置使用令牌/密码身份验证，或者 + - 对于同主机 loopback 代理设置，使用 token/password 身份验证，或 - 通过非 loopback 的受信任代理地址进行路由，并将该 IP 保留在 `gateway.trustedProxies` 中。 @@ -376,7 +377,7 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同 用户标头为空或缺失。请检查： - 你的代理是否已配置为传递身份标头？ - - 标头名称是否正确？（大小写不敏感，但拼写很重要） + - 标头名称是否正确？（不区分大小写，但拼写必须正确） - 用户是否确实已在代理处完成身份验证？ @@ -384,11 +385,11 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同 某个必需标头不存在。请检查： - 你的代理中针对这些特定标头的配置。 - - 标头是否在链路中的某处被剥离。 + - 标头是否在链路中的某个位置被剥离了。 - 用户已通过身份验证，但不在 `allowUsers` 中。请将其加入，或移除允许列表。 + 用户已通过身份验证，但不在 `allowUsers` 中。请将其添加进去，或移除允许列表。 trusted-proxy 身份验证已成功，但浏览器的 `Origin` 标头未通过 Control UI 来源检查。 @@ -396,27 +397,27 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同 请检查： - `gateway.controlUi.allowedOrigins` 是否包含精确的浏览器来源。 - - 你是否没有依赖通配符来源，除非你确实想要允许所有来源的行为。 - - 如果你有意使用 Host 标头回退模式，是否已明确设置 `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true`。 + - 除非你确实想允许所有来源，否则不要依赖通配符来源。 + - 如果你有意使用 Host 标头回退模式，请确认已明确设置 `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true`。 - 请确保你的代理： + 确保你的代理： - 支持 WebSocket 升级（`Upgrade: websocket`、`Connection: upgrade`）。 - - 在 WebSocket 升级请求中传递身份标头（而不只是 HTTP）。 + - 在 WebSocket 升级请求中也会传递身份标头（而不仅仅是 HTTP）。 - 没有为 WebSocket 连接设置单独的身份验证路径。 -## 从令牌身份验证迁移 +## 从 token 身份验证迁移 -如果你正在从令牌身份验证迁移到 trusted-proxy： +如果你正从 token 身份验证迁移到 trusted-proxy： - 配置你的代理来验证用户身份并传递标头。 + 配置你的代理，使其验证用户身份并传递标头。 独立测试代理设置（使用带标头的 curl）。 @@ -428,10 +429,10 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同 重启 Gateway 网关。 - 从 Control UI 测试 WebSocket 连接。 + 测试来自 Control UI 的 WebSocket 连接。 - 运行 `openclaw security audit` 并查看发现项。 + 运行 `openclaw security audit` 并查看结果。 @@ -440,4 +441,4 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同 - [配置](/zh-CN/gateway/configuration) — 配置参考 - [远程访问](/zh-CN/gateway/remote) — 其他远程访问模式 - [安全](/zh-CN/gateway/security) — 完整安全指南 -- [Tailscale](/zh-CN/gateway/tailscale) — 仅限 tailnet 访问的更简单替代方案 +- [Tailscale](/zh-CN/gateway/tailscale) — 仅 tailnet 访问的更简单替代方案 diff --git a/docs/zh-CN/plugins/sdk-subpaths.md b/docs/zh-CN/plugins/sdk-subpaths.md index 3fd297ae4..644667d8d 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -1,32 +1,33 @@ --- read_when: - 为插件导入选择合适的 plugin-sdk 子路径 - - 审计内置插件子路径和辅助接口 surface -summary: 插件 SDK 子路径目录：按领域分组，哪些导入位于何处 + - 审查 bundled-plugin 子路径和辅助接口 +summary: 插件 SDK 子路径目录：按领域分组，哪些导入位于哪里 title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-27T21:58:41Z" + generated_at: "2026-04-27T22:22:33Z" model: gpt-5.4 provider: openai - source_hash: c0a164b1e967c1e794c6f03f5a2ff42ec2b8121dd7e4b1232c8ede10d97a7ebb + source_hash: 56f76f2371500ab77dc791ba862cb628daec596059f1f9def7227fecb2826347 source_path: plugins/sdk-subpaths.md workflow: 15 --- - plugin SDK 通过 `openclaw/plugin-sdk/` 下的一组窄子路径公开。 - 本页按用途分组，整理了常用子路径。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；保留的内置插件辅助子路径也会出现在其中，但除非某个文档页面明确将其作为公开能力介绍，否则它们属于实现细节。 + 插件 SDK 以 `openclaw/plugin-sdk/` 下的一组窄子路径形式对外暴露。 + 本页按用途分组，汇总常用子路径。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`； + 其中也会列出保留的 bundled-plugin 辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。 关于插件编写指南，参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 - | 子路径 | 关键导出 | + | 子路径 | 关键导出 | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | | `plugin-sdk/config-schema` | `OpenClawSchema` | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/migration` | 迁移提供商条目辅助函数，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助函数以及 `summarizeMigrationItems` | + | `plugin-sdk/migration` | 迁移提供商条目辅助函数，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助函数，以及 `summarizeMigrationItems` | | `plugin-sdk/migration-runtime` | 运行时迁移辅助函数，例如 `copyMigrationFileItem` 和 `writeMigrationReport` | @@ -34,272 +35,272 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | + | `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/setup` | 共享设置向导辅助函数、allowlist 提示、设置状态构建器 | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户配置/操作门控辅助函数、默认账户回退辅助函数 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 | - | `plugin-sdk/account-resolution` | 账户查找 + 默认值回退辅助函数 | - | `plugin-sdk/account-helpers` | 窄范围的账户列表/账户操作辅助函数 | + | `plugin-sdk/account-core` | 多账户配置 / 动作门控辅助函数，默认账户回退辅助函数 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`，账户 ID 规范化辅助函数 | + | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 | + | `plugin-sdk/account-helpers` | 窄范围的账户列表 / 账户操作辅助函数 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 共享渠道配置 schema 原语和通用构建器 | - | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置渠道配置 schema，仅用于内置兼容性 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助函数，带内置契约回退 | - | `plugin-sdk/command-gating` | 窄范围的命令鉴权门控辅助函数 | + | `plugin-sdk/channel-config-schema-legacy` | 已弃用的 bundled-channel 配置 schema，仅用于保持内置兼容性 | + | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助函数，并带有 bundled 合同回退 | + | `plugin-sdk/command-gating` | 窄范围命令授权门控辅助函数 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/收尾辅助函数 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`，草稿流生命周期 / 收尾辅助函数 | | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助函数 | - | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助函数 | - | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助函数 | + | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与派发辅助函数 | + | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 | | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助函数 | - | `plugin-sdk/outbound-send-deps` | 供渠道适配器使用的轻量级出站发送依赖查找 | - | `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化和负载规划辅助函数 | - | `plugin-sdk/poll-runtime` | 窄范围的投票规范化辅助函数 | + | `plugin-sdk/outbound-send-deps` | 面向渠道适配器的轻量级出站发送依赖查找 | + | `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化和载荷规划辅助函数 | + | `plugin-sdk/poll-runtime` | 窄范围投票规范化辅助函数 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 | - | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 | - | `plugin-sdk/conversation-runtime` | 对话/线程绑定、配对和已配置绑定辅助函数 | + | `plugin-sdk/agent-media-payload` | 旧版智能体媒体载荷构建器 | + | `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对和已配置绑定辅助函数 | | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 | | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 | - | `plugin-sdk/channel-status` | 共享渠道 Status 快照/摘要辅助函数 | - | `plugin-sdk/channel-config-primitives` | 窄范围的渠道配置 schema 原语 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入鉴权辅助函数 | + | `plugin-sdk/channel-status` | 共享渠道 Status 快照 / 摘要辅助函数 | + | `plugin-sdk/channel-config-primitives` | 窄范围渠道配置 schema 原语 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 | | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助函数 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助函数 | | `plugin-sdk/group-access` | 共享群组访问决策辅助函数 | - | `plugin-sdk/direct-dm` | 共享直接私信鉴权/守卫辅助函数 | + | `plugin-sdk/direct-dm` | 共享直接私信授权 / 守卫辅助函数 | | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递和旧版交互式回复辅助函数。参见 [消息呈现](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 入站防抖、提及匹配、提及策略辅助函数和 envelope 辅助函数的兼容性 barrel | - | `plugin-sdk/channel-inbound-debounce` | 窄范围的入站防抖辅助函数 | - | `plugin-sdk/channel-mention-gating` | 窄范围的提及策略、提及标记和提及文本辅助函数，不包含更广泛的入站运行时接口 | - | `plugin-sdk/channel-envelope` | 窄范围的入站 envelope 格式化辅助函数 | + | `plugin-sdk/channel-inbound` | 面向入站去抖动、提及匹配、提及策略辅助函数和 envelope 辅助函数的兼容性 barrel | + | `plugin-sdk/channel-inbound-debounce` | 窄范围入站去抖动辅助函数 | + | `plugin-sdk/channel-mention-gating` | 窄范围提及策略、提及标记和提及文本辅助函数，不包含更广泛的入站运行时接口 | + | `plugin-sdk/channel-envelope` | 窄范围入站 envelope 格式化辅助函数 | | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助函数 | - | `plugin-sdk/channel-logging` | 用于入站丢弃及 typing/ack 失败的渠道日志辅助函数 | + | `plugin-sdk/channel-logging` | 用于入站丢弃及输入中 / 确认失败的渠道日志辅助函数 | | `plugin-sdk/channel-send-result` | 回复结果类型 | - | `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为插件兼容性保留的已弃用原生 schema 辅助函数 | - | `plugin-sdk/channel-targets` | 目标解析/匹配辅助函数 | - | `plugin-sdk/channel-contract` | 渠道契约类型 | - | `plugin-sdk/channel-feedback` | 反馈/reaction 连接 | - | `plugin-sdk/channel-secret-runtime` | 窄范围的 secret 契约辅助函数，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 以及 secret 目标类型 | + | `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为保持插件兼容性而保留的已弃用原生 schema 辅助函数 | + | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 | + | `plugin-sdk/channel-contract` | 渠道合同类型 | + | `plugin-sdk/channel-feedback` | 反馈 / 反应接线 | + | `plugin-sdk/channel-secret-runtime` | 窄范围密钥合同辅助函数，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 | | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | 受支持的 LM Studio 提供商 facade，用于设置、目录发现和运行时模型准备 | - | `plugin-sdk/lmstudio-runtime` | 受支持的 LM Studio 运行时 facade，用于本地服务器默认值、模型发现、请求头和已加载模型辅助函数 | - | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助函数 | + | `plugin-sdk/lmstudio` | 受支持的 LM Studio 提供商外观层，用于设置、目录发现和运行时模型准备 | + | `plugin-sdk/lmstudio-runtime` | 受支持的 LM Studio 运行时外观层，用于本地服务器默认值、模型发现、请求头和已加载模型辅助函数 | + | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 | | `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的专用设置辅助函数 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助函数 | - | `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助函数，例如 `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 | - | `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助函数 | - | `plugin-sdk/provider-env-vars` | 提供商鉴权环境变量查找辅助函数 | + | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API 密钥解析辅助函数 | + | `plugin-sdk/provider-auth-api-key` | API 密钥新手引导 / 配置文件写入辅助函数，例如 `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | + | `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助函数 | + | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助函数，以及如 `normalizeNativeXaiModelId` 之类的模型 ID 规范化辅助函数 | - | `plugin-sdk/provider-catalog-runtime` | 用于契约测试的提供商目录运行时钩子和 plugin-provider registry 接口 | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`，共享 replay-policy 构建器、提供商端点辅助函数，以及模型 ID 规范化辅助函数，例如 `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-catalog-runtime` | 提供商目录运行时钩子和插件提供商注册表接口，用于合同测试 | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助函数、提供商 HTTP 错误，以及音频转录 multipart form 辅助函数 | - | `plugin-sdk/provider-web-fetch-contract` | 窄范围的 web-fetch 配置/选择契约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助函数 | - | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用连接逻辑的提供商的窄范围 web-search 配置/凭证辅助函数 | - | `plugin-sdk/provider-web-search-contract` | 窄范围的 web-search 配置/凭证契约辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化凭证 setter/getter | - | `plugin-sdk/provider-web-search` | Web 搜索提供商注册/缓存/运行时辅助函数 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容性辅助函数 | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似导出 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助函数 | - | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助函数，例如受保护 fetch、传输消息转换和可写传输事件流 | + | `plugin-sdk/provider-http` | 通用提供商 HTTP / 端点能力辅助函数、提供商 HTTP 错误，以及音频转录 multipart form 辅助函数 | + | `plugin-sdk/provider-web-fetch-contract` | 窄范围 web-fetch 配置 / 选择合同辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助函数 | + | `plugin-sdk/provider-web-search-config-contract` | 面向无需插件启用接线的提供商的窄范围 web-search 配置 / 凭证辅助函数 | + | `plugin-sdk/provider-web-search-contract` | 窄范围 web-search 配置 / 凭证合同辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及带作用域的凭证设置器 / 读取器 | + | `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助函数 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`，Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似函数 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / DeepSeek V4 / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助函数 | + | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助函数，例如受保护的 fetch、传输消息转换和可写传输事件流 | | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 | - | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助函数 | - | `plugin-sdk/group-activation` | 窄范围的群组激活模式和命令解析辅助函数 | + | `plugin-sdk/global-singleton` | 进程内 singleton / map / cache 辅助函数 | + | `plugin-sdk/group-activation` | 窄范围群组激活模式和命令解析辅助函数 | - + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数（包括动态参数菜单格式化）、发送者鉴权辅助函数 | - | `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作鉴权辅助函数 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助函数 | - | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数（包括动态参数菜单格式化）、发送者授权辅助函数 | + | `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天中的操作认证辅助函数 | + | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件 / 过滤器辅助函数 | + | `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 投递适配器 | | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助函数 | | `plugin-sdk/approval-handler-adapter-runtime` | 面向热渠道入口点的轻量级原生审批适配器加载辅助函数 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助函数；若较窄的 adapter/gateway 接口已足够，优先使用它们 | + | `plugin-sdk/approval-handler-runtime` | 范围更广的审批处理器运行时辅助函数；如果更窄的 adapter / gateway 接口已经足够，优先使用它们 | | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 | - | `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助函数 | - | `plugin-sdk/approval-runtime` | exec/插件审批负载辅助函数、原生审批路由/运行时辅助函数，以及如 `formatApprovalDisplayPath` 之类的结构化审批显示辅助函数 | - | `plugin-sdk/reply-dedupe` | 窄范围的入站回复去重重置辅助函数 | - | `plugin-sdk/channel-contract-testing` | 不包含宽泛测试 barrel 的窄范围渠道契约测试辅助函数 | - | `plugin-sdk/command-auth-native` | 原生命令鉴权、动态参数菜单格式化和原生会话目标辅助函数 | + | `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复载荷辅助函数 | + | `plugin-sdk/approval-runtime` | exec / 插件审批载荷辅助函数、原生审批路由 / 运行时辅助函数，以及结构化审批显示辅助函数，例如 `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | 窄范围入站回复去重重置辅助函数 | + | `plugin-sdk/channel-contract-testing` | 不含广泛测试 barrel 的窄范围渠道合同测试辅助函数 | + | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化和原生会话目标辅助函数 | | `plugin-sdk/command-detection` | 共享命令检测辅助函数 | | `plugin-sdk/command-primitives-runtime` | 面向热渠道路径的轻量级命令文本谓词 | - | `plugin-sdk/command-surface` | 命令体规范化和命令 surface 辅助函数 | + | `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助函数 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 面向渠道/插件 secret surface 的窄范围 secret 契约收集辅助函数 | - | `plugin-sdk/secret-ref-runtime` | 面向 secret 契约/配置解析的窄范围 `coerceSecretRef` 和 `SecretRef` 类型辅助函数 | - | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本脱敏、常量时间 secret 比较和 secret 收集辅助函数 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件密钥接口的窄范围密钥合同收集辅助函数 | + | `plugin-sdk/secret-ref-runtime` | 面向密钥合同 / 配置解析的窄范围 `coerceSecretRef` 和 `SecretRef` 类型辅助函数 | + | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本脱敏、常量时间密钥比较和密钥收集辅助函数 | | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 | - | `plugin-sdk/ssrf-dispatcher` | 不包含宽泛 infra 运行时接口的窄范围固定 dispatcher 辅助函数 | - | `plugin-sdk/ssrf-runtime` | 固定 dispatcher、受 SSRF 保护的 fetch、SSRF 错误和 SSRF 策略辅助函数 | - | `plugin-sdk/secret-input` | secret 输入解析辅助函数 | - | `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助函数，以及原始 websocket/body 强制转换 | - | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助函数 | + | `plugin-sdk/ssrf-dispatcher` | 不含广泛基础设施运行时接口的窄范围 pinned-dispatcher 辅助函数 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch、SSRF 错误和 SSRF 策略辅助函数 | + | `plugin-sdk/secret-input` | 密钥输入解析辅助函数 | + | `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助函数，以及原始 websocket / body 强制转换 | + | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 宽泛的运行时/日志/备份/插件安装辅助函数 | - | `plugin-sdk/runtime-env` | 窄范围的运行时环境、logger、超时、重试和退避辅助函数 | - | `plugin-sdk/browser-config` | 受支持的浏览器配置 facade，用于规范化 profile/默认值、CDP URL 解析和浏览器控制鉴权辅助函数 | + | `plugin-sdk/runtime` | 范围广泛的运行时 / 日志 / 备份 / 插件安装辅助函数 | + | `plugin-sdk/runtime-env` | 窄范围运行时环境、logger、超时、重试和退避辅助函数 | + | `plugin-sdk/browser-config` | 受支持的浏览器配置外观层，用于规范化的配置文件 / 默认值、CDP URL 解析和浏览器控制认证辅助函数 | | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助函数 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共享插件命令/钩子/HTTP/交互式辅助函数 | - | `plugin-sdk/hook-runtime` | 共享 webhook/内部钩子管道辅助函数 | - | `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | + | `plugin-sdk/plugin-runtime` | 共享插件命令 / 钩子 / HTTP / 交互式辅助函数 | + | `plugin-sdk/hook-runtime` | 共享 webhook / 内部钩子流水线辅助函数 | + | `plugin-sdk/lazy-runtime` | 惰性运行时导入 / 绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | 进程 exec 辅助函数 | | `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和惰性命令组辅助函数 | | `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道 Status 补丁辅助函数 | - | `plugin-sdk/config-types` | 仅类型的配置 surface，用于插件配置形状，例如 `OpenClawConfig` 以及渠道/提供商配置类型 | + | `plugin-sdk/config-types` | 仅类型的配置接口，用于插件配置结构，例如 `OpenClawConfig` 以及渠道 / 提供商配置类型 | | `plugin-sdk/plugin-config-runtime` | 运行时插件配置查找辅助函数，例如 `requireRuntimeConfig`、`resolvePluginConfigObject` 和 `resolveLivePluginConfigObject` | | `plugin-sdk/config-mutation` | 事务性配置变更辅助函数，例如 `mutateConfigFile`、`replaceConfigFile` 和 `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | 当前进程配置快照辅助函数，例如 `getRuntimeConfig`、`getRuntimeConfigSnapshot` 和测试快照 setter | - | `plugin-sdk/telegram-command-config` | Telegram 命令名/描述规范化以及重复/冲突检查，即使内置 Telegram 契约 surface 不可用也可使用 | - | `plugin-sdk/text-autolink-runtime` | 不依赖宽泛 text-runtime barrel 的文件引用自动链接检测 | - | `plugin-sdk/approval-runtime` | exec/插件审批辅助函数、审批能力构建器、鉴权/profile 辅助函数、原生路由/运行时辅助函数，以及结构化审批显示路径格式化 | - | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助函数、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围的回复分发/收尾和对话标签辅助函数 | - | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数和标记，例如 `buildHistoryContext`、`HISTORY_CONTEXT_MARKER`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/runtime-config-snapshot` | 当前进程配置快照辅助函数，例如 `getRuntimeConfig`、`getRuntimeConfigSnapshot` 和测试快照设置器 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化，以及重复 / 冲突检查，即使内置 Telegram 合同接口不可用也可使用 | + | `plugin-sdk/text-autolink-runtime` | 不依赖广泛 text-runtime barrel 的文件引用自动链接检测 | + | `plugin-sdk/approval-runtime` | exec / 插件审批辅助函数、审批能力构建器、认证 / 配置文件辅助函数、原生路由 / 运行时辅助函数，以及结构化审批显示路径格式化 | + | `plugin-sdk/reply-runtime` | 共享入站 / 回复运行时辅助函数、分块、派发、heartbeat、回复规划器 | + | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复派发 / 收尾和会话标签辅助函数 | + | `plugin-sdk/reply-history` | 共享短时间窗口回复历史辅助函数和标记，例如 `buildHistoryContext`、`HISTORY_CONTEXT_MARKER`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 窄范围的文本/Markdown 分块辅助函数 | + | `plugin-sdk/reply-chunking` | 窄范围文本 / Markdown 分块辅助函数 | | `plugin-sdk/session-store-runtime` | 会话存储路径、会话键、更新时间和存储变更辅助函数 | - | `plugin-sdk/cron-store-runtime` | Cron 存储路径/加载/保存辅助函数 | - | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助函数 | - | `plugin-sdk/routing` | 路由/会话键/账户绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享渠道/账户 Status 摘要辅助函数、运行时状态默认值和问题元数据辅助函数 | + | `plugin-sdk/cron-store-runtime` | Cron 存储路径 / 加载 / 保存辅助函数 | + | `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助函数 | + | `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | 共享渠道 / 账户 Status 摘要辅助函数、运行时状态默认值和问题元数据辅助函数 | | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助函数 | - | `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助函数 | - | `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL | - | `plugin-sdk/run-command` | 带时间控制的命令运行器，返回规范化的 stdout/stderr 结果 | - | `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 | - | `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 | + | `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助函数 | + | `plugin-sdk/request-url` | 从 fetch / request 类输入中提取字符串 URL | + | `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout / stderr 结果 | + | `plugin-sdk/param-readers` | 常用工具 / CLI 参数读取器 | + | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化载荷 | + | `plugin-sdk/tool-send` | 从工具参数中提取标准发送目标字段 | | `plugin-sdk/temp-path` | 共享临时下载路径辅助函数 | | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助函数 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助函数 | - | `plugin-sdk/model-session-runtime` | 模型/会话覆盖辅助函数，例如 `applyModelOverrideToSessionEntry` 和 `resolveAgentMaxConcurrent` | + | `plugin-sdk/model-session-runtime` | 模型 / 会话覆盖辅助函数，例如 `applyModelOverrideToSessionEntry` 和 `resolveAgentMaxConcurrent` | | `plugin-sdk/talk-config-runtime` | Talk 提供商配置解析辅助函数 | | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 | | `plugin-sdk/file-lock` | 可重入文件锁辅助函数 | | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 | - | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助函数 | + | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复派发辅助函数 | | `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 | - | `plugin-sdk/agent-config-primitives` | 窄范围的智能体运行时配置 schema 原语 | + | `plugin-sdk/agent-config-primitives` | 窄范围 agent 运行时配置 schema 原语 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 | - | `plugin-sdk/device-bootstrap` | 设备 bootstrap 和配对令牌辅助函数 | + | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 | | `plugin-sdk/extension-shared` | 共享被动渠道、Status 和环境代理辅助原语 | - | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助函数 | + | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 | | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助函数 | - | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助函数 | - | `plugin-sdk/agent-harness` | 面向低层 Agent harness 的实验性受信任插件 surface：harness 类型、活跃运行 steer/abort 辅助函数、OpenClaw 工具桥接辅助函数、运行时计划工具策略辅助函数、终端结果分类、工具进度格式化/详情辅助函数以及尝试结果工具函数 | + | `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助函数 | + | `plugin-sdk/agent-harness` | 面向低层智能体 harness 的实验性可信插件接口：harness 类型、活动运行 steer / abort 辅助函数、OpenClaw 工具桥接辅助函数、运行时规划工具策略辅助函数、终端结果分类、工具进度格式化 / 详情辅助函数，以及尝试结果工具函数 | | `plugin-sdk/provider-zai-endpoint` | Z.A.I 端点检测辅助函数 | - | `plugin-sdk/async-lock-runtime` | 面向小型运行时状态文件的进程本地异步锁辅助函数 | + | `plugin-sdk/async-lock-runtime` | 面向小型运行时状态文件的进程内 async 锁辅助函数 | | `plugin-sdk/channel-activity-runtime` | 渠道活动遥测辅助函数 | | `plugin-sdk/concurrency-runtime` | 有界异步任务并发辅助函数 | | `plugin-sdk/dedupe-runtime` | 内存去重缓存辅助函数 | - | `plugin-sdk/delivery-queue-runtime` | 出站待投递排空辅助函数 | - | `plugin-sdk/file-access-runtime` | 安全本地文件和媒体源路径辅助函数 | - | `plugin-sdk/heartbeat-runtime` | 心跳事件和可见性辅助函数 | + | `plugin-sdk/delivery-queue-runtime` | 出站待投递清空辅助函数 | + | `plugin-sdk/file-access-runtime` | 安全的本地文件和媒体源路径辅助函数 | + | `plugin-sdk/heartbeat-runtime` | heartbeat 事件和可见性辅助函数 | | `plugin-sdk/number-runtime` | 数值强制转换辅助函数 | - | `plugin-sdk/secure-random-runtime` | 安全令牌/UUID 辅助函数 | + | `plugin-sdk/secure-random-runtime` | 安全令牌 / UUID 辅助函数 | | `plugin-sdk/system-event-runtime` | 系统事件队列辅助函数 | | `plugin-sdk/transport-ready-runtime` | 传输就绪等待辅助函数 | - | `plugin-sdk/infra-runtime` | 已弃用的兼容性 shim；请使用上方更聚焦的运行时子路径 | + | `plugin-sdk/infra-runtime` | 已弃用的兼容性垫片；请改用上面更聚焦的运行时子路径 | | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | - | `plugin-sdk/diagnostic-runtime` | 诊断标志、事件和 trace-context 辅助函数 | + | `plugin-sdk/diagnostic-runtime` | 诊断标记、事件和 trace-context 辅助函数 | | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和固定查找辅助函数 | - | `plugin-sdk/runtime-fetch` | 不引入代理/受保护 fetch 导入、具备 dispatcher 感知能力的运行时 fetch | - | `plugin-sdk/response-limit-runtime` | 不依赖宽泛 media 运行时 surface 的有界响应体读取器 | - | `plugin-sdk/session-binding-runtime` | 当前对话绑定状态，不包含已配置绑定路由或配对存储 | - | `plugin-sdk/session-store-runtime` | 不包含宽泛配置写入/维护导入的会话存储辅助函数 | - | `plugin-sdk/context-visibility-runtime` | 不引入宽泛配置/安全导入的上下文可见性解析和补充上下文过滤 | - | `plugin-sdk/string-coerce-runtime` | 不引入 markdown/logging 导入的窄范围原始记录/字符串强制转换和规范化辅助函数 | + | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和 pinned 查找辅助函数 | + | `plugin-sdk/runtime-fetch` | 不引入代理 / 受保护 fetch 导入的 dispatcher 感知型运行时 fetch | + | `plugin-sdk/response-limit-runtime` | 不依赖广泛媒体运行时接口的有界响应体读取器 | + | `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 | + | `plugin-sdk/session-store-runtime` | 不引入广泛配置写入 / 维护导入的会话存储辅助函数 | + | `plugin-sdk/context-visibility-runtime` | 不依赖广泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 | + | `plugin-sdk/string-coerce-runtime` | 不依赖 markdown / logging 导入的窄范围原始记录 / 字符串强制转换和规范化辅助函数 | | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 | - | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 | - | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助函数 | - | `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 | + | `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助函数 | + | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / Agent 工作区辅助函数 | + | `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助函数，以及媒体负载构建器 | - | `plugin-sdk/media-store` | 窄范围的媒体存储辅助函数，例如 `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障切换辅助函数、候选项选择和缺失模型消息 | - | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助函数，例如去除对助手可见的文本、Markdown 渲染/分块/表格辅助函数、脱敏辅助函数、指令标签辅助函数和安全文本工具 | + | `plugin-sdk/media-runtime` | 共享媒体获取 / 转换 / 存储辅助函数，以及媒体载荷构建器 | + | `plugin-sdk/media-store` | 窄范围媒体存储辅助函数，例如 `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助函数、候选项选择和缺失模型提示消息 | + | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享文本 / Markdown / 日志辅助函数，例如对助手可见文本的剥离、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 | | `plugin-sdk/text-chunking` | 出站文本分块辅助函数 | | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的指令、注册表、校验和语音辅助导出 | | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、指令、规范化和语音辅助导出 | - | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助函数和共享 WebSocket 会话辅助函数 | + | `plugin-sdk/realtime-transcription` | 实时转写提供商类型、注册表辅助函数和共享 WebSocket 会话辅助函数 | | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 | | `plugin-sdk/image-generation` | 图像生成提供商类型 | - | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障切换、鉴权和注册表辅助函数 | - | `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 | - | `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助函数 | - | `plugin-sdk/webhook-path` | Webhook 路径规范化辅助函数 | - | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助函数 | + | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助函数 | + | `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成提供商 / 请求 / 结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助函数 | + | `plugin-sdk/webhook-path` | webhook 路径规范化辅助函数 | + | `plugin-sdk/web-media` | 共享远程 / 本地媒体加载辅助函数 | | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/testing` | 公开的扩展测试辅助函数，包括插件注册表/运行时 mock、schema/媒体/live-test 辅助函数、`installCommonResolveTargetErrorCases`、`writeSkill`、`createTestRegistry` 和实时生成功能环境加载。扩展 `*.test-support.ts` 辅助函数应放在这里或聚焦的 SDK 子路径上，而不是核心内部 | + | `plugin-sdk/testing` | 公共扩展测试辅助函数，包括插件注册表 / 运行时 mock、fetch / 环境变量 / 临时 fixture、schema / 媒体 / 实时测试辅助函数、`installCommonResolveTargetErrorCases`、`writeSkill`、`createTestRegistry` 以及实时生成环境加载。扩展 `*.test-support.ts` 辅助函数应保留在该路径或聚焦的 SDK 子路径上，而不是核心内部 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助接口 surface，用于 manager/config/file/CLI 辅助函数 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时 facade | - | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商以及通用批处理/远程辅助函数 | - | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助函数 | - | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助函数 | - | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助函数 | - | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助函数 | - | `plugin-sdk/memory-core-host-status` | Memory host Status 辅助函数 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助函数 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助函数 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助函数 | - | `plugin-sdk/memory-host-core` | 面向供应商中立的 Memory host 核心运行时辅助函数别名 | - | `plugin-sdk/memory-host-events` | 面向供应商中立的 Memory host 事件日志辅助函数别名 | - | `plugin-sdk/memory-host-files` | 面向供应商中立的 Memory host 文件/运行时辅助函数别名 | - | `plugin-sdk/memory-host-markdown` | 用于 Memory 相邻插件的共享托管 Markdown 辅助函数 | - | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活跃 Memory 运行时 facade | - | `plugin-sdk/memory-host-status` | 面向供应商中立的 Memory host Status 辅助函数别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 surface | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于 manager / config / file / CLI 辅助函数 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时外观层 | + | `plugin-sdk/memory-core-host-engine-foundation` | Memory 主机基础引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机 embedding 合同、注册表访问、本地提供商以及通用批处理 / 远程辅助函数 | + | `plugin-sdk/memory-core-host-engine-qmd` | Memory 主机 QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | Memory 主机存储引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | Memory 主机多模态辅助函数 | + | `plugin-sdk/memory-core-host-query` | Memory 主机查询辅助函数 | + | `plugin-sdk/memory-core-host-secret` | Memory 主机密钥辅助函数 | + | `plugin-sdk/memory-core-host-events` | Memory 主机事件日志辅助函数 | + | `plugin-sdk/memory-core-host-status` | Memory 主机 Status 辅助函数 | + | `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件 / 运行时辅助函数 | + | `plugin-sdk/memory-host-core` | 面向厂商中立的别名，用于 Memory 主机核心运行时辅助函数 | + | `plugin-sdk/memory-host-events` | 面向厂商中立的别名，用于 Memory 主机事件日志辅助函数 | + | `plugin-sdk/memory-host-files` | 面向厂商中立的别名，用于 Memory 主机文件 / 运行时辅助函数 | + | `plugin-sdk/memory-host-markdown` | 面向 Memory 邻近插件的共享托管 Markdown 辅助函数 | + | `plugin-sdk/memory-host-search` | 用于访问搜索管理器的活动 Memory 运行时外观层 | + | `plugin-sdk/memory-host-status` | 面向厂商中立的别名，用于 Memory 主机 Status 辅助函数 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 | - | 家族 | 当前子路径 | 预期用途 | + | 系列 | 当前子路径 | 预期用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置浏览器插件支持辅助函数。`browser-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 形状。`browser-support` 仍然是兼容性 barrel。 | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时接口 surface | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时接口 surface | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 surface | - | 渠道专用辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | 已弃用的内置渠道兼容性/辅助接口。新插件应导入通用 SDK 子路径或插件本地 barrel。 | - | 鉴权/插件专用辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | 浏览器 | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置浏览器插件支持辅助函数。`browser-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 结构。`browser-support` 仍作为兼容性 barrel。 | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助 / 运行时接口 | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助 / 运行时接口 | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 | + | 渠道专用辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | 已弃用的内置渠道兼容性 / 辅助接口。新插件应导入通用 SDK 子路径或插件本地 barrel。 | + | 认证 / 插件专用辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | diff --git a/docs/zh-CN/plugins/sdk-testing.md b/docs/zh-CN/plugins/sdk-testing.md index 8531b0b92..14730cecd 100644 --- a/docs/zh-CN/plugins/sdk-testing.md +++ b/docs/zh-CN/plugins/sdk-testing.md @@ -1,24 +1,24 @@ --- read_when: - - 你正在为插件编写测试 + - 你正在为一个插件编写测试 - 你需要来自插件 SDK 的测试工具 - 你想了解内置插件的契约测试 sidebarTitle: Testing -summary: OpenClaw 插件的测试工具和模式 +summary: OpenClaw 插件的测试工具与模式 title: 插件测试 x-i18n: - generated_at: "2026-04-27T12:55:14Z" + generated_at: "2026-04-27T22:22:37Z" model: gpt-5.4 provider: openai - source_hash: 3030e2a838b641433da2882270ef2b332284a7fc2f16037681b51536de42998e + source_hash: 358a1e76d6a8e78ad503b040d49bab7f66fa8bfb2f1fe7dcb6088ef932e56860 source_path: plugins/sdk-testing.md workflow: 15 --- -OpenClaw 插件的测试工具、模式和 lint 强制规则参考。 +OpenClaw 插件的测试工具、模式以及 lint 强制规则参考。 - **在找测试示例吗？** 操作指南中包含了完整的测试示例： + **在找测试示例？** 操作指南中包含了完整的测试示例： [渠道插件测试](/zh-CN/plugins/sdk-channel-plugins#step-6-test) 和 [提供商插件测试](/zh-CN/plugins/sdk-provider-plugins#step-6-test)。 @@ -27,7 +27,7 @@ OpenClaw 插件的测试工具、模式和 lint 强制规则参考。 **导入：** `openclaw/plugin-sdk/testing` -testing 子路径为插件作者导出了一组精简的辅助工具： +测试子路径为插件作者导出了一组精简的辅助工具： ```typescript import { @@ -39,15 +39,26 @@ import { ### 可用导出 -| 导出 | 用途 | -| -------------------------------------- | ------------------------------------------------------ | -| `installCommonResolveTargetErrorCases` | 目标解析错误处理的共享测试用例 | -| `shouldAckReaction` | 检查某个渠道是否应添加 ack reaction | -| `removeAckReactionAfterReply` | 在回复投递后移除 ack reaction | +| 导出 | 用途 | +| -------------------------------------- | ---------------------------- | +| `installCommonResolveTargetErrorCases` | 用于目标解析错误处理的共享测试用例 | +| `shouldAckReaction` | 检查某个渠道是否应添加 ack reaction | +| `removeAckReactionAfterReply` | 在回复送达后移除 ack reaction | +| `createTestRegistry` | 构建渠道插件注册表 fixture | +| `createEmptyPluginRegistry` | 构建空的插件注册表 fixture | +| `setActivePluginRegistry` | 为插件运行时测试安装注册表 fixture | +| `createRequestCaptureJsonFetch` | 在媒体辅助工具测试中捕获 JSON fetch 请求 | +| `withFetchPreconnect` | 在安装了 preconnect hooks 的情况下运行 fetch 测试 | +| `withEnv` / `withEnvAsync` | 临时修改环境变量 | +| `createTempHomeEnv` / `withTempDir` | 创建隔离的文件系统测试 fixture | +| `createMockServerResponse` | 创建一个最小化的 HTTP 服务器响应 mock | +| `registerSingleProviderPlugin` | 在 loader 冒烟测试中注册一个提供商插件 | +| `createRuntimeTaskFlow` | 创建隔离的运行时任务流状态 | +| `typedCases` | 为表驱动测试保留字面量类型 | ### 类型 -testing 子路径还会重新导出一些在测试文件中有用的类型： +测试子路径还会重新导出在测试文件中有用的类型： ```typescript import type { @@ -62,8 +73,7 @@ import type { ## 测试目标解析 -使用 `installCommonResolveTargetErrorCases` 为 -渠道目标解析添加标准错误用例： +使用 `installCommonResolveTargetErrorCases` 为渠道目标解析添加标准错误用例： ```typescript import { describe } from "vitest"; @@ -78,7 +88,7 @@ describe("my-channel target resolution", () => { implicitAllowFrom: ["user1", "user2"], }); - // 添加渠道特定测试用例 + // 添加渠道特定的测试用例 it("should resolve @username targets", () => { // ... }); @@ -89,22 +99,13 @@ describe("my-channel target resolution", () => { ### 测试注册契约 -将手写的 `api` mock 传给 `register(api)` 的单元测试，并不能覆盖 -OpenClaw 加载器的接收门禁。对于插件依赖的每一种注册接口，至少添加一个基于加载器的冒烟测试， -尤其是钩子和像 memory 这样的独占能力。 +把手写的 `api` mock 传给 `register(api)` 的单元测试，并不能覆盖 OpenClaw 的 loader 接受门禁。对于你的插件依赖的每个注册入口，至少添加一个基于 loader 的冒烟测试，尤其是 hooks 和 memory 这类独占能力。 -当缺少必需元数据，或者某个插件调用了它不拥有的能力 API 时， -真实加载器会让插件注册失败。例如， -`api.registerHook(...)` 需要一个 hook 名称，而 -`api.registerMemoryCapability(...)` 需要在插件清单或导出的 -入口点中声明 `kind: "memory"`。 +真实的 loader 会在缺少必需元数据，或插件调用了其并不拥有的能力 API 时，使插件注册失败。例如，`api.registerHook(...)` 需要一个 hook 名称，而 `api.registerMemoryCapability(...)` 则要求插件 manifest 或导出的入口声明 `kind: "memory"`。 ### 测试运行时配置访问 -测试内置插件时，优先使用仓库测试辅助工具中的共享插件运行时 mock。 -其已弃用的 `runtime.config.loadConfig()` 和 -`runtime.config.writeConfigFile(...)` mock 默认会抛错，以便让测试捕获对兼容 API 的新增使用。 -只有当测试明确覆盖旧版兼容行为时，才覆盖这些 mock。 +在测试内置插件时，优先使用仓库测试辅助工具中的共享插件运行时 mock。它的已弃用 `runtime.config.loadConfig()` 和 `runtime.config.writeConfigFile(...)` mocks 默认会抛错，这样测试就能捕获对兼容性 API 的新使用。只有在测试明确覆盖旧版兼容行为时，才覆盖这些 mocks。 ### 渠道插件的单元测试 @@ -172,7 +173,7 @@ describe("my-provider plugin", () => { ### Mock 插件运行时 -对于使用 `createPluginRuntimeStore` 的代码，请在测试中 mock 运行时： +对于使用 `createPluginRuntimeStore` 的代码，在测试中应 mock 运行时： ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; @@ -187,7 +188,7 @@ const store = createPluginRuntimeStore({ const mockRuntime = { agent: { resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"), - // ... 其他 mock + // ... 其他 mocks }, config: { current: vi.fn(() => ({}) as const), @@ -199,16 +200,16 @@ const mockRuntime = { store.setRuntime(mockRuntime); -// 测试后 +// 测试结束后 store.clearRuntime(); ``` -### 使用按实例 stub 进行测试 +### 使用按实例设置的 stub 进行测试 -优先使用按实例 stub，而不是修改原型： +优先使用按实例设置的 stub，而不是修改原型： ```typescript -// 推荐：按实例 stub +// 推荐：按实例设置 stub const client = new MyChannelClient(); client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); @@ -218,7 +219,7 @@ client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); ## 契约测试（仓库内插件） -内置插件带有契约测试，用于验证注册归属关系： +内置插件带有用于验证注册归属的契约测试： ```bash pnpm test -- src/plugins/contracts/ @@ -228,18 +229,18 @@ pnpm test -- src/plugins/contracts/ - 哪些插件注册了哪些提供商 - 哪些插件注册了哪些语音提供商 -- 注册形状是否正确 -- 运行时契约是否合规 +- 注册形状的正确性 +- 运行时契约符合性 -### 运行范围化测试 +### 运行限定范围测试 -针对特定插件： +针对某个特定插件： ```bash pnpm test -- /my-channel/ ``` -仅运行契约测试： +只运行契约测试： ```bash pnpm test -- src/plugins/contracts/shape.contract.test.ts @@ -249,9 +250,9 @@ pnpm test -- src/plugins/contracts/runtime.contract.test.ts ## lint 强制规则（仓库内插件） -对于仓库内插件，`pnpm check` 会强制执行三条规则： +`pnpm check` 会对仓库内插件强制执行三条规则： -1. **禁止单体根导入** —— 会拒绝 `openclaw/plugin-sdk` 根 barrel +1. **禁止整体式根导入** —— 拒绝使用 `openclaw/plugin-sdk` 根 barrel 2. **禁止直接导入 `src/`** —— 插件不能直接导入 `../../src/` 3. **禁止自导入** —— 插件不能导入自己的 `plugin-sdk/` 子路径 @@ -268,10 +269,10 @@ pnpm test # 运行特定插件测试 pnpm test -- /my-channel/src/channel.test.ts -# 使用特定测试名称过滤运行 +# 使用特定测试名称过滤器运行 pnpm test -- /my-channel/ -t "resolves account" -# 带覆盖率运行 +# 运行并收集覆盖率 pnpm test:coverage ``` @@ -281,9 +282,9 @@ pnpm test:coverage OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test ``` -## 相关 +## 相关内容 -- [SDK 概览](/zh-CN/plugins/sdk-overview) -- 导入约定 -- [渠道插件 SDK](/zh-CN/plugins/sdk-channel-plugins) -- 渠道插件接口 -- [提供商插件 SDK](/zh-CN/plugins/sdk-provider-plugins) -- 提供商插件钩子 -- [构建插件](/zh-CN/plugins/building-plugins) -- 入门指南 +- [SDK 概览](/zh-CN/plugins/sdk-overview) —— 导入约定 +- [SDK 渠道插件](/zh-CN/plugins/sdk-channel-plugins) —— 渠道插件接口 +- [SDK 提供商插件](/zh-CN/plugins/sdk-provider-plugins) —— 提供商插件钩子 +- [构建插件](/zh-CN/plugins/building-plugins) —— 入门指南