chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
81fa5269ef
commit
cf23bc0038
@ -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` 必须是支持图像的 `<provider/model>` |
|
||||
| 运行文本/模型提示 | `openclaw infer model run --prompt "..." --json` | 默认使用常规本地路径 |
|
||||
| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 从现有文件开始时使用 `image edit` |
|
||||
| 描述图像文件 | `openclaw infer image describe --file ./image.png --json` | `--model` 必须是具备图像能力的 `<provider/model>` |
|
||||
| 转录音频 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` 必须是 `<provider/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` 必须是 `<provider/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` 必须使用 `<provider/model>` 形式。
|
||||
- 对于 `image describe`，显式传入 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/<model>` 会运行一次受限的 Codex app-server 图像理解回合；`openai-codex/<model>` 使用 OpenAI Codex OAuth provider 路径。
|
||||
- 对于 `image describe`，显式提供 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/<model>` 会运行一个受限的 Codex app-server 图像理解轮次；`openai-codex/<model>` 使用 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
|
||||
```
|
||||
|
||||
使用完整的 `<provider/model>` 引用来对特定提供商进行冒烟测试，而无需启动 Gateway 网关或加载完整的智能体工具面：
|
||||
使用完整的 `<provider/model>` 引用来对特定提供商执行冒烟测试，而无需启动 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 <provider/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 <provider/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` 必须是支持图像的 `<provider/model>`。
|
||||
- 对于本地 Ollama 视觉模型，先拉取模型，并将 `OLLAMA_API_KEY` 设为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。
|
||||
- 对于 `image describe`，`--model` 必须是具备图像能力的 `<provider/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` 必须是 `<provider/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。
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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
|
||||
```
|
||||
|
||||
接受默认选项而不提示（包括在适用时的重启/服务/沙箱修复步骤）。
|
||||
接受默认选项而不提示（在适用时，包括重启/服务/沙箱修复步骤）。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair">
|
||||
@ -38,7 +38,7 @@ openclaw doctor
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
无需提示即可应用推荐的修复（在安全情况下执行修复 + 重启）。
|
||||
不经提示应用建议的修复（在安全情况下执行修复 + 重启）。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair --force">
|
||||
@ -46,7 +46,7 @@ openclaw doctor
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
也会应用激进修复（会覆盖自定义 supervisor 配置）。
|
||||
也应用激进修复（会覆盖自定义 supervisor 配置）。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--non-interactive">
|
||||
@ -54,7 +54,7 @@ openclaw doctor
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
在无提示的情况下运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态时，会自动运行旧版状态迁移。
|
||||
无提示运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。会跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态时，会自动运行旧版状态迁移。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--deep">
|
||||
@ -62,7 +62,7 @@ openclaw doctor
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
扫描系统服务以查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。
|
||||
扫描系统服务以查找额外的 Gateway 网关安装（`launchd`/`systemd`/`schtasks`）。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -73,76 +73,76 @@ openclaw doctor
|
||||
cat ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
## 它会做什么（摘要）
|
||||
## 它会执行什么操作（摘要）
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="健康状况、UI 和更新">
|
||||
- 针对 git 安装的可选预检更新（仅交互模式）。
|
||||
- 为 git 安装提供可选的预检更新（仅交互模式）。
|
||||
- UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。
|
||||
- 健康检查 + 重启提示。
|
||||
- Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。
|
||||
- Skills 状态摘要（可用/缺失/被阻止）和插件状态。
|
||||
</Accordion>
|
||||
<Accordion title="配置和迁移">
|
||||
- 针对旧版值的配置规范化。
|
||||
- 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.<provider>` 的 Talk 配置迁移。
|
||||
- 旧版值的配置规范化。
|
||||
- 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.<provider>` 的 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`。
|
||||
</Accordion>
|
||||
<Accordion title="状态和完整性">
|
||||
- 会话锁文件检查和陈旧锁清理。
|
||||
- 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支会话转录。
|
||||
- 状态完整性和权限检查（sessions、transcripts、状态目录）。
|
||||
- 会话锁文件检查和过时锁清理。
|
||||
- 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支的会话转录。
|
||||
- 状态完整性和权限检查（会话、转录、状态目录）。
|
||||
- 本地运行时的配置文件权限检查（`chmod 600`）。
|
||||
- 模型认证健康检查：检查 OAuth 过期情况，可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。
|
||||
- 模型认证健康状况：检查 OAuth 过期时间、可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。
|
||||
- 额外工作区目录检测（`~/openclaw`）。
|
||||
</Accordion>
|
||||
<Accordion title="Gateway 网关、服务和 supervisor">
|
||||
- 在启用沙箱隔离时修复沙箱镜像。
|
||||
- 在启用沙箱隔离时执行沙箱镜像修复。
|
||||
- 旧版服务迁移和额外 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`）。
|
||||
</Accordion>
|
||||
<Accordion title="认证、安全和配对">
|
||||
- 针对开放私信策略的安全警告。
|
||||
- local token 模式的 Gateway 网关认证检查（在没有 token 来源时提供生成 token；不会覆盖 token SecretRef 配置）。
|
||||
- 设备配对问题检测（首次配对请求待处理、角色/作用域升级待处理、陈旧的本地设备 token 缓存漂移，以及已配对记录的认证漂移）。
|
||||
- 本地令牌模式的 Gateway 网关认证检查（当不存在令牌来源时提供令牌生成功能；不会覆盖 token SecretRef 配置）。
|
||||
- 设备配对问题检测（首次配对请求待处理、角色/作用域升级待处理、本地设备令牌缓存漂移过时，以及已配对记录的认证漂移）。
|
||||
</Accordion>
|
||||
<Accordion title="工作区和 shell">
|
||||
- Linux 上的 systemd linger 检查。
|
||||
- 工作区 bootstrap 文件大小检查（上下文文件的截断/接近限制警告）。
|
||||
- Linux 上的 `systemd linger` 检查。
|
||||
- 工作区 bootstrap 文件大小检查（上下文文件的截断/接近上限警告）。
|
||||
- shell 补全状态检查和自动安装/升级。
|
||||
- Memory 搜索嵌入提供商就绪状态检查（本地模型、远程 API key 或 QMD 二进制文件）。
|
||||
- 源码安装检查（pnpm 工作区不匹配、缺失 UI 资源、缺失 tsx 二进制文件）。
|
||||
- Memory 搜索 embedding 提供商就绪状态检查（本地模型、远程 API 密钥或 QMD 二进制）。
|
||||
- 源码安装检查（`pnpm` 工作区不匹配、缺少 UI 资源、缺少 `tsx` 二进制）。
|
||||
- 写入更新后的配置 + 向导元数据。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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` 作为审查界面。
|
||||
|
||||
## 详细行为和原理
|
||||
## 详细行为和原因说明
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="0. 可选更新（git 安装）">
|
||||
如果这是一个 git 检出，并且 doctor 以交互模式运行，它会先提供在运行 doctor 之前更新（fetch/rebase/build）的选项。
|
||||
如果这是一个 git 检出，并且 doctor 以交互模式运行，它会在运行 doctor 之前提供更新选项（fetch/rebase/build）。
|
||||
</Accordion>
|
||||
<Accordion title="1. 配置规范化">
|
||||
如果配置中包含旧版值结构（例如没有渠道专属覆盖的 `messages.ackReaction`），doctor 会将其规范化为当前 schema。
|
||||
如果配置包含旧版值结构（例如 `messages.ackReaction` 没有特定于渠道的覆盖），doctor 会将其规范化为当前 schema。
|
||||
|
||||
这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置为 `talk.provider` + `talk.providers.<provider>`。doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 结构重写到提供商映射中。
|
||||
这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置为 `talk.provider` + `talk.providers.<provider>`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 结构重写到提供商映射中。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. 旧版配置键迁移">
|
||||
当配置包含已弃用的键时，其他命令会拒绝运行，并要求你运行 `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.<provider>`
|
||||
- `routing.agentToAgent` → `tools.agentToAgent`
|
||||
- `routing.transcribeAudio` → `tools.media.audio.models`
|
||||
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
|
||||
- `messages.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `messages.tts.providers.<provider>`
|
||||
- `messages.tts.provider: "edge"` 和 `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` 和 `messages.tts.providers.microsoft`
|
||||
- `channels.discord.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.<provider>`
|
||||
- `channels.discord.accounts.<id>.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts.<id>.voice.tts.providers.<provider>`
|
||||
- `plugins.entries.voice-call.config.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.<provider>`
|
||||
- `channels.discord.voice.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.voice.tts.providers.<provider>`
|
||||
- `channels.discord.accounts.<id>.voice.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.accounts.<id>.voice.tts.providers.<provider>`
|
||||
- `plugins.entries.voice-call.config.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `plugins.entries.voice-call.config.tts.providers.<provider>`
|
||||
- `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.<id>.timeoutSeconds`
|
||||
- 删除 `agents.defaults.llm`；慢速提供商/模型超时请使用 `models.providers.<id>.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.<channel>.defaultAccount` 或 `accounts.default` 的情况下配置了两个或更多 `channels.<channel>.accounts` 条目，doctor 会警告回退路由可能会选择意外的账户。
|
||||
- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有 `channels.<channel>.defaultAccount` 或 `accounts.default`，doctor 会警告回退路由可能选择意外账户。
|
||||
- 如果 `channels.<channel>.defaultAccount` 被设置为未知账户 ID，doctor 会发出警告并列出已配置的账户 ID。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2b. OpenCode 提供商覆盖">
|
||||
如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型走错误的 API，或将成本归零。Doctor 会发出警告，以便你移除该覆盖并恢复按模型路由的 API + 成本。
|
||||
<Accordion title="2b. OpenCode provider 覆盖">
|
||||
如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型使用错误的 API，或将费用归零。Doctor 会发出警告，以便你移除该覆盖并恢复按模型路由的 API + 费用。
|
||||
</Accordion>
|
||||
<Accordion title="2c. 浏览器迁移和 Chrome MCP 就绪状态">
|
||||
如果你的浏览器配置仍然指向已移除的 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。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2d. OAuth TLS 前置条件">
|
||||
当配置了 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 网关健康，该探测也会运行。
|
||||
</Accordion>
|
||||
<Accordion title="2e. Codex OAuth 提供商覆盖">
|
||||
如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽较新版本自动使用的内置 Codex OAuth 提供商路径。当 doctor 看到这些旧的传输设置与 Codex OAuth 同时存在时，会发出警告，以便你移除或重写过期的传输覆盖，从而恢复内置路由/回退行为。自定义代理和仅头部覆盖仍受支持，不会触发此警告。
|
||||
<Accordion title="2e. Codex OAuth provider 覆盖">
|
||||
如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽新版本自动使用的内置 Codex OAuth provider 路径。当 doctor 在 Codex OAuth 旁边看到这些旧传输设置时，会发出警告，以便你移除或重写过时的传输覆盖，并恢复内置的路由/回退行为。自定义代理和仅标头覆盖仍受支持，不会触发此警告。
|
||||
</Accordion>
|
||||
<Accordion title="2f. Codex 插件路由警告">
|
||||
启用内置 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，请保持该警告原样不动。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. 旧版状态迁移（磁盘布局）">
|
||||
Doctor 可以将旧版磁盘布局迁移到当前结构：
|
||||
Doctor 可以将较旧的磁盘布局迁移到当前结构：
|
||||
|
||||
- 会话存储 + 转录：
|
||||
- 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Agent 目录：
|
||||
- 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
|
||||
- 从 `~/.openclaw/sessions/` 迁移到 `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- 智能体目录：
|
||||
- 从 `~/.openclaw/agent/` 迁移到 `~/.openclaw/agents/<agentId>/agent/`
|
||||
- WhatsApp 认证状态（Baileys）：
|
||||
- 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
|
||||
- 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账户 ID：`default`）
|
||||
- 迁移到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账户 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` 更改。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3a. 旧版插件 manifest 迁移">
|
||||
Doctor 会扫描所有已安装插件的 manifest，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到后，它会建议将它们移入 `contracts` 对象，并原地重写 manifest 文件。该迁移是幂等的；如果 `contracts` 键中已包含相同值，则会移除旧键而不会重复数据。
|
||||
<Accordion title="3a. 旧版插件清单迁移">
|
||||
Doctor 会扫描所有已安装的插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。发现后，它会提供将它们移动到 `contracts` 对象中，并原地重写清单文件。此迁移是幂等的；如果 `contracts` 键中已经有相同的值，则会删除旧版键，而不会重复数据。
|
||||
</Accordion>
|
||||
<Accordion title="3b. 旧版 cron 存储迁移">
|
||||
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 会发出警告，并将该任务留给你手动审查。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3c. 会话锁清理">
|
||||
Doctor 会扫描每个 agent 会话目录中的陈旧写锁文件——这些文件通常是会话异常退出后遗留的。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍存活、锁年龄，以及是否被视为陈旧（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除陈旧锁文件；否则，它会打印说明并提示你使用 `--fix` 重新运行。
|
||||
Doctor 会扫描每个智能体会话目录中的过时写锁文件——即会话异常退出后遗留的文件。对于发现的每个锁文件，它会报告：路径、PID、该 PID 是否仍存活、锁的存在时长，以及它是否被视为过时（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动删除过时锁文件；否则它会输出说明，并指示你使用 `--fix` 重新运行。
|
||||
</Accordion>
|
||||
<Accordion title="3d. 会话转录分支修复">
|
||||
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 读取器就不会再看到重复轮次。
|
||||
</Accordion>
|
||||
<Accordion title="4. 状态完整性检查（会话持久化、路由和安全）">
|
||||
状态目录是运行中的“脑干”。如果它消失，你将失去会话、凭证、日志和配置（除非你在其他地方有备份）。
|
||||
状态目录是运行层面的中枢。如果它消失了，你将丢失会话、凭证、日志和配置（除非你在其他地方有备份）。
|
||||
|
||||
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` 的选项。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. 模型认证健康检查（OAuth 过期）">
|
||||
Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已过期，它会建议使用 Anthropic API key 或 Anthropic setup-token 路径。刷新提示只会在交互模式（TTY）下出现；`--non-interactive` 会跳过刷新尝试。
|
||||
<Accordion title="5. 模型认证健康状况（OAuth 过期）">
|
||||
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 还会报告因以下原因而暂时不可用的认证配置：
|
||||
|
||||
- 短暂冷却（速率限制/超时/认证失败）
|
||||
- 更长期禁用（计费/额度失败）
|
||||
- 短时间冷却（速率限制/超时/认证失败）
|
||||
- 较长时间禁用（账单/额度失败）
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="6. Hooks 模型验证">
|
||||
如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在其无法解析或不被允许时发出警告。
|
||||
如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证该模型引用，并在它无法解析或不被允许时发出警告。
|
||||
</Accordion>
|
||||
<Accordion title="7. 沙箱镜像修复">
|
||||
启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。
|
||||
</Accordion>
|
||||
<Accordion title="7b. 内置插件运行时依赖">
|
||||
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` 树。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8. Gateway 网关服务迁移和清理提示">
|
||||
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`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8b. 启动时 Matrix 迁移">
|
||||
当 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时，doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都不是致命错误；错误会被记录，启动会继续。在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查会被完全跳过。
|
||||
当 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时，doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续进行。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。
|
||||
</Accordion>
|
||||
<Accordion title="8c. 设备配对和认证漂移">
|
||||
Doctor 现在会把设备配对状态纳入常规健康检查的一部分。
|
||||
Doctor 现在会将设备配对状态作为常规健康检查的一部分进行检查。
|
||||
|
||||
它会报告：
|
||||
|
||||
- 首次配对请求待处理
|
||||
- 已配对设备的角色升级待处理
|
||||
- 已配对设备的作用域升级待处理
|
||||
- 公钥不匹配修复：设备 ID 仍然匹配，但设备身份已不再匹配已批准记录
|
||||
- 已配对记录缺少已批准角色的活动 token
|
||||
- 已配对 token 的作用域漂移到已批准配对基线之外
|
||||
- 当前机器的本地缓存设备 token 条目早于 Gateway 网关侧 token 轮换，或携带过期的作用域元数据
|
||||
- 待处理的首次配对请求
|
||||
- 已配对设备待处理的角色升级
|
||||
- 已配对设备待处理的作用域升级
|
||||
- 当设备 ID 仍匹配但设备身份不再匹配已批准记录时的公钥不匹配修复
|
||||
- 已配对记录中缺少已批准角色的活动令牌
|
||||
- 作用域漂移超出已批准配对基线的已配对令牌
|
||||
- 当前机器上的本地缓存设备令牌条目早于 Gateway 网关侧令牌轮换，或携带过时作用域元数据
|
||||
|
||||
Doctor 不会自动批准配对请求，也不会自动轮换设备 token。它会直接输出精确的下一步操作：
|
||||
Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它会改为输出精确的下一步操作：
|
||||
|
||||
- 使用 `openclaw devices list` 检查待处理请求
|
||||
- 使用 `openclaw devices approve <requestId>` 批准指定请求
|
||||
- 使用 `openclaw devices rotate --device <deviceId> --role <role>` 轮换新的 token
|
||||
- 使用 `openclaw devices remove <deviceId>` 删除并重新批准过期记录
|
||||
- 使用 `openclaw devices approve <requestId>` 批准精确请求
|
||||
- 使用 `openclaw devices rotate --device <deviceId> --role <role>` 轮换新的令牌
|
||||
- 使用 `openclaw devices remove <deviceId>` 删除并重新批准过时记录
|
||||
|
||||
这填补了常见的“已经配对但仍然提示需要配对”的漏洞：doctor 现在可以区分首次配对、待处理的角色/作用域升级，以及过期 token/设备身份漂移。
|
||||
这样就堵住了常见的“明明已经配对但仍然提示需要配对”的漏洞：doctor 现在可以区分首次配对、待处理的角色/作用域升级，以及过时的令牌/设备身份漂移。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="9. 安全警告">
|
||||
当某个提供商对私信开放但没有允许列表，或者某项策略以危险方式配置时，doctor 会发出警告。
|
||||
当某个 provider 对私信开放但没有允许列表，或者某项策略以危险方式配置时，doctor 会发出警告。
|
||||
</Accordion>
|
||||
<Accordion title="10. systemd linger（Linux）">
|
||||
如果以 systemd 用户服务运行，doctor 会确保启用 lingering，以便 Gateway 网关在注销后继续运行。
|
||||
如果作为 systemd 用户服务运行，doctor 会确保已启用 lingering，以便 Gateway 网关在注销后仍保持运行。
|
||||
</Accordion>
|
||||
<Accordion title="11. 工作区状态（Skills、插件和旧版目录）">
|
||||
Doctor 会输出默认 agent 的工作区状态摘要：
|
||||
Doctor 会打印默认智能体的工作区状态摘要：
|
||||
|
||||
- **Skills 状态**：统计符合条件、缺少要求以及被允许列表阻止的 Skills。
|
||||
- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。
|
||||
- **插件状态**：统计已启用/已禁用/出错的插件；列出出错插件的插件 ID；报告内置插件能力。
|
||||
- **Skills 状态**：统计可用、缺少要求和被允许列表阻止的 Skills 数量。
|
||||
- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区同时存在时发出警告。
|
||||
- **插件状态**：统计已启用/已禁用/出错的插件数量；列出所有出错插件的插件 ID；报告 bundle 插件能力。
|
||||
- **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。
|
||||
- **插件诊断**：展示插件注册表在加载时输出的任何警告或错误。
|
||||
- **插件诊断**：显示插件注册表在加载时发出的任何警告或错误。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="11b. Bootstrap 文件大小">
|
||||
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` 的建议。
|
||||
</Accordion>
|
||||
<Accordion title="11d. 过期渠道插件清理">
|
||||
当 `openclaw doctor --fix` 移除缺失的渠道插件时，它还会移除引用该插件的悬空渠道作用域配置：`channels.<id>` 条目、命名该渠道的 heartbeat 目标，以及 `agents.*.models["<channel>/*"]` 覆盖。这可以防止 Gateway 网关在渠道运行时已不存在、但配置仍要求 Gateway 网关绑定到它时进入启动循环。
|
||||
<Accordion title="11d. 过时渠道插件清理">
|
||||
当 `openclaw doctor --fix` 删除缺失的渠道插件时，它也会删除引用该插件的悬空渠道作用域配置：`channels.<id>` 条目、指定该渠道的心跳目标，以及 `agents.*.models["<channel>/*"]` 覆盖。这可以防止 Gateway 网关启动循环：渠道运行时已经不存在，但配置仍要求 Gateway 网关绑定到它。
|
||||
</Accordion>
|
||||
<Accordion title="11c. shell 补全">
|
||||
Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否安装了 Tab 补全：
|
||||
<Accordion title="11c. Shell 补全">
|
||||
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` 可手动重新生成缓存。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12. Gateway 网关认证检查（local token）">
|
||||
Doctor 会检查本地 Gateway 网关 token 认证的就绪状态。
|
||||
<Accordion title="12. Gateway 网关认证检查（本地令牌）">
|
||||
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` 才会强制生成令牌。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12b. 只读的 SecretRef 感知修复">
|
||||
<Accordion title="12b. 只读 SecretRef 感知修复">
|
||||
某些修复流程需要检查已配置的凭证，同时又不能削弱运行时快速失败行为。
|
||||
|
||||
- `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 会报告该凭证“已配置但不可用”，并跳过自动解析，而不是崩溃或错误地将令牌报告为缺失。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="13. Gateway 网关健康检查 + 重启">
|
||||
Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。
|
||||
</Accordion>
|
||||
<Accordion title="13b. Memory 搜索就绪状态">
|
||||
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 就绪状态。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="14. 渠道状态警告">
|
||||
如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告带有建议修复方案的警告。
|
||||
如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告附带建议修复方案的警告。
|
||||
</Accordion>
|
||||
<Accordion title="15. supervisor 配置审计 + 修复">
|
||||
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` 强制执行完整重写。
|
||||
|
||||
</Accordion>
|
||||
@ -461,13 +461,16 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
Doctor 会检查服务运行时（PID、最近退出状态），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。
|
||||
</Accordion>
|
||||
<Accordion title="17. Gateway 网关运行时最佳实践">
|
||||
当 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 审计保持一致。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="18. 配置写入 + 向导元数据">
|
||||
Doctor 会持久化任何配置更改，并写入向导元数据以记录本次 doctor 运行。
|
||||
Doctor 会持久化所有配置更改，并写入向导元数据以记录本次 doctor 运行。
|
||||
</Accordion>
|
||||
<Accordion title="19. 工作区提示（备份 + Memory 系统）">
|
||||
当工作区缺少 Memory 系统时，doctor 会给出建议；如果工作区尚未受 git 管理，它还会输出备份提示。
|
||||
当工作区缺少 Memory 系统时，Doctor 会建议使用一个工作区 Memory 系统；如果工作区尚未置于 git 管理下，它还会输出备份提示。
|
||||
|
||||
有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。
|
||||
|
||||
|
||||
@ -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
|
||||
---
|
||||
|
||||
<Warning>
|
||||
**安全敏感功能。** 此模式会将身份验证完全委托给你的反向代理。配置错误可能会让未经授权的访问暴露你的 Gateway 网关。启用前请仔细阅读本页。
|
||||
**安全敏感功能。** 此模式会将身份验证完全委托给你的反向代理。配置错误可能会让你的 Gateway 网关暴露给未授权访问。在启用前请仔细阅读本页。
|
||||
</Warning>
|
||||
|
||||
## 何时使用
|
||||
|
||||
在以下情况下使用 `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 以获得更简单的设置）。
|
||||
|
||||
## 工作原理
|
||||
|
||||
<Steps>
|
||||
<Step title="代理验证用户身份">
|
||||
你的反向代理会验证用户身份（OAuth、OIDC、SAML 等）。
|
||||
你的反向代理验证用户身份（OAuth、OIDC、SAML 等）。
|
||||
</Step>
|
||||
<Step title="代理添加身份标头">
|
||||
代理会添加一个包含已验证用户身份的标头（例如 `x-forwarded-user: nick@example.com`）。
|
||||
代理添加一个包含已验证用户身份的标头（例如 `x-forwarded-user: nick@example.com`）。
|
||||
</Step>
|
||||
<Step title="Gateway 网关验证受信任来源">
|
||||
OpenClaw 会检查请求是否来自**受信任的代理 IP**（在 `gateway.trustedProxies` 中配置）。
|
||||
OpenClaw 检查请求是否来自**受信任的代理 IP**（在 `gateway.trustedProxies` 中配置）。
|
||||
</Step>
|
||||
<Step title="Gateway 网关提取身份">
|
||||
OpenClaw 会从已配置的标头中提取用户身份。
|
||||
OpenClaw 从已配置的标头中提取用户身份。
|
||||
</Step>
|
||||
<Step title="授权">
|
||||
如果一切检查通过，则请求会被授权。
|
||||
如果所有检查都通过，则请求会被授权。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 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:
|
||||
<Warning>
|
||||
**重要运行时规则**
|
||||
|
||||
- 受信任代理身份验证会拒绝来自 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 身份验证。
|
||||
</Warning>
|
||||
|
||||
### 配置参考
|
||||
@ -122,16 +122,16 @@ x-i18n:
|
||||
用户身份允许列表。为空表示允许所有已验证用户。
|
||||
</ParamField>
|
||||
|
||||
## TLS 终止与 HSTS
|
||||
## TLS 终止和 HSTS
|
||||
|
||||
使用一个 TLS 终止点，并在那里应用 HSTS。
|
||||
使用单一 TLS 终止点，并在那里应用 HSTS。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="代理 TLS 终止（推荐）">
|
||||
当你的反向代理为 `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` 显式禁用。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 发布指导
|
||||
|
||||
- 开始时先使用较短的 max age（例如 `max-age=300`）来验证流量。
|
||||
- 只有在确信无误后，再增加到长期值（例如 `max-age=31536000`）。
|
||||
- 仅当每个子域都已准备好支持 HTTPS 时，才添加 `includeSubDomains`。
|
||||
- 开始时先使用较短的最大存活时间（例如 `max-age=300`）来验证流量。
|
||||
- 仅在你有足够把握后，再增加到长期值（例如 `max-age=31536000`）。
|
||||
- 只有在每个子域都已支持 HTTPS 时，才添加 `includeSubDomains`。
|
||||
- 仅当你有意满足整个域名集合的 preload 要求时，才使用 preload。
|
||||
- 仅限 loopback 的本地开发不会从 HSTS 中获益。
|
||||
- 仅限 loopback 的本地开发无法从 HSTS 中受益。
|
||||
|
||||
## 代理设置示例
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Pomerium">
|
||||
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:
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="nginx + oauth2-proxy">
|
||||
oauth2-proxy 会验证用户身份，并通过 `x-auth-request-email` 传递身份。
|
||||
oauth2-proxy 验证用户身份，并在 `x-auth-request-email` 中传递身份。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -291,20 +291,20 @@ x-i18n:
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 混合令牌配置
|
||||
## 混合 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` 中。
|
||||
|
||||
</Accordion>
|
||||
@ -376,7 +377,7 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同
|
||||
用户标头为空或缺失。请检查：
|
||||
|
||||
- 你的代理是否已配置为传递身份标头？
|
||||
- 标头名称是否正确？（大小写不敏感，但拼写很重要）
|
||||
- 标头名称是否正确？（不区分大小写，但拼写必须正确）
|
||||
- 用户是否确实已在代理处完成身份验证？
|
||||
|
||||
</Accordion>
|
||||
@ -384,11 +385,11 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同
|
||||
某个必需标头不存在。请检查：
|
||||
|
||||
- 你的代理中针对这些特定标头的配置。
|
||||
- 标头是否在链路中的某处被剥离。
|
||||
- 标头是否在链路中的某个位置被剥离了。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="trusted_proxy_user_not_allowed">
|
||||
用户已通过身份验证，但不在 `allowUsers` 中。请将其加入，或移除允许列表。
|
||||
用户已通过身份验证，但不在 `allowUsers` 中。请将其添加进去，或移除允许列表。
|
||||
</Accordion>
|
||||
<Accordion title="trusted_proxy_origin_not_allowed">
|
||||
trusted-proxy 身份验证已成功，但浏览器的 `Origin` 标头未通过 Control UI 来源检查。
|
||||
@ -396,27 +397,27 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同
|
||||
请检查：
|
||||
|
||||
- `gateway.controlUi.allowedOrigins` 是否包含精确的浏览器来源。
|
||||
- 你是否没有依赖通配符来源，除非你确实想要允许所有来源的行为。
|
||||
- 如果你有意使用 Host 标头回退模式，是否已明确设置 `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true`。
|
||||
- 除非你确实想允许所有来源，否则不要依赖通配符来源。
|
||||
- 如果你有意使用 Host 标头回退模式，请确认已明确设置 `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="WebSocket 仍然失败">
|
||||
请确保你的代理：
|
||||
确保你的代理：
|
||||
|
||||
- 支持 WebSocket 升级（`Upgrade: websocket`、`Connection: upgrade`）。
|
||||
- 在 WebSocket 升级请求中传递身份标头（而不只是 HTTP）。
|
||||
- 在 WebSocket 升级请求中也会传递身份标头（而不仅仅是 HTTP）。
|
||||
- 没有为 WebSocket 连接设置单独的身份验证路径。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 从令牌身份验证迁移
|
||||
## 从 token 身份验证迁移
|
||||
|
||||
如果你正在从令牌身份验证迁移到 trusted-proxy：
|
||||
如果你正从 token 身份验证迁移到 trusted-proxy：
|
||||
|
||||
<Steps>
|
||||
<Step title="配置代理">
|
||||
配置你的代理来验证用户身份并传递标头。
|
||||
配置你的代理，使其验证用户身份并传递标头。
|
||||
</Step>
|
||||
<Step title="独立测试代理">
|
||||
独立测试代理设置（使用带标头的 curl）。
|
||||
@ -428,10 +429,10 @@ loopback 的受信任代理身份验证也会以失败关闭方式处理：同
|
||||
重启 Gateway 网关。
|
||||
</Step>
|
||||
<Step title="测试 WebSocket">
|
||||
从 Control UI 测试 WebSocket 连接。
|
||||
测试来自 Control UI 的 WebSocket 连接。
|
||||
</Step>
|
||||
<Step title="审计">
|
||||
运行 `openclaw security audit` 并查看发现项。
|
||||
运行 `openclaw security audit` 并查看结果。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -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 访问的更简单替代方案
|
||||
|
||||
@ -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` |
|
||||
|
||||
<AccordionGroup>
|
||||
@ -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` 和密钥目标类型 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="提供商子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `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` | 窄范围群组激活模式和命令解析辅助函数 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="鉴权与安全子路径">
|
||||
<Accordion title="认证与安全子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `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` | 请求体大小 / 超时辅助函数 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="运行时与存储子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `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` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="能力与测试子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `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 子路径上，而不是核心内部 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory 子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `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 辅助接口 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="保留的内置辅助子路径">
|
||||
| 家族 | 当前子路径 | 预期用途 |
|
||||
| 系列 | 当前子路径 | 预期用途 |
|
||||
| --- | --- | --- |
|
||||
| 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` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
|
||||
@ -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 强制规则参考。
|
||||
|
||||
<Tip>
|
||||
**在找测试示例吗？** 操作指南中包含了完整的测试示例：
|
||||
**在找测试示例？** 操作指南中包含了完整的测试示例：
|
||||
[渠道插件测试](/zh-CN/plugins/sdk-channel-plugins#step-6-test) 和
|
||||
[提供商插件测试](/zh-CN/plugins/sdk-provider-plugins#step-6-test)。
|
||||
</Tip>
|
||||
@ -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<PluginRuntime>({
|
||||
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 -- <bundled-plugin-root>/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/<name>` 子路径
|
||||
|
||||
@ -268,10 +269,10 @@ pnpm test
|
||||
# 运行特定插件测试
|
||||
pnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts
|
||||
|
||||
# 使用特定测试名称过滤运行
|
||||
# 使用特定测试名称过滤器运行
|
||||
pnpm test -- <bundled-plugin-root>/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) —— 入门指南
|
||||
|
||||
Loading…
Reference in New Issue
Block a user