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-06 00:57:31 +00:00
parent b61137d1c9
commit 88e8bf44b8
13 changed files with 2399 additions and 2005 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
docs/zh-CN/concepts/models.md
View File

@ -1,46 +1,47 @@
---
read_when:
- 添加或修改 models CLI（models list/set/scan/aliases/fallbacks）
- 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks）
- 更改模型回退行为或选择 UX
- 更新模型扫描探测（工具/图像）
summary: Models CLI：列出、设置、别名、回退、扫描、状态
title: Models CLI
summary: 模型 CLI：列出、设置、别名、回退、扫描、状态
title: 模型 CLI
x-i18n:
generated_at: "2026-04-05T21:58:57Z"
generated_at: "2026-04-06T00:52:21Z"
model: gpt-5.4
provider: openai
source_hash: 09507720942af72bf7027c733879935d53c79c72b607d737a131eaa02b9b2576
source_hash: 299602ccbe0c3d6bbdb2deab22bc60e1300ef6843ed0b8b36be574cc0213c155
source_path: concepts/models.md
workflow: 15
---
# Models CLI
# 模型 CLI
有关凭证配置轮换、冷却时间以及它们如何与回退交互，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。
提供商快速概览和示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。
有关凭证配置轮换、冷却时间及其与回退机制如何交互，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。
有关提供商的快速概览和示例，请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers)。
## 模型选择如何工作
## 模型选择的工作方式
OpenClaw 按以下顺序选择模型：
1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
2. `agents.defaults.model.fallbacks` 中的**回退模型**（按顺序）。
3. **提供商凭证故障转移**会先在提供商内部发生，然后才会切换到下一个模型。
1. **主** 模型（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
2. `agents.defaults.model.fallbacks` 中的 **回退** 模型（按顺序）。
3. **提供商凭证故障切换** 会先在提供商内部发生，然后才会切换到下一个模型。
相关项：
- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（以及别名）。
- `agents.defaults.imageModel` **仅在**主模型无法接受图像时使用。
- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会依次回退到 `agents.defaults.imageModel`，然后是已解析的当前会话/默认模型。
- `agents.defaults.imageGenerationModel` 用于共享的图像生成功能。如果省略，`image_generate` 仍可推断出由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API key。
- `agents.defaults.videoGenerationModel` 用于共享的视频生成功能。如果省略，`video_generate` 仍可推断出由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API key。
- 每个智能体的默认值可以通过 `agents.list[].model` 加上绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。
- `agents.defaults.imageModel` **仅在** 主模型无法接受图像时使用。
- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会依次回退到 `agents.defaults.imageModel`，然后是已解析的会话/默认模型。
- `agents.defaults.imageGenerationModel` 由共享图像生成功能使用。如果省略，`image_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请同时配置该提供商的凭证/API 密钥。
- `agents.defaults.musicGenerationModel` 由共享音乐生成功能使用。如果省略，`music_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请同时配置该提供商的凭证/API 密钥。
- `agents.defaults.videoGenerationModel` 由共享视频生成功能使用。如果省略，`video_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请同时配置该提供商的凭证/API 密钥。
- 每个智能体的默认值可通过 `agents.list[].model` 及绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。
## 快速模型策略
- 将你的主模型设置为你可用的最强新一代模型。
- 对于成本/延迟敏感的任务和风险较低的聊天，使用回退模型。
- 对于启用了工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。
- 将主模型设置为你可用的最强最新一代模型。
- 对成本/延迟敏感的任务和风险较低的聊天使用回退模型。
- 对启用了工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。
## 新手引导（推荐）
@ -50,8 +51,7 @@ OpenClaw 按以下顺序选择模型：
openclaw onboard
```
它可以为常见提供商设置模型和凭证，包括 **OpenAI Code (Codex)**
订阅（OAuth）和 **Anthropic**（API key 或 Claude CLI）。
它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code（Codex）订阅**（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。
## 配置键名（概览）
@ -63,25 +63,23 @@ openclaw onboard
- `agents.defaults.models`（允许列表 + 别名 + 提供商参数）
- `models.providers`（写入 `models.json` 的自定义提供商）
模型引用会规范化为小写。像 `z.ai/*` 这样的提供商别名会规范化为
`zai/*`。
模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会规范化为 `zai/*`。
提供商配置示例（包括 OpenCode）位于
提供商配置示例（包括 OpenCode）见
[/providers/opencode](/zh-CN/providers/opencode)。
## “模型不被允许”（以及为什么回复会停止）
## “Model is not allowed”（以及为什么回复会停止）
如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择了不在该允许列表中的模型时，
OpenClaw 会返回：
如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择的模型不在该允许列表中时，OpenClaw 会返回：
```
Model "provider/model" is not allowed. Use /model to list available models.
```
这会在生成正常回复**之前**发生，因此消息看起来像是“没有响应”。解决方法是：
这会发生在生成正常回复**之前**，因此消息看起来会像“没有响应”。修复方法是执行以下任一操作：
- 将该模型添加到 `agents.defaults.models`，或
- 清空允许列表（移除 `agents.defaults.models`），或
- 清除允许列表（移除 `agents.defaults.models`），或
- 从 `/model list` 中选择一个模型。
允许列表示例配置：
@ -100,7 +98,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
## 在聊天中切换模型（`/model`）
你可以在不重启的情况下为当前会话切换模型：
你可以为当前会话切换模型，而无需重启：
```
/model
@ -112,23 +110,23 @@ Model "provider/model" is not allowed. Use /model to list available models.
说明：
- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型系列 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个 Submit 步骤。
- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及提交步骤。
- `/model <#>` 会从该选择器中进行选择。
- `/model` 会立即持久化新的会话选择。
- 如果智能体处于空闲状态，下一次运行会立即使用新模型。
- 如果某次运行已处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在一次干净的重试点重启并切换到新模型。
- 如果工具活动或回复输出已经开始，待处理的切换可能会保持排队状态，直到稍后的重试机会或下一次用户轮次。
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并且仅在一个干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到稍后的重试机会或下一次用户轮次。
- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。
- 模型引用通过按**第一个** `/` 进行拆分来解析。输入 `/model <ref>` 时，请使用 `provider/model`。
- 模型引用会通过按**第一个** `/` 拆分来解析。输入 `/model <ref>` 时请使用 `provider/model`。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。
- 如果你省略了提供商，OpenClaw 会按以下顺序解析输入：
- 如果你省略提供商，OpenClaw 会按以下顺序解析输入：
1. 别名匹配
2. 该精确无前缀模型 ID 的唯一已配置提供商匹配
3. 已弃用的回退行为：回退到已配置的默认提供商
如果该提供商不再提供已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露陈旧的、已移除提供商默认值。
3. 已弃用的回退行为：回退到已配置的默认提供商
如果该提供商不再公开已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露过时的、已移除提供商默认值。
完整的命令行为/配置： [Slash commands](/zh-CN/tools/slash-commands)。
完整命令行为/配置： [斜杠命令](/zh-CN/tools/slash-commands)。
## CLI 命令
@ -157,7 +155,7 @@ openclaw models image-fallbacks clear
### `models list`
默认显示已配置的模型。常用标志：
默认显示已配置的模型。有用的标志：
- `--all`：完整目录
- `--local`：仅本地提供商
@ -167,18 +165,14 @@ openclaw models image-fallbacks clear
### `models status`
显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示凭证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内给出警告）。`--plain` 仅打印已解析的主模型。
OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置提供商没有凭证，`models status` 会打印一个**缺少凭证**部分。
JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`
（每个提供商的生效凭证，包括由环境变量支持的凭证）。`auth.oauth`
仅表示凭证存储配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。
自动化场景请使用 `--check`（缺少/过期时退出码为 `1`，即将过期时为 `2`）。
使用 `--probe` 执行实时凭证检查；探测行可能来自凭证配置文件、环境变量凭证或 `models.json`。
如果显式 `auth.order.<provider>` 省略了某个已存储配置文件，探测会报告
`excluded_by_auth_order`，而不是尝试它。如果存在凭证，但该提供商无法解析出可探测模型，探测会报告 `status: no_model`。
显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内到期时警告）。`--plain` 仅打印已解析的主模型。
OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置提供商没有凭证，`models status` 会打印 **Missing auth** 部分。
JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的实际凭证，包括由环境变量支持的凭证）。`auth.oauth` 仅表示凭证存储配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。
对自动化场景请使用 `--check`（缺失/已过期时退出 `1`，即将过期时退出 `2`）。
使用 `--probe` 可进行实时凭证检查；探测行可能来自凭证配置文件、环境变量凭证或 `models.json`。
如果显式的 `auth.order.<provider>` 省略了某个已存储配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果存在凭证，但无法为该提供商解析出可探测的模型，探测会报告 `status: no_model`。
凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API
key 通常最可预测；也支持复用 Claude CLI，以及现有的 Anthropic OAuth/token 配置文件。
凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常最可预测；也支持复用 Claude CLI 以及现有的 Anthropic OAuth/token 配置文件。
示例（Claude CLI）：
@ -189,7 +183,7 @@ openclaw models status
## 扫描（OpenRouter 免费模型）
`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并且可以选择性地探测模型是否支持工具和图像。
`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型是否支持工具和图像。
关键标志：
@ -198,13 +192,13 @@ openclaw models status
- `--max-age-days <days>`：跳过较旧模型
- `--provider <name>`：提供商前缀筛选
- `--max-candidates <n>`：回退列表大小
- `--set-default`：将 `agents.defaults.model.primary` 设置为首个选择项
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为首个图像选择项
- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择项
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择项
探测需要 OpenRouter API key（来自凭证配置文件或
`OPENROUTER_API_KEY`）。如果没有 key，请使用 `--no-probe` 仅列出候选项。
探测需要 OpenRouter API 密钥（来自凭证配置文件或
`OPENROUTER_API_KEY`）。如果没有密钥，请使用 `--no-probe` 仅列出候选项。
扫描结果按以下顺序排序：
扫描结果按以下规则排序：
1. 图像支持
2. 工具延迟
@ -214,33 +208,33 @@ openclaw models status
输入
- OpenRouter `/models` 列表（筛选 `:free`）
- 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API key（参见 [/environment](/zh-CN/help/environment)）
- 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/zh-CN/help/environment)）
- 可选筛选条件：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
- 探测控制：`--timeout`、`--concurrency`
在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。
在 TTY 中运行时，你可以以交互方式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。
## 模型注册表（`models.json`）
`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`
（默认路径为 `~/.openclaw/agents/<agentId>/agent/models.json`）。默认会合并此文件，除非将 `models.mode` 设置为 `replace`。
`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json`（默认为 `~/.openclaw/agents/<agentId>/agent/models.json`）。除非将 `models.mode` 设置为 `replace`，否则默认会合并该文件。
对于匹配的提供商 ID，合并模式的优先级如下：
匹配提供商 ID 的合并模式优先级：
- 如果智能体 `models.json` 中已存在非空 `baseUrl`，则其优先。
- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中不是由 SecretRef 管理时才优先。
- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。
- 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`）。
- 智能体中的 `apiKey`/`baseUrl` 为空或缺失时，会回退到配置中的 `models.providers`。
- 其他提供商字段会从配置和规范化后的目录数据中刷新。
- 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。
- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中不受 SecretRef 管理时优先。
- 受 SecretRef 管理的提供商 `apiKey` 值会根据源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。
- 受 SecretRef 管理的提供商请求头值会根据源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。
- 智能体中为空或缺失的 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
- 其他提供商字段会根据配置和规范化后的目录数据进行刷新。
标记持久化遵循源配置权威：OpenClaw 会根据活动源配置快照（预解析）写入标记，而不是根据运行时已解析的密钥值写入。
这适用于 OpenClaw 重新生成 `models.json` 的所有情况，包括像 `openclaw agent` 这样的命令驱动路径。
标记持久化以源为准：OpenClaw 会根据活动源配置快照（预解析）写入标记，而不是根据已解析的运行时密钥值写入。
这适用于 OpenClaw 重新生成 `models.json` 的所有场景，包括 `openclaw agent` 这样的命令驱动路径。
## 相关内容
- [Model Providers](/zh-CN/concepts/model-providers) — 提供商路由和凭证
- [Model Failover](/zh-CN/concepts/model-failover) — 回退链
- [Image Generation](/zh-CN/tools/image-generation) — 图像模型配置
- [Video Generation](/zh-CN/tools/video-generation) — 视频模型配置
- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键名
- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由与凭证
- [模型故障切换](/zh-CN/concepts/model-failover) — 回退链
- [图像生成](/zh-CN/tools/image-generation) — 图像模型配置
- [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置
- [视频生成](/zh-CN/tools/video-generation) — 视频模型配置
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键名

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

File diff suppressed because it is too large Load Diff

1191
docs/zh-CN/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

121
docs/zh-CN/plugins/building-plugins.md
View File

@ -2,50 +2,50 @@
read_when:
- 你想创建一个新的 OpenClaw 插件
- 你需要一个用于插件开发的快速开始指南
- 你正在为 OpenClaw 添加新的渠道、提供商、工具或其他能力
- 你要为 OpenClaw 添加一个新的渠道、提供商、工具或其他能力
sidebarTitle: Getting Started
summary: 几分钟内创建你的第一个 OpenClaw 插件
summary: 在几分钟内创建你的第一个 OpenClaw 插件
title: 构建插件
x-i18n:
generated_at: "2026-04-05T18:13:47Z"
generated_at: "2026-04-06T00:52:29Z"
model: gpt-5.4
provider: openai
source_hash: 677da2cfba6706bd502fc055169072eb82d2d3baa5a78f28eb520f821caa3773
source_hash: 9be344cb300ecbcba08e593a95bcc93ab16c14b28a0ff0c29b26b79d8249146c
source_path: plugins/building-plugins.md
workflow: 15
---
# 构建插件
插件可通过新增能力来扩展 OpenClaw：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或以上任意组合。
插件可通过新增能力来扩展 OpenClaw：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或任意组合。
你不需要把你的插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm 后，用户可使用 `openclaw plugins install <package-name>` 安装。OpenClaw 会先尝试 ClawHub，并在需要时自动回退到 npm。
你不需要将你的插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，用户即可使用 `openclaw plugins install <package-name>` 安装。OpenClaw 会先尝试 ClawHub，并自动回退到 npm。
## 前置条件
## 先决条件
- Node >= 22，以及一个包管理器（npm 或 pnpm）
- Node >= 22 和一个包管理器（npm 或 pnpm）
- 熟悉 TypeScript（ESM）
- 对于仓库内插件：已克隆仓库并完成 `pnpm install`
## 这是什么类型的插件？
## 哪种类型的插件？
<CardGroup cols={3}>
<Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
将 OpenClaw 连接到消息平台（Discord、IRC 等）
将 OpenClaw 连接到一个消息平台（Discord、IRC 等）
</Card>
<Card title="提供商插件" icon="cpu" href="/zh-CN/plugins/sdk-provider-plugins">
添加模型提供商（LLM、代理或自定义端点）
添加一个模型提供商（LLM、代理或自定义端点）
</Card>
<Card title="工具 / hook 插件" icon="wrench">
注册智能体工具、事件 hooks 或服务 —— 继续阅读下文
<Card title="工具 / 钩子插件" icon="wrench">
注册智能体工具、事件钩子或服务 — 继续阅读下文
</Card>
</CardGroup>
如果某个渠道插件是可选的，并且在新手引导 / 设置运行时可能尚未安装，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装完成前对实际配置写入采取失败关闭策略。
如果某个渠道插件是可选的，并且在运行 onboarding/设置 时可能尚未安装，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导 组合，用于提示安装要求，并在插件安装完成之前，对实际配置写入采取默认拒绝策略。
## 快速开始：工具插件
本演练将创建一个最小插件，用于注册一个智能体工具。渠道插件和提供商插件有上方链接的专用指南。
本演练将创建一个用于注册智能体工具的最小插件。渠道插件和提供商插件有上方链接的专门指南。
<Steps>
<Step title="创建包和清单">
@ -82,7 +82,7 @@ x-i18n:
```
</CodeGroup>
每个插件都需要一个清单，即使没有配置也一样。完整模式请参见 [Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub 发布代码片段位于 `docs/snippets/plugin-publish/`。
每个插件都需要一个清单，即使没有配置也是如此。完整 schema 请参见 [Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub 发布片段位于 `docs/snippets/plugin-publish/`。
</Step>
@ -110,7 +110,7 @@ x-i18n:
});
```
`definePluginEntry` 用于非渠道插件。对于渠道，请使用 `defineChannelPluginEntry` —— 参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。完整入口点选项请参见 [入口点](/zh-CN/plugins/sdk-entrypoints)。
`definePluginEntry` 用于非渠道插件。对于渠道，请使用 `defineChannelPluginEntry` —— 参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。有关完整的入口点选项，请参见 [入口点](/zh-CN/plugins/sdk-entrypoints)。
</Step>
@ -137,49 +137,50 @@ x-i18n:
## 插件能力
单个插件可通过 `api` 对象注册任意数量的能力：
一个插件可以通过 `api` 对象注册任意数量的能力：
| 能力 | 注册方法 | 详细指南 |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| 文本推理（LLM） | `api.registerProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins) |
| 渠道 / 消息传递 | `api.registerChannel(...)` | [渠道插件](/zh-CN/plugins/sdk-channel-plugins) |
| 渠道 / 消息 | `api.registerChannel(...)` | [渠道插件](/zh-CN/plugins/sdk-channel-plugins) |
| 语音（TTS/STT） | `api.registerSpeechProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 图像生成 | `api.registerImageGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 音乐生成 | `api.registerMusicGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 视频生成 | `api.registerVideoGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 网页抓取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 网页搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 智能体工具 | `api.registerTool(...)` | 下文 |
| 自定义命令 | `api.registerCommand(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
| 事件 hooks | `api.registerHook(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
| 事件钩子 | `api.registerHook(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
| HTTP 路由 | `api.registerHttpRoute(...)` | [内部机制](/zh-CN/plugins/architecture#gateway-http-routes) |
| CLI 子命令 | `api.registerCli(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
完整注册 API 请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。
有关完整注册 API，请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。
如果你的插件注册了自定义 Gateway RPC 方法，请将它们放在插件专属前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保留，并且总是解析到 `operator.admin`，即使插件请求了更窄的作用域也是如此。
如果你的插件注册了自定义 Gateway 网关 RPC 方法，请将它们保留在插件专用前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍然保留，并且始终解析为 `operator.admin`，即使插件请求了更窄的作用域也是如此。
需要注意的 hook 防护语义：
需要注意的钩子守卫语义：
- `before_tool_call`：`{ block: true }` 是终结结果，并会停止优先级更低的处理器。
- `before_tool_call`：`{ block: false }` 会被视为没有作出决定。
- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户审批。
- `before_install`：`{ block: true }` 是终结结果，并会停止优先级更低的处理器。
- `before_install`：`{ block: false }` 会被视为没有作出决定。
- `message_sending`：`{ cancel: true }` 是终结结果，并会停止优先级更低的处理器。
- `message_sending`：`{ cancel: false }` 会被视为没有作出决定。
- `before_tool_call`: `{ block: true }` 是终态结果，会阻止更低优先级的处理器继续执行。
- `before_tool_call`: `{ block: false }` 会被视为未作决定。
- `before_tool_call`: `{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户审批。
- `before_install`: `{ block: true }` 是终态结果，会阻止更低优先级的处理器继续执行。
- `before_install`: `{ block: false }` 会被视为未作决定。
- `message_sending`: `{ cancel: true }` 是终态结果，会阻止更低优先级的处理器继续执行。
- `message_sending`: `{ cancel: false }` 会被视为未作决定。
`/approve` 命令会同时处理 exec 审批和插件审批，并带有有界回退机制：当找不到某个 exec 审批 id 时，OpenClaw 会使用同一个 id 重试插件审批。插件审批转发可以通过配置中的 `approvals.plugin` 独立配置。
`/approve` 命令同时处理 exec 审批和插件审批，并带有有界回退机制：当找不到 exec 审批 id 时，OpenClaw 会通过插件审批使用同一个 id 重试。插件审批转发可以通过配置中的 `approvals.plugin` 独立设置。
如果自定义审批流程需要检测这个相同的有界回退场景，优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。
详情请参见 [SDK 概览 hook 决策语义](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
详情请参见 [SDK 概览中的钩子决策语义](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
## 注册智能体工具
工具是 LLM 可调用的类型化函数。它们可以是必需的（始终可用），也可以是可选的（用户主动选择启用）：
工具是 LLM 可调用的类型化函数。它们可以是必需的（始终可用），也可以是可选的（用户选择启用）：
```typescript
register(api) {
@ -216,66 +217,66 @@ register(api) {
}
```
- 工具名称不能与核心工具冲突（冲突项会被跳过）
- 对于有副作用或需要额外二进制依赖的工具，请使用 `optional: true`
- 用户可通过将插件 id 添加到 `tools.allow` 来启用某个插件的所有工具
- 工具名称不得与核心工具冲突（冲突项会被跳过）
- 对具有副作用或需要额外二进制依赖的工具使用 `optional: true`
- 用户可以通过将插件 id 添加到 `tools.allow` 来启用某个插件中的所有工具
## 导入约定
始终从聚焦的 `openclaw/plugin-sdk/<subpath>` 路径导入：
始终从精确的 `openclaw/plugin-sdk/<subpath>` 路径导入：
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
// 错误：单体根路径（已弃用，将被移除）
// 错误：单体根路径（已弃用，未来将移除）
import { ... } from "openclaw/plugin-sdk";
```
完整子路径参考请参见 [SDK 概览](/zh-CN/plugins/sdk-overview)。
完整的子路径参考请参见 [SDK 概览](/zh-CN/plugins/sdk-overview)。
在你的插件内部，请使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行内部导入 —— 绝不要通过其 SDK 路径导入你自己的插件。
在你的插件内部，使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行内部导入 —— 永远不要通过其 SDK 路径导入你自己的插件。
对于提供商插件，除非该扩展点确实是通用的，否则应将提供商专属辅助函数保留在这些包根级 barrel 中。当前内置示例包括：
对于提供商插件，请将提供商专用辅助函数保留在这些包根级 barrel 中，除非该接口确实足够通用。当前内置示例包括：
- Anthropic：Claude 流包装器，以及 `service_tier` / beta 辅助函数
- OpenAI：提供商构建器、默认模型辅助函数、实时提供商
- OpenRouter：提供商构建器，以及新手引导 / 配置辅助函数
- OpenRouter：提供商构建器，以及 onboarding/配置 辅助函数
如果某个辅助函数只在一个内置提供商包内部有用，就应把它保留在该包根级扩展点上，而不是将其提升到 `openclaw/plugin-sdk/*` 中。
如果某个辅助函数只在一个内置提供商包中有用，请将其保留在该包根级接口上，而不是提升到 `openclaw/plugin-sdk/*` 中。
某些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助扩展点仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。应将这些视为保留接口，而不是新第三方插件的默认模式。
一些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助接口仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。请将这些视为保留接口，而不是新第三方插件的默认模式。
## 提交前检查清单
<Check>**package.json** 具有正确的 `openclaw` 元数据</Check>
<Check>**openclaw.plugin.json** 清单已存在且有效</Check>
<Check>入口点使用 `defineChannelPluginEntry` 或 `definePluginEntry`</Check>
<Check>所有导入都使用聚焦的 `plugin-sdk/<subpath>` 路径</Check>
<Check>所有导入都使用精确的 `plugin-sdk/<subpath>` 路径</Check>
<Check>内部导入使用本地模块，而不是 SDK 自导入</Check>
<Check>测试通过（`pnpm test -- <bundled-plugin-root>/my-plugin/`）</Check>
<Check>`pnpm check` 通过（仓库内插件）</Check>
## Beta 版本测试
1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签形式类似 `v2026.3.N-beta.1`。你也可以为 OpenClaw 官方 X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以获取发布公告。
2. 在 beta 标签出现后尽快使用它测试你的插件。稳定版发布前的窗口通常只有几个小时。
3. 测试完成后，在 `plugin-forum` Discord 渠道中你的插件线程里发帖，说明是 `all good` 还是哪里出问题了。如果你还没有线程，请创建一个。
4. 如果出了问题，请创建或更新一个标题为 `Beta blocker: <plugin-name> - <summary>` 的 issue，并添加 `beta-blocker` 标签。把该 issue 链接发到你的线程中。
5. 向 `main` 提交一个标题为 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，并在 PR 和你的 Discord 线程中都链接该 issue。贡献者无法给 PR 打标签，因此标题就是给维护者和自动化系统的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题则可能仍然随版本发布。维护者会在 beta 测试期间关注这些线程。
6. 没有消息就表示一切正常。如果你错过了窗口，你的修复很可能会在下一个周期落地。
1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签格式类似 `v2026.3.N-beta.1`。你也可以为 OpenClaw 官方 X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以接收发布公告。
2. Beta 标签一出现，就尽快用它测试你的插件。正式版本发布前的窗口期通常只有几个小时。
3. 测试后，在 `plugin-forum` Discord 渠道中你插件对应的主题里发帖，说明是 `all good` 还是哪里出了问题。如果你还没有主题，请创建一个。
4. 如果出现问题，打开或更新一个标题为 `Beta blocker: <plugin-name> - <summary>` 的 issue，并添加 `beta-blocker` 标签。将该 issue 链接贴到你的主题中。
5. 向 `main` 提交一个标题为 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，并在 PR 和你的 Discord 主题中都关联该 issue。贡献者不能为 PR 添加标签，因此标题就是给维护者和自动化系统的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题可能仍然会随版本发布。维护者会在 Beta 测试期间关注这些主题。
6. 没有消息就表示一切正常。如果你错过了这个窗口，你的修复很可能会落到下一个周期。
## 后续步骤
<CardGroup cols={2}>
<Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
构建消息渠道插件
构建一个消息渠道插件
</Card>
<Card title="提供商插件" icon="cpu" href="/zh-CN/plugins/sdk-provider-plugins">
构建模型提供商插件
构建一个模型提供商插件
</Card>
<Card title="SDK 概览" icon="book-open" href="/zh-CN/plugins/sdk-overview">
导入映射与注册 API 参考
导入映射和注册 API 参考
</Card>
<Card title="运行时辅助函数" icon="settings" href="/zh-CN/plugins/sdk-runtime">
通过 api.runtime 使用 TTS、搜索、子智能体
@ -284,14 +285,14 @@ import { ... } from "openclaw/plugin-sdk";
测试工具和模式
</Card>
<Card title="插件清单" icon="file-json" href="/zh-CN/plugins/manifest">
完整清单模式参考
完整清单 schema 参考
</Card>
</CardGroup>
## 相关内容
- [插件架构](/zh-CN/plugins/architecture) —— 内部架构深度解析
- [SDK 概览](/zh-CN/plugins/sdk-overview) —— 插件 SDK 参考
- [Manifest](/zh-CN/plugins/manifest) —— 插件清单格式
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) —— 构建渠道插件
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) —— 构建提供商插件
- [插件架构](/zh-CN/plugins/architecture) — 内部架构深入解析
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考
- [Manifest](/zh-CN/plugins/manifest) — 插件清单格式
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件

274
docs/zh-CN/plugins/manifest.md
View File

@ -1,62 +1,63 @@
---
read_when:
- 你正在构建一个 OpenClaw 插件
- 你需要发布插件配置 schema，或调试插件校验错误
- 你需要发布一个插件配置 schema，或调试插件校验错误
summary: 插件清单 + JSON Schema 要求（严格配置校验）
title: 插件清单
x-i18n:
generated_at: "2026-04-06T00:20:32Z"
generated_at: "2026-04-06T00:52:42Z"
model: gpt-5.4
provider: openai
source_hash: 89a940d54bd18bf60368addd09aeef47d53ca9b07714397e1c43083e01aac6b6
source_hash: f6f915a761cdb5df77eba5d2ccd438c65445bd2ab41b0539d1200e63e8cf2c3a
source_path: plugins/manifest.md
workflow: 15
---
# 插件清单（`openclaw.plugin.json`）
# 插件清单 (`openclaw.plugin.json`)
本页仅适用于**原生 OpenClaw 插件清单**。
本页面仅适用于**原生 OpenClaw 插件清单**。
关于兼容的 bundle 布局，请参阅 [插件包](/zh-CN/plugins/bundles)。
关于兼容的 bundle 布局，请参见 [插件 bundles](/zh-CN/plugins/bundles)。
兼容的 bundle 格式使用不同的清单文件：
- Codex bundle：`.codex-plugin/plugin.json`
- Claude bundle：`.claude-plugin/plugin.json` 或不带清单的默认 Claude 组件布局
- Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件
布局
- Cursor bundle：`.cursor-plugin/plugin.json`
OpenClaw 也会自动检测这些 bundle 布局，但它们不会按照这里介绍的 `openclaw.plugin.json` schema 进行校验。
OpenClaw 也会自动检测这些 bundle 布局，但不会按照这里描述的 `openclaw.plugin.json` schema 对它们进行校验。
对于兼容 bundle，当布局符合 OpenClaw 运行时预期时，OpenClaw 当前会读取 bundle 元数据，以及声明的 skill 根目录、Claude 命令根目录、Claude bundle `settings.json` 默认值、Claude bundle LSP 默认值，以及受支持的 hook 包。
对于兼容 bundles，OpenClaw 当前会在布局符合 OpenClaw 运行时预期时，读取 bundle 元数据、声明的 skill 根目录、Claude 命令根目录、Claude bundle `settings.json` 默认值、Claude bundle LSP 默认值，以及受支持的 hook packs。
每个原生 OpenClaw 插件**都必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用这个清单在**不执行插件代码的情况下**校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
每个原生 OpenClaw 插件**都必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用这个清单在**不执行插件代码**的情况下校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
完整的插件系统指南请参阅：[插件](/zh-CN/tools/plugin)。
关于原生能力模型和当前外部兼容性指南，请参阅：
查看完整的插件系统指南：[插件](/zh-CN/tools/plugin)。
关于原生能力模型和当前的外部兼容性指南，请参见：
[能力模型](/zh-CN/plugins/architecture#public-capability-model)。
## 这个文件的作用
`openclaw.plugin.json` 是 OpenClaw 在加载你的插件代码之前读取的元数据。
请将它用于：
用于：
- 插件标识
- 配置校验
- 无需启动插件运行时即可获取的凭证和新手引导元数据
- 应在插件运行时加载前解析的别名和自动启用元数据
- 应在运行时加载前自动激活插件的简写模型家族归属元数据
- 用于内置兼容接线和契约覆盖的静态能力归属快照
- 无需加载运行时即可合并到目录和校验表面的渠道专用配置元数据
- 无需启动插件运行时即可使用的认证和新手引导元数据
- 在插件运行时加载前就应解析的别名和自动启用元数据
- 在运行时加载前自动激活插件的 shorthand 模型族归属元数据
- 用于内置兼容性接线和契约覆盖的静态能力归属快照
- 无需加载运行时即可合并到目录和校验表面的渠道特定配置元数据
- 配置 UI 提示
不要将它用于：
不要用于：
- 注册运行时行为
- 声明代码入口点
- npm 安装元数据
这些内容应放在你的插件代码和 `package.json` 中。
这些应该放在你的插件代码和 `package.json` 中。
## 最小示例
@ -122,50 +123,50 @@ OpenClaw 也会自动检测这些 bundle 布局，但它们不会按照这里介
## 顶层字段参考
| Field | Required | Type | 含义 |
| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.<id>` 中使用的 id。 |
| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将某个内置插件标记为默认启用。省略它，或将其设为任何非 `true` 的值，都会让该插件默认保持禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会规范化到此规范插件 id 的旧版 id。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当凭证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个供 `plugins.slots.*` 使用的独占插件类型。 |
| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于发现和配置校验。 |
| `providers` | 否 | `string[]` | 此插件拥有的提供商 id。 |
| `modelSupport` | 否 | `object` | 由清单拥有的简写模型家族元数据，用于在运行时之前自动加载插件。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | 无需加载插件代码即可由 OpenClaw 检查的轻量提供商凭证环境变量元数据。 |
| `providerAuthChoices` | 否 | `object[]` | 供新手引导选择器、首选提供商解析和简单 CLI flag 接线使用的轻量凭证选项元数据。 |
| `contracts` | 否 | `object` | 用于语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、Web 搜索 和工具归属的静态内置能力快照。 |
| `channelConfigs` | 否 | `Record<string, object>` | 由清单拥有的渠道配置元数据，在运行时加载前合并到发现和校验表面中。 |
| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 |
| `name` | 否 | `string` | 人类可读的插件名称。 |
| `description` | 否 | `string` | 在插件相关表面中显示的简短摘要。 |
| `version` | 否 | `string` | 信息性插件版本。 |
| `uiHints` | 否 | `Record<string, object>` | 配置字段的 UI 标签、占位符和敏感性提示。 |
| 字段 | 必填 | 类型 | 含义 |
| ----------------------------------- | -------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.<id>` 中使用的 id。 |
| `configSchema` | 是 | `object` | 该插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将一个内置插件标记为默认启用。省略它，或设置为任何非 `true` 的值，即表示该插件默认禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会被规范化为当前规范插件 id 的旧版 id。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明由 `plugins.slots.*` 使用的独占插件类型。 |
| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于设备发现和配置校验。 |
| `providers` | 否 | `string[]` | 由此插件拥有的提供商 id。 |
| `modelSupport` | 否 | `object` | 由清单拥有的 shorthand 模型族元数据，用于在运行时之前自动加载插件。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 无需加载插件代码即可检查的轻量级提供商认证环境变量元数据。 |
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的轻量级认证选项元数据。 |
| `contracts` | 否 | `object` | 用于语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 |
| `channelConfigs` | 否 | `Record<string, object>` | 在运行时加载前，合并到设备发现和校验表面的由清单拥有的渠道配置元数据。 |
| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 |
| `name` | 否 | `string` | 人类可读的插件名称。 |
| `description` | 否 | `string` | 显示在插件表面中的简短摘要。 |
| `version` | 否 | `string` | 信息性插件版本。 |
| `uiHints` | 否 | `Record<string, object>` | 用于配置字段的 UI 标签、占位符和敏感性提示。 |
## `providerAuthChoices` 参考
每个 `providerAuthChoices` 条目描述一个新手引导或凭证选择项。
每个 `providerAuthChoices` 条目描述一个新手引导或认证选项。
OpenClaw 会在提供商运行时加载前读取它。
| Field | Required | Type | 含义 |
| 字段 | 必填 | 类型 | 含义 |
| --------------------- | -------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `provider` | 是 | `string` | 此选项所属的提供商 id。 |
| `method` | 是 | `string` | 要分派到的凭证方法 id。 |
| `choiceId` | 是 | `string` | 供新手引导和 CLI 流程使用的稳定凭证选项 id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 |
| `choiceHint` | 否 | `string` | 选择器的简短帮助文本。 |
| `assistantPriority` | 否 | `number` | 在由智能体驱动的交互式选择器中，数值越小排序越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在智能体选择器中隐藏该选项，但仍允许在手动 CLI 选择中使用。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到当前替代选项的旧版 choice id。 |
| `groupId` | 否 | `string` | 用于对相关选项进行分组的可选组 id。 |
| `groupLabel` | 否 | `string` | 该分组的面向用户标签。 |
| `groupHint` | 否 | `string` | 该分组的简短帮助文本。 |
| `optionKey` | 否 | `string` | 用于简单单 flag 凭证流程的内部选项键名。 |
| `cliFlag` | 否 | `string` | CLI flag 名称，例如 `--openrouter-api-key`。 |
| `cliOption` | 否 | `string` | 完整的 CLI 选项形态，例如 `--openrouter-api-key <key>`。 |
| `cliDescription` | 否 | `string` | 用于 CLI 帮助信息中的说明。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 该选项应出现在哪些新手引导表面中。如果省略，默认值为 `["text-inference"]`。 |
| `method` | 是 | `string` | 要分发到的认证方法 id。 |
| `choiceId` | 是 | `string` | 由新手引导和 CLI 流程使用的稳定认证选项 id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如省略，OpenClaw 会回退为 `choiceId`。 |
| `choiceHint` | 否 | `string` | 选择器中的简短辅助文本。 |
| `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小排序越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许手动通过 CLI 选择。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 |
| `groupId` | 否 | `string` | 用于对相关选项进行分组的可选分组 id。 |
| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 |
| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 |
| `optionKey` | 否 | `string` | 用于简单单标志认证流程的内部选项键。 |
| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 |
| `cliOption` | 否 | `string` | 完整的 CLI 选项形式，例如 `--openrouter-api-key <key>`。 |
| `cliDescription` | 否 | `string` | CLI 帮助中使用的说明。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 该选项应出现在哪些新手引导表面中。如省略，默认值为 `["text-inference"]`。 |
## `uiHints` 参考
@ -186,18 +187,18 @@ OpenClaw 会在提供商运行时加载前读取它。
每个字段提示可以包含：
| Field | Type | 含义 |
| ------------- | ---------- | -------------------------- |
| `label` | `string` | 面向用户的字段标签。 |
| `help` | `string` | 简短帮助文本。 |
| `tags` | `string[]` | 可选的 UI 标签。 |
| `advanced` | `boolean` | 将该字段标记为高级字段。 |
| `sensitive` | `boolean` | 将该字段标记为密钥或敏感。 |
| `placeholder` | `string` | 表单输入的占位文本。 |
| 字段 | 类型 | 含义 |
| ------------- | ---------- | ------------------------------ |
| `label` | `string` | 面向用户的字段标签。 |
| `help` | `string` | 简短辅助文本。 |
| `tags` | `string[]` | 可选 UI 标签。 |
| `advanced` | `boolean` | 将该字段标记为高级项。 |
| `sensitive` | `boolean` | 将该字段标记为密钥或敏感项。 |
| `placeholder` | `string` | 表单输入的占位文本。 |
## `contracts` 参考
仅将 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据。
仅在 `contracts` 中放置 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据。
```json
{
@ -217,21 +218,21 @@ OpenClaw 会在提供商运行时加载前读取它。
每个列表都是可选的：
| Field | Type | 含义 |
| -------------------------------- | ---------- | ---------------------------------------------- |
| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 |
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转写提供商 id。 |
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 |
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 |
| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 |
| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 |
| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取提供商 id。 |
| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索 提供商 id。 |
| `tools` | `string[]` | 此插件为内置契约检查拥有的智能体工具名称。 |
| 字段 | 类型 | 含义 |
| -------------------------------- | ---------- | ------------------------------------------------------ |
| `speechProviders` | `string[]` | 该插件拥有的语音提供商 id。 |
| `realtimeTranscriptionProviders` | `string[]` | 该插件拥有的实时转录提供商 id。 |
| `realtimeVoiceProviders` | `string[]` | 该插件拥有的实时语音提供商 id。 |
| `mediaUnderstandingProviders` | `string[]` | 该插件拥有的媒体理解提供商 id。 |
| `imageGenerationProviders` | `string[]` | 该插件拥有的图像生成提供商 id。 |
| `videoGenerationProviders` | `string[]` | 该插件拥有的视频生成提供商 id。 |
| `webFetchProviders` | `string[]` | 该插件拥有的网页抓取提供商 id。 |
| `webSearchProviders` | `string[]` | 该插件拥有的网页搜索提供商 id。 |
| `tools` | `string[]` | 该插件拥有的智能体工具名称，用于内置契约检查。 |
## `channelConfigs` 参考
当渠道插件在运行时加载前需要轻量配置元数据时，请使用 `channelConfigs`。
当渠道插件在运行时加载前需要轻量级配置元数据时，请使用 `channelConfigs`。
```json
{
@ -260,17 +261,17 @@ OpenClaw 会在提供商运行时加载前读取它。
每个渠道条目可以包含：
| Field | Type | 含义 |
| ------------- | ------------------------ | -------------------------------------------------------------------------------------- |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 |
| `uiHints` | `Record<string, object>` | 该渠道配置部分可选的 UI 标签 / 占位符 / 敏感性提示。 |
| `label` | `string` | 当运行时元数据尚未准备好时，合并到选择器和检查表面中的渠道标签。 |
| `description` | `string` | 用于检查和目录表面的简短渠道描述。 |
| `preferOver` | `string[]` | 在选择表面中，此渠道应优先于的旧版或较低优先级插件 id。 |
| 字段 | 类型 | 含义 |
| ------------- | ------------------------ | ------------------------------------------------------------------------------------ |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 |
| `uiHints` | `Record<string, object>` | 该渠道配置部分的可选 UI 标签 / 占位符 / 敏感性提示。 |
| `label` | `string` | 当运行时元数据尚未准备好时，合并到选择器和检查表面的渠道标签。 |
| `description` | `string` | 用于检查和目录表面的简短渠道描述。 |
| `preferOver` | `string[]` | 在选择表面中，该渠道应优先于的旧版或较低优先级插件 id。 |
## `modelSupport` 参考
如果 OpenClaw 应在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断你的提供商插件，请使用 `modelSupport`。
当 OpenClaw 应在运行时加载前根据 `gpt-5.4` 或 `claude-sonnet-4.6` 之类的 shorthand 模型 id 推断你的提供商插件时，请使用 `modelSupport`。
```json
{
@ -281,60 +282,60 @@ OpenClaw 会在提供商运行时加载前读取它。
}
```
OpenClaw 会按以下优先级处理：
OpenClaw 应用以下优先级：
- 显式 `provider/model` 引用使用所属 `providers` 清单元数据
- `modelPatterns` 优先于 `modelPrefixes`
- 显式 `provider/model` 引用使用拥有该模型的 `providers` 清单元数据
- `modelPatterns` 的优先级高于 `modelPrefixes`
- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出
- 其余歧义会被忽略，直到用户或配置显式指定提供商
- 如果仍存在歧义，则在用户或配置明确指定提供商之前会忽略该歧义
字段：
| Field | Type | 含义 |
| --------------- | ---------- | -------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | 使用 `startsWith` 针对简写模型 id 进行匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除 profile 后缀后，针对简写模型 id 进行匹配的正则表达式源码。 |
| 字段 | 类型 | 含义 |
| --------------- | ---------- | ---------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | 使用 `startsWith` 对 shorthand 模型 id 进行匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除 profile 后缀后，对 shorthand 模型 id 进行匹配的正则表达式源。 |
旧版顶层能力键已弃用。请使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；普通清单加载不再将这些顶层字段视为能力归属。
旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规清单加载不再将这些顶层字段视为能力归属。
## 清单与 `package.json` 的区别
这两个文件承担不同的职责：
| File | 用途 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.plugin.json` | 发现、配置校验、凭证选项元数据，以及必须在插件代码运行前存在的 UI 提示 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 配置块 |
| 文件 | 用途 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | 在插件代码运行前必须存在的设备发现、配置校验、认证选项元数据和 UI 提示 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 配置块 |
如果你不确定某段元数据应放在哪里，请使用以下规则：
如果你不确定某条元数据应放在哪里，请使用这个规则：
- 如果 OpenClaw 必须在加载插件代码之前知道它，就把它放在 `openclaw.plugin.json` 中
- 如果它与打包、入口文件或 npm 安装行为有关，就把它放在 `package.json` 中
- 如果 OpenClaw 必须在加载插件代码前知道它，就放在 `openclaw.plugin.json` 中
- 如果它与打包、入口文件或 npm 安装行为有关，就放在 `package.json` 中
### 影响发现的 `package.json` 字段
### 会影响设备发现的 `package.json` 字段
某些运行时前的插件元数据有意放在 `package.json` 的 `openclaw` 配置块下，而不是 `openclaw.plugin.json` 中。
有些运行前插件元数据被有意放在 `package.json` 的 `openclaw` 配置块下，而不是 `openclaw.plugin.json` 中。
重要示例：
| Field | 含义 |
| 字段 | 含义 |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | 声明原生插件入口点。 |
| `openclaw.setupEntry` | 轻量的仅设置入口点，用于新手引导和延迟渠道启动期间。 |
| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择文案。 |
| `openclaw.channel.configuredState` | 轻量已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅基于环境变量的设置？”。 |
| `openclaw.channel.persistedAuthState` | 轻量持久化凭证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何已登录状态？”。 |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 用于内置插件和外部发布插件的安装 / 更新提示。 |
| `openclaw.install.defaultChoice` | 当存在多个安装来源时的首选安装路径。 |
| `openclaw.setupEntry` | 在新手引导和延迟渠道启动期间使用的轻量级仅设置入口点。 |
| `openclaw.channel` | 轻量级渠道目录元数据，例如标签、文档路径、别名和选择文案。 |
| `openclaw.channel.configuredState` | 轻量级已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅环境变量设置？” |
| `openclaw.channel.persistedAuthState` | 轻量级持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何已登录状态？” |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 用于内置插件和外部发布插件的安装 / 更新提示。 |
| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 |
| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个范围很窄的内置插件重新安装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间，先加载仅设置渠道表面，再加载完整渠道插件。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个范围很窄的内置插件重装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置的渠道表面，再加载完整渠道插件。 |
`openclaw.install.minHostVersion` 会在安装期间和清单注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会让旧主机跳过该插件。
`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；合法但更高的新版本值会使插件在较旧主机上被跳过。
`openclaw.install.allowInvalidConfigRecovery` 的范围被有意限制得很窄。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或该内置插件对应的陈旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并引导操作员使用 `openclaw doctor --fix`。
`openclaw.install.allowInvalidConfigRecovery` 的设计范围刻意很窄。它不会让任意损坏的配置变得可安装。目前，它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一个内置插件对应的陈旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并将操作人员引导到 `openclaw doctor --fix`。
`openclaw.channel.persistedAuthState` 是一个小型检查器模块的包元数据：
`openclaw.channel.persistedAuthState` 是一个微型检查器模块的包元数据：
```json
{
@ -350,9 +351,9 @@ OpenClaw 会按以下优先级处理：
}
```
当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行轻量的是 / 否凭证探测时，请使用它。目标导出应是一个仅读取持久化状态的小函数；不要通过完整渠道运行时 barrel 暴露它。
当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行一个轻量级的是 / 否认证探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 暴露它。
`openclaw.channel.configuredState` 对轻量仅环境变量已配置检查采用相同的结构：
`openclaw.channel.configuredState` 采用相同的结构，用于轻量级的仅环境变量已配置检查：
```json
{
@ -368,42 +369,43 @@ OpenClaw 会按以下优先级处理：
}
```
当某个渠道可以根据环境变量或其他微小的非运行时输入回答已配置状态时，请使用它。如果检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。
当一个渠道可以通过环境变量或其他微小的非运行时输入回答已配置状态时，请使用它。如果检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。
## JSON Schema 要求
- **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。
- 可以接受空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。
- Schema 会在配置读取 / 写入时校验，而不是在运行时校验。
- Schema 在配置读写时校验，而不是在运行时校验。
## 校验行为
- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已由某个插件清单声明。
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。
- 未知的 `channels.*` 键是**错误**，除非该渠道 id 由某个插件清单声明。
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*`
必须引用**可发现的**插件 id。未知 id 是**错误**。
- 如果插件已安装，但其清单或 schema 损坏或缺失，校验会失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件处于**禁用**状态，则配置会被保留，并且 Doctor + 日志中会显示**警告**。
- 如果插件配置存在，但插件**已禁用**，配置会被保留，并且 Doctor + 日志中会显示一个**警告**。
完整的 `plugins.*` schema 请参阅 [配置参考](/zh-CN/gateway/configuration)。
完整的 `plugins.*` schema 请参见 [配置参考](/zh-CN/gateway/configuration)。
## 注意事项
## 说明
- 对于**原生 OpenClaw 插件**，清单是**必需的**，包括本地文件系统加载。
- 运行时仍会单独加载插件模块；清单仅用于发现 + 校验。
- 原生清单使用 JSON5 解析，因此支持注释、尾随逗号和未加引号的键，只要最终值仍然是一个对象即可。
- 清单加载器只会读取文档中说明的清单字段。避免在这里添加自定义顶层键。
- `providerAuthEnvVars` 是用于凭证探测、环境变量标记校验以及类似提供商凭证表面的轻量元数据路径，这些表面不应为了检查环境变量名而启动插件运行时。
- `providerAuthChoices` 是在提供商运行时加载前，用于凭证选项选择器、`--auth-choice` 解析、首选提供商映射以及简单新手引导 CLI flag 注册的轻量元数据路径。对于需要提供商代码的运行时向导元数据，请参阅
- 清单对于**原生 OpenClaw 插件**是**必需的**，包括本地文件系统加载。
- 运行时仍会单独加载插件模块；清单仅用于设备发现 + 校验。
- 原生清单使用 JSON5 解析，因此接受注释、尾随逗号和未加引号的键，只要最终值仍然是一个对象。
- 清单加载器只读取已记录的清单字段。避免在这里添加自定义顶层键。
- `providerAuthEnvVars` 是用于认证探测、环境变量标记校验以及类似提供商认证表面的轻量级元数据路径，这些场景不应仅为了检查环境变量名称而启动插件运行时。
- `providerAuthChoices` 是用于认证选项选择器、`--auth-choice` 解析、首选提供商映射以及在提供商运行时加载前进行简单新手引导 CLI 标志注册的轻量级元数据路径。对于需要提供商代码的运行时向导元数据，请参见
[提供商运行时 hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
- 独占插件类型通过 `plugins.slots.*` 进行选择。
- 独占插件类型通过 `plugins.slots.*` 选择。
- `kind: "memory"` 通过 `plugins.slots.memory` 选择。
- `kind: "context-engine"` 通过 `plugins.slots.contextEngine` 选择
（默认值：内置 `legacy`）。
- `kind: "context-engine"` 通过 `plugins.slots.contextEngine`
选择（默认值：内置 `legacy`）。
- 当插件不需要它们时，可以省略 `channels`、`providers` 和 `skills`。
- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm `allow-build-scripts`
- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器 allowlist 要求（例如 pnpm `allow-build-scripts`
- `pnpm rebuild <package>`）。
## 相关内容
- [构建插件](/zh-CN/plugins/building-plugins) — 插件快速开始
- [插件架构](/zh-CN/plugins/architecture) — 内部架构
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考
- [插件 SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考

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

@ -1,64 +1,62 @@
---
read_when:
- 你看到了 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 警告
- 你看到了 OPENCLAW_EXTENSION_API_DEPRECATED 警告
- 你看到 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 警告
- 你看到 OPENCLAW_EXTENSION_API_DEPRECATED 警告
- 你正在将插件更新到现代插件架构
- 你维护一个外部 OpenClaw 插件
- 你在维护外部 OpenClaw 插件
sidebarTitle: Migrate to SDK
summary: 从旧版向后兼容层迁移到现代插件 SDK
summary: 从旧版向后兼容层迁移到现代 插件 SDK
title: 插件 SDK 迁移
x-i18n:
generated_at: "2026-04-05T22:37:39Z"
generated_at: "2026-04-06T00:53:02Z"
model: gpt-5.4
provider: openai
source_hash: 23fd97ccf58e626ea4be4ae36d060cb963e13f14036cd82d2a86b7dc631ec8f1
source_hash: b71ce69b30c3bb02da1b263b1d11dc3214deae5f6fc708515e23b5a1c7bb7c8f
source_path: plugins/sdk-migration.md
workflow: 15
---
# 插件 SDK 迁移
OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且文档完善的导入路径。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。
OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且有文档说明的导入方式。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。
## 正在发生什么变化
## 正在发生哪些变化
旧插件系统提供了两个高度开放的表面，使插件可以从单个入口点导入所需的任何内容：
旧插件系统提供了两个完全开放的接口，使插件能够从单一入口点导入所需的任何内容：
- **`openclaw/plugin-sdk/compat`** — 一个会重新导出数十个辅助工具的单一导入入口。它被引入是为了在构建新插件架构期间，保持旧的基于 hook 的插件继续工作。
- **`openclaw/extension-api`** — 一个桥接层，使插件能够直接访问宿主侧辅助工具，例如嵌入式 agent 运行器。
- **`openclaw/plugin-sdk/compat`** —— 一个单一导入入口，重新导出了数十个辅助函数。引入它是为了在构建新插件架构期间，让较旧的基于 hook 的插件继续工作。
- **`openclaw/extension-api`** —— 一个桥接层，使插件能够直接访问宿主侧辅助函数，例如嵌入式智能体运行器。
这两个表面现已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。
这两个接口现在都已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。
<Warning>
向后兼容层将在未来的主版本中移除。
到那时，仍从这些表面导入的插件将会失效。
向后兼容层将在未来的某个主版本中移除。
到那时，仍然从这些接口导入内容的插件将会失效。
</Warning>
## 为什么会有这个变化
旧方法会带来以下问题：
旧方法会导致一些问题：
- **启动缓慢** — 导入一个辅助工具就会加载数十个无关模块
- **循环依赖** — 宽泛的重新导出让导入环更容易出现
- **API 表面不清晰** — 无法判断哪些导出是稳定的，哪些属于内部实现
- **启动缓慢** —— 导入一个辅助函数会加载数十个无关模块
- **循环依赖** —— 宽泛的重新导出使导入环路更容易出现
- **API 接口不清晰** —— 无法区分哪些导出是稳定的，哪些属于内部实现
现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\<subpath\>`）都是一个小型、自包含的模块，具有明确用途和文档化契约。
现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\<subpath\>`）都是一个小型、自包含的模块，拥有明确用途和文档化契约。
面向内置渠道的旧版 provider 便利接缝也已移除。像 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助工具接缝，以及 `openclaw/plugin-sdk/telegram-core` 这样的导入，都是私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区中，请将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。
面向内置渠道的旧版提供商便捷接口也已移除。像 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口，以及 `openclaw/plugin-sdk/telegram-core` 这样的导入路径，都是私有 mono-repo 快捷方式，并不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区中，请将提供商自有辅助函数保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。
当前内置 provider 示例：
当前内置提供商示例：
- Anthropic 将 Claude 专用的流式辅助工具保存在自己的 `api.ts` / `contract-api.ts` 接缝中
- OpenAI 将 provider 构建器、默认模型辅助工具以及实时 provider 构建器保存在自己的 `api.ts` 中
- OpenRouter 将 provider 构建器以及新手引导 / 配置辅助工具保存在自己的 `api.ts` 中
- Anthropic 将 Claude 专用的流式辅助函数保留在它自己的 `api.ts` / `contract-api.ts` 接口中
- OpenAI 将提供商构建器、默认模型辅助函数和实时提供商构建器保留在它自己的 `api.ts` 中
- OpenRouter 将提供商构建器以及新手引导/配置辅助函数保留在它自己的 `api.ts` 中
## 如何迁移
<Steps>
<Step title="审查 Windows 包装器回退行为">
如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，那么无法解析的 Windows
`.cmd`/`.bat` 包装器现在会默认失败关闭，除非你显式传入
`allowShellFallback: true`。
如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，当 Windows 的 `.cmd`/`.bat` 包装器无法解析时，现在会默认安全失败，除非你显式传入 `allowShellFallback: true`。
```typescript
// Before
@ -67,19 +65,18 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
// After
const program = applyWindowsSpawnProgramPolicy({
candidate,
// 仅对受信任的兼容性调用方设置此项，这些调用方会有意
// 接受经由 shell 的回退。
// Only set this for trusted compatibility callers that intentionally
// accept shell-mediated fallback.
allowShellFallback: true,
});
```
如果你的调用方并非有意依赖 shell 回退，请不要设置
`allowShellFallback`，而应改为处理抛出的错误。
如果你的调用方并不明确依赖 shell 回退，请不要设置 `allowShellFallback`，而应改为处理抛出的错误。
</Step>
<Step title="查找已弃用的导入">
在你的插件中搜索来自这两个已弃用表面的导入：
在你的插件中搜索来自这两个已弃用接口的导入：
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -89,7 +86,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
</Step>
<Step title="替换为聚焦导入">
旧表面中的每个导出，都映射到一个特定的现代导入路径：
旧接口中的每个导出都对应一个特定的现代导入路径：
```typescript
// Before (deprecated backwards-compatibility layer)
@ -105,7 +102,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```
对于宿主侧辅助工具，请使用注入的插件运行时，而不是直接导入：
对于宿主侧辅助函数，请使用注入的插件运行时，而不是直接导入：
```typescript
// Before (deprecated extension-api bridge)
@ -116,9 +113,9 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
其他旧版桥接辅助工具也适用相同模式：
其他旧版桥接辅助函数同样适用这一模式：
| 旧导入 | 现代等价项 |
| 旧导入 | 现代等价方式 |
| --- | --- |
| `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` |
| `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |
@ -143,198 +140,195 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
<Accordion title="常见导入路径表">
| 导入路径 | 用途 | 关键导出 |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` |
| `plugin-sdk/core` | 用于渠道入口定义 / 构建器的旧版伞形重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/plugin-entry` | 规范的插件入口辅助函数 | `definePluginEntry` |
| `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | 单 provider 入口辅助工具 | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-entry` | 单提供商入口辅助函数 | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 导入安全的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 |
| `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表 / 配置 / 操作 gate 辅助工具 |
| `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 |
| `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 |
| `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表 / 账户操作辅助工具 |
| `plugin-sdk/setup` | 共享的设置向导辅助函数 | Allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | 设置时运行时辅助函数 | 可安全导入的设置补丁适配器、lookup-note 辅助函数、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 |
| `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助函数 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置工具辅助函数 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账号辅助函数 | 账号列表/配置/操作门控辅助函数 |
| `plugin-sdk/account-id` | account-id 辅助函数 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 |
| `plugin-sdk/account-resolution` | 账号查找辅助函数 | 账号查找 + 默认回退辅助函数 |
| `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` |
| `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入连线 | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 渠道配置 schema 类型 |
| `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复 / 冲突校验 |
| `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | 账户状态跟踪 | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope 构建器辅助工具 |
| `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 |
| `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助工具 |
| `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 |
| `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份 / 发送委托辅助工具 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 |
| `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧字段布局的 agent 媒体负载构建器 |
| `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助函数 | 命令名规范化、描述裁剪、重复/冲突校验 |
| `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | 账号状态跟踪 | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | 入站 envelope 辅助函数 | 共享路由 + envelope 构建器辅助函数 |
| `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助函数 | 共享记录与分发辅助函数 |
| `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助函数 |
| `plugin-sdk/outbound-media` | 出站媒体辅助函数 | 共享出站媒体加载 |
| `plugin-sdk/outbound-runtime` | 出站运行时辅助函数 | 出站身份/发送委托辅助函数 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助函数 | 线程绑定生命周期和适配器辅助函数 |
| `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` | 窄范围运行时环境辅助工具 | Logger / 运行时环境、超时、重试和退避辅助工具 |
| `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / hooks / http / 交互式辅助工具 |
| `plugin-sdk/hook-runtime` | Hook 管道辅助工具 | 共享 webhook / 内部 hook 管道辅助工具 |
| `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` | 配置辅助工具 | 配置加载 / 写入辅助工具 |
| `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-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复负载辅助工具 |
| `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信 gate、外部内容和 secret 收集辅助工具 |
| `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 |
| `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定 dispatcher、受保护 fetch、SSRF 策略辅助工具 |
| `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | 诊断 gate 辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 |
| `plugin-sdk/fetch-runtime` | 包装的 fetch / 代理辅助工具 | `resolveFetch`、代理辅助工具 |
| `plugin-sdk/host-runtime` | 宿主规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 |
| `plugin-sdk/runtime` | 宽范围运行时辅助函数 | 运行时/日志/备份/插件安装辅助函数 |
| `plugin-sdk/runtime-env` | 窄范围运行时环境辅助函数 | Logger/运行时环境、超时、重试和退避辅助函数 |
| `plugin-sdk/plugin-runtime` | 共享插件运行时辅助函数 | 插件命令/hooks/http/交互式辅助函数 |
| `plugin-sdk/hook-runtime` | hook 管道辅助函数 | 共享 webhook/内部 hook 管道辅助函数 |
| `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` | 配置辅助函数 | 配置加载/写入辅助函数 |
| `plugin-sdk/telegram-command-config` | Telegram 命令辅助函数 | 当内置 Telegram 契约接口不可用时，提供稳定回退的 Telegram 命令校验辅助函数 |
| `plugin-sdk/approval-runtime` | 审批提示辅助函数 | exec/插件审批载荷、审批能力/profile 辅助函数、原生审批路由/运行时辅助函数 |
| `plugin-sdk/approval-auth-runtime` | 审批认证辅助函数 | approver 解析、同聊天操作认证 |
| `plugin-sdk/approval-client-runtime` | 审批客户端辅助函数 | 原生 exec 审批 profile/filter 辅助函数 |
| `plugin-sdk/approval-delivery-runtime` | 审批投递辅助函数 | 原生审批能力/投递适配器 |
| `plugin-sdk/approval-native-runtime` | 审批目标辅助函数 | 原生审批目标/账号绑定辅助函数 |
| `plugin-sdk/approval-reply-runtime` | 审批回复辅助函数 | exec/插件审批回复载荷辅助函数 |
| `plugin-sdk/security-runtime` | 安全辅助函数 | 共享信任、私信门控、外部内容和密钥收集辅助函数 |
| `plugin-sdk/ssrf-policy` | SSRF 策略辅助函数 | 主机 allowlist 和私有网络策略辅助函数 |
| `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助函数 | pinned-dispatcher、受保护 fetch、SSRF 策略辅助函数 |
| `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/host-runtime` | 主机规范化辅助函数 | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | 重试辅助函数 | `RetryConfig`, `retryAsync`、策略运行器 |
| `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | allowlist 输入映射 | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | 命令 gate 和命令表面辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 |
| `plugin-sdk/secret-input` | Secret 输入解析 | Secret 输入辅助工具 |
| `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标工具 |
| `plugin-sdk/webhook-request-guards` | webhook 请求体守卫辅助工具 | 请求体读取 / 限制辅助工具 |
| `plugin-sdk/command-auth` | 命令门控和命令接口辅助函数 | `resolveControlCommandGate`、发送者授权辅助函数、命令注册表辅助函数 |
| `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助函数 |
| `plugin-sdk/webhook-ingress` | webhook 请求辅助函数 | webhook 目标工具 |
| `plugin-sdk/webhook-request-guards` | webhook 请求体保护辅助函数 | 请求体读取/限制辅助函数 |
| `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 |
| `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | 完成 + provider 分发辅助工具 |
| `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助函数 | 完成 + 提供商分发辅助函数 |
| `plugin-sdk/reply-history` | 回复历史辅助函数 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本 / markdown 分块辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 |
| `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 |
| `plugin-sdk/routing` | 路由 / session-key 辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、session-key 规范化辅助工具 |
| `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道 / 账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 |
| `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 |
| `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/reply-chunking` | 回复分块辅助函数 | 文本/markdown 分块辅助函数 |
| `plugin-sdk/session-store-runtime` | 会话存储辅助函数 | 存储路径 + updated-at 辅助函数 |
| `plugin-sdk/state-paths` | 状态路径辅助函数 | 状态和 OAuth 目录辅助函数 |
| `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/run-command` | 定时命令辅助函数 | 带规范化 stdout/stderr 的定时命令运行器 |
| `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 |
| `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 |
| `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 |
| `plugin-sdk/logging-core` | 日志辅助工具 | 子系统 logger 和脱敏辅助工具 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 |
| `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 |
| `plugin-sdk/provider-setup` | 精选的本地 / 自托管 provider 设置辅助工具 | 自托管 provider 发现 / 配置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管 provider 设置辅助工具 | 相同的自托管 provider 发现 / 配置辅助工具 |
| `plugin-sdk/provider-auth-runtime` | provider 运行时认证辅助工具 | 运行时 API key 解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key 新手引导 / 配置文件写入辅助工具 |
| `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result 构建器 |
| `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 |
| `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider 认证环境变量查找辅助工具 |
| `plugin-sdk/provider-model-shared` | 共享 provider 模型 / replay 辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider endpoint 辅助工具，以及 model-id 规范化辅助工具 |
| `plugin-sdk/provider-catalog-shared` | 共享 provider catalog 辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 |
| `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP / endpoint 能力辅助工具 |
| `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册 / 缓存辅助工具 |
| `plugin-sdk/provider-web-search` | provider web-search 辅助工具 | web-search provider 注册 / 缓存 / 配置辅助工具 |
| `plugin-sdk/provider-tools` | provider 工具 / schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | provider 用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`，以及其他 provider 用量辅助工具 |
| `plugin-sdk/provider-stream` | provider 流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助工具 |
| `plugin-sdk/temp-path` | 临时路径辅助函数 | 共享临时下载路径辅助函数 |
| `plugin-sdk/logging-core` | 日志辅助函数 | 子系统 logger 和脱敏辅助函数 |
| `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 key 解析辅助函数 |
| `plugin-sdk/provider-auth-api-key` | 提供商 API key 设置辅助函数 | API key 新手引导/profile 写入辅助函数 |
| `plugin-sdk/provider-auth-result` | 提供商 auth-result 辅助函数 | 标准 OAuth auth-result 构建器 |
| `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助函数 | 共享交互式登录辅助函数 |
| `plugin-sdk/provider-env-vars` | 提供商环境变量辅助函数 | 提供商认证环境变量查找辅助函数 |
| `plugin-sdk/provider-model-shared` | 共享提供商模型/重放辅助函数 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助函数，以及 model-id 规范化辅助函数 |
| `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助函数 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助函数 |
| `plugin-sdk/provider-http` | 提供商 HTTP 辅助函数 | 通用提供商 HTTP/端点能力辅助函数 |
| `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助函数 | web-fetch 提供商注册/缓存辅助函数 |
| `plugin-sdk/provider-web-search` | 提供商 web-search 辅助函数 | web-search 提供商注册/缓存/配置辅助函数 |
| `plugin-sdk/provider-tools` | 提供商工具/schema 兼容辅助函数 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | 提供商用量辅助函数 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他提供商用量辅助函数 |
| `plugin-sdk/provider-stream` | 提供商流包装辅助函数 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装辅助函数 |
| `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取 / 转换 / 存储辅助工具，以及媒体负载构建器 |
| `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像 / 音频辅助工具导出 |
| `plugin-sdk/text-runtime` | 共享文本辅助工具 | 去除 assistant 可见文本、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本 / 日志辅助工具 |
| `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的 directive、注册表和校验辅助工具 |
| `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、directive、规范化 |
| `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型和注册表辅助工具 |
| `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型和注册表辅助工具 |
| `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助工具 |
| `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider / request / result 类型 |
| `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 |
| `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化 / 归约 |
| `plugin-sdk/media-runtime` | 共享媒体辅助函数 | 媒体获取/转换/存储辅助函数，以及媒体载荷构建器 |
| `plugin-sdk/media-understanding` | 媒体理解辅助函数 | 媒体理解提供商类型，以及面向提供商的图像/音频辅助函数导出 |
| `plugin-sdk/text-runtime` | 共享文本辅助函数 | 去除智能体可见文本、markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数、安全文本工具，以及相关文本/日志辅助函数 |
| `plugin-sdk/text-chunking` | 文本分块辅助函数 | 出站文本分块辅助函数 |
| `plugin-sdk/speech` | 语音辅助函数 | 语音提供商类型，以及面向提供商的指令、注册表和校验辅助函数 |
| `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、规范化 |
| `plugin-sdk/realtime-transcription` | 实时转录辅助函数 | 提供商类型和注册表辅助函数 |
| `plugin-sdk/realtime-voice` | 实时语音辅助函数 | 提供商类型和注册表辅助函数 |
| `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助函数 |
| `plugin-sdk/music-generation` | 音乐生成辅助函数 | 音乐生成提供商/请求/结果类型 |
| `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 |
| `plugin-sdk/video-generation` | 视频生成辅助函数 | 视频生成提供商/请求/结果类型 |
| `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 |
| `plugin-sdk/interactive-runtime` | 交互式回复辅助函数 | 交互式回复载荷规范化/归约 |
| `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道 config-schema 原语 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 |
| `plugin-sdk/channel-plugin-common` | 共享渠道前导 | 共享渠道插件前导导出 |
| `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照 / 摘要辅助工具 |
| `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑 / 读取辅助工具 |
| `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 |
| `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证 / 守卫辅助工具 |
| `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态辅助工具原语 |
| `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 辅助工具 | memory manager / config / file / CLI 辅助工具表面 |
| `plugin-sdk/memory-core-engine-runtime` | Memory engine 运行时门面 | Memory index / search 运行时门面 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入辅助函数 | 渠道配置写入授权辅助函数 |
| `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 |
| `plugin-sdk/channel-status` | 渠道状态辅助函数 | 共享渠道状态快照/摘要辅助函数 |
| `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助函数 | allowlist 配置编辑/读取辅助函数 |
| `plugin-sdk/group-access` | 群组访问辅助函数 | 共享群组访问决策辅助函数 |
| `plugin-sdk/direct-dm` | 直接私信辅助函数 | 共享直接私信认证/保护辅助函数 |
| `plugin-sdk/extension-shared` | 共享扩展辅助函数 | 被动渠道/状态辅助原语 |
| `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 辅助函数 | Memory manager/config/file/CLI 辅助接口 |
| `plugin-sdk/memory-core-engine-runtime` | Memory engine 运行时门面 | Memory index/search 运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine | Memory host foundation engine 导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding engine | Memory host embedding engine 导出 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine | Memory host QMD engine 导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine | Memory host storage engine 导出 |
| `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 | Memory host 多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 | Memory host 查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 | Memory host secret 辅助工具 |
| `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 | Memory host 状态辅助工具 |
| `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时 | Memory host CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时 | Memory host 核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助工具 | Memory host 文件 / 运行时辅助工具 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | memory-lancedb 辅助工具表面 |
| `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mocks |
| `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助函数 | Memory host 多模态辅助函数 |
| `plugin-sdk/memory-core-host-query` | Memory host 查询辅助函数 | Memory host 查询辅助函数 |
| `plugin-sdk/memory-core-host-secret` | Memory host 密钥辅助函数 | Memory host 密钥辅助函数 |
| `plugin-sdk/memory-core-host-status` | Memory host 状态辅助函数 | Memory host 状态辅助函数 |
| `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时 | Memory host CLI 运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时 | Memory host 核心运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助函数 | Memory host 文件/运行时辅助函数 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助函数 | Memory-lancedb 辅助接口 |
| `plugin-sdk/testing` | 测试工具 | 测试辅助函数和 mock |
</Accordion>
此表刻意只列出常见迁移子集，而不是完整的 SDK 表面。完整的 200+ 入口点列表位于
`scripts/lib/plugin-sdk-entrypoints.json`。
此表有意只包含常见迁移子集，而不是完整 SDK 接口。完整的 200+ 入口点列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。
该列表仍包含一些内置插件辅助工具接缝，例如
`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、
`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些导出仍会保留，以支持内置插件维护和兼容性，但它们被有意省略出了常见迁移表，也不是新插件代码的推荐目标。
该列表仍然包含一些内置插件辅助接口，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些导出仍会保留，以支持内置插件维护和兼容性，但它们被有意省略出常见迁移表，也不是新插件代码的推荐目标。
同样的规则也适用于其他内置辅助工具家族，例如：
同样的规则也适用于其他内置辅助函数族，例如：
- 浏览器支持辅助工具：`plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
- 浏览器支持辅助函数：`plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
- Matrix：`plugin-sdk/matrix*`
- LINE：`plugin-sdk/line*`
- IRC：`plugin-sdk/irc*`
- 内置辅助工具 / 插件表面，例如 `plugin-sdk/googlechat`、
- 内置辅助/插件接口，例如 `plugin-sdk/googlechat`,
`plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
`plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
`plugin-sdk/twitch`,
`plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`,
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
`plugin-sdk/thread-ownership`, 以及 `plugin-sdk/voice-call`
`plugin-sdk/thread-ownership`, 和 `plugin-sdk/voice-call`
`plugin-sdk/github-copilot-token` 当前暴露的是窄范围 token-helper
表面 `DEFAULT_COPILOT_API_BASE_URL`、
`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。
`plugin-sdk/github-copilot-token` 当前公开的是窄范围 token 辅助接口：`DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。
请使用最符合任务需求的最窄导入路径。如果你找不到某个导出，请查看 `src/plugin-sdk/` 中的源码，或到 Discord 提问。
请使用与你的任务最匹配、范围最窄的导入。如果你找不到某个导出，请查看 `src/plugin-sdk/` 中的源码，或在 Discord 中提问。
## 移除时间线
| 时间 | 会发生什么 |
| ---------------------- | ----------------------------------------------------------------------- |
| **现在** | 已弃用表面会发出运行时警告 |
| **下一个主版本** | 已弃用表面将被移除；仍在使用它们的插件将会失效 |
| **现在** | 已弃用接口会发出运行时警告 |
| **下一个主版本** | 已弃用接口将被移除；仍在使用它们的插件将会失效 |
所有核心插件都已完成迁移。外部插件应在下一个主版本之前完成迁移。
## 暂时抑制警告
## 临时抑制警告
在迁移期间设置这些环境变量：
在你进行迁移时，可以设置以下环境变量：
```bash
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
```
这只是临时逃生口，不是永久解决方案。
这是一个临时逃生舱口，不是永久解决方案。
## 相关内容
- [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建 provider 插件
- [Plugin Internals](/zh-CN/plugins/architecture) — 架构深度解析
- [Plugin Manifest](/zh-CN/plugins/manifest) — manifest schema 参考
- [入门指南](/zh-CN/plugins/building-plugins) —— 构建你的第一个插件
- [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) —— manifest schema 参考

372
docs/zh-CN/plugins/sdk-overview.md
View File

@ -1,16 +1,16 @@
---
read_when:
- 你需要知道应该从哪个 SDK 子路径导入
- 你需要知道应从哪个 SDK 子路径导入
- 你想查阅 OpenClawPluginApi 上所有注册方法的参考
- 你正在查找某个特定的 SDK 导出
sidebarTitle: SDK Overview
summary: 导入映射、注册 API 参考和 SDK 架构
title: 插件 SDK 概览
x-i18n:
generated_at: "2026-04-05T22:37:46Z"
generated_at: "2026-04-06T00:53:13Z"
model: gpt-5.4
provider: openai
source_hash: 0e023cf1ca8a35a437e27fdebde66d955771d50a3db5ffeef335c174873b1867
source_hash: d801641f26f39dc21490d2a69a337ff1affb147141360916b8b58a267e9f822a
source_path: plugins/sdk-overview.md
workflow: 15
---
@ -20,10 +20,10 @@ x-i18n:
插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考。
<Tip>
**在找操作指南？**
- 第一个插件？从 [入门指南](/zh-CN/plugins/building-plugins) 开始
- 渠道插件？参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)
- 提供商插件？参见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)
**在找操作指南吗？**
- 第一个插件？请先阅读 [入门指南](/zh-CN/plugins/building-plugins)
- 渠道插件？请参阅 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)
- 提供商插件？请参阅 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)
</Tip>
## 导入约定
@ -35,21 +35,32 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
每个子路径都是一个小型、独立的模块。这能保持快速启动，并防止循环依赖问题。对于渠道专用的入口/构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 留给更广泛的总入口表面和共享辅助函数，例如 `buildChannelConfigSchema`。
每个子路径都是一个小型、自包含模块。这样可以保持快速启动，并防止循环依赖问题。对于渠道专用的入口/构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总入口层以及诸如 `buildChannelConfigSchema` 之类的共享辅助函数。
不要添加或依赖带有提供商名称的便捷入口，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助入口。内置插件应在它们自己的 `api.ts` 或 `runtime-api.ts` barrel 文件中组合通用 SDK 子路径，而核心则应使用这些插件本地的 barrel 文件，或者在需求确实跨渠道时新增一个窄而通用的 SDK 契约。
不要添加或依赖按提供商命名的便捷接缝，例如
`openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、
`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或
带有渠道品牌的辅助接缝。内置插件应在自己的 `api.ts` 或 `runtime-api.ts`
barrel 文件中组合通用 SDK 子路径，而核心应使用这些插件本地的 barrel，
或者仅在需求确实跨渠道时才添加一个狭窄的通用 SDK 契约。
生成的导出映射仍然包含一小部分内置插件辅助入口，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅用于内置插件维护和兼容性；它们有意未出现在下面的常用表格中，也不是新第三方插件推荐的导入路径。
生成的导出映射中仍然包含一小部分内置插件辅助接缝，例如
`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、
`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些
子路径仅为内置插件维护和兼容性而存在；它们有意未列入下方的常用表格中，
也不是新第三方插件推荐的导入路径。
## 子路径参考
最常用的子路径，按用途分组。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`。
以下是最常用的子路径，按用途分组。生成的完整列表包含 200 多个子路径，
位于 `scripts/lib/plugin-sdk-entrypoints.json`。
保留的内置插件辅助子路径仍会出现在那个生成列表中。除非某个文档页面明确将其作为公共接口推荐，否则请将它们视为实现细节/兼容性表面。
保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其
标注为公开接口，否则请将它们视为实现细节/兼容性接口。
### 插件入口
| 子路径 | 关键导出 |
| 子路径 | 关键导出 |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
@ -62,20 +73,20 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | 共享设置向导辅助函数、allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`、`noteChannelLookupFailure`、`noteChannelLookupSummary`、`promptResolvedAllowFrom`、`splitSetupEntries`、`createAllowlistSetupWizardProxy`、`createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账户配置/动作门控辅助函数、默认账户回退辅助函数 |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化辅助函数 |
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 |
| `plugin-sdk/account-helpers` | 窄范围的账户列表/账户操作辅助函数 |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账号配置/动作门控辅助函数、默认账号回退辅助函数 |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`，账号 ID 规范化辅助函数 |
| `plugin-sdk/account-resolution` | 账号查找 + 默认回退辅助函数 |
| `plugin-sdk/account-helpers` | 更窄范围的账号列表/账号动作辅助函数 |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 |
| `plugin-sdk/telegram-command-config` | 带有内置契约回退的 Telegram 自定义命令规范化/校验辅助函数 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助函数，带内置契约回退 |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助函数 |
@ -89,19 +100,19 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 |
| `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助函数 |
| `plugin-sdk/channel-config-primitives` | 窄范围的渠道配置 schema 基元 |
| `plugin-sdk/channel-config-primitives` | 更窄范围的渠道配置 schema 原语 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 |
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助函数 |
| `plugin-sdk/group-access` | 共享群组访问决策辅助函数 |
| `plugin-sdk/direct-dm` | 共享直接私信认证/保护辅助函数 |
| `plugin-sdk/direct-dm` | 共享私信身份验证/保护辅助函数 |
| `plugin-sdk/interactive-runtime` | 交互式回复负载规范化/归约辅助函数 |
| `plugin-sdk/channel-inbound` | 去抖、提及匹配、envelope 辅助函数 |
| `plugin-sdk/channel-inbound` | 去抖动、提及匹配、envelope 辅助函数 |
| `plugin-sdk/channel-send-result` | 回复结果类型 |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`、`createMessageToolCardSchema` |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | 目标解析/匹配辅助函数 |
| `plugin-sdk/channel-contract` | 渠道契约类型 |
| `plugin-sdk/channel-feedback` | 反馈/反应接线 |
| `plugin-sdk/channel-feedback` | 反馈/表情反应接线 |
</Accordion>
<Accordion title="提供商子路径">
@ -109,41 +120,41 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助函数 |
| `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容自托管提供商的设置辅助函数 |
| `plugin-sdk/provider-auth-runtime` | 用于提供商插件的运行时 API 密钥解析辅助函数 |
| `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的专用设置辅助函数 |
| `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API 密钥解析辅助函数 |
| `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/配置文件写入辅助函数 |
| `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 |
| `plugin-sdk/provider-auth-login` | 用于提供商插件的共享交互式登录辅助函数 |
| `plugin-sdk/provider-env-vars` | 提供商凭证环境变量查找辅助函数 |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`、`ensureApiKeyFromOptionEnvOrPrompt`、`upsertAuthProfile` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的模型 ID 规范化辅助函数 |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-auth-result` | 标准 OAuth 身份验证结果构建器 |
| `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助函数 |
| `plugin-sdk/provider-env-vars` | 提供商身份验证环境变量查找辅助函数 |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`，共享重放策略构建器、提供商端点辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的模型 ID 规范化辅助函数 |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助函数 |
| `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助函数 |
| `plugin-sdk/provider-web-search` | Web 搜索提供商注册/缓存/配置辅助函数 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助函数 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`，Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 的 xAI 兼容性辅助函数 |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似函数 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助函数 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`，流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助函数 |
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 |
| `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助函数 |
</Accordion>
<Accordion title="认证和安全子路径">
<Accordion title="身份验证和安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 |
| `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天动作认证辅助函数 |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送方授权辅助函数 |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天动作身份验证辅助函数 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤器辅助函数 |
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账号绑定辅助函数 |
| `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助函数 |
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 |
| `plugin-sdk/command-auth-native` | 原生命令身份验证 + 原生会话目标辅助函数 |
| `plugin-sdk/command-detection` | 共享命令检测辅助函数 |
| `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助函数 |
| `plugin-sdk/command-surface` | 命令正文规范化和命令表面辅助函数 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助函数 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助函数 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助函数 |
| `plugin-sdk/secret-input` | secret 输入解析辅助函数 |
| `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助函数 |
| `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助函数 |
@ -152,54 +163,54 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
<Accordion title="运行时和存储子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助函数 |
| `plugin-sdk/runtime-env` | 窄范围的运行时环境、logger、超时、重试和退避辅助函数 |
| `plugin-sdk/runtime` | 广义的运行时/日志/备份/插件安装辅助函数 |
| `plugin-sdk/runtime-env` | 更窄范围的运行时环境、logger、超时、重试和回退辅助函数 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/交互式辅助函数 |
| `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 流水线辅助函数 |
| `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/lazy-runtime` | 延迟运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程 exec 辅助函数 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助函数 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 |
| `plugin-sdk/config-runtime` | 配置加载/写入辅助函数 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约表面不可用时也可使用 |
| `plugin-sdk/approval-runtime` | exec/插件审批辅助函数、审批能力构建器、认证/配置文件辅助函数、原生路由/运行时辅助函数 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约接口不可用时也是如此 |
| `plugin-sdk/approval-runtime` | exec/插件审批辅助函数、审批能力构建器、身份验证/配置文件辅助函数、原生路由/运行时辅助函数 |
| `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助函数、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 窄范围的回复分发/完成辅助函数 |
| `plugin-sdk/reply-dispatch-runtime` | 更窄范围的回复分发/完成辅助函数 |
| `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 窄范围的文本/Markdown 分块辅助函数 |
| `plugin-sdk/reply-chunking` | 更窄范围的文本/markdown 分块辅助函数 |
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助函数 |
| `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助函数 |
| `plugin-sdk/routing` | 路由/会话键/账户绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助函数、运行时状态默认值和问题元数据辅助函数 |
| `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` | 从 fetch/request 类输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout/stderr 结果 |
| `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 |
| `plugin-sdk/run-command` | 带超时的命令运行器，输出已规范化的 stdout/stderr 结果 |
| `plugin-sdk/param-readers` | 常用工具/CLI 参数读取器 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范化发送目标字段 |
| `plugin-sdk/temp-path` | 共享临时下载路径辅助函数 |
| `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助函数 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助函数 |
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 |
| `plugin-sdk/json-store` | 小型 JSON 状态读取/写入辅助函数 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助函数 |
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 |
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助函数 |
| `plugin-sdk/agent-config-primitives` | 窄范围的智能体运行时配置 schema 基元 |
| `plugin-sdk/agent-config-primitives` | 更窄范围的智能体运行时配置 schema 原语 |
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对 token 辅助函数 |
| `plugin-sdk/extension-shared` | 共享被动渠道和状态辅助基元 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 |
| `plugin-sdk/extension-shared` | 共享被动渠道和状态辅助原语 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助函数 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 |
| `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助函数 |
| `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助函数 |
| `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助函数 |
| `plugin-sdk/infra-runtime` | 系统事件/心跳辅助函数 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和 pinned 查找辅助函数 |
| `plugin-sdk/fetch-runtime` | 包装的 fetch、代理和 pinned 查找辅助函数 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 |
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 |
| `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助函数 |
@ -210,103 +221,110 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
<Accordion title="能力和测试子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助函数，以及媒体负载构建器 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助函数，例如移除对助手可见的文本、Markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 |
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助函数以及媒体负载构建器 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型以及面向提供商的图像/音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本/markdown/日志辅助函数，例如面向助手可见文本剥离、markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助函数 |
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助函数 |
| `plugin-sdk/speech` | 语音提供商类型以及面向提供商的 directive、注册表和校验辅助函数 |
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助函数 |
| `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助函数 |
| `plugin-sdk/realtime-transcription` | 实时转写提供商类型和注册表辅助函数 |
| `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 |
| `plugin-sdk/image-generation` | 图像生成提供商类型 |
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障切换、认证和注册表辅助函数 |
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障切换、身份验证和注册表辅助函数 |
| `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 |
| `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 |
| `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 |
| `plugin-sdk/video-generation-core` | 共享视频生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 |
| `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助函数 |
| `plugin-sdk/webhook-path` | webhook 路径规范化辅助函数 |
| `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助函数 |
| `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="内存子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助表面，用于 manager/config/file/CLI 辅助函数 |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于 manager/config/file/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-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` | 内存主机 secret 辅助函数 |
| `plugin-sdk/memory-core-host-status` | 内存主机状态辅助函数 |
| `plugin-sdk/memory-core-host-runtime-cli` | 内存主机 CLI 运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-core` | 内存主机核心运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-files` | 内存主机文件/运行时辅助函数 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助表面 |
| `plugin-sdk/memory-core-host-engine-foundation` | 内存宿主基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | 内存宿主嵌入引擎导出 |
| `plugin-sdk/memory-core-host-engine-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` | 内存宿主 secret 辅助函数 |
| `plugin-sdk/memory-core-host-status` | 内存宿主状态辅助函数 |
| `plugin-sdk/memory-core-host-runtime-cli` | 内存宿主 CLI 运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-core` | 内存宿主核心运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-files` | 内存宿主文件/运行时辅助函数 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 |
</Accordion>
<Accordion title="保留的内置辅助子路径">
| 系列 | 当前子路径 | 预期用途 |
| 家族 | 当前子路径 | 预期用途 |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` | 内置 Browser 插件支持辅助函数（`browser-support` 仍然是兼容性 barrel） |
| Matrix | `plugin-sdk/matrix`、`plugin-sdk/matrix-helper`、`plugin-sdk/matrix-runtime-heavy`、`plugin-sdk/matrix-runtime-shared`、`plugin-sdk/matrix-runtime-surface`、`plugin-sdk/matrix-surface`、`plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时表面 |
| Line | `plugin-sdk/line`、`plugin-sdk/line-core`、`plugin-sdk/line-runtime`、`plugin-sdk/line-surface` | 内置 LINE 辅助/运行时表面 |
| IRC | `plugin-sdk/irc`、`plugin-sdk/irc-surface` | 内置 IRC 辅助表面 |
| 渠道专用辅助函数 | `plugin-sdk/googlechat`、`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles`、`plugin-sdk/bluebubbles-policy`、`plugin-sdk/mattermost`、`plugin-sdk/mattermost-policy`、`plugin-sdk/feishu-conversation`、`plugin-sdk/msteams`、`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、`plugin-sdk/twitch` | 内置渠道兼容/辅助入口 |
| 认证/插件专用辅助函数 | `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、`plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`、`plugin-sdk/voice-call` | 内置功能/插件辅助入口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助函数（`browser-support` 仍是兼容性 barrel） |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时接口 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时接口 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 |
| 渠道专用辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助接缝 |
| 身份验证/插件专用辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## 注册 API
`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，它包含以下方法：
`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，包含以下
方法：
### 能力注册
| 方法 | 注册内容 |
| 方法 | 注册内容 |
| ------------------------------------------------ | -------------------------------- |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 |
| `api.registerRealtimeVoiceProvider(...)` | 双向实时语音会话 |
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
| `api.registerImageGenerationProvider(...)` | 图像生成 |
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 |
| `api.registerWebSearchProvider(...)` | Web 搜索 |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转写 |
| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 |
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
| `api.registerImageGenerationProvider(...)` | 图像生成 |
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
| `api.registerWebFetchProvider(...)` | Web 抓取 / scrape 提供商 |
| `api.registerWebSearchProvider(...)` | Web 搜索 |
### 工具和命令
| 方法 | 注册内容 |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） |
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
| 方法 | 注册内容 |
| ----------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | 智能体工具（必需，或 `{ optional: true }`） |
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
### 基础设施
| 方法 | 注册内容 |
| ---------------------------------------------- | --------------------- |
| `api.registerHook(events, handler, opts?)` | 事件 hook |
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 |
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
| `api.registerService(service)` | 后台服务 |
| `api.registerInteractiveHandler(registration)` | 交互处理器 |
| 方法 | 注册内容 |
| -------------------------------------------- | --------------------- |
| `api.registerHook(events, handler, opts?)` | 事件 hook |
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 |
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
| `api.registerService(service)` | 后台服务 |
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件拥有的方法，优先使用插件专属前缀。
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、
`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的
Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件专属前缀。
### CLI 注册元数据
`api.registerCli(registrar, opts?)` 接受两种顶层元数据：
`api.registerCli(registrar, opts?)` 接受两类顶层元数据：
- `commands`：由注册器拥有的显式命令根
- `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析时命令描述符
- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析期命令描述符
如果你希望插件命令在正常的根 CLI 路径中保持惰性加载，请提供 `descriptors`，覆盖该注册器公开的每个顶层命令根。
如果你希望插件命令在正常的根 CLI 路径中保持延迟加载，请提供
`descriptors`，覆盖该注册器暴露的每个顶层命令根。
```typescript
api.registerCli(
@ -318,7 +336,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
description: "管理 Matrix 账户、验证、设备和配置文件状态",
description: "管理 Matrix 账号、验证、设备和配置文件状态",
hasSubcommands: true,
},
],
@ -326,60 +344,65 @@ api.registerCli(
);
```
仅在你不需要惰性根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会安装带描述符支持的占位符用于解析时惰性加载。
仅当你不需要延迟根 CLI 注册时，才单独使用 `commands`。这种预加载兼容路径
仍受支持，但它不会安装基于描述符的占位符来实现解析期延迟加载。
### 独占槽位
| 方法 | 注册内容 |
| ------------------------------------------ | ------------------------------------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个处于活动状态） |
| `api.registerMemoryPromptSection(builder)` | 内存提示词区段构建器 |
| `api.registerMemoryFlushPlan(resolver)` | 内存刷新计划解析器 |
| `api.registerMemoryRuntime(runtime)` | 内存运行时适配器 |
| 方法 | 注册内容 |
| ---------------------------------------- | -------------------------------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只能启用一个） |
| `api.registerMemoryPromptSection(builder)` | 内存提示词区段构建器 |
| `api.registerMemoryFlushPlan(resolver)` | 内存刷新计划解析器 |
| `api.registerMemoryRuntime(runtime)` | 内存运行时适配器 |
### 内存嵌入适配器
| 方法 | 注册内容 |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的内存嵌入适配器 |
| 方法 | 注册内容 |
| ---------------------------------------------- | ------------------------------------------ |
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的内存嵌入适配器 |
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 仅供内存插件独占使用。
- `registerMemoryEmbeddingProvider` 允许活动内存插件注册一个或多个嵌入适配器 ID（例如 `openai`、`gemini` 或自定义的插件定义 ID）。
- 用户配置，例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`，会根据这些已注册的适配器 ID 进行解析。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和
`registerMemoryRuntime` 是内存插件专属的独占项。
- `registerMemoryEmbeddingProvider` 允许活动内存插件注册一个或多个嵌入适配器
ID（例如 `openai`、`gemini` 或自定义的插件定义 ID）。
- 用户配置，例如 `agents.defaults.memorySearch.provider` 和
`agents.defaults.memorySearch.fallback`，会针对这些已注册的适配器 ID
进行解析。
### 事件和生命周期
| 方法 | 作用 |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
| `api.onConversationBindingResolved(handler)` | 会话绑定回调 |
| 方法 | 作用 |
| ------------------------------------------ | ------------------------ |
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
| `api.onConversationBindingResolved(handler)` | 会话绑定回调 |
### Hook 决策语义
- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置了它，低优先级处理器就会被跳过。
- `before_tool_call`：返回 `{ block: false }` 会被视为未做决策（等同于省略 `block`），而不是覆盖。
- `before_install`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置了它，低优先级处理器就会被跳过。
- `before_install`：返回 `{ block: false }` 会被视为未做决策（等同于省略 `block`），而不是覆盖。
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任意处理器声明接管分发，低优先级处理器和默认模型分发路径都会被跳过。
- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任意处理器设置了它，低优先级处理器就会被跳过。
- `message_sending`：返回 `{ cancel: false }` 会被视为未做决策（等同于省略 `cancel`），而不是覆盖。
- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。
- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
- `before_install`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。
- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任意处理器声明已接管分发，就会跳过更低优先级的处理器以及默认模型分发路径。
- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。
- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。
### API 对象字段
| 字段 | 类型 | 描述 |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | 插件 ID |
| `api.name` | `string` | 显示名称 |
| `api.version` | `string?` | 插件版本（可选） |
| `api.description` | `string?` | 插件描述（可选） |
| `api.source` | `string` | 插件源码路径 |
| `api.rootDir` | `string?` | 插件根目录（可选） |
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动内存运行时快照） |
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量窗口 |
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
| 字段 | 类型 | 说明 |
| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- |
| `api.id` | `string` | 插件 ID |
| `api.name` | `string` | 显示名称 |
| `api.version` | `string?` | 插件版本（可选） |
| `api.description` | `string?` | 插件说明（可选） |
| `api.source` | `string` | 插件源路径 |
| `api.rootDir` | `string?` | 插件根目录（可选） |
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动中的内存运行时快照） |
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | 作用域 logger（`debug`, `info`, `warn`, `error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是轻量级的完整入口启动/设置前窗口 |
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
## 内部模块约定
@ -387,36 +410,47 @@ api.registerCli(
```
my-plugin/
api.ts # 供外部使用者使用的公共导出
api.ts # 面向外部使用者的公开导出
runtime-api.ts # 仅供内部使用的运行时导出
index.ts # 插件入口点
setup-entry.ts # 仅用于轻量设置的入口（可选）
setup-entry.ts # 轻量级仅设置入口（可选）
```
<Warning>
不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>` 导入你自己的插件。
应通过 `./api.ts` 或 `./runtime-api.ts` 进行内部导入。SDK 路径仅是外部契约。
内部导入应通过 `./api.ts` 或 `./runtime-api.ts`。SDK 路径仅是对外契约。
</Warning>
门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）现在会在 OpenClaw 已运行时优先使用活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上解析得到的配置文件。
通过门面加载的内置插件公开接口（`api.ts`、`runtime-api.ts`、
`index.ts`、`setup-entry.ts` 以及类似的公开入口文件）现在在
OpenClaw 已运行时会优先使用活动运行时配置快照。如果尚不存在运行时快照，
它们会回退到磁盘上已解析的配置文件。
当某个辅助函数明确属于提供商专用、尚不适合放入通用 SDK 子路径时，提供商插件也可以公开一个窄范围的插件本地契约 barrel。当前内置示例：Anthropic 提供商将其 Claude 流辅助函数保留在自己的公共 `api.ts` / `contract-api.ts` 入口中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升为通用 `plugin-sdk/*` 契约。
提供商插件在某个辅助函数明确属于提供商专有、且暂时还不适合放入通用 SDK
子路径时，也可以暴露一个更窄的插件本地契约 barrel。当前的内置示例：
Anthropic 提供商将其 Claude 流辅助函数保留在自己的公开
`api.ts` / `contract-api.ts` 接缝中，而不是将 Anthropic beta-header 和
`service_tier` 逻辑提升为通用 `plugin-sdk/*` 契约。
其他当前内置示例：
其他当前的内置示例：
- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助函数和实时提供商构建器
- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/配置辅助函数
- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、
默认模型辅助函数和实时提供商构建器
- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及
新手引导/配置辅助函数
<Warning>
扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。
如果某个辅助函数确实需要共享，应将其提升到中立的 SDK 子路径，例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他面向能力的表面，而不是让两个插件彼此耦合。
扩展生产代码同样应避免使用 `openclaw/plugin-sdk/<other-plugin>`
导入。如果某个辅助函数确实需要共享，请将它提升到中立的 SDK 子路径，
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他
面向能力的接口，而不是让两个插件彼此耦合。
</Warning>
## 相关内容
- [入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` 选项
- [运行时辅助函数](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考
- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema
- [运行时](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考
- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、manifest、配置 schema
- [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则
- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移
- [插件内部机制](/zh-CN/plugins/architecture) — 深入的架构和能力模型
- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用接口迁移
- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构和能力模型

77
docs/zh-CN/providers/google.md
View File

@ -1,21 +1,22 @@
---
read_when:
- 你想将 Google Gemini 模型与 OpenClaw 一起使用
- 你想在 OpenClaw 中使用 Google Gemini 模型
- 你需要 API 密钥认证流程
summary: Google Gemini 设置（API 密钥、图像生成、媒体理解、Web 搜索）
summary: Google Gemini 设置（API 密钥、图像生成、媒体理解、网页搜索）
title: Google（Gemini）
x-i18n:
generated_at: "2026-04-05T22:22:59Z"
generated_at: "2026-04-06T00:51:57Z"
model: gpt-5.4
provider: openai
source_hash: c0dc6413ca67e0fe274c7fc1182cf220252aae31266a72e0b251a319d4dd286e
source_hash: 358d33a68275b01ebd916a3621dd651619cb9a1d062e2fb6196a7f3c501c015a
source_path: providers/google.md
workflow: 15
---
# Google（Gemini）
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及通过 Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）和 Web 搜索。
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并通过
Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）和网页搜索功能。
- 提供商：`google`
- 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
@ -52,24 +53,28 @@ openclaw onboard --non-interactive \
## 功能
| 能力 | 支持情况 |
| 功能 | 支持情况 |
| ---------------------- | ----------------- |
| 聊天补全 | 是 |
| 图像生成 | 是 |
| 音乐生成 | 是 |
| 图像理解 | 是 |
| 音频转录 | 是 |
| 音频转写 | 是 |
| 视频理解 | 是 |
| Web 搜索（Grounding） | 是 |
| 网页搜索（Grounding） | 是 |
| 思考/推理 | 是（Gemini 3.1+） |
## 直接复用 Gemini 缓存
对于直接调用 Gemini API 的运行（`api: "google-generative-ai"`），OpenClaw 现在会将已配置的 `cachedContent` 句柄透传给 Gemini 请求。
对于直接使用 Gemini API 的运行（`api: "google-generative-ai"`），OpenClaw 现在会
将已配置的 `cachedContent` 句柄传递给 Gemini 请求。
- 可使用 `cachedContent` 或旧版 `cached_content` 为每个模型或全局配置参数
- 如果两者同时存在，则以 `cachedContent` 为准
- 可通过 `cachedContent` 或旧版的 `cached_content`
为每个模型或全局参数进行配置
- 如果两者同时存在，则 `cachedContent` 优先
- 示例值：`cachedContents/prebuilt-context`
- Gemini 的缓存命中用量会从上游的 `cachedContentTokenCount` 规范化为 OpenClaw 的 `cacheRead`
- Gemini 的缓存命中用量会从上游的 `cachedContentTokenCount`
统一归一化到 OpenClaw 的 `cacheRead`
示例：
@ -91,14 +96,16 @@ openclaw onboard --non-interactive \
## 图像生成
内置的 `google` 图像生成提供商默认使用 `google/gemini-3.1-flash-image-preview`。
内置的 `google` 图像生成提供商默认使用
`google/gemini-3.1-flash-image-preview`。
- 也支持 `google/gemini-3-pro-image-preview`
- 生成：每次请求最多 4 张图像
- 编辑模式：已启用，最多支持 5 张输入图像
- 几何控制：`size`、`aspectRatio` 和 `resolution`
图像生成、媒体理解和 Gemini Grounding 都保持使用 `google` 提供商 id。
图像生成、媒体理解和 Gemini Grounding 都继续使用
`google` 提供商 id。
要将 Google 用作默认图像提供商：
@ -114,11 +121,13 @@ openclaw onboard --non-interactive \
}
```
有关共享工具参数、提供商选择和故障转移行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。
参见 [图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、
提供商选择和故障切换行为。
## 视频生成
内置的 `google` 插件还会通过共享的 `video_generate` 工具注册视频生成功能。
内置的 `google` 插件还通过共享的
`video_generate` 工具注册了视频生成功能。
- 默认视频模型：`google/veo-3.1-fast-generate-preview`
- 模式：文生视频、图生视频，以及单视频参考流程
@ -139,8 +148,40 @@ openclaw onboard --non-interactive \
}
```
有关共享工具参数、提供商选择和故障转移行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。
参见 [视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、
提供商选择和故障切换行为。
## 音乐生成
内置的 `google` 插件还通过共享的
`music_generate` 工具注册了音乐生成功能。
- 默认音乐模型：`google/lyria-3-clip-preview`
- 也支持 `google/lyria-3-pro-preview`
- 提示词控制：`lyrics` 和 `instrumental`
- 输出格式：默认 `mp3`，此外 `google/lyria-3-pro-preview` 还支持 `wav`
- 参考输入：最多 10 张图像
- 基于会话的运行会通过共享的任务/状态流程分离执行，包括 `action: "status"`
要将 Google 用作默认音乐提供商：
```json5
{
agents: {
defaults: {
musicGenerationModel: {
primary: "google/lyria-3-clip-preview",
},
},
},
}
```
参见 [音乐生成](/zh-CN/tools/music-generation)，了解共享工具参数、
提供商选择和故障切换行为。
## 环境说明
如果 Gateway 网关 作为守护进程运行（launchd/systemd），请确保该进程可以访问 `GEMINI_API_KEY`（例如，在 `~/.openclaw/.env` 中设置，或通过 `env.shellEnv` 提供）。
如果 Gateway 网关 以守护进程方式运行（launchd/systemd），请确保 `GEMINI_API_KEY`
对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过
`env.shellEnv` 提供）。

34
docs/zh-CN/providers/index.md
View File

@ -1,27 +1,28 @@
---
read_when:
- 你想选择一个模型提供商
- 你需要快速了解支持的 LLM 后端
- 你需要支持的 LLM 后端的快速概览
summary: OpenClaw 支持的模型提供商（LLM）
title: 提供商目录
x-i18n:
generated_at: "2026-04-06T00:47:08Z"
generated_at: "2026-04-06T00:52:07Z"
model: gpt-5.4
provider: openai
source_hash: 24b3f2b6edee49fbce7762a22ee03308ef9cd62c61de114b0ab5d61fb3919c26
source_hash: 17a1996056cad47f0bcf9b199384f44c5ffcb6a21de40c4f7ac3bf9164201ff1
source_path: providers/index.md
workflow: 15
---
# 模型提供商
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份验证，然后将默认模型设置为 `provider/model`。
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证，然后将
默认模型设置为 `provider/model`。
在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）等）？请参阅 [Channels](/zh-CN/channels)。
在寻找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/等）？参见 [Channels](/zh-CN/channels)。
## 快速开始
1. 使用提供商完成身份验证（通常通过 `openclaw onboard`）。
1. 使用提供商完成认证（通常通过 `openclaw onboard`）。
2. 设置默认模型：
```json5
@ -37,16 +38,16 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
- [Anthropic（API + Claude CLI）](/zh-CN/providers/anthropic)
- [BytePlus（国际版）](/zh-CN/concepts/model-providers#byteplus-international)
- [Chutes](/zh-CN/providers/chutes)
- [ComfyUI](/providers/comfy)
- [ComfyUI](/zh-CN/providers/comfy)
- [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)
- [DeepSeek](/zh-CN/providers/deepseek)
- [fal](/zh-CN/providers/fal)
- [Fireworks](/zh-CN/providers/fireworks)
- [GitHub Copilot](/zh-CN/providers/github-copilot)
- [GLM 模型](/zh-CN/providers/glm)
- [GLM models](/zh-CN/providers/glm)
- [Google（Gemini）](/zh-CN/providers/google)
- [Groq（LPU 推理）](/zh-CN/providers/groq)
- [Hugging Face（推理）](/zh-CN/providers/huggingface)
- [Hugging Face（Inference）](/zh-CN/providers/huggingface)
- [Kilocode](/zh-CN/providers/kilocode)
- [LiteLLM（统一 Gateway 网关）](/zh-CN/providers/litellm)
- [MiniMax](/zh-CN/providers/minimax)
@ -58,7 +59,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
- [OpenCode](/zh-CN/providers/opencode)
- [OpenCode Go](/zh-CN/providers/opencode-go)
- [OpenRouter](/zh-CN/providers/openrouter)
- [Perplexity（网络搜索）](/zh-CN/providers/perplexity-provider)
- [Perplexity（网页搜索）](/zh-CN/providers/perplexity-provider)
- [Qianfan](/zh-CN/providers/qianfan)
- [Qwen Cloud](/zh-CN/providers/qwen)
- [Runway](/zh-CN/providers/runway)
@ -66,7 +67,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
- [StepFun](/zh-CN/providers/stepfun)
- [Synthetic](/zh-CN/providers/synthetic)
- [Together AI](/zh-CN/providers/together)
- [Venice（Venice AI，注重隐私）](/zh-CN/providers/venice)
- [Venice（Venice AI，以隐私为重点）](/zh-CN/providers/venice)
- [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)
- [vLLM（本地模型）](/zh-CN/providers/vllm)
- [Volcengine（Doubao）](/zh-CN/providers/volcengine)
@ -78,15 +79,16 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
- [其他内置变体](/zh-CN/providers/models#additional-bundled-provider-variants) - Anthropic Vertex、Copilot Proxy 和 Gemini CLI OAuth
- [图像生成](/zh-CN/tools/image-generation) - 共享的 `image_generate` 工具、提供商选择和故障切换
- [音乐生成](/tools/music-generation) - 插件提供的 `music_generate` 工具界面
- [音乐生成](/zh-CN/tools/music-generation) - 共享的 `music_generate` 工具、提供商选择和故障切换
- [视频生成](/zh-CN/tools/video-generation) - 共享的 `video_generate` 工具、提供商选择和故障切换
## 转录提供商
## 转写提供商
- [Deepgram（音频转录）](/zh-CN/providers/deepgram)
- [Deepgram（音频转写）](/zh-CN/providers/deepgram)
## 社区工具
- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请核实 Anthropic 的政策/条款）
- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请确认 Anthropic 的政策/条款）
有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。
有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，
请参见 [模型提供商](/zh-CN/concepts/model-providers)。

187
docs/zh-CN/providers/minimax.md
View File

@ -5,10 +5,10 @@ read_when:
summary: 在 OpenClaw 中使用 MiniMax 模型
title: MiniMax
x-i18n:
generated_at: "2026-04-05T22:23:23Z"
generated_at: "2026-04-06T00:52:43Z"
model: gpt-5.4
provider: openai
source_hash: 32e737d8eb9b9728ec3925f626599bb4be6d0904b6357b29c6f33a315600fef4
source_hash: 9ca35c43cdde53f6f09d9e12d48ce09e4c099cf8cbe1407ac6dbb45b1422507e
source_path: providers/minimax.md
workflow: 15
---
@ -19,14 +19,15 @@ OpenClaw 的 MiniMax 提供商默认使用 **MiniMax M2.7**。
MiniMax 还提供：
- 通过 T2A v2 内置语音合成
- 通过 `MiniMax-VL-01` 内置图像理解
- 通过 MiniMax Coding Plan 搜索 API 内置 `web_search`
- 通过 T2A v2 内置的语音合成
- 通过 `MiniMax-VL-01` 内置的图像理解
- 通过 `music-2.5+` 内置的音乐生成
- 通过 MiniMax Coding Plan 搜索 API 内置的 `web_search`
提供商划分：
提供商拆分如下：
- `minimax`：基于 API 密钥的文本提供商，另含内置图像生成、图像理解、语音和 Web 搜索
- `minimax-portal`：基于 OAuth 的文本提供商，另含内置图像生成和图像理解
- `minimax`：基于 API 密钥的文本提供商，另加内置的图像生成、图像理解、语音和网页搜索
- `minimax-portal`：基于 OAuth 的文本提供商，另加内置的图像生成和图像理解
## 模型阵容
@ -38,10 +39,10 @@ MiniMax 还提供：
MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持：
- 可控制宽高比的**文生图生成**。
- 可控制宽高比的**图生图编辑**（主体参考）。
- 每次请求最多 **9 张输出图像**。
- 每次编辑请求最多 **1 张参考图像**。
- 具有宽高比控制的**文生图生成**。
- 具有宽高比控制的**图生图编辑**（主体参考）。
- 每次请求最多生成 **9 张输出图像**。
- 每次编辑请求最多支持 **1 张参考图像**。
- 支持的宽高比：`1:1`、`16:9`、`4:3`、`3:2`、`2:3`、`3:4`、`9:16`、`21:9`。
要将 MiniMax 用于图像生成，请将其设置为图像生成提供商：
@ -58,20 +59,47 @@ MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持
该插件对文本模型使用相同的 `MINIMAX_API_KEY` 或 OAuth 认证。如果 MiniMax 已经设置完成，则无需额外配置。
`minimax` 和 `minimax-portal` 都使用相同的 `image-01` 模型注册了 `image_generate`。
基于 API 密钥的设置使用 `MINIMAX_API_KEY`；基于 OAuth 的设置则可以改用
`minimax` 和 `minimax-portal` 都会使用相同的
`image-01` 模型注册 `image_generate`。基于 API 密钥的设置使用 `MINIMAX_API_KEY`；基于 OAuth 的设置则可以改用
内置的 `minimax-portal` 认证路径。
当新手引导或 API 密钥设置写入显式的 `models.providers.minimax`
条目时，OpenClaw 会具体生成 `MiniMax-M2.7` 和
`MiniMax-M2.7-highspeed`，并带有 `input: ["text", "image"]`。
当新手引导或基于 API 密钥的设置写入显式的 `models.providers.minimax`
条目时，OpenClaw 会具体化 `MiniMax-M2.7` 和
`MiniMax-M2.7-highspeed`，并设置 `input: ["text", "image"]`。
内置的 MiniMax 文本目录本身仍然保持为仅文本元数据，
直到该显式提供商配置存在为止。图像理解则通过插件自有的
`MiniMax-VL-01` 媒体提供商单独公开。
内置的 MiniMax 文本目录本身会保持为仅文本元数据，
直到存在该显式提供商配置。图像理解则通过插件自有的 `MiniMax-VL-01` 媒体提供商单独暴露。
有关共享工具参数、提供商选择和故障切换行为，请参见
[图像生成](/zh-CN/tools/image-generation)。
参见 [图像生成](/zh-CN/tools/image-generation)，了解共享工具
参数、提供商选择和故障切换行为。
## 音乐生成
内置的 `minimax` 插件还通过共享的
`music_generate` 工具注册了音乐生成功能。
- 默认音乐模型：`minimax/music-2.5+`
- 也支持 `minimax/music-2.5` 和 `minimax/music-2.0`
- 提示词控制：`lyrics`、`instrumental`、`durationSeconds`
- 输出格式：`mp3`
- 基于会话的运行会通过共享的任务/状态流程分离执行，包括 `action: "status"`
要将 MiniMax 用作默认音乐提供商：
```json5
{
agents: {
defaults: {
musicGenerationModel: {
primary: "minimax/music-2.5+",
},
},
},
}
```
参见 [音乐生成](/zh-CN/tools/music-generation)，了解共享工具
参数、提供商选择和故障切换行为。
## 视频生成
@ -96,46 +124,48 @@ MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持
}
```
有关共享工具参数、提供商选择和故障切换行为，请参见
[视频生成](/zh-CN/tools/video-generation)。
参见 [视频生成](/zh-CN/tools/video-generation)，了解共享工具
参数、提供商选择和故障切换行为。
## 图像理解
MiniMax 插件将图像理解与文本目录分开注册：
MiniMax 插件将图像理解与文本
目录分开注册：
- `minimax`：默认图像模型 `MiniMax-VL-01`
- `minimax-portal`：默认图像模型 `MiniMax-VL-01`
- `minimax`：默认图像模型为 `MiniMax-VL-01`
- `minimax-portal`：默认图像模型为 `MiniMax-VL-01`
这就是为什么自动媒体路由即使在内置文本提供商目录仍显示为
仅文本的 M2.7 聊天引用时，也可以使用 MiniMax 图像理解。
这就是为什么自动媒体路由即使在
内置文本提供商目录仍显示为仅文本的 M2.7 聊天引用时，
也可以使用 MiniMax 图像理解。
## Web 搜索
## 网页搜索
MiniMax 插件还通过 MiniMax Coding Plan
搜索 API 注册了 `web_search`。
- 提供商 ID：`minimax`
- 提供商 id：`minimax`
- 结构化结果：标题、URL、摘要、相关查询
- 首选环境变量：`MINIMAX_CODE_PLAN_KEY`
- 可接受的环境变量别名：`MINIMAX_CODING_API_KEY`
- 兼容性回退：当 `MINIMAX_API_KEY` 已指向 coding-plan 令牌时使用它
- 兼容性回退：当 `MINIMAX_API_KEY` 已指向 coding-plan 令牌时可使用它
- 区域复用：`plugins.entries.minimax.config.webSearch.region`，然后是 `MINIMAX_API_HOST`，再然后是 MiniMax 提供商基础 URL
- 搜索始终保留在提供商 ID `minimax` 上；OAuth 中国区 / 全球设置仍可通过 `models.providers.minimax-portal.baseUrl` 间接引导区域
- 搜索始终保留在提供商 id `minimax`；OAuth 中国区/国际版设置仍可通过 `models.providers.minimax-portal.baseUrl` 间接引导区域
配置位于 `plugins.entries.minimax.config.webSearch.*` 下。
请参见 [MiniMax 搜索](/zh-CN/tools/minimax-search)。
参见 [MiniMax Search](/zh-CN/tools/minimax-search)。
## 选择一种设置方式
### MiniMax OAuth（Coding Plan）- 推荐
### MiniMax OAuth（Coding Plan） - 推荐
**最适合：** 通过 OAuth 快速设置 MiniMax Coding Plan，无需 API 密钥。
使用显式的区域 OAuth 选项进行认证：
使用明确的区域 OAuth 选项进行认证：
```bash
openclaw onboard --auth-choice minimax-global-oauth
# 或
# or
openclaw onboard --auth-choice minimax-cn-oauth
```
@ -148,7 +178,7 @@ openclaw onboard --auth-choice minimax-cn-oauth
### MiniMax M2.7（API 密钥）
**最适合：** 使用带有 Anthropic 兼容 API 的托管 MiniMax。
**最适合：** 使用与 Anthropic 兼容 API 的托管 MiniMax。
通过 CLI 配置：
@ -156,7 +186,7 @@ openclaw onboard --auth-choice minimax-cn-oauth
```bash
openclaw onboard --auth-choice minimax-global-api
# 或
# or
openclaw onboard --auth-choice minimax-cn-api
```
@ -200,16 +230,16 @@ openclaw onboard --auth-choice minimax-cn-api
}
```
在 Anthropic 兼容的流式传输路径上，OpenClaw 现在默认禁用 MiniMax
的 thinking，除非你自己明确设置了 `thinking`。MiniMax 的
流式端点会以 OpenAI 风格的 delta 分块发出 `reasoning_content`，
而不是原生的 Anthropic thinking 块，如果默认隐式启用，
可能会把内部推理泄露到可见输出中。
在与 Anthropic 兼容的流式传输路径上，OpenClaw 现在默认会禁用 MiniMax 的
thinking，除非你显式自行设置了 `thinking`。MiniMax 的
流式端点会以 OpenAI 风格的 delta 分块形式发出 `reasoning_content`，
而不是原生的 Anthropic thinking 块，
如果默认启用，可能会将内部推理泄露到可见输出中。
### 将 MiniMax M2.7 用作回退模型（示例）
**最适合：** 将你最强的最新一代模型保留为主模型，并在失败时回退到 MiniMax M2.7。
下面的示例使用 Opus 作为具体主模型；请替换为你偏好的最新一代主模型。
**最适合：** 将你最强的最新一代模型保留为主模型，在失败时回退到 MiniMax M2.7。
下面的示例使用 Opus 作为具体主模型；你可以替换为自己偏好的最新一代主模型。
```json5
{
@ -231,14 +261,14 @@ openclaw onboard --auth-choice minimax-cn-api
## 通过 `openclaw configure` 配置
使用交互式配置向导，无需编辑 JSON 即可设置 MiniMax：
使用交互式配置向导来设置 MiniMax，而无需编辑 JSON：
1. 运行 `openclaw configure`。
2. 选择 **Model/auth**。
3. 选择一个 **MiniMax** 认证选项。
4. 在提示时选择你的默认模型。
向导 / CLI 中当前可用的 MiniMax 认证选项：
向导/CLI 中当前可用的 MiniMax 认证选项：
- `minimax-global-oauth`
- `minimax-cn-oauth`
@ -247,12 +277,12 @@ openclaw onboard --auth-choice minimax-cn-api
## 配置选项
- `models.providers.minimax.baseUrl`：优先使用 `https://api.minimax.io/anthropic`（Anthropic 兼容）；`https://api.minimax.io/v1` 可选，用于 OpenAI 兼容载荷。
- `models.providers.minimax.api`：优先使用 `anthropic-messages`；`openai-completions` 可选，用于 OpenAI 兼容载荷。
- `models.providers.minimax.baseUrl`：优先使用 `https://api.minimax.io/anthropic`（与 Anthropic 兼容）；也可选用 `https://api.minimax.io/v1` 以使用与 OpenAI 兼容的负载。
- `models.providers.minimax.api`：优先使用 `anthropic-messages`；也可选用 `openai-completions` 以使用与 OpenAI 兼容的负载。
- `models.providers.minimax.apiKey`：MiniMax API 密钥（`MINIMAX_API_KEY`）。
- `models.providers.minimax.models`：定义 `id`、`name`、`reasoning`、`contextWindow`、`maxTokens`、`cost`。
- `agents.defaults.models`：为你想加入 allowlist 的模型设置别名。
- `models.mode`：如果你想在内置模型旁添加 MiniMax，请保持为 `merge`。
- `models.mode`：如果你想在内置提供商之外添加 MiniMax，请保持为 `merge`。
## 说明
@ -261,40 +291,41 @@ openclaw onboard --auth-choice minimax-cn-api
- OAuth 设置：`minimax-portal/<model>`
- 默认聊天模型：`MiniMax-M2.7`
- 备用聊天模型：`MiniMax-M2.7-highspeed`
- 在 `api: "anthropic-messages"` 下，OpenClaw 会注入
`thinking: { type: "disabled" }`，除非 thinking 已在
params / config 中被显式设置。
- `/fast on` 或 `params.fastMode: true` 会在 Anthropic 兼容流式路径上
将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
- 新手引导和直接 API 密钥设置会为两个 M2.7 变体写入显式模型定义，
并带有 `input: ["text", "image"]`
- 在显式 MiniMax 提供商配置存在之前，
内置提供商目录当前会将聊天引用公开为仅文本元数据
- 在 `api: "anthropic-messages"` 上，OpenClaw 会注入
`thinking: { type: "disabled" }`，除非在
params/config 中已经显式设置了 thinking。
- `/fast on` 或 `params.fastMode: true` 会在与 Anthropic 兼容的流式路径上，
将 `MiniMax-M2.7` 重写为
`MiniMax-M2.7-highspeed`。
- 新手引导和直接 API 密钥设置会为
两个 M2.7 变体都写入显式模型定义，并设置
`input: ["text", "image"]`
- 在存在显式 MiniMax 提供商配置之前，
内置提供商目录目前会将聊天引用显示为仅文本
元数据
- Coding Plan 用量 API：`https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains`（需要 coding plan 密钥）。
- OpenClaw 会将 MiniMax coding-plan 用量标准化为与其他提供商相同的
“% left” 显示。MiniMax 原始的 `usage_percent` / `usagePercent`
字段表示的是剩余额度，而不是已消耗额度，因此 OpenClaw 会对其取反。
如果存在按次数统计的字段，则优先使用这些字段。当 API 返回 `model_remains` 时，
OpenClaw 会优先选择聊天模型条目，并在需要时从
`start_time` / `end_time` 推导窗口标签，同时在计划标签中包含所选模型名称，
以便更容易区分 coding-plan 窗口。
- OpenClaw 会将 MiniMax coding-plan 用量归一化为与其他提供商相同的 `% left` 显示。
MiniMax 原始的 `usage_percent` / `usagePercent`
字段表示的是剩余配额，而不是已消耗配额，因此 OpenClaw 会将其反转。
如果存在基于计数的字段，则优先使用。当 API 返回 `model_remains` 时，
OpenClaw 会优先选择聊天模型条目，在需要时从
`start_time` / `end_time` 推导窗口标签，并将所选模型名称
包含在计划标签中，以便更容易区分 coding-plan 窗口。
- 用量快照会将 `minimax`、`minimax-cn` 和 `minimax-portal` 视为
同一个 MiniMax 配额面，并优先使用已存储的 MiniMax OAuth，
然后才回退到 Coding Plan 密钥环境变量。
同一个 MiniMax 配额面，并优先使用已存储的 MiniMax OAuth，然后才回退到 Coding Plan 密钥环境变量。
- 如果你需要精确的成本跟踪，请更新 `models.json` 中的定价值。
- MiniMax Coding Plan 推荐链接（9 折优惠）：[https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
- 有关提供商规则，请参见 [/concepts/model-providers](/zh-CN/concepts/model-providers)。
- 使用 `openclaw models list` 确认当前提供商 ID，然后通过
- MiniMax Coding Plan 推荐链接（九折优惠）：[https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
- 提供商规则参见 [/concepts/model-providers](/zh-CN/concepts/model-providers)。
- 使用 `openclaw models list` 确认当前提供商 id，然后通过
`openclaw models set minimax/MiniMax-M2.7` 或
`openclaw models set minimax-portal/MiniMax-M2.7` 切换。
`openclaw models set minimax-portal/MiniMax-M2.7` 进行切换。
## 故障排除
### “Unknown model: minimax/MiniMax-M2.7”
这通常意味着**MiniMax 提供商未配置**（没有匹配的
provider 条目，也没有找到 MiniMax 认证配置文件 / 环境变量密钥）。
针对这一检测问题的修复已包含在 **2026.1.12** 中。可通过以下方式修复：
这通常意味着 **MiniMax 提供商尚未配置**（没有匹配的
提供商条目，且未找到 MiniMax 认证配置文件/环境变量密钥）。此检测问题的修复已包含在 **2026.1.12** 中。可通过以下方式修复：
- 升级到 **2026.1.12**（或从源码 `main` 运行），然后重启 Gateway 网关。
- 运行 `openclaw configure` 并选择一个 **MiniMax** 认证选项，或
@ -303,13 +334,13 @@ provider 条目，也没有找到 MiniMax 认证配置文件 / 环境变量密
- 设置 `MINIMAX_API_KEY`、`MINIMAX_OAUTH_TOKEN` 或 MiniMax 认证配置文件，
以便注入匹配的提供商。
请确保模型 ID **区分大小写**：
请确保模型 id **区分大小写**：
- API 密钥路径：`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`
- OAuth 路径：`minimax-portal/MiniMax-M2.7` 或
`minimax-portal/MiniMax-M2.7-highspeed`
然后使用以下命令再次检查：
然后重新检查：
```bash
openclaw models list

153
docs/zh-CN/tools/index.md
View File

@ -1,23 +1,23 @@
---
read_when:
- 你想了解 OpenClaw 提供了哪些工具
- 你想了解 OpenClaw 提供哪些工具
- 你需要配置、允许或拒绝工具
- 你正在内置工具、Skills 和插件之间做选择
summary: OpenClaw 工具和插件概览：智能体能做什么，以及如何扩展它
title: 工具和插件
x-i18n:
generated_at: "2026-04-06T00:47:35Z"
generated_at: "2026-04-06T00:52:46Z"
model: gpt-5.4
provider: openai
source_hash: 28f287e3a137f10e8d78ad1124f1f234e32d3a079f5c8271f475f4a911d81ad7
source_hash: c09e6ba0bba59be93eec676f119ab81b51f08536744f5d91f340734a4ce531c5
source_path: tools/index.md
workflow: 15
---
# 工具和插件
智能体执行的所有超出生成文本范围的操作，都是通过**工具**完成的。
工具让智能体能够读取文件、运行命令、浏览网页、发送消息，并与设备交互。
智能体除了生成文本之外所做的一切，都是通过**工具**完成的。
工具是智能体读取文件、运行命令、浏览网页、发送消息以及与设备交互的方式。
## 工具、Skills 和插件
@ -25,27 +25,26 @@ OpenClaw 有三个协同工作的层级：
<Steps>
<Step title="工具是智能体调用的内容">
工具是智能体可以调用的类型化函数（例如 `exec`、`browser`、
`web_search`、`message`）。OpenClaw 内置了一组**内置工具**，插件也可以注册额外工具。
工具是智能体可调用的类型化函数（例如 `exec`、`browser`、
`web_search`、`message`）。OpenClaw 随附一组**内置工具**，插件也可以注册额外工具。
对智能体来说，工具是发送到模型 API 的结构化函数定义。
智能体看到的工具，是发送到模型 API 的结构化函数定义。
</Step>
<Step title="Skills 教会智能体何时以及如何使用">
Skills 是注入系统提示词中的 Markdown 文件（`SKILL.md`）。
Skills 为智能体提供上下文、约束，以及高效使用工具的分步指导。Skills 可以位于你的工作区、共享文件夹中，或随插件一起提供。
Skills 是注入到系统提示中的 Markdown 文件（`SKILL.md`）。
Skills 为智能体提供上下文、约束以及使用工具的分步指导。
Skills 可以位于你的工作区、共享文件夹中，或随插件一起提供。
[Skills 参考](/zh-CN/tools/skills) | [创建 Skills](/zh-CN/tools/creating-skills)
</Step>
<Step title="插件将一切打包在一起">
插件是一种可注册任意能力组合的软件包：
渠道、模型提供商、工具、Skills、语音、实时转录、
实时语音、媒体理解、图像生成、视频生成、
网页抓取、网页搜索等。有些插件是**核心**插件（随
OpenClaw 一起提供），另一些是**外部**插件（由社区发布到 npm）。
插件是可以注册任意能力组合的软件包：渠道、模型提供商、工具、Skills、语音、实时转录、
实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。
有些插件是**核心**插件（随 OpenClaw 一起提供），另一些是**外部**插件（由社区发布到 npm）。
[安装和配置插件](/zh-CN/tools/plugin) | [构建你自己的插件](/zh-CN/plugins/building-plugins)
@ -56,56 +55,58 @@ OpenClaw 有三个协同工作的层级：
这些工具随 OpenClaw 一起提供，无需安装任何插件即可使用：
| 工具 | 功能 | 页面 |
| Tool | 它的作用 | 页面 |
| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------- |
| `exec` / `process` | 运行 shell 命令，管理后台进程 | [Exec](/zh-CN/tools/exec) |
| `code_execution` | 运行沙箱隔离的远程 Python 分析 | [Code Execution](/zh-CN/tools/code-execution) |
| `browser` | 控制 Chromium 浏览器（导航、点击、截图） | [Browser](/zh-CN/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | 搜索网页、搜索 X 帖子、抓取页面内容 | [Web](/zh-CN/tools/web) |
| `read` / `write` / `edit` | 在工作区中执行文件 I/O | |
| `apply_patch` | 多段文件补丁 | [Apply Patch](/zh-CN/tools/apply-patch) |
| `message` | 跨所有渠道发送消息 | [Agent Send](/zh-CN/tools/agent-send) |
| `canvas` | 驱动节点 Canvas（present、eval、snapshot） | |
| `nodes` | 发现并定位已配对设备 | |
| `cron` / `gateway` | 管理定时任务；检查、修补、重启或更新 Gateway 网关 | |
| `image` / `image_generate` | 分析或生成图像 | [Image Generation](/zh-CN/tools/image-generation) |
| `video_generate` | 生成视频 | [Video Generation](/zh-CN/tools/video-generation) |
| `tts` | 一次性文本转语音转换 | [TTS](/zh-CN/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | 会话管理、状态和子智能体编排 | [Sub-agents](/zh-CN/tools/subagents) |
| `session_status` | 轻量级 `/status` 风格回读和会话模型覆盖 | [Session Tools](/zh-CN/concepts/session-tool) |
| `exec` / `process` | 运行 shell 命令，管理后台进程 | [Exec](/zh-CN/tools/exec) |
| `code_execution` | 运行沙箱隔离的远程 Python 分析 | [Code Execution](/zh-CN/tools/code-execution) |
| `browser` | 控制 Chromium 浏览器（导航、点击、截图） | [Browser](/zh-CN/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | 搜索网页、搜索 X 帖子、抓取页面内容 | [Web](/zh-CN/tools/web) |
| `read` / `write` / `edit` | 在工作区中进行文件 I/O | |
| `apply_patch` | 多块文件补丁 | [Apply Patch](/zh-CN/tools/apply-patch) |
| `message` | 跨所有渠道发送消息 | [Agent Send](/zh-CN/tools/agent-send) |
| `canvas` | 驱动节点 Canvas（present、eval、snapshot） | |
| `nodes` | 发现并定位已配对设备 | |
| `cron` / `gateway` | 管理定时任务；检查、修补、重启或更新 Gateway 网关 | |
| `image` / `image_generate` | 分析或生成图像 | [Image Generation](/zh-CN/tools/image-generation) |
| `music_generate` | 生成音乐轨道 | [Music Generation](/zh-CN/tools/music-generation) |
| `video_generate` | 生成视频 | [Video Generation](/zh-CN/tools/video-generation) |
| `tts` | 一次性文本转语音转换 | [TTS](/zh-CN/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | 会话管理、状态查看和子智能体编排 | [Sub-agents](/zh-CN/tools/subagents) |
| `session_status` | 轻量级 `/status` 风格回读和会话模型覆盖 | [Session Tools](/zh-CN/concepts/session-tool) |
对于图像任务，使用 `image` 进行分析，使用 `image_generate` 进行生成或编辑。如果你要使用 `openai/*`、`google/*`、`fal/*` 或其他非默认图像提供商，请先配置该提供商的身份验证/API 密钥。
对于图像相关工作，使用 `image` 进行分析，使用 `image_generate` 进行生成或编辑。如果你的目标是 `openai/*`、`google/*`、`fal/*` 或其他非默认图像提供商，请先配置该提供商的凭证/API 密钥。
对于视频任务，使用 `video_generate`。如果你要使用 `qwen/*` 或其他非默认视频提供商，请先配置该提供商的身份验证/API 密钥。
对于音乐相关工作，使用 `music_generate`。如果你的目标是 `google/*`、`minimax/*` 或其他非默认音乐提供商，请先配置该提供商的凭证/API 密钥。
对于由工作流驱动的音频生成，当 ComfyUI 之类的插件注册了 `music_generate` 时，请使用它。
这与 `tts` 不同，后者是文本转语音。
对于视频相关工作，使用 `video_generate`。如果你的目标是 `qwen/*` 或其他非默认视频提供商，请先配置该提供商的凭证/API 密钥。
`session_status` 是 sessions 组中的轻量级状态/回读工具。
它用于回答当前会话的 `/status` 风格问题，并且
可以选择设置按会话生效的模型覆盖；`model=default` 会清除该
覆盖。和 `/status` 一样，它可以从最新的转录使用记录中
回填稀疏的 token/缓存计数器，以及当前运行时模型标签。
对于由工作流驱动的音频生成，当某个插件（例如
ComfyUI）注册了它时，请使用 `music_generate`。这与 `tts` 不同，后者是文本转语音。
`gateway` 是仅限所有者使用的 Gateway 网关运行时工具，用于执行 Gateway 网关操作：
`session_status` 是 sessions 分组中的轻量级状态/回读工具。
它用于回答当前会话中 `/status` 风格的问题，也可以选择设置按会话生效的模型覆盖；`model=default` 会清除此覆盖。
与 `/status` 一样，它可以从最新的转录用量条目中回填稀疏的 token/缓存计数器以及当前运行时模型标签。
- `config.schema.lookup`：在编辑前查找一个按路径限定范围的配置子树
`gateway` 是仅限所有者使用、用于 Gateway 网关操作的运行时工具：
- `config.schema.lookup`：在编辑前查看单一路径范围内的配置子树
- `config.get`：获取当前配置快照 + 哈希
- `config.patch`：执行带重启的部分配置更新
- `config.apply`：仅用于完整替换整个配置
- `update.run`：显式执行自更新 + 重启
- `config.patch`：使用重启执行部分配置更新
- `config.apply`：仅用于完整配置替换
- `update.run`：用于显式自更新 + 重启
对于部分更改，优先使用 `config.schema.lookup` 然后使用 `config.patch`。只有在你有意替换整个配置时，才使用 `config.apply`。
对于部分变更，优先使用 `config.schema.lookup`，然后使用 `config.patch`。仅当你有意替换整个配置时，才使用
`config.apply`。
该工具还会拒绝更改 `tools.exec.ask` 或 `tools.exec.security`；
旧版 `tools.bash.*` 别名会规范化到同样受保护的 exec 路径。
旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径。
### 插件提供的工具
插件可以注册额外工具。一些示例：
- [Lobster](/zh-CN/tools/lobster) — 带可恢复审批的类型化工作流运行时
- [LLM Task](/zh-CN/tools/llm-task) — 仅输出 JSON 的 LLM 步骤，用于结构化输出
- [Music Generation](/tools/music-generation) — 插件提供的 `music_generate` 工具接口
- [LLM Task](/zh-CN/tools/llm-task) — 用于结构化输出的仅 JSON LLM 步骤
- [Music Generation](/zh-CN/tools/music-generation) — 插件提供的 `music_generate` 工具界面
- [Diffs](/zh-CN/tools/diffs) — 差异查看器和渲染器
- [OpenProse](/zh-CN/prose) — 以 Markdown 为优先的工作流编排
@ -113,7 +114,8 @@ OpenClaw 有三个协同工作的层级：
### 允许列表和拒绝列表
通过配置中的 `tools.allow` / `tools.deny` 控制智能体可以调用哪些工具。拒绝规则始终优先于允许规则。
通过配置中的 `tools.allow` / `tools.deny` 控制智能体可以调用哪些工具。
拒绝始终优先于允许。
```json5
{
@ -124,44 +126,43 @@ OpenClaw 有三个协同工作的层级：
}
```
### 工具配置文件
### 工具配置档案
`tools.profile` 会在应用 `allow`/`deny` 之前设置基础允许列表。
`tools.profile` 会在应用 `allow`/`deny` 之前设置一个基础允许列表。
按智能体覆盖：`agents.list[].tools.profile`。
| 配置文件 | 包含内容 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `full` | 不做限制（等同于未设置） |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `minimal` | 仅 `session_status` |
| Profile | 包含内容 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `full` | 无限制（与未设置相同） |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `minimal` | 仅 `session_status` |
### 工具分组
### 工具组
在允许/拒绝列表中使用 `group:*` 简写：
| 分组 | 工具 |
| Group | 工具 |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `group:runtime` | exec、process、code_execution（`bash` 可作为 `exec` 的别名使用） |
| `group:fs` | read、write、edit、apply_patch |
| `group:runtime` | exec、process、code_execution（`bash` 可作为 `exec` 的别名使用） |
| `group:fs` | read、write、edit、apply_patch |
| `group:sessions` | sessions_list、sessions_history、sessions_send、sessions_spawn、sessions_yield、subagents、session_status |
| `group:memory` | memory_search、memory_get |
| `group:web` | web_search、x_search、web_fetch |
| `group:ui` | browser、canvas |
| `group:automation` | cron、gateway |
| `group:messaging` | message |
| `group:nodes` | nodes |
| `group:agents` | agents_list |
| `group:media` | image、image_generate、video_generate、tts |
| `group:openclaw` | 所有 OpenClaw 内置工具（不包括插件工具） |
| `group:memory` | memory_search、memory_get |
| `group:web` | web_search、x_search、web_fetch |
| `group:ui` | browser、canvas |
| `group:automation` | cron、gateway |
| `group:messaging` | message |
| `group:nodes` | nodes |
| `group:agents` | agents_list |
| `group:media` | image、image_generate、music_generate、video_generate、tts |
| `group:openclaw` | 所有 OpenClaw 内置工具（不包括插件工具） |
`sessions_history` 返回一个有边界、经过安全过滤的回忆视图。它会从 assistant 文本中剥离思维标签、`<relevant-memories>` 脚手架、纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、
`sessions_history` 返回一个有界的、经过安全过滤的回忆视图。它会从助手文本中移除思考标签、`<relevant-memories>` 脚手架、纯文本工具调用 XML
负载（包括 `<tool_call>...</tool_call>`、
`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、
`<function_calls>...</function_calls>` 以及被截断的工具调用块）、
降级后的工具调用脚手架、泄露的 ASCII/全角模型控制 token，
以及格式错误的 MiniMax 工具调用 XML，然后再应用
脱敏/截断，并在需要时使用超大行占位符，而不是
直接充当原始转录转储。
降级后的工具调用脚手架、泄露的 ASCII/全角模型控制
token，以及格式错误的 MiniMax 工具调用 XML，然后再应用脱敏/截断，并在必要时使用超大行占位符，而不是充当原始转录转储。
### 提供商专属限制

154
docs/zh-CN/tools/music-generation.md
View File

@ -1,30 +1,68 @@
---
read_when:
- 通过智能体生成音乐或音频
- 配置插件提供的音乐生成工具
- 配置音乐生成提供商和模型
- 了解 `music_generate` 工具参数
summary: 使用插件提供的工具（例如 ComfyUI 工作流）生成音乐或音频
summary: 通过共享提供商或插件提供的工作流生成音乐
title: 音乐生成
x-i18n:
generated_at: "2026-04-06T00:47:16Z"
generated_at: "2026-04-06T00:52:53Z"
model: gpt-5.4
provider: openai
source_hash: 625fe7cd03f88541104d21da12dc318344e8d82fd2ec0bf1f7c0fb817dd14c62
source_hash: 7c4fa4b98627be77de47a8c53f686d9459ccc9ecf9064bb8459f94433afad5aa
source_path: tools/music-generation.md
workflow: 15
---
# 音乐生成
当某个插件注册了音乐生成功能时，`music_generate` 工具允许智能体创建音频文件。
`music_generate` 工具允许智能体通过以下任一方式创建音乐或音频：
内置的 `comfy` 插件当前通过工作流配置的 ComfyUI 图提供 `music_generate`。
- 使用共享的音乐生成能力，以及已配置的提供商，例如 Google 和 MiniMax
- 使用插件提供的工具接口，例如通过工作流配置的 ComfyUI 图表
对于由共享提供商支持的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务账本中跟踪它，然后在音轨准备就绪后再次唤醒智能体，以便智能体将完成的音频发回原始渠道。
<Note>
只有在至少有一个音乐生成提供商可用时，内置共享工具才会显示。如果你在智能体工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。
</Note>
<Note>
插件提供的 `music_generate` 实现可能暴露不同的参数或运行时行为。下方的异步任务/状态流程适用于内置的共享提供商支持路径。
</Note>
## 快速开始
### 共享提供商支持的生成
1. 为至少一个提供商设置 API 密钥，例如 `GEMINI_API_KEY` 或 `MINIMAX_API_KEY`。
2. 可选地设置你偏好的模型：
```json5
{
agents: {
defaults: {
musicGenerationModel: {
primary: "google/lyria-3-clip-preview",
},
},
},
}
```
3. 让智能体执行：_“生成一段关于夜间驾车穿过霓虹都市的欢快 synthpop 曲目。”_
智能体会自动调用 `music_generate`。无需添加工具 allowlist。
对于没有会话支持的智能体运行的直接同步上下文，内置工具仍会回退到内联生成，并在工具结果中返回最终媒体路径。
### 工作流驱动的插件生成
内置的 `comfy` 插件也可以使用通过工作流配置的 ComfyUI 图表提供 `music_generate`。
1. 使用工作流 JSON 以及提示词/输出节点配置 `models.providers.comfy.music`。
2. 如果你使用 Comfy Cloud，请设置 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。
3. 让智能体生成音乐，或直接调用该工具。
3. 请求智能体生成音乐，或直接调用该工具。
示例：
@ -32,32 +70,110 @@ x-i18n:
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
```
## 工具参数
## 共享内置提供商支持
| 参数 | 类型 | 描述 |
| ---------- | ------ | --------------------------------------------------- |
| `prompt` | string | 音乐或音频生成提示词 |
| `action` | string | `"generate"`（默认）或 `"list"` |
| `model` | string | 提供商/模型覆盖。当前为 `comfy/workflow` |
| `filename` | string | 已保存音频文件的输出文件名提示 |
| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 |
| -------- | ---------------------- | ---------------- | --------------------------------------------------------- | ---------------------------------- |
| Google | `lyria-3-clip-preview` | 最多 10 张图片 | `lyrics`、`instrumental`、`format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.5+` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` |
## 当前提供商支持
## 插件提供的支持
| 提供商 | 模型 | 说明 |
| -------- | ---------- | ------------------------------- |
| ComfyUI | `workflow` | 由工作流定义的音乐或音频 |
| ComfyUI | `workflow` | 由工作流定义的音乐或音频 |
使用 `action: "list"` 可在运行时检查可用的共享提供商和模型：
```text
/tool music_generate action=list
```
## 内置工具参数
| 参数 | 类型 | 说明 |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `prompt` | string | 音乐生成提示词（`action: "generate"` 时必填） |
| `action` | string | `"generate"`（默认）、用于当前会话任务的 `"status"`，或用于检查提供商的 `"list"` |
| `model` | string | 提供商/模型覆盖，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` |
| `lyrics` | string | 当提供商支持显式歌词输入时，可选的歌词 |
| `instrumental` | boolean | 当提供商支持时，请求仅器乐输出 |
| `image` | string | 单张参考图片路径或 URL |
| `images` | string[] | 多张参考图片（最多 10 张） |
| `durationSeconds` | number | 当提供商支持时长提示时，以秒为单位的目标时长 |
| `format` | string | 当提供商支持时，输出格式提示（`mp3` 或 `wav`） |
| `filename` | string | 输出文件名提示 |
并非所有提供商或插件都支持所有参数。共享内置工具会在提交请求前验证提供商能力限制。
## 共享提供商支持路径的异步行为
- 有会话支持的智能体运行：`music_generate` 会创建一个后台任务，立即返回一个 started/task 响应，并稍后在后续智能体消息中发布完成的音轨。
- 防止重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中后续对 `music_generate` 的调用会返回任务状态，而不是启动新的生成。
- 状态查询：使用 `action: "status"` 可以检查当前活跃的、由会话支持的音乐任务，而不会启动新任务。
- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 检查生成任务的排队中、运行中和终态状态。
- 完成唤醒：OpenClaw 会将一个内部完成事件注入回同一会话，以便模型自行编写面向用户的后续回复。
- 提示信息：当音乐任务已在进行中时，同一会话中后续用户/手动轮次会收到一个小型运行时提示，这样模型就不会盲目再次调用 `music_generate`。
- 无会话回退：在没有真实智能体会话的直接/本地上下文中，仍会以内联方式运行，并在同一轮中返回最终音频结果。
## 配置
### 模型选择
```json5
{
agents: {
defaults: {
musicGenerationModel: {
primary: "google/lyria-3-clip-preview",
fallbacks: ["minimax/music-2.5+"],
},
},
},
}
```
### 提供商选择顺序
生成音乐时，OpenClaw 会按以下顺序尝试提供商：
1. 工具调用中的 `model` 参数（如果智能体指定了它）
2. 配置中的 `musicGenerationModel.primary`
3. 按顺序使用 `musicGenerationModel.fallbacks`
4. 仅使用基于凭证支持的提供商默认值进行自动检测：
- 先使用当前默认提供商
- 再按提供商 id 顺序使用其余已注册的音乐生成提供商
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。
## 提供商说明
- Google 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本和可选参考图片。
- MiniMax 使用批量 `music_generation` 端点。当前内置流程支持提示词、可选歌词、器乐模式、时长引导和 mp3 输出。
- ComfyUI 支持由工作流驱动，并取决于所配置的图表以及提示词/输出字段的节点映射。
## 实时测试
内置 ComfyUI 音乐路径的选择启用式实时覆盖：
共享内置提供商的选择加入式实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
```
内置 ComfyUI 音乐路径的选择加入式实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
如果这些部分已完成配置，该实时文件还涵盖 comfy 图像和视频工作流。
如果配置了这些部分，Comfy 实时文件还会覆盖 comfy 图像和视频工作流。
## 相关内容
- [ComfyUI](/providers/comfy)
- [后台任务](/zh-CN/automation/tasks) - 分离式 `music_generate` 运行的任务跟踪
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) - `musicGenerationModel` 配置
- [ComfyUI](/zh-CN/providers/comfy)
- [Google（Gemini）](/zh-CN/providers/google)
- [MiniMax](/zh-CN/providers/minimax)
- [模型](/zh-CN/concepts/models) - 模型配置和故障转移
- [工具概览](/zh-CN/tools)

239
docs/zh-CN/tools/plugin.md
View File

@ -2,26 +2,22 @@
read_when:
- 安装或配置插件
- 了解插件设备发现和加载规则
- 使用兼容 Codex/Claude 的插件 bundle
- 使用兼容 Codex / Claude 的插件 bundles
sidebarTitle: Install and Configure
summary: 安装、配置和管理 OpenClaw 插件
title: 插件
x-i18n:
generated_at: "2026-04-05T10:12:31Z"
generated_at: "2026-04-06T00:53:21Z"
model: gpt-5.4
provider: openai
source_hash: 707bd3625596f290322aeac9fecb7f4c6f45d595fdfb82ded7cbc8e04457ac7f
source_hash: 9e2472a3023f3c1c6ee05b0cdc228f6b713cc226a08695b327de8a3ad6973c83
source_path: tools/plugin.md
workflow: 15
---
# 插件
插件通过新增能力来扩展 OpenClaw：渠道、模型 provider、
工具、Skills、语音、实时转录、实时语音、
媒体理解、图像生成、视频生成、Web 抓取、Web
搜索等等。有些插件是**核心**插件（随 OpenClaw 一起提供），另一些
则是**外部**插件（由社区发布到 npm）。
插件可为 OpenClaw 扩展新能力：渠道、模型提供商、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起提供），其他则是**外部**插件（由社区发布到 npm）。
## 快速开始
@ -34,10 +30,10 @@ x-i18n:
<Step title="安装插件">
```bash
# 从 npm 安装
# 从 npm
openclaw plugins install @openclaw/voice-call
# 从本地目录或归档安装
# 从本地目录或归档文件
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz
```
@ -49,12 +45,12 @@ x-i18n:
openclaw gateway restart
```
然后在你的配置文件中通过 `plugins.entries.\<id\>.config` 进行配置。
然后在你的配置文件中，通过 `plugins.entries.\<id\>.config` 进行配置。
</Step>
</Steps>
如果你更喜欢在聊天中原生控制，请启用 `commands.plugins: true` 并使用：
如果你更喜欢原生聊天控制，请启用 `commands.plugins: true` 并使用：
```text
/plugin install clawhub:@openclaw/voice-call
@ -62,64 +58,59 @@ x-i18n:
/plugin enable voice-call
```
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式
`clawhub:<pkg>`，或裸包规范（先尝试 ClawHub，再回退到 npm）。
安装路径使用与 CLI 相同的解析器：本地路径 / 归档文件、显式 `clawhub:<pkg>`，或裸包规范（先 ClawHub，再回退到 npm）。
如果配置无效，安装通常会以默认拒绝方式失败，并提示你使用
`openclaw doctor --fix`。唯一的恢复例外是一个范围很窄的内置插件
重装路径，仅适用于选择加入
`openclaw.install.allowInvalidConfigRecovery` 的插件。
如果配置无效，安装通常会以关闭失败的方式终止，并提示你使用 `openclaw doctor --fix`。唯一的恢复例外是为选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件提供的一条范围很窄的内置插件重装路径。
## 插件类型
OpenClaw 可识别两种插件格式：
| 格式 | 工作方式 | 示例 |
| ---------- | --------------------------------------------------------------- | ------------------------------------------------------ |
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
| **Bundle** | 兼容 Codex/Claude/Cursor 的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
| 格式 | 工作方式 | 示例 |
| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
| **Bundle** | 兼容 Codex / Claude / Cursor 的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
两者都会出现在 `openclaw plugins list` 中。有关 bundle 的详细信息，请参见 [插件 Bundles](/zh-CN/plugins/bundles)。
两者都会显示在 `openclaw plugins list` 中。有关 bundle 详情，请参见 [插件 Bundles](/zh-CN/plugins/bundles)。
如果你要编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins)
和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
## 官方插件
### 可安装（npm）
| 插件 | 包 | 文档 |
| ---------------- | -------------------------- | ------------------------------------ |
| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) |
| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) |
| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) |
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
| 插件 | 包 | 文档 |
| ---------------- | ---------------------- | ------------------------------------ |
| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) |
| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) |
| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) |
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
### 核心（随 OpenClaw 一起提供）
<AccordionGroup>
<Accordion title="模型 providers（默认启用）">
`anthropic`、`byteplus`、`cloudflare-ai-gateway`、`github-copilot`、`google`、
`huggingface`、`kilocode`、`kimi-coding`、`minimax`、`mistral`、`qwen`、
`moonshot`、`nvidia`、`openai`、`opencode`、`opencode-go`、`openrouter`、
`qianfan`、`synthetic`、`together`、`venice`、
`vercel-ai-gateway`、`volcengine`、`xiaomi`、`zai`
<Accordion title="模型提供商（默认启用）">
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
`qianfan`, `synthetic`, `together`, `venice`,
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
</Accordion>
<Accordion title="内存插件">
- `memory-core` — 内置内存搜索（通过 `plugins.slots.memory` 默认启用）
- `memory-lancedb` — 按需安装的长期记忆，带自动 recall/capture（设置 `plugins.slots.memory = "memory-lancedb"`）
<Accordion title="Memory 插件">
- `memory-core` — 内置内存搜索（默认通过 `plugins.slots.memory`）
- `memory-lancedb` — 按需安装的长期记忆，带自动召回 / 捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
</Accordion>
<Accordion title="语音 providers（默认启用）">
`elevenlabs`、`microsoft`
<Accordion title="语音提供商（默认启用）">
`elevenlabs`, `microsoft`
</Accordion>
<Accordion title="其他">
- `browser` — 用于 browser 工具、`openclaw browser` CLI、`browser.request` gateway 方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用）
- `copilot-proxy` — VS Code Copilot Proxy bridge（默认禁用）
- `browser` — 用于 browser 工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、browser 运行时和默认 browser 控制服务的内置 browser 插件（默认启用；替换前请先禁用）
- `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用）
</Accordion>
</AccordionGroup>
@ -144,23 +135,21 @@ OpenClaw 可识别两种插件格式：
| 字段 | 说明 |
| ---------------- | --------------------------------------------------------- |
| `enabled` | 主开关（默认：`true`） |
| `allow` | 插件 allowlist（可选） |
| `deny` | 插件 denylist（可选；deny 优先） |
| `load.paths` | 额外插件文件/目录 |
| `slots` | 独占 slot 选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 每插件开关 + 配置 |
| `allow` | 插件允许列表（可选） |
| `deny` | 插件拒绝列表（可选；拒绝优先） |
| `load.paths` | 额外的插件文件 / 目录 |
| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 每个插件的开关 + 配置 |
配置变更**需要重启 Gateway 网关**。如果 Gateway 网关以启用了配置监视 +
进程内重启的方式运行（默认 `openclaw gateway` 路径），那么该
重启通常会在配置写入后不久自动执行。
配置更改**需要重启 Gateway 网关**。如果 Gateway 网关以启用配置监视 + 进程内重启的方式运行（默认的 `openclaw gateway` 路径），则通常会在配置写入完成后稍等片刻自动执行该重启。
<Accordion title="插件状态：已禁用 vs 缺失 vs 无效">
- **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
- **缺失**：配置引用了某个插件 id，但设备发现没有找到它。
- **无效**：插件存在，但其配置与声明的 schema 不匹配。
- **缺失**：配置引用了一个设备发现未找到的插件 id。
- **无效**：插件存在，但其配置不符合声明的 schema。
</Accordion>
## 设备发现和优先级
## 设备发现与优先级
OpenClaw 按以下顺序扫描插件（先匹配者优先）：
@ -178,8 +167,8 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
</Step>
<Step title="内置插件">
随 OpenClaw 一起提供。许多默认启用（模型 providers、语音）。
其他插件则需要显式启用。
随 OpenClaw 一起提供。许多默认启用（模型提供商、语音等）。
其他则需要显式启用。
</Step>
</Steps>
@ -189,35 +178,35 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
- `plugins.deny` 总是优先于 allow
- `plugins.entries.\<id\>.enabled: false` 会禁用该插件
- 来源于工作区的插件**默认禁用**（必须显式启用）
- 内置插件遵循默认启用集合，除非被覆盖
- 独占 slots 可为该 slot 强制启用所选插件
- 内置插件遵循内建的默认启用集合，除非被覆盖
- 独占槽位可强制启用该槽位中选定的插件
## 插件 slots（独占类别）
## 插件槽位（独占类别）
有些类别是独占的（一次只能有一个处于活动状态）：
有些类别是独占的（同一时间只能激活一个）：
```json5
{
plugins: {
slots: {
memory: "memory-core", // 或使用 "none" 禁用
memory: "memory-core", // 或 "none" 以禁用
contextEngine: "legacy", // 或某个插件 id
},
},
}
```
| Slot | 控制内容 | 默认值 |
| ---------------- | ------------------ | ------------------- |
| `memory` | 活动内存插件 | `memory-core` |
| `contextEngine` | 活动上下文引擎 | `legacy`（内置） |
| 槽位 | 控制内容 | 默认值 |
| --------------- | ---------------- | ------------------- |
| `memory` | 活动 memory 插件 | `memory-core` |
| `contextEngine` | 活动上下文引擎 | `legacy`（内建） |
## CLI 参考
```bash
openclaw plugins list # 紧凑清单
openclaw plugins list --enabled # 仅显示已加载插件
openclaw plugins list --verbose # 每插件详细信息行
openclaw plugins list --verbose # 每个插件的详细行
openclaw plugins list --json # 机器可读清单
openclaw plugins inspect <id> # 深度详情
openclaw plugins inspect <id> --json # 机器可读
@ -232,12 +221,12 @@ openclaw plugins install <path> # 从本地路径安装
openclaw plugins install -l <path> # 链接（不复制），用于开发
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin # 记录精确解析后的 npm 规范
openclaw plugins install <spec> --pin # 记录精确解析后的 npm spec
openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id> # 更新单个插件
openclaw plugins update <id> --dangerously-force-unsafe-install
openclaw plugins update --all # 更新全部
openclaw plugins uninstall <id> # 移除配置/安装记录
openclaw plugins uninstall <id> # 删除配置 / 安装记录
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
@ -246,47 +235,28 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
内置插件随 OpenClaw 一起提供。许多默认启用（例如
内置模型 providers、内置语音 providers 和内置 browser
插件）。其他内置插件仍需要执行 `openclaw plugins enable <id>`。
内置插件随 OpenClaw 一起提供。许多默认启用（例如内置模型提供商、内置语音提供商和内置 browser 插件）。其他内置插件仍然需要 `openclaw plugins enable <id>`。
`--force` 会原地覆盖现有已安装的插件或 hook 包。
它不支持与 `--link` 一起使用，因为后者会复用源路径，而不是
复制到受管理的安装目标。
`--force` 会就地覆盖现有已安装插件或 hook pack。
它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到受管理的安装目标。
`--pin` 仅适用于 npm。不支持与 `--marketplace` 一起使用，因为
marketplace 安装会持久化 marketplace 源元数据，而不是 npm 规范。
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
`--dangerously-force-unsafe-install` 是一个紧急覆盖开关，用于处理内置危险代码扫描器的误报。
它允许插件安装和插件更新在遇到内置 `critical` 发现后继续进行，但仍然
不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
`--dangerously-force-unsafe-install` 是针对内置危险代码扫描器误报的紧急覆盖开关。它允许插件安装和插件更新在遇到内置 `critical` 发现后继续进行，但仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skill
依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而
`openclaw skills install` 仍然是独立的 ClawHub Skill 下载/安装流程。
这个 CLI 标志仅适用于插件安装 / 更新流程。由 Gateway 网关驱动的 skill 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub skill 下载 / 安装流程。
兼容的 bundle 会参与相同的插件 list/inspect/enable/disable
流程。当前运行时支持包括 bundle Skills、Claude 命令 Skills、
Claude `settings.json` 默认值、Claude `.lsp.json` 以及 manifest 声明的
`lspServers` 默认值、Cursor 命令 Skills 和兼容的 Codex hook
目录。
兼容 bundles 会参与相同的插件列表 / 检查 / 启用 / 禁用流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及
由 bundle 支持或不支持的 MCP 和 LSP server 条目。
`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及由 bundle 支持或不支持的 MCP 和 LSP server 条目。
Marketplace 源可以是来自
`~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、
本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、
GitHub 仓库 URL，或 git URL。对于远程 marketplaces，插件条目必须保留在
已克隆 marketplace 仓库内部，并且只能使用相对路径源。
Marketplace 来源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、形如 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplaces，插件条目必须保留在克隆的 marketplace 仓库内，并且只能使用相对路径来源。
完整详情请参见 [`openclaw plugins` CLI 参考](/cli/plugins)。
## 插件 API 概览
原生插件导出一个入口对象，该对象暴露 `register(api)`。旧版
插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应
使用 `register`。
原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
```typescript
export default definePluginEntry({
@ -306,47 +276,46 @@ export default definePluginEntry({
});
```
OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。
对于旧插件，加载器仍会回退到 `activate(api)`，
但内置插件和新的外部插件应将 `register` 视为公开契约。
OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为较旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
常见注册方法：
| 方法 | 注册内容 |
| --------------------------------------- | ----------------------- |
| `registerProvider` | 模型 provider（LLM） |
| `registerChannel` | 聊天渠道 |
| `registerTool` | 智能体工具 |
| `registerHook` / `on(...)` | 生命周期 hooks |
| `registerSpeechProvider` | 文本转语音 / STT |
| `registerRealtimeTranscriptionProvider` | 流式 STT |
| `registerRealtimeVoiceProvider` | 双工实时语音 |
| `registerMediaUnderstandingProvider` | 图像/音频分析 |
| `registerImageGenerationProvider` | 图像生成 |
| `registerVideoGenerationProvider` | 视频生成 |
| `registerWebFetchProvider` | Web 抓取 / scrape provider |
| `registerWebSearchProvider` | Web 搜索 |
| `registerHttpRoute` | HTTP 端点 |
| `registerCommand` / `registerCli` | CLI 命令 |
| `registerContextEngine` | 上下文引擎 |
| `registerService` | 后台服务 |
| 方法 | 注册内容 |
| --------------------------------------- | --------------------------- |
| `registerProvider` | 模型提供商（LLM） |
| `registerChannel` | 聊天渠道 |
| `registerTool` | 智能体工具 |
| `registerHook` / `on(...)` | 生命周期 hooks |
| `registerSpeechProvider` | 文本转语音 / STT |
| `registerRealtimeTranscriptionProvider` | 流式 STT |
| `registerRealtimeVoiceProvider` | 双工实时语音 |
| `registerMediaUnderstandingProvider` | 图像 / 音频分析 |
| `registerImageGenerationProvider` | 图像生成 |
| `registerMusicGenerationProvider` | 音乐生成 |
| `registerVideoGenerationProvider` | 视频生成 |
| `registerWebFetchProvider` | 网页抓取 / scrape 提供商 |
| `registerWebSearchProvider` | Web 搜索 |
| `registerHttpRoute` | HTTP 端点 |
| `registerCommand` / `registerCli` | CLI 命令 |
| `registerContextEngine` | 上下文引擎 |
| `registerService` | 后台服务 |
类型化生命周期 hooks 的 hook 保护行为：
类型化生命周期 hooks 的 hook 守卫行为：
- `before_tool_call`：`{ block: true }` 为终止状态；会跳过较低优先级处理器。
- `before_tool_call`：`{ block: false }` 为 no-op，不会清除更早的 block。
- `before_install`：`{ block: true }` 为终止状态；会跳过较低优先级处理器。
- `before_install`：`{ block: false }` 为 no-op，不会清除更早的 block。
- `message_sending`：`{ cancel: true }` 为终止状态；会跳过较低优先级处理器。
- `message_sending`：`{ cancel: false }` 为 no-op，不会清除更早的 cancel。
- `before_tool_call`：`{ block: true }` 是终止性的；较低优先级处理器会被跳过。
- `before_tool_call`：`{ block: false }` 是空操作，不会清除更早的 block。
- `before_install`：`{ block: true }` 是终止性的；较低优先级处理器会被跳过。
- `before_install`：`{ block: false }` 是空操作，不会清除更早的 block。
- `message_sending`：`{ cancel: true }` 是终止性的；较低优先级处理器会被跳过。
- `message_sending`：`{ cancel: false }` 是空操作，不会清除更早的 cancel。
有关完整的类型化 hook 行为，请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
完整的类型化 hook 行为，请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
## 相关内容
- [构建插件](/zh-CN/plugins/building-plugins) —— 创建你自己的插件
- [插件 Bundles](/zh-CN/plugins/bundles) —— Codex/Claude/Cursor bundle 兼容性
- [插件清单](/zh-CN/plugins/manifest) —— manifest schema
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) —— 在插件中添加智能体工具
- [插件内部机制](/plugins/architecture) —— 能力模型和加载管线
- [社区插件](/zh-CN/plugins/community) —— 第三方列表
- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
- [插件 Bundles](/zh-CN/plugins/bundles) — Codex / Claude / Cursor bundle 兼容性
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线
- [社区插件](/zh-CN/plugins/community) — 第三方列表