From d0379c6b3db1906d71020fac07d2a97edae40384 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 09:42:40 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/feishu.md | 114 +++---- docs/zh-CN/plugins/sdk-migration.md | 495 ++++++++++++++-------------- docs/zh-CN/plugins/sdk-subpaths.md | 373 +++++++++++---------- docs/zh-CN/providers/minimax.md | 185 ++++++----- docs/zh-CN/tools/slash-commands.md | 246 +++++++------- docs/zh-CN/tools/tts.md | 191 ++++++----- 6 files changed, 805 insertions(+), 799 deletions(-) diff --git a/docs/zh-CN/channels/feishu.md b/docs/zh-CN/channels/feishu.md index 19ec0db4c..a920c495d 100644 --- a/docs/zh-CN/channels/feishu.md +++ b/docs/zh-CN/channels/feishu.md @@ -5,25 +5,25 @@ read_when: summary: Feishu 机器人概览、功能和配置 title: Feishu x-i18n: - generated_at: "2026-04-25T08:32:00Z" + generated_at: "2026-04-25T09:40:23Z" model: gpt-5.4 provider: openai - source_hash: 5630a1f817a4831e1af75d63594edd4647861c09b5b2cfd32478b2c2aba1b049 + source_hash: 2b9cebcedf05a517b03a15ae306cece1a3c07f772c48c54b7ece05ef892d05d2 source_path: channels/feishu.md workflow: 15 --- # Feishu / Lark -Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共享文档、管理日历并协同完成工作。 +Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共享文档、管理日历，并一起完成工作。 -**Status：** 已可用于生产环境的机器人私信和群聊。WebSocket 是默认模式；webhook 模式为可选。 +**Status：** 机器人私信 + 群聊已可用于生产环境。WebSocket 是默认模式；webhook 模式为可选。 --- ## 快速开始 -> **需要 OpenClaw 2026.4.24 或更高版本。** 运行 `openclaw --version` 进行检查。使用 `openclaw update` 升级。 +> **需要 OpenClaw 2026.4.25 或更高版本。** 运行 `openclaw --version` 进行检查。使用 `openclaw update` 升级。 @@ -62,19 +62,19 @@ openclaw pairing approve feishu ### 群聊 -**群组策略**（`channels.feishu.groupPolicy`）： +**群策略**（`channels.feishu.groupPolicy`）： | 值 | 行为 | | ------------- | ---- | | `"open"` | 响应群组中的所有消息 | | `"allowlist"` | 仅响应 `groupAllowFrom` 中的群组 | -| `"disabled"` | 禁用所有群组消息 | +| `"disabled"` | 禁用所有群消息 | 默认值：`allowlist` **提及要求**（`channels.feishu.requireMention`）： -- `true` — 必须 @ 提及（默认） +- `true` — 需要 @ 提及（默认） - `false` — 无需 @ 提及也会响应 - 按群组覆盖：`channels.feishu.groups..requireMention` @@ -114,7 +114,7 @@ openclaw pairing approve feishu channels: { feishu: { groupPolicy: "allowlist", - // 群组 ID 形如：oc_xxx + // 群组 ID 类似于：oc_xxx groupAllowFrom: ["oc_xxx", "oc_yyy"], }, }, @@ -131,7 +131,7 @@ openclaw pairing approve feishu groupAllowFrom: ["oc_xxx"], groups: { oc_xxx: { - // 用户 open_id 形如：ou_xxx + // 用户 open_id 类似于：ou_xxx allowFrom: ["ou_user1", "ou_user2"], }, }, @@ -144,17 +144,17 @@ openclaw pairing approve feishu -## 获取群组 / 用户 ID +## 获取群组/用户 ID ### 群组 ID（`chat_id`，格式：`oc_xxx`） 在 Feishu/Lark 中打开群组，点击右上角的菜单图标，然后进入**设置**。群组 ID（`chat_id`）会显示在设置页面中。 -![获取群组 ID](/images/feishu-get-group-id.png) +![Get Group ID](/images/feishu-get-group-id.png) ### 用户 ID（`open_id`，格式：`ou_xxx`） -启动 Gateway 网关，向机器人发送一条私信，然后查看日志： +启动 Gateway 网关，向机器人发送一条私信，然后检查日志： ```bash openclaw logs --follow @@ -176,7 +176,7 @@ openclaw pairing list feishu | `/reset` | 重置当前会话 | | `/model` | 显示或切换 AI 模型 | -> Feishu/Lark 不支持原生斜杠命令菜单，因此请将这些命令作为纯文本消息发送。 +> Feishu/Lark 不支持原生斜杠命令菜单，因此请将这些命令作为普通文本消息发送。 --- @@ -184,31 +184,31 @@ openclaw pairing list feishu ### 机器人在群聊中没有响应 -1. 确认机器人已添加到群组 -2. 确认你已 @ 提及机器人（默认要求） +1. 确保机器人已加入群组 +2. 确保你已 @ 提及机器人（默认需要） 3. 验证 `groupPolicy` 不是 `"disabled"` 4. 检查日志：`openclaw logs --follow` -### 机器人未接收到消息 +### 机器人没有收到消息 -1. 确认机器人已在 Feishu Open Platform / Lark Developer 中发布并获批 -2. 确认事件订阅包含 `im.message.receive_v1` -3. 确认已选择**长连接**（WebSocket） -4. 确认已授予所有必需的权限范围 -5. 确认 Gateway 网关正在运行：`openclaw gateway status` +1. 确保机器人已在 Feishu Open Platform / Lark Developer 中发布并获批 +2. 确保事件订阅包含 `im.message.receive_v1` +3. 确保已选择**持久连接**（WebSocket） +4. 确保已授予所有必需的权限范围 +5. 确保 Gateway 网关正在运行：`openclaw gateway status` 6. 检查日志：`openclaw logs --follow` ### App Secret 泄露 1. 在 Feishu Open Platform / Lark Developer 中重置 App Secret -2. 更新你配置中的值 +2. 更新你的配置中的对应值 3. 重启 Gateway 网关：`openclaw gateway restart` --- ## 高级配置 -### 多账号 +### 多账户 ```json5 { @@ -233,12 +233,12 @@ openclaw pairing list feishu } ``` -`defaultAccount` 用于控制当出站 API 未指定 `accountId` 时使用哪个账号。 +`defaultAccount` 控制在出站 API 未指定 `accountId` 时使用哪个账户。 ### 消息限制 - `textChunkLimit` — 出站文本分块大小（默认：`2000` 个字符） -- `mediaMaxMb` — 媒体上传 / 下载限制（默认：`30` MB） +- `mediaMaxMb` — 媒体上传/下载限制（默认：`30` MB） ### 流式传输 @@ -249,20 +249,20 @@ Feishu/Lark 通过交互式卡片支持流式回复。启用后，机器人会 channels: { feishu: { streaming: true, // 启用流式卡片输出（默认：true） - blockStreaming: true, // 启用分块流式传输（默认：true） + blockStreaming: true, // 启用块级分块流式传输（默认：true） }, }, } ``` -将 `streaming: false` 设置为一次性发送完整回复。 +设置 `streaming: false` 可将完整回复作为一条消息发送。 ### 配额优化 使用两个可选标志来减少 Feishu/Lark API 调用次数： -- `typingIndicator`（默认 `true`）：设置为 `false` 可跳过正在输入的反应调用 -- `resolveSenderNames`（默认 `true`）：设置为 `false` 可跳过发送者资料查询 +- `typingIndicator`（默认 `true`）：设置为 `false` 以跳过“正在输入”反应调用 +- `resolveSenderNames`（默认 `true`）：设置为 `false` 以跳过发送者资料查询 ```json5 { @@ -277,7 +277,7 @@ Feishu/Lark 通过交互式卡片支持流式回复。启用后，机器人会 ### ACP 会话 -Feishu/Lark 支持在私信和群组话题消息中使用 ACP。Feishu/Lark ACP 由文本命令驱动——没有原生斜杠命令菜单，因此请直接在对话中使用 `/acp ...` 消息。 +Feishu/Lark 支持用于私信和群线程消息的 ACP。Feishu/Lark ACP 由文本命令驱动——没有原生斜杠命令菜单，因此请直接在对话中使用 `/acp ...` 消息。 #### 持久 ACP 绑定 @@ -325,13 +325,13 @@ Feishu/Lark 支持在私信和群组话题消息中使用 ACP。Feishu/Lark ACP #### 从聊天中启动 ACP -在 Feishu/Lark 私信或话题中： +在 Feishu/Lark 私信或线程中： ```text /acp spawn codex --thread here ``` -`--thread here` 适用于私信和 Feishu/Lark 话题消息。随后在已绑定对话中的后续消息会直接路由到该 ACP 会话。 +`--thread here` 适用于私信和 Feishu/Lark 线程消息。绑定对话中的后续消息会直接路由到该 ACP 会话。 ### 多智能体路由 @@ -371,40 +371,40 @@ Feishu/Lark 支持在私信和群组话题消息中使用 ACP。Feishu/Lark ACP - `match.peer.kind`：`"direct"`（私信）或 `"group"`（群聊） - `match.peer.id`：用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`） -有关查找方法，请参阅[获取群组 / 用户 ID](#get-groupuser-ids)。 +查找提示请参见[获取群组/用户 ID](#get-groupuser-ids)。 --- ## 配置参考 -完整配置：[Gateway 网关配置](/zh-CN/gateway/configuration) +完整配置：[Gateway configuration](/zh-CN/gateway/configuration) | 设置 | 说明 | 默认值 | | ------------------------------------------------- | ------------------------------------------ | ---------------- | -| `channels.feishu.enabled` | 启用 / 禁用该渠道 | `true` | -| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` | +| `channels.feishu.enabled` | 启用/禁用该渠道 | `true` | +| `channels.feishu.domain` | API 域（`feishu` 或 `lark`） | `feishu` | | `channels.feishu.connectionMode` | 事件传输方式（`websocket` 或 `webhook`） | `websocket` | -| `channels.feishu.defaultAccount` | 出站路由的默认账号 | `default` | +| `channels.feishu.defaultAccount` | 出站路由的默认账户 | `default` | | `channels.feishu.verificationToken` | webhook 模式必需 | — | | `channels.feishu.encryptKey` | webhook 模式必需 | — | -| `channels.feishu.webhookPath` | Webhook 路由路径 | `/feishu/events` | -| `channels.feishu.webhookHost` | Webhook 绑定主机 | `127.0.0.1` | -| `channels.feishu.webhookPort` | Webhook 绑定端口 | `3000` | +| `channels.feishu.webhookPath` | webhook 路由路径 | `/feishu/events` | +| `channels.feishu.webhookHost` | webhook 绑定主机 | `127.0.0.1` | +| `channels.feishu.webhookPort` | webhook 绑定端口 | `3000` | | `channels.feishu.accounts..appId` | App ID | — | | `channels.feishu.accounts..appSecret` | App Secret | — | -| `channels.feishu.accounts..domain` | 按账号覆盖的域名 | `feishu` | +| `channels.feishu.accounts..domain` | 每账户域覆盖 | `feishu` | | `channels.feishu.dmPolicy` | 私信策略 | `allowlist` | | `channels.feishu.allowFrom` | 私信允许列表（`open_id` 列表） | [BotOwnerId] | -| `channels.feishu.groupPolicy` | 群组策略 | `allowlist` | -| `channels.feishu.groupAllowFrom` | 群组允许列表 | — | -| `channels.feishu.requireMention` | 在群组中要求 @ 提及 | `true` | -| `channels.feishu.groups..requireMention` | 按群组覆盖 @ 提及要求 | inherited | -| `channels.feishu.groups..enabled` | 启用 / 禁用特定群组 | `true` | +| `channels.feishu.groupPolicy` | 群策略 | `allowlist` | +| `channels.feishu.groupAllowFrom` | 群允许列表 | — | +| `channels.feishu.requireMention` | 群中需要 @ 提及 | `true` | +| `channels.feishu.groups..requireMention` | 每群 @ 提及覆盖 | 继承 | +| `channels.feishu.groups..enabled` | 启用/禁用特定群组 | `true` | | `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` | | `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` | | `channels.feishu.streaming` | 流式卡片输出 | `true` | | `channels.feishu.blockStreaming` | 分块流式传输 | `true` | -| `channels.feishu.typingIndicator` | 发送正在输入反应 | `true` | +| `channels.feishu.typingIndicator` | 发送“正在输入”反应 | `true` | | `channels.feishu.resolveSenderNames` | 解析发送者显示名称 | `true` | --- @@ -418,7 +418,7 @@ Feishu/Lark 支持在私信和群组话题消息中使用 ACP。Feishu/Lark ACP - ✅ 图片 - ✅ 文件 - ✅ 音频 -- ✅ 视频 / 媒体 +- ✅ 视频/媒体 - ✅ 表情贴纸 ### 发送 @@ -427,26 +427,26 @@ Feishu/Lark 支持在私信和群组话题消息中使用 ACP。Feishu/Lark ACP - ✅ 图片 - ✅ 文件 - ✅ 音频 -- ✅ 视频 / 媒体 +- ✅ 视频/媒体 - ✅ 交互式卡片（包括流式更新） - ⚠️ 富文本（post 样式格式；不支持完整的 Feishu/Lark 编辑能力） -原生 Feishu/Lark 音频气泡使用 Feishu `audio` 消息类型，并要求上传 Ogg/Opus 媒体（`file_type: "opus"`）。现有的 `.opus` 和 `.ogg` 媒体会直接作为原生音频发送。MP3/WAV/M4A 和其他常见音频格式，仅在回复请求语音投递时才会通过 `ffmpeg` 转码为 48 kHz 的 Ogg/Opus（`audioAsVoice` / 消息工具 `asVoice`，包括 TTS 语音便笺回复）。普通 MP3 附件会保持为常规文件。如果缺少 `ffmpeg` 或转换失败，OpenClaw 会回退为文件附件，并记录原因。 +原生 Feishu/Lark 音频气泡使用 Feishu `audio` 消息类型，并且需要上传 Ogg/Opus 媒体（`file_type: "opus"`）。现有的 `.opus` 和 `.ogg` 媒体会直接作为原生音频发送。MP3/WAV/M4A 和其他可能的音频格式，仅在回复请求语音投递（`audioAsVoice` / 消息工具 `asVoice`，包括 TTS 语音便笺回复）时，才会使用 `ffmpeg` 转码为 48 kHz 的 Ogg/Opus。普通 MP3 附件会保留为常规文件。如果缺少 `ffmpeg` 或转换失败，OpenClaw 会回退为文件附件并记录原因。 -### 话题和回复 +### 线程和回复 - ✅ 行内回复 -- ✅ 话题回复 -- ✅ 回复话题消息时，媒体回复会保持话题感知 +- ✅ 线程回复 +- ✅ 回复线程消息时，媒体回复会保持线程感知 -对于 `groupSessionScope: "group_topic"` 和 `"group_topic_sender"`，原生 Feishu/Lark 话题群组使用事件 `thread_id`（`omt_*`）作为规范的话题会话键。对于 OpenClaw 转换为话题的普通群组回复，仍然使用回复根消息 ID（`om_*`），这样首轮消息和后续消息会保持在同一个会话中。 +对于 `groupSessionScope: "group_topic"` 和 `"group_topic_sender"`，原生 Feishu/Lark 话题群组使用事件 `thread_id`（`omt_*`）作为规范的话题会话键。OpenClaw 转换为线程的普通群组回复，仍然使用回复根消息 ID（`om_*`），这样首轮消息和后续轮次会保留在同一个会话中。 --- ## 相关内容 -- [渠道概览](/zh-CN/channels) — 所有受支持的渠道 -- [配对](/zh-CN/channels/pairing) — 私信身份验证和配对流程 +- [渠道概览](/zh-CN/channels) — 所有支持的渠道 +- [配对](/zh-CN/channels/pairing) — 私信认证和配对流程 - [群组](/zh-CN/channels/groups) — 群聊行为和提及门控 - [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由 - [安全](/zh-CN/gateway/security) — 访问模型和加固措施 diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 8a9aeefda..e4652a650 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -2,70 +2,71 @@ read_when: - 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 - - 你在 OpenClaw 2026.4.24 之前使用了 `api.registerEmbeddedExtensionFactory` - - 你正在将插件更新为现代插件架构 + - 你在 OpenClaw 2026.4.25 之前使用了 `api.registerEmbeddedExtensionFactory` + - 你正在将插件更新到现代插件架构 - 你维护一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-25T01:59:31Z" + generated_at: "2026-04-25T09:40:22Z" model: gpt-5.4 provider: openai - source_hash: 6944e81e02d0e4031090a1b557e58842c59046f5e0c3834d7079c6370b4cb45c + source_hash: e3a1410d9353156b4597d16a42a931f83189680f89c320a906aa8d2c8196792f source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且文档化的导入路径。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 +OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚焦且有文档说明的导入方式。如果你的插件构建于新架构之前，本指南将帮助你完成迁移。 -## 正在发生什么变化 +## 正在发生哪些变化 -旧插件系统提供了两个开放范围很大的接口，让插件能够从单一入口点导入所需的任何内容： +旧插件系统提供了两个开放范围很广的接口，使插件可以通过单一入口点导入所需的任何内容： -- **`openclaw/plugin-sdk/compat`** —— 一个会重新导出数十个辅助工具的单一导入入口。它的引入是为了在构建新插件架构期间，让较早的基于钩子的插件继续工作。 -- **`openclaw/extension-api`** —— 一个桥接层，让插件可以直接访问宿主端辅助工具，例如嵌入式智能体运行器。 -- **`api.registerEmbeddedExtensionFactory(...)`** —— 一个已移除、仅限 Pi 的内置扩展钩子，可观察诸如 `tool_result` 之类的嵌入式运行器事件。 +- **`openclaw/plugin-sdk/compat`** —— 单一导入路径，重新导出了数十个辅助工具。它的引入是为了在新插件架构构建期间，让旧的基于钩子的插件继续工作。 +- **`openclaw/extension-api`** —— 一个桥接层，使插件可以直接访问宿主侧辅助工具，例如嵌入式智能体运行器。 +- **`api.registerEmbeddedExtensionFactory(...)`** —— 一个已移除、仅限 Pi 的内置扩展钩子，可观察诸如 `tool_result` 之类的 embedded-runner 事件。 这些宽泛的导入接口现已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。 -OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已文档化的插件行为。破坏性合同变更必须先经过兼容适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、清单字段、设置 API、钩子以及运行时注册行为。 +OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已有文档说明的插件行为。破坏性契约变更必须先经过兼容适配器、诊断信息、文档以及弃用窗口。这同样适用于 SDK 导入、manifest 字段、设置 API、钩子以及运行时注册行为。 - 向后兼容层将在未来的主版本中移除。届时，仍从这些接口导入的插件将会中断。 - 仅限 Pi 的嵌入式扩展工厂注册现在已经不再加载。 + 向后兼容层将在未来的某个主版本中移除。 + 仍从这些接口导入的插件届时将会失效。 + 仅限 Pi 的嵌入式扩展工厂注册现已不再加载。 -## 为什么会有这个变化 +## 为什么会有这项变更 -旧方法会带来一些问题： +旧方式会带来一些问题： - **启动缓慢** —— 导入一个辅助工具会加载数十个无关模块 -- **循环依赖** —— 宽泛的重新导出让导入环变得很容易出现 -- **API 接口不清晰** —— 无法判断哪些导出是稳定的，哪些是内部实现 +- **循环依赖** —— 宽泛的重新导出使创建导入循环变得很容易 +- **API 接口不清晰** —— 无法判断哪些导出是稳定接口，哪些是内部实现 -现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有清晰用途和文档化合同。 +现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有明确用途和文档化契约。 -面向内置渠道的旧版提供商便捷接口也已移除。像 `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 便捷接口也已移除。像 `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` 中。 -当前内置提供商示例： +当前内置 provider 示例： -- Anthropic 将 Claude 专用流辅助工具保留在其自己的 `api.ts` / `contract-api.ts` 接口中 -- OpenAI 将提供商构建器、默认模型辅助工具和实时提供商构建器保留在其自己的 `api.ts` 中 -- OpenRouter 将提供商构建器以及新手引导 / 配置辅助工具保留在其自己的 `api.ts` 中 +- Anthropic 将 Claude 专用流式辅助工具保留在它自己的 `api.ts` / `contract-api.ts` 接口中 +- OpenAI 将 provider 构建器、默认模型辅助工具和 realtime provider 构建器保留在它自己的 `api.ts` 中 +- OpenRouter 将 provider 构建器以及新手引导/配置辅助工具保留在它自己的 `api.ts` 中 ## 兼容性策略 对于外部插件，兼容性工作遵循以下顺序： -1. 添加新合同 -2. 通过兼容适配器保留旧行为 -3. 发出诊断或警告，明确指出旧路径及其替代方案 -4. 在测试中覆盖两条路径 +1. 添加新契约 +2. 通过兼容适配器继续连接旧行为 +3. 发出诊断信息或警告，明确指出旧路径和替代方案 +4. 在测试中覆盖新旧两条路径 5. 记录弃用信息和迁移路径 -6. 仅在宣布的迁移窗口之后移除，通常是在主版本中 +6. 仅在已公布的迁移窗口之后移除，通常是在主版本中 -如果某个清单字段仍然被接受，插件作者就可以继续使用它，直到文档和诊断另有说明。新代码应优先使用文档化的替代方案，但现有插件不应在常规次版本发布期间损坏。 +如果某个 manifest 字段仍被接受，插件作者就可以继续使用它，直到文档和诊断信息另有说明为止。新代码应优先使用文档中说明的替代方案，但现有插件不应在普通次版本发布中被破坏。 ## 如何迁移 @@ -84,7 +85,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 }); ``` - 同时更新插件清单： + 同时更新插件 manifest： ```json { @@ -94,55 +95,52 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 } ``` - 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任度工具输出之前对其进行重写。 + 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前对其进行重写。 - + 具备审批能力的渠道插件现在通过 - `approvalCapability.nativeRuntime` 以及共享运行时上下文注册表来公开原生审批行为。 + `approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来暴露原生审批行为。 关键变化： - - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 - `approvalCapability.nativeRuntime` - - 将审批专用的认证 / 投递逻辑从旧版 `plugin.auth` / - `plugin.approvals` 线路迁移到 `approvalCapability` - - `ChannelPlugin.approvals` 已从公共渠道插件合同中移除； - 请将 delivery / native / render 字段迁移到 `approvalCapability` - - `plugin.auth` 仍仅用于渠道登录 / 注销流程；其中的审批认证 - 钩子不再被核心读取 + - 用 `approvalCapability.nativeRuntime` 替换 `approvalCapability.handler.loadRuntime(...)` + - 将审批专用的认证/投递从旧版 `plugin.auth` / + `plugin.approvals` 连接方式迁移到 `approvalCapability` + - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除； + 请将 delivery/native/render 字段迁移到 `approvalCapability` + - `plugin.auth` 仅保留用于渠道登录/登出流程；其中的审批认证钩子不再被核心读取 - 通过 `openclaw/plugin-sdk/channel-runtime-context` - 注册渠道自有运行时对象，例如客户端、令牌或 Bolt - 应用 - - 不要从原生审批处理器发送插件自有的重路由通知； - 核心现在会根据实际投递结果统一处理“已路由到其他位置”通知 - - 当把 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供一个 - 真实的 `createPluginRuntime().channel` 接口。部分桩实现将被拒绝。 + 注册渠道自有运行时对象，例如客户端、令牌或 Bolt 应用 + - 不要从原生审批处理器发送插件自有的改道通知； + 核心现在根据实际投递结果统一处理“已路由到其他位置”的通知 + - 当将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 + `createPluginRuntime().channel` 接口。部分桩实现会被拒绝。 - 当前审批能力布局请参见 `/plugins/sdk-channel-plugins`。 + 请参阅 `/plugins/sdk-channel-plugins` 了解当前审批能力布局。 - 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在在 Windows 上无法解析的 - `.cmd` / `.bat` 包装器将默认失败关闭，除非你显式传入 + 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`， + 未解析的 Windows `.cmd`/`.bat` 包装器现在会默认失败关闭，除非你显式传入 `allowShellFallback: true`。 ```typescript - // Before + // 之前 const program = applyWindowsSpawnProgramPolicy({ candidate }); - // After + // 之后 const program = applyWindowsSpawnProgramPolicy({ candidate, - // 仅对受信任的兼容性调用方设置此项，这些调用方明确 - // 接受通过 shell 中介进行回退。 + // 仅为受信任的兼容性调用方设置此项，这些调用方明确接受 + // 通过 shell 中介进行回退。 allowShellFallback: true, }); ``` - 如果你的调用方并不有意依赖 shell 回退，请不要设置 + 如果你的调用方并非有意依赖 shell 回退，请不要设置 `allowShellFallback`，而应改为处理抛出的错误。 @@ -161,27 +159,27 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 旧接口中的每个导出都映射到一个特定的现代导入路径： ```typescript - // Before (deprecated backwards-compatibility layer) + // 之前（已弃用的向后兼容层） import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // After (modern focused imports) + // 之后（现代聚焦导入） import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - 对于宿主端辅助工具，请使用注入的插件运行时，而不是直接导入： + 对于宿主侧辅助工具，请使用注入的插件运行时，而不是直接导入： ```typescript - // Before (deprecated extension-api bridge) + // 之前（已弃用的 extension-api 桥接） import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // After (injected runtime) + // 之后（注入的运行时） const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` @@ -212,180 +210,180 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | 规范的插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 面向渠道入口定义 / 构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | 根配置模式导出 | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | 单提供商入口辅助工具 | `defineSingleProviderPluginEntry` | + | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` | + | `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | 单一 provider 入口辅助工具 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 可安全导入的设置补丁适配器、查找说明辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | + | `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-core` | 多账户辅助工具 | 账户列表/配置/操作门控辅助工具 | + | `plugin-sdk/account-id` | 账户 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化 | | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 精简账户辅助工具 | 账户列表 / 账户操作辅助工具 | + | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表/账户操作辅助工具 | | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | 私信配对基础组件 | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入状态线路 | `createChannelReplyPipeline` | + | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入连接逻辑 | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 配置模式构建器 | 共享渠道配置模式基础组件；以内置渠道命名的模式导出仅用于旧版兼容 | - | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复 / 冲突校验 | - | `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览完成辅助工具 | + | `plugin-sdk/channel-config-schema` | 配置 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/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 | | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、身份 / 发送委托、会话、格式化和负载规划辅助工具 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、身份/发送委托、会话、格式化和负载规划辅助工具 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧字段布局的智能体媒体负载构建器 | - | `plugin-sdk/channel-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` | 精简运行时环境辅助工具 | 日志器 / 运行时环境、超时、重试和退避辅助工具 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / 钩子 / http / 交互式辅助工具 | - | `plugin-sdk/hook-runtime` | 钩子管道辅助工具 | 共享 webhook / 内部钩子管道辅助工具 | + | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | 记录器/运行时环境、超时、重试和退避辅助工具 | + | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/钩子/http/交互式辅助工具 | + | `plugin-sdk/hook-runtime` | 钩子流水线辅助工具 | 共享 webhook/内部钩子流水线辅助工具 | | `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 | | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 | | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 | - | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 | - | `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/config-runtime` | 配置辅助工具 | 配置加载/写入辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供回退稳定的 Telegram 命令校验辅助工具 | + | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批负载、审批能力/profile 辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 | + | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同一聊天操作认证 | + | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批 profile/过滤辅助工具 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力/投递适配器 | | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向热渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽泛的审批处理器运行时辅助工具；如果更窄的 adapter / gateway 接口已经足够，优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复负载辅助工具 | - | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register / get / watch 辅助工具 | - | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和密钥收集辅助工具 | - | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 Allowlist 和私有网络策略辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 用于热渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽范围的审批处理器运行时辅助工具；若较窄的 adapter/gateway 接口已足够，应优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账户绑定辅助工具 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复负载辅助工具 | + | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register/get/watch 辅助工具 | + | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和秘密收集辅助工具 | + | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 | | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定 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/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` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | - | `plugin-sdk/command-status` | 命令状态 / 帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 | + | `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | allowlist 输入映射 | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具，包括动态参数菜单格式化 | + | `plugin-sdk/command-status` | 命令 Status/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | 秘密输入解析 | 秘密输入辅助工具 | | `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标工具 | - | `plugin-sdk/webhook-request-guards` | webhook 请求体保护辅助工具 | 请求体读取 / 限制辅助工具 | + | `plugin-sdk/webhook-request-guards` | webhook 请求体保护辅助工具 | 请求体读取/限制辅助工具 | | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 精简回复分发辅助工具 | 完成、提供商分发和会话标签辅助工具 | + | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | 最终化、provider 分发和会话标签辅助工具 | | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `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` | 路由 / session-key 辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、session-key 规范化辅助工具 | - | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道 / 账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | + | `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 | + | `plugin-sdk/status-helpers` | 渠道 Status 辅助工具 | 渠道/账户 Status 摘要构建器、运行时状态默认值、问题元数据辅助工具 | | `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-payload` | 工具负载提取 | 从工具结果对象中提取标准化负载 | - | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | + | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug/字符串规范化辅助工具 | + | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类似请求的输入中提取字符串 URL | + | `plugin-sdk/run-command` | 定时命令辅助工具 | 带规范化 stdout/stderr 的定时命令运行器 | + | `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 | + | `plugin-sdk/tool-payload` | 工具负载提取 | 从工具结果对象中提取规范化负载 | + | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范的发送目标字段 | | `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 | - | `plugin-sdk/logging-core` | 日志辅助工具 | 子系统日志器和脱敏辅助工具 | + | `plugin-sdk/logging-core` | 日志辅助工具 | 子系统记录器和脱敏辅助工具 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 | | `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 | - | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助工具 | 自托管提供商发现 / 配置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助工具 | 相同的自托管提供商发现 / 配置辅助工具 | - | `plugin-sdk/provider-auth-runtime` | 提供商运行时认证辅助工具 | 运行时 API 密钥解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | 提供商 API 密钥设置辅助工具 | API 密钥新手引导 / 配置文件写入辅助工具 | - | `plugin-sdk/provider-auth-result` | 提供商 auth-result 辅助工具 | 标准 OAuth auth-result 构建器 | - | `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助工具 | 共享交互式登录辅助工具 | - | `plugin-sdk/provider-selection-runtime` | 提供商选择辅助工具 | 已配置或自动提供商选择，以及原始提供商配置合并 | - | `plugin-sdk/provider-env-vars` | 提供商环境变量辅助工具 | 提供商认证环境变量查找辅助工具 | - | `plugin-sdk/provider-model-shared` | 共享提供商模型 / 回放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享回放策略构建器、提供商端点辅助工具以及 model-id 规范化辅助工具 | - | `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助工具 | - | `plugin-sdk/provider-http` | 提供商 HTTP 辅助工具 | 通用提供商 HTTP / 端点能力辅助工具，包括音频转录 multipart form 辅助工具 | - | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助工具 | web-fetch 提供商注册 / 缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 提供商 web 搜索配置辅助工具 | 面向不需要插件启用线路的提供商的精简 web 搜索配置 / 凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 提供商 web 搜索合同辅助工具 | 精简 web 搜索配置 / 凭证合同辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及带作用域的凭证 setter / getter | - | `plugin-sdk/provider-web-search` | 提供商 web 搜索辅助工具 | web 搜索提供商注册 / 缓存 / 运行时辅助工具 | - | `plugin-sdk/provider-tools` | 提供商工具 / 模式兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini 模式清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | 提供商用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 及其他提供商用量辅助工具 | - | `plugin-sdk/provider-stream` | 提供商流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助工具 | - | `plugin-sdk/provider-transport-runtime` | 提供商传输辅助工具 | 原生提供商传输辅助工具，例如受保护 fetch、传输消息转换和可写传输事件流 | + | `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 新手引导/profile 写入辅助工具 | + | `plugin-sdk/provider-auth-result` | provider 认证结果辅助工具 | 标准 OAuth 认证结果构建器 | + | `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 | + | `plugin-sdk/provider-selection-runtime` | provider 选择辅助工具 | 已配置或自动 provider 选择，以及原始 provider 配置合并 | + | `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider 认证环境变量查找辅助工具 | + | `plugin-sdk/provider-model-shared` | 共享 provider 模型/重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、provider 端点辅助工具，以及模型 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/端点能力辅助工具，包括音频转录 multipart 表单辅助工具 | + | `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册/缓存辅助工具 | + | `plugin-sdk/provider-web-search-config-contract` | provider web 搜索配置辅助工具 | 面向无需插件启用连接的 provider 的窄范围 web 搜索配置/凭证辅助工具 | + | `plugin-sdk/provider-web-search-contract` | provider web 搜索契约辅助工具 | 窄范围 web 搜索配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` 以及作用域凭证 setter/getter | + | `plugin-sdk/provider-web-search` | provider web 搜索辅助工具 | web 搜索 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/provider-transport-runtime` | provider 传输辅助工具 | 原生 provider 传输辅助工具，例如受保护 fetch、传输消息转换和可写传输事件流 | | `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取 / 转换 / 存储辅助工具，以及媒体负载构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 用于图片 / 视频 / 音乐生成的共享故障转移辅助工具、候选项选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解提供商类型，以及面向提供商的图片 / 音频辅助工具导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 对智能体可见文本剥离、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、指令标签辅助工具、安全文本工具，以及相关文本 / 日志辅助工具 | + | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取/转换/存储辅助工具，以及媒体负载构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 用于图像/视频/音乐生成的共享故障转移辅助工具、候选选择和缺失模型消息 | + | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像/音频辅助工具导出 | + | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本/日志辅助工具 | | `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音辅助工具 | 语音提供商类型，以及面向提供商的指令、注册表和校验辅助工具 | - | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | 提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | 提供商类型、注册表 / 解析辅助工具和桥接会话辅助工具 | + | `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的指令、注册表和校验辅助工具 | + | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、指令、规范化 | + | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具，以及共享 WebSocket 会话辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表/解析辅助工具，以及桥接会话辅助工具 | | `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/music-generation` | 音乐生成辅助工具 | 音乐生成 provider/请求/结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider/请求/结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助工具、provider 查找和 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/channel-status` | 渠道 Status 辅助工具 | 共享渠道 Status 快照/摘要辅助工具 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑/读取辅助工具 | | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证 / 守卫辅助工具 | - | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态和环境代理辅助基础组件 | + | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证/保护辅助工具 | + | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/Status 和环境代理辅助原语 | | `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和路由安装辅助工具 | | `plugin-sdk/webhook-path` | webhook 路径辅助工具 | webhook 路径规范化辅助工具 | - | `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程 / 本地媒体加载辅助工具 | - | `plugin-sdk/zod` | Zod 重新导出 | 面向插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | 内存管理器 / 配置 / 文件 / CLI 辅助接口 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时门面 | Memory 索引 / 搜索运行时门面 | + | `plugin-sdk/web-media` | 共享 web 媒体辅助工具 | 远程/本地媒体加载辅助工具 | + | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用方重新导出的 `zod` | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 管理器/配置/文件/CLI 辅助工具接口 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时外观 | Memory 索引/搜索运行时外观 | | `plugin-sdk/memory-core-host-engine-foundation` | Memory 宿主基础引擎 | Memory 宿主基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入合同、注册表访问、本地提供商以及通用批处理 / 远程辅助工具；具体远程提供商位于其所属插件中 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地 provider 和通用批处理/远程辅助工具；具体远程 provider 位于其所属插件中 | | `plugin-sdk/memory-core-host-engine-qmd` | Memory 宿主 QMD 引擎 | Memory 宿主 QMD 引擎导出 | | `plugin-sdk/memory-core-host-engine-storage` | Memory 宿主存储引擎 | Memory 宿主存储引擎导出 | | `plugin-sdk/memory-core-host-multimodal` | Memory 宿主多模态辅助工具 | Memory 宿主多模态辅助工具 | | `plugin-sdk/memory-core-host-query` | Memory 宿主查询辅助工具 | Memory 宿主查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory 宿主密钥辅助工具 | Memory 宿主密钥辅助工具 | + | `plugin-sdk/memory-core-host-secret` | Memory 宿主秘密辅助工具 | Memory 宿主秘密辅助工具 | | `plugin-sdk/memory-core-host-events` | Memory 宿主事件日志辅助工具 | Memory 宿主事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | Memory 宿主状态辅助工具 | Memory 宿主状态辅助工具 | + | `plugin-sdk/memory-core-host-status` | Memory 宿主 Status 辅助工具 | Memory 宿主 Status 辅助工具 | | `plugin-sdk/memory-core-host-runtime-cli` | Memory 宿主 CLI 运行时 | Memory 宿主 CLI 运行时辅助工具 | | `plugin-sdk/memory-core-host-runtime-core` | Memory 宿主核心运行时 | Memory 宿主核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件 / 运行时辅助工具 | Memory 宿主文件 / 运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件/运行时辅助工具 | Memory 宿主文件/运行时辅助工具 | | `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向供应商中立的 Memory 宿主核心运行时辅助工具别名 | | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向供应商中立的 Memory 宿主事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | Memory 宿主文件 / 运行时别名 | 面向供应商中立的 Memory 宿主文件 / 运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助工具 | 面向与 memory 邻接插件的共享托管 markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索门面 | 惰性活跃 Memory 搜索管理器运行时门面 | - | `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向供应商中立的 Memory 宿主状态辅助工具别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助接口 | + | `plugin-sdk/memory-host-files` | Memory 宿主文件/运行时别名 | 面向供应商中立的 Memory 宿主文件/运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助工具 | 用于 memory 邻接插件的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索外观 | 惰性活跃 Memory 搜索管理器运行时外观 | + | `plugin-sdk/memory-host-status` | Memory 宿主 Status 别名 | 面向供应商中立的 Memory 宿主 Status 辅助工具别名 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助工具接口 | | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mock | -这个表格刻意只包含常见迁移子集，而不是完整的 SDK 接口。完整的 200+ 入口点列表位于 +此表刻意只包含常见迁移子集，而不是完整的 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/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` - 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`, @@ -394,30 +392,30 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` 和 `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` 当前公开的是精简的 token 辅助接口 +`plugin-sdk/github-copilot-token` 当前公开了窄范围令牌辅助接口 `DEFAULT_COPILOT_API_BASE_URL`、 `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 -请使用与你的任务最匹配、最精简的导入路径。如果你找不到某个导出，请查看 `src/plugin-sdk/` 中的源代码，或在 Discord 中提问。 +请使用与你的任务最匹配的最窄导入路径。如果你找不到某个导出，请查看 +`src/plugin-sdk/` 下的源码，或在 Discord 中提问。 -## 当前已激活的弃用项 +## 当前弃用项 -这些更精细的弃用项适用于整个插件 SDK、提供商合同、运行时接口和清单。它们目前仍然可用，但会在未来的主版本中移除。每一项下方的条目都给出了旧 API 到其规范替代方案的映射。 +以下是适用于整个插件 SDK、provider 契约、运行时接口和 manifest 的更窄粒度弃用项。它们目前仍可使用，但会在未来的某个主版本中移除。每一项下方的条目都会将旧 API 映射到其规范替代项。 **旧版（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`。 - **新版（`openclaw/plugin-sdk/command-status`）**：签名相同，导出相同—— - 只是改为从更精简的子路径导入。`command-auth` - 会将它们重新导出为兼容性桩。 + **新版（`openclaw/plugin-sdk/command-status`）**：签名相同，导出相同——只是改为从更窄的子路径导入。`command-auth` + 会将它们作为兼容桩重新导出。 ```typescript - // Before + // 之前 import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; - // After + // 之后 import { buildHelpMessage } from "openclaw/plugin-sdk/command-status"; ``` @@ -432,62 +430,58 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 **新版**：`resolveInboundMentionDecision({ facts, policy })` —— 返回一个 单一决策对象，而不是拆分成两个调用。 - 下游渠道插件（Slack、Discord、Matrix、MS Teams）已经全部切换。 + 下游渠道插件（Slack、Discord、Matrix、MS Teams）已全部完成切换。 - - `openclaw/plugin-sdk/channel-runtime` 是面向旧版 - 渠道插件的兼容性垫片。不要在新代码中导入它；请改用 + + `openclaw/plugin-sdk/channel-runtime` 是为旧版 + 渠道插件提供的兼容垫片。不要在新代码中导入它；请使用 `openclaw/plugin-sdk/channel-runtime-context` 来注册运行时 对象。 `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` - 辅助工具也已与原始 “actions” 渠道导出一同弃用。请改为通过语义化的 - `presentation` 接口暴露能力——渠道插件应声明它们渲染什么 - （cards、buttons、selects），而不是声明它们接受哪些原始 - action 名称。 + 辅助工具会与原始 “actions” 渠道导出一起弃用。请改为通过具备语义的 + `presentation` 接口暴露能力——渠道插件应声明其渲染内容（卡片、按钮、选择器），而不是声明它们接受哪些原始 action 名称。 - - **旧版**：`openclaw/plugin-sdk/provider-web-search` 中的 `tool()` + + **旧版**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` 工厂。 - **新版**：直接在提供商插件上实现 `createTool(...)`。 - OpenClaw 不再需要 SDK 辅助工具来注册工具包装器。 + **新版**：直接在 provider 插件上实现 `createTool(...)`。 + OpenClaw 不再需要 SDK 辅助工具来注册该工具包装器。 **旧版**：`formatInboundEnvelope(...)`（以及 - `ChannelMessageForAgent.channelEnvelope`）用于从入站渠道消息构建扁平纯文本提示 - envelope。 + `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建扁平的纯文本提示 envelope。 **新版**：`BodyForAgent` 加上结构化用户上下文块。 - 渠道插件现在将路由元数据（线程、话题、回复对象、反应）作为 - 类型化字段附加，而不是把它们拼接进提示字符串中。 - `formatAgentEnvelope(...)` 辅助工具仍然支持用于合成的面向助手的 + 渠道插件会将路由元数据（线程、主题、reply-to、reactions）作为 + 类型化字段附加，而不是将它们拼接进提示字符串中。 + `formatAgentEnvelope(...)` 辅助工具仍支持用于合成的、面向助手的 envelope，但入站纯文本 envelope 正在逐步淘汰。 - 受影响区域：`inbound_claim`、`message_received`，以及任何自定义 - 渠道插件中对 `channelEnvelope` 文本进行了后处理的代码。 + 受影响区域：`inbound_claim`、`message_received`，以及任何对 + `channelEnvelope` 文本进行后处理的自定义渠道插件。 - - 四个发现类型别名现在都只是目录时代类型的薄包装： + + 四个发现类型别名现在只是 catalog 时代类型的薄包装： | 旧别名 | 新类型 | | ------------------------- | ------------------------- | - | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | - | `ProviderDiscoveryContext`| `ProviderCatalogContext` | - | `ProviderDiscoveryResult` | `ProviderCatalogResult` | - | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | + | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | + | `ProviderDiscoveryContext`| `ProviderCatalogContext` | + | `ProviderDiscoveryResult` | `ProviderCatalogResult` | + | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - 另外还有旧版的 `ProviderCapabilities` 静态包—— - 提供商插件应通过提供商运行时合同附加能力事实， - 而不是通过静态对象。 + 另外还有旧版静态包 `ProviderCapabilities`——provider 插件 + 应通过 provider 运行时契约附加 capability facts，而不是通过静态对象。 @@ -498,21 +492,20 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 **新版**：单一的 `resolveThinkingProfile(ctx)`，返回一个 `ProviderThinkingProfile`，其中包含规范 `id`、可选 `label`，以及 - 按级别排序的列表。OpenClaw 会根据配置文件等级 - 自动降级过期的已存储值。 + 排序后的级别列表。OpenClaw 会按 profile 排名自动降级过期的已存储值。 - 现在实现一个钩子即可，不再需要三个。旧版钩子在 - 弃用窗口期间仍然可用，但不会与配置文件结果进行组合。 + 现在只需实现一个钩子，而不是三个。旧钩子在弃用窗口期间仍可使用， + 但不会与 profile 结果进行组合。 - - **旧版**：实现 `resolveExternalOAuthProfiles(...)`，但 - 没有在插件清单中声明该提供商。 + + **旧版**：实现 `resolveExternalOAuthProfiles(...)`， + 但未在插件 manifest 中声明该 provider。 - **新版**：在插件清单中声明 `contracts.externalAuthProviders` - **并且**实现 `resolveExternalAuthProfiles(...)`。旧版 “auth - fallback” 路径会在运行时发出警告，并将在之后被移除。 + **新版**：在插件 manifest 中声明 `contracts.externalAuthProviders` + **并且**实现 `resolveExternalAuthProfiles(...)`。旧的 “auth + fallback” 路径会在运行时发出警告，并将在后续移除。 ```json { @@ -524,12 +517,12 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - - **旧版**清单字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 + + **旧版** manifest 字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 - **新版**：将相同的环境变量查找镜像到清单中的 `setup.providers[].envVars`。 - 这样可以把设置 / 状态环境变量元数据集中到一个位置， - 并避免仅为了回答环境变量查找而启动插件运行时。 + **新版**：将相同的环境变量查找镜像到 manifest 中的 `setup.providers[].envVars` + 中。这样可以把设置/Status 环境变量元数据集中到一个位置， + 并避免仅为了响应环境变量查找而启动插件运行时。 `providerAuthEnvVars` 会通过兼容适配器继续受支持， 直到弃用窗口结束。 @@ -545,23 +538,22 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 **新版**：在 memory-state API 上进行一次调用—— `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。 - 相同的插槽，单一注册调用。附加型 Memory 辅助工具 + 相同插槽，单次注册调用。附加型 Memory 辅助工具 （`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, `registerMemoryEmbeddingProvider`）不受影响。 - + 两个旧版类型别名仍从 `src/plugins/runtime/types.ts` 导出： | 旧版 | 新版 | | ----------------------------- | ------------------------------- | - | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | - | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | + | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | + | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | 运行时方法 `readSession` 已弃用，改为使用 - `getSessionMessages`。签名相同；旧方法会直接调用 - 新方法。 + `getSessionMessages`。签名相同；旧方法会直接调用新方法。 @@ -569,33 +561,33 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 **旧版**：`runtime.tasks.flow`（单数）返回一个实时 task-flow 访问器。 **新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问， - 这样可安全导入，并且不需要加载完整任务运行时。 + 可安全导入，且无需加载完整任务运行时。 ```typescript - // Before + // 之前 const flow = api.runtime.tasks.flow(ctx); - // After + // 之后 const flows = api.runtime.tasks.flows(ctx); ``` - 已在上文 “如何迁移 → 将 Pi 工具结果扩展迁移到中间件” - 中说明。这里再次列出以便完整起见：已移除的、仅限 Pi 的 - `api.registerEmbeddedExtensionFactory(...)` 路径已被 - `api.registerAgentToolResultMiddleware(...)` 替代，并且需要在 + 已在上文“如何迁移 → 将 Pi 工具结果扩展迁移到中间件”中介绍。 + 为了完整起见，这里再次说明：已移除的仅限 Pi 的 + `api.registerEmbeddedExtensionFactory(...)` 路径，已被 + `api.registerAgentToolResultMiddleware(...)` 取代，并需要在 `contracts.agentToolResultMiddleware` 中显式声明运行时列表。 - 从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` - 现在只是 `OpenClawConfig` 的一行别名。请优先使用规范名称。 + 从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` 现在只是 + `OpenClawConfig` 的单行别名。请优先使用规范名称。 ```typescript - // Before + // 之前 import type { OpenClawSchemaType } from "openclaw/plugin-sdk"; - // After + // 之后 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema"; ``` @@ -603,10 +595,11 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 -扩展级弃用项（位于 `extensions/` 下的内置渠道 / 提供商插件内部） -会在它们各自的 `api.ts` 和 `runtime-api.ts` -barrel 中跟踪。这些内容不会影响第三方插件合同，因此也未在此列出。 -如果你直接使用某个内置插件的本地 barrel，请在升级前先阅读该 barrel 中的弃用注释。 +扩展级弃用项（位于 `extensions/` 下内置渠道/provider 插件内部） +会在它们自己的 `api.ts` 和 `runtime-api.ts` +barrel 中进行跟踪。它们不会影响第三方插件契约，因此未在此列出。 +如果你直接使用某个内置插件的本地 barrel，请在升级前先阅读该 +barrel 中的弃用注释。 ## 移除时间线 @@ -614,26 +607,26 @@ barrel 中跟踪。这些内容不会影响第三方插件合同，因此也未 | 时间 | 会发生什么 | | ---------------------- | ----------------------------------------------------------------------- | | **现在** | 已弃用接口会发出运行时警告 | -| **下一个主版本** | 已弃用接口将被移除；仍在使用它们的插件将会失败 | +| **下一个主版本** | 已弃用接口将被移除；仍在使用它们的插件将会失效 | -所有核心插件都已经完成迁移。外部插件应在下一个主版本之前完成迁移。 +所有核心插件都已完成迁移。外部插件应在下一个主版本发布前完成迁移。 ## 临时抑制警告 -在你进行迁移时，可以设置以下环境变量： +在迁移期间，你可以设置以下环境变量： ```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) —— 构建提供商插件 +- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) —— 构建 provider 插件 - [插件内部机制](/zh-CN/plugins/architecture) —— 架构深入解析 -- [插件清单](/zh-CN/plugins/manifest) —— 清单模式参考 +- [插件清单](/zh-CN/plugins/manifest) —— manifest schema 参考 diff --git a/docs/zh-CN/plugins/sdk-subpaths.md b/docs/zh-CN/plugins/sdk-subpaths.md index 38bddc11a..ecea11355 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -2,22 +2,21 @@ read_when: - 为插件导入选择合适的 plugin-sdk 子路径 - 审查 bundled-plugin 子路径和辅助接口 -summary: 插件 SDK 子路径目录：按领域分组说明各导入位于何处 +summary: 插件 SDK 子路径目录：按领域分组，哪些导入位于哪里 title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-25T03:24:41Z" + generated_at: "2026-04-25T09:40:18Z" model: gpt-5.4 provider: openai - source_hash: 0ff08a1f6801329cd9c20353e77983c3333a4237db9217d19a621b670c1b636f + source_hash: 47598d82cccc14708d9a4f6fbb3ce29bfa876e3808e335de7572d166ce0c5386 source_path: plugins/sdk-subpaths.md workflow: 15 --- - 插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径暴露。 - 本页按用途分组整理常用子路径。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`； - 其中也会列出保留的 bundled-plugin 辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。 + 插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组窄化子路径对外暴露。 + 本页按用途分组，汇总常用的子路径。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；其中也会出现保留的 bundled-plugin 辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。 - 关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 + 有关插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 @@ -34,248 +33,248 @@ x-i18n: | --- | --- | | `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/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | + | `plugin-sdk/setup` | 共享的设置向导辅助方法、allowlist 提示、设置状态构建器 | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助工具，默认账户回退辅助工具 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 | - | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 精简的账户列表 / 账户操作辅助工具 | + | `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助方法，以及默认账户回退辅助方法 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化辅助方法 | + | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助方法 | + | `plugin-sdk/account-helpers` | 窄化的账户列表 / 账户操作辅助方法 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助工具，带 bundled-contract 回退 | - | `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 | + | `plugin-sdk/telegram-command-config` | 带 bundled-contract 回退的 Telegram 自定义命令规范化 / 验证辅助方法 | + | `plugin-sdk/command-gating` | 窄化的命令授权门控辅助方法 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 终结辅助工具 | - | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 | - | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助工具 | - | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 | - | `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化以及负载规划辅助工具 | - | `plugin-sdk/poll-runtime` | 精简的投票规范化辅助工具 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期与适配器辅助工具 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 终结辅助方法 | + | `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助方法 | + | `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助方法 | + | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助方法 | + | `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助方法 | + | `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化以及负载规划辅助方法 | + | `plugin-sdk/poll-runtime` | 窄化的投票规范化辅助方法 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期与适配器辅助方法 | | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 | - | `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对以及已配置绑定辅助工具 | - | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 | - | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 | - | `plugin-sdk/channel-status` | 共享渠道状态快照 / 摘要辅助工具 | - | `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 基元 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 | - | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助工具 | - | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 共享直接私信认证 / 守卫辅助工具 | - | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递以及旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 入站防抖、提及匹配、提及策略辅助工具以及 envelope 辅助工具的兼容性 barrel | - | `plugin-sdk/channel-inbound-debounce` | 精简的入站防抖辅助工具 | - | `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时能力的精简提及策略与提及文本辅助工具 | - | `plugin-sdk/channel-envelope` | 精简的入站 envelope 格式化辅助工具 | - | `plugin-sdk/channel-location` | 渠道位置上下文与格式化辅助工具 | - | `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助工具 | + | `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对以及已配置绑定辅助方法 | + | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助方法 | + | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助方法 | + | `plugin-sdk/channel-status` | 共享的渠道 Status 快照 / 摘要辅助方法 | + | `plugin-sdk/channel-config-primitives` | 窄化的渠道配置 schema 基元 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助方法 | + | `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助方法 | + | `plugin-sdk/group-access` | 共享的群组访问决策辅助方法 | + | `plugin-sdk/direct-dm` | 共享的直接私信认证 / 守卫辅助方法 | + | `plugin-sdk/interactive-runtime` | 语义消息呈现、投递以及旧版交互式回复辅助方法。参见 [消息呈现](/zh-CN/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | 面向入站去抖、提及匹配、提及策略辅助方法以及 envelope 辅助方法的兼容 barrel | + | `plugin-sdk/channel-inbound-debounce` | 窄化的入站去抖辅助方法 | + | `plugin-sdk/channel-mention-gating` | 不含更广泛入站运行时接口的窄化提及策略与提及文本辅助方法 | + | `plugin-sdk/channel-envelope` | 窄化的入站 envelope 格式化辅助方法 | + | `plugin-sdk/channel-location` | 渠道位置上下文与格式化辅助方法 | + | `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助方法 | | `plugin-sdk/channel-send-result` | 回复结果类型 | - | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为保持插件兼容性而保留的已弃用原生 schema 辅助工具 | - | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助工具 | + | `plugin-sdk/channel-actions` | 渠道消息操作辅助方法，以及为保持插件兼容性而保留的已弃用原生 schema 辅助方法 | + | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助方法 | | `plugin-sdk/channel-contract` | 渠道契约类型 | | `plugin-sdk/channel-feedback` | 反馈 / reaction 接线 | - | `plugin-sdk/channel-secret-runtime` | 精简的 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 以及 secret target 类型 | + | `plugin-sdk/channel-secret-runtime` | 窄化的 secret-contract 辅助方法，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment`，以及 secret 目标类型 | | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容型自托管提供商的设置辅助工具 | + | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助方法 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管提供商的设置辅助方法 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 用于提供商插件的运行时 API key 解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置文件写入辅助工具，例如 `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 | - | `plugin-sdk/provider-auth-login` | 用于提供商插件的共享交互式登录辅助工具 | - | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 | + | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API key 解析辅助方法 | + | `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置文件写入辅助方法，例如 `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | + | `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助方法 | + | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助方法 | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助方法，以及诸如 `normalizeNativeXaiModelId` 之类的模型 ID 规范化辅助方法 | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助工具、提供商 HTTP 错误以及音频转写 multipart form 辅助工具 | - | `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置 / 选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用接线的提供商的精简 web-search 配置 / 凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化凭证 setter / getter | - | `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助工具 | - | `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-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换以及可写传输事件流 | - | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 | - | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助工具 | - | `plugin-sdk/group-activation` | 精简的群组激活模式与命令解析辅助工具 | + | `plugin-sdk/provider-http` | 通用提供商 HTTP / 端点能力辅助方法、提供商 HTTP 错误，以及音频转录 multipart form 辅助方法 | + | `plugin-sdk/provider-web-fetch-contract` | 窄化的 web-fetch 配置 / 选择契约辅助方法，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助方法 | + | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的窄化 web-search 配置 / 凭证辅助方法 | + | `plugin-sdk/provider-web-search-contract` | 窄化的 web-search 配置 / 凭证契约辅助方法，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter / getter | + | `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助方法 | + | `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-transport-runtime` | 原生提供商传输辅助方法，例如受保护的 fetch、传输消息转换以及可写传输事件流 | + | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助方法 | + | `plugin-sdk/global-singleton` | 进程本地 singleton / map / 缓存辅助方法 | + | `plugin-sdk/group-activation` | 窄化的群组激活模式与命令解析辅助方法 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送方授权辅助工具 | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助方法（包括动态参数菜单格式化）、发送方授权辅助方法 | | `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | 审批人解析以及同聊天 action-auth 辅助工具 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件 / 过滤器辅助工具 | + | `plugin-sdk/approval-auth-runtime` | 审批人解析以及同聊天 action-auth 辅助方法 | + | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件 / 过滤器辅助方法 | | `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 投递适配器 | - | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 用于高频渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更精简的 adapter / gateway 接缝已足够，优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助工具 | - | `plugin-sdk/approval-runtime` | exec / 插件审批负载辅助工具、原生审批路由 / 运行时辅助工具，以及结构化审批显示辅助工具，例如 `formatApprovalDisplayPath` | - | `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助工具 | - | `plugin-sdk/channel-contract-testing` | 不带广泛 testing barrel 的精简渠道契约测试辅助工具 | - | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 | - | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | - | `plugin-sdk/command-primitives-runtime` | 用于高频渠道路径的轻量级命令文本谓词 | - | `plugin-sdk/command-surface` | 命令主体规范化和命令表面辅助工具 | + | `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助方法 | + | `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量原生审批适配器加载辅助方法 | + | `plugin-sdk/approval-handler-runtime` | 范围更广的审批处理器运行时辅助方法；如果更窄的 adapter / gateway 接口已足够，优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助方法 | + | `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助方法 | + | `plugin-sdk/approval-runtime` | exec / 插件审批负载辅助方法、原生审批路由 / 运行时辅助方法，以及结构化审批显示辅助方法，例如 `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | 窄化的入站回复去重重置辅助方法 | + | `plugin-sdk/channel-contract-testing` | 不包含宽泛 testing barrel 的窄化渠道契约测试辅助方法 | + | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化，以及原生会话目标辅助方法 | + | `plugin-sdk/command-detection` | 共享的命令检测辅助方法 | + | `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量命令文本谓词 | + | `plugin-sdk/command-surface` | 命令体规范化与命令接口辅助方法 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret surface 的精简 secret 契约收集辅助工具 | - | `plugin-sdk/secret-ref-runtime` | 面向 secret 契约 / 配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助工具 | - | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助工具 | - | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 | - | `plugin-sdk/ssrf-dispatcher` | 不带广泛基础设施运行时表面的精简固定 dispatcher 辅助工具 | - | `plugin-sdk/ssrf-runtime` | 固定 dispatcher、受 SSRF 保护的 fetch 以及 SSRF 策略辅助工具 | - | `plugin-sdk/secret-input` | secret 输入解析辅助工具 | - | `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助工具 | - | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助工具 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 接口的窄化 secret-contract 收集辅助方法 | + | `plugin-sdk/secret-ref-runtime` | 面向 secret-contract / 配置解析的窄化 `coerceSecretRef` 和 SecretRef 类型辅助方法 | + | `plugin-sdk/security-runtime` | 共享的信任、私信门控、外部内容和 secret 收集辅助方法 | + | `plugin-sdk/ssrf-policy` | 主机 allowlist 与私有网络 SSRF 策略辅助方法 | + | `plugin-sdk/ssrf-dispatcher` | 不包含宽泛基础设施运行时接口的窄化 pinned-dispatcher 辅助方法 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、带 SSRF 防护的 fetch，以及 SSRF 策略辅助方法 | + | `plugin-sdk/secret-input` | secret 输入解析辅助方法 | + | `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助方法 | + | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助方法 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 广泛的运行时 / 日志 / 备份 / 插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 精简的运行时环境、日志记录器、超时、重试和退避辅助工具 | - | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 | + | `plugin-sdk/runtime` | 宽泛的运行时 / 日志 / 备份 / 插件安装辅助方法 | + | `plugin-sdk/runtime-env` | 窄化的运行时环境、日志器、超时、重试和退避辅助方法 | + | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助方法 | | `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/process-runtime` | 进程 exec 辅助工具 | - | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 | - | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 | - | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助工具以及插件配置查找辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化以及重复 / 冲突检查，即使 bundled Telegram 契约接口不可用时也可使用 | - | `plugin-sdk/text-autolink-runtime` | 不带广泛 text-runtime barrel 的文件引用自动链接检测 | - | `plugin-sdk/approval-runtime` | exec / 插件审批辅助工具、审批能力构建器、认证 / 配置文件辅助工具、原生路由 / 运行时辅助工具，以及结构化审批显示路径格式化 | - | `plugin-sdk/reply-runtime` | 共享入站 / 回复运行时辅助工具、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发 / 终结和会话标签辅助工具 | - | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | 共享的插件命令 / 钩子 / HTTP / 交互辅助方法 | + | `plugin-sdk/hook-runtime` | 共享的 webhook / 内部钩子管线辅助方法 | + | `plugin-sdk/lazy-runtime` | 惰性运行时导入 / 绑定辅助方法，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程 exec 辅助方法 | + | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助方法 | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端与渠道 Status 补丁辅助方法 | + | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助方法，以及插件配置查找辅助方法 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化与重复 / 冲突检查，即使内置 Telegram 契约接口不可用时也可使用 | + | `plugin-sdk/text-autolink-runtime` | 不依赖宽泛 text-runtime barrel 的文件引用自动链接检测 | + | `plugin-sdk/approval-runtime` | exec / 插件审批辅助方法、审批能力构建器、认证 / 配置文件辅助方法、原生路由 / 运行时辅助方法，以及结构化审批显示路径格式化 | + | `plugin-sdk/reply-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/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/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` | 共享的渠道 / 账户 Status 摘要辅助方法、运行时状态默认值，以及问题元数据辅助方法 | + | `plugin-sdk/target-resolver-runtime` | 共享的目标解析器辅助方法 | + | `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助方法 | | `plugin-sdk/request-url` | 从 fetch / request 类输入中提取字符串 URL | - | `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout / stderr 结果 | - | `plugin-sdk/param-readers` | 通用工具 / CLI 参数读取器 | + | `plugin-sdk/run-command` | 带计时的命令运行器，返回规范化的 stdout / stderr 结果 | + | `plugin-sdk/param-readers` | 常用工具 / CLI 参数读取器 | | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 | - | `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 | - | `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 | - | `plugin-sdk/logging-core` | 子系统日志记录器和脱敏辅助工具 | - | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助工具 | - | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 | - | `plugin-sdk/file-lock` | 可重入文件锁辅助工具 | - | `plugin-sdk/persistent-dedupe` | 磁盘后备去重缓存辅助工具 | - | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助工具 | - | `plugin-sdk/acp-binding-resolve-runtime` | 不带生命周期启动导入的只读 ACP 绑定解析 | - | `plugin-sdk/agent-config-primitives` | 精简的智能体运行时 config-schema 基元 | + | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | + | `plugin-sdk/temp-path` | 共享的临时下载路径辅助方法 | + | `plugin-sdk/logging-core` | 子系统日志器与脱敏辅助方法 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式与转换辅助方法 | + | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助方法 | + | `plugin-sdk/file-lock` | 可重入文件锁辅助方法 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助方法 | + | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话与回复分发辅助方法 | + | `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 | + | `plugin-sdk/agent-config-primitives` | 窄化的智能体运行时配置 schema 基元 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | - | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | - | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 | - | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 | - | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助工具 | - | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 | - | `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助工具 | - | `plugin-sdk/agent-harness` | 面向受信任插件、仍属实验性的底层 Agent harness 接口：harness 类型、活动运行 steer / abort 辅助工具、OpenClaw 工具桥接辅助工具、工具进度格式化 / 细节辅助工具，以及 attempt 结果工具 | - | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助工具 | - | `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助工具 | - | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | - | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 | - | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和固定查找辅助工具 | - | `plugin-sdk/runtime-fetch` | 不导入 proxy / guarded-fetch 的 dispatcher 感知型运行时 fetch | - | `plugin-sdk/response-limit-runtime` | 不带广泛媒体运行时表面的有界响应体读取器 | - | `plugin-sdk/session-binding-runtime` | 不带已配置绑定路由或配对存储的当前会话绑定状态 | - | `plugin-sdk/session-store-runtime` | 不带广泛配置写入 / 维护导入的会话存储读取辅助工具 | - | `plugin-sdk/context-visibility-runtime` | 不带广泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 | - | `plugin-sdk/string-coerce-runtime` | 不带 markdown / 日志导入的精简基元记录 / 字符串强制转换与规范化辅助工具 | - | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | - | `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助工具 | - | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助工具 | - | `plugin-sdk/directory-runtime` | 配置后备目录查询 / 去重 | + | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助方法 | + | `plugin-sdk/device-bootstrap` | 设备引导与配对令牌辅助方法 | + | `plugin-sdk/extension-shared` | 共享的被动渠道、Status 和环境代理辅助基元 | + | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助方法 | + | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助方法 | + | `plugin-sdk/native-command-registry` | 原生命令注册表构建 / 序列化辅助方法 | + | `plugin-sdk/agent-harness` | 面向低层 Agent harness 的实验性受信任插件接口：harness 类型、活动运行 steer / abort 辅助方法、OpenClaw 工具桥接辅助方法、工具进度格式化 / 详情辅助方法，以及尝试结果工具函数 | + | `plugin-sdk/provider-zai-endpoint` | Z.A.I 端点检测辅助方法 | + | `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助方法 | + | `plugin-sdk/collection-runtime` | 小型有界缓存辅助方法 | + | `plugin-sdk/diagnostic-runtime` | 诊断标志与事件辅助方法 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助方法、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和 pinned lookup 辅助方法 | + | `plugin-sdk/runtime-fetch` | 不引入代理 / guarded-fetch 导入的 dispatcher 感知型运行时 fetch | + | `plugin-sdk/response-limit-runtime` | 不依赖宽泛媒体运行时接口的有界响应体读取器 | + | `plugin-sdk/session-binding-runtime` | 不含已配置绑定路由或配对存储的当前会话绑定状态 | + | `plugin-sdk/session-store-runtime` | 不含宽泛配置写入 / 维护导入的会话存储读取辅助方法 | + | `plugin-sdk/context-visibility-runtime` | 不依赖宽泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 | + | `plugin-sdk/string-coerce-runtime` | 不依赖 Markdown / 日志导入的窄化原始记录 / 字符串强制转换与规范化辅助方法 | + | `plugin-sdk/host-runtime` | 主机名与 SCP 主机规范化辅助方法 | + | `plugin-sdk/retry-runtime` | 重试配置与重试执行器辅助方法 | + | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助方法 | + | `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/media-runtime` | 共享媒体获取 / 转换 / 存储辅助工具，以及媒体负载构建器 | - | `plugin-sdk/media-store` | 精简的媒体存储辅助工具，例如 `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图片 / 音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本 / markdown / 日志辅助工具，例如对智能体可见文本的剥离、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具以及安全文本工具 | - | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表、校验和语音辅助导出 | - | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive、规范化和语音辅助导出 | - | `plugin-sdk/realtime-transcription` | 实时转写提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | + | `plugin-sdk/media-runtime` | 共享的媒体获取 / 转换 / 存储辅助方法，以及媒体负载构建器 | + | `plugin-sdk/media-store` | 窄化的媒体存储辅助方法，例如 `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障切换辅助方法、候选项选择和缺失模型消息 | + | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享的文本 / Markdown / 日志辅助方法，例如智能体可见文本剥离、Markdown 渲染 / 分块 / 表格辅助方法、脱敏辅助方法、directive-tag 辅助方法，以及安全文本工具 | + | `plugin-sdk/text-chunking` | 出站文本分块辅助方法 | + | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表、验证和语音辅助导出 | + | `plugin-sdk/speech-core` | 共享的语音提供商类型、注册表、directive、规范化和语音辅助导出 | + | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助方法，以及共享 WebSocket 会话辅助方法 | + | `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/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/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 / 文件 / CLI 辅助工具 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时门面 | - | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地 provider 以及通用批处理 / 远程辅助工具 | - | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 | - | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 | - | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助工具 | - | `plugin-sdk/memory-host-core` | 面向厂商中立的 memory host 核心运行时辅助工具别名 | - | `plugin-sdk/memory-host-events` | 面向厂商中立的 memory host 事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | 面向厂商中立的 memory host 文件 / 运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 面向 Memory 邻近插件的共享托管 markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 Memory 运行时门面 | - | `plugin-sdk/memory-host-status` | 面向厂商中立的 memory host 状态辅助工具别名 | + | `plugin-sdk/memory-core` | 内置的 memory-core 辅助接口，用于 manager / config / file / CLI 辅助方法 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时 facade | + | `plugin-sdk/memory-core-host-engine-foundation` | Memory 主机基础引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机 embedding 契约、注册表访问、本地提供商，以及通用批处理 / 远程辅助方法 | + | `plugin-sdk/memory-core-host-engine-qmd` | Memory 主机 QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | Memory 主机存储引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | Memory 主机多模态辅助方法 | + | `plugin-sdk/memory-core-host-query` | Memory 主机查询辅助方法 | + | `plugin-sdk/memory-core-host-secret` | Memory 主机 secret 辅助方法 | + | `plugin-sdk/memory-core-host-events` | Memory 主机事件日志辅助方法 | + | `plugin-sdk/memory-core-host-status` | Memory 主机 Status 辅助方法 | + | `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时辅助方法 | + | `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时辅助方法 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件 / 运行时辅助方法 | + | `plugin-sdk/memory-host-core` | 面向厂商中立的别名，用于 Memory 主机核心运行时辅助方法 | + | `plugin-sdk/memory-host-events` | 面向厂商中立的别名，用于 Memory 主机事件日志辅助方法 | + | `plugin-sdk/memory-host-files` | 面向厂商中立的别名，用于 Memory 主机文件 / 运行时辅助方法 | + | `plugin-sdk/memory-host-markdown` | 面向 Memory 邻近插件的共享托管 Markdown 辅助方法 | + | `plugin-sdk/memory-host-search` | 面向 search-manager 访问的活跃 Memory 运行时 facade | + | `plugin-sdk/memory-host-status` | 面向厂商中立的别名，用于 Memory 主机 Status 辅助方法 | | `plugin-sdk/memory-lancedb` | 内置的 memory-lancedb 辅助接口 | - + | 家族 | 当前子路径 | 预期用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助工具。`browser-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 结构。`browser-support` 仍然是兼容性 barrel。 | + | 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-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 形态。`browser-support` 仍然是兼容性 barrel。 | | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助 / 运行时接口 | | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助 / 运行时接口 | | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 | - | 渠道专用辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/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` | + | 特定渠道辅助方法 | `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` | diff --git a/docs/zh-CN/providers/minimax.md b/docs/zh-CN/providers/minimax.md index 167d0f44f..89ba3ee4d 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-25T04:09:44Z" + generated_at: "2026-04-25T09:40:18Z" model: gpt-5.4 provider: openai - source_hash: 202b0852f3f1f484193d6f9a019b179c807dc13d7bed497f1122c36eae03e980 + source_hash: ddf6cfb68ef5fcaa360a2a7ebb9e3ce130100a59b014643091449a07654c7c6f source_path: providers/minimax.md workflow: 15 --- @@ -26,21 +26,21 @@ MiniMax 还提供： | Provider ID | 认证方式 | 能力 | | ---------------- | -------- | -------------------------------------------------------------- | -| `minimax` | API key | 文本、图像生成、图像理解、语音、网页搜索 | -| `minimax-portal` | OAuth | 文本、图像生成、图像理解 | +| `minimax` | API 密钥 | 文本、图像生成、图像理解、语音、网页搜索 | +| `minimax-portal` | OAuth | 文本、图像生成、图像理解、语音 | ## 内置目录 -| Model | 类型 | 描述 | -| ------------------------ | ---------------- | ---------------------------- | -| `MiniMax-M2.7` | 聊天（推理） | 默认托管推理模型 | -| `MiniMax-M2.7-highspeed` | 聊天（推理） | 更快的 M2.7 推理层级 | -| `MiniMax-VL-01` | 视觉 | 图像理解模型 | -| `image-01` | 图像生成 | 文生图和图像到图像编辑 | -| `music-2.5+` | 音乐生成 | 默认音乐模型 | -| `music-2.5` | 音乐生成 | 之前的音乐生成层级 | -| `music-2.0` | 音乐生成 | 旧版音乐生成层级 | -| `MiniMax-Hailuo-2.3` | 视频生成 | 文生视频和图像参考流程 | +| 模型 | 类型 | 说明 | +| ------------------------ | ---------------- | ---------------------------------------- | +| `MiniMax-M2.7` | 聊天（推理） | 默认托管推理模型 | +| `MiniMax-M2.7-highspeed` | 聊天（推理） | 更快的 M2.7 推理层级 | +| `MiniMax-VL-01` | 视觉 | 图像理解模型 | +| `image-01` | 图像生成 | 文生图和图像到图像编辑 | +| `music-2.5+` | 音乐生成 | 默认音乐模型 | +| `music-2.5` | 音乐生成 | 上一代音乐生成层级 | +| `music-2.0` | 音乐生成 | 旧版音乐生成层级 | +| `MiniMax-Hailuo-2.3` | 视频生成 | 文生视频和图像参考流程 | ## 入门指南 @@ -48,7 +48,7 @@ MiniMax 还提供： - **最适合：** 通过 OAuth 快速设置 MiniMax Coding Plan，无需 API key。 + **最适合：** 通过 OAuth 快速设置 MiniMax Coding Plan，无需 API 密钥。 @@ -58,7 +58,7 @@ MiniMax 还提供： openclaw onboard --auth-choice minimax-global-oauth ``` - 这会针对 `api.minimax.io` 进行认证。 + 这会对 `api.minimax.io` 进行认证。 ```bash @@ -74,7 +74,7 @@ MiniMax 还提供： openclaw onboard --auth-choice minimax-cn-oauth ``` - 这会针对 `api.minimaxi.com` 进行认证。 + 这会对 `api.minimaxi.com` 进行认证。 ```bash @@ -86,16 +86,16 @@ MiniMax 还提供： - OAuth 设置使用 `minimax-portal` provider id。模型引用采用 `minimax-portal/MiniMax-M2.7` 这种形式。 + OAuth 设置使用 `minimax-portal` 提供商 id。模型引用遵循 `minimax-portal/MiniMax-M2.7` 这种格式。 - MiniMax Coding Plan 推荐链接（九折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link) + MiniMax Coding Plan 邀请链接（9 折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link) - + **最适合：** 使用兼容 Anthropic API 的托管 MiniMax。 @@ -173,11 +173,11 @@ MiniMax 还提供： ``` - 在兼容 Anthropic 的流式传输路径上，除非你自行显式设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。MiniMax 的流式端点会以 OpenAI 风格的 delta 分块而不是原生 Anthropic thinking 块输出 `reasoning_content`，如果默认启用，可能会将内部推理泄露到可见输出中。 + 在兼容 Anthropic 的流式传输路径上，除非你显式自行设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。MiniMax 的流式端点会以 OpenAI 风格的 delta 分块而不是原生 Anthropic thinking 块发出 `reasoning_content`，如果在未显式配置的情况下保持启用，可能会将内部推理泄露到可见输出中。 - API key 设置使用 `minimax` provider id。模型引用采用 `minimax/MiniMax-M2.7` 这种形式。 + API 密钥设置使用 `minimax` 提供商 id。模型引用遵循 `minimax/MiniMax-M2.7` 这种格式。 @@ -185,7 +185,7 @@ MiniMax 还提供： ## 通过 `openclaw configure` 配置 -使用交互式配置向导来设置 MiniMax，而无需编辑 JSON： +使用交互式配置向导设置 MiniMax，而无需编辑 JSON： @@ -193,22 +193,22 @@ MiniMax 还提供： openclaw configure ``` - - 从菜单中选择 **Model/auth**。 + + 从菜单中选择 **模型/认证**。 - + 选择以下可用的 MiniMax 选项之一： - | 认证选项 | 描述 | + | 认证选项 | 说明 | | --- | --- | | `minimax-global-oauth` | 国际版 OAuth（Coding Plan） | | `minimax-cn-oauth` | 中国版 OAuth（Coding Plan） | - | `minimax-global-api` | 国际版 API key | - | `minimax-cn-api` | 中国版 API key | + | `minimax-global-api` | 国际版 API 密钥 | + | `minimax-cn-api` | 中国版 API 密钥 | - 在提示时选择你的默认模型。 + 在出现提示时选择你的默认模型。 @@ -220,8 +220,8 @@ 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 用于图像生成，请将其设置为图像生成提供商： @@ -238,42 +238,61 @@ MiniMax 插件会为 `image_generate` 工具注册 `image-01` 模型。它支持 该插件使用与文本模型相同的 `MINIMAX_API_KEY` 或 OAuth 认证。如果 MiniMax 已经设置完成，则无需额外配置。 -`minimax` 和 `minimax-portal` 都会用相同的 `image-01` 模型注册 `image_generate`。API key 设置使用 `MINIMAX_API_KEY`；OAuth 设置则可以改用内置的 `minimax-portal` 认证路径。 +`minimax` 和 `minimax-portal` 都会使用相同的 `image-01` 模型注册 `image_generate`。 +API 密钥设置使用 `MINIMAX_API_KEY`；OAuth 设置则可以改用内置的 +`minimax-portal` 认证路径。 -当新手引导或 API key 设置写入显式的 `models.providers.minimax` 条目时，OpenClaw 会将 `MiniMax-M2.7` 和 `MiniMax-M2.7-highspeed` 具体化为仅文本的聊天模型。图像理解则通过插件自有的 `MiniMax-VL-01` 媒体提供商单独暴露。 +当新手引导或 API 密钥设置写入显式的 `models.providers.minimax` +条目时，OpenClaw 会将 `MiniMax-M2.7` 和 +`MiniMax-M2.7-highspeed` 实体化为仅文本的聊天模型。图像理解则通过由插件拥有的 `MiniMax-VL-01` 媒体提供商单独提供。 -有关共享工具参数、提供商选择和故障切换行为，请参见 [Image Generation](/zh-CN/tools/image-generation)。 +共享工具参数、提供商选择和故障切换行为请参阅 [图像生成](/zh-CN/tools/image-generation)。 ### 文本转语音 -内置的 `minimax` 插件还会将 MiniMax T2A v2 注册为 `messages.tts` 的语音提供商。 +内置的 `minimax` 插件还会将 MiniMax T2A v2 注册为 +`messages.tts` 的语音提供商。 - 默认 TTS 模型：`speech-2.8-hd` -- 默认语音：`English_expressive_narrator` +- 默认音色：`English_expressive_narrator` +- 支持的内置模型 id 包括 `speech-2.8-hd`、`speech-2.8-turbo`、 + `speech-2.6-hd`、`speech-2.6-turbo`、`speech-02-hd`、 + `speech-02-turbo`、`speech-01-hd` 和 `speech-01-turbo`。 +- 认证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是 + `minimax-portal` OAuth/token 认证配置文件，再然后是 Token Plan 环境变量键 + （`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、 + `MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。 +- 如果未配置 TTS 主机，OpenClaw 会复用已配置的 + `minimax-portal` OAuth 主机，并去掉兼容 Anthropic 的路径后缀， + 例如 `/anthropic`。 - 普通音频附件保持为 MP3。 -- Feishu 和 Telegram 等语音便笺目标会通过 `ffmpeg` 从 MiniMax MP3 转码为 48 kHz Opus，因为 Feishu/Lark 文件 API 对原生音频消息只接受 `file_type: "opus"`。 -- MiniMax T2A 接受小数形式的 `speed` 和 `vol`，但 `pitch` 会以整数发送；OpenClaw 会在 API 请求前截断带小数的 `pitch` 值。 +- Feishu 和 Telegram 等语音便笺目标会通过 `ffmpeg` 从 MiniMax + MP3 转码为 48 kHz Opus，因为 Feishu/Lark 文件 API 对原生音频消息只接受 + `file_type: "opus"`。 +- MiniMax T2A 接受小数 `speed` 和 `vol`，但 `pitch` 会以整数发送； + OpenClaw 会在发起 API 请求前截断带小数的 `pitch` 值。 -| 设置 | 环境变量 | 默认值 | 描述 | +| 设置 | 环境变量 | 默认值 | 说明 | | ---------------------------------------- | ---------------------- | ----------------------------- | ---------------------------- | | `messages.tts.providers.minimax.baseUrl` | `MINIMAX_API_HOST` | `https://api.minimax.io` | MiniMax T2A API 主机。 | | `messages.tts.providers.minimax.model` | `MINIMAX_TTS_MODEL` | `speech-2.8-hd` | TTS 模型 id。 | -| `messages.tts.providers.minimax.voiceId` | `MINIMAX_TTS_VOICE_ID` | `English_expressive_narrator` | 用于语音输出的 voice id。 | +| `messages.tts.providers.minimax.voiceId` | `MINIMAX_TTS_VOICE_ID` | `English_expressive_narrator` | 用于语音输出的音色 id。 | | `messages.tts.providers.minimax.speed` | | `1.0` | 播放速度，`0.5..2.0`。 | | `messages.tts.providers.minimax.vol` | | `1.0` | 音量，`(0, 10]`。 | | `messages.tts.providers.minimax.pitch` | | `0` | 整数音高偏移，`-12..12`。 | ### 音乐生成 -内置的 `minimax` 插件还会通过共享的 `music_generate` 工具注册音乐生成能力。 +内置的 `minimax` 插件还会通过共享的 +`music_generate` 工具注册音乐生成功能。 - 默认音乐模型：`minimax/music-2.5+` -- 也支持 `minimax/music-2.5` 和 `minimax/music-2.0` +- 还支持 `minimax/music-2.5` 和 `minimax/music-2.0` - 提示词控制项：`lyrics`、`instrumental`、`durationSeconds` - 输出格式：`mp3` -- 基于会话的运行会通过共享的任务/状态流程分离执行，包括 `action: "status"` +- 基于会话的运行会通过共享的任务/Status 流程分离执行，包括 `action: "status"` 要将 MiniMax 用作默认音乐提供商： @@ -290,12 +309,13 @@ MiniMax 插件会为 `image_generate` 工具注册 `image-01` 模型。它支持 ``` -有关共享工具参数、提供商选择和故障切换行为，请参见 [Music Generation](/zh-CN/tools/music-generation)。 +共享工具参数、提供商选择和故障切换行为请参阅 [音乐生成](/zh-CN/tools/music-generation)。 ### 视频生成 -内置的 `minimax` 插件还会通过共享的 `video_generate` 工具注册视频生成能力。 +内置的 `minimax` 插件还会通过共享的 +`video_generate` 工具注册视频生成功能。 - 默认视频模型：`minimax/MiniMax-Hailuo-2.3` - 模式：文生视频和单图参考流程 @@ -316,65 +336,68 @@ MiniMax 插件会为 `image_generate` 工具注册 `image-01` 模型。它支持 ``` -有关共享工具参数、提供商选择和故障切换行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。 +共享工具参数、提供商选择和故障切换行为请参阅 [视频生成](/zh-CN/tools/video-generation)。 ### 图像理解 -MiniMax 插件将图像理解与文本目录分开注册： +MiniMax 插件将图像理解与文本 +目录分开注册： -| Provider ID | 默认图像模型 | -| ---------------- | ----------------- | -| `minimax` | `MiniMax-VL-01` | -| `minimax-portal` | `MiniMax-VL-01` | +| Provider ID | 默认图像模型 | +| ---------------- | ------------------- | +| `minimax` | `MiniMax-VL-01` | +| `minimax-portal` | `MiniMax-VL-01` | -这就是为什么即使内置的文本提供商目录仍然只显示仅文本的 M2.7 聊天引用，自动媒体路由仍然可以使用 MiniMax 图像理解。 +这就是为什么自动媒体路由即使在内置文本提供商目录仍显示仅文本的 M2.7 聊天引用时， +也可以使用 MiniMax 图像理解。 ### 网页搜索 -MiniMax 插件还会通过 MiniMax Coding Plan 搜索 API 注册 `web_search`。 +MiniMax 插件还会通过 MiniMax Coding Plan +搜索 API 注册 `web_search`。 -- Provider id：`minimax` +- 提供商 id：`minimax` - 结构化结果：标题、URL、摘要、相关查询 - 首选环境变量：`MINIMAX_CODE_PLAN_KEY` - 可接受的环境变量别名：`MINIMAX_CODING_API_KEY` -- 兼容性回退：如果 `MINIMAX_API_KEY` 已经指向 coding-plan token，则使用它 +- 兼容性回退：当 `MINIMAX_API_KEY` 已经指向 coding-plan token 时可使用它 - 区域复用：`plugins.entries.minimax.config.webSearch.region`，然后是 `MINIMAX_API_HOST`，再然后是 MiniMax 提供商基础 URL -- 搜索始终保留在 provider id `minimax` 上；OAuth 中国版/国际版设置仍然可以通过 `models.providers.minimax-portal.baseUrl` 间接引导区域 +- 搜索始终保留在提供商 id `minimax` 上；OAuth 中国版/国际版设置仍可通过 `models.providers.minimax-portal.baseUrl` 间接引导区域 配置位于 `plugins.entries.minimax.config.webSearch.*` 下。 -有关完整的网页搜索配置和用法，请参见 [MiniMax Search](/zh-CN/tools/minimax-search)。 +完整的网页搜索配置和用法请参阅 [MiniMax 搜索](/zh-CN/tools/minimax-search)。 ## 高级配置 - | 选项 | 描述 | + | 选项 | 说明 | | --- | --- | | `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 key（`MINIMAX_API_KEY`） | + | `models.providers.minimax.apiKey` | MiniMax API 密钥（`MINIMAX_API_KEY`） | | `models.providers.minimax.models` | 定义 `id`、`name`、`reasoning`、`contextWindow`、`maxTokens`、`cost` | - | `agents.defaults.models` | 为你想加入 allowlist 的模型设置别名 | + | `agents.defaults.models` | 为你希望加入 allowlist 的模型设置别名 | | `models.mode` | 如果你想在内置模型之外添加 MiniMax，请保持为 `merge` | 在 `api: "anthropic-messages"` 上，除非参数/配置中已经显式设置了 thinking，否则 OpenClaw 会注入 `thinking: { type: "disabled" }`。 - 这样可以防止 MiniMax 的流式端点以 OpenAI 风格的 delta 分块输出 `reasoning_content`，从而将内部推理泄露到可见输出中。 + 这样可以防止 MiniMax 的流式端点以 OpenAI 风格的 delta 分块发出 `reasoning_content`，从而将内部推理泄露到可见输出中。 - `/fast on` 或 `params.fastMode: true` 会在兼容 Anthropic 的流式路径上将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 + `/fast on` 或 `params.fastMode: true` 会在兼容 Anthropic 的流式路径上，将 `MiniMax-M2.7` 改写为 `MiniMax-M2.7-highspeed`。 - **最适合：** 将你最强的最新一代模型设为主模型，并在失败时回退到 MiniMax M2.7。下面的示例使用 Opus 作为一个具体的主模型；请替换为你偏好的最新一代主模型。 + **最适合：** 将你最强的最新一代模型保留为主模型，并在失败时回退到 MiniMax M2.7。下面的示例使用 Opus 作为具体的主模型；你可以替换为自己偏好的最新一代主模型。 ```json5 { @@ -396,51 +419,51 @@ MiniMax 插件还会通过 MiniMax Coding Plan 搜索 API 注册 `web_search`。 - + - Coding Plan 用量 API：`https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains`（需要 coding plan key）。 - - OpenClaw 会将 MiniMax coding-plan 用量规范化为与其他提供商相同的“剩余 %”显示。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 key 环境变量。 + - OpenClaw 会将 MiniMax coding-plan 用量标准化为与其他提供商相同的“剩余百分比”显示。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 key 环境变量。 ## 说明 - 模型引用遵循认证路径： - - API key 设置：`minimax/` + - API 密钥设置：`minimax/` - OAuth 设置：`minimax-portal/` - 默认聊天模型：`MiniMax-M2.7` - 备用聊天模型：`MiniMax-M2.7-highspeed` -- 新手引导和直接 API key 设置会为这两个 M2.7 变体写入仅文本的模型定义 -- 图像理解使用插件自有的 `MiniMax-VL-01` 媒体提供商 +- 新手引导和直接 API 密钥设置会为两个 M2.7 变体写入仅文本的模型定义 +- 图像理解使用由插件拥有的 `MiniMax-VL-01` 媒体提供商 - 如果你需要精确的成本跟踪，请更新 `models.json` 中的定价值 -- 使用 `openclaw models list` 确认当前 provider id，然后使用 `openclaw models set minimax/MiniMax-M2.7` 或 `openclaw models set minimax-portal/MiniMax-M2.7` 进行切换 +- 使用 `openclaw models list` 确认当前提供商 id，然后通过 `openclaw models set minimax/MiniMax-M2.7` 或 `openclaw models set minimax-portal/MiniMax-M2.7` 进行切换 -MiniMax Coding Plan 推荐链接（九折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link) +MiniMax Coding Plan 邀请链接（9 折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link) -有关提供商规则，请参见 [Model providers](/zh-CN/concepts/model-providers)。 +有关提供商规则，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。 ## 故障排除 - - 这通常意味着**MiniMax 提供商未配置**（没有匹配的提供商条目，且未找到 MiniMax 认证配置文件/环境变量 key）。这一检测的修复已包含在 **2026.1.12** 中。可按以下方式修复： + + 这通常意味着**MiniMax 提供商未配置**（没有匹配的提供商条目，且也未找到 MiniMax 认证配置文件/环境变量键）。此检测的修复已包含在 **2026.1.12** 中。可通过以下方式修复： - - 升级到 **2026.1.12**（或从源码 `main` 运行），然后重启 Gateway 网关。 + - 升级到 **2026.1.12**（或直接从源码 `main` 运行），然后重启 Gateway 网关。 - 运行 `openclaw configure` 并选择一个 **MiniMax** 认证选项，或 - 手动添加匹配的 `models.providers.minimax` 或 `models.providers.minimax-portal` 配置块，或 - - 设置 `MINIMAX_API_KEY`、`MINIMAX_OAUTH_TOKEN`，或设置一个 MiniMax 认证配置文件，以便注入匹配的提供商。 + - 设置 `MINIMAX_API_KEY`、`MINIMAX_OAUTH_TOKEN` 或 MiniMax 认证配置文件，以便注入匹配的提供商。 请确保模型 id **区分大小写**： - - API key 路径：`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed` + - 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 @@ -468,7 +491,7 @@ MiniMax Coding Plan 推荐链接（九折优惠）：[MiniMax Coding Plan](https 共享视频工具参数和提供商选择。 - + 通过 MiniMax Coding Plan 进行网页搜索配置。 diff --git a/docs/zh-CN/tools/slash-commands.md b/docs/zh-CN/tools/slash-commands.md index a95f56411..2f5b19a12 100644 --- a/docs/zh-CN/tools/slash-commands.md +++ b/docs/zh-CN/tools/slash-commands.md @@ -2,32 +2,32 @@ read_when: - 使用或配置聊天命令 - 调试命令路由或权限 -summary: 斜杠命令：文本与原生、配置以及支持的命令 +summary: 斜杠命令：文本与原生、配置，以及支持的命令 title: 斜杠命令 x-i18n: - generated_at: "2026-04-25T08:03:59Z" + generated_at: "2026-04-25T09:40:19Z" model: gpt-5.4 provider: openai - source_hash: bab969a72f10880b88a75a7a0cc7870989c826fbf7e9b8637a558cc29cfcc417 + source_hash: 55cac54aa58d04ebae9b0899d323438fa8a16db3d417147f281056157534644b source_path: tools/slash-commands.md workflow: 15 --- 命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。 -仅主机可用的 bash 聊天命令使用 `! `（`/bash ` 是它的别名）。 +仅主机可用的 bash 聊天命令使用 `! `（`/bash ` 是别名）。 这里有两个相关系统： - **命令**：独立的 `/...` 消息。 - **指令**：`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。 - - 指令会在模型看到消息之前从消息中剥离。 - - 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 - - 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话中，并回复一条确认消息。 - - 指令仅对**已授权发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则，授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。 - 未授权发送者会看到这些指令被当作普通文本处理。 + - 在模型看到消息之前，这些指令会从消息中剥离。 + - 在普通聊天消息中（不是纯指令消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 + - 在纯指令消息中（消息只包含指令），它们会持久化到会话，并回复一条确认消息。 + - 指令仅对**已授权的发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。 + 未授权的发送者会看到这些指令被当作普通文本处理。 还有一些**内联快捷方式**（仅限已列入允许列表/已授权的发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 -它们会立即运行，在模型看到消息之前被剥离，剩余文本则继续走正常流程。 +它们会立即执行，在模型看到消息前被剥离，剩余文本则继续走正常流程。 ## 配置 @@ -57,87 +57,87 @@ x-i18n: ``` - `commands.text`（默认 `true`）启用在聊天消息中解析 `/...`。 - - 在不支持原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设置为 `false`，文本命令仍然可用。 + - 在不支持原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。 - `commands.native`（默认 `"auto"`）注册原生命令。 - - 自动：在 Discord/Telegram 上开启；在 Slack 上关闭（直到你添加斜杠命令）；对不支持原生支持的提供商会被忽略。 + - 自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生能力的提供商则忽略。 - 设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。 - - `false` 会在启动时清除先前已在 Discord/Telegram 上注册的命令。Slack 命令在 Slack 应用中管理，不会被自动移除。 -- `commands.nativeSkills`（默认 `"auto"`）会在支持时以原生方式注册 **Skills** 命令。 - - 自动：在 Discord/Telegram 上开启；在 Slack 上关闭（Slack 需要为每个 Skill 单独创建一个斜杠命令）。 + - `false` 会在启动时清除之前在 Discord/Telegram 上注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。 +- `commands.nativeSkills`（默认 `"auto"`）在支持时以原生方式注册 **skill** 命令。 + - 自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 单独创建一个斜杠命令）。 - 设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 - `commands.bash`（默认 `false`）启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许列表）。 - `commands.bashForegroundMs`（默认 `2000`）控制 bash 在切换到后台模式前等待多长时间（`0` 表示立即转入后台）。 - `commands.config`（默认 `false`）启用 `/config`（读取/写入 `openclaw.json`）。 -- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入由 OpenClaw 管理的、位于 `mcp.servers` 下的 MCP 配置）。 +- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入由 OpenClaw 管理的 `mcp.servers` 下的 MCP 配置）。 - `commands.plugins`（默认 `false`）启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控制）。 - `commands.debug`（默认 `false`）启用 `/debug`（仅运行时覆盖）。 - `commands.restart`（默认 `true`）启用 `/restart` 以及 Gateway 网关重启工具操作。 -- `commands.ownerAllowFrom`（可选）为仅限所有者的命令/工具界面设置显式所有者允许列表。这与 `commands.allowFrom` 是分开的。 -- 每个渠道的 `channels..commands.enforceOwnerForCommands`（可选，默认 `false`）会使仅限所有者的命令在该界面上运行时要求**所有者身份**。当其为 `true` 时，发送者必须匹配一个已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的某个条目，或提供商原生的所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空的/无法解析的所有者候选列表，**都不**足够——仅限所有者的命令会在该渠道上默认拒绝。若你希望仅限所有者的命令只受 `ownerAllowFrom` 和标准命令允许列表控制，请保持此项关闭。 -- `commands.ownerDisplay` 控制系统提示中所有者 ID 的显示方式：`raw` 或 `hash`。 +- `commands.ownerAllowFrom`（可选）为仅限所有者的命令/工具界面设置显式所有者允许列表。它与 `commands.allowFrom` 分开。 +- 每个渠道的 `channels..commands.enforceOwnerForCommands`（可选，默认 `false`）会让仅限所有者的命令在该界面上必须由**所有者身份**执行。当设为 `true` 时，发送者必须匹配一个已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生的所有者元数据），或者在内部消息渠道上拥有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或空的/无法解析的所有者候选列表，**都不**足够——仅限所有者的命令会在该渠道上默认拒绝。若你希望仅限所有者的命令只受 `ownerAllowFrom` 和标准命令允许列表限制，请保持关闭。 +- `commands.ownerDisplay` 控制所有者 id 在系统提示中的显示方式：`raw` 或 `hash`。 - `commands.ownerDisplaySecret` 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 -- `commands.allowFrom`（可选）为命令授权设置按提供商区分的允许列表。配置后，它将成为命令和指令的唯一授权来源（渠道允许列表/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。 +- `commands.allowFrom`（可选）为命令授权设置按提供商划分的允许列表。配置后，它会成为命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商专属键会覆盖它。 - `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令强制执行允许列表/策略。 ## 命令列表 -当前唯一真实来源： +当前事实来源： - 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts` - 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts` - 插件命令来自插件中的 `registerCommand()` 调用 -- 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道界面以及已安装/已启用的插件 +- 你的 Gateway 网关上实际可用的命令仍取决于配置标志、渠道界面，以及已安装/已启用的插件 ### 核心内置命令 -今天可用的内置命令： +当前可用的内置命令： -- `/new [model]` 启动新会话；`/reset` 是重置别名。 -- `/reset soft [message]` 保留当前对话记录，丢弃复用的 CLI 后端会话 ID，并在原地重新运行启动/系统提示加载。 +- `/new [model]` 开始一个新会话；`/reset` 是重置别名。 +- `/reset soft [message]` 保留当前转录内容，丢弃复用的 CLI 后端会话 id，并就地重新运行启动/系统提示加载。 - `/compact [instructions]` 压缩会话上下文。参见 [/concepts/compaction](/zh-CN/concepts/compaction)。 - `/stop` 中止当前运行。 -- `/session idle ` 和 `/session max-age ` 管理线程绑定过期。 -- `/think ` 设置思考级别。可用选项来自当前模型的提供商配置文件；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也包括仅在支持时可用的自定义级别，例如 `xhigh`、`adaptive`、`max`，或二元 `on`。别名：`/thinking`、`/t`。 +- `/session idle ` 和 `/session max-age ` 管理线程绑定过期时间。 +- `/think ` 设置思考级别。可选项来自当前活动模型的提供商配置；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也可能有 `xhigh`、`adaptive`、`max` 或仅二元 `on` 这类自定义级别，但仅在支持时可用。别名：`/thinking`、`/t`。 - `/verbose on|off|full` 切换详细输出。别名：`/v`。 -- `/trace on|off` 为当前会话切换插件跟踪输出。 +- `/trace on|off` 为当前会话切换插件追踪输出。 - `/fast [status|on|off]` 显示或设置快速模式。 - `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。 -- `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。 +- `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。 - `/exec host= security= ask= node=` 显示或设置 exec 默认值。 - `/model [name|#|status]` 显示或设置模型。 - `/models [provider] [page] [limit=|size=|all]` 列出提供商，或列出某个提供商的模型。 - `/queue ` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及诸如 `debounce:2s cap:25 drop:summarize` 之类的选项。 - `/help` 显示简短帮助摘要。 - `/commands` 显示生成的命令目录。 -- `/tools [compact|verbose]` 显示当前智能体此刻可以使用的内容。 -- `/status` 显示执行/运行时状态，包括 `Execution`/`Runtime` 标签，以及在可用时显示提供商用量/配额。 -- `/crestodian ` 从所有者私信运行 Crestodian 设置与修复助手。 -- `/tasks` 列出当前会话中活跃/最近的后台任务。 -- `/context [list|detail|json]` 说明上下文是如何组装的。 +- `/tools [compact|verbose]` 显示当前智能体现在可以使用什么。 +- `/status` 显示执行/运行时状态，包括 `Execution`/`Runtime` 标签，以及可用时的提供商使用量/配额。 +- `/crestodian ` 从所有者私信中运行 Crestodian 设置和修复助手。 +- `/tasks` 列出当前会话的活动/最近后台任务。 +- `/context [list|detail|json]` 解释上下文是如何组装的。 - `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。 - `/export-trajectory [path]` 为当前会话导出一个 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。别名：`/trajectory`。 -- `/whoami` 显示你的发送者 ID。别名：`/id`。 -- `/skill [input]` 按名称运行一个 Skill。 -- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本命令。 +- `/whoami` 显示你的发送者 id。别名：`/id`。 +- `/skill [input]` 按名称运行一个 skill。 +- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。 - `/approve ` 处理 exec 审批提示。 -- `/btw ` 提出一个旁支问题，而不会改变未来的会话上下文。参见 [/tools/btw](/zh-CN/tools/btw)。 +- `/btw ` 提出一个旁支问题，而不改变未来的会话上下文。参见 [/tools/btw](/zh-CN/tools/btw)。 - `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。 - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。 - `/focus ` 将当前 Discord 线程或 Telegram 话题/对话绑定到一个会话目标。 - `/unfocus` 移除当前绑定。 -- `/agents` 列出当前会话中绑定到线程的智能体。 +- `/agents` 列出当前会话中线程绑定的智能体。 - `/kill ` 中止一个或所有正在运行的子智能体。 -- `/steer ` 向一个正在运行的子智能体发送引导。别名：`/tell`。 +- `/steer ` 向正在运行的子智能体发送引导。别名：`/tell`。 - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。 -- `/mcp show|get|set|unset` 读取或写入由 OpenClaw 管理的、位于 `mcp.servers` 下的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。 +- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。 - `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写操作仅限所有者。需要 `commands.plugins: true`。 -- `/debug show|set|unset|reset` 管理仅运行时配置覆盖。仅限所有者。需要 `commands.debug: true`。 -- `/usage off|tokens|full|cost` 控制每次响应的用量页脚，或打印本地成本摘要。 +- `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限所有者。需要 `commands.debug: true`。 +- `/usage off|tokens|full|cost` 控制每次响应的使用量页脚，或打印本地成本摘要。 - `/tts on|off|status|provider|limit|summary|audio|help` 控制 TTS。参见 [/tools/tts](/zh-CN/tools/tts)。 - `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用。 - `/activation mention|always` 设置群组激活模式。 - `/send on|off|inherit` 设置发送策略。仅限所有者。 -- `/bash ` 运行主机 shell 命令。仅文本命令。别名：`! `。需要 `commands.bash: true`，并且在 `tools.elevated` 允许列表中。 +- `/bash ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。 - `!poll [sessionId]` 检查后台 bash 作业。 - `!stop [sessionId]` 停止后台 bash 作业。 @@ -154,94 +154,88 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： 内置插件可以添加更多斜杠命令。此仓库中当前内置的命令： -- `/dreaming [on|off|status|help]` 切换 Memory Wiki dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。 +- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [Pairing](/zh-CN/channels/pairing)。 - `/phone status|arm [duration]|disarm` 临时启用高风险手机节点命令。 - `/voice status|list [limit]|set ` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。 - `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。 - `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置的 Codex app-server harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。 -- 仅限 QQ Bot 的命令： +- 仅 QQ Bot 可用的命令： - `/bot-ping` - `/bot-version` - `/bot-help` - `/bot-upgrade` - `/bot-logs` -### 动态 Skill 命令 +### 动态 skill 命令 -用户可调用的 Skills 也会作为斜杠命令公开： +用户可调用的 Skills 也会暴露为斜杠命令： - `/skill [input]` 始终可作为通用入口点使用。 -- Skills 也可能在 Skill/插件注册时显示为直接命令，例如 `/prose`。 -- 原生 Skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 +- skill 也可能在 skill/插件注册时显示为直接命令，例如 `/prose`。 +- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 -说明： +注意： -- 命令在命令与参数之间可接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 +- 命令接受在命令与参数之间使用可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，则该文本会被视为消息正文。 -- 要查看完整的提供商用量明细，请使用 `openclaw status --usage`。 +- 要查看完整的提供商使用量细分，请使用 `openclaw status --usage`。 - `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。 -- 在多账户渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账户的 `configWrites`。 -- `/usage` 控制每条响应的用量页脚；`/usage cost` 会根据 OpenClaw 会话日志打印本地成本摘要。 -- `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。 -- `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包或 `clawhub:`。 +- 在多账号渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账号的 `configWrites`。 +- `/usage` 控制每次响应的使用量页脚；`/usage cost` 会根据 OpenClaw 会话日志打印本地成本摘要。 +- `/restart` 默认启用；设置 `commands.restart: false` 可禁用。 +- `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规范：本地路径/归档、npm 包，或 `clawhub:`。 - `/plugins enable|disable` 会更新插件配置，并且可能提示你重启。 -- 仅限 Discord 的原生命令：`/vc join|leave|status` 控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。 -- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求已启用有效线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 +- 仅 Discord 原生命令：`/vc join|leave|status` 控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。 +- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求有效的线程绑定已启用（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 - ACP 命令参考和运行时行为： [ACP Agents](/zh-CN/tools/acp-agents)。 -- `/verbose` 用于调试和额外可见性；在正常使用中请保持其为**关闭**状态。 -- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的跟踪/调试行，并保持普通详细工具输出关闭。 +- `/verbose` 主要用于调试和额外可见性；正常使用时请保持**关闭**。 +- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通的详细工具输出关闭。 - `/fast on|off` 会持久化一个会话覆盖。使用 Sessions UI 中的 `inherit` 选项可清除它，并回退到配置默认值。 -- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公开 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 身份验证流量，则会映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 -- 工具失败摘要在相关时仍会显示，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。 -- `/reasoning`、`/verbose` 和 `/trace` 在群组场景中有风险：它们可能会暴露你本不打算公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。 +- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上映射为 `service_tier=priority`，而直接公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，则会映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 +- 相关时仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。 +- `/reasoning`、`/verbose` 和 `/trace` 在群组场景中有风险：它们可能泄露你本无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。 - `/model` 会立即持久化新的会话模型。 - 如果智能体处于空闲状态，下一次运行会立即使用它。 -- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并仅在一个干净的重试点重启进入新模型。 -- 如果工具活动或回复输出已经开始，这个待处理切换可能会一直排队，直到稍后的重试机会或下一次用户轮次。 -- 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 - Crestodian。这与消息渠道救援模式是分开的，也**不会** - 授予远程配置权限。 +- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并仅在合适的重试点重启到新模型。 +- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到稍后的重试机会或下一次用户输入。 +- 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。它与消息渠道救援模式分离，并且不会授予远程配置权限。 - **快速路径：** 来自允许列表发送者的纯命令消息会被立即处理（绕过队列 + 模型）。 - **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。 -- **内联快捷方式（仅限允许列表发送者）：** 某些命令在嵌入普通消息时也能工作，并会在模型看到剩余内容前被剥离。 - - 示例：`hey /status` 会触发一条状态回复，而剩余文本会继续走正常流程。 +- **内联快捷方式（仅限允许列表中的发送者）：** 某些命令嵌入普通消息时也能工作，并会在模型看到剩余文本前被剥离。 + - 示例：`hey /status` 会触发一条状态回复，剩余文本继续按正常流程处理。 - 当前包括：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - 未授权的纯命令消息会被静默忽略，而内联 `/...` 标记会被当作普通文本处理。 -- **Skill 命令：** `user-invocable` 的 Skills 会作为斜杠命令公开。名称会被清洗为 `a-z0-9_`（最多 32 个字符）；冲突时会添加数字后缀（例如 `_2`）。 - - `/skill [input]` 按名称运行一个 Skill（当原生命令限制阻止按 Skill 单独建命令时，这很有用）。 - - 默认情况下，Skill 命令会作为普通请求转发给模型。 - - Skills 也可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性、无模型）。 +- **skill 命令：** `user-invocable` Skills 也会暴露为斜杠命令。名称会被规范化为 `a-z0-9_`（最多 32 个字符）；冲突时会添加数字后缀（例如 `_2`）。 + - `/skill [input]` 按名称运行一个 skill（当原生命令限制阻止为每个 skill 创建单独命令时，这很有用）。 + - 默认情况下，skill 命令会作为普通请求转发给模型。 + - Skills 可选声明 `command-dispatch: tool`，以将命令直接路由到工具（确定性，无需模型）。 - 示例：`/prose`（OpenProse 插件）——参见 [OpenProse](/zh-CN/prose)。 -- **原生命令参数：** Discord 对动态选项使用自动补全（而当你省略必填参数时，则使用按钮菜单）。Telegram 和 Slack 会在某个命令支持选项且你省略该参数时显示按钮菜单。 +- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时也会使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。动态选项会根据目标会话模型解析，因此诸如 `/think` 级别这样的模型特定选项会遵循该会话的 `/model` 覆盖。 ## `/tools` -`/tools` 回答的是一个运行时问题，而不是一个配置问题：**这个智能体现在在 -这段对话中能使用什么**。 +`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体当前在这个对话中可以使用什么**。 -- 默认的 `/tools` 是紧凑模式，并针对快速浏览做了优化。 +- 默认的 `/tools` 是紧凑格式，并针对快速扫描进行了优化。 - `/tools verbose` 会添加简短说明。 -- 支持参数的原生命令界面会公开相同的模式切换，即 `compact|verbose`。 -- 结果是会话范围的，因此更改智能体、渠道、线程、发送者授权或模型都可能 - 改变输出。 -- `/tools` 包含在运行时实际可达的工具，包括核心工具、已连接的 - 插件工具，以及渠道拥有的工具。 +- 支持参数的原生命令界面也会通过 `compact|verbose` 暴露相同的模式切换。 +- 结果是会话作用域的，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。 +- `/tools` 包含那些在运行时真正可访问的工具，包括核心工具、已连接的插件工具，以及渠道拥有的工具。 -对于配置文件和覆盖项编辑，请使用 Control UI Tools 面板或配置/目录界面， -而不要将 `/tools` 视为静态目录。 +对于配置文件和覆盖编辑，请使用 Control UI Tools 面板或配置/目录界面，而不要把 `/tools` 当作静态目录。 -## 用量界面（各处显示内容） +## 使用量界面（不同位置显示什么） -- **提供商用量/配额**（例如：“Claude 剩余 80%”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一规范为“剩余百分比”；对于 MiniMax，只有剩余值的百分比字段会在显示前反转，而 `model_remains` 响应会优先选择聊天模型条目以及带模型标记的计划标签。 -- `/status` 中的 **token/缓存行** 在实时会话快照信息较少时，可以回退到最新的对话记录用量条目。现有的非零实时值仍然优先，而对话记录回退也可以在存储总量缺失或较小时恢复当前活动运行时模型标签以及更偏向提示词的总量。 -- **Execution 与 Runtime：** `/status` 会用 `Execution` 报告有效沙箱路径，并用 `Runtime` 报告实际运行该会话的是谁：`OpenClaw Pi Default`、`OpenAI Codex`、某个 CLI 后端，或 ACP 后端。 -- **每条响应的 token/成本** 由 `/usage off|tokens|full` 控制（附加到正常回复后）。 -- `/model status` 关注的是**模型/凭证/端点**，而不是用量。 +- **提供商使用量/配额**（例如：“Claude 还剩 80%”）会在启用使用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一规范为“剩余百分比”；对于 MiniMax，仅剩余百分比字段会在显示前取反，而 `model_remains` 响应会优先使用聊天模型条目加上带模型标签的套餐标签。 +- 当实时会话快照较稀疏时，`/status` 中的 **token/cache 行** 可以回退到最新转录使用量条目。现有的非零实时值仍然优先，而转录回退也可以在存储总量缺失或更小时恢复当前活动运行时模型标签以及更偏向提示词的更大总量。 +- **执行与运行时：** `/status` 使用 `Execution` 报告有效的沙箱路径，使用 `Runtime` 报告实际运行该会话的是谁：`OpenClaw Pi Default`、`OpenAI Codex`、某个 CLI 后端，或某个 ACP 后端。 +- **每次响应的 token/成本** 由 `/usage off|tokens|full` 控制（追加到普通回复后）。 +- `/model status` 关注的是**模型/凭证/端点**，而不是使用量。 ## 模型选择（`/model`） -`/model` 被实现为一个指令。 +`/model` 是作为指令实现的。 示例： @@ -254,12 +248,12 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /model status ``` -说明： +注意： - `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型家族 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，带有提供商和模型下拉菜单以及提交步骤。 -- `/model <#>` 会从该选择器中进行选择（并在可能时优先使用当前提供商）。 -- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用。 +- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及 Submit 步骤。 +- `/model <#>` 会从该选择器中进行选择（并尽可能优先当前提供商）。 +- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用的话。 ## 调试覆盖 @@ -275,14 +269,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /debug reset ``` -说明： +注意： -- 覆盖项会立即应用到新的配置读取中，但**不会**写入 `openclaw.json`。 -- 使用 `/debug reset` 清除所有覆盖项，并恢复到磁盘上的配置。 +- 覆盖会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。 +- 使用 `/debug reset` 清除所有覆盖，并恢复为磁盘上的配置。 -## 插件跟踪输出 +## 插件 trace 输出 -`/trace` 允许你在不启用完整详细模式的情况下，切换**会话范围的插件跟踪/调试行**。 +`/trace` 允许你切换**会话作用域的插件 trace/debug 行**，而无需开启完整详细模式。 示例： @@ -292,14 +286,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /trace off ``` -说明： +注意： -- 不带参数的 `/trace` 会显示当前会话的跟踪状态。 -- `/trace on` 会为当前会话启用插件跟踪行。 +- 不带参数的 `/trace` 会显示当前会话 trace 状态。 +- `/trace on` 会为当前会话启用插件 trace 行。 - `/trace off` 会再次禁用它们。 -- 插件跟踪行可能出现在 `/status` 中，也可能作为正常助手回复后的后续诊断消息出现。 -- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时配置覆盖。 -- `/trace` 不能替代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。 +- 插件 trace 行可能出现在 `/status` 中，也可能作为普通助手回复后的后续诊断消息出现。 +- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时的配置覆盖。 +- `/trace` 也不能替代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。 ## 配置更新 @@ -315,7 +309,7 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /config unset messages.responsePrefix ``` -说明： +注意： - 写入前会校验配置；无效更改会被拒绝。 - `/config` 更新会在重启后保留。 @@ -333,14 +327,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /mcp unset context7 ``` -说明： +注意： - `/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。 -- 运行时适配器决定哪些传输协议实际上可执行。 +- 实际可执行哪些传输由运行时适配器决定。 ## 插件更新 -`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。 +`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。 示例： @@ -352,36 +346,36 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /plugins disable context7 ``` -说明： +注意： -- `/plugins list` 和 `/plugins show` 会根据当前工作区和磁盘配置执行真实的插件发现。 -- `/plugins enable|disable` 只会更新插件配置；它不会安装或卸载插件。 -- 在启用/禁用更改后，请重启 Gateway 网关以应用它们。 +- `/plugins list` 和 `/plugins show` 会针对当前工作区以及磁盘上的配置执行真实的插件发现。 +- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。 +- 启用/禁用更改后，请重启 Gateway 网关以应用它们。 ## 界面说明 -- **文本命令** 在正常聊天会话中运行（私信共享 `main`，群组有各自独立的会话）。 +- **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有各自的会话）。 - **原生命令** 使用隔离会话： - Discord：`agent::discord:slash:` - Slack：`agent::slack:slash:`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置） - - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 指向聊天会话） -- **`/stop`** 以活动聊天会话为目标，因此可以中止当前运行。 -- **Slack：** `channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 等相同）。Slack 的命令参数菜单以临时 Block Kit 按钮形式提供。 - - Slack 原生命令例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留 `/status`。文本形式的 `/status` 在 Slack 消息中仍然可用。 + - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位聊天会话） +- **`/stop`** 作用于当前活动聊天会话，因此它可以中止当前运行。 +- **Slack：** `channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 等相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式发送。 + - Slack 原生命令例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留 `/status`。文本 `/status` 在 Slack 消息中仍然可用。 ## BTW 旁支问题 -`/btw` 是一个关于当前会话的快速**旁支问题**。 +`/btw` 是关于当前会话的一个快速**旁支问题**。 与普通聊天不同： -- 它会将当前会话用作背景上下文， -- 它会作为一次独立的**无工具**单次调用运行， +- 它使用当前会话作为背景上下文， +- 它作为单独的**无工具**一次性调用运行， - 它不会改变未来的会话上下文， -- 它不会写入对话记录历史， +- 它不会写入转录历史， - 它会作为实时旁支结果交付，而不是普通助手消息。 -这使得 `/btw` 在你想要一个临时澄清、同时主任务继续进行时非常有用。 +这使得 `/btw` 在你想要临时澄清、同时主任务继续进行时非常有用。 示例： diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index 006a1ceac..446b9aa94 100644 --- a/docs/zh-CN/tools/tts.md +++ b/docs/zh-CN/tools/tts.md @@ -3,19 +3,19 @@ read_when: - 为回复启用文本转语音 - 配置 TTS 提供商或限制 - 使用 `/tts` 命令 -summary: 用于外发回复的文本转语音（TTS） +summary: 用于出站回复的文本转语音（TTS） title: 文本转语音 x-i18n: - generated_at: "2026-04-25T08:51:49Z" + generated_at: "2026-04-25T09:40:24Z" model: gpt-5.4 provider: openai - source_hash: 14a2d014850395add532faef86659acae7fd6a8a5757f9dd7dac606c0780d278 + source_hash: 08d41c6d2179162508df8d856cb2d392b274f66abbbdbd3c5ee4f243ac389692 source_path: tools/tts.md workflow: 15 --- -OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax、OpenAI、Vydra、xAI 或 Xiaomi MiMo，将外发回复转换为音频。 -它适用于 OpenClaw 能够发送音频的任何场景。 +OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax、OpenAI、Vydra、xAI 或 Xiaomi MiMo 将出站回复转换为音频。 +只要 OpenClaw 能发送音频，它就能工作。 ## 支持的服务 @@ -31,10 +31,10 @@ OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax ### Microsoft 语音说明 -当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库，使用 Microsoft Edge 的在线神经 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 的端点，并且不需要 API 密钥。 -`node-edge-tts` 提供语音配置选项和输出格式，但并非所有选项都受到该服务支持。使用 `edge` 的旧版配置和指令输入仍然有效，并会被规范化为 `microsoft`。 +当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 端点，并且不需要 API 密钥。 +`node-edge-tts` 提供了语音配置选项和输出格式，但并非所有选项都受到该服务支持。使用 `edge` 的旧版配置和指令输入仍然可用，并会被规范化为 `microsoft`。 -由于这一路径是公共 Web 服务，没有公开发布的 SLA 或配额，请将其视为“尽力而为”服务。如果你需要有保证的限制和支持，请使用 OpenAI 或 ElevenLabs。 +由于此路径是一个没有公开 SLA 或配额的公共 Web 服务，请将其视为尽力而为的服务。如果你需要有保障的限制和支持，请使用 OpenAI 或 ElevenLabs。 ## 可选密钥 @@ -43,7 +43,9 @@ OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax - `ELEVENLABS_API_KEY`（或 `XI_API_KEY`） - `GEMINI_API_KEY`（或 `GOOGLE_API_KEY`） - `GRADIUM_API_KEY` -- `MINIMAX_API_KEY` +- `MINIMAX_API_KEY`；MiniMax TTS 也接受 Token Plan 身份验证，通过 + `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 + `MINIMAX_CODING_API_KEY` - `OPENAI_API_KEY` - `VYDRA_API_KEY` - `XAI_API_KEY` @@ -51,27 +53,27 @@ OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax Microsoft 语音**不**需要 API 密钥。 -如果配置了多个提供商，将优先使用所选提供商，其他提供商作为回退选项。 -自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，该提供商也必须完成认证。 +如果配置了多个提供商，则会首先使用所选提供商，其他提供商作为回退选项。 +自动摘要使用配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用摘要，对应提供商也必须完成身份验证。 ## 服务链接 -- [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech) -- [OpenAI Audio API 参考](https://platform.openai.com/docs/api-reference/audio) -- [ElevenLabs 文本转语音](https://elevenlabs.io/docs/api-reference/text-to-speech) -- [ElevenLabs 认证](https://elevenlabs.io/docs/api-reference/authentication) +- [OpenAI Text-to-Speech guide](https://platform.openai.com/docs/guides/text-to-speech) +- [OpenAI Audio API reference](https://platform.openai.com/docs/api-reference/audio) +- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) +- [ElevenLabs Authentication](https://elevenlabs.io/docs/api-reference/authentication) - [Gradium](/zh-CN/providers/gradium) - [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2) -- [Xiaomi MiMo 语音合成](/zh-CN/providers/xiaomi#text-to-speech) +- [Xiaomi MiMo speech synthesis](/zh-CN/providers/xiaomi#text-to-speech) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) -- [Microsoft Speech 输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) -- [xAI 文本转语音](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) +- [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) +- [xAI Text to Speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) ## 默认启用吗？ -不是。自动 TTS 默认是**关闭**的。可在配置中使用 `messages.tts.auto` 启用，或在本地使用 `/tts on` 启用。 +不会。自动 TTS 默认**关闭**。可在配置中使用 `messages.tts.auto` 启用，或通过 `/tts on` 在本地启用。 -当 `messages.tts.provider` 未设置时，OpenClaw 会按注册表自动选择顺序，选择第一个已配置的语音提供商。 +当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序挑选第一个已配置的语音提供商。 ## 配置 @@ -91,7 +93,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### OpenAI 主提供商 + ElevenLabs 回退 +### OpenAI 作为主要提供商，ElevenLabs 作为回退 ```json5 { @@ -132,7 +134,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### Microsoft 主提供商（无 API 密钥） +### Microsoft 作为主要提供商（无 API 密钥） ```json5 { @@ -155,7 +157,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### MiniMax 主提供商 +### MiniMax 作为主要提供商 ```json5 { @@ -179,7 +181,9 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### Google Gemini 主提供商 +MiniMax TTS 的身份验证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是已存储的 `minimax-portal` OAuth/token 配置文件，然后是 Token Plan 环境变量密钥（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。当未显式设置 TTS `baseUrl` 时，OpenClaw 可以复用已配置的 `minimax-portal` OAuth 主机用于 Token Plan 语音。 + +### Google Gemini 作为主要提供商 ```json5 { @@ -199,10 +203,9 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限定为 Gemini API 的 Google Cloud Console API 密钥，其形式与内置 Google 图像生成提供商使用的密钥相同。解析顺序为： -`messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`。 +Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 Gemini API 的 Google Cloud Console API 密钥，它与内置 Google 图像生成提供商使用的是同一种密钥风格。解析顺序为 `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`。 -### xAI 主提供商 +### xAI 作为主要提供商 ```json5 { @@ -224,10 +227,9 @@ Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限定为 G } ``` -xAI TTS 与内置 Grok 模型提供商使用相同的 `XAI_API_KEY` 路径。解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。 -当前可用的实时语音有 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值为 `eve`。`language` 接受 BCP-47 标签或 `auto`。 +xAI TTS 使用与内置 Grok 模型提供商相同的 `XAI_API_KEY` 路径。解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。当前可用的实时声音为 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值为 `eve`。`language` 接受 BCP-47 标签或 `auto`。 -### Xiaomi MiMo 主提供商 +### Xiaomi MiMo 作为主要提供商 ```json5 { @@ -250,9 +252,9 @@ xAI TTS 与内置 Grok 模型提供商使用相同的 `XAI_API_KEY` 路径。解 } ``` -Xiaomi MiMo TTS 与内置 Xiaomi 模型提供商使用相同的 `XIAOMI_API_KEY` 路径。语音提供商 ID 是 `xiaomi`；`mimo` 可作为别名使用。目标文本会作为 assistant message 发送，以匹配 Xiaomi 的 TTS 协议。可选的 `style` 会作为 user instruction 发送，不会被朗读。 +Xiaomi MiMo TTS 使用与内置 Xiaomi 模型提供商相同的 `XIAOMI_API_KEY` 路径。语音提供商 id 是 `xiaomi`；`mimo` 也可作为别名。目标文本会作为 assistant message 发送，以匹配 Xiaomi 的 TTS 契约。可选的 `style` 会作为用户指令发送，并且不会被朗读。 -### OpenRouter 主提供商 +### OpenRouter 作为主要提供商 ```json5 { @@ -273,11 +275,9 @@ Xiaomi MiMo TTS 与内置 Xiaomi 模型提供商使用相同的 `XIAOMI_API_KEY` } ``` -OpenRouter TTS 与内置 OpenRouter 模型提供商使用相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 -`messages.tts.providers.openrouter.apiKey` -> -`models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。 +OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 `messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。 -### Gradium 主提供商 +### Gradium 作为主要提供商 ```json5 { @@ -328,7 +328,7 @@ OpenRouter TTS 与内置 OpenRouter 模型提供商使用相同的 `OPENROUTER_A } ``` -### 仅在收到入站语音消息后以音频回复 +### 仅在收到入站语音消息后使用音频回复 ```json5 { @@ -361,28 +361,28 @@ OpenRouter TTS 与内置 OpenRouter 模型提供商使用相同的 `OPENROUTER_A ### 字段说明 - `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。 - - `inbound` 仅在收到入站语音消息后发送音频。 - - `tagged` 仅当回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。 + - `inbound` 仅会在收到入站语音消息后发送音频。 + - `tagged` 仅会在回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。 - `enabled`：旧版开关（`doctor` 会将其迁移到 `auto`）。 - `mode`：`"final"`（默认）或 `"all"`（包括工具/分块回复）。 -- `provider`：语音提供商 ID，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"microsoft"`、`"minimax"`、`"openai"`、`"vydra"`、`"xai"` 或 `"xiaomi"`（回退会自动处理）。 +- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"microsoft"`、`"minimax"`、`"openai"`、`"vydra"`、`"xai"` 或 `"xiaomi"`（回退会自动处理）。 - 如果 `provider` **未设置**，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。 - 旧版 `provider: "edge"` 配置可通过 `openclaw doctor --fix` 修复，并重写为 `provider: "microsoft"`。 -- `summaryModel`：用于自动摘要的可选低成本模型；默认为 `agents.defaults.model.primary`。 +- `summaryModel`：用于自动摘要的可选低成本模型；默认值为 `agents.defaults.model.primary`。 - 接受 `provider/model` 或已配置的模型别名。 - `modelOverrides`：允许模型发出 TTS 指令（默认开启）。 - `allowProvider` 默认为 `false`（切换提供商需要显式启用）。 -- `providers.`：由提供商自行管理、以语音提供商 ID 为键的设置。 +- `providers.`：由提供商拥有的设置，以语音提供商 id 为键。 - 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可通过 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.`。 - 旧版 `messages.tts.providers.edge` 也可通过 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.microsoft`。 -- `maxTextLength`：TTS 输入的硬上限（字符数）。如果超过此限制，`/tts audio` 会失败。 +- `maxTextLength`：TTS 输入的硬性上限（字符数）。超过时，`/tts audio` 会失败。 - `timeoutMs`：请求超时（毫秒）。 -- `prefsPath`：覆盖本地偏好设置 JSON 路径（提供商/限制/摘要）。 -- `apiKey` 值可回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`、`XIAOMI_API_KEY`）。 +- `prefsPath`：覆盖本地偏好 JSON 路径（提供商/限制/摘要）。 +- `apiKey` 值会回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`、`XIAOMI_API_KEY`）。 - `providers.elevenlabs.baseUrl`：覆盖 ElevenLabs API 基础 URL。 - `providers.openai.baseUrl`：覆盖 OpenAI TTS 端点。 - 解析顺序：`messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - 非默认值会被视为兼容 OpenAI 的 TTS 端点，因此接受自定义模型名和语音名。 + - 非默认值会被视为与 OpenAI 兼容的 TTS 端点，因此接受自定义模型名和语音名。 - `providers.elevenlabs.voiceSettings`： - `stability`、`similarityBoost`、`style`：`0..1` - `useSpeakerBoost`：`true|false` @@ -395,51 +395,50 @@ OpenRouter TTS 与内置 OpenRouter 模型提供商使用相同的 `OPENROUTER_A - `providers.minimax.voiceId`：语音标识符（默认 `English_expressive_narrator`，环境变量：`MINIMAX_TTS_VOICE_ID`）。 - `providers.minimax.speed`：播放速度 `0.5..2.0`（默认 1.0）。 - `providers.minimax.vol`：音量 `(0, 10]`（默认 1.0；必须大于 0）。 -- `providers.minimax.pitch`：整数音高偏移 `-12..12`（默认 0）。调用 MiniMax T2A 前会截断小数值，因为该 API 拒绝非整数音高值。 +- `providers.minimax.pitch`：整数音高偏移 `-12..12`（默认 0）。在调用 MiniMax T2A 前，小数值会被截断，因为该 API 会拒绝非整数音高值。 - `providers.google.model`：Gemini TTS 模型（默认 `gemini-3.1-flash-tts-preview`）。 - `providers.google.voiceName`：Gemini 预设语音名称（默认 `Kore`；也接受 `voice`）。 -- `providers.google.audioProfile`：在朗读文本前附加的自然语言风格提示。 -- `providers.google.speakerName`：可选说话人标签；当你的 TTS 提示使用命名说话人时，会在朗读文本前附加。 -- `providers.google.baseUrl`：覆盖 Gemini API 基础 URL。只接受 `https://generativelanguage.googleapis.com`。 +- `providers.google.audioProfile`：在朗读文本前添加的自然语言风格提示。 +- `providers.google.speakerName`：可选说话者标签；当你的 TTS 提示使用命名说话者时，会在朗读文本前添加。 +- `providers.google.baseUrl`：覆盖 Gemini API 基础 URL。仅接受 `https://generativelanguage.googleapis.com`。 - 如果省略 `messages.tts.providers.google.apiKey`，TTS 可以在回退到环境变量之前复用 `models.providers.google.apiKey`。 - `providers.gradium.baseUrl`：覆盖 Gradium API 基础 URL（默认 `https://api.gradium.ai`）。 - `providers.gradium.voiceId`：Gradium 语音标识符（默认 Emma，`YTpq7expH9539ERJ`）。 - `providers.xai.apiKey`：xAI TTS API 密钥（环境变量：`XAI_API_KEY`）。 - `providers.xai.baseUrl`：覆盖 xAI TTS 基础 URL（默认 `https://api.x.ai/v1`，环境变量：`XAI_BASE_URL`）。 -- `providers.xai.voiceId`：xAI 语音 ID（默认 `eve`；当前可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。 +- `providers.xai.voiceId`：xAI 语音 id（默认 `eve`；当前可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。 - `providers.xai.language`：BCP-47 语言代码或 `auto`（默认 `en`）。 - `providers.xai.responseFormat`：`mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`（默认 `mp3`）。 - `providers.xai.speed`：提供商原生速度覆盖值。 - `providers.xiaomi.apiKey`：Xiaomi MiMo API 密钥（环境变量：`XIAOMI_API_KEY`）。 - `providers.xiaomi.baseUrl`：覆盖 Xiaomi MiMo API 基础 URL（默认 `https://api.xiaomimimo.com/v1`，环境变量：`XIAOMI_BASE_URL`）。 - `providers.xiaomi.model`：TTS 模型（默认 `mimo-v2.5-tts`，环境变量：`XIAOMI_TTS_MODEL`；也支持 `mimo-v2-tts`）。 -- `providers.xiaomi.voice`：MiMo 语音 ID（默认 `mimo_default`，环境变量：`XIAOMI_TTS_VOICE`）。 +- `providers.xiaomi.voice`：MiMo 语音 id（默认 `mimo_default`，环境变量：`XIAOMI_TTS_VOICE`）。 - `providers.xiaomi.format`：`mp3` 或 `wav`（默认 `mp3`，环境变量：`XIAOMI_TTS_FORMAT`）。 -- `providers.xiaomi.style`：可选的自然语言风格指令，作为 user message 发送；不会被朗读。 +- `providers.xiaomi.style`：可选的自然语言风格指令，会作为 user message 发送；不会被朗读。 - `providers.openrouter.apiKey`：OpenRouter API 密钥（环境变量：`OPENROUTER_API_KEY`；可复用 `models.providers.openrouter.apiKey`）。 - `providers.openrouter.baseUrl`：覆盖 OpenRouter TTS 基础 URL（默认 `https://openrouter.ai/api/v1`；旧版 `https://openrouter.ai/v1` 会被规范化）。 -- `providers.openrouter.model`：OpenRouter TTS 模型 ID（默认 `hexgrad/kokoro-82m`；也接受 `modelId`）。 -- `providers.openrouter.voice`：提供商特定语音 ID（默认 `af_alloy`；也接受 `voiceId`）。 +- `providers.openrouter.model`：OpenRouter TTS 模型 id（默认 `hexgrad/kokoro-82m`；也接受 `modelId`）。 +- `providers.openrouter.voice`：提供商特定语音 id（默认 `af_alloy`；也接受 `voiceId`）。 - `providers.openrouter.responseFormat`：`mp3` 或 `pcm`（默认 `mp3`）。 - `providers.openrouter.speed`：提供商原生速度覆盖值。 -- `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；不需要 API 密钥）。 -- `providers.microsoft.voice`：Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。 +- `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；无 API 密钥）。 +- `providers.microsoft.voice`：Microsoft 神经网络语音名称（例如 `en-US-MichelleNeural`）。 - `providers.microsoft.lang`：语言代码（例如 `en-US`）。 - `providers.microsoft.outputFormat`：Microsoft 输出格式（例如 `audio-24khz-48kbitrate-mono-mp3`）。 - - 有效值请参见 Microsoft Speech 输出格式；并非所有格式都受内置的 Edge 后端传输支持。 + - 有效值请参见 Microsoft Speech 输出格式；并非所有格式都受内置的基于 Edge 的传输支持。 - `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`：百分比字符串（例如 `+10%`、`-5%`）。 - `providers.microsoft.saveSubtitles`：在音频文件旁写入 JSON 字幕。 -- `providers.microsoft.proxy`：Microsoft 语音请求使用的代理 URL。 +- `providers.microsoft.proxy`：Microsoft 语音请求的代理 URL。 - `providers.microsoft.timeoutMs`：请求超时覆盖值（毫秒）。 -- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 - `openclaw doctor --fix` 可将持久化配置重写为 `providers.microsoft`。 +- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 `openclaw doctor --fix` 可将持久化配置重写为 `providers.microsoft`。 -## 模型驱动的覆盖项（默认开启） +## 模型驱动的覆盖（默认开启） 默认情况下，模型**可以**为单条回复发出 TTS 指令。 -当 `messages.tts.auto` 为 `tagged` 时，必须使用这些指令才能触发音频。 +当 `messages.tts.auto` 为 `tagged` 时，必须有这些指令才会触发音频。 -启用后，模型可以发出 `[[tts:...]]` 指令来覆盖单条回复的语音设置，还可以附加一个可选的 `[[tts:text]]...[[/tts:text]]` 块，以提供只应出现在音频中的表现性标记（笑声、唱歌提示等）。 +启用后，模型可以发出 `[[tts:...]]` 指令，为单条回复覆盖语音设置；还可以附带一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于提供表现性标签（笑声、唱歌提示等），这些内容应只出现在音频中。 除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 @@ -452,14 +451,14 @@ Here you go. [[tts:text]](laughs) Read the song once more.[[/tts:text]] ``` -可用的指令键（启用时）： +可用指令键（启用时）： -- `provider`（已注册的语音提供商 ID，例如 `openai`、`elevenlabs`、`google`、`gradium`、`minimax`、`microsoft`、`vydra`、`xai` 或 `xiaomi`；需要 `allowProvider: true`） +- `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`google`、`gradium`、`minimax`、`microsoft`、`vydra`、`xai` 或 `xiaomi`；需要 `allowProvider: true`） - `voice`（OpenAI、Gradium 或 Xiaomi 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音），或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI） -- `model`（OpenAI TTS 模型、ElevenLabs 模型 ID、MiniMax 模型或 Xiaomi MiMo TTS 模型）或 `google_model`（Google TTS 模型） +- `model`（OpenAI TTS 模型、ElevenLabs model id、MiniMax 模型或 Xiaomi MiMo TTS 模型）或 `google_model`（Google TTS 模型） - `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost` - `vol` / `volume`（MiniMax 音量，0-10） -- `pitch`（MiniMax 整数音高，-12 到 12；在发起 MiniMax 请求前会截断小数值） +- `pitch`（MiniMax 整数音高，-12 到 12；在发送 MiniMax 请求前，小数值会被截断） - `applyTextNormalization`（`auto|on|off`） - `languageCode`（ISO 639-1） - `seed` @@ -478,7 +477,7 @@ Here you go. } ``` -可选允许列表（启用提供商切换，同时保留其他参数可配置）： +可选允许列表（启用提供商切换，同时保持其他参数可配置）： ```json5 { @@ -496,9 +495,7 @@ Here you go. ## 每用户偏好设置 -斜杠命令会将本地覆盖项写入 `prefsPath`（默认： -`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 -`messages.tts.prefsPath` 覆盖）。 +斜杠命令会将本地覆盖写入 `prefsPath`（默认值：`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。 存储的字段： @@ -507,45 +504,45 @@ Here you go. - `maxLength`（摘要阈值；默认 1500 个字符） - `summarize`（默认 `true`） -这些字段会在该主机上覆盖 `messages.tts.*`。 +这些设置会覆盖该主机上的 `messages.tts.*`。 ## 输出格式（固定） - **Feishu / Matrix / Telegram / WhatsApp**：语音便笺回复优先使用 Opus（ElevenLabs 使用 `opus_48000_64`，OpenAI 使用 `opus`）。 - - 48 kHz / 64 kbps 是语音消息的良好折中方案。 -- **Feishu**：当语音便笺回复生成为 MP3/WAV/M4A 或其他可能的音频文件时，Feishu 插件会在发送原生 `audio` 气泡前，使用 `ffmpeg` 将其转码为 48 kHz Ogg/Opus。如果转换失败，Feishu 会收到原始文件作为附件。 + - 48 kHz / 64 kbps 是语音消息的一个较好折中。 +- **Feishu**：当语音便笺回复以 MP3/WAV/M4A 或其他可能的音频文件格式生成时，Feishu 插件会在发送原生 `audio` 气泡前，先使用 `ffmpeg` 将其转码为 48 kHz Ogg/Opus。如果转换失败，Feishu 会收到原始文件作为附件。 - **其他渠道**：MP3（ElevenLabs 使用 `mp3_44100_128`，OpenAI 使用 `mp3`）。 - 44.1 kHz / 128 kbps 是语音清晰度的默认平衡点。 -- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在投递前使用 `ffmpeg` 将 MiniMax 的 MP3 转码为 48 kHz Opus。 -- **Xiaomi MiMo**：默认使用 MP3，或在配置时使用 WAV。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在投递前使用 `ffmpeg` 将 Xiaomi 的输出转码为 48 kHz Opus。 +- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在投递前使用 `ffmpeg` 将 MiniMax MP3 转码为 48 kHz Opus。 +- **Xiaomi MiMo**：默认使用 MP3，配置后也可使用 WAV。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在投递前使用 `ffmpeg` 将 Xiaomi 输出转码为 48 kHz Opus。 - **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于音频附件，并为 Talk/电话场景直接返回 PCM。此路径不支持原生 Opus 语音便笺格式。 - **Gradium**：音频附件使用 WAV，语音便笺目标使用 Opus，电话场景使用 8 kHz 的 `ulaw_8000`。 -- **xAI**：默认使用 MP3；`responseFormat` 可为 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批处理 REST TTS 端点，并返回完整的音频附件；此提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。 +- **xAI**：默认使用 MP3；`responseFormat` 可以是 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批量 REST TTS 端点，并返回完整的音频附件；此提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。 - **Microsoft**：使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。 - - 内置传输支持 `outputFormat`，但并非所有格式都可从该服务获得。 + - 内置传输接受 `outputFormat`，但并非所有格式都可从该服务获得。 - 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。 - - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保证的 Opus 语音消息，请使用 OpenAI 或 ElevenLabs。 - - 如果配置的 Microsoft 输出格式失败，OpenClaw 会回退并重试使用 MP3。 + - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保障的 Opus 语音消息，请使用 OpenAI 或 ElevenLabs。 + - 如果已配置的 Microsoft 输出格式失败，OpenClaw 会回退重试 MP3。 -OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 +OpenAI/ElevenLabs 输出格式按渠道固定（见上文）。 ## 自动 TTS 行为 启用后，OpenClaw 会： - 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。 -- 跳过过短的回复（少于 10 个字符）。 -- 在启用时使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复生成摘要。 +- 跳过非常短的回复（少于 10 个字符）。 +- 在启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复生成摘要。 - 将生成的音频附加到回复中。 -如果回复超过 `maxLength`，且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。 +如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。 ## 流程图 ``` 回复 -> 已启用 TTS？ 否 -> 发送文本 - 是 -> 是否包含媒体 / `MEDIA:` / 过短？ + 是 -> 是否包含媒体 / MEDIA: / 过短？ 是 -> 发送文本 否 -> 长度 > 限制？ 否 -> TTS -> 附加音频 @@ -560,7 +557,7 @@ OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 只有一个命令：`/tts`。 启用详情请参见 [斜杠命令](/zh-CN/tools/slash-commands)。 -Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那里将原生命令注册为 `/voice`。文本形式的 `/tts ...` 仍然可用。 +Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在该平台将 `/voice` 注册为原生命令。文本形式的 `/tts ...` 仍然可用。 ``` /tts off @@ -574,24 +571,24 @@ Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那 说明： -- 命令要求发送者已获授权（允许列表/所有者规则仍然适用）。 +- 命令需要已授权的发送者（允许列表/所有者规则仍然适用）。 - 必须启用 `commands.text` 或原生命令注册。 - 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。 - `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。 -- 当你希望默认使用 `inbound` 或 `tagged` 时，请使用配置。 -- `limit` 和 `summary` 存储在本地偏好设置中，而不是主配置中。 -- `/tts audio` 会生成一次性的音频回复（不会将 TTS 切换为开启）。 +- 如果你希望默认使用 `inbound` 或 `tagged`，请使用配置。 +- `limit` 和 `summary` 存储在本地偏好中，而不是主配置中。 +- `/tts audio` 会生成一次性音频回复（不会将 TTS 切换为开启）。 - `/tts status` 包含最近一次尝试的回退可见性： - - 成功回退：`Fallback: -> ` 加 `Attempts: ...` - - 失败：`Error: ...` 加 `Attempts: ...` + - 成功回退：`Fallback: -> `，以及 `Attempts: ...` + - 失败：`Error: ...`，以及 `Attempts: ...` - 详细诊断：`Attempt details: provider:outcome(reasonCode) latency` -- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 ID（当提供商返回时），这些信息会显示在 TTS 错误/日志中。 +- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（如果提供商返回），这些信息会显示在 TTS 错误/日志中。 ## 智能体工具 -`tts` 工具可将文本转换为语音，并返回用于回复投递的音频附件。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会以语音消息而不是文件附件的形式投递。 -当 `ffmpeg` 可用时，Feishu 可以在此路径中对非 Opus 的 TTS 输出进行转码。 -它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是按调用设置的提供商请求超时时间，单位为毫秒。 +`tts` 工具可将文本转换为语音，并返回一个用于回复投递的音频附件。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会作为语音消息而不是文件附件投递。 +当 `ffmpeg` 可用时，Feishu 可以在此路径上对非 Opus 的 TTS 输出进行转码。 +它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是每次调用的提供商请求超时时间，单位为毫秒。 ## Gateway 网关 RPC