From 88e8bf44b8723b8fda0cd9a5229cf9bfa16eb418 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 6 Apr 2026 00:57:31 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/models.md | 146 +- docs/zh-CN/gateway/configuration-reference.md | 1106 ++++++++------- docs/zh-CN/plugins/architecture.md | 1191 ++++++++++------- docs/zh-CN/plugins/building-plugins.md | 121 +- docs/zh-CN/plugins/manifest.md | 274 ++-- docs/zh-CN/plugins/sdk-migration.md | 350 +++-- docs/zh-CN/plugins/sdk-overview.md | 372 ++--- docs/zh-CN/providers/google.md | 77 +- docs/zh-CN/providers/index.md | 34 +- docs/zh-CN/providers/minimax.md | 187 +-- docs/zh-CN/tools/index.md | 153 +-- docs/zh-CN/tools/music-generation.md | 154 ++- docs/zh-CN/tools/plugin.md | 239 ++-- 13 files changed, 2399 insertions(+), 2005 deletions(-) diff --git a/docs/zh-CN/concepts/models.md b/docs/zh-CN/concepts/models.md index bda1cdcff..03438765d 100644 --- a/docs/zh-CN/concepts/models.md +++ b/docs/zh-CN/concepts/models.md @@ -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 ` 时，请使用 `provider/model`。 +- 模型引用会通过按**第一个** `/` 拆分来解析。输入 `/model ` 时请使用 `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.` 省略了某个已存储配置文件，探测会报告 -`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.` 省略了某个已存储配置文件，探测会报告 `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 `：跳过较旧模型 - `--provider `：提供商前缀筛选 - `--max-candidates `：回退列表大小 -- `--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//agent/models.json`）。默认会合并此文件，除非将 `models.mode` 设置为 `replace`。 +`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json`（默认为 `~/.openclaw/agents//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) — 模型配置键名 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 5ec9f4c35..a874c183b 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -1,21 +1,21 @@ --- read_when: - - 你需要精确的字段级配置语义或默认值 - - 你正在验证渠道、模型、Gateway 网关或工具配置块 + - 你需要精确到字段级别的配置语义或默认值 + - 你正在校验渠道、模型、Gateway 网关或工具配置块 summary: 每个 OpenClaw 配置键、默认值和渠道设置的完整参考 title: 配置参考 x-i18n: - generated_at: "2026-04-06T00:37:48Z" + generated_at: "2026-04-06T00:57:31Z" model: gpt-5.4 provider: openai - source_hash: 5ea4ffa8910734c7d4dbc0e8ae1db291aae5e95c27ba543d38af8315017748b8 + source_hash: fa402242dde4bee6e7f75f8fb9512e73df615a1a3693d6beec3153c3ad8a25d1 source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 中可用的每个字段。若要查看面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 中提供的每个字段。若需面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 @@ -23,34 +23,34 @@ x-i18n: ## 渠道 -每个渠道在其配置节存在时都会自动启动（除非设置了 `enabled: false`）。 +每个渠道只要其配置节存在，就会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | ---------------------------------------------- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者） | -| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有入站私信 | +| 私信策略 | 行为 | +| -------------------- | --------------------------------------------------------------- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由 owner 批准 | +| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ---------------------------------------------- | -| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | -| `open` | 绕过群组允许列表（仍会应用提及门控） | -| `disabled` | 屏蔽所有群组/房间消息 | +| 群组策略 | 行为 | +| ----------------------- | ------------------------------------------------------ | +| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | +| `open` | 绕过群组允许列表（但仍会应用提及门控） | +| `disabled` | 阻止所有群组/房间消息 | -`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时作为默认值。 -配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。 -如果提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退到 `allowlist`（默认拒绝）并在启动时发出警告。 +`channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。 +配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 +如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（默认拒绝）并在启动时给出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未拥有模型覆盖时（例如通过 `/model` 设置），就会应用该渠道映射。 +使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未有模型覆盖时（例如通过 `/model` 设置），就会应用该渠道映射。 ```json5 { @@ -73,7 +73,7 @@ x-i18n: ### 渠道默认值和心跳 -使用 `channels.defaults` 为各提供商设置共享的群组策略和心跳行为： +使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： ```json5 { @@ -91,15 +91,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的回退群组策略。 +- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时使用的回退群组策略。 - `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 -- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器样式心跳输出。 +- `channels.defaults.heartbeat.useIndicator`：以紧凑指示器样式渲染心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已链接会话时，它会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已关联会话时会自动启动。 ```json5 { @@ -110,7 +110,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 蓝色对勾（在自聊模式下为 false） + sendReadReceipts: true, // 蓝色对勾（自聊模式下为 false） groups: { "*": { requireMention: true }, }, @@ -132,7 +132,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已 } ``` - + ```json5 { @@ -150,10 +150,10 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用 `default` 账户（如果存在）；否则使用首个已配置的账户 id（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖该回退默认账户选择。 -- 旧版单账户 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 -- 按账户覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 出站命令默认使用 `default` 账号（若存在）；否则使用第一个已配置的账号 ID（排序后）。 +- 可选的 `channels.whatsapp.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖该回退默认账号选择。 +- 旧版单账号 Baileys 认证目录会被 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 按账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -188,7 +188,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress（默认：off；显式启用以避免预览编辑速率限制） + streaming: "partial", // off | partial | block | progress（默认：off；明确启用以避免预览编辑速率限制） actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -211,12 +211,12 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已 } ``` -- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅常规文件；拒绝符号链接），默认账户还可回退到 `TELEGRAM_BOT_TOKEN`。 -- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 -- 在多账户设置（2 个及以上账户 id）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若缺失或无效，`openclaw doctor` 会发出警告。 -- `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中都可用）。 +- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅限普通文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 +- 可选的 `channels.telegram.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 在多账号配置（2 个及以上账号 ID）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若缺失或无效，`openclaw doctor` 会发出警告。 +- `configWrites: false` 会阻止 Telegram 发起的配置写入（supergroup ID 迁移、`/config set|unset`）。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。 - 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 ### Discord @@ -272,7 +272,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress（在 Discord 上，progress 会映射到 partial） + streaming: "off", // off | partial | block | progress（在 Discord 上 progress 会映射为 partial） maxLinesPerMessage: 17, ui: { components: { @@ -283,7 +283,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // 为 sessions_spawn({ thread: true }) 显式启用 + spawnSubagentSessions: false, // 为 sessions_spawn({ thread: true }) 选择性启用 }, voice: { enabled: true, @@ -319,36 +319,36 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已 } ``` -- Token：`channels.discord.token`，默认账户可回退到 `DISCORD_BOT_TOKEN`。 -- 直接出站调用若提供显式 Discord `token`，调用会使用该 token；账户重试/策略设置仍来自活动运行时快照中选定的账户。 -- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 -- 交付目标使用 `user:`（私信）或 `channel:`（服务器频道）；裸数字 ID 会被拒绝。 -- 服务器 slug 为小写，空格替换为 `-`；频道键使用 slug 化名称（不含 `#`）。优先使用服务器 ID。 -- 默认会忽略机器人自己发布的消息。`allowBots: true` 可启用；使用 `allowBots: "mentions"` 仅接受提及该机器人的机器人消息（仍会过滤自己的消息）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及了其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其未超过 2000 个字符。 +- Token：`channels.discord.token`，默认账号还可回退到 `DISCORD_BOT_TOKEN`。 +- 直接出站调用若显式提供 Discord `token`，则该调用会使用该 token；账号重试/策略设置仍来自活动运行时快照中所选账号。 +- 可选的 `channels.discord.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 对投递目标使用 `user:`（私信）或 `channel:`（服务器频道）；裸数字 ID 会被拒绝。 +- Guild slug 为小写，空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。 +- 默认会忽略由 bot 编写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及该 bot 的 bot 消息（自身消息仍会被过滤）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及其他用户或角色但未提及该 bot 的消息（不含 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）即使在消息少于 2000 字符时，也会拆分过高的消息。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定交付/路由） - - `idleHours`：按小时设置的无活动自动取消聚焦 Discord 覆盖（`0` 表示禁用） - - `maxAgeHours`：按小时设置的硬性最大时长 Discord 覆盖（`0` 表示禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式启用开关 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道/线程 id）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 + - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定投递/路由） + - `idleHours`：按小时设置的 Discord 覆盖型无活动自动取消聚焦（`0` 禁用） + - `maxAgeHours`：按小时设置的 Discord 覆盖型硬最大年龄（`0` 禁用） + - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程而选择启用的开关 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用 channel/thread id）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 - `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。 -- `channels.discord.voice` 启用 Discord 语音频道对话以及可选的自动加入 + TTS 覆盖。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会直接透传到 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 -- OpenClaw 还会在多次解密失败后，通过离开并重新加入语音会话来尝试恢复语音接收。 -- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 -- `channels.discord.autoPresence` 将运行时可用性映射为机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批交付和审批者授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，会激活 exec 审批。 +- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入和 TTS 覆盖。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会直接透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 +- OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 +- `channels.discord.autoPresence` 将运行时可用性映射到 bot presence（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 +- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（破窗兼容模式）。 +- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选智能体 ID 允许列表。省略则转发所有智能体的审批。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - `sessionFilter`：可选会话键模式（子串或正则）。 - - `target`：将审批提示发送到哪里。`"dm"`（默认）发送到审批者私信，`"channel"` 发送到原始频道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮仅可由已解析的审批者使用。 + - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到发起频道，`"both"` 两者都发送。当目标包含 `"channel"` 时，按钮仅能由已解析出的审批人使用。 - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中所有消息）。 +**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中的所有消息）。 ### Google Chat @@ -379,11 +379,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已 } ``` -- Service account JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 -- 也支持 service account SecretRef（`serviceAccountRef`）。 +- 服务账号 JSON：可内联（`serviceAccount`）或使用文件（`serviceAccountFile`）。 +- 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 交付目标使用 `spaces/` 或 `users/`。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（紧急兼容模式）。 +- 对投递目标使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变 email principal 匹配（破窗兼容模式）。 ### Slack @@ -448,38 +448,38 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账户环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加 `signingSecret`（在根级或按账户设置）。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 加 `signingSecret`（在根级或按账号设置）。 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 字符串或 SecretRef 对象。 -- Slack 账户快照会暴露每个凭证的来源/状态字段，例如 +- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 - `signingSecretStatus`。`configured_unavailable` 表示该账户 + `signingSecretStatus`。`configured_unavailable` 表示该账号 通过 SecretRef 配置，但当前命令/运行时路径无法 - 解析该 secret 值。 -- `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 -- `channels.slack.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 -- 交付目标使用 `user:`（私信）或 `channel:`。 + 解析出 secret 值。 +- `configWrites: false` 会阻止 Slack 发起的配置写入。 +- 可选的 `channels.slack.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 +- `channels.slack.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 +- 对投递目标使用 `user:`（私信）或 `channel:`。 **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 为每线程（默认）或跨频道共享。`thread.inheritParent` 会将父频道转录复制到新线程。 +**线程会话隔离：** `thread.historyScope` 可设为每线程（默认）或在频道间共享。`thread.inheritParent` 会将父频道转录复制到新线程。 -- `typingReaction` 会在回复运行期间为入站 Slack 消息添加临时反应，并在完成后删除。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批交付和审批者授权。与 Discord 使用相同架构：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- `typingReaction` 会在回复进行期间为传入的 Slack 消息添加临时 reaction，并在完成后移除。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。其 schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 说明 | -| ------------ | ------ | ------------------ | -| reactions | 启用 | 添加反应 + 列出反应 | -| messages | 启用 | 读取/发送/编辑/删除 | -| pins | 启用 | 置顶/取消置顶/列出 | -| memberInfo | 启用 | 成员信息 | -| emojiList | 启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | -------- | ---------------------- | +| reactions | 已启用 | React + 列出 reactions | +| messages | 已启用 | 读取/发送/编辑/删除 | +| pins | 已启用 | 固定/取消固定/列出 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义 emoji 列表 | ### Mattermost -Mattermost 作为插件发布：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -496,10 +496,10 @@ Mattermost 作为插件发布：`openclaw plugins install @openclaw/mattermost` "team-channel-id": { requireMention: false }, }, commands: { - native: true, // 显式启用 + native: true, // 选择启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 反向代理/公共部署下可选的显式 URL + // 反向代理/公网部署的可选显式 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -509,21 +509,21 @@ Mattermost 作为插件发布：`openclaw plugins install @openclaw/mattermost` } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 启用 Mattermost 原生命令时： - `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器必须可以访问。 -- 原生斜杠命令回调使用 Mattermost 在注册斜杠命令时返回的每命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调，并返回 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。 +- 原生 slash 回调会使用 Mattermost 在 slash 命令注册期间返回的每命令 token 进行认证。如果注册失败或没有激活命令，OpenClaw 会拒绝回调，并返回 `Unauthorized: invalid command token.`。 -- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 +- 对于私有/tailnet/internal 回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。 - 请使用主机/域名值，而不是完整 URL。 -- `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 + 使用主机/域名值，不要使用完整 URL。 +- `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。 - `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。 -- `channels.mattermost.groups..requireMention`：按频道设置的提及门控覆盖（`"*"` 用作默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 +- `channels.mattermost.groups..requireMention`：按频道覆盖提及门控（`"*"` 表示默认）。 +- 可选的 `channels.mattermost.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 ### Signal @@ -532,7 +532,7 @@ Mattermost 作为插件发布：`openclaw plugins install @openclaw/mattermost` channels: { signal: { enabled: true, - account: "+15555550123", // 可选账户绑定 + account: "+15555550123", // 可选账号绑定 dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -546,13 +546,13 @@ Mattermost 作为插件发布：`openclaw plugins install @openclaw/mattermost` **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -- `channels.signal.account`：将渠道启动固定到特定 Signal 账户标识。 -- `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 +- `channels.signal.account`：将渠道启动固定到特定 Signal 账号身份。 +- `channels.signal.configWrites`：允许或拒绝 Signal 发起的配置写入。 +- 可选的 `channels.signal.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.bluebubbles` 下配置）。 +BlueBubbles 是推荐的 iMessage 路径（插件支持，配置在 `channels.bluebubbles` 下）。 ```json5 { @@ -567,14 +567,14 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.blueb } ``` -- 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。请在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 -- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 +- 这里涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 +- 可选的 `channels.bluebubbles.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 完整 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage -OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 +OpenClaw 会生成 `imsg rpc`（通过 stdio 进行 JSON-RPC）。不需要守护进程或端口。 ```json5 { @@ -598,17 +598,17 @@ OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 +- 可选的 `channels.imessage.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 需要对 Messages 数据库授予 Full Disk Access。 +- 需要对 Messages DB 授予 Full Disk Access。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装脚本；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 -- `attachmentRoots` 和 `remoteAttachmentRoots` 用于限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 +- `cliPath` 可指向 SSH wrapper；为 SCP 附件抓取设置 `remoteHost`（`host` 或 `user@host`）。 +- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 - SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 -- `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- `channels.imessage.configWrites`：允许或拒绝 iMessage 发起的配置写入。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用标准化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 - + ```bash #!/usr/bin/env bash @@ -619,7 +619,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展支持，并在 `channels.matrix` 下配置。 +Matrix 由扩展提供支持，配置在 `channels.matrix` 下。 ```json5 { @@ -650,23 +650,23 @@ Matrix 由扩展支持，并在 `channels.matrix` 下配置。 ``` - Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账户可使用 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.allowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和 `allowPrivateNetwork` 是彼此独立的控制项。 -- `channels.matrix.defaultAccount` 在多账户设置中选择首选账户。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批交付和审批者授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，会激活 exec 审批。 +- `channels.matrix.proxy` 通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 +- `channels.matrix.allowPrivateNetwork` 允许私有/internal homeserver。`proxy` 和 `allowPrivateNetwork` 是彼此独立的控制项。 +- `channels.matrix.defaultAccount` 在多账号配置中选择首选账号。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选智能体 ID 允许列表。省略则转发所有智能体的审批。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - `sessionFilter`：可选会话键模式（子串或正则）。 - - `target`：将审批提示发送到哪里。`"dm"`（默认）、`"channel"`（原始房间）或 `"both"`。 - - 按账户覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归入会话：`per-user`（默认）按路由对等体共享，而 `per-room` 会隔离每个私信房间。 + - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 + - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由对等方共享，而 `per-room` 会隔离每个私信房间。 - Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 - 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams -Microsoft Teams 由扩展支持，并在 `channels.msteams` 下配置。 +Microsoft Teams 由扩展提供支持，配置在 `channels.msteams` 下。 ```json5 { @@ -681,12 +681,12 @@ Microsoft Teams 由扩展支持，并在 `channels.msteams` 下配置。 } ``` -- 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 +- 这里涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 - 完整 Teams 配置（凭证、webhook、私信/群组策略、按团队/按频道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC -IRC 由扩展支持，并在 `channels.irc` 下配置。 +IRC 由扩展提供支持，配置在 `channels.irc` 下。 ```json5 { @@ -707,13 +707,13 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 } ``` -- 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 -- 完整 IRC 渠道配置（主机/端口/TLS/频道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 +- 这里涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 +- 可选的 `channels.irc.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 完整 IRC 渠道配置（host/port/TLS/频道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 -### 多账户（所有渠道） +### 多账号（所有渠道） -为每个渠道运行多个账户（每个账户有自己的 `accountId`）： +每个渠道可运行多个账号（每个都有自己的 `accountId`）： ```json5 { @@ -734,28 +734,28 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 } ``` -- 省略 `accountId` 时会使用 `default`（CLI + 路由）。 -- 环境变量 token 仅适用于 **default** 账户。 -- 基础渠道设置会应用到所有账户，除非按账户覆盖。 -- 使用 `bindings[].match.accountId` 将每个账户路由到不同智能体。 -- 如果你通过 `openclaw channels add`（或渠道新手引导）添加一个非默认账户，而当前仍是单账户顶层渠道配置，OpenClaw 会先将按账户作用域的顶层单账户值提升到渠道账户映射中，以确保原始账户继续工作。大多数渠道会将它们移到 `channels..accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 -- 现有仅按渠道的绑定（无 `accountId`）仍会匹配默认账户；按账户作用域的绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过将按账户作用域的顶层单账户值移动到该渠道选定的提升账户来修复混合形状。大多数渠道使用 `accounts.default`；Matrix 可以保留现有的匹配命名/默认目标。 +- 当 `accountId` 省略时，使用 `default`（CLI + 路由）。 +- 环境变量 token 仅适用于**默认**账号。 +- 基础渠道设置会应用到所有账号，除非在账号级别覆盖。 +- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 +- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而当前仍在使用单账号顶级渠道配置，OpenClaw 会先将账号作用域的顶级单账号值提升到渠道账号映射中，以便原始账号继续工作。大多数渠道会将它们移动到 `channels..accounts.default`；Matrix 则可以保留现有匹配的命名/default 目标。 +- 现有仅渠道级的绑定（无 `accountId`）会继续匹配默认账号；账号级绑定仍然是可选的。 +- `openclaw doctor --fix` 也会通过将账号作用域的顶级单账号值移动到该渠道所选择的提升后账号中来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有匹配的命名/default 目标。 ### 其他扩展渠道 -许多扩展渠道都配置为 `channels.`，并在各自专属渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -参见完整渠道索引：[Channels](/zh-CN/channels)。 +许多扩展渠道使用 `channels.` 进行配置，并在各自专属渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +请参见完整渠道索引：[Channels](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认 **需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认**需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** -- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式下会被忽略。 -- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 只有在可以检测时（原生提及或至少一个模式），才会强制执行提及门控。 +- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式下会被忽略。 +- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 +- 仅当检测可能时（存在原生提及或至少一个模式）才会强制执行提及门控。 ```json5 { @@ -768,7 +768,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可以使用 `channels..historyLimit`（或按账户设置）来覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 #### 私信历史限制 @@ -818,12 +818,12 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 { commands: { native: "auto", // 在支持的平台上注册原生命令 - text: true, // 在聊天消息中解析 /commands + text: true, // 解析聊天消息中的 /commands bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, config: false, // 允许 /config debug: false, // 允许 /debug - restart: false, // 允许 /restart + gateway restart 工具 + restart: false, // 允许 /restart + Gateway 网关重启工具 allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -836,15 +836,15 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 - 文本命令必须是带前导 `/` 的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 打开原生命令，而对 Slack 保持关闭。 +- `native: "auto"` 会为 Discord/Telegram 打开原生命令，而保留 Slack 为关闭状态。 - 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。 -- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 -- `bash: true` 会为主机 shell 启用 `! `。需要 `tools.elevated.enabled` 且发送者位于 `tools.elevated.allowFrom.` 中。 -- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 对普通写作用域 operator 客户端仍然可用。 -- `channels..configWrites` 按渠道控制配置变更（默认：true）。 -- 对于多账户渠道，`channels..accounts..configWrites` 也会控制以该账户为目标的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `allowFrom` 为按提供商设置。设置后，它会成为**唯一**的授权来源（会忽略渠道允许列表/配对以及 `useAccessGroups`）。 -- `useAccessGroups: false` 允许在未设置 `allowFrom` 时，命令绕过访问组策略。 +- `channels.telegram.customCommands` 会添加额外的 Telegram bot 菜单项。 +- `bash: true` 启用主机 shell 的 `! `。需要 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 +- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还要求 `operator.admin`；只读的 `/config show` 仍可供普通具备写权限的 operator 客户端使用。 +- `channels..configWrites` 控制每个渠道的配置变更（默认：true）。 +- 对多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `allowFrom` 是按提供商设置的。设置后，它将成为**唯一**授权来源（渠道允许列表/配对 和 `useAccessGroups` 会被忽略）。 +- 当 `allowFrom` 未设置时，`useAccessGroups: false` 允许命令绕过访问组策略。 @@ -864,7 +864,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从工作区向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。未设置时，OpenClaw 会从 workspace 向上遍历自动检测。 ```json5 { @@ -874,8 +874,8 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 ### `agents.defaults.skills` -适用于未设置 -`agents.list[].skills` 的智能体的可选默认 Skills 允许列表。 +可选的默认 Skills 允许列表，适用于未设置 +`agents.list[].skills` 的智能体。 ```json5 { @@ -884,21 +884,20 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 list: [ { id: "writer" }, // 继承 github、weather { id: "docs", skills: ["docs-search"] }, // 替换默认值 - { id: "locked-down", skills: [] }, // 不启用 Skills + { id: "locked-down", skills: [] }, // 无 Skills ], }, } ``` -- 省略 `agents.defaults.skills` 表示默认情况下 Skills 不受限制。 -- 省略 `agents.list[].skills` 表示继承默认值。 -- 设置 `agents.list[].skills: []` 表示不启用 Skills。 -- 非空的 `agents.list[].skills` 列表是该智能体的最终集合； - 它不会与默认值合并。 +- 省略 `agents.defaults.skills`，默认对 Skills 不做限制。 +- 省略 `agents.list[].skills` 以继承默认值。 +- 设置 `agents.list[].skills: []` 表示无 Skills。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）的自动创建。 +禁用自动创建 workspace bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -908,7 +907,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 ### `agents.defaults.bootstrapMaxChars` -每个工作区引导文件在截断前的最大字符数。默认值：`20000`。 +每个 workspace bootstrap 文件在截断前的最大字符数。默认值：`20000`。 ```json5 { @@ -918,7 +917,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 ### `agents.defaults.bootstrapTotalMaxChars` -在所有工作区引导文件中注入的总字符数上限。默认值：`150000`。 +所有 workspace bootstrap 文件注入总字符数的上限。默认值：`150000`。 ```json5 { @@ -928,11 +927,11 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制在引导上下文被截断时，向智能体显示的警告文本。 +控制 bootstrap 上下文被截断时，对智能体可见的警告文本。 默认值：`"once"`。 -- `"off"`：永不将警告文本注入系统提示。 -- `"once"`：对每个唯一的截断签名注入一次警告（推荐）。 +- `"off"`：永不在系统提示中注入警告文本。 +- `"once"`：每个唯一截断签名只注入一次警告（推荐）。 - `"always"`：只要存在截断，每次运行都注入警告。 ```json5 @@ -943,11 +942,11 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 ### `agents.defaults.imageMaxDimensionPx` -在提供商调用之前，转录/工具图像块中最长边的最大像素尺寸。 +在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低的值通常可以减少 vision token 使用量和请求负载大小，适合大量截图的运行。 -较高的值可以保留更多视觉细节。 +更低的值通常会减少视觉 token 用量和请求负载大小，尤其适用于大量截图的运行。 +更高的值可保留更多视觉细节。 ```json5 { @@ -957,7 +956,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 ### `agents.defaults.userTimezone` -系统提示上下文使用的时区（不影响消息时间戳）。会回退到主机时区。 +用于系统提示上下文的时区（不影响消息时间戳）。会回退到主机时区。 ```json5 { @@ -1005,7 +1004,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 全局默认提供商参数 + params: { cacheRetention: "long" }, // 全局默认 provider 参数 pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1022,34 +1021,39 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 字符串形式仅设置主模型。 - - 对象形式设置主模型及有序故障转移模型。 + - 对象形式设置主模型以及有序故障转移模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 被 `image` 工具路径用作其视觉模型配置。 - - 当所选/默认模型无法接受图像输入时，也会用作回退路由。 + - 当选定/默认模型无法接受图像输入时，也会用作回退路由。 - `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被共享图像生成功能以及将来任何生成图像的工具/插件接口使用。 - - 典型值：`google/gemini-3.1-flash-image-preview`（原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-1`（OpenAI Images）。 - - 如果你直接选择某个 provider/model，也要配置匹配的提供商认证/API key（例如，`google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 需要 `OPENAI_API_KEY`，`fal/*` 需要 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断一个具有认证的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册图像生成提供商。 + - 被共享图像生成能力及未来任何生成图像的工具/插件接口使用。 + - 典型值：原生 Gemini 图像生成使用 `google/gemini-3.1-flash-image-preview`，fal 使用 `fal/fal-ai/flux/dev`，或 OpenAI Images 使用 `openai/gpt-image-1`。 + - 如果你直接选择 provider/model，请一并配置对应的 provider 凭证/API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断出有凭证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider-id 顺序尝试剩余已注册的图像生成提供商。 +- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 被共享音乐生成能力和内置 `music_generate` 工具使用。 + - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 + - 如果省略，`music_generate` 仍可推断出有凭证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider-id 顺序尝试剩余已注册的音乐生成提供商。 + - 如果你直接选择 provider/model，请一并配置对应的 provider 凭证/API key。 - `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被共享视频生成功能和内置 `video_generate` 工具使用。 + - 被共享视频生成能力和内置 `video_generate` 工具使用。 - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断一个具有认证的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册视频生成提供商。 - - 如果你直接选择某个 provider/model，也要配置匹配的提供商认证/API key。 - - 内置的 Qwen 视频生成提供商当前最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 + - 如果省略，`video_generate` 仍可推断出有凭证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider-id 顺序尝试剩余已注册的视频生成提供商。 + - 如果你直接选择 provider/model，请一并配置对应的 provider 凭证/API key。 + - 内置的 Qwen 视频生成 provider 当前最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及 provider 级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 - `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 被 `pdf` 工具用于模型路由。 - - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析的会话/默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，供 `pdf` 工具使用的默认 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具中提取回退模式默认考虑的最大页数。 + - 如果省略，PDF 工具会回退到 `imageModel`，再回退到解析后的会话/默认模型。 +- `pdfMaxBytesMb`：当调用时未传 `maxBytesMb`，则作为 `pdf` 工具的默认 PDF 大小限制。 +- `pdfMaxPages`：在 `pdf` 工具中，用于提取回退模式时考虑的默认最大页数。 - `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 -- `elevatedDefault`：智能体的默认提升输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果省略 provider，OpenClaw 会先尝试别名，再尝试与该精确模型 id 唯一匹配的已配置提供商，最后才回退到已配置默认提供商（这是已弃用的兼容行为，因此建议显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到首个已配置的 provider/model，而不是继续暴露一个已移除提供商的过时默认值。 -- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 -- `params`：应用于所有模型的全局默认提供商参数。设置于 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配 agent id）逐键覆盖。详情参见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- 变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退增删命令）会保存规范对象形式，并尽可能保留现有回退列表。 -- `maxConcurrent`：跨会话最大并行智能体运行数（每个会话仍然串行）。默认值：4。 +- `elevatedDefault`：智能体的默认 elevated 输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果省略 provider，OpenClaw 会先尝试别名，再尝试唯一配置的 provider 中与该精确模型 id 匹配的项，最后才回退到已配置的默认 provider（已弃用的兼容行为，因此推荐显式使用 `provider/model`）。如果该 provider 不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是继续使用过时且已移除的 provider 默认值。 +- `models`：用于 `/model` 的已配置模型目录和允许列表。每个条目可包含 `alias`（快捷方式）和 `params`（provider 特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用于所有模型的全局默认 provider 参数。在 `agents.defaults.params` 处设置（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 id）按键覆盖。详情参见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和故障转移 add/remove 命令）会保存规范对象形式，并在可能时保留现有的故障转移列表。 +- `maxConcurrent`：跨会话并行智能体运行的最大数量（每个会话内部仍串行）。默认值：4。 **内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： @@ -1066,11 +1070,11 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。 你自己配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用 thinking mode，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用。 -Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 `adaptive` thinking。 +Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置了 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。 +Z.AI 模型默认启用 `tool_stream` 用于工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 +Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 -- 当设置 `sessionArg` 时支持会话。 +- 当设置了 `sessionArg` 时支持会话。 - 当 `imageArg` 接受文件路径时支持图像透传。 ### `agents.defaults.heartbeat` @@ -1082,11 +1086,11 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 agents: { defaults: { heartbeat: { - every: "30m", // 0m 表示禁用 + every: "30m", // 0m 禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // 默认：false；true 时只保留工作区引导文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 时每次心跳都在全新会话中运行（无对话历史） + lightContext: false, // 默认：false；true 时仅保留 workspace bootstrap 文件中的 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 时每次心跳都在新会话中运行（无对话历史） session: "main", to: "+15555550123", directPolicy: "allow", // allow（默认）| block @@ -1100,13 +1104,13 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API-key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 - `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告负载。 -- `directPolicy`：直接/私信交付策略。`allow`（默认）允许直接目标交付。`block` 会抑制直接目标交付，并输出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都会在一个没有先前对话历史的全新会话中运行。其隔离模式与 cron 的 `sessionTarget: "isolated"` 相同。可将每次心跳的 token 成本从约 100K 降至约 2-5K。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 -- 心跳会执行完整智能体轮次——较短间隔会消耗更多 token。 +- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并输出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，心跳运行使用轻量 bootstrap 上下文，并仅保留 workspace bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都在没有任何既有对话历史的新会话中运行。隔离模式与 cron 的 `sessionTarget: "isolated"` 相同。可将单次心跳 token 成本从约 100K 降至约 2-5K。 +- 按智能体设置：使用 `agents.list[].heartbeat`。如果任意智能体定义了 `heartbeat`，则**只有这些智能体**会运行心跳。 +- 心跳会运行完整智能体回合——更短的间隔会消耗更多 token。 ### `agents.defaults.compaction` @@ -1120,9 +1124,9 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 - postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 + postCompactionSections: ["Session Startup", "Red Lines"], // [] 禁用重新注入 model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 - notifyUser: true, // 当 compaction 开始时发送简短通知（默认：false） + notifyUser: true, // compaction 开始时向用户发送简短通知（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1135,18 +1139,18 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（用于长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 在中止单次 compaction 操作前允许的最大秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内建的不透明标识符保留指引。 +- `mode`：`default` 或 `safeguard`（对长历史执行分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止前，单次 compaction 操作允许的最大秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指引。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：compaction 后重新注入的可选 AGENTS.md H2/H3 节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。若未设置或显式设为该默认对，旧版 `Every Session`/`Safety` 标题也会被接受为兼容回退。 -- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应保持一个模型，而 compaction 摘要应在另一个模型上运行时使用；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如 “Compacting context...”）。默认禁用，以保持 compaction 静默进行。 -- `memoryFlush`：在自动 compaction 之前进行静默智能体轮次，以存储持久记忆。若工作区为只读，则会跳过。 +- `postCompactionSections`：compaction 后重新注入的可选 AGENTS.md H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。未设置或显式设置为该默认对时，旧版 `Every Session`/`Safety` 标题也会作为兼容回退被接受。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应继续使用某个模型，而 compaction 摘要应切换到另一个模型时使用；未设置时，compaction 使用会话主模型。 +- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如 “Compacting context...”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：在自动 compaction 前执行的静默智能体回合，用于存储持久记忆。当 workspace 为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1170,23 +1174,23 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 启用修剪流程。 -- `ttl` 控制距离上次缓存触碰后，多长时间可以再次运行修剪。 -- 修剪会先对过大的工具结果进行软截断，然后在需要时硬清除更旧的工具结果。 +- `mode: "cache-ttl"` 启用修剪处理。 +- `ttl` 控制距离上次缓存触碰后，多久可以再次运行修剪。 +- 修剪会先对过大的工具结果做软修剪，如仍有需要，再对更旧的工具结果进行硬清除。 -**软截断**会保留开头和结尾，并在中间插入 `...`。 +**软修剪**会保留开头和结尾，并在中间插入 `...`。 **硬清除**会用占位符替换整个工具结果。 -注意： +说明： -- 图像块永远不会被截断/清除。 -- 比例基于字符数（近似值），而不是精确 token 计数。 -- 若 assistant 消息数少于 `keepLastAssistants`，则跳过修剪。 +- 图像块永远不会被修剪/清除。 +- 比例基于字符数（近似），不是精确 token 数。 +- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 -行为细节参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为细节请参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1204,13 +1208,13 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用块式回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账户变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：块式回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 +- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节参见 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节请参见 [Streaming](/zh-CN/concepts/streaming)。 -### 输入中指示器 +### 输入指示器 ```json5 { @@ -1223,7 +1227,7 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 } ``` -- 默认值：对于私聊/提及消息为 `instant`，对于未提及的群组聊天为 `message`。 +- 默认值：私聊/被提及时为 `instant`，未被提及的群聊中为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 @@ -1232,7 +1236,7 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 ### `agents.defaults.sandbox` -为嵌入式智能体提供可选沙箱隔离。完整指南参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南请参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1335,16 +1339,16 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 - `ssh`：通用 SSH 远程运行时 - `openshell`：OpenShell 运行时 -选择 `backend: "openshell"` 时，运行时专属设置移动到 +当选择 `backend: "openshell"` 时，运行时专用设置会移动到 `plugins.entries.openshell.config`。 **SSH 后端配置：** -- `target`：`user@host[:port]` 形式的 SSH 目标 +- `target`：格式为 `user@host[:port]` 的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域工作区的远程绝对根目录 +- `workspaceRoot`：用于每作用域 workspace 的远程绝对根目录 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 +- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 会在运行时将内联内容或 SecretRef 实体化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 **SSH 认证优先级：** @@ -1352,27 +1356,27 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前从活动 secrets 运行时快照中解析 +- 以 SecretRef 为后盾的 `*Data` 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后对远程工作区进行一次初始化 -- 然后保持远程 SSH 工作区为规范副本 +- 在创建或重建后，先对远程 workspace 进行一次初始化填充 +- 之后将远程 SSH workspace 作为规范状态保持 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程变更同步回主机 - 不支持沙箱浏览器容器 -**工作区访问：** +**workspace 访问：** -- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区 -- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` -- `rw`：智能体工作区以读写方式挂载到 `/workspace` +- `none`：每作用域的沙箱 workspace 位于 `~/.openclaw/sandboxes` +- `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 只读挂载到 `/agent` +- `rw`：智能体 workspace 以读写方式挂载到 `/workspace` **作用域：** -- `session`：每会话一个容器 + 工作区 -- `agent`：每个智能体一个容器 + 工作区（默认） -- `shared`：共享容器和工作区（无跨会话隔离） +- `session`：每会话一个容器 + workspace +- `agent`：每个智能体一个容器 + workspace（默认） +- `shared`：共享容器和 workspace（不进行跨会话隔离） **OpenShell 插件配置：** @@ -1402,30 +1406,30 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：执行前将本地内容同步到远程，执行后同步回本地；本地工作区保持为规范副本 -- `remote`：创建沙箱时只向远程初始化一次，之后保持远程工作区为规范副本 +- `mirror`：在 exec 前从本地填充到远程，exec 后再同步回本地；本地 workspace 保持为规范状态 +- `remote`：在创建沙箱时仅向远程填充一次，之后将远程 workspace 作为规范状态保持 -在 `remote` 模式下，OpenClaw 之外在主机本地进行的编辑，在初始化步骤后不会自动同步到沙箱。 -传输通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选 mirror 同步。 +在 `remote` 模式下，OpenClaw 之外在主机本地进行的编辑，在初始化填充步骤后不会自动同步进沙箱。 +传输层是通过 SSH 连接到 OpenShell 沙箱，但由插件负责沙箱生命周期以及可选的镜像同步。 -**`setupCommand`** 在容器创建后仅运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 -**容器默认使用 `network: "none"`**——若智能体需要出站访问，设置为 `"bridge"`（或自定义桥接网络）。 -默认阻止 `"host"`。默认也阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急放行）。 +**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 +默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗模式）。 -**入站附件** 会被暂存到活动工作区的 `media/inbound/*` 中。 +**传入附件** 会被暂存到活动 workspace 下的 `media/inbound/*` 中。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体 bind 会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。会将 noVNC URL 注入系统提示。无需在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。会将 noVNC URL 注入系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +默认通过 VNC 认证提供 noVNC 观察访问，OpenClaw 会输出短时有效的 token URL（而不是在共享 URL 中暴露密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确需要全局桥接连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选，用于在容器边界将 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅为沙箱浏览器容器挂载额外主机目录。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 -- 启动默认值定义于 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： +- `allowHostControl: false`（默认）会阻止沙箱隔离会话将主机浏览器作为目标。 +- `network` 默认是 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确希望使用全局 bridge 连通性时才设置为 `bridge`。 +- `cdpSourceRange` 可选地将 CDP 入口限制为容器边缘上的某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅将额外主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替代浏览器容器中的 `docker.binds`。 +- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1443,16 +1447,16 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短期有 - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`（默认启用） - - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果你的 WebGL/3D 工作流需要它们，可通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用。 - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会在你的工作流 - 依赖扩展时重新启用扩展。 + - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` + 默认启用，如需 WebGL/3D，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，以适配依赖扩展的工作流。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设置为 `0` 则使用 Chromium 的 - 默认进程数限制。 - - 以及当启用 `noSandbox` 时的 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；若要修改容器默认行为，请使用带自定义 - entrypoint 的自定义浏览器镜像。 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设为 `0` 则使用 Chromium 的 + 默认进程限制。 + - 当启用 `noSandbox` 时，还会附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；若要更改容器默认行为，请使用自定义浏览器镜像和自定义 + entrypoint。 @@ -1478,11 +1482,11 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } - thinkingDefault: "high", // 按智能体设置的 thinking 级别覆盖 - reasoningDefault: "on", // 按智能体设置的 reasoning 可见性覆盖 - fastModeDefault: false, // 按智能体设置的 fast mode 覆盖 - params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params - skills: ["docs-search"], // 设置后会替换 agents.defaults.skills + thinkingDefault: "high", // 按智能体覆盖 thinking 级别 + reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性 + fastModeDefault: false, // 按智能体覆盖 fast mode + params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params + skills: ["docs-search"], // 设置后替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1513,20 +1517,20 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `id`：稳定的智能体 id（必填）。 -- `default`：当设置多个时，首个生效（会记录警告）。如果都未设置，则列表中的首项为默认值。 -- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖二者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 Cron 任务仍会继承默认回退，除非你设置 `fallbacks: []`。 -- `params`：合并到 `agents.defaults.models` 中所选模型条目之上的按智能体流参数。用它为某个智能体做 `cacheRetention`、`temperature` 或 `maxTokens` 等特定覆盖，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。如果省略，则该智能体在 `agents.defaults.skills` 已设置时会继承它；显式列表会替换默认值而不是合并，`[]` 表示不启用 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置按消息或按会话覆盖时，会覆盖此智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话 reasoning 覆盖时适用。 -- `fastModeDefault`：可选的按智能体默认 fast mode（`true | false`）。当未设置按消息或按会话 fast-mode 覆盖时适用。 -- `runtime`：可选的按智能体运行时描述符。当智能体应默认为 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 -- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 +- `id`：稳定的智能体 ID（必填）。 +- `default`：设置多个时，以第一个为准（会记录警告）。如果都未设置，则列表第一项为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局故障转移）。只覆盖 `primary` 的 cron 作业仍会继承默认故障转移，除非你设置 `fallbacks: []`。 +- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型项之上。用于按智能体覆盖 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 +- `skills`：可选的按智能体 Skills 允许列表。省略时，若已设置 `agents.defaults.skills`，则智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 +- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置按消息或按会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话的 reasoning 覆盖时应用。 +- `fastModeDefault`：可选的按智能体默认 fast mode 值（`true | false`）。当未设置按消息或按会话的 fast-mode 覆盖时应用。 +- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"`，并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `identity.avatar`：workspace 相对路径、`http(s)` URL 或 `data:` URI。 - `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 -- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求者会话处于沙箱隔离中，`sessions_spawn` 会拒绝任何会以非沙箱方式运行的目标。 -- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 +- `subagents.allowAgents`：`sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅相同智能体）。 +- 沙箱继承保护：如果请求方会话已启用沙箱隔离，`sessions_spawn` 会拒绝那些将运行在非沙箱环境中的目标。 +- `subagents.requireAgentId`：为 true 时，阻止 `sessions_spawn` 调用省略 `agentId`（强制显式选择配置；默认：false）。 --- @@ -1551,9 +1555,9 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认为 route），持久 ACP 对话绑定使用 `acp`。 +- `type`（可选）：普通路由使用 `route`（缺失时默认为 route），持久 ACP 会话绑定使用 `acp` - `match.channel`（必填） -- `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户） +- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） - `match.guildId` / `match.teamId`（可选；渠道特定） - `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` @@ -1567,9 +1571,9 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 5. `match.accountId: "*"`（渠道范围） 6. 默认智能体 -在每一层级内，首个匹配的 `bindings` 条目获胜。 +在每一层级内，第一个匹配的 `bindings` 条目生效。 -对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账户 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 +对 `type: "acp"` 条目，OpenClaw 会按精确会话标识（`match.channel` + account + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 ### 按智能体访问配置 @@ -1591,7 +1595,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - + ```json5 { @@ -1666,7 +1670,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -优先级细节参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节请参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1692,7 +1696,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 父线程 fork 超过此 token 数时跳过（0 表示禁用） + parentForkMaxTokens: 100000, // 父线程 fork 超过此 token 数时跳过（0 禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1704,8 +1708,8 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时的无活动自动取消聚焦（`0` 表示禁用） - maxAgeHours: 0, // 默认按小时的硬性最大时长（`0` 表示禁用） + idleHours: 24, // 默认按小时计算的无活动自动取消聚焦（`0` 禁用） + maxAgeHours: 0, // 默认按小时计算的硬最大年龄（`0` 禁用） }, mainKey: "main", // 旧版（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, @@ -1720,34 +1724,34 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在渠道上下文中，每个发送者都有独立会话。 - - `global`：渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 -- **`dmScope`**：私信如何分组。 + - `per-sender`（默认）：在某个渠道上下文中，每个发送者都有隔离的会话。 + - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 +- **`dmScope`**：私信分组方式。 - `main`：所有私信共享主会话。 - `per-peer`：按发送者 id 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - - `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（推荐用于多账户）。 -- **`identityLinks`**：将规范 id 映射到带 provider 前缀的 peer，用于跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 在本地时间 `atHour` 重置；`idle` 在 `idleMinutes` 后重置。若两者都已配置，则先到期者生效。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建 fork 线程会话时允许的父会话 `totalTokens` 上限（默认 `100000`）。 + - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 +- **`identityLinks`**：将规范 id 映射到带提供商前缀的对等方，用于跨渠道会话共享。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。两者都配置时，先到期者生效。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 别名接受。 +- **`parentForkMaxTokens`**：创建 fork 线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 - 如果父会话 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。 - - 设置为 `0` 可禁用该保护，并始终允许从父会话 fork。 -- **`mainKey`**：旧版字段。运行时现在始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体间交换时最大来回回复轮数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链式对话。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个 deny 优先。 -- **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 执行清理。 - - `pruneAfter`：陈旧条目的保留期限截止时间（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过此大小时进行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下优先移除最旧的工件/会话。 - - `highWaterBytes`：预算清理后的可选目标值。默认为 `maxDiskBytes` 的 `80%`。 + - 设置为 `0` 可禁用此保护，并始终允许父级 fork。 +- **`mainKey`**：旧版字段。运行时现在始终对主私聊 bucket 使用 `"main"`。 +- **`agentToAgent.maxPingPongTurns`**：智能体间交互中，智能体之间最大来回回复轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式传递。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 别名也支持）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 优先。 +- **`maintenance`**：会话存储清理和保留控制。 + - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 + - `pruneAfter`：旧条目的年龄截止（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中允许的最大条目数（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过该大小时执行轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认等于 `pruneAfter`；设置为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的工件/会话。 + - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：按小时设置的默认无活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：按小时设置的默认硬性最大时长（`0` 表示禁用；提供商可覆盖） + - `enabled`：主默认开关（provider 可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：默认按小时计算的无活动自动取消聚焦（`0` 禁用；provider 可覆盖） + - `maxAgeHours`：默认按小时计算的硬最大年龄（`0` 禁用；provider 可覆盖） @@ -1773,7 +1777,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, }, inbound: { - debounceMs: 2000, // 0 表示禁用 + debounceMs: 2000, // 0 禁用 byChannel: { whatsapp: 5000, slack: 1500, @@ -1785,36 +1789,36 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 回复前缀 -按渠道/账户覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（越具体越优先）：账户 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 +解析顺序（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** -| 变量 | 描述 | 示例 | -| ----------------- | ---------------- | --------------------------- | -| `{model}` | 短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 描述 | 示例 | +| ----------------- | ------------------ | --------------------------- | +| `{model}` | 短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | provider 名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### 确认反应 +### Ack reaction -- 默认为活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 +- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解析顺序：账户 → 渠道 → `messages.ackReaction` → identity 回退。 +- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 - 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上于回复后移除 ack。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时，如果 ack 反应处于活动状态，则保持状态反应启用。 - 在 Telegram 上，请显式将其设为 `true` 以启用生命周期状态反应。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除 ack。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reactions。 + 在 Slack 和 Discord 上，未设置时，当 ack reactions 处于活动状态会保持启用状态 reactions。 + 在 Telegram 上，需要显式将其设为 `true` 才能启用生命周期状态 reactions。 -### 入站防抖 +### 入站去抖 -将来自同一发送者的快速纯文本消息批处理为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 +将同一发送者快速发送的纯文本消息批处理为单个智能体回合。媒体/附件会立即刷新。控制命令会绕过去抖。 ### TTS（文本转语音） @@ -1857,18 +1861,18 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 按会话覆盖。 -- `summaryModel` 会覆盖 `agents.defaults.model.primary` 作为自动摘要模型。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认值为 `false`（显式启用）。 +- `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 会按会话覆盖。 +- `summaryModel` 会覆盖自动摘要的 `agents.defaults.model.primary`。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需选择启用）。 - API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，再然后是 `https://api.openai.com/v1`。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置、然后 `OPENAI_TTS_BASE_URL`、再然后 `https://api.openai.com/v1`。 - 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。 --- ## Talk -Talk mode 的默认值（macOS/iOS/Android）。 +Talk 模式的默认值（macOS/iOS/Android）。 ```json5 { @@ -1892,51 +1896,51 @@ Talk mode 的默认值（macOS/iOS/Android）。 } ``` -- `talk.provider` 在配置了多个 Talk 提供商时必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅为兼容用途，并会自动迁移到 `talk.providers.`。 +- 当配置了多个 Talk provider 时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 - Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 仅当未配置任何 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好的名称。 -- `silenceTimeoutMs` 控制 Talk mode 在用户静音后等待多久才发送转录。未设置时保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多长时间再发送转录。未设置时保持平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- ## 工具 -### 工具配置 +### 工具配置文件 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： +`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置一个基础允许列表： -本地新手引导会在未设置时，将新的本地配置默认设为 `tools.profile: "coding"`（已存在的显式配置会保留）。 +本地新手引导会在新本地配置未设置时默认使用 `tools.profile: "coding"`（现有显式 profile 会保留）。 -| 配置 | 包含内容 | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | -| `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` | -| `full` | 无限制（等同于未设置） | +| 配置文件 | 包含内容 | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | 仅 `session_status` | +| `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` | +| `full` | 不做限制（等同于未设置） | ### 工具组 -| 组 | 工具 | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `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` | 所有内置工具（不包括 provider 插件） | +| 组 | 工具 | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `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` | 所有内置工具（不包括 provider 插件） | ### `tools.allow` / `tools.deny` -全局工具 allow/deny 策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭，也会应用。 +全局工具 allow/deny 策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭也会应用。 ```json5 { @@ -1946,7 +1950,7 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -进一步限制特定提供商或模型的工具。顺序：基础配置 → provider 配置 → allow/deny。 +进一步限制特定 provider 或模型的工具。顺序：基础 profile → provider profile → allow/deny。 ```json5 { @@ -1962,7 +1966,7 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.elevated` -控制沙箱外的提升 exec 访问： +控制沙箱之外的 elevated exec 访问： ```json5 { @@ -1979,8 +1983,8 @@ Talk mode 的默认值（macOS/iOS/Android）。 ``` - 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅适用于单条消息。 -- 提升的 `exec` 会绕过沙箱隔离，并使用已配置的 escape 路径（默认 `gateway`，或者当 exec 目标为 `node` 时使用 `node`）。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 +- Elevated `exec` 会绕过沙箱隔离，并使用配置的 escape 路径（默认 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 ### `tools.exec` @@ -2004,8 +2008,8 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查默认**关闭**。设置 `enabled: true` 可激活检测。 -设置可以全局定义在 `tools.loopDetection` 中，也可以在每个智能体的 `agents.list[].tools.loopDetection` 中覆盖。 +工具循环安全检查**默认关闭**。设置 `enabled: true` 可启用检测。 +可在 `tools.loopDetection` 中全局定义，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 ```json5 { @@ -2026,14 +2030,14 @@ Talk mode 的默认值（macOS/iOS/Android）。 } ``` -- `historySize`：为循环分析保留的最大工具调用历史数。 -- `warningThreshold`：重复无进展模式的警告阈值。 -- `criticalThreshold`：阻止关键循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：对任何无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）发出警告/阻止。 -- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 -- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证将失败。 +- `historySize`：为循环分析保留的最大工具调用历史。 +- `warningThreshold`：用于发出警告的重复无进展模式阈值。 +- `criticalThreshold`：用于阻止关键循环的更高重复阈值。 +- `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 +- `detectors.genericRepeat`：对同工具/同参数的重复调用发出警告。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 +- `detectors.pingPong`：对交替式无进展对模式发出警告/阻止。 +- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，校验将失败。 ### `tools.web` @@ -2067,7 +2071,7 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.media` -配置入站媒体理解（图像/音频/视频）： +配置传入媒体理解（图像/音频/视频）： ```json5 { @@ -2098,9 +2102,9 @@ Talk mode 的默认值（macOS/iOS/Android）。 -**提供商条目**（`type: "provider"` 或省略）： +**Provider 条目**（`type: "provider"` 或省略）： -- `provider`：API 提供商 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） +- `provider`：API provider id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） - `model`：模型 id 覆盖 - `profile` / `preferredProfile`：`auth-profiles.json` 配置选择 @@ -2115,7 +2119,7 @@ Talk mode 的默认值（macOS/iOS/Android）。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 - 失败时会回退到下一个条目。 -提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 @@ -2134,7 +2138,7 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.sessions` -控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以定位哪些会话。 +控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可以针对哪些会话。 默认值：`tree`（当前会话 + 由其派生的会话，例如子智能体）。 @@ -2149,13 +2153,13 @@ Talk mode 的默认值（macOS/iOS/Android）。 } ``` -注意： +说明： - `self`：仅当前会话键。 - `tree`：当前会话 + 由当前会话派生的会话（子智能体）。 -- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者会话，可能包括其他用户）。 -- `all`：任意会话。跨智能体定位仍需要 `tools.agentToAgent`。 -- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者隔离的会话，则可能包含其他用户）。 +- `all`：任意会话。跨智能体目标仍然需要 `tools.agentToAgent`。 +- 沙箱限制：当当前会话已启用沙箱隔离，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2166,29 +2170,29 @@ Talk mode 的默认值（macOS/iOS/Android）。 tools: { sessions_spawn: { attachments: { - enabled: false, // 显式启用：设为 true 以允许内联文件附件 + enabled: false, // 选择启用：设为 true 以允许内联文件附件 maxTotalBytes: 5242880, // 所有文件总计 5 MB maxFiles: 50, maxFileBytes: 1048576, // 每个文件 1 MB - retainOnSessionKeep: false, // cleanup="keep" 时保留附件 + retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件 }, }, }, } ``` -注意： +说明： - 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会实体化到子工作区中的 `.openclaw/attachments//`，并带有 `.manifest.json`。 +- 文件会在子 workspace 中实体化到 `.openclaw/attachments//`，并附带 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会用严格字母表/填充检查以及解码前大小保护进行验证。 -- 文件权限为目录 `0700`、文件 `0600`。 -- 清理由 `cleanup` 策略控制：`delete` 始终移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 +- Base64 输入会进行严格字母表/填充校验，并在解码前进行大小保护检查。 +- 文件权限：目录为 `0700`，文件为 `0600`。 +- 清理遵循 `cleanup` 策略：`delete` 总会删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非某条运行时特定自动启用规则适用。 +实验性内置工具标志。默认关闭，除非有运行时特定的自动启用规则。 ```json5 { @@ -2200,11 +2204,11 @@ Talk mode 的默认值（macOS/iOS/Android）。 } ``` -注意： +说明： -- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：对非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。 -- 启用后，系统提示还会添加使用指导，使模型仅在重要工作中使用它，并始终最多只有一个步骤处于 `in_progress`。 +- `planTool`：为非琐碎的多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认值：对非 OpenAI provider 为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。 +- 启用后，系统提示也会加入使用指导，以便模型仅在重要工作中使用它，并始终最多只有一个步骤处于 `in_progress`。 ### `agents.defaults.subagents` @@ -2224,16 +2228,16 @@ Talk mode 的默认值（macOS/iOS/Android）。 } ``` -- `model`：派生子智能体的默认模型。若省略，子智能体继承调用者的模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 id 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。 +- `model`：派生子智能体的默认模型。若省略，子智能体会继承调用者的模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 id 的默认允许列表（`["*"]` = 任意；默认：仅相同智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时秒数。`0` 表示无超时。 - 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- -## 自定义提供商和 base URL +## 自定义 provider 和 base URL -OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义 provider。 ```json5 { @@ -2262,48 +2266,48 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 使用 `authHeader: true` + `headers` 以满足自定义认证需求。 +- 对自定义认证需求，使用 `authHeader: true` + `headers`。 - 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 对匹配的提供商 ID，合并优先级如下： - - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在当前 config/auth-profile 上下文中该提供商不是 SecretRef 管理时才优先。 - - SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化解析后的 secret。 - - SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 - - 为空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高值。 - - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；用它可以限制有效上下文，而不改变原生模型元数据。 +- 匹配 provider ID 的合并优先级： + - 非空的智能体 `models.json` `baseUrl` 优先。 + - 非空的智能体 `apiKey` 仅在该 provider 在当前 config/auth-profile 上下文中不由 SecretRef 管理时优先。 + - 由 SecretRef 管理的 provider `apiKey` 值会从源标记（环境变量引用用 `ENV_VAR_NAME`，文件/exec 引用用 `secretref-managed`）刷新，而不是持久化已解析的 secret。 + - 由 SecretRef 管理的 provider header 值也会从源标记刷新（环境变量引用用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用用 `secretref-managed`）。 + - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 + - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。 + - 匹配模型的 `contextTokens` 在存在时会保留显式运行时上限；使用它可在不改变模型原生元数据的情况下限制有效上下文。 - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - 标记持久化以源为准：标记从活动源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。 -### 提供商字段详情 +### Provider 字段详情 -- `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：按提供商 id 键控的自定义提供商映射。 +- `models.mode`：provider 目录行为（`merge` 或 `replace`）。 +- `models.providers`：按 provider id 键控的自定义 provider 映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：提供商凭证（推荐使用 SecretRef/环境变量替换）。 +- `models.providers.*.apiKey`：provider 凭证（优先使用 SecretRef/环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：用于 Ollama + `openai-completions` 时，将 `options.num_ctx` 注入请求（默认：`true`）。 -- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 +- `models.providers.*.injectNumCtxForOpenAICompat`：对 Ollama + `openai-completions`，向请求中注入 `options.num_ctx`（默认：`true`）。 +- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传递凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 -- `models.providers.*.headers`：用于代理/租户路由的额外静态 header。 -- `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 - - `request.headers`：额外 header（会与 provider 默认值合并）。值接受 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用 provider 内建认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`、可选 `prefix`）。 +- `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 +- `models.providers.*.request`：模型 provider HTTP 请求的传输覆盖。 + - `request.headers`：额外 headers（与 provider 默认值合并）。值接受 SecretRef。 + - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用 provider 内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都接受 SecretRef）、`serverName`、`insecureSkipVerify`。 -- `models.providers.*.models`：显式提供商模型目录条目。 + - `request.tls`：直连的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都接受 SecretRef）、`serverName`、`insecureSkipVerify`。 +- `models.providers.*.models`：显式 provider 模型目录条目。 - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 - `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于带非空且非原生 `baseUrl`（主机不是 `api.openai.com`）的 `api: "openai-completions"`，OpenClaw 会在运行时强制将其设为 `false`。为空/省略的 `baseUrl` 会保留默认 OpenAI 行为。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。 -- `plugins.entries.amazon-bedrock.config.discovery.enabled`：打开/关闭隐式发现。 -- `plugins.entries.amazon-bedrock.config.discovery.region`：发现使用的 AWS 区域。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选提供商 id 过滤器，用于定向发现。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对 `api: "openai-completions"` 且非空、非原生 `baseUrl`（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空/省略的 `baseUrl` 会保留默认 OpenAI 行为。 +- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根路径。 +- `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。 +- `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选 provider-id 过滤器，用于定向发现。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新轮询间隔。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：发现模型的回退上下文窗口。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：发现模型的回退最大输出 token。 -### 提供商示例 +### Provider 示例 @@ -2339,7 +2343,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 +对 Cerebras 使用 `cerebras/zai-glm-4.7`；对 Z.AI 直连使用 `zai/glm-4.7`。 @@ -2373,11 +2377,11 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 是可接受别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 +设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` -- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 若要使用通用端点，请定义一个带 base URL 覆盖的自定义提供商。 +- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 对于通用端点，请定义一个带 base URL 覆盖的自定义 provider。 @@ -2416,11 +2420,11 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -中国端点使用：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 +中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 -原生 Moonshot 端点会在共享 -`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 现在会基于端点 -能力而不是仅基于内置 provider id 来做判断。 +原生 Moonshot 端点会在共享的 +`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 现在基于端点 +能力而不是仅基于内置 provider id 来决定这一点。 @@ -2438,11 +2442,11 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -与 Anthropic 兼容的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +兼容 Anthropic 的内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2477,7 +2481,7 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 +Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 @@ -2520,9 +2524,9 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 设置 `MINIMAX_API_KEY`。快捷方式： `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 -模型目录现在默认仅使用 M2.7。 -在 Anthropic 兼容的流式路径上，OpenClaw 默认禁用 MiniMax thinking， -除非你显式自行设置 `thinking`。`/fast on` 或 +模型目录现在默认仅包含 M2.7。 +在 Anthropic 兼容的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认关闭 MiniMax thinking。 +`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 @@ -2530,7 +2534,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在足够强大的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能充足的硬件上通过 LM Studio Responses API 运行大型本地模型，并保留托管模型以便故障转移。 @@ -2561,14 +2565,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。 +- `allowBundled`：仅针对内置 Skills 的可选允许列表（受管/workspace Skills 不受影响）。 - `load.extraDirs`：额外的共享 Skills 根目录（最低优先级）。 -- `install.preferBrew`：为 true 时，如果可用则优先使用 Homebrew 安装器， - 然后再回退到其他安装器类型。 +- `install.preferBrew`：为 true 时，若 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 - `install.nodeManager`：用于 `metadata.openclaw.install` - 规格的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使某个 skill 已内置/安装，也会禁用它。 -- `entries..apiKey`：为声明主环境变量的 skill 提供的便捷字段（明文字符串或 SecretRef 对象）。 + 规格的 node 安装器偏好 + （`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使是内置/已安装 Skill，也会禁用该 Skill。 +- `entries..apiKey`：为声明了主环境变量的 Skill 提供的便捷字段（明文字符串或 SecretRef 对象）。 --- @@ -2597,34 +2601,34 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- 设备发现同时接受原生 OpenClaw 插件、兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。 - **配置更改需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 - `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 -- `plugins.entries..env`：插件作用域的环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会变更提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 和受支持 bundle 提供的 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任此插件可为后台子智能体运行请求按次 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖所允许的规范 `provider/model` 目标可选允许列表。仅在你明确希望允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（若可用，则由原生 OpenClaw 插件 schema 校验）。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl Web 抓取提供商设置。 - - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 +- `plugins.entries..env`：插件作用域环境变量映射。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 和受支持 bundle 提供的 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次执行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你有意允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（如果可用，会由原生 OpenClaw 插件 schema 校验）。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch provider 设置。 + - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。 - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 - - `onlyMainContent`：仅提取页面主要内容（默认：`true`）。 - - `maxAgeMs`：缓存最大年龄（毫秒）（默认：`172800000` / 2 天）。 + - `onlyMainContent`：仅提取页面主体内容（默认：`true`）。 + - `maxAgeMs`：最大缓存年龄（毫秒）（默认：`172800000` / 2 天）。 - `timeoutSeconds`：抓取请求超时秒数（默认：`60`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok Web 搜索）设置。 - - `enabled`：启用 X Search 提供商。 +- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 + - `enabled`：启用 X Search provider。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：memory dreaming（实验性）设置。阶段和阈值见 [Dreaming](/zh-CN/concepts/dreaming)。 +- `plugins.entries.memory-core.config.dreaming`：记忆 dreaming（实验性）设置。阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `enabled`：dreaming 主开关（默认 `false`）。 - - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 + - `frequency`：每次完整 dreaming 扫描的 cron 周期（默认 `"0 3 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 已启用的 Claude bundle 插件还可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为经过净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值是 `"legacy"`，除非你安装并选择了其他引擎。 -- `plugins.installs`：CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 +- 已启用的 Claude bundle 插件还可以从 `settings.json` 提供内嵌 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认是 `"legacy"`，除非你安装并选择了其他引擎。 +- `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令，而不是手动编辑。 + - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 参见 [Plugins](/zh-CN/tools/plugin)。 @@ -2639,7 +2643,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // 默认的受信网络模式 + dangerouslyAllowPrivateNetwork: true, // 默认受信网络模式 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2667,28 +2671,25 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认为 `true`（受信网络模型）。 -- 将 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` 设为严格的仅公共网络浏览导航模式。 -- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认 `true`（受信网络模型）。 +- 若要启用严格的仅公网浏览器导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。 +- 在严格模式下，远程 CDP profile 端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止。 - `ssrfPolicy.allowPrivateNetwork` 仍支持作为旧版别名。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 -- 远程配置为仅附加（start/stop/reset 已禁用）。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。 +- 远程 profile 为仅附加模式（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)； - 当提供方直接提供 DevTools WebSocket URL 时使用 WS(S)。 -- `existing-session` 配置仅适用于主机，并使用 Chrome MCP 而不是 CDP。 -- `existing-session` 配置可以设置 `userDataDir` 以定位特定的 - Chromium 浏览器配置，例如 Brave 或 Edge。 -- `existing-session` 配置保留当前 Chrome MCP 路由限制： - 基于快照/引用的操作，而不是 CSS 选择器定位、单文件上传 - hooks、无对话框超时覆盖、无 `wait --load networkidle`，以及无 + 当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当 provider 直接给你 DevTools WebSocket URL 时使用 WS(S)。 +- `existing-session` profile 仅适用于主机，并使用 Chrome MCP 而不是 CDP。 +- `existing-session` profile 可设置 `userDataDir` 来指定特定 + Chromium 系浏览器 profile，例如 Brave 或 Edge。 +- `existing-session` profile 会保留当前 Chrome MCP 路由限制： + 使用 snapshot/ref 驱动的操作，而非 CSS selector 定位，仅支持单文件上传 + hooks，不支持对话框超时覆盖，不支持 `wait --load networkidle`，也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 时 - 显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（若为 Chromium 内核）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- 控制服务：仅 loopback（端口由 `gateway.port` 推导，默认 `18791`）。 -- `extraArgs` 会向本地 Chromium 启动追加额外标志（例如 - `--disable-gpu`、窗口尺寸或调试标志）。 +- 本地托管的 `openclaw` profiles 会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 时显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会向本地 Chromium 启动附加额外标志（例如 `--disable-gpu`、窗口大小或调试标志）。 --- @@ -2700,14 +2701,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji、短文本、图像 URL 或 data URI + avatar: "CB", // emoji、短文本、图片 URL 或 data URI }, }, } ``` -- `seamColor`：原生应用 UI 边框的强调色（Talk Mode 气泡色调等）。 -- `assistant`：Control UI 身份覆盖。会回退到当前活动智能体身份。 +- `seamColor`：原生应用 UI chrome 的强调色（Talk 模式气泡着色等）。 +- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。 --- @@ -2723,7 +2724,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 mode: "token", // none | token | password | trusted-proxy token: "your-token", // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // 适用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth + // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2740,8 +2741,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 enabled: true, basePath: "/openclaw", // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必需 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header 源回退模式 + // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2755,7 +2756,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // 可选。默认 false。 allowRealIpFallback: false, tools: { - // 额外的 /tools/invoke HTTP deny + // 对 /tools/invoke HTTP 的额外 deny deny: ["browser"], // 从默认 HTTP deny 列表中移除工具 allow: ["gateway"], @@ -2774,43 +2775,43 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -- `mode`：`local`（运行 gateway）或 `remote`（连接到远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。 -- `port`：单一复用端口，用于 WS + HTTP。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `port`：WS + HTTP 复用的单一端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind mode 值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` bind 会在容器内部监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 gateway 不可达。请使用 `--network host`，或设置 `bind: "lan"`（或使用 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以在所有接口上监听。 -- **Auth**：默认需要认证。非 loopback bind 必须启用 gateway auth。实际使用中，这意味着共享 token/password，或者使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。若二者都配置但未设置 mode，则启动和服务安装/修复流程会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅应用于受信的本地 local loopback 设置；新手引导提示中不会提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份 header（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 代理来源；同主机 loopback 反向代理不能满足 trusted-proxy auth。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 header 可以满足 Control UI/WebSocket auth（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用 Tailscale header auth；它们仍遵循 gateway 的常规 HTTP auth mode。此无 token 流程假定 gateway 主机是受信的。当 `tailscale.mode = "serve"` 时默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的失败认证限制器。按客户端 IP 和认证作用域应用（共享 secret 和 device-token 会分别跟踪）。被阻止的请求会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败状态前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限制，而不是两个请求都以普通不匹配形式通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你有意希望 localhost 流量也被限速（用于测试设置或严格代理部署），请设为 `false`。 -- 浏览器来源的 WS auth 尝试始终会在关闭 loopback 豁免的情况下限速（作为对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些浏览器来源锁定会按规范化的 `Origin` - 值隔离，因此一个 localhost origin 的重复失败不会自动 - 锁定另一个不同的 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开，需要 auth）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时，这是必需的。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为刻意依赖 Host-header 来源策略的部署启用 Host-header 来源回退。 -- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端紧急开关覆盖，允许向受信私有网络 IP 使用明文 `ws://`；默认仍仅允许在 loopback 上使用明文。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 gateway auth。 -- `gateway.push.apns.relay.baseUrl`：供官方/TestFlight iOS 构建在将基于 relay 的注册发布到 gateway 后使用的外部 APNs relay 的 base HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：gateway 到 relay 的发送超时（毫秒）。默认值：`10000`。 -- 基于 relay 的注册会委托给特定 gateway identity。已配对的 iOS 应用会调用 `gateway.identity.get`，在 relay 注册中包含该 identity，并将一个注册作用域的发送授权转发给 gateway。其他 gateway 无法复用该已存储注册。 +- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` bind 在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **Auth**：默认必须启用。非 loopback 绑定要求 Gateway 网关认证。实际中，这意味着共享 token/password，或使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。若两者都已配置而 mode 未设置，启动以及服务安装/修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信的本地 local loopback 设置；新手引导提示不会提供该选项。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份 headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。该模式要求**非 loopback** 代理来源；同主机 loopback 反向代理不满足 trusted-proxy auth。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 headers 可满足 Control UI/WebSocket auth（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header auth；它们仍遵循 Gateway 网关的普通 HTTP auth 模式。该无 token 流程假定 Gateway 网关主机受信。当 `tailscale.mode = "serve"` 时默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限速器。按客户端 IP 和 auth 作用域生效（共享 secret 和设备 token 会独立跟踪）。被阻止的请求返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败前串行化。因此，来自同一客户端的并发错误尝试，可能会在第二个请求时触发限速，而不是两个都以普通不匹配方式竞争通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；若你有意希望 localhost 流量也受限速（测试设置或严格代理部署），请设为 `false`。 +- 来自浏览器 origin 的 WS auth 尝试始终会关闭 loopback 豁免并进行节流（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 +- 在 loopback 上，这些来自浏览器 origin 的锁定会按归一化后的 `Origin` + 值隔离，因此某个 localhost origin 的重复失败不会自动 + 锁死另一个 origin。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要 auth）。 +- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当预期来自非 loopback origin 的浏览器客户端时，这是必需的。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为那些有意依赖 Host header origin 策略的部署启用 Host-header origin 回退。 +- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧破窗覆盖，允许对受信私有网络 IP 使用明文 `ws://`；默认情况下，明文仍然仅限 loopback。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 +- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的 base HTTPS URL，供官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关之后使用。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时（毫秒）。默认值为 `10000`。 +- 基于 relay 的注册会委派给某个特定 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个注册级发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 - `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发的 loopback HTTP relay URL 放行开关。生产 relay URL 应保持使用 HTTPS。 -- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：在滚动一小时内，每个渠道/账户的健康监控最大重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保留全局监控。 -- `channels..accounts..healthMonitor.enabled`：多账户渠道的按账户覆盖。设置时，其优先级高于渠道级覆盖。 -- 仅当 `gateway.auth.*` 未设置时，本地 gateway 调用路径才可将 `gateway.remote.*` 用作回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置且未解析，则解析会以默认拒绝方式失败（不会被远程回退掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端 header 的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的资格。 -- `allowRealIpFallback`：为 `true` 时，若缺少 `X-Forwarded-For`，gateway 将接受 `X-Real-IP`。默认值 `false`，以保持默认拒绝行为。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发的逃生口，允许 loopback HTTP relay URL。生产 relay URL 应保持 HTTPS。 +- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设置为 `0` 可全局禁用健康监控重启。默认值：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账号的最大健康监控重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：在保持全局监控启用的同时，对单个渠道选择退出健康监控重启。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。若设置，会优先于渠道级覆盖。 +- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可将 `gateway.remote.*` 作为回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置且未解析成功，则解析会失败并默认拒绝（不会被远程回退所掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端 headers 的反向代理 IP。仅列出你控制的代理。loopback 条目对同主机代理/本地检测场景（例如 Tailscale Serve 或本地反向代理）仍有效，但它们**不会**让 loopback 请求具备 `gateway.auth.mode: "trusted-proxy"` 的资格。 +- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，Gateway 网关会接受 `X-Real-IP`。默认 `false`，以保持默认拒绝行为。 - `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认 deny 列表）。 - `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名。 @@ -2821,7 +2822,4 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 - Responses API：`gateway.http.endpoints.responses.enabled`。 - Responses URL 输入加固： - - `gateway.http.endpoints.responses.maxUrlParts` - - `gateway.http.endpoints.responses.files.urlAllowlist` - - `gateway.http.endpoints.responses.images.urlAllowlist` - 空允许列表会被视为未设置；如需禁用 URL 获取，请 \ No newline at end of file + - `gateway \ No newline at end of file diff --git a/docs/zh-CN/plugins/architecture.md b/docs/zh-CN/plugins/architecture.md index 18268d31a..a831f8d5d 100644 --- a/docs/zh-CN/plugins/architecture.md +++ b/docs/zh-CN/plugins/architecture.md @@ -8,10 +8,10 @@ sidebarTitle: Internals summary: 插件内部机制：能力模型、归属、契约、加载流水线和运行时辅助函数 title: 插件内部机制 x-i18n: - generated_at: "2026-04-05T22:33:13Z" + generated_at: "2026-04-06T00:55:26Z" model: gpt-5.4 provider: openai - source_hash: d6e53a71b18d12cde81acac040c2110693dd2586b8888ff6104467ddd81ce22e + source_hash: d39158455701dedfb75f6c20b8c69fd36ed9841f1d92bed1915f448df57fd47b source_path: plugins/architecture.md workflow: 15 --- @@ -19,129 +19,165 @@ x-i18n: # 插件内部机制 - 这是**深度架构参考**。如需实用指南，请参见： - - [安装和使用插件](/zh-CN/tools/plugin) —— 用户指南 - - [入门指南](/zh-CN/plugins/building-plugins) —— 第一个插件教程 - - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) —— 构建一个消息渠道 - - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) —— 构建一个模型提供商 - - [SDK 概览](/zh-CN/plugins/sdk-overview) —— 导入映射与注册 API + 这是**深度架构参考**。如需实用指南，请参阅： + - [安装和使用插件](/zh-CN/tools/plugin) — 用户指南 + - [入门指南](/zh-CN/plugins/building-plugins) — 第一个插件教程 + - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建一个消息渠道 + - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建一个模型提供商 + - [SDK 概览](/zh-CN/plugins/sdk-overview) — 导入映射和注册 API 本页介绍 OpenClaw 插件系统的内部架构。 ## 公共能力模型 -能力是 OpenClaw 内部公开的**原生插件**模型。每个原生 OpenClaw 插件都会针对一种或多种能力类型进行注册： +能力是 OpenClaw 内部公共的**原生插件**模型。每个 +原生 OpenClaw 插件都会针对一种或多种能力类型进行注册： -| 能力 | 注册方法 | 示例插件 | -| ---------------------- | ------------------------------------------------ | ------------------------------------ | -| 文本推理 | `api.registerProvider(...)` | `openai`, `anthropic` | -| 语音 | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| 图像生成 | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| 视频生成 | `api.registerVideoGenerationProvider(...)` | `qwen` | -| 网页抓取 | `api.registerWebFetchProvider(...)` | `firecrawl` | -| 网页搜索 | `api.registerWebSearchProvider(...)` | `google` | -| 渠道 / 消息传递 | `api.registerChannel(...)` | `msteams`, `matrix` | +| 能力 | 注册方法 | 示例插件 | +| -------------------- | ------------------------------------------------ | ------------------------------------ | +| 文本推理 | `api.registerProvider(...)` | `openai`, `anthropic` | +| 语音 | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| 图像生成 | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| 音乐生成 | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| 视频生成 | `api.registerVideoGenerationProvider(...)` | `qwen` | +| 网页抓取 | `api.registerWebFetchProvider(...)` | `firecrawl` | +| 网页搜索 | `api.registerWebSearchProvider(...)` | `google` | +| 渠道 / 消息 | `api.registerChannel(...)` | `msteams`, `matrix` | -一个注册了零个能力，但提供钩子、工具或服务的插件，是**仅钩子遗留**插件。这种模式仍然受到完全支持。 +如果一个插件注册了零个能力，但提供了 hooks、工具或 +服务，那么它就是一个**仅 hooks 的遗留**插件。该模式仍然受到完全支持。 ### 外部兼容性立场 -能力模型已经在核心中落地，并且如今已被内置 / 原生插件使用，但外部插件兼容性仍然需要比“它已导出，因此它已冻结”更严格的标准。 +能力模型已经在 core 中落地，并且如今已被内置 / 原生插件使用， +但外部插件的兼容性仍需要比“它已导出，因此它已冻结” +更严格的标准。 当前指导原则： -- **现有外部插件：** 保持基于钩子的集成继续可用；将此视为兼容性的基线 -- **新的内置 / 原生插件：** 优先使用显式能力注册，而不是厂商特定的深入访问或新的仅钩子设计 -- **采用能力注册的外部插件：** 允许这样做，但除非文档明确将某个契约标记为稳定，否则应将能力专用辅助接口视为仍在演进中 +- **现有外部插件：** 保持基于 hooks 的集成正常工作；将其视为 + 兼容性基线 +- **新的内置 / 原生插件：** 优先使用显式能力注册，而不是 + 面向特定厂商的内部耦合，或新的仅 hooks 设计 +- **采用能力注册的外部插件：** 允许这样做，但除非文档明确将某个 + 契约标记为稳定，否则应将特定于能力的辅助接口视为仍在演进 -实用规则： +实践规则： -- 能力注册 API 是预期的发展方向 -- 在过渡期间，对于外部插件来说，遗留钩子仍然是最安全、最不易破坏的路径 -- 导出的辅助子路径并不全都等价；优先使用狭义且有文档说明的契约，而不是偶然导出的辅助接口 +- 能力注册 API 是目标方向 +- 在过渡期间，对于外部插件来说，遗留 hooks 仍然是最安全、最不容易破坏兼容性的路径 +- 并非所有导出的辅助子路径都同等稳定；优先使用有文档说明的狭窄 + 契约，而不是偶然暴露出来的辅助导出 ### 插件形态 -OpenClaw 会根据每个已加载插件的实际注册行为（而不只是静态元数据）将其归类为某种形态： +OpenClaw 会根据每个已加载插件的实际注册行为来将其归类为一种形态 +（而不只是依据静态元数据）： -- **plain-capability** —— 只注册一种能力类型（例如仅提供商插件，如 `mistral`） -- **hybrid-capability** —— 注册多种能力类型（例如 `openai` 同时拥有文本推理、语音、媒体理解和图像生成） -- **hook-only** —— 仅注册钩子（类型化或自定义），不注册能力、工具、命令或服务 -- **non-capability** —— 注册工具、命令、服务或路由，但不注册能力 +- **plain-capability** -- 恰好注册一种能力类型（例如仅提供商 + 插件 `mistral`） +- **hybrid-capability** -- 注册多种能力类型（例如 + `openai` 同时拥有文本推理、语音、媒体理解和图像 + 生成） +- **hook-only** -- 只注册 hooks（类型化或自定义），不注册能力、 + 工具、命令或服务 +- **non-capability** -- 注册工具、命令、服务或路由，但不注册 + 能力 -使用 `openclaw plugins inspect ` 可查看插件的形态和能力细分。详见 [CLI 参考](/cli/plugins#inspect)。 +使用 `openclaw plugins inspect ` 查看插件的形态及其能力 +明细。详见 [CLI 参考](/cli/plugins#inspect)。 -### 遗留钩子 +### 遗留 hooks -`before_agent_start` 钩子仍作为仅钩子插件的兼容路径受到支持。现实中的遗留插件仍然依赖它。 +`before_agent_start` hook 仍作为仅 hooks 插件的兼容路径受到支持。 +现实中仍有遗留插件依赖它。 -方向： +方向如下： -- 保持其可用 +- 保持其正常工作 - 在文档中将其标记为遗留 -- 对于模型 / 提供商覆盖工作，优先使用 `before_model_resolve` +- 对于模型 / 提供商覆写工作，优先使用 `before_model_resolve` - 对于提示词变更工作，优先使用 `before_prompt_build` -- 只有在真实使用量下降且夹具覆盖证明迁移安全之后，才考虑移除 +- 仅在真实使用量下降，且夹具覆盖证明迁移安全后才移除 ### 兼容性信号 -当你运行 `openclaw doctor` 或 `openclaw plugins inspect ` 时，可能会看到以下标签之一： +当你运行 `openclaw doctor` 或 `openclaw plugins inspect ` 时，你可能会看到 +以下标签之一： -| 信号 | 含义 | -| -------------------------- | ------------------------------------------------------------ | -| **config valid** | 配置可正常解析，插件可正常解析 | -| **compatibility advisory** | 插件使用受支持但较旧的模式（例如 `hook-only`） | -| **legacy warning** | 插件使用 `before_agent_start`，该用法已弃用 | -| **hard error** | 配置无效或插件加载失败 | +| 信号 | 含义 | +| ------------------------ | --------------------------------------------------------- | +| **config valid** | 配置解析正常，插件可正常解析 | +| **compatibility advisory** | 插件使用了受支持但较旧的模式（例如 `hook-only`） | +| **legacy warning** | 插件使用了已弃用的 `before_agent_start` | +| **hard error** | 配置无效或插件加载失败 | -目前，`hook-only` 和 `before_agent_start` 都不会导致你的插件中断 —— `hook-only` 只是提示，而 `before_agent_start` 只会触发警告。这些信号也会显示在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 +如今，`hook-only` 和 `before_agent_start` 都不会破坏你的插件 -- +`hook-only` 只是提示，而 `before_agent_start` 只会触发警告。这些 +信号也会出现在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 ## 架构概览 -OpenClaw 的插件系统分为四层： +OpenClaw 的插件系统有四层： 1. **清单 + 发现** - OpenClaw 会从已配置路径、工作区根目录、全局扩展根目录和内置扩展中查找候选插件。发现流程会优先读取原生 `openclaw.plugin.json` 清单以及受支持的 bundle 清单。 + OpenClaw 会从已配置路径、工作区根目录、 + 全局扩展根目录和内置扩展中查找候选插件。 + 发现阶段会优先读取原生 `openclaw.plugin.json` 清单以及受支持的 bundle 清单。 2. **启用 + 验证** - 核心决定某个已发现的插件是启用、禁用、阻止，还是被选入某个独占槽位，例如 memory。 + Core 决定一个已发现的插件是启用、禁用、阻止，还是 + 被选入某个独占槽位（例如 memory）。 3. **运行时加载** - 原生 OpenClaw 插件通过 jiti 在进程内加载，并将能力注册到一个中央注册表中。兼容 bundle 会在不导入运行时代码的情况下被规范化为注册表记录。 + 原生 OpenClaw 插件通过 jiti 在进程内加载，并将 + 能力注册到一个中央注册表中。兼容 bundle 会在不导入运行时代码的情况下， + 被标准化为注册表记录。 4. **接口消费** - OpenClaw 的其余部分通过读取注册表来暴露工具、渠道、提供商设置、钩子、HTTP 路由、CLI 命令和服务。 + OpenClaw 的其余部分读取该注册表，以暴露工具、渠道、提供商 + 设置、hooks、HTTP 路由、CLI 命令和服务。 -对于插件 CLI，根命令发现被拆分为两个阶段： +对于插件 CLI 而言，根命令发现专门分为两个阶段： - 解析时元数据来自 `registerCli(..., { descriptors: [...] })` -- 真正的插件 CLI 模块可以保持惰性，并在首次调用时再注册 +- 真正的插件 CLI 模块可以保持懒加载，并在首次调用时再注册 -这样可以让插件自有的 CLI 代码保留在插件内部，同时仍允许 OpenClaw 在解析前预留根命令名称。 +这样既能把插件自有的 CLI 代码保留在插件内部，又能让 OpenClaw +在解析前预留根命令名称。 -重要的设计边界： +重要设计边界如下： -- 发现 + 配置验证应基于**清单 / schema 元数据**完成，而无需执行插件代码 +- 发现 + 配置验证应基于**清单 / schema 元数据** + 完成，而无需执行插件代码 - 原生运行时行为来自插件模块的 `register(api)` 路径 -这种拆分使 OpenClaw 能够在完整运行时尚未激活之前，就验证配置、说明缺失 / 禁用的插件，并构建 UI / schema 提示。 +这种拆分让 OpenClaw 能在完整运行时尚未激活前，就完成配置验证、 +解释缺失 / 已禁用插件，并构建 UI / schema 提示。 -### 渠道插件与共享消息工具 +### 渠道插件和共享 `message` 工具 -对于正常聊天操作，渠道插件不需要分别注册发送 / 编辑 / 反应工具。OpenClaw 在核心中保留一个共享的 `message` 工具，而渠道插件则负责其背后的渠道专属发现与执行。 +对于常规聊天动作，渠道插件不需要单独注册 send / edit / react 工具。 +OpenClaw 在 core 中保留一个共享的 `message` 工具，而 +渠道插件负责其背后与渠道相关的发现和执行逻辑。 当前边界如下： -- 核心拥有共享 `message` 工具宿主、提示词接线、会话 / 线程记录以及执行分发 -- 渠道插件拥有作用域动作发现、能力发现以及所有渠道专属 schema 片段 -- 渠道插件拥有提供商专属的会话对话语法，例如对话 id 如何编码线程 id，或如何从父对话继承 +- core 负责共享 `message` 工具宿主、提示词接线、会话 / 线程 + 记账，以及执行分发 +- 渠道插件负责作用域化动作发现、能力发现，以及任何 + 渠道特有的 schema 片段 +- 渠道插件负责提供商特定的会话对话语法，例如 + 会话 id 如何编码线程 id，或如何从父级对话继承 - 渠道插件通过其动作适配器执行最终动作 -对于渠道插件，SDK 接口为 -`ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的发现调用允许插件将其可见动作、能力和 schema 贡献一起返回，以避免这些部分彼此漂移。 +对于渠道插件，SDK 接口是 +`ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的发现 +调用允许插件将可见动作、能力和 schema +扩展一起返回，从而避免这些部分彼此漂移。 -核心会将运行时作用域传入该发现步骤。重要字段包括： +Core 会将运行时作用域传入该发现步骤。重要字段包括： - `accountId` - `currentChannelId` @@ -152,85 +188,121 @@ OpenClaw 的插件系统分为四层： - `agentId` - 受信任的入站 `requesterSenderId` -这对于上下文敏感的插件很重要。渠道可以根据当前账户、当前房间 / 线程 / 消息或受信任的请求者身份来隐藏或暴露消息动作，而无需在核心 `message` 工具中硬编码渠道专属分支。 +这对上下文敏感型插件很重要。渠道可以根据活动账户、 +当前房间 / 线程 / 消息或受信任的请求者身份， +决定隐藏或暴露消息动作，而无需在 core 的 `message` 工具中硬编码 +特定于渠道的分支。 -这也是为什么嵌入式运行器路由变更仍然属于插件工作：运行器负责将当前聊天 / 会话身份转发到插件发现边界，使共享 `message` 工具能为当前轮次暴露正确的渠道自有接口。 +这也是为什么嵌入式 runner 路由变更仍然属于插件工作：runner +负责将当前聊天 / 会话身份转发到插件发现边界， +从而让共享的 `message` 工具在当前轮次暴露出正确的、由渠道拥有的 +接口。 -对于渠道自有执行辅助函数，内置插件应将执行运行时保留在各自的扩展模块中。核心不再拥有位于 `src/agents/tools` 下的 Discord、Slack、Telegram 或 WhatsApp 消息动作运行时。我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，内置插件应直接从其扩展自有模块导入本地运行时代码。 +对于渠道自有的执行辅助函数，内置插件应将执行运行时保留在 +各自的扩展模块中。Core 不再拥有位于 `src/agents/tools` 下的 Discord、 +Slack、Telegram 或 WhatsApp 消息动作运行时。 +我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，而内置 +插件应直接从各自扩展拥有的模块中导入本地运行时代码。 -相同边界同样适用于一般的提供商命名 SDK 接缝：核心不应导入针对 Slack、Discord、Signal、WhatsApp 或类似扩展的渠道专属便捷 barrel。如果核心需要某种行为，应当消费内置插件自己的 `api.ts` / `runtime-api.ts` barrel，或将需求提升为共享 SDK 中一个狭义、通用的能力。 +同样的边界也适用于一般意义上的提供商命名 SDK 接缝：core +不应导入面向 Slack、Discord、Signal、 +WhatsApp 或类似扩展的渠道特定便捷 barrel。如果 core 需要某种行为， +要么消费内置插件自有的 `api.ts` / `runtime-api.ts` barrel， +要么将该需求提升为共享 SDK 中一个狭窄、通用的能力。 -对于投票，当前有两条执行路径： +对于投票，具体有两条执行路径： -- `outbound.sendPoll` 是适用于符合通用投票模型的渠道的共享基线 -- `actions.handleAction("poll")` 是用于渠道专属投票语义或额外投票参数的首选路径 +- `outbound.sendPoll` 是适用于符合通用投票模型渠道的共享基线 +- `actions.handleAction("poll")` 是更推荐的路径，适用于 + 渠道特定的投票语义或额外投票参数 -现在，核心会在插件投票分发拒绝该动作之后，才推迟执行共享投票解析，因此插件自有的投票处理器可以接受渠道专属投票字段，而不会先被通用投票解析器拦截。 +现在，core 会先尝试插件投票分发，只有在插件拒绝该动作后，才会延迟执行共享投票解析， +这样插件自有的投票处理器就能接收特定渠道的投票字段， +而不会先被通用投票解析器阻挡。 -完整启动顺序见[加载流水线](#load-pipeline)。 +完整启动顺序请参阅 [加载流水线](#load-pipeline)。 ## 能力归属模型 -OpenClaw 将原生插件视为某个**公司**或某个**功能**的归属边界，而不是一堆互不相关集成的杂物袋。 +OpenClaw 将一个原生插件视为一个**公司**或一个 +**功能**的归属边界，而不是一堆互不相关集成的集合。 这意味着： -- 公司插件通常应拥有该公司的所有面向 OpenClaw 的接口 -- 功能插件通常应拥有其引入的完整功能接口 -- 渠道应消费共享核心能力，而不是临时重新实现提供商行为 +- 一个公司插件通常应该拥有该公司所有面向 OpenClaw 的 + 接口 +- 一个功能插件通常应该拥有其引入的完整功能接口 +- 渠道应消费共享的 core 能力，而不是临时重复实现 + 提供商行为 -例如： +示例： -- 内置的 `openai` 插件拥有 OpenAI 模型提供商行为，以及 OpenAI 的语音 + 实时语音 + 媒体理解 + 图像生成行为 +- 内置的 `openai` 插件拥有 OpenAI 模型提供商行为，以及 OpenAI + 的语音 + 实时语音 + 媒体理解 + 图像生成行为 - 内置的 `elevenlabs` 插件拥有 ElevenLabs 语音行为 - 内置的 `microsoft` 插件拥有 Microsoft 语音行为 -- 内置的 `google` 插件拥有 Google 模型提供商行为，以及 Google 的媒体理解 + 图像生成 + 网页搜索行为 +- 内置的 `google` 插件拥有 Google 模型提供商行为，以及 Google + 的媒体理解 + 图像生成 + 网页搜索行为 - 内置的 `firecrawl` 插件拥有 Firecrawl 网页抓取行为 -- 内置的 `minimax`、`mistral`、`moonshot` 和 `zai` 插件拥有它们的媒体理解后端 -- 内置的 `qwen` 插件拥有 Qwen 文本提供商行为，以及媒体理解和视频生成行为 -- `voice-call` 插件是一个功能插件：它拥有通话传输、工具、CLI、路由和 Twilio 媒体流桥接，但它会消费共享的语音以及实时转录和实时语音能力，而不是直接导入厂商插件 +- 内置的 `minimax`、`mistral`、`moonshot` 和 `zai` 插件拥有它们各自的 + 媒体理解后端 +- `voice-call` 插件是一个功能插件：它拥有通话传输、工具、 + CLI、路由和 Twilio 媒体流桥接，但它消费共享的语音 + 以及实时转录和实时语音能力，而不是直接导入厂商插件 -预期的最终状态是： +目标终态是： -- 即使 OpenAI 横跨文本模型、语音、图像以及未来的视频，它也应存在于一个插件中 -- 其他厂商也可以对其自己的接口范围采用相同方式 -- 渠道不关心哪个厂商插件拥有该提供商；它们只消费核心暴露的共享能力契约 +- OpenAI 即使横跨文本模型、语音、图像以及未来的视频， + 也只存在于一个插件中 +- 其他厂商也可以对自己的能力范围采用同样方式 +- 渠道不关心哪个厂商插件拥有该提供商；它们只消费 core 暴露的 + 共享能力契约 这是关键区别： - **plugin** = 归属边界 -- **capability** = 可由多个插件实现或消费的核心契约 +- **capability** = 可由多个插件实现或消费的 core 契约 -因此，如果 OpenClaw 增加一个新领域，例如视频，第一个问题不应是“哪个提供商应该硬编码视频处理？”而应是“核心视频能力契约是什么？”一旦这个契约存在，厂商插件就可以针对它注册，而渠道 / 功能插件也可以消费它。 +因此，如果 OpenClaw 新增一个如视频这样的领域，第一个问题不应是 +“哪个提供商应该硬编码视频处理？”第一个问题应是“什么才是 +core 的视频能力契约？”一旦该契约存在，厂商插件 +就可以针对它注册，而渠道 / 功能插件也可以消费它。 如果该能力尚不存在，正确做法通常是： -1. 在核心中定义缺失的能力 -2. 通过插件 API / 运行时以类型化方式暴露它 -3. 让渠道 / 功能基于该能力接线 -4. 让厂商插件注册具体实现 +1. 在 core 中定义缺失的能力 +2. 以类型化方式通过插件 API / 运行时将其暴露出来 +3. 让渠道 / 功能接入该能力 +4. 允许厂商插件注册实现 -这样可以在保持归属明确的同时，避免核心行为依赖单一厂商或一次性的插件专属代码路径。 +这样能让归属关系保持清晰，同时避免 core 的行为依赖于 +单一厂商或一次性的插件特定代码路径。 ### 能力分层 -决定代码归属时，可使用如下思维模型： +在决定代码应放在哪里时，可使用以下思维模型： -- **核心能力层**：共享编排、策略、回退、配置合并规则、投递语义和类型化契约 -- **厂商插件层**：厂商专属 API、认证、模型目录、语音合成、图像生成、未来的视频后端、使用量端点 -- **渠道 / 功能插件层**：Slack / Discord / voice-call 等集成，它们消费核心能力并将其呈现在某个接口上 +- **core 能力层**：共享编排、策略、回退、配置 + 合并规则、交付语义和类型化契约 +- **厂商插件层**：厂商特定 API、认证、模型目录、语音 + 合成、图像生成、未来视频后端、使用量端点 +- **渠道 / 功能插件层**：Slack / Discord / voice-call 等集成， + 它们消费 core 能力并将其呈现在某个接口上 -例如，TTS 遵循这种形态： +例如，TTS 遵循以下形态： -- 核心拥有回复时 TTS 策略、回退顺序、偏好和渠道投递 -- `openai`、`elevenlabs` 和 `microsoft` 拥有合成实现 +- core 负责回复时的 TTS 策略、回退顺序、偏好和渠道交付 +- `openai`、`elevenlabs` 和 `microsoft` 负责合成实现 - `voice-call` 消费电话 TTS 运行时辅助函数 -未来能力也应优先采用相同模式。 +未来能力也应优先遵循同样模式。 ### 多能力公司插件示例 -一个公司插件从外部看应当具有一致性。如果 OpenClaw 为模型、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和网页搜索提供共享契约，那么某个厂商就可以在一个地方拥有其所有接口： +一个公司插件从外部看应当是连贯的。如果 OpenClaw 对模型、 +语音、实时转录、实时语音、媒体理解、图像生成、视频生成、 +网页抓取和网页搜索都提供了共享契约，那么一个厂商就可以在一个地方 +拥有其所有接口： ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -245,12 +317,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // auth/model catalog/runtime hooks + // 认证 / 模型目录 / 运行时 hooks }); api.registerSpeechProvider({ id: "exampleai", - // vendor speech config — implement the SpeechProviderPlugin interface directly + // 厂商语音配置 —— 直接实现 SpeechProviderPlugin 接口 }); api.registerMediaUnderstandingProvider({ @@ -275,7 +347,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // credential + fetch logic + // 凭证 + 获取逻辑 }), ); }, @@ -284,142 +356,177 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -关键不在于辅助函数的确切名称，而在于这种形态： +关键不在于具体的辅助函数名称。重要的是结构： - 一个插件拥有该厂商接口 -- 核心仍然拥有能力契约 +- core 仍然拥有能力契约 - 渠道和功能插件消费 `api.runtime.*` 辅助函数，而不是厂商代码 -- 契约测试可以断言插件确实注册了它所宣称拥有的能力 +- 契约测试可以断言插件已注册其所宣称拥有的能力 ### 能力示例：视频理解 -OpenClaw 已经将图像 / 音频 / 视频理解视为一种共享能力。相同的归属模型也适用于这里： +OpenClaw 已经将图像 / 音频 / 视频理解视为一种共享 +能力。相同的归属模型也适用于此： -1. 核心定义媒体理解契约 -2. 厂商插件根据适用情况注册 `describeImage`、`transcribeAudio` 和 `describeVideo` -3. 渠道和功能插件消费共享核心行为，而不是直接接线到厂商代码 +1. core 定义媒体理解契约 +2. 厂商插件按适用情况注册 `describeImage`、`transcribeAudio` 和 + `describeVideo` +3. 渠道和功能插件消费共享的 core 行为，而不是 + 直接接入厂商代码 -这样可以避免将某个提供商的视频假设固化进核心。插件拥有厂商接口；核心拥有能力契约和回退行为。 +这样就避免了把某个提供商的视频假设固化进 core。插件拥有 +厂商接口；core 拥有能力契约和回退行为。 -视频生成也已经采用同样的顺序：核心拥有类型化能力契约和运行时辅助函数，而厂商插件则针对 `api.registerVideoGenerationProvider(...)` 注册实现。 +视频生成已经使用了同样的顺序：core 拥有类型化 +能力契约和运行时辅助函数，而厂商插件通过 +`api.registerVideoGenerationProvider(...)` 注册实现。 -需要一个具体的发布清单？请参见[能力扩展手册](/zh-CN/plugins/architecture)。 +需要一份具体的发布清单吗？请参阅 +[能力扩展手册](/zh-CN/plugins/architecture)。 ## 契约与强制执行 -插件 API 接口被有意设计为类型化并集中在 `OpenClawPluginApi` 中。该契约定义了受支持的注册点，以及插件可以依赖的运行时辅助函数。 +插件 API 接口是有意采用类型化并集中在 +`OpenClawPluginApi` 中的。该契约定义了受支持的注册点，以及 +插件可依赖的运行时辅助函数。 其重要性在于： -- 插件作者获得一个稳定的内部标准 -- 核心可以拒绝重复归属，例如两个插件注册同一个 provider id -- 启动时可以为格式错误的注册暴露可执行的诊断信息 -- 契约测试可以强制执行内置插件归属，并防止静默漂移 +- 插件作者获得一种稳定的内部标准 +- core 可以拒绝重复归属，例如两个插件注册相同的 + provider id +- 启动时可以为格式错误的注册提供可操作诊断 +- 契约测试可以强制内置插件的归属关系，并防止静默漂移 -这里有两层强制执行： +这里有两层强制执行机制： -1. **运行时注册强制执行** - 插件注册表会在插件加载时验证注册内容。例如：重复 provider id、重复语音提供商 id，以及格式错误的注册都会产生插件诊断，而不是导致未定义行为。 +1. **运行时注册强制** + 插件加载时，插件注册表会验证注册内容。示例： + 重复的 provider id、重复的语音 provider id，以及格式错误的 + 注册，都会生成插件诊断，而不是产生未定义行为。 2. **契约测试** - 在测试运行期间，内置插件会被捕获进契约注册表，以便 OpenClaw 能显式断言归属。目前这用于模型提供商、语音提供商、网页搜索提供商和内置注册归属。 + 在测试运行中，内置插件会被捕获到契约注册表中，从而让 + OpenClaw 能显式断言归属关系。目前这用于模型 + 提供商、语音提供商、网页搜索提供商以及内置注册 + 归属。 -实际效果是，OpenClaw 能够预先知道哪个插件拥有哪些接口。这让核心和渠道可以无缝组合，因为归属是声明式、类型化且可测试的，而不是隐式的。 +其实际效果是，OpenClaw 能够预先知道哪个插件拥有哪个 +接口。这让 core 和渠道可以无缝组合，因为归属关系是 +声明式、类型化且可测试的，而不是隐式的。 -### 什么内容应该属于契约 +### 什么应该属于契约 -好的插件契约应当具备以下特征： +好的插件契约应当是： -- 类型化 -- 小而精 -- 能力专属 -- 由核心拥有 +- 类型化的 +- 小而精的 +- 特定于能力的 +- 由 core 拥有 - 可被多个插件复用 - 可被渠道 / 功能消费，而无需了解厂商细节 -不好的插件契约包括： +糟糕的插件契约包括： -- 隐藏在核心中的厂商专属策略 +- 隐藏在 core 中的厂商特定策略 - 绕过注册表的一次性插件逃生口 -- 直接深入访问厂商实现的渠道代码 -- 不属于 `OpenClawPluginApi` 或 `api.runtime` 的临时运行时对象 +- 渠道代码直接深入厂商实现 +- 不属于 `OpenClawPluginApi` 或 + `api.runtime` 的临时运行时对象 -如果不确定，就提高抽象层级：先定义能力，再让插件接入它。 +如果拿不准，提升抽象层级：先定义能力，再让插件接入。 ## 执行模型 -原生 OpenClaw 插件与 Gateway 网关**在同一进程内**运行。它们不是沙箱隔离的。已加载的原生插件与核心代码共享相同的进程级信任边界。 +原生 OpenClaw 插件会与 Gateway 网关**在同一进程内**运行。它们不会被 +沙箱隔离。已加载的原生插件与 core 代码具有相同的进程级信任边界。 -这意味着： +其影响包括： -- 原生插件可以注册工具、网络处理器、钩子和服务 -- 原生插件中的 bug 可能导致 Gateway 网关崩溃或不稳定 -- 恶意原生插件等同于在 OpenClaw 进程内执行任意代码 +- 原生插件可以注册工具、网络处理器、hooks 和服务 +- 原生插件中的 bug 可能导致网关崩溃或不稳定 +- 恶意原生插件等同于在 OpenClaw 进程内部执行任意代码 -兼容 bundle 默认更安全，因为 OpenClaw 当前将它们视为元数据 / 内容包。在当前版本中，这主要指内置 Skills。 +兼容 bundle 默认更安全，因为 OpenClaw 当前会将它们视为 +元数据 / 内容包。在当前版本中，这主要意味着内置 +Skills。 -对于非内置插件，请使用 allowlist 和显式安装 / 加载路径。将工作区插件视为开发时代码，而不是生产默认项。 +对于非内置插件，请使用 allowlist 和显式的安装 / 加载路径。 +应将工作区插件视为开发期代码，而不是生产默认项。 -对于内置工作区包名，保持插件 id 锚定在 npm 名称中：默认使用 `@openclaw/`，或在包有意暴露更窄的插件角色时使用获批的类型后缀，例如 `-provider`、`-plugin`、`-speech`、`-sandbox` 或 `-media-understanding`。 +对于内置工作区包名，请保持插件 id 与 npm +名称一致：默认使用 `@openclaw/`，或使用经批准的类型化后缀，例如 +`-provider`、`-plugin`、`-speech`、`-sandbox` 或 +`-media-understanding`，当该包有意暴露更窄的插件角色时可使用这些后缀。 -重要的信任说明： +重要信任说明： -- `plugins.allow` 信任的是**插件 id**，而不是来源证明。 -- 与内置插件同 id 的工作区插件，在启用 / 加入 allowlist 时，会有意遮蔽内置副本。 +- `plugins.allow` 信任的是**插件 id**，而不是来源。 +- 如果一个工作区插件与某个内置插件具有相同 id，那么当该工作区插件被启用 / 加入 allowlist 时， + 它会有意遮蔽内置副本。 - 这是正常且有用的行为，适用于本地开发、补丁测试和热修复。 ## 导出边界 -OpenClaw 导出的是能力，而不是实现便捷接口。 +OpenClaw 导出的是能力，而不是实现层面的便捷接口。 -保持能力注册公开。裁剪非契约辅助导出： +应保持能力注册为公开接口。精简非契约辅助导出： -- 内置插件专属辅助子路径 -- 非公共 API 的运行时底层子路径 -- 厂商专属便捷辅助函数 -- 属于实现细节的设置 / 新手引导辅助函数 +- 内置插件特定的辅助子路径 +- 不打算作为公共 API 的运行时接线子路径 +- 厂商特定的便捷辅助函数 +- 作为实现细节的设置 / 新手引导辅助函数 -某些内置插件辅助子路径仍然保留在生成的 SDK 导出映射中，以兼容和维护内置插件。当前示例包括 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 以及若干 `plugin-sdk/matrix*` 接缝。应将它们视为保留的实现细节导出，而不是新第三方插件推荐采用的 SDK 模式。 +出于兼容性和内置插件维护的需要，一些内置插件辅助子路径 +仍然保留在生成的 SDK 导出映射中。当前示例包括 +`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 +`plugin-sdk/zalo-setup` 以及若干 `plugin-sdk/matrix*` 接缝。应将这些视为 +保留的实现细节导出，而不是推荐给新第三方插件使用的 SDK 模式。 ## 加载流水线 -在启动时，OpenClaw 大致会执行以下步骤： +启动时，OpenClaw 大致会执行以下步骤： 1. 发现候选插件根目录 -2. 读取原生或兼容 bundle 的清单与包元数据 -3. 拒绝不安全候选项 -4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、`slots`、`load.paths`） -5. 决定每个候选项是否启用 +2. 读取原生或兼容 bundle 清单以及包元数据 +3. 拒绝不安全的候选项 +4. 标准化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、 + `slots`、`load.paths`） +5. 决定每个候选项的启用状态 6. 通过 jiti 加载已启用的原生模块 -7. 调用原生 `register(api)`（或 `activate(api)` —— 一个遗留别名）钩子，并将注册内容收集到插件注册表中 +7. 调用原生 `register(api)`（或 `activate(api)` —— 一个遗留别名）hooks，并将注册内容收集到插件注册表中 8. 将注册表暴露给命令 / 运行时接口 -`activate` 是 `register` 的遗留别名 —— 加载器会解析当前存在的那个（`def.register ?? def.activate`），并在相同位置调用它。所有内置插件都使用 `register`；新插件请优先使用 `register`。 +`activate` 是 `register` 的遗留别名 —— 加载器会解析两者中存在的那个（`def.register ?? def.activate`），并在同一时机调用。所有内置插件都使用 `register`；新插件请优先使用 `register`。 -安全门会发生在**运行时执行之前**。当入口逃出插件根目录、路径可被所有人写入，或者对于非内置插件来说路径归属看起来可疑时，候选项会被阻止。 +安全门会在**运行时执行之前**生效。如果入口路径逃出插件根目录、 +路径对所有人可写，或对于非内置插件而言路径归属看起来可疑， +候选项就会被阻止。 ### 清单优先行为 -清单是控制面的真实来源。OpenClaw 用它来： +清单是控制平面的事实来源。OpenClaw 使用它来： -- 识别插件 -- 发现声明的 channels / Skills / 配置 schema 或 bundle 能力 +- 标识插件 +- 发现声明的渠道 / Skills / 配置 schema 或 bundle 能力 - 验证 `plugins.entries..config` -- 增强 Control UI 标签 / 占位符 +- 增强 Control UI 标签 / 占位文本 - 显示安装 / 目录元数据 -对于原生插件，运行时模块则是数据面部分。它会注册钩子、工具、命令或提供商流程等实际行为。 +对于原生插件，运行时模块是数据平面部分。它会注册 +hooks、工具、命令或提供商流程等真实行为。 -### 加载器缓存了什么 +### 加载器会缓存什么 OpenClaw 会保留一些短生命周期的进程内缓存，用于： - 发现结果 - 清单注册表数据 -- 已加载插件注册表 +- 已加载的插件注册表 -这些缓存可减少突发启动和重复命令的开销。它们可以被视为短期性能缓存，而不是持久化。 +这些缓存可以减少突发启动和重复命令的开销。你可以放心地将它们视为 +短生命周期的性能缓存，而非持久化。 性能说明： @@ -430,13 +537,14 @@ OpenClaw 会保留一些短生命周期的进程内缓存，用于： ## 注册表模型 -已加载的插件不会直接修改任意核心全局状态。它们会注册到一个中央插件注册表中。 +已加载的插件不会直接改动随意的 core 全局状态。它们会注册到一个 +中央插件注册表中。 注册表会跟踪： -- 插件记录（身份、来源、出处、状态、诊断） +- 插件记录（身份、来源、origin、状态、诊断） - 工具 -- 遗留钩子和类型化钩子 +- 遗留 hooks 和类型化 hooks - 渠道 - 提供商 - Gateway 网关 RPC 处理器 @@ -445,18 +553,22 @@ OpenClaw 会保留一些短生命周期的进程内缓存，用于： - 后台服务 - 插件自有命令 -随后，核心功能会从该注册表中读取，而不是直接与插件模块交互。这使加载保持单向： +然后，core 功能会从该注册表读取内容，而不是直接与插件模块 +交互。这使加载保持单向： - 插件模块 -> 注册表注册 -- 核心运行时 -> 注册表消费 +- core 运行时 -> 注册表消费 -这种分离对于可维护性很重要。它意味着大多数核心接口只需要一个集成点：“读取注册表”，而不是“为每个插件模块做特殊处理”。 +这种分离对可维护性很重要。它意味着大多数 core 接口只 +需要一个集成点：“读取注册表”，而不是“对每个插件 +模块做特殊处理”。 ## 对话绑定回调 -绑定对话的插件可以在审批结果确定后作出响应。 +绑定对话的插件可以在审批完成时做出响应。 -使用 `api.onConversationBindingResolved(...)` 可在绑定请求被批准或拒绝后收到回调： +使用 `api.onConversationBindingResolved(...)`，在绑定 +请求被批准或拒绝后接收回调： ```ts export default { @@ -464,12 +576,12 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // A binding now exists for this plugin + conversation. + // 现在已存在此插件 + 对话的绑定。 console.log(event.binding?.conversationId); return; } - // The request was denied; clear any local pending state. + // 请求被拒绝；清除任何本地待处理状态。 console.log(event.request.conversation.conversationId); }); }, @@ -480,18 +592,22 @@ export default { - `status`：`"approved"` 或 `"denied"` - `decision`：`"allow-once"`、`"allow-always"` 或 `"deny"` -- `binding`：已获批请求的最终绑定 -- `request`：原始请求摘要、detach 提示、发送者 id 和对话元数据 +- `binding`：针对已批准请求的已解析绑定 +- `request`：原始请求摘要、detach 提示、sender id 和 + 对话元数据 -该回调仅用于通知。它不会改变谁被允许绑定对话，并且它会在核心审批处理完成后运行。 +此回调仅用于通知。它不会改变谁有权绑定某个 +对话，并且会在 core 的审批处理完成后运行。 -## 提供商运行时钩子 +## 提供商运行时 hooks -提供商插件现在分为两层： +提供商插件现在有两层： -- 清单元数据：`providerAuthEnvVars` 用于在运行时加载前进行低成本环境认证查找，`providerAuthChoices` 用于在运行时加载前提供低成本的新手引导 / 认证选择标签和 CLI 标志元数据 -- 配置时钩子：`catalog` / 遗留 `discovery` 以及 `applyConfigDefaults` -- 运行时钩子：`normalizeModelId`、`normalizeTransport`、 +- 清单元数据：`providerAuthEnvVars` 用于在运行时加载前进行廉价的 + env 认证查找，`providerAuthChoices` 用于在运行时加载前提供廉价的 + 新手引导 / 认证选项标签和 CLI flag 元数据 +- 配置时 hooks：`catalog` / 遗留 `discovery` 以及 `applyConfigDefaults` +- 运行时 hooks：`normalizeModelId`、`normalizeTransport`、 `normalizeConfig`、 `applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、 `resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、 @@ -510,65 +626,81 @@ export default { `buildReplayPolicy`、 `sanitizeReplayHistory`、`validateReplayTurns`、`onModelSelected` -OpenClaw 仍然拥有通用智能体循环、故障转移、转录处理和工具策略。这些钩子是在不需要整套自定义推理传输的前提下，为提供商专属行为提供的扩展接口。 +OpenClaw 仍然拥有通用智能体循环、故障切换、转录处理和 +工具策略。这些 hooks 是提供商特定行为的扩展接口，使其无需 +实现一整套自定义推理传输。 -当提供商具有基于环境变量的凭证，且通用认证 / 状态 / 模型选择器路径应在不加载插件运行时的情况下看到这些凭证时，请使用清单中的 `providerAuthEnvVars`。当新手引导 / 认证选择 CLI 接口需要在不加载提供商运行时的情况下知道提供商的 choice id、分组标签和简单单标志认证接线时，请使用清单中的 `providerAuthChoices`。将提供商运行时的 `envVars` 保留给面向操作员的提示，例如新手引导标签或 OAuth client-id / client-secret 设置变量。 +当提供商具有基于 env 的凭证，且通用认证 / 状态 / 模型选择器路径 +需要在不加载插件运行时的情况下看到它们时，请使用清单中的 `providerAuthEnvVars`。 +当新手引导 / 认证选择 CLI 接口需要在不加载提供商运行时的情况下 +了解该提供商的 choice id、分组标签和简单的单 flag 认证接线时， +请使用清单中的 `providerAuthChoices`。提供商运行时中的 +`envVars` 应保留给面向运维人员的提示，例如新手引导标签或 OAuth +client-id / client-secret 设置变量。 -### 钩子顺序与用法 +### Hook 顺序与用法 -对于模型 / 提供商插件，OpenClaw 大致按以下顺序调用钩子。 +对于模型 / 提供商插件，OpenClaw 大致按如下顺序调用 hooks。 “何时使用”列是快速决策指南。 -| # | 钩子 | 作用 | 何时使用 | -| --- | --------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | 在生成 `models.json` 期间，将提供商配置发布到 `models.providers` 中 | 提供商拥有目录或 base URL 默认值 | -| 2 | `applyConfigDefaults` | 在配置具体化期间应用提供商自有的全局配置默认值 | 默认值依赖认证模式、环境或提供商模型家族语义 | -| -- | _(内置模型查找)_ | OpenClaw 会先尝试常规注册表 / 目录路径 | _(不是插件钩子)_ | -| 3 | `normalizeModelId` | 在查找前规范化遗留或预览版 model-id 别名 | 提供商在规范模型解析前拥有别名清理逻辑 | -| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商家族的 `api` / `baseUrl` | 提供商在同一传输家族中拥有自定义 provider id 的传输清理逻辑 | -| 5 | `normalizeConfig` | 在运行时 / 提供商解析前规范化 `models.providers.` | 提供商需要把配置清理逻辑放在插件中；内置的 Google 家族辅助函数也会为受支持的 Google 配置项兜底 | -| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式使用量兼容重写 | 提供商需要基于端点的原生流式使用量元数据修复 | -| 7 | `resolveConfigApiKey` | 在加载运行时认证前，为配置提供商解析环境标记认证 | 提供商拥有环境标记 API key 解析逻辑；`amazon-bedrock` 这里也有内置 AWS 环境标记解析器 | -| 8 | `resolveSyntheticAuth` | 在不持久化明文的前提下暴露本地 / 自托管或配置支持的认证 | 提供商可使用合成 / 本地凭证标记运行 | -| 9 | `shouldDeferSyntheticProfileAuth` | 在环境 / 配置支持的认证之后，降低已存储合成配置档占位符的优先级 | 提供商存储了合成占位配置档，且它们不应获得更高优先级 | -| 10 | `resolveDynamicModel` | 为本地注册表中尚不存在的提供商自有 model id 提供同步回退 | 提供商接受任意上游 model id | -| 11 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 之前需要网络元数据 | -| 12 | `normalizeResolvedModel` | 在嵌入式运行器使用已解析模型前做最终重写 | 提供商需要传输重写，但仍使用核心传输 | -| 13 | `contributeResolvedModelCompat` | 为另一种兼容传输背后的厂商模型贡献兼容标志 | 提供商能够在代理传输上识别自己的模型，而无需接管该提供商 | -| 14 | `capabilities` | 被共享核心逻辑使用的提供商自有转录 / 工具元数据 | 提供商需要处理转录 / 提供商家族特性 | -| 15 | `normalizeToolSchemas` | 在嵌入式运行器看到工具 schema 前进行规范化 | 提供商需要传输家族 schema 清理 | -| 16 | `inspectToolSchemas` | 在规范化后暴露提供商自有 schema 诊断 | 提供商希望给出关键字警告，而无需让核心学习提供商专属规则 | -| 17 | `resolveReasoningOutputMode` | 选择原生或带标签的推理输出契约 | 提供商需要使用带标签的推理 / 最终输出，而不是原生字段 | -| 18 | `prepareExtraParams` | 在通用流式选项包装器前进行请求参数规范化 | 提供商需要默认请求参数或按提供商进行参数清理 | -| 19 | `createStreamFn` | 用自定义传输完全替换正常流式路径 | 提供商需要自定义线协议，而不仅仅是包装器 | -| 20 | `wrapStreamFn` | 在通用包装器应用后再包装流式函数 | 提供商需要请求头 / 请求体 / 模型兼容包装器，而非自定义传输 | -| 21 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | 提供商希望通用传输发送提供商原生轮次身份 | -| 22 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | 提供商希望通用 WS 传输调整会话头或回退策略 | -| 23 | `formatApiKey` | 认证配置档格式化器：将存储的配置档转换为运行时 `apiKey` 字符串 | 提供商存储额外认证元数据，并需要自定义运行时令牌形态 | -| 24 | `refreshOAuth` | 为自定义刷新端点或刷新失败策略覆盖 OAuth 刷新 | 提供商不适配共享的 `pi-ai` 刷新器 | -| 25 | `buildAuthDoctorHint` | OAuth 刷新失败时附加的修复提示 | 提供商在刷新失败后需要提供商自有的认证修复指导 | -| 26 | `matchesContextOverflowError` | 提供商自有上下文窗口溢出匹配器 | 提供商有通用启发式无法识别的原始溢出错误 | -| 27 | `classifyFailoverReason` | 提供商自有故障转移原因分类 | 提供商可以将原始 API / 传输错误映射为限流 / 过载等 | -| 28 | `isCacheTtlEligible` | 代理 / 回程提供商的提示词缓存策略 | 提供商需要代理专属缓存 TTL 门控 | -| 29 | `buildMissingAuthMessage` | 替换通用的缺失认证恢复消息 | 提供商需要提供商专属的缺失认证恢复提示 | -| 30 | `suppressBuiltInModel` | 过时上游模型抑制，以及可选的面向用户错误提示 | 提供商需要隐藏过时上游条目或以厂商提示替换它们 | -| 31 | `augmentModelCatalog` | 在发现后追加合成 / 最终目录条目 | 提供商需要在 `models list` 和选择器中加入合成前向兼容条目 | -| 32 | `isBinaryThinking` | 为二元思考提供商提供开 / 关推理切换 | 提供商仅暴露二元开 / 关思考 | -| 33 | `supportsXHighThinking` | 为选定模型提供 `xhigh` 推理支持 | 提供商仅希望在一部分模型上启用 `xhigh` | -| 34 | `resolveDefaultThinkingLevel` | 为特定模型家族指定默认 `/think` 级别 | 提供商拥有某个模型家族的默认 `/think` 策略 | -| 35 | `isModernModelRef` | 用于实时配置档筛选和 smoke 选择的现代模型匹配器 | 提供商拥有 live / smoke 首选模型匹配逻辑 | -| 36 | `prepareRuntimeAuth` | 在推理前最后一步，将已配置凭证交换为实际运行时令牌 / 密钥 | 提供商需要令牌交换或短期请求凭证 | -| 37 | `resolveUsageAuth` | 为 `/usage` 及相关状态接口解析使用量 / 计费凭证 | 提供商需要自定义使用量 / 配额令牌解析或不同的使用量凭证 | -| 38 | `fetchUsageSnapshot` | 在认证解析后抓取并规范化提供商专属使用量 / 配额快照 | 提供商需要提供商专属使用量端点或负载解析器 | -| 39 | `createEmbeddingProvider` | 为 memory / 搜索 构建提供商自有 embedding 适配器 | memory embedding 行为应属于提供商插件 | -| 40 | `buildReplayPolicy` | 返回一个控制提供商转录处理方式的重放策略 | 提供商需要自定义转录策略（例如去除 thinking 块） | -| 41 | `sanitizeReplayHistory` | 在通用转录清理后重写重放历史 | 提供商需要超出共享压缩辅助函数之外的提供商专属重放重写 | -| 42 | `validateReplayTurns` | 在嵌入式运行器之前，对重放轮次进行最终验证或重塑 | 提供商传输需要在通用净化后执行更严格的轮次验证 | -| 43 | `onModelSelected` | 运行提供商自有的选择后副作用 | 当模型变为活动状态时，提供商需要遥测或提供商自有状态 | +| # | Hook | 作用 | 何时使用 | +| --- | --------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 | `catalog` | 在生成 `models.json` 时将提供商配置发布到 `models.providers` | 提供商拥有目录或 base URL 默认值 | +| 2 | `applyConfigDefaults` | 在配置具体化期间应用提供商自有的全局配置默认值 | 默认值依赖认证模式、env 或提供商模型家族语义 | +| -- | _(内置模型查找)_ | OpenClaw 首先尝试常规注册表 / 目录路径 | _(不是插件 hook)_ | +| 3 | `normalizeModelId` | 在查找前标准化遗留或预览版模型 id 别名 | 提供商拥有规范模型解析前的别名清理逻辑 | +| 4 | `normalizeTransport` | 在通用模型组装前标准化提供商家族中的 `api` / `baseUrl` | 提供商拥有同一传输家族中自定义 provider id 的传输清理逻辑 | +| 5 | `normalizeConfig` | 在运行时 / 提供商解析前标准化 `models.providers.` | 提供商需要将配置清理逻辑与插件放在一起；内置 Google 家族辅助函数也会对受支持的 Google 配置项提供兜底兼容清理 | +| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式使用量兼容改写 | 提供商需要基于端点驱动的原生流式使用量元数据修复 | +| 7 | `resolveConfigApiKey` | 在加载运行时认证前，为配置提供商解析 env-marker 认证 | 提供商拥有自有的 env-marker API key 解析逻辑；`amazon-bedrock` 在这里也有内置的 AWS env-marker 解析器 | +| 8 | `resolveSyntheticAuth` | 在不持久化明文的前提下暴露本地 / 自托管或基于配置的认证 | 提供商可以使用 synthetic / 本地凭证标记运行 | +| 9 | `shouldDeferSyntheticProfileAuth` | 降低已存储 synthetic 配置文件占位符在 env / 配置支持认证后的优先级 | 提供商存储了 synthetic 占位 profile，而这些 profile 不应优先 | +| 10 | `resolveDynamicModel` | 为本地注册表中尚不存在的提供商自有模型 id 提供同步回退 | 提供商接受任意上游模型 id | +| 11 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 前需要网络元数据 | +| 12 | `normalizeResolvedModel` | 在嵌入式 runner 使用已解析模型前进行最终改写 | 提供商需要传输改写，但仍使用 core 传输 | +| 13 | `contributeResolvedModelCompat` | 为位于其他兼容传输后的厂商模型提供兼容标记 | 提供商可以在不接管整个提供商的情况下识别代理传输上的自有模型 | +| 14 | `capabilities` | 供共享 core 逻辑使用的、提供商自有的转录 / 工具元数据 | 提供商需要转录 / 提供商家族特有的兼容处理 | +| 15 | `normalizeToolSchemas` | 在嵌入式 runner 看到工具 schema 之前进行标准化 | 提供商需要传输家族级的 schema 清理 | +| 16 | `inspectToolSchemas` | 在标准化后暴露提供商自有的 schema 诊断 | 提供商希望给出关键字警告，而不是让 core 学会提供商特定规则 | +| 17 | `resolveReasoningOutputMode` | 选择原生还是带标签的推理输出契约 | 提供商需要带标签的推理 / 最终输出，而不是原生字段 | +| 18 | `prepareExtraParams` | 在通用流式选项包装器之前做请求参数标准化 | 提供商需要默认请求参数或按提供商清理参数 | +| 19 | `createStreamFn` | 用自定义传输完全替换常规流路径 | 提供商需要自定义线路协议，而不只是包装器 | +| 20 | `wrapStreamFn` | 在应用通用包装器后再包装流函数 | 提供商需要请求头 / 请求体 / 模型兼容包装器，而无需自定义传输 | +| 21 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | 提供商希望通用传输发送提供商原生的轮次身份 | +| 22 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | 提供商希望通用 WS 传输调优会话头或回退策略 | +| 23 | `formatApiKey` | 认证 profile 格式化器：已存储 profile 会变成运行时 `apiKey` 字符串 | 提供商存储了额外认证元数据，且需要自定义运行时 token 形态 | +| 24 | `refreshOAuth` | 针对自定义刷新端点或刷新失败策略的 OAuth 刷新覆写 | 提供商不适合共享的 `pi-ai` 刷新器 | +| 25 | `buildAuthDoctorHint` | 当 OAuth 刷新失败时附加修复提示 | 提供商在刷新失败后需要提供商自有的认证修复指导 | +| 26 | `matchesContextOverflowError` | 提供商自有的上下文窗口溢出匹配器 | 提供商存在通用启发式无法识别的原始溢出错误 | +| 27 | `classifyFailoverReason` | 提供商自有的故障切换原因分类 | 提供商可以将原始 API / 传输错误映射为限速 / 过载等 | +| 28 | `isCacheTtlEligible` | 代理 / 回程提供商的提示词缓存策略 | 提供商需要代理特定的缓存 TTL 门控 | +| 29 | `buildMissingAuthMessage` | 替代通用缺失认证恢复消息 | 提供商需要提供商特定的缺失认证恢复提示 | +| 30 | `suppressBuiltInModel` | 过期上游模型抑制以及可选的面向用户错误提示 | 提供商需要隐藏过期上游条目或用厂商提示替换它们 | +| 31 | `augmentModelCatalog` | 在发现后追加 synthetic / 最终目录条目 | 提供商需要在 `models list` 和选择器中加入 synthetic 前向兼容条目 | +| 32 | `isBinaryThinking` | 二元思考型提供商的开 / 关推理切换 | 提供商只暴露二元的思考开 / 关 | +| 33 | `supportsXHighThinking` | 为选定模型提供 `xhigh` 推理支持 | 提供商只希望部分模型支持 `xhigh` | +| 34 | `resolveDefaultThinkingLevel` | 为特定模型家族提供默认 `/think` 级别 | 提供商拥有某个模型家族的默认 `/think` 策略 | +| 35 | `isModernModelRef` | 用于实时 profile 过滤和 smoke 选择的现代模型匹配器 | 提供商拥有 live / smoke 首选模型匹配逻辑 | +| 36 | `prepareRuntimeAuth` | 在推理前将已配置凭证交换成真实运行时 token / key | 提供商需要 token 交换或短期请求凭证 | +| 37 | `resolveUsageAuth` | 为 `/usage` 及相关状态接口解析使用量 / 计费凭证 | 提供商需要自定义使用量 / 配额 token 解析，或使用不同的使用量凭证 | +| 38 | `fetchUsageSnapshot` | 在认证解析后获取并标准化提供商特定的使用量 / 配额快照 | 提供商需要提供商特定的使用量端点或负载解析器 | +| 39 | `createEmbeddingProvider` | 为 memory / search 构建提供商自有的 embedding 适配器 | memory embedding 行为应归属于提供商插件 | +| 40 | `buildReplayPolicy` | 返回控制提供商转录处理的 replay 策略 | 提供商需要自定义转录策略（例如剥离 thinking block） | +| 41 | `sanitizeReplayHistory` | 在通用转录清理后改写 replay 历史 | 提供商需要超出共享压缩辅助函数之外的提供商特定 replay 改写 | +| 42 | `validateReplayTurns` | 在嵌入式 runner 之前进行最终 replay 轮次验证或重塑 | 提供商传输在通用清理之后需要更严格的轮次验证 | +| 43 | `onModelSelected` | 运行提供商自有的模型选定后副作用 | 提供商需要在模型激活时记录遥测或维护提供商自有状态 | -`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配到的提供商插件，然后再继续检查其他具备相应钩子能力的提供商插件，直到其中某个插件真的修改了 model id 或 transport / config。这样可以让别名 / 兼容提供商 shim 正常工作，而无需让调用方知道哪个内置插件拥有该重写逻辑。如果没有任何提供商钩子重写受支持的 Google 家族配置项，内置 Google 配置规范化器仍会应用该兼容清理。 +`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查 +匹配到的提供商插件，然后依次回退到其他具备 hook 能力的提供商插件， +直到其中某个插件实际更改了 model id 或 transport / config 为止。这让 +别名 / 兼容性提供商 shim 可以继续工作，而无需要求调用方知道哪个 +内置插件拥有该改写逻辑。如果没有提供商 hook 改写受支持的 +Google 家族配置项，内置 Google 配置标准化器仍会应用 +该兼容性清理。 -如果提供商需要完全自定义的线协议或自定义请求执行器，那是另一类扩展。这些钩子适用于仍运行在 OpenClaw 常规推理循环上的提供商行为。 +如果提供商需要完全自定义的线路协议或自定义请求执行器， +那属于另一类扩展。这些 hooks 适用于仍运行在 +OpenClaw 常规推理循环上的提供商行为。 ### 提供商示例 @@ -628,91 +760,115 @@ api.registerProvider({ - Anthropic 使用 `resolveDynamicModel`、`capabilities`、`buildAuthDoctorHint`、 `resolveUsageAuth`、`fetchUsageSnapshot`、`isCacheTtlEligible`、 - `resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef` - 和 `wrapStreamFn`，因为它拥有 Claude 4.6 前向兼容、 + `resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、 + 和 `wrapStreamFn`，因为它拥有 Claude 4.6 的前向兼容、 提供商家族提示、认证修复指导、使用量端点集成、 - 提示词缓存资格、带认证感知的配置默认值、Claude - 默认 / 自适应思考策略，以及面向 beta headers、 - `/fast` / `serviceTier` 和 `context1m` 的 Anthropic 专属流式整形。 -- Anthropic 的 Claude 专属流式辅助函数目前保留在该内置插件自己的公共 `api.ts` / `contract-api.ts` 接缝中。该包接口 + 提示词缓存资格、具备认证感知的配置默认值、Claude + 默认 / 自适应 thinking 策略，以及面向 beta + headers、`/fast` / `serviceTier` 和 `context1m` 的 Anthropic 特定流整形。 +- Anthropic 的 Claude 特定流辅助函数目前保留在该内置插件自己的 + 公共 `api.ts` / `contract-api.ts` 接缝中。该包接口 导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 - `resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及更底层的 - Anthropic 包装器构建函数，而不是围绕某个提供商的 beta-header 规则扩展通用 SDK。 + `resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 + Anthropic 包装器构建函数，而不是围绕某一提供商的 beta header 规则 + 扩大通用 SDK。 - OpenAI 使用 `resolveDynamicModel`、`normalizeResolvedModel` 和 `capabilities`，以及 `buildMissingAuthMessage`、`suppressBuiltInModel`、 `augmentModelCatalog`、`supportsXHighThinking` 和 `isModernModelRef`， - 因为它拥有 GPT-5.4 前向兼容、直接 OpenAI - `openai-completions` -> `openai-responses` 规范化、Codex 感知认证 - 提示、Spark 抑制、合成 OpenAI 列表条目，以及 GPT-5 思考 / - live-model 策略；`openai-responses-defaults` 流式家族拥有 - 共享原生 OpenAI Responses 包装器，用于 attribution headers、 + 因为它拥有 GPT-5.4 的前向兼容、直接的 OpenAI + `openai-completions` -> `openai-responses` 标准化、Codex 感知的认证 + 提示、Spark 抑制、synthetic OpenAI 列表行，以及 GPT-5 thinking / + 实时模型策略；`openai-responses-defaults` 流家族拥有共享的原生 OpenAI Responses 包装器， + 用于 attribution headers、 `/fast`/`serviceTier`、文本冗长度、原生 Codex 网页搜索、 - reasoning-compat 负载整形，以及 Responses 上下文管理。 + reasoning 兼容负载整形，以及 Responses 上下文管理。 - OpenRouter 使用 `catalog` 以及 `resolveDynamicModel` 和 - `prepareDynamicModel`，因为该提供商是透传型的，可能会在 OpenClaw 的静态目录更新之前暴露新的 model id；它还使用 - `capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，以便将 - 提供商专属请求头、路由元数据、推理补丁和提示词缓存策略留在核心之外。它的重放策略来自 - `passthrough-gemini` 家族，而 `openrouter-thinking` 流式家族则拥有代理推理注入和不受支持模型 / `auto` 跳过逻辑。 + `prepareDynamicModel`，因为该提供商是透传型的，可能在 OpenClaw + 静态目录更新前就暴露出新的模型 id；它还使用 + `capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，以将 + 提供商特定的请求头、路由元数据、reasoning 修补和 + 提示词缓存策略留在 core 之外。其 replay 策略来自 + `passthrough-gemini` 家族，而 `openrouter-thinking` 流家族 + 拥有代理 reasoning 注入以及不受支持模型 / `auto` 的跳过逻辑。 - GitHub Copilot 使用 `catalog`、`auth`、`resolveDynamicModel` 和 `capabilities`，以及 `prepareRuntimeAuth` 和 `fetchUsageSnapshot`，因为它 - 需要提供商自有设备登录、模型回退行为、Claude 转录特性、 - GitHub token -> Copilot token 交换，以及提供商自有使用量端点。 + 需要提供商自有的设备登录、模型回退行为、Claude 转录兼容性、 + GitHub token -> Copilot token 交换，以及提供商自有的使用量端点。 - OpenAI Codex 使用 `catalog`、`resolveDynamicModel`、 `normalizeResolvedModel`、`refreshOAuth` 和 `augmentModelCatalog`，以及 `prepareExtraParams`、`resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它 - 仍运行在核心 OpenAI 传输之上，但拥有自己的传输 / base URL - 规范化、OAuth 刷新回退策略、默认传输选择、 - 合成 Codex 目录条目，以及 ChatGPT 使用量端点集成；它与直接 OpenAI 共享同一个 `openai-responses-defaults` 流式家族。 + 仍运行在 core OpenAI 传输之上，但拥有自己的 transport / base URL + 标准化、OAuth 刷新回退策略、默认传输选择、 + synthetic Codex 目录条目，以及 ChatGPT 使用量端点集成；它 + 与直接 OpenAI 共享同一个 `openai-responses-defaults` 流家族。 - Google AI Studio 和 Gemini CLI OAuth 使用 `resolveDynamicModel`、 `buildReplayPolicy`、`sanitizeReplayHistory`、 `resolveReasoningOutputMode`、`wrapStreamFn` 和 `isModernModelRef`，因为 - `google-gemini` 重放家族拥有 Gemini 3.1 前向兼容回退、 - 原生 Gemini 重放验证、bootstrap 重放净化、 - 带标签的推理输出模式，以及现代模型匹配，而 - `google-thinking` 流式家族拥有 Gemini thinking 负载规范化； + `google-gemini` replay 家族拥有 Gemini 3.1 前向兼容回退、 + 原生 Gemini replay 验证、bootstrap replay 清理、 + 带标签的 reasoning 输出模式，以及现代模型匹配，而 + `google-thinking` 流家族拥有 Gemini thinking 负载标准化； Gemini CLI OAuth 还使用 `formatApiKey`、`resolveUsageAuth` 和 - `fetchUsageSnapshot` 来处理令牌格式化、令牌解析和配额端点接线。 + `fetchUsageSnapshot` 来处理 token 格式化、token 解析以及配额端点 + 接线。 - Anthropic Vertex 通过 - `anthropic-by-model` 重放家族使用 `buildReplayPolicy`，这样 Claude 专属重放清理就只作用于 Claude id，而不是所有 `anthropic-messages` 传输。 + `anthropic-by-model` replay 家族使用 `buildReplayPolicy`，从而让 Claude 特定的 replay 清理 + 只作用于 Claude id，而不是每个 `anthropic-messages` 传输。 - Amazon Bedrock 使用 `buildReplayPolicy`、`matchesContextOverflowError`、 `classifyFailoverReason` 和 `resolveDefaultThinkingLevel`，因为它拥有 - 针对 Anthropic-on-Bedrock 流量的 Bedrock 专属限流 / 未就绪 / 上下文溢出错误分类；其重放策略仍共享相同的 - 仅 Claude `anthropic-by-model` 防护。 -- OpenRouter、Kilocode、Opencode 和 Opencode Go 通过 `passthrough-gemini` 重放家族使用 `buildReplayPolicy`，因为它们通过 OpenAI 兼容传输代理 Gemini 模型，并需要 Gemini thought-signature 净化，而不需要原生 Gemini 重放验证或 bootstrap 重写。 + Bedrock 特定的限流 / 未就绪 / 上下文溢出错误分类， + 用于 Anthropic-on-Bedrock 流量；其 replay 策略仍共享相同的 + 仅限 Claude 的 `anthropic-by-model` 防护。 +- OpenRouter、Kilocode、Opencode 和 Opencode Go 通过 + `passthrough-gemini` replay 家族使用 `buildReplayPolicy`，因为它们通过 OpenAI 兼容传输 + 代理 Gemini 模型，并且需要进行 Gemini + thought-signature 清理，而无需原生 Gemini replay 验证或 + bootstrap 改写。 - MiniMax 通过 - `hybrid-anthropic-openai` 重放家族使用 `buildReplayPolicy`，因为一个提供商同时拥有 Anthropic-message 和 OpenAI 兼容语义；它会在 Anthropic 一侧保留仅 Claude 的 thinking 块丢弃逻辑，同时将推理输出模式覆盖回原生，而 `minimax-fast-mode` 流式家族拥有共享流式路径上的 fast-mode 模型重写。 -- Moonshot 使用 `catalog` 加 `wrapStreamFn`，因为它仍使用共享 - OpenAI 传输，但需要提供商自有 thinking 负载规范化；`moonshot-thinking` 流式家族会把配置和 `/think` 状态映射到其原生二元 thinking 负载上。 + `hybrid-anthropic-openai` replay 家族使用 `buildReplayPolicy`，因为一个提供商同时拥有 + Anthropic-message 和 OpenAI 兼容语义；它会在 Anthropic 侧保持仅限 Claude 的 + thinking block 丢弃，同时将 reasoning + 输出模式改回原生，而 `minimax-fast-mode` 流家族则拥有 + 共享流路径上的 fast-mode 模型改写。 +- Moonshot 使用 `catalog` 和 `wrapStreamFn`，因为它仍使用共享的 + OpenAI 传输，但需要提供商自有的 thinking 负载标准化； + `moonshot-thinking` 流家族将配置和 `/think` 状态映射到其 + 原生二元 thinking 负载。 - Kilocode 使用 `catalog`、`capabilities`、`wrapStreamFn` 和 - `isCacheTtlEligible`，因为它需要提供商自有请求头、 - 推理负载规范化、Gemini 转录提示和 Anthropic - 缓存 TTL 门控；`kilocode-thinking` 流式家族会在共享代理流式路径上保留 Kilo thinking 注入，同时跳过 `kilo/auto` 和其他不支持显式推理负载的代理 model id。 + `isCacheTtlEligible`，因为它需要提供商自有的请求头、 + reasoning 负载标准化、Gemini 转录提示，以及 Anthropic + cache-TTL 门控；`kilocode-thinking` 流家族负责在共享代理流路径上注入 Kilo thinking， + 同时跳过 `kilo/auto` 以及其他不支持显式 reasoning 负载的 + 代理模型 id。 - Z.AI 使用 `resolveDynamicModel`、`prepareExtraParams`、`wrapStreamFn`、 `isCacheTtlEligible`、`isBinaryThinking`、`isModernModelRef`、 `resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它拥有 GLM-5 回退、 - `tool_stream` 默认值、二元 thinking 用户体验、现代模型匹配，以及 - 使用量认证和配额抓取；`tool-stream-default-on` 流式家族让默认开启的 `tool_stream` 包装器不必散落在各提供商的手写胶水代码中。 + `tool_stream` 默认值、二元 thinking UX、现代模型匹配，以及 + 使用量认证 + 配额获取；`tool-stream-default-on` 流家族将 + 默认开启的 `tool_stream` 包装器从每个提供商手写粘合逻辑中抽离出来。 - xAI 使用 `normalizeResolvedModel`、`normalizeTransport`、 `contributeResolvedModelCompat`、`prepareExtraParams`、`wrapStreamFn`、 `resolveSyntheticAuth`、`resolveDynamicModel` 和 `isModernModelRef`， - 因为它拥有原生 xAI Responses 传输规范化、Grok fast-mode - 别名重写、默认 `tool_stream`、strict-tool / reasoning-payload - 清理、面向插件自有工具的回退认证复用、前向兼容 Grok - 模型解析，以及提供商自有兼容补丁，例如 xAI 工具 schema - 配置档、不支持的 schema 关键字、原生 `web_search` 和 HTML 实体 + 因为它拥有原生 xAI Responses 传输标准化、Grok fast-mode + 别名改写、默认 `tool_stream`、strict-tool / reasoning-payload + 清理、用于插件自有工具的回退认证复用、前向兼容的 Grok + 模型解析，以及提供商自有的兼容修补，例如 xAI 工具 schema + 配置、受支持范围外的 schema 关键字、原生 `web_search`，以及 HTML 实体 工具调用参数解码。 -- Mistral、OpenCode Zen 和 OpenCode Go 仅使用 `capabilities`，以便将转录 / 工具特性保留在核心之外。 -- 仅目录型内置提供商，如 `byteplus`、`cloudflare-ai-gateway`、 +- Mistral、OpenCode Zen 和 OpenCode Go 仅使用 `capabilities`， + 以将转录 / 工具兼容性留在 core 之外。 +- 仅目录型内置提供商，例如 `byteplus`、`cloudflare-ai-gateway`、 `huggingface`、`kimi-coding`、`nvidia`、`qianfan`、 - `synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine`，仅使用 - `catalog`。 -- Qwen 对其文本提供商使用 `catalog`，同时对其多模态接口注册共享的媒体理解和视频生成能力。 -- MiniMax 和 Xiaomi 使用 `catalog` 加使用量钩子，因为它们的 `/usage` - 行为属于插件自有，即使推理仍通过共享传输运行。 + `synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine`， + 仅使用 `catalog`。 +- Qwen 使用 `catalog` 处理其文本提供商，同时为其多模态接口 + 注册共享的媒体理解和视频生成。 +- MiniMax 和 Xiaomi 使用 `catalog` 加上使用量 hooks，因为它们的 `/usage` + 行为归插件所有，尽管推理仍通过共享传输运行。 ## 运行时辅助函数 -插件可以通过 `api.runtime` 访问部分核心辅助函数。对于 TTS： +插件可以通过 `api.runtime` 访问部分选定的 core 辅助函数。对于 TTS： ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -733,11 +889,11 @@ const voices = await api.runtime.tts.listVoices({ 说明： -- `textToSpeech` 返回用于文件 / 语音笔记接口的常规核心 TTS 输出负载。 -- 使用核心 `messages.tts` 配置和提供商选择。 -- 返回 PCM 音频缓冲区 + 采样率。插件必须为提供商自行重采样 / 编码。 -- `listVoices` 对每个提供商都是可选的。可将它用于厂商自有语音选择器或设置流程。 -- 语音列表可以包含更丰富的元数据，例如地区、性别和个性标签，以供提供商感知的选择器使用。 +- `textToSpeech` 返回面向文件 / 语音便笺接口的常规 core TTS 输出负载。 +- 使用 core 的 `messages.tts` 配置和提供商选择。 +- 返回 PCM 音频缓冲区 + 采样率。插件必须为提供商重新采样 / 编码。 +- `listVoices` 对每个提供商而言是可选的。将其用于厂商自有的语音选择器或设置流程。 +- 语音列表可以包含更丰富的元数据，例如区域设置、性别和 personality 标签，以供感知提供商的选择器使用。 - 目前 OpenAI 和 ElevenLabs 支持电话场景。Microsoft 不支持。 插件也可以通过 `api.registerSpeechProvider(...)` 注册语音提供商。 @@ -760,12 +916,14 @@ api.registerSpeechProvider({ 说明： -- 将 TTS 策略、回退和回复投递保留在核心中。 -- 使用语音提供商承载厂商自有合成行为。 -- 遗留 Microsoft `edge` 输入会被规范化为 `microsoft` provider id。 -- 首选归属模型是面向公司的：随着 OpenClaw 增加这些能力契约，一个厂商插件可以同时拥有文本、语音、图像和未来媒体提供商。 +- 将 TTS 策略、回退和回复交付保留在 core 中。 +- 使用语音提供商承载厂商自有的合成行为。 +- 遗留 Microsoft `edge` 输入会被标准化为 `microsoft` provider id。 +- 推荐的归属模型是面向公司的：随着 OpenClaw 增加这些 + 能力契约，一个厂商插件可以拥有文本、语音、图像以及未来的媒体提供商。 -对于图像 / 音频 / 视频理解，插件应注册一个类型化的媒体理解提供商，而不是通用键值包： +对于图像 / 音频 / 视频理解，插件应注册一个类型化的 +媒体理解提供商，而不是一个通用的 key / value 包： ```ts api.registerMediaUnderstandingProvider({ @@ -779,11 +937,12 @@ api.registerMediaUnderstandingProvider({ 说明： -- 将编排、回退、配置和渠道接线保留在核心中。 +- 将编排、回退、配置和渠道接线保留在 core 中。 - 将厂商行为保留在提供商插件中。 -- 增量扩展应保持类型化：新的可选方法、新的可选结果字段、新的可选能力。 -- 视频生成已经遵循相同模式： - - 核心拥有能力契约和运行时辅助函数 +- 增量扩展应保持类型化：新增可选方法、新增可选 + 结果字段、新增可选能力。 +- 视频生成已经遵循同样模式： + - core 拥有能力契约和运行时辅助函数 - 厂商插件注册 `api.registerVideoGenerationProvider(...)` - 功能 / 渠道插件消费 `api.runtime.videoGeneration.*` @@ -802,21 +961,23 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -对于音频转录，插件可以使用媒体理解运行时，或者使用较旧的 STT 别名： +对于音频转录，插件既可以使用媒体理解运行时， +也可以使用旧的 STT 别名： ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Optional when MIME cannot be inferred reliably: + // 当 MIME 无法可靠推断时可选： mime: "audio/ogg", }); ``` 说明： -- `api.runtime.mediaUnderstanding.*` 是图像 / 音频 / 视频理解的首选共享接口。 -- 使用核心媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。 +- `api.runtime.mediaUnderstanding.*` 是图像 / 音频 / 视频理解 + 的首选共享接口。 +- 使用 core 的媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。 - 当未产生转录输出时（例如输入被跳过 / 不受支持），返回 `{ text: undefined }`。 - `api.runtime.stt.transcribeAudioFile(...)` 仍保留为兼容别名。 @@ -834,13 +995,14 @@ const result = await api.runtime.subagent.run({ 说明： -- `provider` 和 `model` 是每次运行的可选覆盖项，不会持久化更改会话。 -- OpenClaw 仅对受信任调用方接受这些覆盖字段。 -- 对于插件自有回退运行，操作员必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式选择启用。 -- 使用 `plugins.entries..subagent.allowedModels` 将受信任插件限制为特定规范 `provider/model` 目标，或使用 `"*"` 显式允许任何目标。 -- 不受信任的插件子智能体运行仍可工作，但覆盖请求会被拒绝，而不是静默回退。 +- `provider` 和 `model` 是每次运行的可选覆写，而不是持久会话变更。 +- OpenClaw 只会为受信任调用方接受这些覆写字段。 +- 对于插件自有的回退运行，运维人员必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式启用。 +- 使用 `plugins.entries..subagent.allowedModels` 将受信任插件限制为特定的规范 `provider/model` 目标，或设置为 `"*"` 以显式允许任意目标。 +- 不受信任的插件子智能体运行仍可执行，但覆写请求会被拒绝，而不是静默回退。 -对于网页搜索，插件可以消费共享运行时辅助函数，而不是深入访问智能体工具接线： +对于网页搜索，插件可以消费共享运行时辅助函数，而不是 +深入智能体工具接线： ```ts const providers = api.runtime.webSearch.listProviders({ @@ -861,9 +1023,10 @@ const result = await api.runtime.webSearch.search({ 说明： -- 将提供商选择、凭证解析和共享请求语义保留在核心中。 -- 使用网页搜索提供商来承载厂商专属搜索传输。 -- `api.runtime.webSearch.*` 是功能 / 渠道插件在需要搜索行为但不依赖智能体工具包装器时的首选共享接口。 +- 将提供商选择、凭证解析和共享请求语义保留在 core 中。 +- 对于厂商特定的搜索传输，使用网页搜索提供商。 +- `api.runtime.webSearch.*` 是功能 / 渠道插件在需要搜索能力但又不依赖 + 智能体工具包装器时的首选共享接口。 ### `api.runtime.imageGeneration` @@ -901,33 +1064,33 @@ api.registerHttpRoute({ 路由字段： - `path`：Gateway 网关 HTTP 服务器下的路由路径。 -- `auth`：必填。使用 `"gateway"` 表示要求正常 Gateway 网关认证，或使用 `"plugin"` 表示由插件管理认证 / webhook 验签。 +- `auth`：必填。使用 `"gateway"` 以要求常规 Gateway 网关认证，或使用 `"plugin"` 以进行插件管理的认证 / webhook 验证。 - `match`：可选。`"exact"`（默认）或 `"prefix"`。 -- `replaceExisting`：可选。允许同一插件替换自己已有的路由注册。 +- `replaceExisting`：可选。允许同一插件替换自己现有的路由注册。 - `handler`：当路由处理了请求时返回 `true`。 说明： - `api.registerHttpHandler(...)` 已移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。 - 插件路由必须显式声明 `auth`。 -- 精确的 `path + match` 冲突会被拒绝，除非设置 `replaceExisting: true`，并且一个插件不能替换另一个插件的路由。 -- 不同 `auth` 级别的重叠路由会被拒绝。仅在相同认证级别内保留 `exact` / `prefix` 贯穿链。 -- `auth: "plugin"` 路由**不会**自动收到操作员运行时作用域。它们用于插件管理的 webhook / 签名验证，而不是特权 Gateway 网关辅助调用。 -- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域内运行，但该作用域是有意保守的： - - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` - - 受信任的携带身份 HTTP 模式（例如 `trusted-proxy` 或私有入口上的 `gateway.auth.mode = "none"`）只有在明确存在该请求头时，才会尊重 `x-openclaw-scopes` - - 如果这些携带身份的插件路由请求上不存在 `x-openclaw-scopes`，运行时作用域会回退到 `operator.write` -- 实用规则：不要假设一个带 gateway 认证的插件路由天然就是管理员接口。如果你的路由需要仅管理员行为，请要求使用携带身份的认证模式，并记录清楚显式 `x-openclaw-scopes` 请求头契约。 +- 除非设置 `replaceExisting: true`，否则精确的 `path + match` 冲突会被拒绝，且一个插件不能替换另一个插件的路由。 +- 不同 `auth` 级别的重叠路由会被拒绝。`exact` / `prefix` 的顺序回退链只能保留在同一 auth 级别内。 +- `auth: "plugin"` 路由**不会**自动接收运维人员运行时作用域。它们用于插件管理的 webhook / 签名验证，而不是带特权的 Gateway 网关辅助调用。 +- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域内运行，但该作用域有意保持保守： + - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定在 `operator.write`，即使调用方发送了 `x-openclaw-scopes` + - 受信任的携带身份 HTTP 模式（例如 `trusted-proxy` 或私有入口上的 `gateway.auth.mode = "none"`）只有在显式提供该 header 时，才会遵守 `x-openclaw-scopes` + - 如果这些携带身份的插件路由请求中没有 `x-openclaw-scopes`，运行时作用域会回退到 `operator.write` +- 实践规则：不要假设一个经过 gateway 认证的插件路由天然就是管理接口。如果你的路由需要仅管理员行为，请要求使用携带身份的认证模式，并记录显式的 `x-openclaw-scopes` header 契约。 ## 插件 SDK 导入路径 -编写插件时，请使用 SDK 子路径，而不是单体的 `openclaw/plugin-sdk` 导入： +在编写插件时，请使用 SDK 子路径，而不是单体式 `openclaw/plugin-sdk` 导入： -- `openclaw/plugin-sdk/plugin-entry` 用于插件注册原语。 -- `openclaw/plugin-sdk/core` 用于通用共享的面向插件契约。 -- `openclaw/plugin-sdk/config-schema` 用于根 `openclaw.json` Zod schema +- 使用 `openclaw/plugin-sdk/plugin-entry` 进行插件注册基础能力导入。 +- 使用 `openclaw/plugin-sdk/core` 进行通用共享的插件侧契约导入。 +- 使用 `openclaw/plugin-sdk/config-schema` 导入根 `openclaw.json` Zod schema 导出（`OpenClawSchema`）。 -- 稳定的渠道原语，例如 `openclaw/plugin-sdk/channel-setup`、 +- 稳定的渠道基础接口，例如 `openclaw/plugin-sdk/channel-setup`、 `openclaw/plugin-sdk/setup-runtime`、 `openclaw/plugin-sdk/setup-adapter-runtime`、 `openclaw/plugin-sdk/setup-tools`、 @@ -940,13 +1103,13 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/command-auth`、 `openclaw/plugin-sdk/secret-input` 和 `openclaw/plugin-sdk/webhook-ingress`，用于共享设置 / 认证 / 回复 / webhook - 接线。`channel-inbound` 是防抖、提及匹配、 - envelope 格式化和入站 envelope 上下文辅助函数的共享归属位置。 - `channel-setup` 是狭义的可选安装设置接缝。 + 接线。`channel-inbound` 是 debounce、mention 匹配、 + envelope 格式化和入站 envelope 上下文辅助函数的共享位置。 + `channel-setup` 是可选安装设置的狭窄接缝。 `setup-runtime` 是 `setupEntry` / - 延迟启动所使用、运行时安全的设置接口，包括导入安全的设置补丁适配器。 - `setup-adapter-runtime` 是具备环境感知的账户设置适配器接缝。 - `setup-tools` 是一个小型 CLI / 归档 / 文档辅助接口（`formatCliCommand`、 + 延迟启动所使用的运行时安全设置接口，包括可安全导入的设置补丁适配器。 + `setup-adapter-runtime` 是感知 env 的账户设置适配器接缝。 + `setup-tools` 是小型 CLI / 归档 / 文档辅助接缝（`formatCliCommand`、 `detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、 `CONFIG_DIR`）。 - 领域子路径，例如 `openclaw/plugin-sdk/channel-config-helpers`、 @@ -966,148 +1129,167 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/runtime-store` 和 `openclaw/plugin-sdk/directory-runtime`，用于共享运行时 / 配置辅助函数。 `telegram-command-config` 是 Telegram 自定义 - 命令规范化 / 验证的狭义公共接缝，即使内置 - Telegram 契约接口暂时不可用时也会保留。 - `text-runtime` 是共享文本 / markdown / 日志接缝，包括 - assistant 可见文本剥离、markdown 渲染 / 分块辅助函数、脱敏 - 辅助函数、directive-tag 辅助函数以及安全文本工具。 -- 审批专用渠道接缝应优先采用插件上的单个 `approvalCapability` - 契约。然后核心通过这一个能力来读取审批认证、投递、渲染和 - 原生路由行为，而不是将审批行为混杂到其他无关插件字段中。 -- `openclaw/plugin-sdk/channel-runtime` 已弃用，仅保留为 - 旧插件的兼容 shim。新代码应改为导入更窄的通用原语，并且仓库代码不应新增对该 shim 的导入。 -- 内置扩展内部实现仍然是私有的。外部插件应仅使用 - `openclaw/plugin-sdk/*` 子路径。OpenClaw 核心 / 测试代码可以使用 - 插件包根目录下的仓库公共入口点，例如 `index.js`、`api.js`、 - `runtime-api.js`、`setup-entry.js` 和范围更窄的文件，例如 - `login-qr-api.js`。核心或其他扩展绝不要导入某个插件包的 `src/*`。 + 命令标准化 / 验证的狭窄公共接缝，即便内置 + Telegram 契约接口暂时不可用，它也仍然可用。 + `text-runtime` 是共享的文本 / markdown / 日志接缝，包括 + 助手可见文本剥离、markdown 渲染 / 分块辅助函数、脱敏 + 辅助函数、directive-tag 辅助函数和安全文本工具。 +- 针对审批的渠道接缝应优先使用插件上的单一 `approvalCapability` + 契约。然后 core 会通过这一个能力读取审批认证、交付、渲染和 + 原生路由行为，而不是把审批行为混入无关的插件字段中。 +- `openclaw/plugin-sdk/channel-runtime` 已弃用，目前仅作为 + 旧插件的兼容 shim 保留。新代码应改用更狭窄的通用基础接口导入， + 仓库代码也不应再新增对该 shim 的导入。 +- 内置扩展内部实现仍然是私有的。外部插件应只使用 + `openclaw/plugin-sdk/*` 子路径。OpenClaw core / 测试代码可以使用插件包根目录下的 + 仓库公共入口点，例如 `index.js`、`api.js`、 + `runtime-api.js`、`setup-entry.js`，以及作用域较窄的文件，例如 + `login-qr-api.js`。绝不要从 core 或另一个扩展中导入某个插件包的 `src/*`。 - 仓库入口点拆分： `/api.js` 是辅助函数 / 类型 barrel， `/runtime-api.js` 是仅运行时 barrel， `/index.js` 是内置插件入口， `/setup-entry.js` 是设置插件入口。 - 当前内置提供商示例： - - Anthropic 使用 `api.js` / `contract-api.js` 提供 Claude 流式辅助函数，例如 + - Anthropic 使用 `api.js` / `contract-api.js` 提供 Claude 流辅助函数，例如 `wrapAnthropicProviderStream`、beta-header 辅助函数和 `service_tier` 解析。 - - OpenAI 使用 `api.js` 提供提供商构建器、默认模型辅助函数和 + - OpenAI 使用 `api.js` 提供提供商构建器、默认模型辅助函数，以及 实时提供商构建器。 - OpenRouter 使用 `api.js` 提供其提供商构建器以及新手引导 / 配置 - 辅助函数，而 `register.runtime.js` 仍可为仓库本地用途重新导出通用 + 辅助函数，而 `register.runtime.js` 仍然可以为仓库本地用途重新导出通用 `plugin-sdk/provider-stream` 辅助函数。 -- 由 facade 加载的公共入口点会优先使用当前活动的运行时配置快照； +- 通过 facade 加载的公共入口点会优先使用活动中的运行时配置快照； 如果 OpenClaw 尚未提供运行时快照，则回退到磁盘上的已解析配置文件。 -- 通用共享原语仍然是首选的公共 SDK 契约。仍保留一小组保留的兼容性内置渠道品牌辅助接缝。应将它们视为内置维护 / 兼容接缝，而不是新的第三方导入目标；新的跨渠道契约仍应落在通用 `plugin-sdk/*` 子路径或插件本地 `api.js` / +- 通用共享基础接口仍然是首选的公共 SDK 契约。仍然存在一小组保留的、 + 兼容性用途的内置渠道品牌化辅助接缝。应将这些视为内置维护 / + 兼容性接缝，而不是新的第三方导入目标；新的跨渠道契约仍应落在 + 通用 `plugin-sdk/*` 子路径或插件本地 `api.js` / `runtime-api.js` barrel 上。 兼容性说明： -- 新代码请避免使用根 `openclaw/plugin-sdk` barrel。 -- 优先使用窄而稳定的原语。较新的 setup / pairing / reply / +- 新代码应避免使用根级 `openclaw/plugin-sdk` barrel。 +- 优先使用狭窄、稳定的基础接口。更新的 setup / pairing / reply / feedback / contract / inbound / threading / command / secret-input / webhook / infra / - allowlist / status / message-tool 子路径是新内置和外部插件工作的预期契约。 - 目标解析 / 匹配属于 `openclaw/plugin-sdk/channel-targets`。 - 消息动作门控和反应消息 id 辅助函数属于 + allowlist / status / message-tool 子路径，是新的 + 内置和外部插件工作的目标契约。 + 目标解析 / 匹配应放在 `openclaw/plugin-sdk/channel-targets`。 + 消息动作门控和 reaction message-id 辅助函数应放在 `openclaw/plugin-sdk/channel-actions`。 -- 内置扩展专属辅助 barrel 默认并不稳定。如果某个 - 辅助函数仅被某个内置扩展需要，应将其保留在该扩展本地 - `api.js` 或 `runtime-api.js` 接缝后面，而不是提升到 - `openclaw/plugin-sdk/`。 +- 默认情况下，内置扩展特定辅助 barrel 并不稳定。如果 + 某个辅助函数只被某个内置扩展需要，应将其保留在该扩展的 + 本地 `api.js` 或 `runtime-api.js` 接缝后，而不是提升到 + `openclaw/plugin-sdk/` 中。 - 新的共享辅助接缝应是通用的，而不是带渠道品牌的。共享目标 - 解析属于 `openclaw/plugin-sdk/channel-targets`；渠道专属 - 内部实现则保留在所属插件本地的 `api.js` 或 `runtime-api.js` - 接缝之后。 + 解析应放在 `openclaw/plugin-sdk/channel-targets`；渠道特定 + 内部实现应保留在所属插件的本地 `api.js` 或 `runtime-api.js` + 接缝后。 - `image-generation`、 - `media-understanding` 和 `speech` 等能力专用子路径之所以存在，是因为今天内置 / 原生插件确实会使用它们。但这本身并不意味着其中每个导出辅助函数都是长期冻结的外部契约。 + `media-understanding` 和 `speech` 之类的能力特定子路径之所以存在， + 是因为内置 / 原生插件如今在使用它们。这并不自动意味着每个导出的辅助函数 + 都是长期冻结的外部契约。 ## 消息工具 schema -插件应拥有渠道专属的 `describeMessageTool(...)` schema -贡献。将提供商专属字段保留在插件中，而不是共享核心中。 +插件应拥有渠道特定的 `describeMessageTool(...)` schema +扩展。将提供商特定字段保留在插件中，而不是放入共享 core。 -对于共享的可移植 schema 片段，请复用通过 +对于共享的可移植 schema 片段，请复用 `openclaw/plugin-sdk/channel-actions` 导出的通用辅助函数： -- `createMessageToolButtonsSchema()` 用于按钮网格风格负载 +- `createMessageToolButtonsSchema()` 用于按钮网格样式负载 - `createMessageToolCardSchema()` 用于结构化卡片负载 -如果某种 schema 形态只适用于一个提供商，就应在该插件自己的源码中定义，而不是将其提升进共享 SDK。 +如果某个 schema 形态只适用于一个提供商，请在该插件自己的 +源代码中定义，而不要将其提升到共享 SDK 中。 ## 渠道目标解析 -渠道插件应拥有渠道专属目标语义。保持共享 outbound 宿主的通用性，并通过消息适配器接口承载提供商规则： +渠道插件应拥有渠道特定的目标语义。请保持共享 +outbound 宿主的通用性，并通过消息适配器接口处理提供商规则： -- `messaging.inferTargetChatType({ to })` 决定规范化目标在目录查找前应被视为 `direct`、`group` 还是 `channel`。 -- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉核心，某个输入是否应跳过目录搜索，直接进入类 id 解析。 -- `messaging.targetResolver.resolveTarget(...)` 是当核心在规范化之后或目录未命中之后需要提供商自有最终解析时的插件回退。 -- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后拥有提供商专属会话路由构建逻辑。 +- `messaging.inferTargetChatType({ to })` 用于决定一个标准化目标 + 在目录查找前应被视为 `direct`、`group` 还是 `channel`。 +- `messaging.targetResolver.looksLikeId(raw, normalized)` 用于告诉 core + 某个输入是否应跳过目录搜索，直接进入类似 id 的解析。 +- `messaging.targetResolver.resolveTarget(...)` 是在标准化之后或目录未命中后， + core 需要最终提供商自有解析时的插件回退接口。 +- `messaging.resolveOutboundSessionRoute(...)` 拥有提供商特定的会话 + 路由构建逻辑，在目标解析完成后执行。 推荐拆分： -- 使用 `inferTargetChatType` 处理应在搜索 peers / groups 之前完成的类别决策。 -- 使用 `looksLikeId` 处理“将其视为显式 / 原生目标 id”的检查。 -- 使用 `resolveTarget` 处理提供商专属规范化回退，而不是广义目录搜索。 -- 将聊天 id、线程 id、JID、handle 和房间 id 等提供商原生 id 保留在 `target` 值或提供商专属参数中，而不要放进通用 SDK 字段里。 +- 使用 `inferTargetChatType` 处理那些应在搜索 peers / groups 之前完成的分类决策。 +- 使用 `looksLikeId` 进行“将此视为显式 / 原生目标 id”的检查。 +- 使用 `resolveTarget` 进行提供商特定的标准化回退，而不是进行广泛的目录搜索。 +- 将聊天 id、线程 id、JID、handle 和房间 id 等提供商原生 id + 保留在 `target` 值或提供商特定参数中，而不是放入通用 SDK 字段。 -## 由配置支持的目录 +## 基于配置的目录 -从配置派生目录条目的插件，应将该逻辑保留在插件中，并复用来自 -`openclaw/plugin-sdk/directory-runtime` 的共享辅助函数。 +从配置派生目录项的插件应将该逻辑保留在 +插件内部，并复用 +`openclaw/plugin-sdk/directory-runtime` 中的共享辅助函数。 -当某个渠道需要由配置支持的 peers / groups 时，请使用它，例如： +当某个渠道需要基于配置的 peers / groups 时，应使用此模式，例如： -- 由 allowlist 驱动的私信 peers -- 已配置的 channel / group 映射 -- 按账户划分的静态目录回退 +- 基于 allowlist 的私信 peers +- 已配置的渠道 / 群组映射 +- 按账户作用域划分的静态目录回退 `directory-runtime` 中的共享辅助函数只处理通用操作： - 查询过滤 -- 限制应用 -- 去重 / 规范化辅助函数 +- 应用限制 +- 去重 / 标准化辅助函数 - 构建 `ChannelDirectoryEntry[]` -渠道专属账户检查和 id 规范化应保留在插件实现中。 +渠道特定的账户检查和 id 标准化应保留在 +插件实现中。 ## 提供商目录 提供商插件可以通过 -`registerProvider({ catalog: { run(...) { ... } } })` 定义用于推理的模型目录。 +`registerProvider({ catalog: { run(...) { ... } } })` 为推理定义模型目录。 `catalog.run(...)` 返回的形态与 OpenClaw 写入 -`models.providers` 的形态一致： +`models.providers` 的内容相同： -- `{ provider }` 用于一个 provider 条目 -- `{ providers }` 用于多个 provider 条目 +- `{ provider }` 表示一个 provider 条目 +- `{ providers }` 表示多个 provider 条目 -当插件拥有提供商专属 model id、base URL 默认值或受认证控制的模型元数据时，请使用 `catalog`。 +当插件拥有提供商特定的模型 id、base URL 默认值， +或受认证保护的模型元数据时，请使用 `catalog`。 -`catalog.order` 控制插件目录相对于 OpenClaw -内置隐式提供商的合并时机： +`catalog.order` 控制插件目录相对于 OpenClaw 内置隐式提供商 +合并的时机： -- `simple`：普通 API key 或环境驱动的提供商 -- `profile`：当存在认证配置档时出现的提供商 +- `simple`：纯 API key 或 env 驱动的提供商 +- `profile`：当存在 auth profiles 时出现的提供商 - `paired`：合成多个相关 provider 条目的提供商 - `late`：最后一轮，在其他隐式提供商之后 -后出现的 provider 会在键冲突时获胜，因此插件可以有意用相同 provider id 覆盖内置 provider 条目。 +后出现的提供商会在键冲突时获胜，因此插件可以有意用相同的 +provider id 覆盖内置 provider 条目。 兼容性： -- `discovery` 仍可作为遗留别名使用 +- `discovery` 仍可用，作为遗留别名 - 如果同时注册了 `catalog` 和 `discovery`，OpenClaw 会使用 `catalog` ## 只读渠道检查 -如果你的插件注册了一个渠道，请优先实现 -`plugin.config.inspectAccount(cfg, accountId)`，并与 `resolveAccount(...)` 一起提供。 +如果你的插件注册了一个渠道，建议在 +`resolveAccount(...)` 之外同时实现 `plugin.config.inspectAccount(cfg, accountId)`。 原因如下： -- `resolveAccount(...)` 是运行时路径。它可以假定凭证已经被完全具体化，并在缺失必需 secret 时快速失败。 -- 只读命令路径，例如 `openclaw status`、`openclaw status --all`、 - `openclaw channels status`、`openclaw channels resolve`，以及 doctor / 配置 - 修复流程，不应为了描述配置而必须具体化运行时凭证。 +- `resolveAccount(...)` 是运行时路径。它可以假定凭证 + 已完全具体化，并且在所需 secret 缺失时快速失败。 +- `openclaw status`、`openclaw status --all`、 + `openclaw channels status`、`openclaw channels resolve` 以及 Doctor / 配置 + 修复流等只读命令路径，不应为了描述配置而去具体化运行时凭证。 推荐的 `inspectAccount(...)` 行为： @@ -1118,14 +1300,17 @@ api.registerHttpRoute({ - `botTokenSource`、`botTokenStatus` - `appTokenSource`、`appTokenStatus` - `signingSecretSource`、`signingSecretStatus` -- 你不需要为了报告只读可用性而返回原始令牌值。返回 `tokenStatus: "available"`（以及匹配的 source 字段）就足以支持状态类命令。 -- 当某个凭证通过 SecretRef 配置，但在当前命令路径中不可用时，请使用 `configured_unavailable`。 +- 你不需要返回原始 token 值来报告只读 + 可用性。返回 `tokenStatus: "available"`（以及匹配的 source 字段）就足以满足状态类命令。 +- 当某个凭证通过 SecretRef 配置，但在当前命令路径中不可用时， + 使用 `configured_unavailable`。 -这样，只读命令就可以报告“已配置，但在当前命令路径中不可用”，而不是崩溃或误报该账户未配置。 +这样，只读命令就能报告“已配置，但在此命令路径中不可用”， +而不是崩溃或错误地将该账户报告为未配置。 -## 包 pack +## 包集合 -插件目录可以包含一个带有 `openclaw.extensions` 的 `package.json`： +一个插件目录可以包含带有 `openclaw.extensions` 的 `package.json`： ```json { @@ -1137,48 +1322,63 @@ api.registerHttpRoute({ } ``` -每个条目都会变成一个插件。如果 pack 列出了多个扩展，插件 id -将变为 `name/`。 +每个条目都会成为一个插件。如果该包列出多个扩展，插件 id +就会变成 `name/`。 -如果你的插件导入了 npm 依赖，请在该目录中安装它们，以便 -`node_modules` 可用（`npm install` / `pnpm install`）。 +如果你的插件导入了 npm 依赖，请在该目录中安装它们， +以确保 `node_modules` 可用（`npm install` / `pnpm install`）。 -安全护栏：每个 `openclaw.extensions` 条目在解析符号链接后都必须保留在插件目录内。任何逃出包目录的条目都会被拒绝。 +安全护栏：每个 `openclaw.extensions` 条目在解析 symlink 后都必须 +保留在插件目录内。逃出包目录的条目 +会被拒绝。 -安全说明：`openclaw plugins install` 会使用 -`npm install --omit=dev --ignore-scripts` 安装插件依赖（无 lifecycle scripts，运行时无 dev dependencies）。请保持插件依赖树为“纯 JS / TS”，并避免需要 `postinstall` 构建的包。 +安全说明：`openclaw plugins install` 会通过 +`npm install --omit=dev --ignore-scripts` 安装插件依赖（运行时不执行生命周期脚本，也不安装 dev dependencies）。请保持插件依赖树为“纯 JS / TS”，并避免依赖需要 +`postinstall` 构建的包。 -可选：`openclaw.setupEntry` 可以指向一个轻量级、仅设置用的模块。 -当 OpenClaw 需要为一个已禁用渠道插件提供设置接口，或者 -当渠道插件已启用但仍未配置时，它会加载 `setupEntry`， -而不是完整插件入口。这样在你的主插件入口还会接线工具、钩子或其他仅运行时代码时，可以让启动和设置更轻量。 +可选：`openclaw.setupEntry` 可以指向一个轻量级、仅用于设置的模块。 +当 OpenClaw 需要为已禁用渠道插件提供设置接口，或 +当某个渠道插件已启用但尚未配置时，它会加载 `setupEntry` +而不是完整插件入口。这样可以在主插件入口还会接入工具、 +hooks 或其他仅运行时代码时，让启动和设置过程更轻量。 可选：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -可以让渠道插件在 Gateway 网关监听前的启动阶段，也改走同一个 `setupEntry` 路径，即使该渠道已经配置完成。 +可以让渠道插件在 Gateway 网关预监听启动阶段也走同样的 `setupEntry` 路径， +即使该渠道已经完成配置也是如此。 -仅当 `setupEntry` 完全覆盖了启动前必须存在的接口时才应使用此选项。实际来说，这意味着 setup entry -必须注册启动所依赖的每一种渠道自有能力，例如： +仅当 `setupEntry` 完全覆盖了网关开始监听前 +必须存在的启动接口时，才使用此选项。实践中，这意味着设置入口 +必须注册启动阶段所依赖的每个渠道自有能力，例如： - 渠道注册本身 -- 在 Gateway 网关开始监听前必须可用的任何 HTTP 路由 -- 在同一窗口期内必须存在的任何网关方法、工具或服务 +- 任何必须在 Gateway 网关开始监听前就可用的 HTTP 路由 +- 任何在同一窗口期必须存在的 gateway 方法、工具或服务 -如果你的完整入口仍拥有任何必需的启动能力，就不要启用这个标志。保持插件的默认行为，让 OpenClaw 在启动期间加载完整入口。 +如果你的完整入口仍拥有任何必需的启动能力，请不要启用 +该标志。保持插件使用默认行为，让 OpenClaw 在启动期间加载 +完整入口。 -内置渠道还可以发布仅设置用途的契约接口辅助函数，以便核心在完整渠道运行时加载前进行查询。当前的设置提升接口为： +内置渠道还可以发布仅设置用途的契约接口辅助函数，供 core +在完整渠道运行时尚未加载前进行查询。当前的设置提升接口是： - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -当核心需要在不加载完整插件入口的情况下，将遗留单账户渠道配置提升到 `channels..accounts.*` 时，会使用该接口。Matrix 是当前的内置示例：当已存在命名账户时，它只会将认证 / bootstrap 键移动到一个已命名的提升账户中，并且它可以保留一个已配置的非规范 default-account 键，而不是总是创建 -`accounts.default`。 +当 core 需要在不加载完整插件入口的情况下，将遗留的单账户渠道 +配置提升到 `channels..accounts.*` 时，就会使用该接口。 +Matrix 是当前的内置示例：当命名账户已存在时，它只会将 auth / bootstrap 键 +迁移到一个命名提升账户中，并且可以保留一个已配置的非规范默认账户键， +而不总是创建 `accounts.default`。 -这些设置补丁适配器可使内置契约接口发现保持惰性。导入时间因此保持轻量；该提升接口仅在首次使用时加载，而不会在模块导入时重新进入内置渠道启动流程。 +这些设置补丁适配器让内置契约接口发现保持懒加载。 +导入时开销保持很轻；提升接口只会在首次使用时加载， +而不会在模块导入时重新进入内置渠道启动流程。 -当这些启动接口包含 Gateway 网关 RPC 方法时，请将其保留在 -插件专属前缀之下。核心管理命名空间（`config.*`、 -`exec.approvals.*`、`wizard.*`、`update.*`）始终保留，并且即使某个插件请求更窄作用域，它们也始终解析为 `operator.admin`。 +当这些启动接口包含 gateway RPC 方法时，请将它们保留在 +插件特定前缀下。Core 管理命名空间（`config.*`、 +`exec.approvals.*`、`wizard.*`、`update.*`）始终是保留的，并且总会解析为 +`operator.admin`，即使某个插件请求了更窄的作用域也是如此。 示例： @@ -1197,7 +1397,8 @@ api.registerHttpRoute({ ### 渠道目录元数据 -渠道插件可以通过 `openclaw.channel` 声明设置 / 发现元数据，并通过 `openclaw.install` 提供安装提示。这样可以让核心目录保持无数据化。 +渠道插件可以通过 `openclaw.channel` 声明设置 / 发现元数据，并通过 +`openclaw.install` 声明安装提示。这样可以让 core 目录保持无数据状态。 示例： @@ -1225,37 +1426,41 @@ api.registerHttpRoute({ } ``` -除了最小示例之外，有用的 `openclaw.channel` 字段还包括： +除最小示例之外，一些有用的 `openclaw.channel` 字段还包括： -- `detailLabel`：用于更丰富目录 / 状态接口的次级标签 -- `docsLabel`：覆盖文档链接的链接文本 -- `preferOver`：此目录条目应优先于的低优先级插件 / 渠道 id -- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择界面文案控制 -- `markdownCapable`：将该渠道标记为支持 markdown，以用于出站格式决策 -- `exposure.configured`：设置为 `false` 时，在已配置渠道列表接口中隐藏该渠道 -- `exposure.setup`：设置为 `false` 时，在交互式设置 / 配置选择器中隐藏该渠道 -- `exposure.docs`：将该渠道标记为内部 / 私有，以用于文档导航接口 -- `showConfigured` / `showInSetup`：遗留别名，出于兼容性仍被接受；优先使用 `exposure` -- `quickstartAllowFrom`：让渠道接入标准快速开始 `allowFrom` 流程 +- `detailLabel`：更丰富目录 / 状态接口中的次级标签 +- `docsLabel`：覆盖文档链接文本 +- `preferOver`：该目录项应优先于的低优先级插件 / 渠道 id +- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择界面的文案控制 +- `markdownCapable`：将该渠道标记为支持 markdown，以便做 outbound 格式决策 +- `exposure.configured`：设为 `false` 时，在已配置渠道列表接口中隐藏该渠道 +- `exposure.setup`：设为 `false` 时，在交互式设置 / 配置选择器中隐藏该渠道 +- `exposure.docs`：在文档导航接口中将该渠道标记为内部 / 私有 +- `showConfigured` / `showInSetup`：遗留别名，出于兼容性仍接受；推荐使用 `exposure` +- `quickstartAllowFrom`：让该渠道加入标准快速开始 `allowFrom` 流程 - `forceAccountBinding`：即使只存在一个账户，也要求显式账户绑定 - `preferSessionLookupForAnnounceTarget`：在解析 announce 目标时优先使用会话查找 -OpenClaw 还可以合并**外部渠道目录**（例如 MPM -注册表导出）。可将 JSON 文件放在以下任一位置： +OpenClaw 还可以合并**外部渠道目录**（例如某个 MPM +注册表导出）。将一个 JSON 文件放到以下任一路径： - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（以逗号 / 分号 / `PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的遗留别名。 +或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向 +一个或多个 JSON 文件（使用逗号 / 分号 / `PATH` 分隔）。每个文件应 +包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的遗留别名。 ## 上下文引擎插件 -上下文引擎插件拥有会话上下文编排，用于摄取、组装和压缩。可通过 -`api.registerContextEngine(id, factory)` 从你的插件中注册它们，然后通过 +上下文引擎插件拥有会话上下文的编排逻辑，包括摄取、组装 +和压缩。你可以在插件中通过 +`api.registerContextEngine(id, factory)` 注册它们，然后通过 `plugins.slots.contextEngine` 选择活动引擎。 -当你的插件需要替换或扩展默认上下文流水线，而不仅仅是增加 memory 搜索或钩子时，请使用此方式。 +当你的插件需要替换或扩展默认上下文 +流水线，而不只是添加 memory 搜索或 hooks 时，请使用此方式。 ```ts export default function (api) { @@ -1275,7 +1480,7 @@ export default function (api) { ``` 如果你的引擎**不**拥有压缩算法，请保持 `compact()` -已实现，并显式委托给它： +实现存在，并显式委托： ```ts import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core"; @@ -1302,53 +1507,59 @@ export default function (api) { ## 添加新能力 -当插件需要当前 API 无法覆盖的行为时，不要通过私有深入访问来绕过插件系统。请添加缺失的能力。 +当某个插件需要当前 API 无法容纳的行为时，不要通过私有内部访问 +绕过插件系统。应添加缺失的能力。 推荐顺序： -1. 定义核心契约 - 确定核心应拥有哪些共享行为：策略、回退、配置合并、 +1. 定义 core 契约 + 明确 core 应拥有哪些共享行为：策略、回退、配置合并、 生命周期、面向渠道的语义，以及运行时辅助函数形态。 -2. 添加类型化插件注册 / 运行时接口 - 以最小但有用的类型化能力接口扩展 `OpenClawPluginApi` 和 / 或 `api.runtime`。 -3. 接线核心 + 渠道 / 功能消费者 - 渠道和功能插件应通过核心消费新能力， +2. 添加类型化的插件注册 / 运行时接口 + 使用最小但有用的 + 类型化能力接口扩展 `OpenClawPluginApi` 和 / 或 `api.runtime`。 +3. 接入 core + 渠道 / 功能消费者 + 渠道和功能插件应通过 core 消费新能力， 而不是直接导入某个厂商实现。 4. 注册厂商实现 - 然后由厂商插件针对该能力注册其后端。 + 然后由厂商插件将其后端注册到该能力上。 5. 添加契约覆盖 - 添加测试，使归属和注册形态在长期内保持明确。 + 添加测试，使归属关系和注册形态始终保持明确。 -这正是 OpenClaw 能保持有主张、却不会被硬编码到某个提供商世界观中的方式。具体文件清单和完整示例，请参见[能力扩展手册](/zh-CN/plugins/architecture)。 +这就是 OpenClaw 在保持鲜明主张的同时，不会被某个 +提供商的世界观硬编码束缚的方式。请参阅 [能力扩展手册](/zh-CN/plugins/architecture) +了解具体文件清单和完整示例。 ### 能力清单 -当你添加一个新能力时，通常应该同时触及以下接口： +当你添加一个新能力时，实现通常应同时涉及以下 +接口： -- `src//types.ts` 中的核心契约类型 -- `src//runtime.ts` 中的核心运行器 / 运行时辅助函数 +- `src//types.ts` 中的 core 契约类型 +- `src//runtime.ts` 中的 core runner / 运行时辅助函数 - `src/plugins/types.ts` 中的插件 API 注册接口 - `src/plugins/registry.ts` 中的插件注册表接线 -- 当功能 / 渠道插件需要消费该能力时，位于 `src/plugins/runtime/*` 中的插件运行时暴露 +- 当功能 / 渠道插件需要消费该能力时，位于 `src/plugins/runtime/*` 中的插件运行时暴露接口 - `src/test-utils/plugin-registration.ts` 中的捕获 / 测试辅助函数 - `src/plugins/contracts/registry.ts` 中的归属 / 契约断言 -- `docs/` 中面向操作员 / 插件的文档 +- `docs/` 中面向运维人员 / 插件作者的文档 -如果这些接口中缺少某一项，通常说明该能力尚未完全集成。 +如果其中某个接口缺失，这通常意味着该能力 +尚未被完整集成。 ### 能力模板 最小模式： ```ts -// core contract +// core 契约 export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// plugin API +// 插件 API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1357,7 +1568,7 @@ api.registerVideoGenerationProvider({ }, }); -// shared runtime helper for feature/channel plugins +// 面向功能 / 渠道插件的共享运行时辅助函数 const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -1372,7 +1583,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); 这样规则就很简单： -- 核心拥有能力契约 + 编排 +- core 拥有能力契约 + 编排 - 厂商插件拥有厂商实现 - 功能 / 渠道插件消费运行时辅助函数 -- 契约测试使归属保持明确 +- 契约测试使归属关系保持明确 diff --git a/docs/zh-CN/plugins/building-plugins.md b/docs/zh-CN/plugins/building-plugins.md index 5c46ccec7..3cd368f8a 100644 --- a/docs/zh-CN/plugins/building-plugins.md +++ b/docs/zh-CN/plugins/building-plugins.md @@ -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 ` 安装。OpenClaw 会先尝试 ClawHub，并在需要时自动回退到 npm。 +你不需要将你的插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，用户即可使用 `openclaw plugins install ` 安装。OpenClaw 会先尝试 ClawHub，并自动回退到 npm。 -## 前置条件 +## 先决条件 -- Node >= 22，以及一个包管理器（npm 或 pnpm） +- Node >= 22 和一个包管理器（npm 或 pnpm） - 熟悉 TypeScript（ESM） - 对于仓库内插件：已克隆仓库并完成 `pnpm install` -## 这是什么类型的插件？ +## 哪种类型的插件？ - 将 OpenClaw 连接到消息平台（Discord、IRC 等） + 将 OpenClaw 连接到一个消息平台（Discord、IRC 等） - 添加模型提供商（LLM、代理或自定义端点） + 添加一个模型提供商（LLM、代理或自定义端点） - - 注册智能体工具、事件 hooks 或服务 —— 继续阅读下文 + + 注册智能体工具、事件钩子或服务 — 继续阅读下文 -如果某个渠道插件是可选的，并且在新手引导 / 设置运行时可能尚未安装，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装完成前对实际配置写入采取失败关闭策略。 +如果某个渠道插件是可选的，并且在运行 onboarding/设置 时可能尚未安装，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导 组合，用于提示安装要求，并在插件安装完成之前，对实际配置写入采取默认拒绝策略。 ## 快速开始：工具插件 -本演练将创建一个最小插件，用于注册一个智能体工具。渠道插件和提供商插件有上方链接的专用指南。 +本演练将创建一个用于注册智能体工具的最小插件。渠道插件和提供商插件有上方链接的专门指南。 @@ -82,7 +82,7 @@ x-i18n: ``` - 每个插件都需要一个清单，即使没有配置也一样。完整模式请参见 [Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub 发布代码片段位于 `docs/snippets/plugin-publish/`。 + 每个插件都需要一个清单，即使没有配置也是如此。完整 schema 请参见 [Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub 发布片段位于 `docs/snippets/plugin-publish/`。 @@ -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)。 @@ -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/` 路径导入： +始终从精确的 `openclaw/plugin-sdk/` 路径导入： ```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/` 辅助扩展点仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。应将这些视为保留接口，而不是新第三方插件的默认模式。 +一些生成的 `openclaw/plugin-sdk/` 辅助接口仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。请将这些视为保留接口，而不是新第三方插件的默认模式。 ## 提交前检查清单 **package.json** 具有正确的 `openclaw` 元数据 **openclaw.plugin.json** 清单已存在且有效 入口点使用 `defineChannelPluginEntry` 或 `definePluginEntry` -所有导入都使用聚焦的 `plugin-sdk/` 路径 +所有导入都使用精确的 `plugin-sdk/` 路径 内部导入使用本地模块，而不是 SDK 自导入 测试通过（`pnpm test -- /my-plugin/`） `pnpm 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: - ` 的 issue，并添加 `beta-blocker` 标签。把该 issue 链接发到你的线程中。 -5. 向 `main` 提交一个标题为 `fix(): beta blocker - ` 的 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: - ` 的 issue，并添加 `beta-blocker` 标签。将该 issue 链接贴到你的主题中。 +5. 向 `main` 提交一个标题为 `fix(): beta blocker - ` 的 PR，并在 PR 和你的 Discord 主题中都关联该 issue。贡献者不能为 PR 添加标签，因此标题就是给维护者和自动化系统的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题可能仍然会随版本发布。维护者会在 Beta 测试期间关注这些主题。 +6. 没有消息就表示一切正常。如果你错过了这个窗口，你的修复很可能会落到下一个周期。 ## 后续步骤 - 构建消息渠道插件 + 构建一个消息渠道插件 - 构建模型提供商插件 + 构建一个模型提供商插件 - 导入映射与注册 API 参考 + 导入映射和注册 API 参考 通过 api.runtime 使用 TTS、搜索、子智能体 @@ -284,14 +285,14 @@ import { ... } from "openclaw/plugin-sdk"; 测试工具和模式 - 完整清单模式参考 + 完整清单 schema 参考 ## 相关内容 -- [插件架构](/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) — 构建提供商插件 diff --git a/docs/zh-CN/plugins/manifest.md b/docs/zh-CN/plugins/manifest.md index feae688a8..df3b04306 100644 --- a/docs/zh-CN/plugins/manifest.md +++ b/docs/zh-CN/plugins/manifest.md @@ -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。 | -| `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` | 无需加载插件代码即可由 OpenClaw 检查的轻量提供商凭证环境变量元数据。 | -| `providerAuthChoices` | 否 | `object[]` | 供新手引导选择器、首选提供商解析和简单 CLI flag 接线使用的轻量凭证选项元数据。 | -| `contracts` | 否 | `object` | 用于语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、Web 搜索 和工具归属的静态内置能力快照。 | -| `channelConfigs` | 否 | `Record` | 由清单拥有的渠道配置元数据，在运行时加载前合并到发现和校验表面中。 | -| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | -| `name` | 否 | `string` | 人类可读的插件名称。 | -| `description` | 否 | `string` | 在插件相关表面中显示的简短摘要。 | -| `version` | 否 | `string` | 信息性插件版本。 | -| `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | +| 字段 | 必填 | 类型 | 含义 | +| ----------------------------------- | -------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.` 中使用的 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` | OpenClaw 无需加载插件代码即可检查的轻量级提供商认证环境变量元数据。 | +| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的轻量级认证选项元数据。 | +| `contracts` | 否 | `object` | 用于语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 | +| `channelConfigs` | 否 | `Record` | 在运行时加载前，合并到设备发现和校验表面的由清单拥有的渠道配置元数据。 | +| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | +| `name` | 否 | `string` | 人类可读的插件名称。 | +| `description` | 否 | `string` | 显示在插件表面中的简短摘要。 | +| `version` | 否 | `string` | 信息性插件版本。 | +| `uiHints` | 否 | `Record` | 用于配置字段的 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 `。 | -| `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 `。 | +| `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.` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 | -| `uiHints` | `Record` | 该渠道配置部分可选的 UI 标签 / 占位符 / 敏感性提示。 | -| `label` | `string` | 当运行时元数据尚未准备好时，合并到选择器和检查表面中的渠道标签。 | -| `description` | `string` | 用于检查和目录表面的简短渠道描述。 | -| `preferOver` | `string[]` | 在选择表面中，此渠道应优先于的旧版或较低优先级插件 id。 | +| 字段 | 类型 | 含义 | +| ------------- | ------------------------ | ------------------------------------------------------------------------------------ | +| `schema` | `object` | `channels.` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 | +| `uiHints` | `Record` | 该渠道配置部分的可选 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.` 条目。无关的配置错误仍会阻止安装，并引导操作员使用 `openclaw doctor --fix`。 +`openclaw.install.allowInvalidConfigRecovery` 的设计范围刻意很窄。它不会让任意损坏的配置变得可安装。目前，它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一个内置插件对应的陈旧 `channels.` 条目。无关的配置错误仍会阻止安装，并将操作人员引导到 `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.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。 +- 未知的 `channels.*` 键是**错误**，除非该渠道 id 由某个插件清单声明。 +- `plugins.entries.`、`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 `）。 ## 相关内容 - [构建插件](/zh-CN/plugins/building-plugins) — 插件快速开始 - [插件架构](/zh-CN/plugins/architecture) — 内部架构 -- [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考 +- [插件 SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考 diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 87af5c159..40a98ca64 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -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`** —— 一个桥接层，使插件能够直接访问宿主侧辅助函数，例如嵌入式智能体运行器。 -这两个表面现已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 +这两个接口现在都已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 - 向后兼容层将在未来的主版本中移除。 - 到那时，仍从这些表面导入的插件将会失效。 + 向后兼容层将在未来的某个主版本中移除。 + 到那时，仍然从这些接口导入内容的插件将会失效。 ## 为什么会有这个变化 -旧方法会带来以下问题： +旧方法会导致一些问题： -- **启动缓慢** — 导入一个辅助工具就会加载数十个无关模块 -- **循环依赖** — 宽泛的重新导出让导入环更容易出现 -- **API 表面不清晰** — 无法判断哪些导出是稳定的，哪些属于内部实现 +- **启动缓慢** —— 导入一个辅助函数会加载数十个无关模块 +- **循环依赖** —— 宽泛的重新导出使导入环路更容易出现 +- **API 接口不清晰** —— 无法区分哪些导出是稳定的，哪些属于内部实现 -现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有明确用途和文档化契约。 +现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，拥有明确用途和文档化契约。 -面向内置渠道的旧版 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` 中 ## 如何迁移 - 如果你的插件使用 `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`，而应改为处理抛出的错误。 - 在你的插件中搜索来自这两个已弃用表面的导入： + 在你的插件中搜索来自这两个已弃用接口的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -89,7 +86,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 - 旧表面中的每个导出，都映射到一个特定的现代导入路径： + 旧接口中的每个导出都对应一个特定的现代导入路径： ```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 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | - | `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 | -此表刻意只列出常见迁移子集，而不是完整的 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 参考 diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index 5e432ad3b..a03215031 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -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 是插件与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考。 - **在找操作指南？** - - 第一个插件？从 [入门指南](/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) ## 导入约定 @@ -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` | 反馈/表情反应接线 | @@ -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 辅助函数 | - + | 子路径 | 关键导出 | | --- | --- | - | `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"; | 子路径 | 关键导出 | | --- | --- | - | `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"; | 子路径 | 关键导出 | | --- | --- | - | `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` | | 子路径 | 关键导出 | | --- | --- | - | `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 辅助接口 | - | 系列 | 当前子路径 | 预期用途 | + | 家族 | 当前子路径 | 预期用途 | | --- | --- | --- | - | 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` | ## 注册 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` | 来自 `plugins.entries..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` | 来自 `plugins.entries..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 # 轻量级仅设置入口（可选） ``` 不要在生产代码中通过 `openclaw/plugin-sdk/` 导入你自己的插件。 - 应通过 `./api.ts` 或 `./runtime-api.ts` 进行内部导入。SDK 路径仅是外部契约。 + 内部导入应通过 `./api.ts` 或 `./runtime-api.ts`。SDK 路径仅是对外契约。 -门面加载的内置插件公共表面（`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` 导出提供商构建器以及 + 新手引导/配置辅助函数 - 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。 - 如果某个辅助函数确实需要共享，应将其提升到中立的 SDK 子路径，例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他面向能力的表面，而不是让两个插件彼此耦合。 + 扩展生产代码同样应避免使用 `openclaw/plugin-sdk/` + 导入。如果某个辅助函数确实需要共享，请将它提升到中立的 SDK 子路径， + 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他 + 面向能力的接口，而不是让两个插件彼此耦合。 ## 相关内容 - [入口点](/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) — 深入架构和能力模型 diff --git a/docs/zh-CN/providers/google.md b/docs/zh-CN/providers/google.md index 1172b7a98..63ea7778f 100644 --- a/docs/zh-CN/providers/google.md +++ b/docs/zh-CN/providers/google.md @@ -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` 提供）。 diff --git a/docs/zh-CN/providers/index.md b/docs/zh-CN/providers/index.md index 5173b37d0..6b2275aea 100644 --- a/docs/zh-CN/providers/index.md +++ b/docs/zh-CN/providers/index.md @@ -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)。 diff --git a/docs/zh-CN/providers/minimax.md b/docs/zh-CN/providers/minimax.md index 94815617a..7e60c9ae4 100644 --- a/docs/zh-CN/providers/minimax.md +++ b/docs/zh-CN/providers/minimax.md @@ -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/` - 默认聊天模型：`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 diff --git a/docs/zh-CN/tools/index.md b/docs/zh-CN/tools/index.md index 1f2ab856c..96f125022 100644 --- a/docs/zh-CN/tools/index.md +++ b/docs/zh-CN/tools/index.md @@ -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 有三个协同工作的层级： - 工具是智能体可以调用的类型化函数（例如 `exec`、`browser`、 - `web_search`、`message`）。OpenClaw 内置了一组**内置工具**，插件也可以注册额外工具。 + 工具是智能体可调用的类型化函数（例如 `exec`、`browser`、 + `web_search`、`message`）。OpenClaw 随附一组**内置工具**，插件也可以注册额外工具。 - 对智能体来说，工具是发送到模型 API 的结构化函数定义。 + 智能体看到的工具，是发送到模型 API 的结构化函数定义。 - Skills 是注入系统提示词中的 Markdown 文件（`SKILL.md`）。 - Skills 为智能体提供上下文、约束，以及高效使用工具的分步指导。Skills 可以位于你的工作区、共享文件夹中，或随插件一起提供。 + Skills 是注入到系统提示中的 Markdown 文件（`SKILL.md`）。 + Skills 为智能体提供上下文、约束以及使用工具的分步指导。 + Skills 可以位于你的工作区、共享文件夹中，或随插件一起提供。 [Skills 参考](/zh-CN/tools/skills) | [创建 Skills](/zh-CN/tools/creating-skills) - 插件是一种可注册任意能力组合的软件包： - 渠道、模型提供商、工具、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 文本中剥离思维标签、`` 脚手架、纯文本工具调用 XML 载荷（包括 `...`、 +`sessions_history` 返回一个有界的、经过安全过滤的回忆视图。它会从助手文本中移除思考标签、`` 脚手架、纯文本工具调用 XML +负载（包括 `...`、 `...`、`...`、 `...` 以及被截断的工具调用块）、 -降级后的工具调用脚手架、泄露的 ASCII/全角模型控制 token， -以及格式错误的 MiniMax 工具调用 XML，然后再应用 -脱敏/截断，并在需要时使用超大行占位符，而不是 -直接充当原始转录转储。 +降级后的工具调用脚手架、泄露的 ASCII/全角模型控制 +token，以及格式错误的 MiniMax 工具调用 XML，然后再应用脱敏/截断，并在必要时使用超大行占位符，而不是充当原始转录转储。 ### 提供商专属限制 diff --git a/docs/zh-CN/tools/music-generation.md b/docs/zh-CN/tools/music-generation.md index d0716d18a..7b5614c44 100644 --- a/docs/zh-CN/tools/music-generation.md +++ b/docs/zh-CN/tools/music-generation.md @@ -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 会将音乐生成作为后台任务启动，在任务账本中跟踪它，然后在音轨准备就绪后再次唤醒智能体，以便智能体将完成的音频发回原始渠道。 + + +只有在至少有一个音乐生成提供商可用时，内置共享工具才会显示。如果你在智能体工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。 + + + +插件提供的 `music_generate` 实现可能暴露不同的参数或运行时行为。下方的异步任务/状态流程适用于内置的共享提供商支持路径。 + ## 快速开始 +### 共享提供商支持的生成 + +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 ` 检查生成任务的排队中、运行中和终态状态。 +- 完成唤醒：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) diff --git a/docs/zh-CN/tools/plugin.md b/docs/zh-CN/tools/plugin.md index 2e8115dbe..185075a2d 100644 --- a/docs/zh-CN/tools/plugin.md +++ b/docs/zh-CN/tools/plugin.md @@ -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: ```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.\.config` 进行配置。 + 然后在你的配置文件中，通过 `plugins.entries.\.config` 进行配置。 -如果你更喜欢在聊天中原生控制，请启用 `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:`，或裸包规范（先尝试 ClawHub，再回退到 npm）。 +安装路径使用与 CLI 相同的解析器：本地路径 / 归档文件、显式 `clawhub:`，或裸包规范（先 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 一起提供） - - `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` + + `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` - - - `memory-core` — 内置内存搜索（通过 `plugins.slots.memory` 默认启用） - - `memory-lancedb` — 按需安装的长期记忆，带自动 recall/capture（设置 `plugins.slots.memory = "memory-lancedb"`） + + - `memory-core` — 内置内存搜索（默认通过 `plugins.slots.memory`） + - `memory-lancedb` — 按需安装的长期记忆，带自动召回 / 捕获（设置 `plugins.slots.memory = "memory-lancedb"`） - - `elevenlabs`、`microsoft` + + `elevenlabs`, `microsoft` - - `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 桥接（默认禁用） @@ -144,23 +135,21 @@ OpenClaw 可识别两种插件格式： | 字段 | 说明 | | ---------------- | --------------------------------------------------------- | | `enabled` | 主开关（默认：`true`） | -| `allow` | 插件 allowlist（可选） | -| `deny` | 插件 denylist（可选；deny 优先） | -| `load.paths` | 额外插件文件/目录 | -| `slots` | 独占 slot 选择器（例如 `memory`、`contextEngine`） | -| `entries.\` | 每插件开关 + 配置 | +| `allow` | 插件允许列表（可选） | +| `deny` | 插件拒绝列表（可选；拒绝优先） | +| `load.paths` | 额外的插件文件 / 目录 | +| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） | +| `entries.\` | 每个插件的开关 + 配置 | -配置变更**需要重启 Gateway 网关**。如果 Gateway 网关以启用了配置监视 + -进程内重启的方式运行（默认 `openclaw gateway` 路径），那么该 -重启通常会在配置写入后不久自动执行。 +配置更改**需要重启 Gateway 网关**。如果 Gateway 网关以启用配置监视 + 进程内重启的方式运行（默认的 `openclaw gateway` 路径），则通常会在配置写入完成后稍等片刻自动执行该重启。 - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。 - - **缺失**：配置引用了某个插件 id，但设备发现没有找到它。 - - **无效**：插件存在，但其配置与声明的 schema 不匹配。 + - **缺失**：配置引用了一个设备发现未找到的插件 id。 + - **无效**：插件存在，但其配置不符合声明的 schema。 -## 设备发现和优先级 +## 设备发现与优先级 OpenClaw 按以下顺序扫描插件（先匹配者优先）： @@ -178,8 +167,8 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： - 随 OpenClaw 一起提供。许多默认启用（模型 providers、语音）。 - 其他插件则需要显式启用。 + 随 OpenClaw 一起提供。许多默认启用（模型提供商、语音等）。 + 其他则需要显式启用。 @@ -189,35 +178,35 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： - `plugins.deny` 总是优先于 allow - `plugins.entries.\.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 # 深度详情 openclaw plugins inspect --json # 机器可读 @@ -232,12 +221,12 @@ openclaw plugins install # 从本地路径安装 openclaw plugins install -l # 链接（不复制），用于开发 openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # 记录精确解析后的 npm 规范 +openclaw plugins install --pin # 记录精确解析后的 npm spec openclaw plugins install --dangerously-force-unsafe-install openclaw plugins update # 更新单个插件 openclaw plugins update --dangerously-force-unsafe-install openclaw plugins update --all # 更新全部 -openclaw plugins uninstall # 移除配置/安装记录 +openclaw plugins uninstall # 删除配置 / 安装记录 openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -246,47 +235,28 @@ openclaw plugins enable openclaw plugins disable ``` -内置插件随 OpenClaw 一起提供。许多默认启用（例如 -内置模型 providers、内置语音 providers 和内置 browser -插件）。其他内置插件仍需要执行 `openclaw plugins enable `。 +内置插件随 OpenClaw 一起提供。许多默认启用（例如内置模型提供商、内置语音提供商和内置 browser 插件）。其他内置插件仍然需要 `openclaw plugins enable `。 -`--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 ` 还会报告检测到的 bundle 能力，以及 -由 bundle 支持或不支持的 MCP 和 LSP server 条目。 +`openclaw plugins inspect ` 还会报告检测到的 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) — 第三方列表