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

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-29 04:08:52 +00:00
parent 1076bd5c97
commit 43d7e949cd
5 changed files with 969 additions and 984 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

281
docs/zh-CN/concepts/model-providers.md
View File

@ -3,18 +3,18 @@ read_when:
- 你需要一份按提供商划分的模型设置参考
- 你想要模型提供商的示例配置或 CLI 新手引导命令
sidebarTitle: Model providers
summary: 模型提供商概览，包含示例配置 + CLI 流程
summary: 模型提供商概览，包含示例配置和 CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-04-28T11:49:37Z"
generated_at: "2026-04-29T04:06:10Z"
model: gpt-5.5
provider: openai
source_hash: caf3d258b9d6028f13ea04ec3dd9bb70ae4de34316271eaa49fd7932cbc962f8
source_hash: ee6c7fc1a87ec8db7df291ac87281e13b43b0b4e2076e1084698932b9a3bf1b9
source_path: concepts/model-providers.md
workflow: 16
---
LLM/模型提供商参考（不是 WhatsApp/Telegram 等聊天渠道）。模型选择规则见 [Models](/zh-CN/concepts/models)。
**LLM/模型提供商**参考（不是 WhatsApp/Telegram 这样的聊天渠道）。有关模型选择规则，请参阅 [Models](/zh-CN/concepts/models)。
## 快速规则
@ -23,28 +23,28 @@ LLM/模型提供商参考（不是 WhatsApp/Telegram 等聊天渠道）。模型
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
- 设置 `agents.defaults.models` 后，它会作为允许列表。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 按模型覆盖这些默认值。
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 会按模型覆盖它们。
- 回退规则、冷却探测和会话覆盖持久化：[模型故障转移](/zh-CN/concepts/model-failover)。
</Accordion>
<Accordion title="OpenAI provider/运行时拆分">
OpenAI 系列路由按前缀区分：
- `openai/<model>` 在 PI 中使用直接 OpenAI API 密钥提供商。
- `openai-codex/<model>` 在 PI 中使用 Codex OAuth。
- `openai/<model>` 加上 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex 应用服务器 harness。
- `openai/<model>` 使用 PI 中直接的 OpenAI API key 提供商。
- `openai-codex/<model>` 使用 PI 中的 Codex OAuth。
- `openai/<model>` 加上 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex app-server harness。
参见 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果 provider/运行时拆分让人困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果提供商/运行时拆分让人困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
插件自动启用遵循相同边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/<model>` 引用启用。
GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API 密钥流量，通过 PI 中的 `openai-codex/gpt-5.5` 用于 Codex OAuth，并且在设置 `agentRuntime.id: "codex"` 时可用于原生 Codex 应用服务器 harness。
GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API key 流量，通过 PI 中的 `openai-codex/gpt-5.5` 用于 Codex OAuth，并在设置 `agentRuntime.id: "codex"` 时通过原生 Codex app-server harness 使用。
</Accordion>
<Accordion title="CLI 运行时">
CLI 运行时使用相同拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在需要本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。
CLI 运行时使用相同拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在你想使用本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。
旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并将运行时单独记录。
旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并单独记录运行时。
</Accordion>
</AccordionGroup>
@ -53,55 +53,55 @@ LLM/模型提供商参考（不是 WhatsApp/Telegram 等聊天渠道）。模型
大多数提供商特定逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置文件等。
provider SDK 钩子和内置插件示例的完整列表位于 [Provider plugins](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于一个独立且更深的扩展表面。
提供商 SDK 钩子和内置插件示例的完整列表位于[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于一个单独、更深入的扩展表面。
<Note>
提供商运行时 `capabilities` 是共享的运行器元数据（提供商系列、转录/工具怪癖、传输/缓存提示）。它不同于[公共能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述插件注册的内容（文本推理、语音等）。
提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求辅助工具。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，共享 runner 逻辑已不再读取它。
</Note>
## API 密钥轮换
## API key 轮换
<AccordionGroup>
<Accordion title="密钥来源和优先级">
通过以下方式配置多个密钥：
<Accordion title="key 来源和优先级">
通过以下方式配置多个 key：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号分隔列表）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEYS`（逗号或分号列表）
- `<PROVIDER>_API_KEY`（主 key）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。密钥选择顺序会保留优先级并去重。
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。key 选择顺序会保留优先级并去重值。
</Accordion>
<Accordion title="轮换触发时机">
- 仅在速率限制响应时（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）才会使用下一个密钥重试请求。
- 非速率限制失败会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，返回最后一次尝试的最终错误。
<Accordion title="何时触发轮换">
- 仅在限速响应时才会使用下一个 key 重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
- 非限速失败会立即失败；不会尝试 key 轮换。
- 当所有候选 key 都失败时，会返回最后一次尝试的最终错误。
</Accordion>
</AccordionGroup>
## 内置提供商（pi-ai 目录）
OpenClaw 随附 pi‑ai 目录。这些提供商**不**需要 `models.providers` 配置；只需设置认证并选择模型。
OpenClaw 随附 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证并选择模型。
### OpenAI
- 提供商：`openai`
- 认证：`OPENAI_API_KEY`
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
- 凭证：`OPENAI_API_KEY`
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖项）
- 示例模型：`openai/gpt-5.5`、`openai/gpt-5.4-mini`
- 如果某个特定安装或 API 密钥表现不同，请使用 `openclaw models list --provider openai` 验证账户/模型可用性。
- 如果某个特定安装或 API key 表现不同，请使用 `openclaw models list --provider openai` 验证账号/模型可用性。
- CLI：`openclaw onboard --auth-choice openai-api-key`
- 默认传输为 `auto`（优先 WebSocket，SSE 回退）
- 通过 `agents.defaults.models["openai/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- 默认传输协议是 `auto`（WebSocket 优先，SSE 回退）
- 可通过 `agents.defaults.models["openai/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`）
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先处理
- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 当你需要显式层级而不是共享 `/fast` 开关时，使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）只适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI reasoning 兼容载荷整形；代理路由不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录不公开它
- OpenAI 优先处理可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用
- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射为 `api.openai.com` 上的 `service_tier=priority`
- 当你想使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不应用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示，以及 OpenAI reasoning 兼容的载荷整形；代理路由不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未公开它
```json5
{
@ -112,18 +112,15 @@ OpenClaw 随附 pi‑ai 目录。这些提供商**不**需要 `models.providers`
### Anthropic
- 提供商：`anthropic`
- 认证：`ANTHROPIC_API_KEY`
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
- 凭证：`ANTHROPIC_API_KEY`
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖项）
- 示例模型：`anthropic/claude-opus-4-6`
- CLI：`openclaw onboard --auth-choice apiKey`
- 直接公共 Anthropic 请求支持共享 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 对 `standard_only`）
- 首选 Claude CLI 配置会保持模型引用为规范形式，并单独选择 CLI
后端：`anthropic/claude-opus-4-7` 搭配
`agents.defaults.agentRuntime.id: "claude-cli"`。旧版
`claude-cli/claude-opus-4-7` 引用仍可用于兼容。
- 直接的公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API-key 和 OAuth 凭证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- 首选 Claude CLI 配置会保持模型引用规范化，并单独选择 CLI 后端：`anthropic/claude-opus-4-7` 搭配 `agents.defaults.agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 引用仍可用于兼容。
<Note>
Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 用法已再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成获准使用，除非 Anthropic 发布新策略。Anthropic 设置令牌仍作为受支持的 OpenClaw 令牌路径可用，但 OpenClaw 现在会优先使用 Claude CLI 复用和可用的 `claude -p`。
Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法已再次被允许，因此除非 Anthropic 发布新政策，OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的受认可方式。Anthropic setup-token 仍作为受支持的 OpenClaw 令牌路径提供，但 OpenClaw 现在会在可用时优先使用 Claude CLI 复用和 `claude -p`。
</Note>
```json5
@ -135,21 +132,21 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 用法已再
### OpenAI Codex OAuth
- 提供商：`openai-codex`
- 认证：OAuth（ChatGPT）
- 凭证：OAuth（ChatGPT）
- PI 模型引用：`openai-codex/gpt-5.5`
- 原生 Codex 应用服务器 harness 引用：`openai/gpt-5.5` 搭配 `agents.defaults.agentRuntime.id: "codex"`
- 原生 Codex 应用服务器 harness 文档：[Codex harness](/zh-CN/plugins/codex-harness)
- 原生 Codex app-server harness 引用：`openai/gpt-5.5` 搭配 `agents.defaults.agentRuntime.id: "codex"`
- 原生 Codex app-server harness 文档：[Codex harness](/zh-CN/plugins/codex-harness)
- 旧版模型引用：`codex/gpt-*`
- 插件边界：`openai-codex/*` 加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择。
- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex app-server 插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择。
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
- 默认传输为 `auto`（优先 WebSocket，SSE 回退）
- 通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 按 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上转发
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）只会附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量上，不适用于通用 OpenAI 兼容代理
- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority`
- `openai-codex/gpt-5.5` 使用 Codex 目录原生 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；使用 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 等外部工具/工作流。
- 当你需要 Codex OAuth/订阅路由时，使用 `openai-codex/gpt-5.5`；当你的 API 密钥设置和本地目录公开公共 API 路由时，使用 `openai/gpt-5.5`。
- 默认传输协议是 `auto`（WebSocket 优先，SSE 回退）
- 可通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 按 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `params.serviceTier` 也会转发到原生 Codex Responses 请求（`chatgpt.com/backend-api`）
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不附加到通用 OpenAI 兼容代理
- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
- `openai-codex/gpt-5.5` 使用 Codex 目录原生 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可使用 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具/工作流。
- 当你想使用 Codex OAuth/订阅路由时，请使用 `openai-codex/gpt-5.5`；当你的 API-key 设置和本地目录公开公共 API 路由时，请使用 `openai/gpt-5.5`。
```json5
{
@ -172,20 +169,20 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 用法已再
### 其他订阅式托管选项
<CardGroup cols={3}>
<Card title="GLM 模型" href="/zh-CN/providers/glm">
<Card title="GLM models" href="/zh-CN/providers/glm">
Z.AI Coding Plan 或通用 API 端点。
</Card>
<Card title="MiniMax" href="/zh-CN/providers/minimax">
MiniMax Coding Plan OAuth 或 API 密钥访问。
MiniMax Coding Plan OAuth 或 API key 访问。
</Card>
<Card title="Qwen Cloud" href="/zh-CN/providers/qwen">
Qwen Cloud 提供商表面，以及 Alibaba DashScope 和 Coding Plan 端点映射。
Qwen Cloud 提供商界面，以及 Alibaba DashScope 和 Coding Plan 端点映射。
</Card>
</CardGroup>
### OpenCode
- 认证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
- 凭证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
- Zen 运行时提供商：`opencode`
- Go 运行时提供商：`opencode-go`
- 示例模型：`opencode/claude-opus-4-6`、`opencode-go/kimi-k2.6`
@ -197,31 +194,31 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 用法已再
}
```
### Google Gemini（API 密钥）
### Google Gemini（API key）
- 提供商：`google`
- 认证：`GEMINI_API_KEY`
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
- 凭证：`GEMINI_API_KEY`
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖项）
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会规范化为 `google/gemini-3-flash-preview`
- 别名：`google/gemini-3.1-pro` 可被接受，并规范化为 Google 的实时 Gemini API ID：`google/gemini-3.1-pro-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview`
- 别名：`google/gemini-3.1-pro` 会被接受并规范化为 Google 的实时 Gemini API id：`google/gemini-3.1-pro-preview`
- CLI：`openclaw onboard --auth-choice gemini-api-key`
- Thinking：`/think adaptive` 使用 Google 动态 thinking。Gemini 3/3.1 会省略固定的 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。
- 直接 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会作为 OpenClaw `cacheRead` 呈现
- 思考：`/think adaptive` 使用 Google 动态思考。Gemini 3/3.1 会省略固定的 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。
- 直接 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
### Google Vertex 和 Gemini CLI
- 提供商：`google-vertex`、`google-gemini-cli`
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
- 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
<Warning>
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告在使用第三方客户端后遇到 Google 账户限制。请审阅 Google 条款；如果选择继续，请使用非关键账户。
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后遇到 Google 账号限制。请查阅 Google 条款；如果选择继续，请使用非关键账号。
</Warning>
Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
<Steps>
<Step title="安装 Gemini CLI">
<Step title="Install Gemini CLI">
<Tabs>
<Tab title="brew">
```bash
@ -235,68 +232,68 @@ Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
</Tab>
</Tabs>
</Step>
<Step title="启用插件">
<Step title="Enable plugin">
```bash
openclaw plugins enable google
```
</Step>
<Step title="登录">
<Step title="Login">
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不要**把客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会把令牌存储在 Gateway 网关主机上的认证配置文件中。
默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不要**把客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置档案中。
</Step>
<Step title="设置项目（如有需要）">
<Step title="Set project (if needed)">
如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
</Step>
</Steps>
Gemini CLI 的 JSON 回复会从 `response` 解析；用量会回退到 `stats`，并将 `stats.cached` 规范化为 OpenClaw 的 `cacheRead`。
Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，并将 `stats.cached` 规范化为 OpenClaw `cacheRead`。
### Z.AI（GLM）
### Z.AI (GLM)
- 提供商：`zai`
- 认证：`ZAI_API_KEY`
- 凭证：`ZAI_API_KEY`
- 示例模型：`zai/glm-5.1`
- CLI：`openclaw onboard --auth-choice zai-api-key`
- 别名：`z.ai/*` 和 `z-ai/*` 会规范化为 `zai/*`
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定表面
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口面
### Vercel AI Gateway
### Vercel AI Gateway 网关
- 提供商：`vercel-ai-gateway`
- 认证：`AI_GATEWAY_API_KEY`
- 凭证：`AI_GATEWAY_API_KEY`
- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`、`vercel-ai-gateway/moonshotai/kimi-k2.6`
- CLI：`openclaw onboard --auth-choice ai-gateway-api-key`
### Kilo Gateway
### Kilo Gateway 网关
- 提供商：`kilocode`
- 认证：`KILOCODE_API_KEY`
- 凭证：`KILOCODE_API_KEY`
- 示例模型：`kilocode/kilo/auto`
- CLI：`openclaw onboard --auth-choice kilocode-api-key`
- 基础 URL：`https://api.kilo.ai/api/gateway/`
- 静态回退目录随附 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 设备发现可以进一步扩展运行时目录。
- `kilocode/kilo/auto` 背后的准确上游路由由 Kilo Gateway 拥有，不是在 OpenClaw 中硬编码的。
- 静态回退目录随附 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时目录。
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 网关拥有，不在 OpenClaw 中硬编码。
有关设置详情，请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。
设置详情请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。
### 其他内置提供商插件
| 提供商 | ID | 认证环境变量 | 示例模型 |
| 提供商 | ID | 认证环境变量 | 示例模型 |
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- |
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
| Cloudflare AI Gateway 网关 | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
| DeepInfra | `deepinfra` | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V3.2` |
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` |
| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — |
| Groq | `groq` | `GROQ_API_KEY` | — |
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
| Kimi Coding | `kimi` | `KIMI_API_KEY` or `KIMICODE_API_KEY` | `kimi/kimi-code` |
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
| Kilo Gateway 网关 | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
| Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` |
| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` |
| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` |
| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` |
@ -307,28 +304,28 @@ Gemini CLI 的 JSON 回复会从 `response` 解析；用量会回退到 `stats`
| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` |
| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` |
| Venice | `venice` | `VENICE_API_KEY` | — |
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
| 火山引擎（豆包） | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
| Vercel AI Gateway 网关 | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` |
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
#### 值得了解的特殊情况
#### 值得了解的细节
<AccordionGroup>
<Accordion title="OpenRouter">
仅在已验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 管理的提示缓存的 cache-TTL 条件，但不会接收 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容）。Gemini 支持的引用仅保留代理 Gemini 思维签名清理。
仅在已验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 托管的提示缓存的缓存 TTL 条件，但不会收到 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的塑形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容性）。Gemini 后端引用只保留代理 Gemini 思维签名清理。
</Accordion>
<Accordion title="Kilo Gateway">
Gemini 支持的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。
Gemini 后端引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。
</Accordion>
<Accordion title="MiniMax">
API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在插件拥有的 `MiniMax-VL-01` 媒体提供商上。
</Accordion>
<Accordion title="xAI">
使用 xAI Responses 路径。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为它们的 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 禁用。
使用 xAI Responses 路径。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 禁用。
</Accordion>
<Accordion title="Cerebras">
作为内置的 `cerebras` 提供商插件随附。GLM 使用 `zai-glm-4.7`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。
作为内置 `cerebras` 提供商插件随附。GLM 使用 `zai-glm-4.7`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。
</Accordion>
</AccordionGroup>
@ -336,16 +333,16 @@ Gemini CLI 的 JSON 回复会从 `response` 解析；用量会回退到 `stats`
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。
下面许多内置提供商插件已经发布默认目录。只有当你想覆盖默认基础 URL、标头或模型列表时，才使用显式的 `models.providers.<id>` 条目。
下面的许多内置提供商插件已经发布默认目录。只有当你想覆盖默认基础 URL、标头或模型列表时，才使用显式的 `models.providers.<id>` 条目。
Gateway 网关模型能力检查也会读取显式的 `models.providers.<id>.models[]` 元数据。如果自定义或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，这样 WebChat 和节点来源附件路径会将图像作为原生模型输入传递，而不是纯文本媒体引用。
Gateway 网关模型能力检查也会读取显式的 `models.providers.<id>.models[]` 元数据。如果自定义或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，这样 WebChat 和节点来源附件路径就会把图像作为原生模型输入传递，而不是作为纯文本媒体引用。
### Moonshot AI（Kimi）
### Moonshot AI (Kimi)
Moonshot 作为内置提供商插件随附。默认使用内置提供商，只有在需要覆盖基础 URL 或模型元数据时才添加显式的 `models.providers.moonshot` 条目：
Moonshot 作为内置提供商插件随附。默认使用内置提供商，只有在需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
- 提供商：`moonshot`
- 认证：`MOONSHOT_API_KEY`
- 凭证：`MOONSHOT_API_KEY`
- 示例模型：`moonshot/kimi-k2.6`
- CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`
@ -382,7 +379,7 @@ Kimi K2 模型 ID：
### Kimi 编码
Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
Kimi 编码使用 Moonshot AI 的 Anthropic 兼容端点：
- 提供商：`kimi`
- 认证：`KIMI_API_KEY`
@ -399,9 +396,9 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
旧版 `kimi/k2p5` 仍作为兼容模型 ID 被接受。
### Volcano Engine（豆包）
### Volcano Engine（Doubao）
Volcano Engine（火山引擎）在中国提供对豆包和其他模型的访问。
Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。
- 提供商：`volcengine`（编码：`volcengine-plan`）
- 认证：`VOLCANO_ENGINE_API_KEY`
@ -416,20 +413,20 @@ Volcano Engine（火山引擎）在中国提供对豆包和其他模型的访问
}
```
新手引导默认使用编码界面，但通用 `volcengine/*` 目录会同时注册。
新手引导默认使用编码界面，但通用的 `volcengine/*` 目录会同时注册。
在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的提供商范围选择器。
在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商限定选择器。
<Tabs>
<Tab title="Standard models">
- `volcengine/doubao-seed-1-8-251228`（豆包 Seed 1.8）
<Tab title="标准模型">
- `volcengine/doubao-seed-1-8-251228`（Doubao Seed 1.8）
- `volcengine/doubao-seed-code-preview-251028`
- `volcengine/kimi-k2-5-260127`（Kimi K2.5）
- `volcengine/glm-4-7-251222`（GLM 4.7）
- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K）
</Tab>
<Tab title="Coding models (volcengine-plan)">
<Tab title="编码模型（volcengine-plan）">
- `volcengine-plan/ark-code-latest`
- `volcengine-plan/doubao-seed-code`
- `volcengine-plan/kimi-k2.5`
@ -441,7 +438,7 @@ Volcano Engine（火山引擎）在中国提供对豆包和其他模型的访问
### BytePlus（国际版）
BytePlus ARK 为国际用户提供对与 Volcano Engine 相同模型的访问。
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。
- 提供商：`byteplus`（编码：`byteplus-plan`）
- 认证：`BYTEPLUS_API_KEY`
@ -456,9 +453,9 @@ BytePlus ARK 为国际用户提供对与 Volcano Engine 相同模型的访问。
}
```
新手引导默认使用编码界面，但通用 `byteplus/*` 目录会同时注册。
新手引导默认使用编码界面，但通用的 `byteplus/*` 目录会同时注册。
在新手引导/配置模型选择器中，BytePlus 凭证选择会优先显示 `byteplus/*` 和 `byteplus-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的、按提供商限定的选择器。
在新手引导/配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商限定选择器。
<Tabs>
<Tab title="标准模型">
@ -515,28 +512,28 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax API 密钥（中国）：`--auth-choice minimax-cn-api`
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
设置详情、模型选项和配置片段见 [/providers/minimax](/zh-CN/providers/minimax)。
有关设置详情、模型选项和配置片段，请参阅 [/providers/minimax](/zh-CN/providers/minimax)。
<Note>
在 MiniMax 兼容 Anthropic 的流式路径上，除非你显式设置，OpenClaw 默认会禁用思考，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
在 MiniMax 的兼容 Anthropic 的流式传输路径上，除非你显式设置，否则 OpenClaw 默认会禁用 thinking，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
</Note>
插件拥有的能力拆分：
- 文本/聊天默认保留在 `minimax/MiniMax-M2.7`
- 文本/聊天默认值保留在 `minimax/MiniMax-M2.7`
- 图像生成是 `minimax/image-01` 或 `minimax-portal/image-01`
- 图像理解是在两个 MiniMax 凭证路径上都由插件拥有的 `MiniMax-VL-01`
- Web 搜索保留在提供商 ID `minimax`
### LM Studio
LM Studio 作为内置提供商插件提供，并使用原生 API：
LM Studio 作为内置提供商插件发布，使用原生 API：
- 提供商：`lmstudio`
- 凭证：`LM_API_TOKEN`
- 默认推理基础 URL：`http://localhost:1234/v1`
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的 ID 之一）：
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
```json5
{
@ -546,19 +543,19 @@ LM Studio 作为内置提供商插件提供，并使用原生 API：
}
```
OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。设置和故障排除见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。有关设置和故障排除，请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
### Ollama
Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API：
Ollama 作为内置提供商插件发布，并使用 Ollama 的原生 API：
- 提供商：`ollama`
- 凭证：无需（本地服务器）
- 凭证：不需要（本地服务器）
- 示例模型：`ollama/llama3.3`
- 安装：[https://ollama.com/download](https://ollama.com/download)
```bash
# Install Ollama, then pull a model:
# 安装 Ollama，然后拉取一个模型：
ollama pull llama3.3
```
@ -570,23 +567,23 @@ ollama pull llama3.3
}
```
当你使用 `OLLAMA_API_KEY` 选择启用时，会在本地 `http://127.0.0.1:11434` 检测 Ollama，并且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器。新手引导、云端/本地模式和自定义配置见 [/providers/ollama](/zh-CN/providers/ollama)。
当你使用 `OLLAMA_API_KEY` 选择启用时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，并且内置提供商插件会把 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。有关新手引导、云/本地模式和自定义配置，请参阅 [/providers/ollama](/zh-CN/providers/ollama)。
### vLLM
vLLM 作为内置提供商插件提供，面向本地/自托管的 OpenAI 兼容服务器：
vLLM 作为内置提供商插件发布，用于本地/自托管的兼容 OpenAI 的服务器：
- 提供商：`vllm`
- 凭证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:8000/v1`
要在本地选择启用自动发现（如果你的服务器不强制执行凭证，任意值都可以）：
要在本地选择启用自动设备发现（如果你的服务器不强制凭证，任何值都可以）：
```bash
export VLLM_API_KEY="vllm-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的 ID 之一）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -596,23 +593,23 @@ export VLLM_API_KEY="vllm-local"
}
```
详情见 [/providers/vllm](/zh-CN/providers/vllm)。
有关详情，请参阅 [/providers/vllm](/zh-CN/providers/vllm)。
### SGLang
SGLang 作为内置提供商插件提供，面向快速自托管的 OpenAI 兼容服务器：
SGLang 作为内置提供商插件发布，用于快速的自托管兼容 OpenAI 的服务器：
- 提供商：`sglang`
- 凭证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:30000/v1`
要在本地选择启用自动发现（如果你的服务器不强制执行凭证，任意值都可以）：
要在本地选择启用自动设备发现（如果你的服务器不强制凭证，任何值都可以）：
```bash
export SGLANG_API_KEY="sglang-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的 ID 之一）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -622,7 +619,7 @@ export SGLANG_API_KEY="sglang-local"
}
```
详情见 [/providers/sglang](/zh-CN/providers/sglang)。
有关详情，请参阅 [/providers/sglang](/zh-CN/providers/sglang)。
### 本地代理（LM Studio、vLLM、LiteLLM 等）
@ -662,7 +659,7 @@ export SGLANG_API_KEY="sglang-local"
<AccordionGroup>
<Accordion title="默认可选字段">
对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 是可选的。省略时，OpenClaw 默认使用：
对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。省略时，OpenClaw 默认使用：
- `reasoning: false`
- `input: ["text"]`
@ -670,18 +667,18 @@ export SGLANG_API_KEY="sglang-local"
- `contextWindow: 200000`
- `maxTokens: 8192`
建议：设置与你的代理/模型限制匹配的显式值。
推荐：设置与你的代理/模型限制匹配的显式值。
</Accordion>
<Accordion title="代理路由整形规则">
- 对于非原生端点（任何非空且主机不是 `api.openai.com` 的 `baseUrl`）上的 `api: "openai-completions"`，OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持的 `developer` 角色而返回 400 错误。
- 代理风格的 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求整形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有提示缓存提示，没有 OpenAI 推理兼容载荷整形，也没有隐藏的 OpenClaw 归因标头。
- 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求正文中。
- 对于 vLLM 聊天模板控制，设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话思考级别关闭时，内置 vLLM 插件会为 `vllm/nemotron-3-*` 自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
- 对于较慢的本地模型或远程 LAN/tailnet 主机，设置 `models.providers.<id>.timeoutSeconds`。这会延长提供商模型 HTTP 请求处理，包括连接、标头、正文流式传输以及总受保护 fetch 中止时间，而不会增加整个 agent 运行时超时。
- 对于非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl`，且其主机不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持的 `developer` 角色而返回 400 错误。
- 代理风格的兼容 OpenAI 路由也会跳过仅限原生 OpenAI 的请求整形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有提示缓存提示，没有 OpenAI reasoning 兼容负载整形，也没有隐藏的 OpenClaw 归因标头。
- 对于需要供应商特定字段的兼容 OpenAI 的 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以便把额外 JSON 合并到出站请求体中。
- 对于 vLLM 聊天模板控制，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话 thinking 级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
- 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers.<id>.timeoutSeconds`。这会扩展提供商模型 HTTP 请求处理，包括连接、标头、正文流式传输以及总的受保护 fetch 中止时间，而不会增加整个 Agent 运行时超时。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。
- 为了安全，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
- 对于非直连端点（除规范 `anthropic` 之外的任何提供商，或主机不是公共 `api.anthropic.com` 端点的自定义 `models.providers.anthropic.baseUrl`）上的 `api: "anthropic-messages"`，OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，因此自定义 Anthropic 兼容代理不会拒绝不支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 `models.providers.<id>.headers["anthropic-beta"]`。
- 对于非直连端点上的 `api: "anthropic-messages"`（除规范 `anthropic` 之外的任何提供商，或主机不是公共 `api.anthropic.com` 端点的自定义 `models.providers.anthropic.baseUrl`），OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，因此自定义兼容 Anthropic 的代理不会因不支持的 beta 标志而拒绝请求。如果你的代理需要特定 beta 功能，请显式设置 `models.providers.<id>.headers["anthropic-beta"]`。
</Accordion>
</AccordionGroup>
@ -694,11 +691,11 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
另见：[配置](/zh-CN/gateway/configuration)，了解完整配置示例。
另请参阅：[配置](/zh-CN/gateway/configuration)，了解完整配置示例。
## 相关
## 相关内容
- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键
- [模型故障切换](/zh-CN/concepts/model-failover) — 回退链和重试行为
- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链和重试行为
- [Models](/zh-CN/concepts/models) — 模型配置和别名
- [提供商](/zh-CN/providers) — 各提供商设置指南

370
docs/zh-CN/gateway/protocol.md
View File

@ -2,29 +2,29 @@
read_when:
- 实现或更新 Gateway 网关 WS 客户端
- 调试协议不匹配或连接失败
- 正在重新生成协议模式/模型
- 正在重新生成协议架构/模型
summary: Gateway 网关 WebSocket 协议：握手、帧、版本控制
title: Gateway 网关协议
x-i18n:
generated_at: "2026-04-28T20:08:34Z"
generated_at: "2026-04-29T04:06:17Z"
model: gpt-5.5
provider: openai
source_hash: 95845fc2aa56b0a53cf8c62c517b70d2624b15e707d84503c791af572360aff2
source_hash: c2923919857e430b2db1d9c731025dc18499e5dbe01f248c0f873bd30041cf0e
source_path: gateway/protocol.md
workflow: 16
---
Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输协议**。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明它们的**角色** + **作用域**。
Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输协议**。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明它们的**角色** + **范围**。
## 传输协议
- WebSocket，使用带 JSON 载荷的文本帧。
- WebSocket，带有 JSON 载荷的文本帧。
- 第一帧**必须**是 `connect` 请求。
- 连接前帧大小上限为 64 KiB。握手成功后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断后，超大入站帧和缓慢出站缓冲区会在 Gateway 网关关闭或丢弃受影响帧之前发出 `payload.large` 事件。这些事件会保留大小、限制、表面和安全原因码。它们不会保留消息正文、附件内容、原始帧正文、令牌、Cookie 或机密值。
- 连接前帧上限为 64 KiB。握手成功后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断后，超大的入站帧和缓慢的出站缓冲区会在 Gateway 网关关闭或丢弃受影响帧之前发出 `payload.large` 事件。这些事件会保留大小、限制、表面和安全原因代码。它们不会保留消息正文、附件内容、原始帧正文、令牌、Cookie 或机密值。
## 握手（connect）
Gateway 网关 → 客户端（连接前质询）：
Gateway 网关 → 客户端（连接前挑战）：
```json
{
@ -95,7 +95,7 @@ Gateway 网关 → 客户端：
}
```
`server`、`features`、`snapshot` 和 `policy` 都是 schema（`src/gateway/protocol/schema/frames.ts`）要求的字段。`auth` 也是必需字段，并报告协商后的角色/作用域。`canvasHostUrl` 是可选字段。
`server`、`features`、`snapshot` 和 `policy` 都是 schema（`src/gateway/protocol/schema/frames.ts`）要求的字段。`auth` 也是必需的，并报告协商后的角色/范围。`canvasHostUrl` 是可选的。
未签发设备令牌时，`hello-ok.auth` 会报告协商后的权限，不包含令牌字段：
@ -108,7 +108,7 @@ Gateway 网关 → 客户端：
}
```
受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在使用共享 Gateway 网关令牌/密码进行身份验证时，可以在直接 local loopback 连接上省略 `device`。此路径保留给内部控制平面 RPC，可避免过期的 CLI/设备配对基线阻塞本地后端工作，例如子智能体会话更新。远程客户端、浏览器源客户端、节点客户端，以及显式设备令牌/设备身份客户端仍使用正常的配对和作用域升级检查。
受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在使用共享 Gateway 网关令牌/密码进行身份验证时，可以在直接 loopback 连接上省略 `device`。此路径保留给内部控制平面 RPC，并避免过时的 CLI/设备配对基线阻塞本地后端工作，例如子智能体会话更新。远程客户端、浏览器来源客户端、节点客户端，以及显式设备令牌/设备身份客户端仍使用正常的配对和范围升级检查。
签发设备令牌时，`hello-ok` 还会包含：
@ -122,7 +122,7 @@ Gateway 网关 → 客户端：
}
```
在受信任的引导交接期间，`hello-ok.auth` 也可能在 `deviceTokens` 中包含其他有边界的角色条目：
在受信任的 bootstrap 移交流程中，`hello-ok.auth` 也可能在 `deviceTokens` 中包含其他有界角色条目：
```json
{
@ -141,7 +141,7 @@ Gateway 网关 → 客户端：
}
```
对于内置节点/operator 引导流程，主节点令牌保持 `scopes: []`，任何交接出的 operator 令牌都保持限定在引导 operator 允许列表（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）内。引导作用域检查保持角色前缀规则：operator 条目只满足 operator 请求，非 operator 角色仍需要其自身角色前缀下的作用域。
对于内置的节点/operator bootstrap 流程，主节点令牌保持 `scopes: []`，任何移交的 operator 令牌都保持限制在 bootstrap operator 允许列表（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）内。Bootstrap 范围检查保持角色前缀：operator 条目只能满足 operator 请求，非 operator 角色仍需要其自身角色前缀下的范围。
### 节点示例
@ -178,7 +178,7 @@ Gateway 网关 → 客户端：
}
```
## 分帧
## 帧格式
- **请求**：`{type:"req", id, method, params}`
- **响应**：`{type:"res", id, ok, payload|error}`
@ -186,16 +186,16 @@ Gateway 网关 → 客户端：
有副作用的方法需要**幂等键**（参见 schema）。
## 角色 + 作用域
## 角色 + 范围
### 角色
- `operator` = 控制平面客户端（CLI/UI/自动化）。
- `node` = 能力宿主（camera/screen/canvas/system.run）。
### 作用域（operator）
### 范围（operator）
常见作用域：
常见范围：
- `operator.read`
- `operator.write`
@ -206,11 +206,11 @@ Gateway 网关 → 客户端：
带有 `includeSecrets: true` 的 `talk.config` 需要 `operator.talk.secrets`（或 `operator.admin`）。
插件注册的 Gateway 网关 RPC 方法可以请求自己的 operator 作用域，但保留的核心 admin 前缀（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终解析为 `operator.admin`。
插件注册的 Gateway 网关 RPC 方法可以请求自己的 operator 范围，但保留的核心 admin 前缀（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终解析为 `operator.admin`。
方法作用域只是第一道门槛。某些通过 `chat.send` 到达的斜杠命令会在此之上应用更严格的命令级检查。例如，持久化的 `/config set` 和 `/config unset` 写入需要 `operator.admin`。
方法范围只是第一道门。一些通过 `chat.send` 触达的斜杠命令还会在其上应用更严格的命令级检查。例如，持久化的 `/config set` 和 `/config unset` 写入需要 `operator.admin`。
`node.pair.approve` 也会在基础方法作用域之上进行额外的批准时作用域检查：
`node.pair.approve` 在基础方法范围之上还有额外的批准时范围检查：
- 无命令请求：`operator.pairing`
- 带非 exec 节点命令的请求：`operator.pairing` + `operator.write`
@ -218,23 +218,23 @@ Gateway 网关 → 客户端：
### 能力/命令/权限（节点）
节点在连接时声明能力声明：
节点在连接时声明能力主张：
- `caps`：高层能力类别。
- `commands`：用于调用的命令允许列表。
- `caps`：高级能力类别。
- `commands`：用于 invoke 的命令允许列表。
- `permissions`：细粒度开关（例如 `screen.record`、`camera.capture`）。
Gateway 网关将这些视为**声明**，并执行服务端允许列表。
Gateway 网关将这些视为**主张**，并强制执行服务端允许列表。
## 在线状态
- `system-presence` 返回按设备身份键控的条目。
- 在线状态条目包括 `deviceId`、`roles` 和 `scopes`，因此 UI 即使在设备同时以 **operator** 和 **node** 身份连接时，也能为每个设备显示单行。
- `node.list` 包含可选的 `lastSeenAtMs` 和 `lastSeenReason` 字段。已连接节点会将其当前连接时间报告为 `lastSeenAtMs`，原因是 `connect`；当受信任节点事件更新其配对元数据时，已配对节点也可以报告持久后台在线状态。
- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，因此即使设备同时以 **operator** 和 **node** 身份连接，UI 也能为每个设备显示单行。
- `node.list` 包含可选的 `lastSeenAtMs` 和 `lastSeenReason` 字段。已连接的节点会将其当前连接时间报告为 `lastSeenAtMs`，原因为 `connect`；当受信任的节点事件更新配对元数据时，已配对的节点也可以报告持久的后台在线状态。
### 节点后台存活事件
节点可以调用带有 `event: "node.presence.alive"` 的 `node.event`，以记录某个已配对节点在后台唤醒期间处于存活状态，而不将其标记为已连接。
节点可以调用带有 `event: "node.presence.alive"` 的 `node.event`，以记录已配对节点在后台唤醒期间存活，而不将其标记为已连接。
```json
{
@ -243,9 +243,9 @@ Gateway 网关将这些视为**声明**，并执行服务端允许列表。
}
```
`trigger` 是封闭枚举：`background`、`silent_push`、`bg_app_refresh`、`significant_location`、`manual` 或 `connect`。未知触发器字符串会在持久化前由 Gateway 网关规范化为 `background`。该事件仅对已认证的节点设备会话持久化；无设备或未配对会话返回 `handled: false`。
`trigger` 是封闭枚举：`background`、`silent_push`、`bg_app_refresh`、`significant_location`、`manual` 或 `connect`。未知 trigger 字符串会在持久化前由 Gateway 网关规范化为 `background`。该事件仅对已认证的节点设备会话持久化；无设备或未配对会话返回 `handled: false`。
成功的 Gateway 网关返回结构化结果：
成功的 Gateway 网关会返回结构化结果：
```json
{
@ -256,97 +256,97 @@ Gateway 网关将这些视为**声明**，并执行服务端允许列表。
}
```
较旧的 Gateway 网关对 `node.event` 仍可能返回 `{ "ok": true }`；客户端应将其视为已确认的 RPC，而不是持久在线状态持久化。
较旧的 Gateway 网关仍可能为 `node.event` 返回 `{ "ok": true }`；客户端应将其视为已确认的 RPC，而不是持久在线状态已保存。
## 广播事件作用域
## 广播事件范围限定
服务端推送的 WebSocket 广播事件受作用域限制，因此配对作用域会话或仅节点会话不会被动接收会话内容。
服务端推送的 WebSocket 广播事件会按范围设门，避免配对范围或仅节点会话被动接收会话内容。
- **聊天、智能体和工具结果帧**（包括流式 `agent` 事件和工具调用结果）至少需要 `operator.read`。没有 `operator.read` 的会话会完全跳过这些帧。
- **插件定义的 `plugin.*` 广播**会根据插件注册方式限制为 `operator.write` 或 `operator.admin`。
- **Status 和传输事件**（`heartbeat`、`presence`、`tick`、连接/断开生命周期等）保持不受限制，因此每个已认证会话都能观察传输健康状态。
- **未知广播事件族**默认受作用域限制（失败关闭），除非已注册处理程序显式放宽限制。
- **插件定义的 `plugin.*` 广播**会根据插件注册方式设门为 `operator.write` 或 `operator.admin`。
- **Status 和传输事件**（`heartbeat`、`presence`、`tick`、连接/断开生命周期等）保持不受限制，以便每个已认证会话都能观察传输健康状况。
- **未知广播事件族**默认按范围设门（失败关闭），除非已注册处理程序显式放宽限制。
每个客户端连接都会保留自己的逐客户端序列号，因此即使不同客户端看到的事件流子集因作用域过滤而不同，广播也能在该 socket 上保持单调顺序。
每个客户端连接都会保留自己的按客户端序列号，因此即使不同客户端看到不同的范围过滤事件流子集，广播也会在该 socket 上保持单调顺序。
## 常见 RPC 方法族
公共 WS 表面比上面的握手/认证示例更广。这不是生成的转储 — `hello-ok.features.methods` 是从 `src/gateway/server-methods-list.ts` 加上已加载插件/渠道方法导出构建的保守设备发现列表。请将其视为功能设备发现，而不是 `src/gateway/server-methods/*.ts` 的完整枚举。
公共 WS 表面比上面的握手/身份验证示例更广。它不是生成的完整转储，`hello-ok.features.methods` 是一个保守的设备发现列表，由 `src/gateway/server-methods-list.ts` 加上已加载的插件/渠道方法导出构建。应将其视为功能设备发现，而不是 `src/gateway/server-methods/*.ts` 的完整枚举。
<AccordionGroup>
<Accordion title="System and identity">
<Accordion title="系统和身份">
- `health` 返回缓存的或新探测的 Gateway 网关健康快照。
- `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它保留事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称和会话 ID 等运行元数据。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie 或机密值。需要 operator read 作用域。
- `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅包含给具有 admin 作用域的 operator 客户端。
- `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它保留操作元数据，例如事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称和会话 ID。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie 或机密值。需要 operator read 范围。
- `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅包含给具有 admin 范围的 operator 客户端。
- `gateway.identity.get` 返回 relay 和配对流程使用的 Gateway 网关设备身份。
- `system-presence` 返回已连接 operator/node 设备的当前在线状态快照。
- `system-event` 追加一个系统事件，并可以更新/广播在线状态上下文。
- `last-heartbeat` 返回最新持久化的心跳事件。
- `set-heartbeats` 切换 Gateway 网关上的心跳处理。
- `system-presence` 返回已连接 operator/节点设备的当前在线状态快照。
- `system-event` 追加系统事件，并可更新/广播在线状态上下文。
- `last-heartbeat` 返回最近持久化的 heartbeat 事件。
- `set-heartbeats` 切换 Gateway 网关上的 heartbeat 处理。
</Accordion>
<Accordion title="Models and usage">
- `models.list` 返回运行时允许的模型目录。传入 `{ "view": "configured" }` 获取适合选择器大小的已配置模型（先是 `agents.defaults.models`，然后是 `models.providers.*.models`），或传入 `{ "view": "all" }` 获取完整目录。
<Accordion title="Models 和使用量">
- `models.list` 返回运行时允许的模型目录。传入 `{ "view": "configured" }` 可获取适合选择器大小的已配置模型（先是 `agents.defaults.models`，然后是 `models.providers.*.models`），或传入 `{ "view": "all" }` 获取完整目录。
- `usage.status` 返回提供商使用窗口/剩余额度摘要。
- `usage.cost` 返回日期范围内的聚合成本使用摘要。
- `doctor.memory.status` 返回活动默认 Agent 工作区的向量内存/缓存嵌入就绪状态。仅当调用方明确想要实时嵌入提供商 ping 时，才传入 `{ "probe": true }` 或 `{ "deep": true }`。
- `sessions.usage` 返回每个会话的使用摘要。
- `sessions.usage.timeseries` 返回一个会话的时间序列使用情况。
- `usage.cost` 返回某个日期范围内的聚合成本使用摘要。
- `doctor.memory.status` 返回活动默认 Agent 工作区的向量记忆/缓存 embedding 就绪状态。仅当调用方明确需要实时 embedding 提供商 ping 时，才传入 `{ "probe": true }` 或 `{ "deep": true }`。
- `sessions.usage` 返回按会话统计的使用摘要。
- `sessions.usage.timeseries` 返回一个会话的时间序列使用量。
- `sessions.usage.logs` 返回一个会话的使用日志条目。
</Accordion>
<Accordion title="渠道和登录辅助方法">
- `channels.status` 返回内置 + 随附渠道/插件 Status 摘要。
<Accordion title="渠道和登录助手">
- `channels.status` 返回内置 + 捆绑渠道/插件 Status 摘要。
- `channels.logout` 会在渠道支持登出时登出指定渠道/账户。
- `web.login.start` 为当前支持 QR 的 Web 渠道提供商启动 QR/Web 登录流程。
- `web.login.wait` 等待该 QR/Web 登录流程完成，并在成功后启动该渠道。
- `web.login.start` 为当前支持二维码的 Web 渠道提供商启动二维码/Web 登录流程。
- `web.login.wait` 等待该二维码/Web 登录流程完成，并在成功后启动渠道。
- `push.test` 向已注册的 iOS 节点发送测试 APNs 推送。
- `voicewake.get` 返回已存储的唤醒词触发器。
- `voicewake.set` 更新唤醒词触发器并广播变更。
- `voicewake.set` 更新唤醒词触发器并广播更改。
</Accordion>
<Accordion title="消息和日志">
- `send` 是用于在聊天运行器之外按渠道/账户/线程目标直接发送的出站投递 RPC。
- `logs.tail` 返回已配置的 Gateway 网关文件日志尾部，并带有游标/限制和最大字节控制。
<Accordion title="消息与日志">
- `send` 是用于在聊天运行器之外按渠道/账户/线程目标发送的直接出站投递 RPC。
- `logs.tail` 返回已配置 Gateway 网关文件日志尾部，支持 cursor/limit 和最大字节数控制。
</Accordion>
<Accordion title="Talk 和 TTS">
- `talk.config` 返回有效的 Talk 配置载荷；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。
- `talk.mode` 设置/广播 WebChat/Control UI 客户端的当前 Talk 模式状态。
- `talk.speak` 通过活动的 Talk 语音提供商合成语音。
- `tts.status` 返回 TTS 启用状态、活动提供商、备用提供商和提供商配置状态。
- `talk.config` 返回生效的 Talk 配置负载；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。
- `talk.mode` 为 WebChat/Control UI 客户端设置/广播当前 Talk 模式状态。
- `talk.speak` 通过当前活动的 Talk 语音提供商合成语音。
- `tts.status` 返回 TTS 启用状态、活动提供商、回退提供商和提供商配置状态。
- `tts.providers` 返回可见的 TTS 提供商清单。
- `tts.enable` 和 `tts.disable` 切换 TTS 偏好状态。
- `tts.setProvider` 更新首选 TTS 提供商。
- `tts.convert` 运行一次性文本转语音转换。
- `tts.convert` 执行一次性文本转语音转换。
</Accordion>
<Accordion title="密钥、配置、更新和向导">
- `secrets.reload` 重新解析活动的 SecretRefs，并且仅在完全成功时替换运行时密钥状态。
- `secrets.resolve` 为特定命令/目标集合解析面向命令目标的密钥分配。
- `secrets.reload` 重新解析活动 SecretRefs，并且仅在完全成功时替换运行时密钥状态。
- `secrets.resolve` 为特定命令/目标集合解析命令目标密钥赋值。
- `config.get` 返回当前配置快照和哈希。
- `config.set` 写入经过验证的配置载荷。
- `config.set` 写入已验证的配置负载。
- `config.patch` 合并部分配置更新。
- `config.apply` 验证并替换完整配置载荷。
- `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置架构载荷：架构、`uiHints`、版本和生成元数据，包括运行时能够加载时的插件 + 渠道架构元数据。该架构包含字段 `title` / `description` 元数据，这些元数据派生自 UI 使用的同一组标签和帮助文本；当存在匹配的字段文档时，也包括嵌套对象、通配符、数组项以及 `anyOf` / `oneOf` / `allOf` 组合分支。
- `config.schema.lookup` 为一个配置路径返回路径限定的查找载荷：规范化路径、浅层架构节点、匹配的提示 + `hintPath`，以及用于 UI/CLI 下钻的直接子项摘要。查找架构节点会保留面向用户的文档和常见验证字段（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数字/字符串/数组/对象边界，以及 `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` 等标志）。子项摘要公开 `key`、规范化的 `path`、`type`、`required`、`hasChildren`，以及匹配的 `hint` / `hintPath`。
- `config.apply` 验证并替换完整配置负载。
- `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置 schema 负载：schema、`uiHints`、版本和生成元数据，并在运行时可加载时包含插件 + 渠道 schema 元数据。该 schema 包含字段 `title` / `description` 元数据，这些元数据派生自 UI 使用的相同标签和帮助文本；当存在匹配的字段文档时，也包括嵌套对象、通配符、数组项以及 `anyOf` / `oneOf` / `allOf` 组合分支。
- `config.schema.lookup` 返回一个配置路径的路径范围查找负载：规范化路径、浅层 schema 节点、匹配的提示 + `hintPath`，以及用于 UI/CLI 下钻的直接子项摘要。查找 schema 节点会保留面向用户的文档和常见验证字段（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数值/字符串/数组/对象边界，以及 `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` 等标志）。子项摘要会公开 `key`、规范化 `path`、`type`、`required`、`hasChildren`，以及匹配的 `hint` / `hintPath`。
- `update.run` 运行 Gateway 网关更新流程，并且仅在更新本身成功时安排重启。
- `update.status` 返回最新缓存的更新重启哨兵，包括可用时重启后的运行版本。
- `wizard.start`、`wizard.next`、`wizard.status` 和 `wizard.cancel` 通过 WS RPC 暴露新手引导向导。
</Accordion>
<Accordion title="智能体和工作区辅助方法">
- `agents.list` 返回已配置的智能体条目。
- `agents.create`、`agents.update` 和 `agents.delete` 管理智能体记录和工作区接线。
<Accordion title="智能体和工作区助手">
- `agents.list` 返回已配置的智能体条目，包括生效模型和运行时元数据。
- `agents.create`、`agents.update` 和 `agents.delete` 管理智能体记录和工作区连接。
- `agents.files.list`、`agents.files.get` 和 `agents.files.set` 管理为智能体暴露的引导工作区文件。
- `agent.identity.get` 返回智能体或会话的有效助手身份。
- `agent.wait` 等待运行完成，并在可用时返回终止快照。
- `agent.identity.get` 返回智能体或会话的生效助手身份。
- `agent.wait` 等待一次运行完成，并在可用时返回终态快照。
</Accordion>
@ -363,42 +363,42 @@ Gateway 网关将这些视为**声明**，并执行服务端允许列表。
- `sessions.patch` 更新会话元数据/覆盖项。
- `sessions.reset`、`sessions.delete` 和 `sessions.compact` 执行会话维护。
- `sessions.get` 返回完整存储的会话行。
- 聊天执行仍使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。`chat.history` 会针对 UI 客户端进行显示规范化：从可见文本中剥离内联指令标签，剥离纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 和被截断的工具调用块）以及泄漏的 ASCII/全角模型控制令牌，省略纯静默令牌助手行，例如精确的 `NO_REPLY` / `no_reply`，并且可用占位符替换过大的行。
- 聊天执行仍使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。`chat.history` 会针对 UI 客户端进行显示规范化：从可见文本中剥离内联指令标签，剥离纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 和截断的工具调用块）以及泄漏的 ASCII/全角模型控制令牌，省略精确为 `NO_REPLY` / `no_reply` 等纯静默令牌助手行，并且超大行可替换为占位符。
</Accordion>
<Accordion title="设备配对和设备令牌">
- `device.pair.list` 返回待处理和已批准的配对设备。
- `device.pair.approve`、`device.pair.reject` 和 `device.pair.remove` 管理设备配对记录。
- `device.token.rotate` 在已批准的角色和调用方作用域边界内轮换配对设备令牌。
- `device.token.revoke` 在已批准的角色和调用方作用域边界内撤销配对设备令牌。
- `device.token.rotate` 在已批准的角色和调用方范围边界内轮换配对设备令牌。
- `device.token.revoke` 在已批准的角色和调用方范围边界内撤销配对设备令牌。
</Accordion>
<Accordion title="节点配对、调用和待处理工作">
- `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.remove` 和 `node.pair.verify` 涵盖节点配对和引导验证。
- `node.list` 和 `node.describe` 返回已知/已连接节点状态。
- `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.remove` 和 `node.pair.verify` 覆盖节点配对和引导验证。
- `node.list` 和 `node.describe` 返回已知/已连接的节点状态。
- `node.rename` 更新已配对节点标签。
- `node.invoke` 将命令转发到已连接节点。
- `node.invoke.result` 返回调用请求的结果。
- `node.event` 将节点发起的事件带回 Gateway 网关。
- `node.canvas.capability.refresh` 刷新限定作用域的画布能力令牌。
- `node.canvas.capability.refresh` 刷新限定范围的画布能力令牌。
- `node.pending.pull` 和 `node.pending.ack` 是已连接节点队列 API。
- `node.pending.enqueue` 和 `node.pending.drain` 管理离线/断开连接节点的持久待处理工作。
</Accordion>
<Accordion title="审批系列">
- `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 涵盖一次性 exec 审批请求以及待处理审批查找/重放。
- `exec.approval.waitDecision` 等待一个待处理的 exec 审批，并返回最终决定（超时则返回 `null`）。
- `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 覆盖一次性 exec 审批请求以及待处理审批查找/重放。
- `exec.approval.waitDecision` 等待一个待处理 exec 审批并返回最终决策（超时时返回 `null`）。
- `exec.approvals.get` 和 `exec.approvals.set` 管理 Gateway 网关 exec 审批策略快照。
- `exec.approvals.node.get` 和 `exec.approvals.node.set` 通过节点中继命令管理节点本地 exec 审批策略。
- `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision` 和 `plugin.approval.resolve` 涵盖插件定义的审批流程。
- `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision` 和 `plugin.approval.resolve` 覆盖插件定义的审批流程。
</Accordion>
<Accordion title="自动化、Skills 和工具">
- 自动化：`wake` 安排立即或下一次心跳时注入唤醒文本；`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` 管理计划工作。
- 自动化：`wake` 调度立即或下一次心跳唤醒文本注入；`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` 管理计划工作。
- Skills 和工具：`commands.list`、`skills.*`、`tools.catalog`、`tools.effective`。
</Accordion>
@ -406,11 +406,10 @@ Gateway 网关将这些视为**声明**，并执行服务端允许列表。
### 常见事件系列
- `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅转录的聊天
事件。
- `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅转录聊天事件。
- `session.message` 和 `session.tool`：已订阅会话的转录/事件流更新。
- `sessions.changed`：会话索引或元数据已更改。
- `presence`：系统存在状态快照更新。
- `presence`：系统在线状态快照更新。
- `tick`：周期性 keepalive / 存活事件。
- `health`：Gateway 网关健康快照更新。
- `heartbeat`：心跳事件流更新。
@ -420,170 +419,155 @@ Gateway 网关将这些视为**声明**，并执行服务端允许列表。
- `node.invoke.request`：节点调用请求广播。
- `device.pair.requested` / `device.pair.resolved`：配对设备生命周期。
- `voicewake.changed`：唤醒词触发器配置已更改。
- `exec.approval.requested` / `exec.approval.resolved`：exec 审批
生命周期。
- `plugin.approval.requested` / `plugin.approval.resolved`：插件审批
生命周期。
- `exec.approval.requested` / `exec.approval.resolved`：exec 审批生命周期。
- `plugin.approval.requested` / `plugin.approval.resolved`：插件审批生命周期。
### 节点辅助方法
### 节点助手方法
- 节点可以调用 `skills.bins` 以获取当前技能可执行文件列表，
用于自动允许检查。
- 节点可以调用 `skills.bins` 来获取当前技能可执行文件列表，用于自动允许检查。
### 操作员辅助方法
### 操作员助手方法
- 操作员可以调用 `commands.list`（`operator.read`）以获取智能体的运行时
命令清单。
- `agentId` 是可选的；省略它可读取默认智能体工作区。
- 操作员可以调用 `commands.list`（`operator.read`）来获取智能体的运行时命令清单。
- `agentId` 是可选的；省略它以读取默认智能体工作区。
- `scope` 控制主 `name` 面向哪个表面：
- `text` 返回不带前导 `/` 的主文本命令令牌
- `native` 和默认的 `both` 路径会在可用时返回提供商感知的原生命名
- `native` 和默认的 `both` 路径会在可用时返回感知提供商的原生命名
- `textAliases` 携带精确的斜杠别名，例如 `/model` 和 `/m`。
- `nativeName` 在存在时携带提供商感知的原生命令名称。
- `provider` 是可选的，并且仅影响原生命名以及原生插件命令可用性。
- `includeArgs=false` 从响应中省略序列化的参数元数据。
- 操作员可以调用 `tools.catalog`（`operator.read`）以获取智能体的运行时工具目录。响应包括分组工具和来源元数据：
- `nativeName` 在存在时携带感知提供商的原生命令名称。
- `provider` 是可选的，并且只影响原生命名以及原生插件命令可用性。
- `includeArgs=false` 会从响应中省略序列化的参数元数据。
- 操作员可以调用 `tools.catalog`（`operator.read`）来获取智能体的运行时工具目录。响应包含分组工具和来源元数据：
- `source`：`core` 或 `plugin`
- `pluginId`：当 `source="plugin"` 时的插件所有者
- `optional`：插件工具是否为可选
- 操作员可以调用 `tools.effective`（`operator.read`）以获取会话的运行时有效工具
清单。
- 操作员可以调用 `tools.effective`（`operator.read`）来获取会话的运行时生效工具清单。
- `sessionKey` 是必需的。
- Gateway 网关会从服务器端会话派生受信任的运行时上下文，而不是接受
调用方提供的认证或投递上下文。
- 响应限定于会话作用域，并反映活动对话当前可以使用的内容，
包括核心、插件和渠道工具。
- 操作员可以调用 `skills.status`（`operator.read`）以获取智能体的可见
技能清单。
- `agentId` 是可选的；省略它可读取默认智能体工作区。
- 响应包括资格、缺失要求、配置检查，以及
不暴露原始密钥值的已净化安装选项。
- 操作员可以调用 `skills.search` 和 `skills.detail`（`operator.read`）以获取
ClawHub 发现元数据。
- 操作员可以用两种模式调用 `skills.install`（`operator.admin`）：
- ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 将一个
技能文件夹安装到默认智能体工作区的 `skills/` 目录。
- Gateway 网关安装器模式：`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
在 Gateway 网关主机上运行声明的 `metadata.openclaw.install` 动作。
- 操作员可以用两种模式调用 `skills.update`（`operator.admin`）：
- ClawHub 模式会更新默认智能体工作区中一个已跟踪的 slug，或所有已跟踪的 ClawHub 安装。
- 配置模式会修补 `skills.entries.<skillKey>` 值，例如 `enabled`、
`apiKey` 和 `env`。
- Gateway 网关从服务端会话派生可信运行时上下文，而不是接受调用方提供的认证或投递上下文。
- 响应限定于会话范围，并反映活动对话当前可使用的内容，包括核心、插件和渠道工具。
- 操作员可以调用 `skills.status`（`operator.read`）来获取智能体的可见技能清单。
- `agentId` 是可选的；省略它以读取默认智能体工作区。
- 响应包含资格、缺失要求、配置检查，以及经过清理且不会暴露原始密钥值的安装选项。
- 操作员可以调用 `skills.search` 和 `skills.detail`（`operator.read`）获取 ClawHub 发现元数据。
- 操作员可以调用 `skills.install`（`operator.admin`），它有两种模式：
- ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 将技能文件夹安装到默认智能体工作区的 `skills/` 目录中。
- Gateway 网关安装器模式：`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` 在 Gateway 网关主机上运行已声明的 `metadata.openclaw.install` 操作。
- 操作员可以调用 `skills.update`（`operator.admin`），它有两种模式：
- ClawHub 模式会更新默认智能体工作区中的一个已跟踪 slug 或所有已跟踪的 ClawHub 安装。
- 配置模式会修补 `skills.entries.<skillKey>` 值，例如 `enabled`、`apiKey` 和 `env`。
### `models.list` 视图
`models.list` 接受可选的 `view` 参数：
- 省略或 `"default"`：当前运行时行为。如果已配置 `agents.defaults.models`，响应为允许的目录；否则响应为完整的 Gateway 网关目录。
- `"configured"`：适合选择器大小的行为。如果已配置 `agents.defaults.models`，它仍然优先。否则响应使用显式的 `models.providers.*.models` 条目，仅在不存在已配置模型行时才回退到完整目录。
- `"all"`：完整的 Gateway 网关目录，绕过 `agents.defaults.models`。将其用于诊断和发现 UI，而不是常规模型选择器。
- 省略或 `"default"`：当前运行时行为。如果配置了 `agents.defaults.models`，响应为允许的目录；否则响应为完整 Gateway 网关目录。
- `"configured"`：适合选择器大小的行为。如果配置了 `agents.defaults.models`，它仍然优先。否则响应使用显式的 `models.providers.*.models` 条目，并且仅在不存在已配置模型行时回退到完整目录。
- `"all"`：完整 Gateway 网关目录，绕过 `agents.defaults.models`。将它用于诊断和设备发现 UI，而不是常规模型选择器。
## Exec 审批
## Exec 批准
- 当 exec 请求需要审批时，Gateway 网关会广播 `exec.approval.requested`。
- 操作员客户端通过调用 `exec.approval.resolve` 来处理（需要 `operator.approvals` 作用域）。
- 当 exec 请求需要批准时，Gateway 网关会广播 `exec.approval.requested`。
- 操作员客户端通过调用 `exec.approval.resolve` 来解决（需要 `operator.approvals` 作用域）。
- 对于 `host=node`，`exec.approval.request` 必须包含 `systemRunPlan`（规范的 `argv`/`cwd`/`rawCommand`/会话元数据）。缺少 `systemRunPlan` 的请求会被拒绝。
- 审批后，转发的 `node.invoke system.run` 调用会复用该规范
`systemRunPlan`，作为权威的命令/cwd/会话上下文。
- 如果调用方在准备阶段和最终已审批的 `system.run` 转发之间修改了 `command`、`rawCommand`、`cwd`、`agentId` 或
`sessionKey`，Gateway 网关会拒绝本次运行，而不是信任被修改的载荷。
- 批准后，转发的 `node.invoke system.run` 调用会复用该规范
`systemRunPlan` 作为权威的命令/cwd/会话上下文。
- 如果调用方在准备与最终获批的 `system.run` 转发之间修改了 `command`、`rawCommand`、`cwd`、`agentId` 或
`sessionKey`，Gateway 网关会拒绝运行，而不是信任被修改的载荷。
## 智能体投递回退
## 智能体交付回退
- `agent` 请求可以包含 `deliver=true` 来请求出站投递。
- `bestEffortDeliver=false` 保持严格行为：无法解析或仅限内部的投递目标会返回 `INVALID_REQUEST`。
- `bestEffortDeliver=true` 允许在无法解析外部可投递路由时回退到仅会话执行（例如内部/webchat 会话，或存在歧义的多渠道配置）。
- `agent` 请求可以包含 `deliver=true` 来请求出站交付。
- `bestEffortDeliver=false` 保持严格行为：无法解析或仅限内部的交付目标会返回 `INVALID_REQUEST`。
- `bestEffortDeliver=true` 允许在无法解析外部可交付路由时回退到仅会话执行（例如内部/webchat 会话或有歧义的多渠道配置）。
## 版本控制
- `PROTOCOL_VERSION` 位于 `src/gateway/protocol/schema/protocol-schemas.ts`。
- 客户端发送 `minProtocol` + `maxProtocol`；服务器会拒绝不匹配的情况。
- schema + 模型从 TypeBox 定义生成：
- 客户端发送 `minProtocol` + `maxProtocol`；服务器会拒绝不匹配项。
- Schema + 模型由 TypeBox 定义生成：
- `pnpm protocol:gen`
- `pnpm protocol:gen:swift`
- `pnpm protocol:check`
### 客户端常量
`src/gateway/client.ts` 中的参考客户端使用这些默认值。值在协议 v3 中保持稳定，并且是第三方客户端的预期基线。
`src/gateway/client.ts` 中的参考客户端使用这些默认值。这些值在协议 v3 中保持稳定，并且是第三方客户端的预期基线。
| 常量 | 默认值 | 来源 |
| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
| 请求超时（每个 RPC） | `30_000` ms | `src/gateway/client.ts`（`requestTimeoutMs`） |
| 预认证 / 连接挑战超时 | `15_000` ms | `src/gateway/handshake-timeouts.ts`（钳制 `250`–`15_000`） |
| 预认证 / connect-challenge 超时 | `15_000` ms | `src/gateway/handshake-timeouts.ts`（限制为 `250`-`15_000`） |
| 初始重连退避 | `1_000` ms | `src/gateway/client.ts`（`backoffMs`） |
| 最大重连退避 | `30_000` ms | `src/gateway/client.ts`（`scheduleReconnect`） |
| 设备令牌关闭后的快速重试钳制 | `250` ms | `src/gateway/client.ts` |
| `terminate()` 前的强制停止宽限 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
| device-token 关闭后的快速重试限制 | `250` ms | `src/gateway/client.ts` |
| `terminate()` 前的强制停止宽限期 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
| `stopAndWait()` 默认超时 | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
| 默认 tick 间隔（`hello-ok` 前） | `30_000` ms | `src/gateway/client.ts` |
| Tick 超时关闭 | 当静默超过 `tickIntervalMs * 2` 时使用代码 `4000` | `src/gateway/client.ts` |
| tick 超时关闭 | 静默超过 `tickIntervalMs * 2` 时使用代码 `4000` | `src/gateway/client.ts` |
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024`（25 MB） | `src/gateway/server-constants.ts` |
服务器会在 `hello-ok` 中公布有效的 `policy.tickIntervalMs`、`policy.maxPayload`
和 `policy.maxBufferedBytes`；客户端应遵循这些值，而不是握手前的默认值。
服务器会在 `hello-ok` 中通告有效的 `policy.tickIntervalMs`、`policy.maxPayload`
和 `policy.maxBufferedBytes`；客户端应遵循这些值，而不是握手前默认值。
## 认证
- 共享密钥 Gateway 网关认证使用 `connect.params.auth.token` 或
`connect.params.auth.password`，具体取决于配置的认证模式。
- 带身份的模式（例如 Tailscale Serve
（`gateway.auth.allowTailscale: true`）或非 loopback 的
`gateway.auth.mode: "trusted-proxy"`）会从请求头满足连接认证检查，而不是使用 `connect.params.auth.*`。
- 私有入口 `gateway.auth.mode: "none"` 会完全跳过共享密钥连接认证；不要在公共/不受信任入口上暴露该模式。
- 配对后，Gateway 网关会签发一个作用域限定为连接角色 + 作用域的**设备令牌**。它在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化以供将来连接使用。
- 客户端应在任何成功连接后持久化主要的 `hello-ok.auth.deviceToken`。
- 使用该**已存储**设备令牌重新连接时，还应复用该令牌已存储的已批准作用域集。这样会保留已授予的读取/探测/Status 访问权限，并避免将重连静默压缩到更窄的隐式仅管理员作用域。
`connect.params.auth.password`，具体取决于已配置的认证模式。
- 携带身份的模式（例如 Tailscale Serve
（`gateway.auth.allowTailscale: true`）或非环回
`gateway.auth.mode: "trusted-proxy"`）会通过请求标头而不是 `connect.params.auth.*` 满足连接认证检查。
- 私有入口 `gateway.auth.mode: "none"` 会完全跳过共享密钥连接认证；不要在公共/不受信任的入口上暴露该模式。
- 配对后，Gateway 网关会发放一个限定于连接角色 + 作用域的**设备令牌**。它在 `hello-ok.auth.deviceToken` 中返回，客户端应持久化它以供未来连接使用。
- 客户端应在任何成功连接后持久化主 `hello-ok.auth.deviceToken`。
- 使用该**已存储**设备令牌重新连接时，也应复用该令牌已存储的获批作用域集合。这会保留已授予的读取/探测/Status 访问权限，并避免将重连静默收缩为更窄的隐式仅管理员作用域。
- 客户端侧连接认证组装（`src/gateway/client.ts` 中的 `selectConnectAuth`）：
- `auth.password` 是正交的，设置时始终会被转发。
- `auth.token` 按优先级填充：先使用显式共享令牌，然后是显式 `deviceToken`，再然后是已存储的每设备令牌（按 `deviceId` + `role` 键控）。
- 只有当上述任何项都没有解析出 `auth.token` 时，才会发送 `auth.bootstrapToken`。共享令牌或任何已解析的设备令牌都会抑制它。
- 在一次性 `AUTH_TOKEN_MISMATCH` 重试中自动提升已存储设备令牌，仅限**受信任端点**：
loopback，或带有已固定 `tlsFingerprint` 的 `wss://`。没有固定的公共 `wss://`
不符合条件。
- 额外的 `hello-ok.auth.deviceTokens` 条目是 bootstrap 交接令牌。仅当连接在受信任传输（例如 `wss://` 或 loopback/local 配对）上使用 bootstrap 认证时才持久化它们。
- 如果客户端提供**显式** `deviceToken` 或显式 `scopes`，该调用方请求的作用域集仍为权威；仅当客户端复用已存储的每设备令牌时，才会复用缓存的作用域。
- `auth.password` 是正交的，并且设置后总会被转发。
- `auth.token` 按优先级填充：首先是显式共享令牌，然后是显式 `deviceToken`，再然后是已存储的按设备令牌（由 `deviceId` + `role` 作为键）。
- 仅当以上都未解析出 `auth.token` 时，才会发送 `auth.bootstrapToken`。共享令牌或任何已解析的设备令牌都会抑制它。
- 在一次性
`AUTH_TOKEN_MISMATCH` 重试中自动提升已存储设备令牌，仅限**受信任端点**：loopback，或带有固定 `tlsFingerprint` 的 `wss://`。未固定的公共 `wss://` 不符合条件。
- 额外的 `hello-ok.auth.deviceTokens` 条目是引导交接令牌。仅当连接在受信任传输（例如 `wss://` 或 loopback/local pairing）上使用了引导认证时，才持久化它们。
- 如果客户端提供**显式** `deviceToken` 或显式 `scopes`，该调用方请求的作用域集合仍然是权威的；仅当客户端复用已存储的按设备令牌时，才会复用缓存作用域。
- 设备令牌可以通过 `device.token.rotate` 和
`device.token.revoke` 轮换/撤销（需要 `operator.pairing` 作用域）。
- `device.token.rotate` 返回轮换元数据。它仅针对已经使用该设备令牌完成认证的同设备调用回显替换 bearer 令牌，因此仅令牌客户端可以在重连前持久化其替换令牌。共享/管理员轮换不会回显 bearer 令牌。
- 令牌签发、轮换和撤销始终受限于该设备配对条目中记录的已批准角色集；令牌变更无法扩展或指向配对审批从未授予的设备角色。
- 对于配对设备令牌会话，除非调用方还拥有 `operator.admin`，设备管理都是自作用域的：非管理员调用方只能移除/撤销/轮换其**自己的**设备条目。
- `device.token.rotate` 和 `device.token.revoke` 还会检查目标操作员令牌作用域集是否匹配调用方当前会话作用域。非管理员调用方无法轮换或撤销比其当前持有范围更宽的操作员令牌。
- 认证失败包含 `error.details.code` 以及恢复提示：
- `device.token.rotate` 返回轮换元数据。它仅对已使用该设备令牌认证的同设备调用回显替代 bearer 令牌，以便仅令牌客户端可以在重连前持久化替代令牌。共享/管理员轮换不会回显 bearer 令牌。
- 令牌发放、轮换和撤销会被限制在该设备配对条目中记录的获批角色集合内；令牌变更不能扩展到或指向配对批准从未授予的设备角色。
- 对于已配对设备令牌会话，除非调用方还拥有 `operator.admin`，否则设备管理是自作用域的：非管理员调用方只能移除/撤销/轮换自己的设备条目。
- `device.token.rotate` 和 `device.token.revoke` 还会检查目标操作员令牌作用域集合是否匹配调用方当前会话作用域。非管理员调用方不能轮换或撤销比自己已持有权限更宽的操作员令牌。
- 认证失败会包含 `error.details.code` 以及恢复提示：
- `error.details.canRetryWithDeviceToken`（布尔值）
- `error.details.recommendedNextStep`（`retry_with_device_token`、`update_auth_configuration`、`update_auth_credentials`、`wait_then_retry`、`review_auth_configuration`）
- 客户端对 `AUTH_TOKEN_MISMATCH` 的行为：
- 受信任客户端可以尝试使用缓存的每设备令牌进行一次有界重试。
- 如果该重试失败，客户端应停止自动重连循环，并显示需要操作员处理的指导。
- `AUTH_TOKEN_MISMATCH` 的客户端行为：
- 受信任客户端可以尝试一次有界重试，使用缓存的按设备令牌。
- 如果该重试失败，客户端应停止自动重连循环，并向操作员显示操作指导。
## 设备身份 + 配对
- 节点应包含从密钥对指纹派生的稳定设备身份（`device.id`）。
- Gateway 网关按设备 + 角色签发令牌。
- 除非启用了本地自动审批，否则新设备 ID 需要配对审批。
- 配对自动审批以直接 local loopback 连接为中心。
- OpenClaw 还为受信任的共享密钥辅助流程提供一个很窄的后端/容器本地自连接路径。
- 同主机 tailnet 或 LAN 连接仍会被视为远程配对，并且需要审批。
- WS 客户端通常会在 `connect` 期间包含 `device` 身份（操作员 +
节点）。唯一无设备操作员例外是显式信任路径：
- Gateway 网关按设备 + 角色发放令牌。
- 除非启用了本地自动批准，否则新的设备 ID 需要配对批准。
- 配对自动批准以直接 local loopback 连接为中心。
- OpenClaw 还提供一个窄范围的后端/容器本地自连接路径，用于受信任的共享密钥辅助流程。
- 同主机 tailnet 或 LAN 连接仍会按远程配对处理，并且需要批准。
- WS 客户端通常会在 `connect` 期间包含 `device` 身份（操作员 + 节点）。唯一的无设备操作员例外是显式信任路径：
- `gateway.controlUi.allowInsecureAuth=true`，用于仅 localhost 的不安全 HTTP 兼容性。
- 成功的 `gateway.auth.mode: "trusted-proxy"` 操作员 Control UI 认证。
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（紧急破窗，严重降低安全性）。
- 使用共享 Gateway 网关令牌/密码认证的直连 loopback `gateway-client` 后端 RPC。
- 所有连接都必须签名服务器提供的 `connect.challenge` nonce。
- 成功的 `gateway.auth.mode: "trusted-proxy"` 操作员控制 UI 认证。
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（应急开关，严重降低安全性）。
- 直接 loopback 的 `gateway-client` 后端 RPC，使用共享 Gateway 网关令牌/密码认证。
- 所有连接都必须签署服务器提供的 `connect.challenge` nonce。
### 设备认证迁移诊断
对于仍使用挑战前签名行为的旧版客户端，`connect` 现在会在 `error.details.code` 下返回
对于仍使用挑战前签名行为的旧客户端，`connect` 现在会在 `error.details.code` 下返回
`DEVICE_AUTH_*` 详情代码，并带有稳定的 `error.details.reason`。
常见迁移失败：
| 消息 | details.code | details.reason | 含义 |
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | 客户端省略了 `device.nonce`（或发送为空）。 |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | 客户端使用过期/错误 nonce 进行签名。 |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | 客户端省略了 `device.nonce`（或发送了空值）。 |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | 客户端使用过期/错误的 nonce 签名。 |
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 签名载荷与 v2 载荷不匹配。 |
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 已签名时间戳超出允许偏差。 |
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` 与公钥指纹不匹配。 |
@ -592,24 +576,22 @@ Gateway 网关将这些视为**声明**，并执行服务端允许列表。
迁移目标：
- 始终等待 `connect.challenge`。
- 签名包含服务器 nonce 的 v2 载荷。
- 在 `connect.params.device.nonce` 中发送相同的 nonce。
- 首选签名载荷为 `v3`，除设备/客户端/角色/作用域/令牌/nonce 字段外，还绑定 `platform` 和 `deviceFamily`。
- 旧版 `v2` 签名仍会出于兼容性被接受，但配对设备元数据固定仍会在重连时控制命令策略。
- 签署包含服务器 nonce 的 v2 载荷。
- 在 `connect.params.device.nonce` 中发送相同 nonce。
- 首选签名载荷为 `v3`，它除了设备/客户端/角色/作用域/令牌/nonce 字段之外，还绑定 `platform` 和 `deviceFamily`。
- 为保持兼容性，仍接受旧版 `v2` 签名，但已配对设备元数据固定仍会控制重连时的命令策略。
## TLS + 固定
- WS 连接支持 TLS。
- 客户端可以选择固定 Gateway 网关证书指纹（参见 `gateway.tls`
配置，以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。
- 客户端可以选择固定 Gateway 网关证书指纹（请参阅 `gateway.tls`
配置以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。
## 作用域
此协议公开**完整 Gateway 网关 API**（Status、渠道、模型、聊天、
智能体、会话、节点、审批等）。确切表面由
`src/gateway/protocol/schema.ts` 中的 TypeBox schema 定义。
此协议公开**完整 Gateway 网关 API**（Status、渠道、模型、聊天、智能体、会话、节点、批准等）。确切表面由 `src/gateway/protocol/schema.ts` 中的 TypeBox schema 定义。
## 相关
- [桥接协议](/zh-CN/gateway/bridge-protocol)
- [Gateway 网关运行手册](/zh-CN/gateway)
- [Gateway 网关运维手册](/zh-CN/gateway)

550
docs/zh-CN/plugins/architecture-internals.md
View File

@ -1,27 +1,27 @@
---
read_when:
- 实现提供商运行时钩子、渠道生命周期或包集合
- 实现提供商运行时钩子、渠道生命周期或包组
- 调试插件加载顺序或注册表状态
- 添加新的插件能力或上下文引擎插件
summary: 插件架构内部机制：加载流水线、注册表、运行时钩子、HTTP 路由和参考表
title: 插件架构内部机制
x-i18n:
generated_at: "2026-04-29T03:44:32Z"
generated_at: "2026-04-29T04:06:18Z"
model: gpt-5.5
provider: openai
source_hash: a598de14ca67d4ef08093a4e6ce65ade18e1c427fca9b3edfce218f847915850
source_hash: 51020f00fd501c006a8e8e92f4daaeb65a9e211771f8f350d869017332b5da3b
source_path: plugins/architecture-internals.md
workflow: 16
---
对于公开的能力模型、插件形态和所有权/执行契约，请参阅[插件架构](/zh-CN/plugins/architecture)。本页是内部机制的参考：加载管线、注册表、运行时钩子、Gateway 网关 HTTP 路由、导入路径和 schema 表。
对于公开能力模型、插件形状和所有权/执行契约，请参阅 [插件架构](/zh-CN/plugins/architecture)。本页是内部机制的参考：加载流水线、注册表、运行时钩子、Gateway 网关 HTTP 路由、导入路径和架构表。
## 加载管线
## 加载流水线
启动时，OpenClaw 大致会执行以下操作：
1. 发现候选插件根目录
2. 读取原生或兼容 bundle 清单和 package 元数据
2. 读取原生或兼容包清单和包元数据
3. 拒绝不安全的候选项
4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、
`slots`、`load.paths`）
@ -29,67 +29,67 @@ x-i18n:
6. 加载已启用的原生模块：已构建的内置模块使用原生加载器；
未构建的原生插件使用 jiti
7. 调用原生 `register(api)` 钩子，并将注册项收集到插件注册表中
8. 将注册表暴露给命令/运行时表面
8. 将注册表暴露给命令/运行时界面
<Note>
`activate` 是 `register` 的旧版别名 — 加载器会解析存在的那个（`def.register ?? def.activate`），并在同一位置调用它。所有内置插件都使用 `register`；新插件请优先使用 `register`。
`activate` 是 `register` 的旧版别名——加载器会解析存在的那一个（`def.register ?? def.activate`），并在同一个时点调用它。所有内置插件都使用 `register`；新插件优先使用 `register`。
</Note>
安全门禁发生在运行时执行**之前**。当入口逃逸出插件根目录、路径对所有用户可写，或非内置插件的路径所有权看起来可疑时，候选项会被阻止。
安全门控发生在运行时执行**之前**。当入口逃逸插件根目录、路径全局可写，或非内置插件的路径所有权看起来可疑时，候选项会被阻止。
### 清单优先行为
清单是控制平面的事实来源。OpenClaw 使用它来：
清单是控制平面的事实来源。OpenClaw 用它来：
- 识别插件
- 发现声明的渠道/Skills/配置 schema 或 bundle 能力
- 发现声明的渠道/Skills/配置架构或包能力
- 验证 `plugins.entries.<id>.config`
- 增强 Control UI 标签/占位符
- 补充 Control UI 标签/占位符
- 显示安装/目录元数据
- 在不加载插件运行时的情况下，保留低成本的激活和设置描述符
- 在不加载插件运行时的情况下保留低成本激活和设置描述符
对于原生插件，运行时模块是数据平面部分。它注册钩子、工具、命令或提供商流程等实际行为。
可选的清单 `activation` 和 `setup` 块保留在控制平面上。它们是用于激活规划和设置发现的纯元数据描述符；它们不会替代运行时注册、`register(...)` 或 `setupEntry`。首批实时激活使用者现在会使用清单命令、渠道和提供商提示，在更广泛的注册表物化之前缩小插件加载范围：
可选清单 `activation` 和 `setup` 块保留在控制平面上。它们是仅包含元数据的描述符，用于激活规划和设置发现；它们不会取代运行时注册、`register(...)` 或 `setupEntry`。首批实时激活使用者现在会使用清单中的命令、渠道和提供商提示，在更广泛的注册表物化之前缩小插件加载范围：
- CLI 加载会缩小到拥有所请求主命令的插件
- 渠道设置/插件解析会缩小到拥有所请求渠道 ID 的插件
- 显式提供商设置/运行时解析会缩小到拥有所请求提供商 ID 的插件
- Gateway 网关启动规划使用 `activation.onStartup` 处理显式启动导入和启动退出；随着 OpenClaw 从隐式启动导入迁移，每个插件都应声明它，而没有静态能力元数据且没有 `activation.onStartup` 的插件，仍会为了兼容性使用已弃用的隐式启动辅助回退
- Gateway 网关启动规划使用 `activation.onStartup` 处理显式启动导入和启动选择退出；随着 OpenClaw 从隐式启动导入迁移开来，每个插件都应声明它，而没有静态能力元数据且没有 `activation.onStartup` 的插件仍会使用已弃用的隐式启动 sidecar 回退以保持兼容性
激活规划器同时为现有调用方暴露仅含 ID 的 API，并为新的诊断暴露规划 API。规划条目会报告插件被选中的原因，将显式 `activation.*` 规划器提示与清单所有权回退（例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和钩子）分开。该原因拆分是兼容性边界：现有插件元数据继续工作，而新代码可以在不改变运行时加载语义的情况下检测宽泛提示或回退行为。
激活规划器既为现有调用方暴露仅含 ID 的 API，也为新的诊断暴露规划 API。规划条目会报告插件被选中的原因，将显式 `activation.*` 规划器提示与清单所有权回退区分开来，例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和钩子。这种原因拆分就是兼容性边界：现有插件元数据会继续工作，而新代码可以在不改变运行时加载语义的情况下检测宽泛提示或回退行为。
设置发现现在优先使用描述符拥有的 ID（例如 `setup.providers` 和 `setup.cliBackends`）来缩小候选插件范围，然后才回退到面向仍需要设置时运行时钩子的插件的 `setup-api`。提供商设置列表会使用清单 `providerAuthChoices`、从描述符派生的设置选项，以及安装目录元数据，而无需加载提供商运行时。显式的 `setup.requiresRuntime: false` 是仅描述符的截止条件；省略 `requiresRuntime` 会保留旧版 `setup-api` 回退以保持兼容。如果多个已发现插件声明同一个规范化后的设置提供商或 CLI 后端 ID，设置查找会拒绝这个有歧义的所有者，而不是依赖发现顺序。当设置运行时确实执行时，注册表诊断会报告 `setup.providers` / `setup.cliBackends` 与由 setup-api 注册的提供商或 CLI 后端之间的偏差，但不会阻止旧版插件。
设置发现现在优先使用描述符拥有的 ID（例如 `setup.providers` 和 `setup.cliBackends`）来缩小候选插件范围，然后才回退到仍需要设置时运行时钩子的插件的 `setup-api`。提供商设置列表使用清单 `providerAuthChoices`、由描述符派生的设置选项，以及安装目录元数据，而无需加载提供商运行时。显式 `setup.requiresRuntime: false` 是仅描述符的截止点；省略 `requiresRuntime` 会保留旧版 setup-api 回退以保持兼容性。如果多个已发现插件声明了相同的规范化设置提供商或 CLI 后端 ID，设置查找会拒绝这个有歧义的所有者，而不是依赖发现顺序。当设置运行时确实执行时，注册表诊断会报告 `setup.providers` / `setup.cliBackends` 与 setup-api 注册的提供商或 CLI 后端之间的偏差，但不会阻止旧版插件。
### 插件缓存边界
OpenClaw 不会在基于墙钟时间的窗口后面缓存插件发现结果或直接清单注册表数据。安装、清单编辑和加载路径变更必须在下一次显式元数据读取或快照重建时可见。清单文件解析器可以保留一个有界的文件签名缓存，以打开的清单路径、inode、大小和时间戳为键；该缓存只用于避免重新解析未变化的字节，不得缓存发现、注册表、所有者或策略答案。
OpenClaw 不会在按墙钟时间划定的窗口后面缓存插件发现结果或直接清单注册表数据。安装、清单编辑和加载路径变更必须在下一次显式元数据读取或快照重建时可见。清单文件解析器可以保留一个有界文件签名缓存，该缓存以已打开的清单路径、inode、大小和时间戳为键；该缓存只用于避免重新解析未更改的字节，绝不能缓存发现、注册表、所有者或策略答案。
安全的元数据快速路径是显式对象所有权，而不是隐藏缓存。Gateway 网关启动热路径应通过调用链传递当前的 `PluginMetadataSnapshot`、派生的 `PluginLookUpTable`，或显式清单注册表。配置验证、启动自动启用、插件引导和提供商选择可以复用这些对象，只要它们代表当前配置和插件清单。设置查找仍会按需重建清单元数据，除非特定设置路径接收到显式清单注册表；应将其保留为冷路径回退，而不是添加隐藏查找缓存。当输入发生变化时，应重建并替换快照，而不是修改它或保留历史副本。
应从当前注册表/根目录重新计算活动插件注册表上的视图和内置渠道引导助手。短生命周期的 map 可以在单次调用中用于去重工作或防止重入；它们不得变成进程元数据缓存。
安全的元数据快速路径是显式对象所有权，而不是隐藏缓存。Gateway 网关启动热路径应通过调用链传递当前的 `PluginMetadataSnapshot`、派生的 `PluginLookUpTable`，或显式清单注册表。配置验证、启动自动启用、插件引导和提供商选择可以复用这些对象，只要它们代表当前配置和插件清单。设置查找仍会按需重建清单元数据，除非特定设置路径收到显式清单注册表；应将其保留为冷路径回退，而不是添加隐藏查找缓存。输入变化时，重建并替换快照，而不是修改它或保留历史副本。
活动插件注册表视图和内置渠道引导助手应根据当前注册表/根目录重新计算。短生命周期映射可以在一次调用内用于去重工作或防止重入；它们绝不能变成进程元数据缓存。
对于插件加载，持久缓存层是运行时加载。它可以在代码或已安装 artifact 实际加载时复用加载器状态，例如：
对于插件加载，持久缓存层是运行时加载。它可以在代码或已安装工件确实被加载时复用加载器状态，例如：
- `PluginLoaderCacheState` 和兼容的活动运行时注册表
- 用于避免重复导入同一运行时表面的 jiti/模块缓存和公共表面加载器缓存
- 已安装插件 artifact 的运行时依赖镜像和文件系统缓存
- 用于路径规范化或重复解析的短生命周期按调用 map
- jiti/模块缓存，以及用于避免重复导入同一运行时界面的公共界面加载器缓存
- 已安装插件工件的运行时依赖镜像和文件系统缓存
- 用于路径规范化或重复解析的短生命周期逐调用映射
这些缓存是数据平面实现细节。除非调用方有意请求运行时加载，否则它们不得回答控制平面问题，例如“哪个插件拥有此提供商？”。
这些缓存是数据平面实现细节。它们不能回答诸如“哪个插件拥有这个提供商？”这类控制平面问题，除非调用方有意请求运行时加载。
不要为以下内容添加持久缓存或基于墙钟时间的缓存：
不要为以下内容添加持久缓存或墙钟缓存：
- 发现结果
- 直接清单注册表
- 从已安装插件索引重建的清单注册表
- 提供商所有者查找、模型抑制、提供商策略或公共 artifact 元数据
- 任何其他从清单派生的答案，其中变更后的清单、已安装索引或加载路径应在下一次元数据读取时可见
- 提供商所有者查找、模型抑制、提供商策略或公共工件元数据
- 任何其他由清单派生的答案，其中已更改的清单、已安装索引或加载路径应在下一次元数据读取时可见
从持久化的已安装插件索引重建清单元数据的调用方，会按需重建该注册表。已安装索引是持久的来源平面状态；它不是隐藏的进程内元数据缓存。
从持久化的已安装插件索引重建清单元数据的调用方会按需重建该注册表。已安装索引是持久的来源平面状态；它不是隐藏的进程内元数据缓存。
## 注册表模型
已加载的插件不会直接修改随机的核心全局变量。它们会注册到一个中央插件注册表中。
已加载插件不会直接修改随机核心全局变量。它们会注册到一个中央插件注册表中。
注册表会跟踪：
@ -104,18 +104,18 @@ OpenClaw 不会在基于墙钟时间的窗口后面缓存插件发现结果或
- 后台服务
- 插件拥有的命令
随后，核心功能会从该注册表读取，而不是直接与插件模块交互。这让加载保持单向：
然后核心功能会从该注册表读取，而不是直接与插件模块通信。这让加载保持单向：
- 插件模块 -> 注册表注册
- 核心运行时 -> 注册表消费
这种分离对可维护性很重要。它意味着大多数核心表面只需要一个集成点：“读取注册表”，而不是“为每个插件模块做特殊处理”。
这种分离对可维护性很重要。它意味着大多数核心界面只需要一个集成点：“读取注册表”，而不是“为每个插件模块编写特殊逻辑”。
## 对话绑定回调
绑定对话的插件可以在批准完成解析时做出反应。
绑定对话的插件可以在审批被解决时作出反应。
使用 `api.onConversationBindingResolved(...)` 可在绑定请求被批准或拒绝后接收回调：
使用 `api.onConversationBindingResolved(...)` 在绑定请求被批准或拒绝后接收回调：
```ts
export default {
@ -140,84 +140,85 @@ export default {
- `status`：`"approved"` 或 `"denied"`
- `decision`：`"allow-once"`、`"allow-always"` 或 `"deny"`
- `binding`：已批准请求的已解析绑定
- `request`：原始请求摘要、分离提示、发送方 ID 和对话元数据
- `request`：原始请求摘要、分离提示、发送者 ID 和对话元数据
此回调仅用于通知。它不会更改谁被允许绑定对话，并且会在核心批准处理完成后运行。
此回调仅用于通知。它不会改变谁被允许绑定对话，并且会在核心审批处理完成后运行。
## 提供商运行时钩子
提供商插件有三层：
- **清单元数据**，用于低成本的运行时前查找：
- **清单元数据**，用于低成本的预运行时查找：
`setup.providers[].envVars`、已弃用的兼容性 `providerAuthEnvVars`、
`providerAuthAliases`、`providerAuthChoices` 和 `channelEnvVars`。
- **配置时钩子**：`catalog`（旧版 `discovery`）以及
`applyConfigDefaults`。
- **运行时钩子**：40 多个可选钩子，涵盖认证、模型解析、流包装、思考等级、重放策略和用量端点。完整列表见[钩子顺序和用法](#hook-order-and-usage)。
- **运行时钩子**：40 多个可选钩子，涵盖认证、模型解析、
流包装、thinking 等级、重放策略和用量端点。请参阅
[钩子顺序和用法](#hook-order-and-usage) 下的完整列表。
OpenClaw 仍然拥有通用 Agent loop、故障转移、转录处理和工具策略。这些钩子是用于提供商特定行为的扩展表面，无需完整的自定义推理传输。
OpenClaw 仍然拥有通用 Agent loop、故障转移、转录处理和工具策略。这些钩子是提供商特定行为的扩展界面，无需完整的自定义推理传输。
当提供商拥有基于环境的凭证，并且通用认证/Status/模型选择器路径应在不加载插件运行时的情况下看到这些凭证时，请使用清单 `setup.providers[].envVars`。已弃用的 `providerAuthEnvVars` 在弃用窗口期间仍会由兼容性适配器读取，使用它的非内置插件会收到清单诊断。当一个提供商 ID 应复用另一个提供商 ID 的环境变量、认证配置、配置支持的认证和 API 密钥新手引导选项时，请使用清单 `providerAuthAliases`。当新手引导/认证选择 CLI 表面应在不加载提供商运行时的情况下知道提供商的选择 ID、分组标签和简单的单标志认证接线时，请使用清单 `providerAuthChoices`。将提供商运行时 `envVars` 保留给面向操作员的提示，例如新手引导标签或 OAuth 客户端 ID/客户端密钥设置变量。
当提供商拥有基于环境的凭证，并且通用认证/状态/模型选择器路径应在不加载插件运行时的情况下看到这些凭证时，使用清单 `setup.providers[].envVars`。在弃用窗口期间，兼容性适配器仍会读取已弃用的 `providerAuthEnvVars`，使用它的非内置插件会收到清单诊断。当一个提供商 ID 应复用另一个提供商 ID 的环境变量、认证配置文件、配置支持的认证和 API 密钥新手引导选项时，使用清单 `providerAuthAliases`。当新手引导/认证选项 CLI 界面应在不加载提供商运行时的情况下知道提供商的选项 ID、分组标签和简单的单标志认证接线时，使用清单 `providerAuthChoices`。将提供商运行时 `envVars` 保留用于面向操作员的提示，例如新手引导标签或 OAuth 客户端 ID/客户端密钥设置变量。
当渠道具有由环境驱动的认证或设置，并且通用 shell 环境回退、配置/Status 检查或设置提示应在不加载渠道运行时的情况下看到它时，请使用清单 `channelEnvVars`。
当渠道具有由环境驱动的认证或设置，并且通用 shell 环境回退、配置/状态检查或设置提示应在不加载渠道运行时的情况下看到它时，使用清单 `channelEnvVars`。
### 钩子顺序和用法
对于模型/提供商插件，OpenClaw 会按以下大致顺序调用钩子。
对于模型/提供商插件，OpenClaw 会按大致如下顺序调用钩子。
“When to use” 列是快速决策指南。
OpenClaw 不再调用的仅兼容性提供商字段（例如 `ProviderPlugin.capabilities` 和 `suppressBuiltInModel`）有意未在此处列出。
| # | 钩子 | 作用 | 何时使用 |
| # | 钩子 | 作用 | 使用时机 |
| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `catalog` | 在生成 `models.json` 期间，将提供商配置发布到 `models.providers` | 提供商拥有目录或基准 URL 默认值 |
| 2 | `applyConfigDefaults` | 在配置物化期间应用提供商自有的全局配置默认值 | 默认值取决于凭证模式、环境或提供商模型系列语义 |
| -- | _(内置模型查找)_ | OpenClaw 会先尝试正常的注册表/目录路径 | _(不是插件钩子)_ |
| 3 | `normalizeModelId` | 在查找前规范化旧版或预览版模型 ID 别名 | 提供商在规范模型解析前负责别名清理 |
| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商系列的 `api` / `baseUrl` | 提供商负责同一传输系列中自定义提供商 ID 的传输清理 |
| 5 | `normalizeConfig` | 在运行时/提供商解析前规范化 `models.providers.<id>` | 提供商需要应与插件共存的配置清理；内置 Google 系列帮助程序也会兜底支持的 Google 配置项 |
| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式用量兼容性重写 | 提供商需要由端点驱动的原生流式用量元数据修复 |
| 7 | `resolveConfigApiKey` | 在加载运行时凭证前，为配置提供商解析环境变量标记凭证 | 提供商有提供商自有的环境变量标记 API 密钥解析；`amazon-bedrock` 也在这里有内置 AWS 环境变量标记解析器 |
| 8 | `resolveSyntheticAuth` | 暴露本地/自托管或配置支持的凭证，而不持久化明文 | 提供商可以使用合成/本地凭证标记运行 |
| 9 | `resolveExternalAuthProfiles` | 叠加提供商自有的外部凭证配置；CLI/应用自有凭据的默认 `persistence` 是 `runtime-only` | 提供商复用外部凭证凭据，而不持久化复制的刷新令牌；在清单中声明 `contracts.externalAuthProviders` |
| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的合成配置占位符置于环境变量/配置支持的凭证之后 | 提供商存储不应赢得优先级的合成占位符配置 |
| 11 | `resolveDynamicModel` | 为尚未进入本地注册表的提供商自有模型 ID 提供同步回退 | 提供商接受任意上游模型 ID |
| 12 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 ID 前需要网络元数据 |
| 13 | `normalizeResolvedModel` | 在嵌入式运行器使用已解析模型前进行最终重写 | 提供商需要传输重写，但仍使用核心传输 |
| 14 | `contributeResolvedModelCompat` | 为位于另一种兼容传输之后的供应商模型贡献兼容性标志 | 提供商能识别代理传输上的自有模型，而不接管提供商 |
| 15 | `capabilities` | 共享核心逻辑使用的提供商自有 transcript/工具元数据 | 提供商需要 transcript/提供商系列特殊处理 |
| 16 | `normalizeToolSchemas` | 在嵌入式运行器看到工具 schema 前对其进行规范化 | 提供商需要传输系列 schema 清理 |
| 17 | `inspectToolSchemas` | 在规范化后暴露提供商自有的 schema 诊断 | 提供商想要关键字警告，而不把提供商特定规则教给核心 |
| 18 | `resolveReasoningOutputMode` | 选择原生或标记式 reasoning 输出契约 | 提供商需要标记式 reasoning/最终输出，而不是原生字段 |
| 19 | `prepareExtraParams` | 在通用流式选项包装器前规范化请求参数 | 提供商需要默认请求参数或按提供商进行参数清理 |
| 20 | `createStreamFn` | 用自定义传输完全替换正常流式路径 | 提供商需要自定义 wire protocol，而不仅仅是包装器 |
| 21 | `wrapStreamFn` | 应用通用包装器之后的流式包装器 | 提供商需要请求标头/正文/模型兼容包装器，而不需要自定义传输 |
| 22 | `resolveTransportTurnState` | 附加原生每轮传输标头或元数据 | 提供商希望通用传输发送提供商原生的轮次身份 |
| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 标头或会话冷却策略 | 提供商希望通用 WS 传输调整会话标头或回退策略 |
| 24 | `formatApiKey` | 凭证配置格式化器：已存储配置会变成运行时 `apiKey` 字符串 | 提供商存储额外凭证元数据，并需要自定义运行时令牌形态 |
| 25 | `refreshOAuth` | 针对自定义刷新端点或刷新失败策略的 OAuth 刷新覆盖 | 提供商不适合共享的 `pi-ai` 刷新器 |
| 26 | `buildAuthDoctorHint` | OAuth 刷新失败时附加的修复提示 | 提供商在刷新失败后需要提供商自有的凭证修复指导 |
| 27 | `matchesContextOverflowError` | 提供商自有的上下文窗口溢出匹配器 | 提供商存在通用启发式规则会漏掉的原始溢出错误 |
| 28 | `classifyFailoverReason` | 提供商自有的故障转移原因分类 | 提供商可以将原始 API/传输错误映射到速率限制/过载等 |
| 29 | `isCacheTtlEligible` | 针对代理/回程提供商的提示缓存策略 | 提供商需要代理特定的缓存 TTL 门控 |
| 30 | `buildMissingAuthMessage` | 替换通用缺失凭证恢复消息 | 提供商需要提供商特定的缺失凭证恢复提示 |
| 31 | `suppressBuiltInModel` | 已弃用。运行时钩子不再被调用；请使用清单 `modelCatalog.suppressions` | 用于隐藏陈旧上游行的历史钩子；将新的抑制数据保留在插件清单中 |
| 32 | `augmentModelCatalog` | 在设备发现后追加的合成/最终目录行 | 提供商需要 `models list` 和选择器中的合成前向兼容行 |
| 33 | `resolveThinkingProfile` | 特定模型的 `/think` 级别集合、显示标签和默认值 | 提供商为所选模型暴露自定义思考阶梯或二元标签 |
| 34 | `isBinaryThinking` | 开/关 reasoning 切换兼容性钩子 | 提供商只暴露二元思考开关 |
| 35 | `supportsXHighThinking` | `xhigh` reasoning 支持兼容性钩子 | 提供商只想对部分模型启用 `xhigh` |
| 36 | `resolveDefaultThinkingLevel` | 默认 `/think` 级别兼容性钩子 | 提供商拥有某个模型系列的默认 `/think` 策略 |
| 37 | `isModernModelRef` | 用于实时配置文件过滤器和冒烟选择的现代模型匹配器 | 提供商负责实时/冒烟首选模型匹配 |
| 38 | `prepareRuntimeAuth` | 在推理前，将已配置的凭证交换为实际运行时令牌/密钥 | 提供商需要令牌交换或短期请求凭证 |
| 39 | `resolveUsageAuth` | 为 `/usage` 和相关 Status 界面解析用量/计费凭证 | 提供商需要自定义用量/配额令牌解析，或不同的用量凭证 |
| 40 | `fetchUsageSnapshot` | 在认证解析完成后，获取并规范化提供商特定的用量/配额快照 | 提供商需要提供商特定的用量端点或载荷解析器 |
| 41 | `createEmbeddingProvider` | 为记忆/搜索构建提供商拥有的嵌入适配器 | 记忆嵌入行为属于提供商插件 |
| 42 | `buildReplayPolicy` | 返回用于控制该提供商转录处理的重放策略 | 提供商需要自定义转录策略（例如，剥离思考块） |
| 43 | `sanitizeReplayHistory` | 在通用转录清理后重写重放历史 | 提供商需要超出共享压缩辅助函数之外的提供商特定重放重写 |
| 44 | `validateReplayTurns` | 在嵌入式运行器之前进行最终的重放轮次验证或重塑 | 提供商传输协议在通用清理后需要更严格的轮次验证 |
| 45 | `onModelSelected` | 运行提供商拥有的选择后副作用 | 当模型变为活动状态时，提供商需要遥测或提供商拥有的状态 |
| 1 | `catalog` | 在生成 `models.json` 期间将提供商配置发布到 `models.providers` | 提供商拥有目录或基础 URL 默认值 |
| 2 | `applyConfigDefaults` | 在配置物化期间应用提供商拥有的全局配置默认值 | 默认值依赖于凭证模式、环境或提供商模型系列语义 |
| -- | _(内置模型查找)_ | OpenClaw 先尝试正常的注册表/目录路径 | _(不是插件钩子)_ |
| 3 | `normalizeModelId` | 在查找前规范化旧版或预览模型 ID 别名 | 提供商在规范模型解析前负责别名清理 |
| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商系列的 `api` / `baseUrl` | 提供商负责同一传输系列中自定义提供商 ID 的传输清理 |
| 5 | `normalizeConfig` | 在运行时/提供商解析前规范化 `models.providers.<id>` | 提供商需要应随插件一起维护的配置清理；内置 Google 系列助手也会为受支持的 Google 配置条目兜底 |
| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式用量兼容性重写 | 提供商需要由端点驱动的原生流式用量元数据修复 |
| 7 | `resolveConfigApiKey` | 在运行时凭证加载前解析配置提供商的环境标记凭证 | 提供商拥有由提供商负责的环境标记 API 密钥解析；`amazon-bedrock` 在这里也有内置 AWS 环境标记解析器 |
| 8 | `resolveSyntheticAuth` | 暴露本地/自托管或由配置支持的凭证，而不持久化明文 | 提供商可以使用合成/本地凭证标记运行 |
| 9 | `resolveExternalAuthProfiles` | 叠加提供商拥有的外部凭证配置文件；CLI/应用拥有的凭证默认 `persistence` 为 `runtime-only` | 提供商复用外部凭证，而不持久化复制的刷新令牌；在清单中声明 `contracts.externalAuthProviders` |
| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的合成配置文件占位符降级到环境/配置支持的凭证之后 | 提供商存储不应优先胜出的合成占位符配置文件 |
| 11 | `resolveDynamicModel` | 为尚未在本地注册表中的提供商拥有模型 ID 提供同步回退 | 提供商接受任意上游模型 ID |
| 12 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 ID 前需要网络元数据 |
| 13 | `normalizeResolvedModel` | 在嵌入式运行器使用已解析模型前进行最终重写 | 提供商需要传输重写，但仍使用核心传输 |
| 14 | `contributeResolvedModelCompat` | 为另一个兼容传输背后的供应商模型贡献兼容性标志 | 提供商能在代理传输上识别自己的模型，而不接管该提供商 |
| 15 | `normalizeToolSchemas` | 在嵌入式运行器看到工具 schema 前规范化它们 | 提供商需要传输系列的 schema 清理 |
| 16 | `inspectToolSchemas` | 在规范化后暴露提供商拥有的 schema 诊断 | 提供商想提供关键字警告，而不让核心学习提供商特定规则 |
| 17 | `resolveReasoningOutputMode` | 选择原生或带标签的推理输出契约 | 提供商需要带标签的推理/最终输出，而不是原生字段 |
| 18 | `prepareExtraParams` | 在通用流选项包装器前进行请求参数规范化 | 提供商需要默认请求参数或按提供商进行参数清理 |
| 19 | `createStreamFn` | 用自定义传输完全替换正常流路径 | 提供商需要自定义线路协议，而不只是包装器 |
| 20 | `wrapStreamFn` | 应用通用包装器后的流包装器 | 提供商需要请求头/正文/模型兼容性包装器，而不是自定义传输 |
| 21 | `resolveTransportTurnState` | 附加原生的每轮传输请求头或元数据 | 提供商希望通用传输发送提供商原生的轮次身份 |
| 22 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 请求头或会话冷却策略 | 提供商希望通用 WS 传输调整会话请求头或回退策略 |
| 23 | `formatApiKey` | 凭证配置文件格式化器：已存储配置文件会变成运行时 `apiKey` 字符串 | 提供商存储额外凭证元数据，并需要自定义运行时令牌形态 |
| 24 | `refreshOAuth` | OAuth 刷新覆盖，用于自定义刷新端点或刷新失败策略 | 提供商不适配共享的 `pi-ai` 刷新器 |
| 25 | `buildAuthDoctorHint` | OAuth 刷新失败时附加的修复提示 | 提供商在刷新失败后需要提供商拥有的凭证修复指南 |
| 26 | `matchesContextOverflowError` | 提供商拥有的上下文窗口溢出匹配器 | 提供商有通用启发式规则会漏掉的原始溢出错误 |
| 27 | `classifyFailoverReason` | 提供商拥有的故障转移原因分类 | 提供商可以将原始 API/传输错误映射为限速/过载等 |
| 28 | `isCacheTtlEligible` | 代理/回传提供商的提示缓存策略 | 提供商需要代理特定的缓存 TTL 门控 |
| 29 | `buildMissingAuthMessage` | 替换通用缺失凭证恢复消息 | 提供商需要提供商特定的缺失凭证恢复提示 |
| 30 | `augmentModelCatalog` | 设备发现后追加的合成/最终目录行 | 提供商需要在 `models list` 和选择器中提供合成的前向兼容行 |
| 31 | `resolveThinkingProfile` | 模型特定的 `/think` 级别集合、显示标签和默认值 | 提供商为选定模型暴露自定义思考阶梯或二元标签 |
| 32 | `isBinaryThinking` | 开/关推理切换兼容性钩子 | 提供商只暴露二元思考开/关 |
| 33 | `supportsXHighThinking` | `xhigh` 推理支持兼容性钩子 | 提供商只想在部分模型上启用 `xhigh` |
| 34 | `resolveDefaultThinkingLevel` | 默认 `/think` 级别兼容性钩子 | 提供商拥有某个模型系列的默认 `/think` 策略 |
| 35 | `isModernModelRef` | 用于实时配置文件过滤器和冒烟选择的现代模型匹配器 | 提供商拥有实时/冒烟首选模型匹配 |
| 36 | `prepareRuntimeAuth` | 在推理前将已配置凭证交换成实际运行时令牌/密钥 | 提供商需要令牌交换或短期请求凭证 |
| 37 | `resolveUsageAuth` | 为 `/usage` 和相关状态界面解析用量/计费凭证 | 提供商需要自定义用量/配额令牌解析，或需要不同的用量凭证 |
| 38 | `fetchUsageSnapshot` | 在凭证解析完成后，获取并规范化特定于提供商的用量/配额快照 | 提供商需要特定于提供商的用量端点或载荷解析器 |
| 39 | `createEmbeddingProvider` | 为记忆/搜索构建提供商自有的嵌入适配器 | 记忆嵌入行为归属于提供商插件 |
| 40 | `buildReplayPolicy` | 返回用于控制提供商对话记录处理的重放策略 | 提供商需要自定义对话记录策略（例如剥离思考块） |
| 41 | `sanitizeReplayHistory` | 在通用对话记录清理后重写重放历史 | 提供商需要超出共享压缩辅助函数范围的、特定于提供商的重放重写 |
| 42 | `validateReplayTurns` | 在嵌入式运行器之前进行最终的重放轮次验证或重塑 | 提供商传输层在通用清理后需要更严格的轮次验证 |
| 43 | `onModelSelected` | 运行提供商自有的选择后副作用 | 当模型变为活动状态时，提供商需要遥测或提供商自有状态 |
`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配的提供商插件，然后继续遍历其他具备钩子能力的提供商插件，直到某个钩子实际更改模型 ID 或传输/配置。这样可以让别名/兼容性提供商垫片继续工作，而不要求调用方知道哪个内置插件拥有这次重写。如果没有提供商钩子重写受支持的 Google 系列配置条目，内置的 Google 配置规范化器仍会应用该兼容性清理。
`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配的提供商插件，然后继续检查其他具备钩子能力的提供商插件，直到某个插件实际更改模型 ID 或传输协议/配置。这样可以让别名/兼容提供商适配层继续工作，而不要求调用方知道哪个内置插件拥有这次重写。如果没有提供商钩子重写受支持的 Google 系列配置条目，内置的 Google 配置规范化器仍会应用该兼容性清理。
如果提供商需要完全自定义的传输协议或自定义请求执行器，那属于另一类扩展。这些钩子适用于仍运行在 OpenClaw 正常推理循环上的提供商行为。
如果提供商需要完全自定义的线路协议或自定义请求执行器，那属于另一类扩展。这些钩子适用于仍运行在 OpenClaw 常规推理循环上的提供商行为。
### 提供商示例
@ -275,37 +276,29 @@ api.registerProvider({
### 内置示例
内置提供商插件会组合上面的钩子，以适配各个厂商的目录、鉴权、思考、重放和用量需求。权威钩子集合位于 `extensions/` 下的各个插件中；本页说明这些形态，而不是镜像该列表。
内置提供商插件会组合上面的钩子，以适配每个供应商的目录、凭证、思考、重放和用量需求。权威钩子集合随各插件一起位于 `extensions/` 下；本页展示的是形态，而不是镜像完整列表。
<AccordionGroup>
<Accordion title="透传目录提供商">
OpenRouter、Kilocode、Z.AI、xAI 注册 `catalog` 以及
`resolveDynamicModel` / `prepareDynamicModel`，这样它们可以在 OpenClaw 的静态目录之前暴露上游模型 ID。
<Accordion title="Pass-through catalog providers">
OpenRouter、Kilocode、Z.AI、xAI 会注册 `catalog` 以及 `resolveDynamicModel` / `prepareDynamicModel`，以便它们可以在 OpenClaw 的静态目录之前暴露上游模型 ID。
</Accordion>
<Accordion title="OAuth 和用量端点提供商">
GitHub Copilot、Gemini CLI、ChatGPT Codex、MiniMax、Xiaomi、z.ai 将
`prepareRuntimeAuth` 或 `formatApiKey` 与 `resolveUsageAuth` +
`fetchUsageSnapshot` 搭配使用，以自行负责令牌交换和 `/usage` 集成。
<Accordion title="OAuth and usage endpoint providers">
GitHub Copilot、Gemini CLI、ChatGPT Codex、MiniMax、Xiaomi、z.ai 会将 `prepareRuntimeAuth` 或 `formatApiKey` 与 `resolveUsageAuth` + `fetchUsageSnapshot` 配对，以拥有令牌交换和 `/usage` 集成。
</Accordion>
<Accordion title="重放和转录清理系列">
共享的命名系列（`google-gemini`、`passthrough-gemini`、
`anthropic-by-model`、`hybrid-anthropic-openai`）让提供商可以通过 `buildReplayPolicy` 选择加入转录策略，而不需要每个插件重新实现清理。
<Accordion title="Replay and transcript cleanup families">
共享的命名族（`google-gemini`、`passthrough-gemini`、`anthropic-by-model`、`hybrid-anthropic-openai`）允许提供商通过 `buildReplayPolicy` 选择加入转录策略，而不是让每个插件重新实现清理。
</Accordion>
<Accordion title="仅目录提供商">
`byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、`nvidia`、
`qianfan`、`synthetic`、`together`、`venice`、`vercel-ai-gateway` 和
`volcengine` 只注册 `catalog`，并使用共享推理循环。
<Accordion title="Catalog-only providers">
`byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、`nvidia`、`qianfan`、`synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine` 只注册 `catalog`，并使用共享推理循环。
</Accordion>
<Accordion title="Anthropic 专用流式辅助工具">
Beta 标头、`/fast` / `serviceTier` 和 `context1m` 位于 Anthropic 插件的公共 `api.ts` / `contract-api.ts` 边界中
（`wrapAnthropicProviderStream`、`resolveAnthropicBetas`、
`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`），而不是位于通用 SDK 中。
<Accordion title="Anthropic-specific stream helpers">
Beta 标头、`/fast` / `serviceTier` 和 `context1m` 位于 Anthropic 插件的公共 `api.ts` / `contract-api.ts` 接缝中（`wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`），而不是位于通用 SDK 中。
</Accordion>
</AccordionGroup>
## 运行时辅助工具
## 运行时辅助函数
插件可以通过 `api.runtime` 访问选定的核心辅助工具。对于 TTS：
插件可以通过 `api.runtime` 访问选定的核心辅助函数。对于 TTS：
```ts
const clip = await api.runtime.tts.textToSpeech({
@ -324,14 +317,14 @@ const voices = await api.runtime.tts.listVoices({
});
```
注意：
说明：
- `textToSpeech` 会返回用于文件/语音备注界面的常规核心 TTS 输出载荷。
- `textToSpeech` 会为文件/语音备注表面返回常规核心 TTS 输出载荷。
- 使用核心 `messages.tts` 配置和提供商选择。
- 返回 PCM 音频缓冲区 + 采样率。插件必须为提供商重采样/编码。
- `listVoices` 对每个提供商都是可选的。将它用于厂商自有的语音选择器或设置流程。
- 语音列表可以包含更丰富的元数据，例如区域设置、性别和个性标签，供提供商感知的选择器使用。
- OpenAI 和 ElevenLabs 目前支持电话音频。Microsoft 不支持。
- `listVoices` 对每个提供商都是可选的。将它用于供应商拥有的语音选择器或设置流程。
- 语音列表可以包含更丰富的元数据，例如语言区域、性别和个性标签，供感知提供商的选择器使用。
- OpenAI 和 ElevenLabs 目前支持电话语音。Microsoft 不支持。
插件也可以通过 `api.registerSpeechProvider(...)` 注册语音提供商。
@ -351,14 +344,14 @@ api.registerSpeechProvider({
});
```
注意：
说明：
- 将 TTS 策略、回退和回复投递保留在核心中。
- 将语音提供商用于厂商自有的合成行为。
- 将语音提供商用于供应商拥有的合成行为。
- 旧版 Microsoft `edge` 输入会规范化为 `microsoft` 提供商 ID。
- 首选的所有权模型以公司为导向：随着 OpenClaw 添加这些能力契约，一个厂商插件可以拥有文本、语音、图像和未来的媒体提供商。
- 首选的所有权模型以公司为导向：随着 OpenClaw 添加这些能力契约，一个供应商插件可以拥有文本、语音、图像以及未来的媒体提供商。
对于图像/音频/视频理解，插件注册一个有类型的媒体理解提供商，而不是通用键/值包：
对于图像/音频/视频理解，插件会注册一个带类型的媒体理解提供商，而不是通用键值包：
```ts
api.registerMediaUnderstandingProvider({
@ -370,17 +363,17 @@ api.registerMediaUnderstandingProvider({
});
```
注意：
说明：
- 将编排、回退、配置和渠道接线保留在核心中。
- 将厂商行为保留在提供商插件中。
- 将供应商行为保留在提供商插件中。
- 增量扩展应保持类型化：新的可选方法、新的可选结果字段、新的可选能力。
- 视频生成已经遵循相同模式：
- 核心拥有能力契约和运行时辅助工具
- 厂商插件注册 `api.registerVideoGenerationProvider(...)`
- 核心拥有能力契约和运行时辅助函数
- 供应商插件注册 `api.registerVideoGenerationProvider(...)`
- 功能/渠道插件使用 `api.runtime.videoGeneration.*`
对于媒体理解运行时辅助工具，插件可以调用：
对于媒体理解运行时辅助函数，插件可以调用：
```ts
const image = await api.runtime.mediaUnderstanding.describeImageFile({
@ -395,7 +388,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({
});
```
对于音频转录，插件可以使用媒体理解运行时，也可以使用较旧的 STT 别名：
对于音频转写，插件可以使用媒体理解运行时，或较旧的 STT 别名：
```ts
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
@ -406,14 +399,14 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
});
```
注意：
说明：
- `api.runtime.mediaUnderstanding.*` 是图像/音频/视频理解的首选共享界面。
- `api.runtime.mediaUnderstanding.*` 是图像/音频/视频理解的首选共享表面。
- 使用核心媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。
- 当没有产生转录输出时（例如跳过/不支持的输入），返回 `{ text: undefined }`。
- 当没有生成转写输出时（例如跳过/不支持的输入），返回 `{ text: undefined }`。
- `api.runtime.stt.transcribeAudioFile(...)` 仍作为兼容性别名保留。
插件还可以通过 `api.runtime.subagent` 启动后台子智能体运行：
插件也可以通过 `api.runtime.subagent` 启动后台子智能体运行：
```ts
const result = await api.runtime.subagent.run({
@ -425,16 +418,16 @@ const result = await api.runtime.subagent.run({
});
```
注意：
说明：
- `provider` 和 `model` 是每次运行的可选覆盖项，不是持久会话更改。
- OpenClaw 只会为可信调用方遵循这些覆盖字段。
- 对于插件拥有的回退运行，运营者必须使用 `plugins.entries.<id>.subagent.allowModelOverride: true` 选择启用。
- 使用 `plugins.entries.<id>.subagent.allowedModels` 将可信插件限制为特定的规范 `provider/model` 目标，或使用 `"*"` 明确允许任何目标。
- 不可信插件的子智能体运行仍可工作，但覆盖请求会被拒绝，而不是静默回退。
- 插件创建的子智能体会话会标记创建它的插件 ID。回退 `api.runtime.subagent.deleteSession(...)` 只能删除这些归属会话；任意会话删除仍需要管理员范围的 Gateway 网关请求。
- OpenClaw 只为受信任调用方接受这些覆盖字段。
- 对于插件拥有的回退运行，操作者必须使用 `plugins.entries.<id>.subagent.allowModelOverride: true` 选择加入。
- 使用 `plugins.entries.<id>.subagent.allowedModels` 将受信任插件限制到特定的规范 `provider/model` 目标，或使用 `"*"` 显式允许任意目标。
- 不受信任的插件子智能体运行仍可工作，但覆盖请求会被拒绝，而不是静默回退。
- 插件创建的子智能体会话会标记创建插件 ID。回退 `api.runtime.subagent.deleteSession(...)` 只能删除这些归属会话；任意会话删除仍需要具备管理员范围的 Gateway 网关请求。
对于网页搜索，插件可以使用共享运行时辅助工具，而不是深入智能体工具接线：
对于 Web 搜索，插件可以使用共享运行时辅助函数，而不是进入 Agent 工具接线：
```ts
const providers = api.runtime.webSearch.listProviders({
@ -450,14 +443,13 @@ const result = await api.runtime.webSearch.search({
});
```
插件也可以通过
`api.registerWebSearchProvider(...)` 注册网页搜索提供商。
插件也可以通过 `api.registerWebSearchProvider(...)` 注册 Web 搜索提供商。
注意：
说明：
- 将提供商选择、凭证解析和共享请求语义保留在核心中。
- 将网页搜索提供商用于厂商专用搜索传输。
- `api.runtime.webSearch.*` 是需要搜索行为但不依赖智能体工具包装器的功能/渠道插件的首选共享界面。
- 将 Web 搜索提供商用于供应商特定的搜索传输协议。
- `api.runtime.webSearch.*` 是需要搜索行为但不依赖 Agent 工具封装器的功能/渠道插件的首选共享表面。
### `api.runtime.imageGeneration`
@ -472,7 +464,7 @@ const providers = api.runtime.imageGeneration.listProviders({
});
```
- `generate(...)`：使用已配置的图像生成提供商链生成图像。
- `generate(...)`：使用配置的图像生成提供商链生成图像。
- `listProviders(...)`：列出可用的图像生成提供商及其能力。
## Gateway 网关 HTTP 路由
@ -495,42 +487,43 @@ api.registerHttpRoute({
路由字段：
- `path`：Gateway 网关 HTTP 服务器下的路由路径。
- `auth`：必填。使用 `"gateway"` 要求常规 Gateway 网关鉴权，或使用 `"plugin"` 进行插件管理的鉴权/webhook 验证。
- `auth`：必需。使用 `"gateway"` 要求常规 Gateway 网关凭证，或使用 `"plugin"` 进行插件管理的凭证/Webhook 验证。
- `match`：可选。`"exact"`（默认）或 `"prefix"`。
- `replaceExisting`：可选。允许同一个插件替换它自己现有的路由注册。
- `handler`：当该路由处理了请求时返回 `true`。
- `replaceExisting`：可选。允许同一插件替换它自己现有的路由注册。
- `handler`：当路由已处理请求时返回 `true`。
注意：
说明：
- `api.registerHttpHandler(...)` 已移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。
- 插件路由必须显式声明 `auth`。
- 除非设置 `replaceExisting: true`，否则精确的 `path + match` 冲突会被拒绝，并且一个插件不能替换另一个插件的路由。
- 具有不同 `auth` 级别的重叠路由会被拒绝。只在同一认证级别上保留 `exact`/`prefix` 回退链。
- `auth: "plugin"` 路由**不会**自动获得操作者运行时作用域。它们用于插件管理的 webhook/签名验证，而不是有特权的 Gateway 网关辅助调用。
- 精确的 `path + match` 冲突会被拒绝，除非设置了 `replaceExisting: true`，并且一个插件不能替换另一个插件的路由。
- 不同 `auth` 级别的重叠路由会被拒绝。仅在相同 auth 级别上保留 `exact`/`prefix` 回退链。
- `auth: "plugin"` 路由**不会**自动获得操作者运行时作用域。它们用于插件管理的 webhook/签名验证，而不是特权 Gateway 网关辅助调用。
- `auth: "gateway"` 路由在 Gateway 网关请求运行时作用域内运行，但该作用域有意保持保守：
- 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes`
- 受信任且携带身份的 HTTP 模式（例如 `trusted-proxy`，或私有入口上的 `gateway.auth.mode = "none"`）仅在显式提供该标头时才遵循 `x-openclaw-scopes`
- 如果这些携带身份的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退到 `operator.write`
- 实用规则：不要假设通过 Gateway 网关认证的插件路由是隐式管理员表面。如果你的路由需要仅限管理员的行为，请要求携带身份的认证模式，并记录显式 `x-openclaw-scopes` 标头约定。
- 共享密钥 bearer auth（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes`
- 可信的带身份 HTTP 模式（例如 `trusted-proxy`，或私有入口上的 `gateway.auth.mode = "none"`）仅在显式提供该 header 时才遵循 `x-openclaw-scopes`
- 如果这些带身份的插件路由请求缺少 `x-openclaw-scopes`，运行时作用域会回退到 `operator.write`
- 实用规则：不要假设 gateway-auth 插件路由是隐式管理员入口。如果你的路由需要仅限管理员的行为，请要求带身份的 auth 模式，并记录显式 `x-openclaw-scopes` header 合约。
## 插件 SDK 导入路径
编写新插件时，请使用窄范围的 SDK 子路径，而不是单体的 `openclaw/plugin-sdk` 根
编写新插件时，请使用窄 SDK 子路径，而不是单体式 `openclaw/plugin-sdk` 根
barrel。核心子路径：
| 子路径 | 用途 |
| ----------------------------------- | -------------------------------------------------- |
| `openclaw/plugin-sdk/plugin-entry` | 插件注册原语 |
| `openclaw/plugin-sdk/channel-core` | 渠道入口/构建辅助工具 |
| `openclaw/plugin-sdk/core` | 通用共享辅助工具和伞形契约 |
| `openclaw/plugin-sdk/config-schema` | 根 `openclaw.json` Zod 模式（`OpenClawSchema`） |
| `openclaw/plugin-sdk/core` | 通用共享辅助工具和伞形合约 |
| `openclaw/plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema（`OpenClawSchema`） |
渠道插件可从一组窄范围接缝中选择：`channel-setup`、
渠道插件可从一组窄衔接面中选择：`channel-setup`、
`setup-runtime`、`setup-adapter-runtime`、`setup-tools`、`channel-pairing`、
`channel-contract`、`channel-feedback`、`channel-inbound`、`channel-lifecycle`、
`channel-reply-pipeline`、`command-auth`、`secret-input`、`webhook-ingress`、
`channel-targets` 和 `channel-actions`。审批行为应统一到一个
`approvalCapability` 契约上，而不是混用无关的插件字段。参见[渠道插件](/zh-CN/plugins/sdk-channel-plugins)。
`approvalCapability` 合约上，而不是混用不相关的插件字段。请参阅
[渠道插件](/zh-CN/plugins/sdk-channel-plugins)。
运行时和配置辅助工具位于匹配的聚焦 `*-runtime` 子路径下
（`approval-runtime`、`agent-runtime`、`lazy-runtime`、`directory-runtime`、
@ -552,115 +545,129 @@ barrel。核心子路径：
- `runtime-api.js` — 仅运行时 barrel
- `setup-entry.js` — 设置插件入口
外部插件应只导入 `openclaw/plugin-sdk/*` 子路径。切勿从核心或另一个插件中
导入另一个插件包的 `src/*`。通过 facade 加载的入口点会在存在活动运行时配置快照时优先使用它，
然后回退到磁盘上解析出的配置文件。
外部插件应只导入 `openclaw/plugin-sdk/*` 子路径。绝不要从核心或另一个插件
导入另一个插件包的 `src/*`。通过 facade 加载的入口点会优先使用有效的运行时
配置快照（如果存在），然后回退到磁盘上解析出的配置文件。
`image-generation`、`media-understanding` 和 `speech` 等特定能力子路径存在，
是因为内置插件当前正在使用它们。它们不会自动成为长期冻结的外部契约；依赖它们时请查看相关 SDK 参考页面。
`image-generation`、`media-understanding` 和 `speech` 等能力专用子路径存在，
是因为内置插件目前在使用它们。它们并不会自动成为长期冻结的外部合约；
依赖它们时请查看相关 SDK 参考页面。
## 消息工具模式
## 消息工具 schema
插件应拥有针对非消息原语（如反应、已读和投票）的渠道特定
`describeMessageTool(...)` 模式贡献。共享发送呈现应使用通用
`MessagePresentation` 契约，而不是提供商原生的按钮、组件、块或卡片字段。
有关契约、回退规则、提供商映射和插件作者检查清单，请参见[消息呈现](/zh-CN/plugins/message-presentation)。
插件应拥有渠道特定的 `describeMessageTool(...)` schema 贡献，用于 reaction、
read 和 poll 等非消息原语。共享发送呈现应使用通用 `MessagePresentation` 合约，
而不是提供商原生的按钮、组件、区块或卡片字段。有关合约、回退规则、提供商映射
和插件作者检查清单，请参阅 [消息呈现](/zh-CN/plugins/message-presentation)。
具备发送能力的插件通过消息能力声明它们可以渲染的内容：
- `presentation` 用于语义呈现块（`text`、`context`、`divider`、`buttons`、`select`）
- `presentation` 用于语义呈现区块（`text`、`context`、`divider`、`buttons`、`select`）
- `delivery-pin` 用于固定投递请求
核心决定是以原生方式渲染呈现，还是将其降级为文本。不要从通用消息工具中暴露提供商原生 UI 逃生口。
面向旧版原生模式的已弃用 SDK 辅助工具仍会为现有第三方插件导出，但新插件不应使用它们。
核心会决定是原生渲染呈现，还是将其降级为文本。不要从通用消息工具暴露
提供商原生 UI 逃逸口。旧版原生 schema 的已弃用 SDK 辅助工具仍会为现有
第三方插件导出，但新插件不应使用它们。
## 渠道目标解析
渠道插件应拥有渠道特定的目标语义。保持共享出站宿主通用，并使用消息适配器表面处理提供商规则：
渠道插件应拥有渠道特定的目标语义。保持共享出站主机的通用性，并使用消息
适配器表面处理提供商规则：
- `messaging.inferTargetChatType({ to })` 在目录查找前决定归一化目标应被视为 `direct`、`group` 还是 `channel`。
- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉核心，某个输入是否应直接跳到类似 ID 的解析，而不是进行目录搜索。
- `messaging.targetResolver.resolveTarget(...)` 是核心在归一化后或目录未命中后需要最终由提供商拥有的解析时使用的插件回退。
- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后拥有提供商特定的会话路由构建。
- `messaging.inferTargetChatType({ to })` 在目录查找之前决定规范化后的目标
应被视为 `direct`、`group` 还是 `channel`。
- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉核心某个输入是否
应跳过目录搜索，直接进入类似 id 的解析。
- `messaging.targetResolver.resolveTarget(...)` 是当核心在规范化之后或目录未命中
之后需要最终由提供商拥有的解析时使用的插件回退。
- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后负责构造提供商特定的
会话路由。
推荐拆分：
- 使用 `inferTargetChatType` 处理应在搜索对等方/群组前发生的类别决策。
- 使用 `looksLikeId` 进行“将此视为显式/原生目标 ID”的检查。
- 使用 `resolveTarget` 处理提供商特定的归一化回退，而不是用于宽泛的目录搜索。
- 将聊天 ID、线程 ID、JID、handle 和房间 ID 等提供商原生 ID 保留在 `target` 值或提供商特定参数中，而不是放在通用 SDK 字段中。
- 使用 `inferTargetChatType` 处理应在搜索 peer/group 之前发生的类别决策。
- 使用 `looksLikeId` 进行“将其视为显式/原生目标 id”的检查。
- 使用 `resolveTarget` 作为提供商特定规范化回退，而不是用于宽泛的目录搜索。
- 将 chat id、thread id、JID、handle 和 room id 等提供商原生 id 保留在 `target`
值或提供商特定参数中，而不是放入通用 SDK 字段。
## 配置驱动的目录
## 配置支撑的目录
从配置派生目录条目的插件应将该逻辑保留在插件中，并复用
`openclaw/plugin-sdk/directory-runtime` 中的共享辅助工具。
当渠道需要由配置驱动的对等方/群组时使用此方式，例如：
当渠道需要配置支撑的 peer/group 时使用此方式，例如：
- allowlist 驱动的私信对等方
- 已配置的渠道/群组映射
- 账号作用域的静态目录回退
- allowlist 驱动的私信 peer
- 已配置的渠道/group 映射
- 账号范围内的静态目录回退
`directory-runtime` 中的共享辅助工具只处理通用操作：
- 查询过滤
- 限制应用
- 去重/归一化辅助工具
- limit 应用
- 去重/规范化辅助工具
- 构建 `ChannelDirectoryEntry[]`
渠道特定的账号检查和 ID 归一化应保留在插件实现中。
渠道特定的账号检查和 id 规范化应留在插件实现中。
## 提供商目录
## 提供商 catalog
提供商插件可以使用 `registerProvider({ catalog: { run(...) { ... } } })`
定义用于推理的模型目录。
提供商插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })`
定义用于推理的模型 catalog。
`catalog.run(...)` 返回的形状与 OpenClaw 写入 `models.providers` 的形状相同：
- `{ provider }` 表示一个提供商条目
- `{ providers }` 表示多个提供商条目
- `{ provider }` 用于一个提供商条目
- `{ providers }` 用于多个提供商条目
当插件拥有提供商特定的模型 ID、基础 URL 默认值，或需要认证控制的模型元数据时，请使用 `catalog`。
当插件拥有提供商特定的模型 id、base URL 默认值或受 auth 限制的模型元数据时，
请使用 `catalog`。
`catalog.order` 控制插件目录相对于 OpenClaw 内置隐式提供商的合并时机：
`catalog.order` 控制插件 catalog 相对于 OpenClaw 内置隐式提供商的合并时机：
- `simple`：普通 API key 或环境驱动的提供商
- `profile`：存在认证配置文件时出现的提供商
- `simple`：普通 API key 或环境变量驱动的提供商
- `profile`：当 auth profile 存在时出现的提供商
- `paired`：合成多个相关提供商条目的提供商
- `late`：最后一轮，在其他隐式提供商之后
后面的提供商会在键冲突时胜出，因此插件可以有意使用相同的提供商 ID 覆盖内置提供商条目。
后面的提供商在键冲突时胜出，因此插件可以有意使用相同的提供商 id 覆盖内置
提供商条目。
兼容性：
- `discovery` 仍作为旧版别名可用
- `discovery` 仍可作为旧版别名使用
- 如果同时注册了 `catalog` 和 `discovery`，OpenClaw 会使用 `catalog`
## 只读渠道检查
如果你的插件注册了渠道，请优先在 `resolveAccount(...)` 旁实现
`plugin.config.inspectAccount(cfg, accountId)`。
如果你的插件注册了渠道，请优先同时实现
`plugin.config.inspectAccount(cfg, accountId)` 和 `resolveAccount(...)`。
原因：
- `resolveAccount(...)` 是运行时路径。它可以假设凭证已完全具体化，并且在缺少必要密钥时快速失败。
- `openclaw status`、`openclaw status --all`、`openclaw channels status`、`openclaw channels resolve` 以及 Doctor/配置修复流程等只读命令路径，不应仅为了描述配置而需要具体化运行时凭证。
- `resolveAccount(...)` 是运行时路径。它可以假设凭据已完全实体化，并且在缺少必需
secret 时快速失败。
- `openclaw status`、`openclaw status --all`、`openclaw channels status`、
`openclaw channels resolve` 以及 Doctor/配置修复流程等只读命令路径，不应仅仅为了
描述配置就需要实体化运行时凭据。
推荐的 `inspectAccount(...)` 行为：
- 只返回描述性的账号状态。
- 保留 `enabled` 和 `configured`。
- 在相关时包含凭证来源/状态字段，例如：
- 在相关时包含凭据来源/状态字段，例如：
- `tokenSource`、`tokenStatus`
- `botTokenSource`、`botTokenStatus`
- `appTokenSource`、`appTokenStatus`
- `signingSecretSource`、`signingSecretStatus`
- 你不需要仅为了报告只读可用性而返回原始令牌值。返回 `tokenStatus: "available"`（以及匹配的来源字段）就足以支持状态类命令。
- 当凭证通过 SecretRef 配置，但在当前命令路径中不可用时，使用 `configured_unavailable`。
- 你不需要仅为了报告只读可用性而返回原始 token 值。返回
`tokenStatus: "available"`（以及匹配的 source 字段）就足以供 status 风格命令使用。
- 当凭据通过 SecretRef 配置但在当前命令路径中不可用时，使用 `configured_unavailable`。
这使只读命令能够报告“已配置但在此命令路径中不可用”，而不是崩溃或误报账号未配置。
这样只读命令就可以报告“已配置但在此命令路径中不可用”，而不是崩溃或误报账号未配置。
## 包集合
## 包打包
插件目录可以包含带有 `openclaw.extensions` 的 `package.json`：
@ -674,49 +681,52 @@ barrel。核心子路径：
}
```
每个条目都会成为一个插件。如果包列出了多个扩展，插件 ID
会变成 `name/<fileBase>`。
每个条目都会成为一个插件。如果包列出多个扩展，插件 id 会变为
`name/<fileBase>`。
如果你的插件导入 npm 依赖，请在该目录中安装它们，以便
`node_modules` 可用（`npm install` / `pnpm install`）。
如果你的插件导入 npm 依赖，请在该目录中安装它们，以便 `node_modules` 可用
（`npm install` / `pnpm install`）。
安全护栏：符号链接解析后，每个 `openclaw.extensions` 条目都必须保留在插件
目录内。逃逸出包目录的条目会被拒绝。
安全护栏：符号链接解析后，每个 `openclaw.extensions` 条目都必须留在插件目录内。
逃出包目录的条目会被拒绝。
安全说明：`openclaw plugins install` 会使用项目本地的 `npm install --omit=dev --ignore-scripts`
安装插件依赖（没有生命周期脚本，运行时没有 dev 依赖），并忽略继承的全局 npm 安装设置。
请保持插件依赖树为“纯 JS/TS”，并避免需要 `postinstall` 构建的包。
安全说明：`openclaw plugins install` 会使用项目本地
`npm install --omit=dev --ignore-scripts` 安装插件依赖（无生命周期脚本，
运行时无 dev 依赖），并忽略继承的全局 npm 安装设置。保持插件依赖树为“纯 JS/TS”，
并避免需要 `postinstall` 构建的包。
可选：`openclaw.setupEntry` 可以指向轻量的仅设置模块。当 OpenClaw 需要为已禁用的渠道插件提供设置表面，
或当渠道插件已启用但仍未配置时，它会加载 `setupEntry`
而不是完整插件入口。当你的主插件入口还会连接工具、钩子或其他仅运行时代码时，
这能让启动和设置更轻量。
可选：`openclaw.setupEntry` 可以指向轻量的仅设置模块。当 OpenClaw 需要为已禁用的
渠道插件提供设置表面，或当渠道插件已启用但仍未配置时，它会加载 `setupEntry`
而不是完整插件入口。这样当你的主插件入口还会接入工具、钩子或其他仅运行时代码时，
启动和设置会更轻量。
可选：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
可以让渠道插件在 Gateway 网关预监听启动阶段选择同一个 `setupEntry` 路径，即使该渠道已经配置完成。
可以让渠道插件在 Gateway 网关监听前的启动阶段进入相同的 `setupEntry` 路径，
即使该渠道已经配置完成。
仅当 `setupEntry` 完全覆盖 Gateway 网关开始监听前必须存在的启动表面时才使用此选项。实践中，这意味着设置入口
必须注册启动所依赖的每个渠道拥有的能力，例如：
仅当 `setupEntry` 完整覆盖 Gateway 网关开始监听之前必须存在的启动表面时，
才使用此选项。实践中，这意味着设置入口必须注册启动所依赖的每个渠道自有能力，
例如：
- 渠道注册本身
- Gateway 网关开始监听前必须可用的任何 HTTP 路由
- Gateway 网关开始监听之前必须可用的任何 HTTP 路由
- 在同一时间窗口内必须存在的任何 Gateway 网关方法、工具或服务
如果你的完整入口仍拥有任何必需的启动能力，请不要启用此标志。保持插件使用默认行为，并让 OpenClaw 在启动期间加载
完整入口。
如果你的完整入口仍拥有任何必需的启动能力，请不要启用此标志。保持插件使用默认行为，
让 OpenClaw 在启动期间加载完整入口。
内置渠道也可以发布仅设置的契约表面辅助工具，供核心在完整渠道运行时加载前查询。当前的设置
提升表面是：
内置渠道还可以发布仅设置的合约表面辅助工具，供核心在完整渠道运行时加载之前查询。
当前的设置提升表面是：
- `singleAccountKeysToMove`
- `namedAccountPromotionKeys`
- `resolveSingleAccountPromotionTarget(...)`
当核心需要在不加载完整插件入口的情况下，将旧版单账户渠道配置提升到 `channels.<id>.accounts.*` 时，会使用这个接口。Matrix 是当前内置示例：当命名账户已存在时，它只会把认证/引导键移入命名提升账户，并且可以保留已配置的非规范默认账户键，而不是总是创建 `accounts.default`。
核心在需要将旧版单账号渠道配置提升到 `channels.<id>.accounts.*`，且不加载完整插件入口时，会使用这个接口面。Matrix 是当前内置示例：当命名账号已存在时，它只将认证/引导键移入命名的提升账号，并且可以保留已配置的非规范默认账号键，而不是总是创建 `accounts.default`。
这些设置补丁适配器会让内置契约接口发现保持惰性。导入时间保持轻量；提升接口只会在首次使用时加载，而不是在模块导入时重新进入内置渠道启动流程。
这些设置补丁适配器会让内置契约面发现保持惰性。导入时开销保持很低；提升接口面只会在首次使用时加载，而不是在模块导入时重新进入内置渠道启动流程。
当这些启动接口包含 Gateway 网关 RPC 方法时，请把它们放在插件专属前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并且始终解析为 `operator.admin`，即使某个插件请求更窄的作用域也是如此。
当这些启动接口面包含 Gateway 网关 RPC 方法时，请将它们保留在插件专属前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍然保留，并且始终解析为 `operator.admin`，即使插件请求了更窄的作用域。
示例：
@ -735,7 +745,7 @@ barrel。核心子路径：
### 渠道目录元数据
渠道插件可以通过 `openclaw.channel` 公布设置/设备发现元数据，并通过 `openclaw.install` 公布安装提示。这让核心目录不包含数据。
渠道插件可以通过 `openclaw.channel` 声明设置/发现元数据，并通过 `openclaw.install` 声明安装提示。这样可以让核心目录不包含数据。
示例：
@ -763,38 +773,38 @@ barrel。核心子路径：
}
```
除了最小示例以外，常用的 `openclaw.channel` 字段：
除最小示例之外，实用的 `openclaw.channel` 字段包括：
- `detailLabel`：用于更丰富目录/Status 接口的次级标签
- `detailLabel`：用于更丰富目录/Status 界面的辅助标签
- `docsLabel`：覆盖文档链接的链接文本
- `preferOver`：此目录条目应优先于的较低优先级插件/渠道 ID
- `preferOver`：此目录条目应优先于的低优先级插件/渠道 ID
- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择界面文案控制
- `markdownCapable`：将渠道标记为支持 markdown，用于出站格式化决策
- `exposure.configured`：设为 `false` 时，在已配置渠道列表界面中隐藏该渠道
- `exposure.setup`：设为 `false` 时，在交互式设置/配置选择器中隐藏该渠道
- `exposure.docs`：将渠道标记为文档导航界面的内部/私有渠道
- `showConfigured` / `showInSetup`：出于兼容性仍接受的旧别名；优先使用 `exposure`
- `quickstartAllowFrom`：让该渠道加入标准快速开始 `allowFrom` 流程
- `forceAccountBinding`：即使只有一个账户，也要求显式账户绑定
- `markdownCapable`：将渠道标记为支持 Markdown，用于出站格式决策
- `exposure.configured`：设置为 `false` 时，从已配置渠道列表界面隐藏该渠道
- `exposure.setup`：设置为 `false` 时，从交互式设置/配置选择器隐藏该渠道
- `exposure.docs`：将渠道标记为内部/私有，用于文档导航界面
- `showConfigured` / `showInSetup`：为兼容性仍接受的旧版别名；优先使用 `exposure`
- `quickstartAllowFrom`：让渠道加入标准快速开始 `allowFrom` 流程
- `forceAccountBinding`：即使只存在一个账号，也要求显式账号绑定
- `preferSessionLookupForAnnounceTarget`：解析公告目标时优先使用会话查找
OpenClaw 也可以合并**外部渠道目录**（例如 MPM 注册表导出）。把 JSON 文件放在以下任一位置：
OpenClaw 还可以合并**外部渠道目录**（例如 MPM 注册表导出）。将 JSON 文件放到以下任一位置：
- `~/.openclaw/mpm/plugins.json`
- `~/.openclaw/mpm/catalog.json`
- `~/.openclaw/plugins/catalog.json`
或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（逗号/分号/`PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧别名。
或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（用逗号/分号/`PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧版别名。
生成的渠道目录条目和提供商安装目录条目会在原始 `openclaw.install` 块旁边公开规范化的安装源事实。规范化事实会标识 npm 规格是精确版本还是浮动选择器、是否存在预期完整性元数据，以及本地源路径是否也可用。当目录/包身份已知时，如果解析出的 npm 包名偏离该身份，规范化事实会发出警告。当 `defaultChoice` 无效或指向不可用的源，以及存在 npm 完整性元数据但没有有效 npm 源时，它们也会发出警告。消费者应将 `installSource` 视为一个增量可选字段，这样手工构建的条目和目录兼容层不必合成它。这让新手引导和诊断能够解释源平面状态，而无需导入插件运行时。
生成的渠道目录条目和提供商安装目录条目会在原始 `openclaw.install` 块旁公开规范化后的安装源事实。规范化事实会标识 npm 规格是精确版本还是浮动选择器、是否存在预期完整性元数据，以及本地源路径是否也可用。当目录/包身份已知时，如果解析出的 npm 包名偏离该身份，规范化事实会发出警告。当 `defaultChoice` 无效或指向不可用来源，以及存在 npm 完整性元数据但没有有效 npm 来源时，它们也会发出警告。消费者应将 `installSource` 视为附加的可选字段，这样手写条目和目录适配层就不必合成它。这样新手引导和诊断无需导入插件运行时，就能解释源平面状态。
官方外部 npm 条目应优先使用精确的 `npmSpec` 加 `expectedIntegrity`。裸包名和 dist-tag 出于兼容性仍可使用，但它们会显示源平面警告，以便目录可以逐步转向固定版本、带完整性校验的安装，而不破坏现有插件。当新手引导从本地目录路径安装时，它会记录一个托管插件索引条目，其中 `source: "path"`，并在可能时使用工作区相对的 `sourcePath`。绝对操作加载路径仍保存在 `plugins.load.paths`；安装记录会避免把本地工作站路径重复写入长期配置。这让本地开发安装对源平面诊断保持可见，同时不会增加第二个原始文件系统路径披露界面。持久化的 `plugins/installs.json` 插件索引是安装信息的事实来源，并且可以在不加载插件运行时模块的情况下刷新。即使插件清单缺失或无效，它的 `installRecords` 映射也是持久的；它的 `plugins` 数组是可重建的清单视图。
官方外部 npm 条目应优先使用精确 `npmSpec` 加 `expectedIntegrity`。裸包名和 dist-tag 为兼容性仍可工作，但它们会显示源平面警告，以便目录逐步转向固定版本且经过完整性检查的安装，同时不破坏现有插件。当新手引导从本地目录路径安装时，会记录一个托管插件索引条目，其中包含 `source: "path"`，并在可能时包含工作区相对的 `sourcePath`。绝对运行加载路径仍保留在 `plugins.load.paths` 中；安装记录避免把本地工作站路径重复写入长期配置。这让本地开发安装对源平面诊断可见，同时不会增加第二个原始文件系统路径披露界面。持久化的 `plugins/installs.json` 插件索引是安装来源事实，并且可以在不加载插件运行时模块的情况下刷新。即使插件清单缺失或无效，其 `installRecords` 映射也是持久的；其 `plugins` 数组是可重建的清单视图。
## 上下文引擎插件
上下文引擎插件拥有用于摄取、组装和压缩的会话上下文编排。从你的插件中使用 `api.registerContextEngine(id, factory)` 注册它们，然后用 `plugins.slots.contextEngine` 选择活跃引擎。
上下文引擎插件拥有会话上下文编排，负责摄取、组装和压缩。用 `api.registerContextEngine(id, factory)` 从你的插件注册它们，然后用 `plugins.slots.contextEngine` 选择活动引擎。
当你的插件需要替换或扩展默认上下文流水线，而不是只添加记忆搜索或钩子时，请使用它。
当你的插件需要替换或扩展默认上下文管线，而不只是添加记忆搜索或钩子时，请使用此方式。
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
@ -822,9 +832,9 @@ export default function (api) {
}
```
工厂的 `ctx` 会公开可选的 `config`、`agentDir` 和 `workspaceDir` 值，用于构造时初始化。
工厂 `ctx` 会公开可选的 `config`、`agentDir` 和 `workspaceDir` 值，用于构造时初始化。
如果你的引擎**不**拥有压缩算法，请保留 `compact()` 实现并显式委托：
如果你的引擎**不**拥有压缩算法，请保留 `compact()` 实现，并显式委托它：
```ts
import {
@ -861,37 +871,37 @@ export default function (api) {
## 添加新能力
当插件需要的行为不适合当前 API 时，不要通过私有内部访问绕过插件系统。请添加缺失的能力。
当插件需要当前 API 无法容纳的行为时，不要通过私有深入访问绕过插件系统。添加缺失的能力。
推荐顺序：
1. 定义核心契约
决定核心应拥有哪些共享行为：策略、回退、配置合并、生命周期、面向渠道的语义，以及运行时辅助工具形态。
2. 添加类型化插件注册/运行时接口
使用最小可用的类型化能力接口扩展 `OpenClawPluginApi` 和/或 `api.runtime`。
决定核心应拥有哪些共享行为：策略、回退、配置合并、生命周期、面向渠道的语义，以及运行时辅助器形态。
2. 添加类型化插件注册/运行时接口面
使用最小实用的类型化能力接口面扩展 `OpenClawPluginApi` 和/或 `api.runtime`。
3. 连接核心 + 渠道/功能消费者
渠道和功能插件应通过核心使用新能力，而不是直接导入某个供应商实现。
渠道和功能插件应通过核心使用新能力，而不是直接导入供应商实现。
4. 注册供应商实现
然后供应商插件针对该能力注册其后端。
然后由供应商插件针对该能力注册它们的后端。
5. 添加契约覆盖
添加测试，让所有权和注册形态长期保持明确。
添加测试，让所有权和注册形态随时间保持明确。
这就是 OpenClaw 在保持有主见的同时，不会硬编码到某个提供商世界观的方式。请参阅[能力扩展手册](/zh-CN/plugins/architecture)，了解具体文件检查清单和完整示例。
这就是 OpenClaw 保持有主张、同时不被硬编码到某个提供商世界观中的方式。有关具体文件检查清单和完整示例，请参阅[能力扩展手册](/zh-CN/plugins/architecture)。
### 能力检查清单
添加新能力时，通常应同时触及这些接口：
添加新能力时，通常应同时触及这些接口面：
- `src/<capability>/types.ts` 中的核心契约类型
- `src/<capability>/runtime.ts` 中的核心运行器/运行时辅助工具
- `src/plugins/types.ts` 中的插件 API 注册接口
- `src/<capability>/runtime.ts` 中的核心运行器/运行时辅助器
- `src/plugins/types.ts` 中的插件 API 注册接口面
- `src/plugins/registry.ts` 中的插件注册表接线
- 当功能/渠道插件需要使用它时，`src/plugins/runtime/*` 中的插件运行时暴露
- `src/test-utils/plugin-registration.ts` 中的捕获/测试辅助工具
- `src/test-utils/plugin-registration.ts` 中的捕获/测试辅助器
- `src/plugins/contracts/registry.ts` 中的所有权/契约断言
- `docs/` 中的操作员/插件文档
如果缺少其中某个接口，通常说明该能力尚未完全集成。
如果缺少其中某个接口面，通常说明该能力尚未完全集成。
### 能力模板
@ -927,14 +937,14 @@ const clip = await api.runtime.videoGeneration.generate({
expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
```
这让规则保持简单：
这样规则保持简单：
- 核心拥有能力契约 + 编排
- 供应商插件拥有供应商实现
- 功能/渠道插件使用运行时辅助工具
- 契约测试让所有权保持明确
- 功能/渠道插件使用运行时辅助器
- 契约测试保持所有权明确
## 相关
## 相关内容
- [插件架构](/zh-CN/plugins/architecture) — 公共能力模型和形态
- [插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)

503
docs/zh-CN/plugins/sdk-migration.md
View File

@ -1,84 +1,84 @@
---
read_when:
- 你看到 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 警告
- 你看到了 OPENCLAW_EXTENSION_API_DEPRECATED 警告
- 你在 OpenClaw 2026.4.25 之前使用过 api.registerEmbeddedExtensionFactory
- 你会看到 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 警告
- 你看到 OPENCLAW_EXTENSION_API_DEPRECATED 警告
- 你在 OpenClaw 2026.4.25 之前使用了 api.registerEmbeddedExtensionFactory
- 你正在将插件更新到现代插件架构
- 你维护一个外部 OpenClaw 插件
sidebarTitle: Migrate to SDK
summary: 从旧版向后兼容层迁移到现代插件 SDK
title: 插件 SDK 迁移
x-i18n:
generated_at: "2026-04-28T20:08:50Z"
generated_at: "2026-04-29T04:06:21Z"
model: gpt-5.5
provider: openai
source_hash: efaf0f397e7b06a67fd324f1710ac62529dd2c039d483b381a8df5495716cd51
source_hash: e9988b83466fa2c38511e2ca6eefa85108266b0d929e223ed5849921b956ac80
source_path: plugins/sdk-migration.md
workflow: 16
---
OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，使用聚焦且有文档说明的导入。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。
OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，使用更聚焦且有文档说明的导入。如果你的插件是在新架构之前构建的，本指南会帮助你迁移。
## 正在变化的内容
## 变化内容
旧插件系统提供了两个开放范围很大的表面，允许插件从单一入口点导入所需的任何内容：
旧插件系统提供了两个完全开放的入口，让插件可以从单个入口点导入所需的一切：
- **`openclaw/plugin-sdk/compat`** — 一个会重新导出数十个辅助函数的单一导入。它的引入是为了在新的插件架构构建期间，保持较旧的基于钩子的插件可用。
- **`openclaw/plugin-sdk/infra-runtime`** — 一个宽泛的运行时辅助 barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助函数、文件辅助函数、审批类型和无关工具。
- **`openclaw/plugin-sdk/config-runtime`** — 一个宽泛的配置兼容性 barrel，在迁移窗口期间仍携带已弃用的直接加载/写入辅助函数。
- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问主机侧辅助函数，例如嵌入式智能体 runner。
- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除的仅限 Pi 的内置扩展钩子，可观察嵌入式 runner 事件，例如 `tool_result`。
- **`openclaw/plugin-sdk/compat`** — 单个导入，会重新导出数十个辅助工具。它的引入是为了在新的插件架构构建期间，让较旧的基于钩子的插件继续工作。
- **`openclaw/plugin-sdk/infra-runtime`** — 一个宽泛的运行时辅助 barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助工具、文件辅助工具、审批类型和无关工具。
- **`openclaw/plugin-sdk/config-runtime`** — 一个宽泛的配置兼容 barrel，在迁移窗口期间仍然携带已弃用的直接加载/写入辅助工具。
- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问宿主端辅助工具，例如嵌入式智能体运行器。
- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除的仅 Pi 内置插件钩子，可观察嵌入式运行器事件，例如 `tool_result`。
这些宽泛的导入表面现在已**弃用**。它们在运行时仍可工作，但新插件不得使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已移除；请改用工具结果中间件。
这些宽泛的导入入口现在已**弃用**。它们在运行时仍然可用，但新插件不得使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。仅 Pi 的嵌入式插件工厂注册 API 已被移除；请改用工具结果中间件。
OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有文档说明的插件行为。破坏性契约变更必须先经过兼容性适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、manifest 字段、设置 API、钩子和运行时注册行为。
OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已文档化的插件行为。破坏性契约变更必须先经过兼容适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、清单字段、设置 API、钩子和运行时注册行为。
<Warning>
向后兼容层将在未来的主要版本中移除。届时仍从这些表面导入的插件将会中断。仅限 Pi 的嵌入式扩展工厂注册现在已经不再加载。
向后兼容层将在未来的主版本中移除。仍从这些入口导入的插件届时会中断。仅 Pi 的嵌入式插件工厂注册已经不再加载。
</Warning>
## 为什么做出此变更
旧方法带来了问题：
旧方法会导致一些问题：
- **启动缓慢** — 导入一个辅助函数会加载数十个无关模块
- **循环依赖** — 宽泛的重新导出很容易造成导入环
- **API 表面不清晰** — 无法判断哪些导出是稳定的，哪些是内部的
- **启动缓慢** — 导入一个辅助工具会加载数十个无关模块
- **循环依赖** — 宽泛的重新导出很容易造成导入循环
- **API 边界不清晰** — 无法判断哪些导出是稳定的，哪些是内部的
现代插件 SDK 修复了这一点：每个导入路径（`openclaw/plugin-sdk/\<subpath\>`）都是一个小型、自包含模块，具有明确用途和有文档说明的契约。
现代插件 SDK 修复了这一点：每个导入路径（`openclaw/plugin-sdk/\<subpath\>`）都是一个小型、自包含模块，具有明确用途和文档化契约。
内置渠道的旧提供商便利接缝也已移除。带渠道品牌的辅助接缝是私有 mono-repo 快捷方式，不是稳定的插件契约。请改用狭窄的通用 SDK 子路径。在内置插件工作区内，将提供商拥有的辅助函数保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。
面向内置渠道的旧版提供商便捷接缝也已移除。带渠道品牌的辅助接缝是私有 monorepo 快捷方式，不是稳定的插件契约。请改用窄范围的通用 SDK 子路径。在内置插件工作区内，将提供商拥有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。
当前内置提供商示例：
- Anthropic 将 Claude 专用流辅助函数保留在自己的 `api.ts` / `contract-api.ts` 接缝中
- OpenAI 将提供商 builder、默认模型辅助函数和实时提供商 builder 保留在自己的 `api.ts` 中
- OpenRouter 将提供商 builder 和新手引导/配置辅助函数保留在自己的 `api.ts` 中
- Anthropic 将 Claude 专用流辅助工具保留在自己的 `api.ts` / `contract-api.ts` 接缝中
- OpenAI 将提供商构建器、默认模型辅助工具和实时提供商构建器保留在自己的 `api.ts` 中
- OpenRouter 将提供商构建器和新手引导/配置辅助工具保留在自己的 `api.ts` 中
## 兼容性策略
对于外部插件，兼容性工作遵循以下顺序：
对于外部插件，兼容性工作按以下顺序进行：
1. 添加新契约
2. 通过兼容性适配器保持旧行为连通
3. 发出诊断或警告，指明旧路径和替代方案
4. 在测试中覆盖两个路径
5. 记录弃用和迁移路径
6. 仅在已公告的迁移窗口之后移除，通常是在主要版本中
2. 通过兼容适配器继续连接旧行为
3. 发出诊断或警告，指出旧路径和替代方案
4. 在测试中覆盖两条路径
5. 记录弃用说明和迁移路径
6. 仅在已公告的迁移窗口之后移除，通常是在主版本发布中
维护者可以使用 `pnpm plugins:boundary-report` 审计当前迁移队列。使用 `pnpm plugins:boundary-report:summary` 获取紧凑计数，使用 `--owner <id>` 查看单个插件或兼容性 owner，并在 CI gate 应因到期兼容性记录、跨 owner 保留 SDK 导入或未使用的保留 SDK 子路径而失败时使用 `pnpm plugins:boundary-report:ci`。该报告会按移除日期对已弃用的兼容性记录分组，统计本地代码/文档引用，显示跨 owner 保留 SDK 导入，并汇总私有 memory-host SDK 桥接，使兼容性清理保持显式，而不是依赖临时搜索。保留 SDK 子路径必须有已跟踪的 owner 使用；未使用的保留辅助导出应从公共 SDK 中移除。
维护者可以使用 `pnpm plugins:boundary-report` 审计当前迁移队列。使用 `pnpm plugins:boundary-report:summary` 获取紧凑计数，使用 `--owner <id>` 查看单个插件或兼容性所有者，在 CI 门禁需要因到期兼容记录、跨所有者保留 SDK 导入或未使用的保留 SDK 子路径而失败时使用 `pnpm plugins:boundary-report:ci`。该报告会按移除日期对已弃用的兼容性记录分组，统计本地代码/文档引用，暴露跨所有者保留 SDK 导入，并汇总私有 memory-host SDK 桥接，使兼容性清理保持显式，而不是依赖临时搜索。保留 SDK 子路径必须有已跟踪的所有者使用情况；未使用的保留辅助导出应从公共 SDK 中移除。
如果某个 manifest 字段仍被接受，插件作者可以继续使用它，直到文档和诊断另有说明。新代码应优先使用有文档说明的替代方案，但现有插件不应在普通次要版本发布期间中断。
如果某个清单字段仍被接受，插件作者可以继续使用它，直到文档和诊断另有说明。新代码应优先使用文档化的替代方案，但现有插件不应在普通次版本发布期间中断。
## 如何迁移
<Steps>
<Step title="Migrate runtime config load/write helpers">
<Step title="迁移运行时配置加载/写入辅助工具">
内置插件应停止直接调用
`api.runtime.config.loadConfig()` 和
`api.runtime.config.writeConfigFile(...)`。优先使用已传入当前活动调用路径的配置。需要当前进程快照的长生命周期处理器可以使用 `api.runtime.config.current()`。长生命周期智能体工具应在 `execute` 内使用工具上下文的 `ctx.getRuntimeConfig()`，这样在配置写入前创建的工具仍能看到刷新的运行时配置。
`api.runtime.config.writeConfigFile(...)`。优先使用已经传入当前活动调用路径的配置。需要当前进程快照的长生命周期处理程序可以使用 `api.runtime.config.current()`。长生命周期智能体工具应在 `execute` 内使用工具上下文的 `ctx.getRuntimeConfig()`，这样在配置写入之前创建的工具仍然可以看到刷新的运行时配置。
配置写入必须通过事务辅助函数，并选择写入后策略：
配置写入必须通过事务性辅助工具，并选择写入后策略：
```typescript
await api.runtime.config.mutateConfigFile({
@ -89,12 +89,9 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
});
```
当调用方知道变更需要一次干净的 Gateway 网关重启时，使用 `afterWrite: { mode: "restart", reason: "..." }`；只有当调用方拥有后续处理并有意抑制 reload planner 时，才使用 `afterWrite: { mode: "none", reason: "..." }`。变更结果包含一个带类型的 `followUp` 摘要，用于测试和日志；Gateway 网关仍负责应用或调度重启。`loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为外部插件的已弃用兼容性辅助函数保留，并会以 `runtime-config-load-write` 兼容性代码警告一次。内置插件和仓库运行时代码受到
`pnpm check:deprecated-internal-config-api` 和
`pnpm check:no-runtime-action-load-config` 中扫描器 guardrail 的保护：新的生产插件用法会直接失败，直接配置写入会失败，Gateway 网关服务器方法必须使用请求运行时快照，运行时渠道发送/action/client 辅助函数必须从其边界接收配置，并且长生命周期运行时模块允许的环境级 `loadConfig()` 调用数为零。
当调用方知道变更需要干净地重启 Gateway 网关时，使用 `afterWrite: { mode: "restart", reason: "..." }`；只有当调用方拥有后续处理并有意抑制重载规划器时，才使用 `afterWrite: { mode: "none", reason: "..." }`。变更结果包含用于测试和日志记录的类型化 `followUp` 摘要；Gateway 网关仍负责应用或安排重启。`loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为面向外部插件的已弃用兼容辅助工具保留，并会使用 `runtime-config-load-write` 兼容代码警告一次。内置插件和仓库运行时代码受扫描器护栏保护，相关命令为 `pnpm check:deprecated-internal-config-api` 和 `pnpm check:no-runtime-action-load-config`：新的生产插件用法会直接失败，直接配置写入会失败，Gateway 网关服务器方法必须使用请求运行时快照，运行时渠道发送/操作/客户端辅助工具必须从其边界接收配置，长生命周期运行时模块允许的环境 `loadConfig()` 调用数为零。
新插件代码还应避免导入宽泛的
`openclaw/plugin-sdk/config-runtime` 兼容性 barrel。请使用与任务匹配的狭窄 SDK 子路径：
新插件代码还应避免导入宽泛的 `openclaw/plugin-sdk/config-runtime` 兼容 barrel。请使用与任务匹配的窄范围 SDK 子路径：
| 需求 | 导入 |
| --- | --- |
@ -102,19 +99,19 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
| 已加载配置断言和插件入口配置查找 | `openclaw/plugin-sdk/plugin-config-runtime` |
| 当前运行时快照读取 | `openclaw/plugin-sdk/runtime-config-snapshot` |
| 配置写入 | `openclaw/plugin-sdk/config-mutation` |
| 会话存储辅助函数 | `openclaw/plugin-sdk/session-store-runtime` |
| 会话存储辅助工具 | `openclaw/plugin-sdk/session-store-runtime` |
| Markdown 表格配置 | `openclaw/plugin-sdk/markdown-table-runtime` |
| 组策略运行时辅助函数 | `openclaw/plugin-sdk/runtime-group-policy` |
| Secret 输入解析 | `openclaw/plugin-sdk/secret-input-runtime` |
| 组策略运行时辅助工具 | `openclaw/plugin-sdk/runtime-group-policy` |
| 密钥输入解析 | `openclaw/plugin-sdk/secret-input-runtime` |
| 模型/会话覆盖 | `openclaw/plugin-sdk/model-session-runtime` |
内置插件及其测试会通过扫描器防护避免使用宽泛 barrel，确保导入和 mock 保持在所需行为的本地范围内。宽泛 barrel 仍为外部兼容性存在，但新代码不应依赖它。
内置插件及其测试会被扫描器防护，禁止使用该宽泛 barrel，因此导入和 mock 会保持局部化，只覆盖所需行为。该宽泛 barrel 仍为外部兼容性而存在，但新代码不应依赖它。
</Step>
<Step title="Migrate Pi tool-result extensions to middleware">
内置插件必须将仅限 Pi 的
`api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为运行时中立的中间件。
<Step title="将 Pi 工具结果插件迁移到中间件">
内置插件必须将仅 Pi 的
`api.registerEmbeddedExtensionFactory(...)` 工具结果处理程序替换为运行时中立的中间件。
```typescript
// Pi and Codex runtime dynamic tools
@ -125,7 +122,7 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
});
```
同时更新插件 manifest：
同时更新插件清单：
```json
{
@ -135,31 +132,29 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
}
```
外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前重写它。
外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前改写它。
</Step>
<Step title="Migrate approval-native handlers to capability facts">
支持审批的渠道插件现在通过 `approvalCapability.nativeRuntime` 加共享运行时上下文注册表来暴露原生审批行为。
<Step title="将审批原生处理程序迁移到能力事实">
支持审批的渠道插件现在通过 `approvalCapability.nativeRuntime` 加上共享运行时上下文注册表暴露原生审批行为。
关键变更：
- 将 `approvalCapability.handler.loadRuntime(...)` 替换为
`approvalCapability.nativeRuntime`
- 将审批专用 auth/delivery 从旧版 `plugin.auth` /
`plugin.approvals` 接线迁移到 `approvalCapability`
- `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；将 delivery/native/render 字段迁移到 `approvalCapability`
- `plugin.auth` 仅保留用于渠道登录/登出流程；core 不再读取其中的审批 auth 钩子
- 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道拥有的运行时对象，例如 client、token 或 Bolt app
- 不要从原生审批处理器发送插件拥有的 reroute 通知；core 现在根据实际投递结果拥有 routed-elsewhere 通知
- 将 `channelRuntime` 传入 `createChannelManager(...)` 时，提供真实的 `createPluginRuntime().channel` 表面。部分 stub 会被拒绝。
- 将 `approvalCapability.handler.loadRuntime(...)` 替换为 `approvalCapability.nativeRuntime`
- 将审批专用身份验证/投递从旧版 `plugin.auth` / `plugin.approvals` 接线迁移到 `approvalCapability`
- `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；将投递/原生/render 字段迁移到 `approvalCapability`
- `plugin.auth` 仅保留用于渠道登录/登出流程；core 不再读取其中的审批身份验证钩子
- 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道拥有的运行时对象，例如客户端、令牌或 Bolt 应用
- 不要从原生审批处理程序发送插件拥有的重路由通知；core 现在基于实际投递结果拥有 routed-elsewhere 通知
- 将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 表面。部分 stub 会被拒绝。
请参阅 `/plugins/sdk-channel-plugins` 了解当前审批能力布局。
参见 `/plugins/sdk-channel-plugins` 了解当前审批能力布局。
</Step>
<Step title="Audit Windows wrapper fallback behavior">
如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，未解析的 Windows `.cmd`/`.bat` wrapper 现在会 fail closed，除非你显式传入 `allowShellFallback: true`。
<Step title="审计 Windows 包装器回退行为">
如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，未解析的 Windows `.cmd`/`.bat` 包装器现在会默认失败关闭，除非你显式传入 `allowShellFallback: true`。
```typescript
// Before
@ -174,12 +169,12 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
});
```
如果你的调用方并非有意依赖 shell fallback，不要设置 `allowShellFallback`，而应处理抛出的错误。
如果你的调用方并非有意依赖 shell 回退，请不要设置 `allowShellFallback`，而是处理抛出的错误。
</Step>
<Step title="Find deprecated imports">
在你的插件中搜索来自任一已弃用表面的导入：
<Step title="查找已弃用的导入">
在你的插件中搜索来自任一已弃用入口的导入：
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -190,8 +185,8 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
</Step>
<Step title="Replace with focused imports">
旧表面中的每个导出都映射到一个特定的现代导入路径：
<Step title="替换为聚焦导入">
旧入口中的每个导出都映射到一个具体的现代导入路径：
```typescript
// Before (deprecated backwards-compatibility layer)
@ -207,7 +202,7 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```
对于主机侧辅助函数，请使用注入的插件运行时，而不是直接导入：
对于宿主端辅助工具，请使用注入的插件运行时，而不是直接导入：
```typescript
// Before (deprecated extension-api bridge)
@ -218,9 +213,9 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
同一模式也适用于其他旧版桥接辅助函数：
同样的模式也适用于其他旧版桥接辅助函数：
| 旧导入 | 现代等价项 |
| 旧导入 | 现代等效项 |
| --- | --- |
| `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` |
| `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |
@ -233,17 +228,17 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
</Step>
<Step title="替换宽泛的 infra-runtime 导入">
`openclaw/plugin-sdk/infra-runtime` 仍为外部兼容性而存在，但新代码应导入它实际需要的聚焦辅助接口：
`openclaw/plugin-sdk/infra-runtime` 仍然存在，用于外部兼容性，但新代码应导入它实际需要的聚焦辅助函数表面：
| 需求 | 导入 |
| --- | --- |
| 系统事件队列辅助函数 | `openclaw/plugin-sdk/system-event-runtime` |
| 心跳事件和可见性辅助函数 | `openclaw/plugin-sdk/heartbeat-runtime` |
| 待处理投递队列排空 | `openclaw/plugin-sdk/delivery-queue-runtime` |
| 待处理投递队列清空 | `openclaw/plugin-sdk/delivery-queue-runtime` |
| 渠道活动遥测 | `openclaw/plugin-sdk/channel-activity-runtime` |
| 内存中去重缓存 | `openclaw/plugin-sdk/dedupe-runtime` |
| 内存去重缓存 | `openclaw/plugin-sdk/dedupe-runtime` |
| 安全的本地文件/媒体路径辅助函数 | `openclaw/plugin-sdk/file-access-runtime` |
| 感知调度器的 fetch | `openclaw/plugin-sdk/runtime-fetch` |
| 支持调度器感知的 fetch | `openclaw/plugin-sdk/runtime-fetch` |
| 代理和受保护的 fetch 辅助函数 | `openclaw/plugin-sdk/fetch-runtime` |
| SSRF 调度器策略类型 | `openclaw/plugin-sdk/ssrf-dispatcher` |
| 审批请求/解析类型 | `openclaw/plugin-sdk/approval-runtime` |
@ -256,12 +251,12 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
| 进程本地异步锁 | `openclaw/plugin-sdk/async-lock-runtime` |
| 文件锁 | `openclaw/plugin-sdk/file-lock` |
内置插件会通过扫描器防止使用 `infra-runtime`，因此仓库代码无法退回到宽泛的 barrel。
内置插件会通过扫描器防止使用 `infra-runtime`，因此仓库代码不能回退到宽泛的 barrel。
</Step>
<Step title="迁移渠道路由辅助函数">
新的渠道路由代码应使用 `openclaw/plugin-sdk/channel-route`。较旧的 route-key 和 comparable-target 名称在迁移窗口期间仍作为兼容性别名保留，但新插件应使用直接描述行为的路由名称：
新的渠道路由代码应使用 `openclaw/plugin-sdk/channel-route`。较旧的路由键和可比较目标名称在迁移窗口期间仍作为兼容别名保留，但新插件应使用能直接描述行为的路由名称：
| 旧辅助函数 | 现代辅助函数 |
| --- | --- |
@ -273,11 +268,11 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
| `comparableChannelTargetsMatch(...)` | `channelRouteTargetsMatchExact(...)` |
| `comparableChannelTargetsShareRoute(...)` | `channelRouteTargetsShareConversation(...)` |
现代路由辅助函数会在原生审批、回复抑制、入站去重、cron 投递和会话路由中一致地规范化 `{ channel, to, accountId, threadId }`。如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)` 将该解析器适配到相同的路由目标契约。
现代路由辅助函数会在原生审批、回复抑制、入站去重、cron 投递和会话路由中一致地规范化 `{ channel, to, accountId, threadId }`。如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)` 将该解析器适配到同一路由目标契约。
</Step>
<Step title="构建并测试">
<Step title="构建和测试">
```bash
pnpm build
pnpm test -- my-plugin/
@ -291,73 +286,73 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
| 导入路径 | 用途 | 关键导出 |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` |
| `plugin-sdk/core` | 旧版统括式重新导出，用于渠道入口定义/构建器 | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版总括再导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | 单提供商入口辅助工具 | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/provider-entry` | 单一提供商入口辅助工具 | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | 专用渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | 共享设置向导辅助工具 | 允许列表提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | 设置期间运行时辅助工具 | 导入安全的设置补丁适配器、查找备注辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托式设置代理 |
| `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 导入安全的设置补丁适配器、查找备注辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委派设置代理 |
| `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/setup-tools` | 设置工具链辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账号辅助工具 | 账号列表/配置/操作门控辅助工具 |
| `plugin-sdk/account-id` | 账号 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账号 ID 规范化 |
| `plugin-sdk/account-resolution` | 账号查找辅助工具 | 账号查找 + 默认回退辅助工具 |
| `plugin-sdk/account-helpers` | 窄范围账号辅助工具 | 账号列表/账号操作辅助工具 |
| `plugin-sdk/account-helpers` | 窄作用域账号辅助工具 | 账号列表/账号操作辅助工具 |
| `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | 回复前缀、输入中状态和来源投递接线 | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` |
| `plugin-sdk/channel-pairing` | 私信 配对原语 | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | 回复前缀、输入状态和来源投递接线 | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` |
| `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 仅共享渠道配置 schema 原语和通用构建器 |
| `plugin-sdk/bundled-channel-config-schema` | 内置配置 schema | 仅限 OpenClaw 维护的内置插件；新插件必须定义插件本地 schema |
| `plugin-sdk/bundled-channel-config-schema` | 内置配置 schema | 仅 OpenClaw 维护的内置插件；新插件必须定义插件本地 schema |
| `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置 schema | 仅兼容性别名；对维护中的内置插件使用 `plugin-sdk/bundled-channel-config-schema` |
| `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名称规范化、描述裁剪、重复/冲突验证 |
| `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` |
| `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复/冲突校验 |
| `plugin-sdk/channel-policy` | 群组/私信 策略解析 | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | 账号状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览终结辅助工具 |
| `plugin-sdk/inbound-envelope` | 入站信封辅助工具 | 共享路由 + 信封构建器辅助工具 |
| `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 |
| `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 |
| `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 |
| `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 无需导入完整出站运行时的轻量级 `resolveOutboundSendDep` 查找 |
| `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 不导入完整出站运行时的轻量级 `resolveOutboundSendDep` 查找 |
| `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、身份/发送委托、会话、格式化和载荷规划辅助工具 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 |
| `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助工具 | 适用于旧版字段布局的 Agent 媒体载荷构建器 |
| `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时实用工具 |
| `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助工具 | 用于旧版字段布局的智能体媒体载荷构建器 |
| `plugin-sdk/channel-runtime` | 已弃用的兼容性垫片 | 仅旧版渠道运行时工具 |
| `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 |
| `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | 广范围运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | 日志记录器/运行时环境、超时、重试和退避辅助工具 |
| `plugin-sdk/runtime` | 宽作用域运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 窄作用域运行时环境辅助工具 | 日志记录器/运行时环境、超时、重试和退避辅助工具 |
| `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/钩子/http/交互式辅助工具 |
| `plugin-sdk/hook-runtime` | 钩子流水线辅助工具 | 共享 webhook/内部钩子流水线辅助工具 |
| `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 |
| `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 |
| `plugin-sdk/config-runtime` | 已弃用的配置兼容性 shim | 优先使用 `config-types`, `plugin-config-runtime`, `runtime-config-snapshot` 和 `config-mutation` |
| `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 合同表面不可用时，提供回退稳定的 Telegram 命令验证辅助工具 |
| `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批载荷、审批能力/配置文件辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 |
| `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批者解析、同一聊天操作认证 |
| `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件/过滤器辅助工具 |
| `plugin-sdk/config-runtime` | 已弃用的配置兼容性垫片 | 优先使用 `config-types`, `plugin-config-runtime`, `runtime-config-snapshot` 和 `config-mutation` |
| `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 合同表面不可用时，提供回退稳定的 Telegram 命令校验辅助工具 |
| `plugin-sdk/approval-runtime` | 审批提示辅助工具 | Exec/插件审批载荷、审批能力/配置档辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 |
| `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同聊天操作认证 |
| `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置档/过滤器辅助工具 |
| `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力/投递适配器 |
| `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 |
| `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向热门渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 审批处理程序辅助工具 | 更广范围的审批处理程序运行时辅助工具；当更窄的适配器/Gateway 网关衔接已足够时，优先使用它们 |
| `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 用于热渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽作用域的审批处理器运行时辅助工具；当更窄的适配器/Gateway 网关接缝足够时，优先使用它们 |
| `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账号绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复载荷辅助工具 |
| `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | Exec/插件审批回复载荷辅助工具 |
| `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文注册/获取/监听辅助工具 |
| `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和密钥收集辅助工具 |
| `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信 门控、外部内容和密钥收集辅助工具 |
| `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机允许列表和专用网络策略辅助工具 |
| `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定 dispatcher、受保护 fetch、SSRF 策略辅助工具 |
| `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定分派器、受保护 fetch、SSRF 策略辅助工具 |
| `plugin-sdk/system-event-runtime` | 系统事件辅助工具 | `enqueueSystemEvent`, `peekSystemEventEntries` |
| `plugin-sdk/heartbeat-runtime` | 心跳辅助工具 | 心跳事件和可见性辅助工具 |
| `plugin-sdk/delivery-queue-runtime` | 投递队列辅助工具 | `drainPendingDeliveries` |
| `plugin-sdk/channel-activity-runtime` | 渠道活动辅助工具 | `recordChannelActivity` |
| `plugin-sdk/dedupe-runtime` | 去重辅助工具 | 内存中去重缓存 |
| `plugin-sdk/dedupe-runtime` | 去重辅助工具 | 内存内去重缓存 |
| `plugin-sdk/file-access-runtime` | 文件访问辅助工具 | 安全本地文件/媒体路径辅助工具 |
| `plugin-sdk/transport-ready-runtime` | 传输就绪辅助工具 | `waitForTransportReady` |
| `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 |
| `plugin-sdk/fetch-runtime` | 包装 fetch/代理辅助工具 | `resolveFetch`、代理辅助工具 |
| `plugin-sdk/fetch-runtime` | 包装的 fetch/代理辅助工具 | `resolveFetch`、代理辅助工具 |
| `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 |
| `plugin-sdk/allow-from` | 允许列表格式化 | `formatAllowFromLowercase` |
@ -365,10 +360,10 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
| `plugin-sdk/command-auth` | 命令门控和命令表面辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具，包括动态参数菜单格式化 |
| `plugin-sdk/command-status` | 命令状态/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 |
| `plugin-sdk/webhook-ingress` | Webhook 请求辅助工具 | Webhook 目标实用工具 |
| `plugin-sdk/webhook-ingress` | Webhook 请求辅助工具 | Webhook 目标工具 |
| `plugin-sdk/webhook-request-guards` | Webhook 正文保护辅助工具 | 请求正文读取/限制辅助工具 |
| `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 |
| `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | 终结、提供商分发和对话标签辅助工具 |
| `plugin-sdk/reply-dispatch-runtime` | 窄作用域回复分发辅助工具 | 终结、提供商分发和对话标签辅助工具 |
| `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/markdown 分块辅助工具 |
@ -377,118 +372,118 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
| `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 |
| `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道/账号状态摘要构建器、运行时状态默认值、问题元数据辅助工具 |
| `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 |
| `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug/字符串规范化辅助工具 |
| `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类似请求的输入中提取字符串 URL |
| `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | Slug/字符串规范化辅助工具 |
| `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类请求输入提取字符串 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` | 日志记录辅助函数 | 子系统日志记录器和修订辅助函数 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助函数 | Markdown 表格模式辅助函数 |
| `plugin-sdk/tool-payload` | 工具载荷提取 | 从工具结果对象提取规范化载荷 |
| `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数提取规范发送目标字段 |
| `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 |
| `plugin-sdk/logging-core` | 日志辅助工具 | 子系统日志器和脱敏辅助工具 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 |
| `plugin-sdk/reply-payload` | 消息回复类型 | 回复载荷类型 |
| `plugin-sdk/provider-setup` | 精选本地/自托管提供商设置辅助函数 | 自托管提供商发现/配置辅助函数 |
| `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管提供商的设置辅助函数 | 相同的自托管提供商发现/配置辅助函数 |
| `plugin-sdk/provider-auth-runtime` | 提供商运行时认证辅助函数 | 运行时 API 密钥解析辅助函数 |
| `plugin-sdk/provider-auth-api-key` | 提供商 API 密钥设置辅助函数 | API 密钥新手引导/配置文件写入辅助函数 |
| `plugin-sdk/provider-auth-result` | 提供商认证结果辅助函数 | 标准 OAuth 认证结果构建器 |
| `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助函数 | 共享交互式登录辅助函数 |
| `plugin-sdk/provider-selection-runtime` | 提供商选择辅助函数 | 已配置或自动提供商选择以及原始提供商配置合并 |
| `plugin-sdk/provider-env-vars` | 提供商环境变量辅助函数 | 提供商认证环境变量查找辅助函数 |
| `plugin-sdk/provider-model-shared` | 共享提供商模型/重放辅助函数 | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享重放策略构建器、提供商端点辅助函数以及模型 ID 规范化辅助函数 |
| `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助函数 | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`buildManifestModelProviderConfig`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助函数 |
| `plugin-sdk/provider-http` | 提供商 HTTP 辅助函数 | 通用提供商 HTTP/端点能力辅助函数，包括音频转录 multipart 表单辅助函数 |
| `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助函数 | Web-fetch 提供商注册/缓存辅助函数 |
| `plugin-sdk/provider-web-search-config-contract` | 提供商 Web 搜索配置辅助函数 | 面向不需要插件启用接线的提供商的窄 Web 搜索配置/凭证辅助函数 |
| `plugin-sdk/provider-web-search-contract` | 提供商 Web 搜索契约辅助函数 | 窄 Web 搜索配置/凭证契约辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化凭证设置器/获取器 |
| `plugin-sdk/provider-web-search` | 提供商 Web 搜索辅助函数 | Web 搜索提供商注册/缓存/运行时辅助函数 |
| `plugin-sdk/provider-tools` | 提供商工具/架构兼容辅助函数 | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini 架构清理 + 诊断，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | 提供商用量辅助函数 | `fetchClaudeUsage`、`fetchGeminiUsage`、`fetchGithubCopilotUsage` 以及其他提供商用量辅助函数 |
| `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-setup` | 精选本地/自托管提供商设置辅助工具 | 自托管提供商设备发现/配置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容自托管提供商的设置辅助工具 | 同一组自托管提供商设备发现/配置辅助工具 |
| `plugin-sdk/provider-auth-runtime` | 提供商运行时凭证辅助工具 | 运行时 API 密钥解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | 提供商 API 密钥设置辅助工具 | API 密钥新手引导/配置文件写入辅助工具 |
| `plugin-sdk/provider-auth-result` | 提供商凭证结果辅助工具 | 标准 OAuth 凭证结果构建器 |
| `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助工具 | 共享交互式登录辅助工具 |
| `plugin-sdk/provider-selection-runtime` | 提供商选择辅助工具 | 已配置或自动提供商选择和原始提供商配置合并 |
| `plugin-sdk/provider-env-vars` | 提供商环境变量辅助工具 | 提供商凭证环境变量查找辅助工具 |
| `plugin-sdk/provider-model-shared` | 共享提供商模型/重放辅助工具 | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享重放策略构建器、提供商端点辅助工具，以及模型 ID 规范化辅助工具 |
| `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助工具 | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`buildManifestModelProviderConfig`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助工具 |
| `plugin-sdk/provider-http` | 提供商 HTTP 辅助工具 | 通用提供商 HTTP/端点能力辅助工具，包括音频转录 multipart 表单辅助工具 |
| `plugin-sdk/provider-web-fetch` | 提供商网页获取辅助工具 | 网页获取提供商注册/缓存辅助工具 |
| `plugin-sdk/provider-web-search-config-contract` | 提供商 Web 搜索配置辅助工具 | 面向不需要插件启用接线的提供商的窄 Web 搜索配置/凭据辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 提供商 Web 搜索契约辅助工具 | 窄 Web 搜索配置/凭据契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及带作用域的凭据设置器/获取器 |
| `plugin-sdk/provider-web-search` | 提供商 Web 搜索辅助工具 | Web 搜索提供商注册/缓存/运行时辅助工具 |
| `plugin-sdk/provider-tools` | 提供商工具/架构兼容辅助工具 | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini 架构清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | 提供商用量辅助工具 | `fetchClaudeUsage`、`fetchGeminiUsage`、`fetchGithubCopilotUsage`，以及其他提供商用量辅助工具 |
| `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` | 提供商传输辅助工具 | 原生提供商传输辅助工具，例如受保护的获取、传输消息转换，以及可写传输事件流 |
| `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | 共享媒体辅助函数 | 媒体获取/转换/存储辅助函数以及媒体载荷构建器 |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助函数 | 用于图像/视频/音乐生成的共享故障转移辅助函数、候选选择以及缺失模型消息 |
| `plugin-sdk/media-understanding` | 媒体理解辅助函数 | 媒体理解提供商类型以及面向提供商的图像/音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本辅助函数 | 助手可见文本剥离、Markdown 渲染/分块/表格辅助函数、修订辅助函数、指令标签辅助函数、安全文本实用工具以及相关文本/日志记录辅助函数 |
| `plugin-sdk/text-chunking` | 文本分块辅助函数 | 出站文本分块辅助函数 |
| `plugin-sdk/speech` | 语音辅助函数 | 语音提供商类型以及面向提供商的指令、注册表、验证辅助函数和 OpenAI 兼容 TTS 构建器 |
| `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取/转换/存储辅助工具以及媒体载荷构建器 |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 用于图像/视频/音乐生成的共享故障转移辅助工具、候选选择和缺失模型消息 |
| `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解提供商类型，以及面向提供商的图像/音频辅助工具导出 |
| `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本的剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具、安全文本实用工具，以及相关文本/日志辅助工具 |
| `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | 语音辅助工具 | 语音提供商类型，以及面向提供商的指令、注册表、验证辅助工具和 OpenAI 兼容 TTS 构建器 |
| `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、规范化 |
| `plugin-sdk/realtime-transcription` | 实时转录辅助函数 | 提供商类型、注册表辅助函数以及共享 WebSocket 会话辅助函数 |
| `plugin-sdk/realtime-voice` | 实时语音辅助函数 | 提供商类型、注册表/解析辅助函数以及桥接会话辅助函数 |
| `plugin-sdk/image-generation` | 图像生成辅助函数 | 图像生成提供商类型以及图像资产/数据 URL 辅助函数和 OpenAI 兼容图像提供商构建器 |
| `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助函数 |
| `plugin-sdk/music-generation` | 音乐生成辅助函数 | 音乐生成提供商/请求/结果类型 |
| `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助函数、提供商查找以及模型引用解析 |
| `plugin-sdk/video-generation` | 视频生成辅助函数 | 视频生成提供商/请求/结果类型 |
| `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助函数、提供商查找以及模型引用解析 |
| `plugin-sdk/interactive-runtime` | 交互式回复辅助函数 | 交互式回复载荷规范化/缩减 |
| `plugin-sdk/channel-config-primitives` | 渠道配置基元 | 窄渠道配置架构基元 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入辅助函数 | 渠道配置写入授权辅助函数 |
| `plugin-sdk/channel-plugin-common` | 共享渠道前奏 | 共享渠道插件前奏导出 |
| `plugin-sdk/channel-status` | 渠道 Status 辅助函数 | 共享渠道 Status 快照/摘要辅助函数 |
| `plugin-sdk/allowlist-config-edit` | 允许列表配置辅助函数 | 允许列表配置编辑/读取辅助函数 |
| `plugin-sdk/group-access` | 群组访问辅助函数 | 共享群组访问决策辅助函数 |
| `plugin-sdk/direct-dm` | 直接私信辅助函数 | 共享直接私信认证/防护辅助函数 |
| `plugin-sdk/extension-shared` | 共享扩展辅助函数 | 被动渠道/Status 和环境代理辅助基元 |
| `plugin-sdk/webhook-targets` | Webhook 目标辅助函数 | Webhook 目标注册表和路由安装辅助函数 |
| `plugin-sdk/webhook-path` | Webhook 路径辅助函数 | Webhook 路径规范化辅助函数 |
| `plugin-sdk/web-media` | 共享 Web 媒体辅助函数 | 远程/本地媒体加载辅助函数 |
| `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 消费者重新导出的 `zod` |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助函数 | 内存管理器/配置/文件/CLI 辅助表面 |
| `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | 提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 |
| `plugin-sdk/realtime-voice` | 实时语音辅助工具 | 提供商类型、注册表/解析辅助工具和桥接会话辅助工具 |
| `plugin-sdk/image-generation` | 图像生成辅助工具 | 图像生成提供商类型，以及图像资产/数据 URL 辅助工具和 OpenAI 兼容图像提供商构建器 |
| `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、凭证和注册表辅助工具 |
| `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成提供商/请求/结果类型 |
| `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助工具、提供商查找和模型引用解析 |
| `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成提供商/请求/结果类型 |
| `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助工具、提供商查找和模型引用解析 |
| `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复载荷规范化/缩减 |
| `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄渠道配置架构原语 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 |
| `plugin-sdk/channel-plugin-common` | 共享渠道前置导出 | 共享渠道插件前置导出 |
| `plugin-sdk/channel-status` | 渠道 Status 辅助工具 | 共享渠道 Status 快照/摘要辅助工具 |
| `plugin-sdk/allowlist-config-edit` | 允许列表配置辅助工具 | 允许列表配置编辑/读取辅助工具 |
| `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 |
| `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信凭证/防护辅助工具 |
| `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/Status 和环境代理辅助原语 |
| `plugin-sdk/webhook-targets` | Webhook 目标辅助工具 | Webhook 目标注册表和路由安装辅助工具 |
| `plugin-sdk/webhook-path` | Webhook 路径辅助工具 | Webhook 路径规范化辅助工具 |
| `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程/本地媒体加载辅助工具 |
| `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用者重新导出的 `zod` |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | 内存管理器/配置/文件/CLI 辅助表面 |
| `plugin-sdk/memory-core-engine-runtime` | 内存引擎运行时门面 | 内存索引/搜索运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | 内存主机基础引擎 | 内存主机基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | 内存主机嵌入引擎 | 内存嵌入契约、注册表访问、本地提供商以及通用批处理/远程辅助函数；具体远程提供商位于其所属插件中 |
| `plugin-sdk/memory-core-host-engine-embeddings` | 内存主机嵌入引擎 | 内存嵌入契约、注册表访问、本地提供商，以及通用批处理/远程辅助工具；具体远程提供商位于其所属插件中 |
| `plugin-sdk/memory-core-host-engine-qmd` | 内存主机 QMD 引擎 | 内存主机 QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | 内存主机存储引擎 | 内存主机存储引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | 内存主机多模态辅助函数 | 内存主机多模态辅助函数 |
| `plugin-sdk/memory-core-host-query` | 内存主机查询辅助函数 | 内存主机查询辅助函数 |
| `plugin-sdk/memory-core-host-secret` | 内存主机密钥辅助函数 | 内存主机密钥辅助函数 |
| `plugin-sdk/memory-core-host-events` | 内存主机事件日志辅助函数 | 内存主机事件日志辅助函数 |
| `plugin-sdk/memory-core-host-status` | 内存主机 Status 辅助函数 | 内存主机 Status 辅助函数 |
| `plugin-sdk/memory-core-host-runtime-cli` | 内存主机 CLI 运行时 | 内存主机 CLI 运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-core` | 内存主机核心运行时 | 内存主机核心运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-files` | 内存主机文件/运行时辅助函数 | 内存主机文件/运行时辅助函数 |
| `plugin-sdk/memory-host-core` | 内存主机核心运行时别名 | 内存主机核心运行时辅助函数的供应商中立别名 |
| `plugin-sdk/memory-host-events` | 内存主机事件日志别名 | 内存主机事件日志辅助函数的供应商中立别名 |
| `plugin-sdk/memory-host-files` | 内存主机文件/运行时别名 | 内存主机文件/运行时辅助函数的供应商中立别名 |
| `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助函数 | 面向内存相关插件的共享托管 Markdown 辅助函数 |
| `plugin-sdk/memory-host-search` | 活跃内存搜索门面 | 延迟活跃内存搜索管理器运行时门面 |
| `plugin-sdk/memory-host-status` | 内存主机 Status 别名 | 内存主机 Status 辅助函数的供应商中立别名 |
| `plugin-sdk/testing` | 测试实用工具 | 旧版宽泛兼容 barrel；优先使用聚焦的测试子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/channel-target-testing`、`plugin-sdk/test-env` 和 `plugin-sdk/test-fixtures` |
| `plugin-sdk/memory-core-host-multimodal` | 内存主机多模态辅助工具 | 内存主机多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | 内存主机查询辅助工具 | 内存主机查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | 内存主机密钥辅助工具 | 内存主机密钥辅助工具 |
| `plugin-sdk/memory-core-host-events` | 内存主机事件日志辅助工具 | 内存主机事件日志辅助工具 |
| `plugin-sdk/memory-core-host-status` | 内存主机 Status 辅助工具 | 内存主机 Status 辅助工具 |
| `plugin-sdk/memory-core-host-runtime-cli` | 内存主机 CLI 运行时 | 内存主机 CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | 内存主机核心运行时 | 内存主机核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | 内存主机文件/运行时辅助工具 | 内存主机文件/运行时辅助工具 |
| `plugin-sdk/memory-host-core` | 内存主机核心运行时别名 | 面向供应商中立的内存主机核心运行时辅助工具别名 |
| `plugin-sdk/memory-host-events` | 内存主机事件日志别名 | 面向供应商中立的内存主机事件日志辅助工具别名 |
| `plugin-sdk/memory-host-files` | 内存主机文件/运行时别名 | 面向供应商中立的内存主机文件/运行时辅助工具别名 |
| `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助工具 | 面向内存相邻插件的共享托管 Markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 活跃内存搜索门面 | 懒加载活跃内存搜索管理器运行时门面 |
| `plugin-sdk/memory-host-status` | 内存主机 Status 别名 | 面向供应商中立的内存主机 Status 辅助工具别名 |
| `plugin-sdk/testing` | 测试实用工具 | 旧版宽兼容聚合导出；优先使用聚焦的测试子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/channel-target-testing`、`plugin-sdk/test-env` 和 `plugin-sdk/test-fixtures` |
</Accordion>
此表有意只列出常见迁移子集，而不是完整的 SDK
表面。200 多个入口点的完整列表位于
表面。200+ 个入口点的完整列表位于
`scripts/lib/plugin-sdk-entrypoints.json`。
预留的内置插件 helper 接缝已从公共 SDK
导出映射中退役，但明确记录的兼容 facade 除外，例如为已发布的
保留的内置插件辅助衔接点已从公开 SDK
导出映射中移除，明确记录的兼容外观除外，例如为已发布的
`@openclaw/discord@2026.3.13` 包保留的已弃用
`plugin-sdk/discord` shim。特定所有者的 helper 位于所属的
插件包内；共享的宿主行为应通过通用 SDK
`plugin-sdk/discord` shim。特定所有者的辅助工具位于所属
插件包内部；共享宿主行为应通过通用 SDK
契约迁移，例如 `plugin-sdk/gateway-runtime`、`plugin-sdk/security-runtime`
和 `plugin-sdk/plugin-config-runtime`。
使用与任务匹配的最窄导入。如果找不到导出，
使用与任务匹配的最窄导入。如果找不到某个导出，
请检查 `src/plugin-sdk/` 中的源代码，或询问维护者应由哪个通用契约
拥有它。
来拥有它。
## 活跃弃用项
适用于插件 SDK、提供商契约、运行时表面和清单的更窄弃用项。
每一项今天仍可使用，但会在未来的主版本中移除。每个条目下方
都会把旧 API 映射到其规范替代项。
这些更窄范围的弃用项适用于插件 SDK、提供商契约、
运行时表面和清单。每一项今天仍可使用，但会在未来的主版本中移除。
每个条目下方都会将旧 API 映射到其规范替代项。
<AccordionGroup>
<Accordion title="command-auth 帮助构建器 → command-status">
**旧 (`openclaw/plugin-sdk/command-auth`)**：`buildCommandsMessage`,
**旧（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`,
`buildCommandsMessagePaginated`, `buildHelpMessage`。
**新 (`openclaw/plugin-sdk/command-status`)**：相同签名、相同
**新（`openclaw/plugin-sdk/command-status`）**：相同签名、相同
导出，只是从更窄的子路径导入。`command-auth`
会将它们重新导出为兼容 stub。
会将它们作为兼容桩重新导出。
```typescript
// Before
@ -500,61 +495,59 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
</Accordion>
<Accordion title="提及门控 helper → resolveInboundMentionDecision">
<Accordion title="Mention gating 辅助工具 → resolveInboundMentionDecision">
**旧**：来自
`openclaw/plugin-sdk/channel-inbound` 或
`openclaw/plugin-sdk/channel-mention-gating` 的
`resolveInboundMentionRequirement({ facts, policy })` 和
`shouldDropInboundForMention(...)`。
**新**：`resolveInboundMentionDecision({ facts, policy })`，返回单个
decision 对象，而不是两次拆分调用。
**新**：`resolveInboundMentionDecision({ facts, policy })`，返回一个
单一决策对象，而不是拆成两个调用。
下游渠道插件（Slack、Discord、Matrix、MS Teams）已经切换。
</Accordion>
<Accordion title="渠道运行时 shim 和渠道 actions helper">
`openclaw/plugin-sdk/channel-runtime` 是面向较旧
渠道插件的兼容 shim。新代码不要从它导入；请使用
<Accordion title="渠道运行时 shim 和渠道 actions 辅助工具">
`openclaw/plugin-sdk/channel-runtime` 是面向旧版
渠道插件的兼容 shim。不要在新代码中导入它；使用
`openclaw/plugin-sdk/channel-runtime-context` 来注册运行时
对象。
`openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` helper
已随原始 “actions” 渠道导出一起弃用。请改为通过语义化
`presentation` 表面暴露能力，即渠道插件声明它们渲染什么
`openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助工具
会和原始的 “actions” 渠道导出一起弃用。请改为通过语义化的
`presentation` 表面暴露能力，也就是渠道插件声明它们渲染什么
（卡片、按钮、选择器），而不是它们接受哪些原始 action 名称。
</Accordion>
<Accordion title="Web 搜索提供商 tool() helper → 插件上的 createTool()">
<Accordion title="Web 搜索提供商 tool() 辅助工具 → 插件上的 createTool()">
**旧**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` 工厂。
**新**：直接在提供商插件上实现 `createTool(...)`。
OpenClaw 不再需要 SDK helper 来注册工具 wrapper。
OpenClaw 不再需要 SDK 辅助工具来注册工具包装器。
</Accordion>
<Accordion title="明文渠道信封 → BodyForAgent">
<Accordion title="纯文本渠道信封 → BodyForAgent">
**旧**：使用 `formatInboundEnvelope(...)`（以及
`ChannelMessageForAgent.channelEnvelope`）从入站渠道消息构建扁平明文提示
`ChannelMessageForAgent.channelEnvelope`）从入站渠道消息构建一个扁平的纯文本提示词
信封。
**新**：`BodyForAgent` 加结构化用户上下文块。渠道
插件将路由元数据（线程、主题、回复目标、反应）作为
类型化字段附加，而不是把它们拼接进提示字符串。
`formatAgentEnvelope(...)` helper 仍支持用于合成
面向 assistant 的信封，但入站明文信封正在
退出。
插件会把路由元数据（线程、主题、回复目标、回应）作为
类型化字段附加，而不是把它们拼接进提示词字符串。
`formatAgentEnvelope(...)` 辅助工具仍支持用于合成的
面向助手的信封，但入站纯文本信封正在逐步退出。
受影响区域：`inbound_claim`、`message_received`，以及任何对
`channelEnvelope` 文本进行后处理的自定义
渠道插件。
`channelEnvelope` 文本做后处理的自定义渠道插件。
</Accordion>
<Accordion title="提供商发现类型 → 提供商目录类型">
四个发现类型别名现在只是目录时代类型的薄 wrapper：
四个发现类型别名现在都是目录时代类型之上的薄包装：
| 旧别名 | 新类型 |
| ------------------------- | ------------------------- |
@ -563,9 +556,9 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
| `ProviderDiscoveryResult` | `ProviderCatalogResult` |
| `ProviderPluginDiscovery` | `ProviderPluginCatalog` |
另外还有旧版 `ProviderCapabilities` 静态包。提供商插件
应通过提供商运行时契约附加能力 facts，
而不是使用静态对象。
还有旧版 `ProviderCapabilities` 静态包。提供商插件
应使用明确的提供商钩子，例如 `buildReplayPolicy`、
`normalizeToolSchemas` 和 `wrapStreamFn`，而不是静态对象。
</Accordion>
@ -574,23 +567,22 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
`isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)` 和
`resolveDefaultThinkingLevel(ctx)`。
**新**：单个 `resolveThinkingProfile(ctx)`，它返回包含规范 `id`、
可选 `label` 和排序 level 列表的
`ProviderThinkingProfile`。OpenClaw 会自动按 profile
rank 降级过时的已存储值。
**新**：单个 `resolveThinkingProfile(ctx)`，它返回一个
`ProviderThinkingProfile`，其中包含规范 `id`、可选 `label` 和
排序后的级别列表。OpenClaw 会按配置档案排名自动降级过时的已存储值。
实现一个钩子，而不是三个。旧版钩子在弃用窗口期间仍可工作，
但不会与 profile 结果组合。
请实现一个钩子，而不是三个。旧版钩子会在弃用窗口期内继续工作，
但不会与配置档案结果组合。
</Accordion>
<Accordion title="外部 OAuth 提供商 fallback → contracts.externalAuthProviders">
**旧**：实现 `resolveExternalOAuthProfiles(...)`，但未在
插件清单中声明提供商。
<Accordion title="外部 OAuth 提供商回退 → contracts.externalAuthProviders">
**旧**：实现 `resolveExternalOAuthProfiles(...)`，但不在插件清单中
声明该提供商。
**新**：在插件清单中声明 `contracts.externalAuthProviders`
**并且**实现 `resolveExternalAuthProfiles(...)`。旧的 “auth
fallback” 路径会在运行时发出警告，并会被移除。
**并且**实现 `resolveExternalAuthProfiles(...)`。旧的“认证
回退”路径会在运行时发出警告，并将在之后移除。
```json
{
@ -605,12 +597,12 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
<Accordion title="提供商环境变量查找 → setup.providers[].envVars">
**旧**清单字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。
**新**：把相同的环境变量查找镜像到清单上的 `setup.providers[].envVars`。
这会把设置/Status 环境元数据整合到一个
位置，并避免仅为响应环境变量查找而启动插件运行时。
**新**：将相同的环境变量查找镜像到清单上的 `setup.providers[].envVars`。
这会把设置/Status 环境元数据合并到一个位置，并避免仅为了回答
环境变量查找而启动插件运行时。
在弃用窗口关闭前，`providerAuthEnvVars` 会继续通过兼容适配器
受支持。
`providerAuthEnvVars` 会通过兼容适配器继续受支持，
直到弃用窗口关闭。
</Accordion>
@ -620,10 +612,10 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
`api.registerMemoryFlushPlan(...)`、
`api.registerMemoryRuntime(...)`。
**新**：memory-state API 上的一次调用：
**新**：在 memory-state API 上进行一次调用：
`registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。
相同槽位，单次注册调用。增量 Memory helper
相同槽位，单次注册调用。增量 Memory 辅助工具
（`registerMemoryPromptSupplement`、`registerMemoryCorpusSupplement`、
`registerMemoryEmbeddingProvider`）不受影响。
@ -638,17 +630,16 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
| `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` |
运行时方法 `readSession` 已弃用，请改用
`getSessionMessages`。签名相同；旧方法会转调到
新方法。
`getSessionMessages`。签名相同；旧方法会转调到新方法。
</Accordion>
<Accordion title="runtime.tasks.flow → runtime.tasks.managedFlows">
**旧**：`runtime.tasks.flow`（单数）返回实时 task-flow 访问器。
**旧**：`runtime.tasks.flow`（单数）返回一个实时 task-flow 访问器。
**新**：`runtime.tasks.managedFlows` 为需要从 flow 创建、更新、取消或运行
子任务的插件保留托管 TaskFlow 变更
运行时。当插件只需要基于 DTO 的读取时，请使用 `runtime.tasks.flows`。
**新**：`runtime.tasks.managedFlows` 保留了托管 TaskFlow 变更
运行时，供需要从流程中创建、更新、取消或运行子任务的插件使用。
当插件只需要基于 DTO 的读取时，请使用 `runtime.tasks.flows`。
```typescript
// Before
@ -659,18 +650,18 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
</Accordion>
<Accordion title="嵌入式插件工厂 → 智能体工具结果中间件">
已在上方“如何迁移 → 将 Pi 工具结果插件迁移到
中间件”中涵盖。为完整性在此列出：已移除的仅 Pi
<Accordion title="嵌入式扩展工厂 → 智能体工具结果中间件">
已在上方“如何迁移 → 将 Pi 工具结果扩展迁移到
中间件”中覆盖。这里为完整性再次列出：已移除的 Pi 专用
`api.registerEmbeddedExtensionFactory(...)` 路径由
`api.registerAgentToolResultMiddleware(...)` 取代，并在
`contracts.agentToolResultMiddleware` 中提供显式运行时
`api.registerAgentToolResultMiddleware(...)` 替代，并在
`contracts.agentToolResultMiddleware` 中提供明确的运行时
列表。
</Accordion>
<Accordion title="OpenClawSchemaType 别名 → OpenClawConfig">
从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` 现在是
`OpenClawConfig` 的单行别名。优先使用规范名称。
`OpenClawConfig` 的一行别名。请优先使用规范名称。
```typescript
// Before
@ -683,10 +674,10 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有
</AccordionGroup>
<Note>
插件级弃用项（位于 `extensions/` 下的内置渠道/提供商插件内）
在它们自己的 `api.ts` 和 `runtime-api.ts`
barrel 中跟踪。它们不影响第三方插件契约，也不会在此列出。
如果你直接使用内置插件的本地 barrel，请在升级前阅读该
扩展级弃用项（位于 `extensions/` 下的内置渠道/提供商插件内部）
会在它们自己的 `api.ts` 和 `runtime-api.ts`
barrel 中跟踪。它们不会影响第三方插件契约，因此未在此处列出。
如果你直接使用某个内置插件的本地 barrel，请在升级前阅读该
barrel 中的弃用注释。
</Note>
@ -695,9 +686,9 @@ barrel 中的弃用注释。
| 时间 | 会发生什么 |
| ---------------------- | ----------------------------------------------------------------------- |
| **现在** | 已弃用表面会发出运行时警告 |
| **下一个主版本** | 已弃用表面将被移除；仍在使用它们的插件会失败 |
| **下一个主版本** | 已弃用表面将被移除；仍在使用它们的插件将失败 |
所有核心插件都已迁移。外部插件应在下一个主版本发布前迁移。
所有核心插件都已完成迁移。外部插件应在下一个主版本之前迁移。
## 临时抑制警告
@ -716,5 +707,5 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件
- [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema 参考
- [插件内部机制](/zh-CN/plugins/architecture) — 架构深度解析
- [插件清单](/zh-CN/plugins/manifest) — 清单架构参考

249
docs/zh-CN/plugins/sdk-provider-plugins.md
View File

@ -1,34 +1,35 @@
---
read_when:
- 你正在构建一个新的模型提供商插件
- 你想将与 OpenAI 兼容的代理或自定义 LLM 添加到 OpenClaw 中
- 你想将兼容 OpenAI 的代理或自定义 LLM 添加到 OpenClaw
- 你需要了解提供商身份验证、目录和运行时钩子
sidebarTitle: Provider plugins
summary: 构建 OpenClaw 模型提供商插件的分步指南
title: 构建提供商插件
x-i18n:
generated_at: "2026-04-28T01:41:58Z"
model: gpt-5.4
generated_at: "2026-04-29T04:06:10Z"
model: gpt-5.5
provider: openai
source_hash: 4f28bc56347cca1259959444e086a3c6ea1b9f00e3a7d68332add962dfcac2d3
source_hash: 1404594fe1d1e11a612f903512c1002c8f3a804dee53d4204457b534eae93381
source_path: plugins/sdk-provider-plugins.md
workflow: 15
workflow: 16
---
本指南将带你逐步构建一个提供商插件，把模型提供商（LLM）添加到 OpenClaw。完成后，你将拥有一个带有模型目录、API 密钥身份验证和动态模型解析的提供商。
本指南将介绍如何构建一个提供商插件，用于向 OpenClaw 添加模型提供商（LLM）。完成后，你将拥有一个带有模型目录、API 密钥凭证和动态模型解析的提供商。
<Info>
如果你之前还没有构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基础包结构和清单设置。
如果你之前没有构建过任何 OpenClaw 插件，请先阅读
[入门指南](/zh-CN/plugins/building-plugins)，了解基础包结构和清单设置。
</Info>
<Tip>
提供商插件会将模型添加到 OpenClaw 的常规推理循环中。如果模型必须通过原生智能体守护进程运行，并且该守护进程负责线程、压缩或工具事件，请将该提供商与一个 [agent harness](/zh-CN/plugins/sdk-agent-harness) 配合使用，而不是把守护进程协议细节放进核心中。
提供商插件会把模型添加到 OpenClaw 的常规推理循环中。如果模型必须通过拥有线程、压缩或工具事件的原生智能体守护进程运行，请将该提供商与 [agent harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心。
</Tip>
## 演练
<Steps>
<Step title="包与清单">
<Step title="Package and manifest">
<CodeGroup>
```json package.json
{
@ -86,12 +87,12 @@ x-i18n:
```
</CodeGroup>
该清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测凭证。当某个提供商变体应复用另一个提供商 id 的身份验证时，添加 `providerAuthAliases`。`modelSupport` 是可选的，它允许 OpenClaw 在运行时钩子存在之前，根据像 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你要在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必填的。
清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测凭证。当某个提供商变体应复用另一个提供商 id 的凭证时，添加 `providerAuthAliases`。`modelSupport` 是可选的，它允许 OpenClaw 在运行时钩子存在之前，根据 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你在 ClawHub 上发布该提供商，则 `package.json` 中必须包含这些 `openclaw.compat` 和 `openclaw.build` 字段。
</Step>
<Step title="注册提供商">
一个最小可用的提供商需要有 `id`、`label`、`auth` 和 `catalog`：
<Step title="Register the provider">
一个最小提供商需要 `id`、`label`、`auth` 和 `catalog`：
```typescript index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -162,8 +163,8 @@ x-i18n:
});
```
这样就是一个可工作的提供商了。用户现在可以运行
`openclaw onboard --acme-ai-api-key <key>` 并选择
这就是一个可工作的提供商。用户现在可以执行
`openclaw onboard --acme-ai-api-key <key>`，并选择
`acme-ai/acme-large` 作为他们的模型。
如果上游提供商使用的控制令牌与 OpenClaw 不同，请添加一个小型双向文本转换，而不是替换流路径：
@ -183,9 +184,10 @@ x-i18n:
});
```
`input` 会在传输之前重写最终系统提示词和文本消息内容。`output` 会在 OpenClaw 解析其自身控制标记或进行渠道投递之前，重写助手文本增量和最终文本。
`input` 会在传输前重写最终系统提示词和文本消息内容。`output` 会在 OpenClaw 解析自己的控制标记或渠道投递之前，重写助手文本增量和最终文本。
对于仅注册一个带 API 密钥身份验证的文本提供商，并附带单个基于目录的运行时的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数：
对于仅注册一个带 API 密钥凭证且由单个目录支持运行时的文本提供商的内置提供商，优先使用范围更窄的
`defineSingleProviderPluginEntry(...)` 辅助函数：
```typescript
import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
@ -225,16 +227,22 @@ x-i18n:
});
```
`buildProvider` 是 OpenClaw 能解析真实提供商身份验证时使用的实时目录路径。它可以执行提供商特定的发现逻辑。仅在需要显示离线条目且这些内容在身份验证配置完成前可安全展示时，才使用 `buildStaticProvider`；它不得要求凭证，也不得发起网络请求。OpenClaw 的 `models list --all` 显示目前仅对内置提供商插件执行静态目录，并且使用空配置、空环境变量，以及没有智能体/工作区路径的环境。
`buildProvider` 是 OpenClaw 能够解析真实提供商凭证时使用的实时目录路径。它可以执行提供商特定的设备发现。仅将 `buildStaticProvider` 用于在配置凭证前可以安全显示的离线行；它不得要求凭证，也不得发起网络请求。OpenClaw 当前的 `models list --all` 显示只会为内置提供商插件执行静态目录，并且使用空配置、空环境，且没有智能体/工作区路径。
如果你的身份验证流程还需要在新手引导期间修补 `models.providers.*`、别名以及智能体默认模型，请使用来自 `openclaw/plugin-sdk/provider-onboard` 的预设辅助函数。最精简的辅助函数包括 `createDefaultModelPresetAppliers(...)`、`createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。
如果你的凭证流程还需要在新手引导期间修补 `models.providers.*`、别名以及智能体默认模型，请使用来自
`openclaw/plugin-sdk/provider-onboard` 的预设辅助函数。范围最窄的辅助函数是
`createDefaultModelPresetAppliers(...)`、
`createDefaultModelsPresetAppliers(...)` 和
`createModelCatalogPresetAppliers(...)`。
当某个提供商的原生端点在普通 `openai-completions` 传输上支持流式 usage 块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和 `applyProviderNativeStreamingUsageCompat(...)` 会从端点能力映射中检测支持情况，因此原生的 Moonshot/DashScope 风格端点即使在插件使用自定义提供商 id 时也仍可启用。
当提供商的原生端点在常规 `openai-completions` 传输上支持流式 usage 块时，优先使用
`openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和
`applyProviderNativeStreamingUsageCompat(...)` 会从端点能力映射中检测支持，因此即使插件使用自定义提供商 id，原生 Moonshot/DashScope 风格端点仍可选择启用。
</Step>
<Step title="添加动态模型解析">
如果你的提供商接受任意模型 id（例如代理或路由器），请添加 `resolveDynamicModel`：
<Step title="Add dynamic model resolution">
如果你的提供商接受任意模型 ID（例如代理或路由器），请添加 `resolveDynamicModel`：
```typescript
api.registerProvider({
@ -255,14 +263,14 @@ x-i18n:
});
```
如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热 —— 在它完成后，`resolveDynamicModel` 会再次运行。
如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热——它完成后会再次运行 `resolveDynamicModel`。
</Step>
<Step title="按需添加运行时钩子">
大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商需求增加，再逐步添加钩子即可。
<Step title="Add runtime hooks (as needed)">
大多数提供商只需要 `catalog` + `resolveDynamicModel`。根据提供商需求逐步添加钩子。
共享辅助构建器现在已覆盖最常见的重放/工具兼容性系列，因此插件通常不需要手动逐个接线每个钩子：
共享辅助构建器现在覆盖了最常见的重放/工具兼容系列，因此插件通常不需要逐个手动接线每个钩子：
```typescript
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
@ -282,38 +290,38 @@ x-i18n:
});
```
当前可用的重放系列如下：
当前可用的重放系列：
| 系列 | 它接入的内容 | 内置示例 |
| 系列 | 接入内容 | 内置示例 |
| --- | --- | --- |
| `openai-compatible` | 用于与 OpenAI 兼容传输的共享 OpenAI 风格重放策略，包括工具调用 id 清理、助手优先顺序修正，以及传输需要时的通用 Gemini 轮次校验 | `moonshot`, `ollama`, `xai`, `zai` |
| `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知重放策略，因此 Anthropic-message 传输只有在解析出的模型实际是 Claude id 时才会获得 Claude 特定的 thinking 块清理 | `amazon-bedrock`, `anthropic-vertex` |
| `google-gemini` | 原生 Gemini 重放策略，加上引导重放清理和带标签的推理输出模式 | `google`, `google-gemini-cli` |
| `passthrough-gemini` | 针对通过与 OpenAI 兼容的代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini 重放校验或引导重写 | `openrouter`, `kilocode`, `opencode`, `opencode-go` |
| `hybrid-anthropic-openai` | 适用于在单个插件中混合 Anthropic-message 与 OpenAI 兼容模型表面的提供商的混合策略；可选的仅 Claude thinking 块丢弃仍限定在 Anthropic 一侧 | `minimax` |
| `openai-compatible` | 用于 OpenAI 兼容传输的共享 OpenAI 风格重放策略，包括工具调用 id 清理、assistant-first 排序修复，以及传输需要时的通用 Gemini 轮次校验 | `moonshot`, `ollama`, `xai`, `zai` |
| `anthropic-by-model` | 由 `modelId` 选择的 Claude 感知重放策略，因此 Anthropic 消息传输只有在解析后的模型确实是 Claude id 时，才会获得 Claude 特定的思考块清理 | `amazon-bedrock`, `anthropic-vertex` |
| `google-gemini` | 原生 Gemini 重放策略，以及引导重放清理和带标签的推理输出模式 | `google`, `google-gemini-cli` |
| `passthrough-gemini` | 适用于通过 OpenAI 兼容代理传输运行的 Gemini 模型的 Gemini 思考签名清理；不会启用原生 Gemini 重放校验或引导重写 | `openrouter`, `kilocode`, `opencode`, `opencode-go` |
| `hybrid-anthropic-openai` | 适用于在一个插件中混合 Anthropic 消息和 OpenAI 兼容模型表面的提供商的混合策略；可选的仅 Claude 思考块丢弃会保持在 Anthropic 侧范围内 | `minimax` |
当前可用的流系列：
| 系列 | 它接入的内容 | 内置示例 |
| 系列 | 接入内容 | 内置示例 |
| --- | --- | --- |
| `google-thinking` | 共享流路径上的 Gemini thinking 负载规范化 | `google`, `google-gemini-cli` |
| `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，其中 `kilo/auto` 和不支持代理推理 id 的情况会跳过注入的 thinking | `kilocode` |
| `moonshot-thinking` | 根据配置和 `/think` 级别进行 Moonshot 二进制原生 thinking 负载映射 | `moonshot` |
| `minimax-fast-mode` | 共享流路径上的 MiniMax 快速模式模型重写 | `minimax`, `minimax-portal` |
| `openai-responses-defaults` | 共享原生 OpenAI/Codex Responses 包装器：归属标头、`/fast`/`serviceTier`、文本详细程度、原生 Codex 网络搜索、推理兼容负载整形，以及 Responses 上下文管理 | `openai`, `openai-codex` |
| `openrouter-thinking` | 用于代理路由的 OpenRouter 推理包装器，集中处理不支持模型/`auto` 的跳过逻辑 | `openrouter` |
| `tool-stream-default-on` | 为像 Z.AI 这类希望默认启用工具流式传输，除非被明确禁用的提供商提供默认开启的 `tool_stream` 包装器 | `zai` |
| `google-thinking` | 共享流路径上的 Gemini thinking 载荷规范化 | `google`, `google-gemini-cli` |
| `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，带有 `kilo/auto`，且不支持的代理推理 ID 会跳过注入的 thinking | `kilocode` |
| `moonshot-thinking` | 从配置 + `/think` 级别映射 Moonshot 二进制原生 thinking 载荷 | `moonshot` |
| `minimax-fast-mode` | 共享流路径上的 MiniMax 快速模式模型改写 | `minimax`, `minimax-portal` |
| `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归因标头、`/fast`/`serviceTier`、文本详略度、原生 Codex Web 搜索、推理兼容载荷整形，以及 Responses 上下文管理 | `openai`, `openai-codex` |
| `openrouter-thinking` | 代理路由的 OpenRouter 推理包装器，集中处理不支持模型/`auto` 跳过 | `openrouter` |
| `tool-stream-default-on` | 面向 Z.AI 等提供商的默认开启 `tool_stream` 包装器，除非显式禁用，否则它们需要工具流式传输 | `zai` |
<Accordion title="为系列构建器提供支持的 SDK 接缝">
每个系列构建器都由同一包中导出的更底层公开辅助函数组合而成，当某个提供商需要偏离通用模式时，你可以使用这些辅助函数：
<Accordion title="驱动系列构建器的 SDK 接缝">
每个系列构建器都由同一包导出的较低层级公共辅助工具组成；当某个提供商需要偏离通用模式时，你可以使用这些辅助工具：
- `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`、`buildProviderReplayFamilyHooks(...)` 以及原始重放构建器（`buildOpenAICompatibleReplayPolicy`、`buildAnthropicReplayPolicyForModel`、`buildGoogleGeminiReplayPolicy`、`buildHybridAnthropicOrOpenAIReplayPolicy`）。还导出 Gemini 重放辅助函数（`sanitizeGoogleGeminiReplayHistory`、`resolveTaggedReasoningOutputMode`）以及端点/模型辅助函数（`resolveProviderEndpoint`、`normalizeProviderId`、`normalizeGooglePreviewModelId`、`normalizeNativeXaiModelId`）。
- `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`、`buildProviderStreamFamilyHooks(...)`、`composeProviderStreamWrappers(...)`，以及共享 OpenAI/Codex 包装器（`createOpenAIAttributionHeadersWrapper`、`createOpenAIFastModeWrapper`、`createOpenAIServiceTierWrapper`、`createOpenAIResponsesContextManagementWrapper`、`createCodexNativeWebSearchWrapper`）、DeepSeek V4 与 OpenAI 兼容包装器（`createDeepSeekV4OpenAICompatibleThinkingWrapper`）、Anthropic Messages thinking 预填充清理（`createAnthropicThinkingPrefillPayloadWrapper`），以及共享代理/提供商包装器（`createOpenRouterWrapper`、`createToolStreamWrapper`、`createMinimaxFastModeWrapper`）。
- `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks("gemini")`、底层 Gemini schema 辅助函数（`normalizeGeminiToolSchemas`、`inspectGeminiToolSchemas`）以及 xAI 兼容辅助函数（`resolveXaiModelCompatPatch()`、`applyXaiModelCompat(model)`）。内置的 xAI 插件通过 `normalizeResolvedModel` + `contributeResolvedModelCompat` 配合这些辅助函数，以确保 xAI 规则仍由该提供商负责。
- `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`、`buildProviderReplayFamilyHooks(...)`，以及原始重放构建器（`buildOpenAICompatibleReplayPolicy`、`buildAnthropicReplayPolicyForModel`、`buildGoogleGeminiReplayPolicy`、`buildHybridAnthropicOrOpenAIReplayPolicy`）。还导出 Gemini 重放辅助工具（`sanitizeGoogleGeminiReplayHistory`、`resolveTaggedReasoningOutputMode`）和端点/模型辅助工具（`resolveProviderEndpoint`、`normalizeProviderId`、`normalizeGooglePreviewModelId`、`normalizeNativeXaiModelId`）。
- `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`、`buildProviderStreamFamilyHooks(...)`、`composeProviderStreamWrappers(...)`，以及共享的 OpenAI/Codex 包装器（`createOpenAIAttributionHeadersWrapper`、`createOpenAIFastModeWrapper`、`createOpenAIServiceTierWrapper`、`createOpenAIResponsesContextManagementWrapper`、`createCodexNativeWebSearchWrapper`）、DeepSeek V4 OpenAI 兼容包装器（`createDeepSeekV4OpenAICompatibleThinkingWrapper`）、Anthropic Messages thinking 预填充清理（`createAnthropicThinkingPrefillPayloadWrapper`），以及共享代理/提供商包装器（`createOpenRouterWrapper`、`createToolStreamWrapper`、`createMinimaxFastModeWrapper`）。
- `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks("gemini")`、底层 Gemini schema 辅助工具（`normalizeGeminiToolSchemas`、`inspectGeminiToolSchemas`），以及 xAI 兼容辅助工具（`resolveXaiModelCompatPatch()`、`applyXaiModelCompat(model)`）。内置 xAI 插件将 `normalizeResolvedModel` + `contributeResolvedModelCompat` 与这些工具结合使用，确保 xAI 规则由提供商自行拥有。
一些流辅助函数有意保持为提供商本地。`@openclaw/anthropic-provider` 将 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 Anthropic 包装器构建器保留在它自己的公开 `api.ts` / `contract-api.ts` 接缝中，因为它们编码了 Claude OAuth beta 处理和 `context1m` 门控。xAI 插件同样将原生 xAI Responses 整形保留在它自己的 `wrapStreamFn` 中（`/fast` 别名、默认 `tool_stream`、不支持的严格工具清理、xAI 特有的推理负载移除）。
有些流辅助工具会有意保留在提供商本地。`@openclaw/anthropic-provider` 将 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及较低层级的 Anthropic 包装器构建器保留在它自己的公共 `api.ts` / `contract-api.ts` 接缝中，因为它们编码了 Claude OAuth beta 处理和 `context1m` 门控。xAI 插件同样将原生 xAI Responses 整形保留在自己的 `wrapStreamFn` 中（`/fast` 别名、默认 `tool_stream`、不支持严格工具清理、移除 xAI 专属推理载荷）。
同样的包根模式也支持 `@openclaw/openai-provider`（提供商构建器、默认模型辅助函数、实时提供商构建器）和 `@openclaw/openrouter-provider`（提供商构建器以及新手引导/配置辅助函数）。
同一个包根模式也支撑 `@openclaw/openai-provider`（提供商构建器、默认模型辅助工具、实时提供商构建器）和 `@openclaw/openrouter-provider`（提供商构建器以及新手引导/配置辅助工具）。
</Accordion>
<Tabs>
@ -332,7 +340,7 @@ x-i18n:
```
</Tab>
<Tab title="自定义标头">
对于需要自定义请求标头或请求体修改的提供商：
对于需要自定义请求标头或正文修改的提供商：
```typescript
// wrapStreamFn returns a StreamFn derived from ctx.streamFn
@ -350,7 +358,7 @@ x-i18n:
```
</Tab>
<Tab title="原生传输身份">
对于需要在通用 HTTP 或 WebSocket 传输上附加原生请求/会话标头或元数据的提供商：
对于需要在通用 HTTP 或 WebSocket 传输上使用原生请求/会话标头或元数据的提供商：
```typescript
resolveTransportTurnState: (ctx) => ({
@ -386,70 +394,70 @@ x-i18n:
</Tabs>
<Accordion title="所有可用的提供商钩子">
OpenClaw 会按以下顺序调用钩子。大多数提供商只会使用其中 2 到 3 个：
OpenClaw 会按此顺序调用钩子。大多数提供商只使用 2-3 个：
OpenClaw 不再调用的仅兼容提供商字段，例如 `ProviderPlugin.capabilities` 和 `suppressBuiltInModel`，未在此列出。
| # | 钩子 | 何时使用 |
| # | 钩子 | 使用场景 |
| --- | --- | --- |
| 1 | `catalog` | 模型目录或基础 URL 默认值 |
| 2 | `applyConfigDefaults` | 在配置实体化期间应用由提供商负责的全局默认值 |
| 3 | `normalizeModelId` | 在查找前清理旧版/预览模型 id 别名 |
| 4 | `normalizeTransport` | 在通用模型组装前清理提供商系列的 `api` / `baseUrl` |
| 2 | `applyConfigDefaults` | 配置具象化期间由提供商拥有的全局默认值 |
| 3 | `normalizeModelId` | 查找前清理旧版/预览模型 ID 别名 |
| 4 | `normalizeTransport` | 通用模型组装前清理提供商系列 `api` / `baseUrl` |
| 5 | `normalizeConfig` | 规范化 `models.providers.<id>` 配置 |
| 6 | `applyNativeStreamingUsageCompat` | 为配置提供商执行原生流式 usage 兼容重写 |
| 7 | `resolveConfigApiKey` | 由提供商负责的环境标记身份验证解析 |
| 8 | `resolveSyntheticAuth` | 本地/自托管或基于配置的合成身份验证 |
| 9 | `shouldDeferSyntheticProfileAuth` | 将合成的已存储配置文件占位符置于环境变量/配置身份验证之后 |
| 10 | `resolveDynamicModel` | 接受任意上游模型 id |
| 11 | `prepareDynamicModel` | 在解析前异步获取元数据 |
| 12 | `normalizeResolvedModel` | 在运行器之前重写传输 |
| 13 | `contributeResolvedModelCompat` | 为通过另一种兼容传输运行的厂商模型提供兼容标志 |
| 14 | `capabilities` | 旧版静态能力包；仅用于兼容性 |
| 15 | `normalizeToolSchemas` | 在注册前清理由提供商负责的工具 schema |
| 16 | `inspectToolSchemas` | 由提供商负责的工具 schema 诊断 |
| 17 | `resolveReasoningOutputMode` | 带标签与原生推理输出契约 |
| 18 | `prepareExtraParams` | 默认请求参数 |
| 19 | `createStreamFn` | 完全自定义的 StreamFn 传输 |
| 20 | `wrapStreamFn` | 在常规流路径上包装自定义标头/请求体 |
| 21 | `resolveTransportTurnState` | 原生逐轮标头/元数据 |
| 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话标头/冷却时间 |
| 23 | `formatApiKey` | 自定义运行时令牌形态 |
| 24 | `refreshOAuth` | 自定义 OAuth 刷新 |
| 25 | `buildAuthDoctorHint` | 身份验证修复指引 |
| 26 | `matchesContextOverflowError` | 由提供商负责的上下文溢出检测 |
| 27 | `classifyFailoverReason` | 由提供商负责的限流/过载分类 |
| 28 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 |
| 29 | `buildMissingAuthMessage` | 自定义缺失身份验证提示 |
| 30 | `suppressBuiltInModel` | 已弃用。运行时钩子不再调用；请使用清单中的 `modelCatalog.suppressions` |
| 31 | `augmentModelCatalog` | 合成的前向兼容条目 |
| 32 | `resolveThinkingProfile` | 模型特定的 `/think` 选项集 |
| 33 | `isBinaryThinking` | 二进制 thinking 开/关兼容性 |
| 34 | `supportsXHighThinking` | `xhigh` 推理支持兼容性 |
| 35 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略兼容性 |
| 36 | `isModernModelRef` | 实时/冒烟模型匹配 |
| 37 | `prepareRuntimeAuth` | 推理前的令牌交换 |
| 38 | `resolveUsageAuth` | 自定义用量凭证解析 |
| 39 | `fetchUsageSnapshot` | 自定义用量端点 |
| 40 | `createEmbeddingProvider` | 用于 memory/search 的由提供商负责的嵌入适配器 |
| 41 | `buildReplayPolicy` | 自定义转录重放/压缩策略 |
| 42 | `sanitizeReplayHistory` | 通用清理后执行提供商特定的重放重写 |
| 43 | `validateReplayTurns` | 在嵌入式运行器之前执行严格的重放轮次校验 |
| 44 | `onModelSelected` | 选择模型后的回调（例如遥测） |
| 6 | `applyNativeStreamingUsageCompat` | 配置提供商的原生流式用量兼容改写 |
| 7 | `resolveConfigApiKey` | 由提供商拥有的环境标记凭证解析 |
| 8 | `resolveSyntheticAuth` | 本地/自托管或配置支持的合成凭证 |
| 9 | `shouldDeferSyntheticProfileAuth` | 将合成的已存储 profile 占位符降级到环境/配置凭证之后 |
| 10 | `resolveDynamicModel` | 接受任意上游模型 ID |
| 11 | `prepareDynamicModel` | 解析前异步获取元数据 |
| 12 | `normalizeResolvedModel` | 运行器前的传输改写 |
| 13 | `contributeResolvedModelCompat` | 另一个兼容传输背后的厂商模型兼容标志 |
| 14 | `normalizeToolSchemas` | 注册前由提供商拥有的工具 schema 清理 |
| 15 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 |
| 16 | `resolveReasoningOutputMode` | 标记式与原生推理输出契约 |
| 17 | `prepareExtraParams` | 默认请求参数 |
| 18 | `createStreamFn` | 完全自定义的 StreamFn 传输 |
| 19 | `wrapStreamFn` | 普通流路径上的自定义标头/正文包装器 |
| 20 | `resolveTransportTurnState` | 原生逐轮标头/元数据 |
| 21 | `resolveWebSocketSessionPolicy` | 原生 WS 会话标头/冷却时间 |
| 22 | `formatApiKey` | 自定义运行时令牌形态 |
| 23 | `refreshOAuth` | 自定义 OAuth 刷新 |
| 24 | `buildAuthDoctorHint` | 凭证修复指引 |
| 25 | `matchesContextOverflowError` | 由提供商拥有的溢出检测 |
| 26 | `classifyFailoverReason` | 由提供商拥有的速率限制/过载分类 |
| 27 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 |
| 28 | `buildMissingAuthMessage` | 自定义缺失凭证提示 |
| 29 | `augmentModelCatalog` | 合成的前向兼容行 |
| 30 | `resolveThinkingProfile` | 模型专属 `/think` 选项集 |
| 31 | `isBinaryThinking` | 二进制 thinking 开/关兼容性 |
| 32 | `supportsXHighThinking` | `xhigh` 推理支持兼容性 |
| 33 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略兼容性 |
| 34 | `isModernModelRef` | 实时/smoke 模型匹配 |
| 35 | `prepareRuntimeAuth` | 推理前令牌交换 |
| 36 | `resolveUsageAuth` | 自定义用量凭证解析 |
| 37 | `fetchUsageSnapshot` | 自定义用量端点 |
| 38 | `createEmbeddingProvider` | 由提供商拥有、用于 memory/search 的嵌入适配器 |
| 39 | `buildReplayPolicy` | 自定义转录重放/压缩策略 |
| 40 | `sanitizeReplayHistory` | 通用清理后的提供商专属重放改写 |
| 41 | `validateReplayTurns` | 嵌入式运行器前的严格重放轮次验证 |
| 42 | `onModelSelected` | 选择后的回调（例如遥测） |
运行时回退说明：
- `normalizeConfig` 会先检查匹配的提供商，然后再检查其他支持钩子的提供商插件，直到某个插件实际修改了配置为止。如果没有任何提供商钩子重写受支持的 Google 系列配置项，内置的 Google 配置规范化器仍会生效。
- `resolveConfigApiKey` 在提供商暴露该钩子时会使用它。内置的 `amazon-bedrock` 路径在这里也带有内建的 AWS 环境标记解析器，尽管 Bedrock 运行时身份验证本身仍使用 AWS SDK 默认链。
- `resolveSystemPromptContribution` 允许提供商为某个模型系列注入具备缓存感知能力的系统提示词指导。当某个行为属于单一提供商/模型系列，并且应保留稳定/动态缓存拆分时，应优先使用它，而不是 `before_prompt_build`。
- `normalizeConfig` 会先检查匹配的提供商，然后检查其他具备钩子能力的提供商插件，直到某个钩子确实修改了配置。如果没有提供商钩子改写受支持的 Google 系列配置条目，内置 Google 配置规范化器仍会应用。
- `resolveConfigApiKey` 在暴露时使用提供商钩子。内置 `amazon-bedrock` 路径在这里也有内置 AWS 环境标记解析器，尽管 Bedrock 运行时凭证本身仍使用 AWS SDK 默认链。
- `resolveSystemPromptContribution` 允许提供商为某个模型系列注入具备缓存感知能力的系统提示词指引。当行为属于一个提供商/模型系列，并且应保留稳定/动态缓存拆分时，优先使用它，而不是 `before_prompt_build`。
如需详细说明和真实示例，请参阅 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。
有关详细描述和真实示例，请参阅 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。
</Accordion>
</Step>
<Step title="添加额外能力（可选）">
提供商插件除了文本推理外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和网络搜索。OpenClaw 将这类插件归类为 **混合能力** 插件——这是公司插件（每个厂商一个插件）的推荐模式。请参阅 [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。
提供商插件可以在文本推理之外，同时注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页获取和 Web 搜索。OpenClaw 将此归类为 **混合能力** 插件，这是公司插件（每个厂商一个插件）的推荐模式。请参阅
[内部机制：能力所有权](/zh-CN/plugins/architecture#capability-ownership-model)。
在 `register(api)` 中，与你现有的 `api.registerProvider(...)` 调用一起注册每项能力。只选择你需要的标签页：
在 `register(api)` 中，将每项能力与现有的 `api.registerProvider(...)` 调用一起注册。只选择你需要的标签页：
<Tabs>
<Tab title="语音（TTS）">
@ -487,10 +495,10 @@ x-i18n:
});
```
对于提供商 HTTP 失败，请使用 `assertOkOrThrowProviderError(...)`，这样插件就可以共享带上限的错误响应体读取、JSON 错误解析以及请求 id 后缀。
对提供商 HTTP 失败使用 `assertOkOrThrowProviderError(...)`，这样插件可共享有上限的错误正文读取、JSON 错误解析和请求 ID 后缀。
</Tab>
<Tab title="实时转录">
优先使用 `createRealtimeTranscriptionWebSocketSession(...)` —— 这个共享辅助函数会处理代理捕获、重连退避、关闭时刷新、就绪握手、音频排队以及关闭事件诊断。你的插件只需要映射上游事件。
优先使用 `createRealtimeTranscriptionWebSocketSession(...)` —— 这个共享辅助函数会处理代理捕获、重连退避、关闭刷新、就绪握手、音频排队和关闭事件诊断。你的插件只需要映射上游事件。
```typescript
api.registerRealtimeTranscriptionProvider({
@ -528,9 +536,7 @@ x-i18n:
});
```
通过 POST multipart 音频的批量 STT 提供商应使用
`openclaw/plugin-sdk/provider-http` 中的
`buildAudioTranscriptionFormData(...)`。该辅助函数会规范化上传文件名，包括那些为了兼容转录 API 而需要使用 M4A 风格文件名的 AAC 上传。
通过 POST 上传 multipart 音频的批处理 STT 提供商应使用来自 `openclaw/plugin-sdk/provider-http` 的 `buildAudioTranscriptionFormData(...)`。该辅助函数会规范化上传文件名，包括为兼容的转录 API 需要 M4A 风格文件名的 AAC 上传。
</Tab>
<Tab title="实时语音">
```typescript
@ -565,7 +571,7 @@ x-i18n:
```
</Tab>
<Tab title="图像和视频生成">
视频能力使用一种**感知模式**的结构：`generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` 这样的扁平聚合字段，不足以清晰地声明变换模式支持或已禁用模式。音乐生成功能也遵循同样的模式，使用显式的 `generate` / `edit` 块。
视频能力使用一种**模式感知**的结构：`generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` 这样的扁平聚合字段不足以清晰声明转换模式支持或已禁用的模式。音乐生成也遵循相同模式，使用显式的 `generate` / `edit` 块。
```typescript
api.registerImageGenerationProvider({
@ -592,12 +598,12 @@ x-i18n:
});
```
</Tab>
<Tab title="网页抓取和搜索">
<Tab title="Web 获取和搜索">
```typescript
api.registerWebFetchProvider({
id: "acme-ai-fetch",
label: "Acme Fetch",
hint: "通过 Acme 的渲染后端抓取页面。",
hint: "Fetch pages through Acme's rendering backend.",
envVars: ["ACME_FETCH_API_KEY"],
placeholder: "acme-...",
signupUrl: "https://acme.example.com/fetch",
@ -608,7 +614,7 @@ x-i18n:
acme.apiKey = value;
},
createTool: () => ({
description: "通过 Acme Fetch 抓取页面。",
description: "Fetch a page through Acme Fetch.",
parameters: {},
execute: async (args) => ({ content: [] }),
}),
@ -668,38 +674,37 @@ clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
这里不要使用旧版仅 Skills 的发布别名；插件包应使用
`clawhub package publish`。
不要在这里使用旧的仅技能发布别名；插件包应使用 `clawhub package publish`。
## 文件结构
```
<bundled-plugin-root>/acme-ai/
├── package.json # openclaw.providers 元数据
├── openclaw.plugin.json # 带有提供商身份验证元数据的清单
├── package.json # openclaw.providers metadata
├── openclaw.plugin.json # Manifest with provider auth metadata
├── index.ts # definePluginEntry + registerProvider
└── src/
├── provider.test.ts # 测试
└── usage.ts # 用量端点（可选）
├── provider.test.ts # Tests
└── usage.ts # Usage endpoint (optional)
```
## 目录顺序参考
`catalog.order` 控制你的目录相对于内置提供商的合并时机：
| 顺序 | 时机 | 使用场景 |
| 顺序 | 时机 | 用例 |
| --------- | ------------- | ----------------------------------------------- |
| `simple` | 第一轮 | 普通 API 密钥提供商 |
| `profile` | 在 simple 之后 | 受身份验证配置文件限制的提供商 |
| `paired` | 在 profile 之后 | 合成多个相关条目 |
| `late` | 最后一轮 | 覆盖现有提供商（发生冲突时胜出） |
| `simple` | 第一轮 | 普通 API key 提供商 |
| `profile` | 在 simple 后 | 由认证档案控制的提供商 |
| `paired` | 在 profile 后 | 合成多个相关条目 |
| `late` | 最后一轮 | 覆盖现有提供商（冲突时胜出） |
## 后续步骤
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) —— 如果你的插件还提供一个渠道
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) —— 如果你的插件也提供渠道
- [SDK 运行时](/zh-CN/plugins/sdk-runtime) —— `api.runtime` 辅助函数（TTS、搜索、子智能体）
- [插件 SDK 概览](/zh-CN/plugins/sdk-overview) —— 完整的子路径导入参考
- [插件内部机制](/zh-CN/plugins/architecture-internals#provider-runtime-hooks) —— 钩子详情和内置示例
- [SDK 概览](/zh-CN/plugins/sdk-overview) —— 完整的子路径导入参考
- [插件内部机制](/zh-CN/plugins/architecture-internals#provider-runtime-hooks) —— 钩子细节和内置示例
## 相关内容