From 2bce2635bd7c677915fb2732c6bcd8884db1b7d5 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 18:15:19 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/whatsapp.md | 218 +++---- docs/zh-CN/gateway/configuration-reference.md | 590 +++++++++--------- docs/zh-CN/plugins/hooks.md | 170 +++-- docs/zh-CN/plugins/sdk-migration.md | 457 +++++++------- docs/zh-CN/plugins/sdk-provider-plugins.md | 229 ++++--- docs/zh-CN/plugins/sdk-subpaths.md | 216 +++---- docs/zh-CN/providers/litellm.md | 91 ++- docs/zh-CN/reference/transcript-hygiene.md | 137 ++-- docs/zh-CN/tools/browser.md | 540 ++++++++-------- docs/zh-CN/tools/image-generation.md | 203 +++--- docs/zh-CN/tools/tts.md | 271 ++++---- 11 files changed, 1550 insertions(+), 1572 deletions(-) diff --git a/docs/zh-CN/channels/whatsapp.md b/docs/zh-CN/channels/whatsapp.md index 65a100b52..ceb5454a6 100644 --- a/docs/zh-CN/channels/whatsapp.md +++ b/docs/zh-CN/channels/whatsapp.md @@ -1,29 +1,29 @@ --- read_when: - 处理 WhatsApp/web 渠道行为或收件箱路由 -summary: WhatsApp 渠道支持、访问控制、传递行为和运维 +summary: WhatsApp 渠道支持、访问控制、投递行为和运维 title: WhatsApp x-i18n: - generated_at: "2026-04-25T11:16:05Z" + generated_at: "2026-04-25T18:12:19Z" model: gpt-5.4 provider: openai - source_hash: cf31e099230c65d9a97b976b11218b0c0bd4559e7917cdcf9b393633443528b4 + source_hash: 0935e7ac3676c57d83173a6dd9eedc489f77b278dfbc47bd811045078ee7e4d0 source_path: channels/whatsapp.md workflow: 15 --- -Status：通过 WhatsApp Web（Baileys）已达到生产就绪。Gateway 网关拥有已关联的会话。 +Status：通过 WhatsApp Web（Baileys）达到生产就绪。Gateway 网关拥有已关联的会话。 ## 安装（按需） - 新手引导（`openclaw onboard`）和 `openclaw channels add --channel whatsapp` - 会在你第一次选择它时提示安装 WhatsApp 插件。 + 会在你首次选择该插件时提示安装 WhatsApp 插件。 - `openclaw channels login --channel whatsapp` 也会在 - 插件尚未存在时提供安装流程。 + 插件尚未安装时提供安装流程。 - 开发渠道 + git 检出：默认使用本地插件路径。 - Stable/Beta：默认使用 npm 包 `@openclaw/whatsapp`。 -仍然可以手动安装： +仍然支持手动安装： ```bash openclaw plugins install @openclaw/whatsapp @@ -31,7 +31,7 @@ openclaw plugins install @openclaw/whatsapp - 未知发送者的默认私信策略是配对。 + 对于未知发件人，默认私信策略是配对。 跨渠道诊断和修复操作手册。 @@ -61,7 +61,7 @@ openclaw plugins install @openclaw/whatsapp - + ```bash openclaw channels login --channel whatsapp @@ -82,7 +82,7 @@ openclaw channels login --channel whatsapp --account work - + ```bash openclaw gateway @@ -97,22 +97,22 @@ openclaw pairing list whatsapp openclaw pairing approve whatsapp ``` - 配对请求会在 1 小时后过期。每个渠道的待处理请求上限为 3 个。 + 配对请求会在 1 小时后过期。每个渠道最多保留 3 个待处理请求。 -OpenClaw 建议你尽可能为 WhatsApp 使用单独的号码。（渠道元数据和设置流程都针对这种设置进行了优化，但也支持个人号码设置。） +OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据和设置流程已针对该方案优化，但也支持个人号码方案。） ## 部署模式 - 这是最简洁的运维模式： + 这是最清晰的运维模式： - - 为 OpenClaw 使用独立的 WhatsApp 身份 + - 为 OpenClaw 使用单独的 WhatsApp 身份 - 更清晰的私信允许列表和路由边界 - 更低的自聊混淆概率 @@ -132,18 +132,18 @@ OpenClaw 建议你尽可能为 WhatsApp 使用单独的号码。（渠道元数 - 新手引导支持个人号码模式，并会写入一个对自聊友好的基线配置： + 新手引导支持个人号码模式，并会写入适合自聊的基础配置： - `dmPolicy: "allowlist"` - `allowFrom` 包含你的个人号码 - `selfChatMode: true` - 在运行时，自聊保护依赖已关联的自身号码和 `allowFrom`。 + 在运行时，自聊保护机制会根据已关联的自身号码和 `allowFrom` 生效。 - 在当前的 OpenClaw 渠道架构中，该消息平台渠道基于 WhatsApp Web（`Baileys`）。 + 在当前 OpenClaw 渠道架构中，消息平台渠道基于 WhatsApp Web（`Baileys`）。 内置聊天渠道注册表中没有单独的 Twilio WhatsApp 消息渠道。 @@ -155,16 +155,16 @@ OpenClaw 建议你尽可能为 WhatsApp 使用单独的号码。（渠道元数 - Gateway 网关拥有 WhatsApp socket 和重连循环。 - 出站发送要求目标账户存在活动的 WhatsApp 监听器。 - Status 和广播聊天会被忽略（`@status`、`@broadcast`）。 -- 直接聊天使用私信会话规则（`session.dmScope`；默认 `main` 会将私信折叠到智能体主会话中）。 -- 群组会话彼此隔离（`agent::whatsapp:group:`）。 +- 直接聊天使用私信会话规则（`session.dmScope`；默认 `main` 会将私信折叠到智能体主会话）。 +- 群组会话是隔离的（`agent::whatsapp:group:`）。 - WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` 及其小写变体）。优先使用主机级代理配置，而不是渠道专用的 WhatsApp 代理设置。 -## 插件钩子和隐私 +## 插件钩子与隐私 WhatsApp 入站消息可能包含个人消息内容、电话号码、 -群组标识符、发送者姓名和会话关联字段。因此， -除非你显式选择启用，否则 WhatsApp 不会向插件广播入站 -`message_received` 钩子负载： +群组标识符、发送者名称和会话关联字段。因此， +除非你明确选择启用，否则 WhatsApp 不会将入站 `message_received` +hook 负载广播给插件： ```json5 { @@ -178,7 +178,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 } ``` -你可以将此启用范围限定到某个账户： +你可以将启用范围限定到单个账户： ```json5 { @@ -196,10 +196,10 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 } ``` -只有在你信任这些插件可以接收入站 WhatsApp 消息内容 -和标识符时，才启用此选项。 +仅当你信任相关插件接收入站 WhatsApp 消息内容和标识符时， +才启用此选项。 -## 访问控制和激活 +## 访问控制与激活 @@ -210,15 +210,15 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 - `open`（要求 `allowFrom` 包含 `"*"`） - `disabled` - `allowFrom` 接受 E.164 风格的号码（内部会进行规范化）。 + `allowFrom` 接受 E.164 风格号码（内部会标准化）。 - 多账户覆盖：`channels.whatsapp.accounts..dmPolicy`（以及 `allowFrom`）对于该账户优先于渠道级默认值。 + 多账户覆盖：`channels.whatsapp.accounts..dmPolicy`（以及 `allowFrom`）对该账户优先于渠道级默认值。 运行时行为细节： - - 配对会持久化到渠道 allow-store 中，并与已配置的 `allowFrom` 合并 + - 配对关系会持久化到渠道允许存储中，并与已配置的 `allowFrom` 合并 - 如果未配置允许列表，则默认允许已关联的自身号码 - - OpenClaw 绝不会自动配对出站 `fromMe` 私信（即你从已关联设备发送给自己的消息） + - OpenClaw 永远不会自动配对出站 `fromMe` 私信（即你从已关联设备发送给自己的消息） @@ -227,7 +227,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 1. **群组成员允许列表**（`channels.whatsapp.groups`） - 如果省略 `groups`，则所有群组都有资格 - - 如果存在 `groups`，它会作为群组允许列表（允许 `"*"`） + - 如果存在 `groups`，它会作为群组允许列表（允许使用 `"*"`） 2. **群组发送者策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`） - `open`：绕过发送者允许列表 @@ -237,9 +237,9 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 发送者允许列表回退： - 如果未设置 `groupAllowFrom`，运行时会在可用时回退到 `allowFrom` - - 在 mention/reply 激活之前，会先评估发送者允许列表 + - 发送者允许列表会在提及/回复激活之前进行评估 - 注意：如果根本不存在 `channels.whatsapp` 配置块，运行时的群组策略回退值为 `allowlist`（并带有警告日志），即使设置了 `channels.defaults.groupPolicy` 也是如此。 + 注意：如果完全不存在 `channels.whatsapp` 配置块，运行时群组策略回退值为 `allowlist`（并记录警告日志），即使设置了 `channels.defaults.groupPolicy` 也是如此。 @@ -250,36 +250,36 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 - 对机器人身份的显式 WhatsApp 提及 - 已配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式回复给机器人检测（回复发送者与机器人身份匹配） + - 隐式回复机器人检测（回复的发送者匹配机器人身份） 安全说明： - - 引用/回复只会满足提及门控；它**不会**授予发送者授权 - - 当使用 `groupPolicy: "allowlist"` 时，未在允许列表中的发送者即使回复了允许列表用户的消息，仍然会被阻止 + - 引用/回复只能满足提及门控；它**不会**授予发送者授权 + - 在 `groupPolicy: "allowlist"` 下，即使非允许列表发送者回复了允许列表用户的消息，仍会被阻止 会话级激活命令： - `/activation mention` - `/activation always` - `activation` 会更新会话状态（不是全局配置）。它受 owner 权限控制。 + `activation` 会更新会话状态（而非全局配置）。它受 owner 权限控制。 -## 个人号码和自聊行为 +## 个人号码与自聊行为 -当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护会激活： +当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护会启用： - 跳过自聊轮次的已读回执 -- 忽略本会触发你自己的 mention-JID 自动触发行为 +- 忽略原本会触发提醒自己的 mention-JID 自动触发行为 - 如果未设置 `messages.responsePrefix`，自聊回复默认使用 `[{identity.name}]` 或 `[openclaw]` -## 消息规范化和上下文 +## 消息标准化与上下文 - 传入的 WhatsApp 消息会被包装到共享的入站信封中。 + 传入的 WhatsApp 消息会被包装进共享的入站信封中。 如果存在引用回复，会按以下形式附加上下文： @@ -289,12 +289,12 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 [/Replying] ``` - 回复元数据字段也会在可用时填充（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。 + 可用时也会填充回复元数据字段（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。 - - 纯媒体入站消息会使用如下占位符进行规范化： + + 仅媒体的入站消息会使用如下占位符进行标准化： - `` - `` @@ -302,7 +302,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 - `` - `` - 位置消息正文使用简洁的坐标文本。位置标签/注释以及联系人/vCard 详情会渲染为带围栏的不可信元数据，而不是内联提示文本。 + 位置消息正文使用简洁的坐标文本。位置标签/注释以及联系人/vCard 详情会呈现为带围栏的不可信元数据，而不是内联提示文本。 @@ -322,7 +322,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 - 默认情况下，已接受的 WhatsApp 入站消息会启用已读回执。 + 默认情况下，已接受的入站 WhatsApp 消息会启用已读回执。 全局禁用： @@ -357,46 +357,46 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 -## 传递、分块和媒体 +## 投递、分块和媒体 - 默认分块上限：`channels.whatsapp.textChunkLimit = 4000` - `channels.whatsapp.chunkMode = "length" | "newline"` - - `newline` 模式优先按段落边界（空行）拆分，然后回退到按长度安全分块 + - `newline` 模式优先按段落边界（空行）分块，然后回退到按长度安全分块 - 支持图片、视频、音频（PTT 语音便笺）和文档负载 - 回复负载会保留 `audioAsVoice`；WhatsApp 会将音频媒体作为 Baileys PTT 语音便笺发送 - - 非 Ogg 音频，包括 Microsoft Edge TTS MP3/WebM 输出，会在 PTT 传递前转码为 Ogg/Opus + - 非 Ogg 音频（包括 Microsoft Edge TTS MP3/WebM 输出）在作为 PTT 投递前会被转码为 Ogg/Opus - 原生 Ogg/Opus 音频会以 `audio/ogg; codecs=opus` 发送，以兼容语音便笺 - - 通过在视频发送上设置 `gifPlayback: true`，支持动画 GIF 播放 - - 发送多媒体回复负载时，说明文字会应用到第一项媒体 - - 媒体来源可以是 HTTP(S)、`file://` 或本地路径 + - 通过在视频发送时设置 `gifPlayback: true`，支持动画 GIF 播放 + - 发送多媒体回复负载时，说明文字会应用到第一项媒体；但 PTT 语音便笺会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端对语音便笺说明文字的渲染并不一致 + - 媒体源可以是 HTTP(S)、`file://` 或本地路径 - 入站媒体保存上限：`channels.whatsapp.mediaMaxMb`（默认 `50`） - 出站媒体发送上限：`channels.whatsapp.mediaMaxMb`（默认 `50`） - 按账户覆盖使用 `channels.whatsapp.accounts..mediaMaxMb` - - 图片会自动优化（尺寸调整/质量扫描）以适应限制 - - 媒体发送失败时，第一项回退会发送文本警告，而不是静默丢弃响应 + - 图片会自动优化（尺寸/质量扫描）以适应限制 + - 媒体发送失败时，首项回退会发送文本警告，而不是静默丢弃响应 ## 回复引用 -WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消息。使用 `channels.whatsapp.replyToMode` 控制此行为。 +WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消息。使用 `channels.whatsapp.replyToMode` 进行控制。 -| 值 | 行为 | -| ----------- | -------------------------------------------------------------------- | -| `"off"` | 从不引用；作为普通消息发送 | -| `"first"` | 仅引用第一条出站回复分块 | -| `"all"` | 引用每一条出站回复分块 | -| `"batched"` | 引用排队的批量回复，同时让即时回复保持不引用 | +| 值 | 行为 | +| ----------- | --------------------------------------------------------------------- | +| `"off"` | 从不引用；作为普通消息发送 | +| `"first"` | 仅引用第一段出站回复分块 | +| `"all"` | 引用每一段出站回复分块 | +| `"batched"` | 引用排队的批量回复，同时让即时回复不带引用 | -默认值为 `"off"`。按账户覆盖使用 `channels.whatsapp.accounts..replyToMode`。 +默认值是 `"off"`。按账户覆盖使用 `channels.whatsapp.accounts..replyToMode`。 ```json5 { @@ -410,14 +410,14 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消 ## 反应级别 -`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用 emoji 反应的广度： +`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用 emoji 反应的广泛程度： -| 级别 | 确认反应 | 智能体主动反应 | 说明 | -| ------------- | -------- | ----------------------- | ------------------------------------ | -| `"off"` | 否 | 否 | 完全不使用反应 | -| `"ack"` | 是 | 否 | 仅确认反应（回复前确认接收） | -| `"minimal"` | 是 | 是（保守） | 确认反应 + 带保守指导的智能体反应 | -| `"extensive"` | 是 | 是（鼓励） | 确认反应 + 带鼓励指导的智能体反应 | +| 级别 | 确认反应 | 智能体主动反应 | 说明 | +| ------------- | ------------- | ------------------------- | ------------------------------------------------ | +| `"off"` | 否 | 否 | 完全不使用反应 | +| `"ack"` | 是 | 否 | 仅确认反应（回复前回执） | +| `"minimal"` | 是 | 是（保守） | 确认反应 + 带保守引导的智能体反应 | +| `"extensive"` | 是 | 是（鼓励） | 确认反应 + 带鼓励性引导的智能体反应 | 默认值：`"minimal"`。 @@ -435,8 +435,8 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消 ## 确认反应 -WhatsApp 通过 `channels.whatsapp.ackReaction` 支持在接收入站消息时立即发送确认反应。 -确认反应受 `reactionLevel` 控制 —— 当 `reactionLevel` 为 `"off"` 时，它们会被抑制。 +WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时立即发送确认反应。 +确认反应受 `reactionLevel` 控制——当 `reactionLevel` 为 `"off"` 时会被抑制。 ```json5 { @@ -455,26 +455,26 @@ WhatsApp 通过 `channels.whatsapp.ackReaction` 支持在接收入站消息时 行为说明： - 在入站消息被接受后立即发送（回复前） -- 失败会记录日志，但不会阻止正常回复传递 -- 群组模式 `mentions` 会在由提及触发的轮次中发送反应；群组激活 `always` 会绕过此检查 -- WhatsApp 使用 `channels.whatsapp.ackReaction`（这里不使用旧版 `messages.ackReaction`） +- 失败会被记录日志，但不会阻塞正常回复投递 +- 群组模式 `mentions` 会在由提及触发的轮次发送反应；群组激活 `always` 会绕过此检查 +- WhatsApp 使用 `channels.whatsapp.ackReaction`（此处不使用旧版 `messages.ackReaction`） -## 多账户和凭证 +## 多账户与凭证 - 账户 id 来自 `channels.whatsapp.accounts` - - 默认账户选择：如果存在则为 `default`，否则为第一个已配置的账户 id（排序后） - - 账户 id 在内部会被规范化以供查找 + - 默认账户选择：如果存在 `default` 则使用它，否则使用第一个已配置的账户 id（已排序） + - 账户 id 会在内部标准化以便查找 - 当前认证路径：`~/.openclaw/credentials/whatsapp//creds.json` - 备份文件：`creds.json.bak` - - `~/.openclaw/credentials/` 中的旧版默认认证仍会在默认账户流程中被识别/迁移 + - `~/.openclaw/credentials/` 中的旧版默认认证仍会被识别/迁移，用于默认账户流程 - + `openclaw channels logout --channel whatsapp [--account ]` 会清除该账户的 WhatsApp 认证状态。 在旧版认证目录中，会保留 `oauth.json`，同时移除 Baileys 认证文件。 @@ -485,18 +485,18 @@ WhatsApp 通过 `channels.whatsapp.ackReaction` 支持在接收入站消息时 ## 工具、操作和配置写入 - 智能体工具支持包括 WhatsApp 反应操作（`react`）。 -- 操作门控： +- 操作开关： - `channels.whatsapp.actions.reactions` - `channels.whatsapp.actions.polls` -- 默认启用由渠道发起的配置写入（可通过 `channels.whatsapp.configWrites=false` 禁用）。 +- 默认启用渠道发起的配置写入（可通过 `channels.whatsapp.configWrites=false` 禁用）。 ## 故障排除 - - 症状：渠道状态报告为未关联。 + + 症状：渠道状态显示未关联。 - 修复： + 修复方法： ```bash openclaw channels login --channel whatsapp @@ -506,9 +506,9 @@ WhatsApp 通过 `channels.whatsapp.ackReaction` 支持在接收入站消息时 - 症状：已关联账户反复断开或反复尝试重连。 + 症状：账户已关联，但反复断开或尝试重连。 - 修复： + 修复方法： ```bash openclaw doctor @@ -538,38 +538,38 @@ WhatsApp 通过 `channels.whatsapp.ackReaction` 支持在接收入站消息时 - WhatsApp Gateway 网关运行时应使用 Node。Bun 被标记为不兼容稳定的 WhatsApp/Telegram Gateway 网关运行。 + WhatsApp Gateway 网关运行时应使用 Node。Bun 被标记为不适合稳定的 WhatsApp/Telegram Gateway 网关运行。 ## 系统提示词 -WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 风格的群组和直接聊天系统提示词。 +WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 的群组和直接聊天系统提示词。 群组消息的解析层级： -首先确定生效的 `groups` 映射：如果账户定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不进行深度合并）。然后提示词查找会在得到的单一映射上运行： +首先确定生效的 `groups` 映射：如果账户定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不进行深度合并）。然后在生成的单一映射上执行提示词查找： -1. **群组特定系统提示词**（`groups[""].systemPrompt`）：当映射中存在特定群组条目，**且** 其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，并且不应用任何系统提示词。 -2. **群组通配符系统提示词**（`groups["*"].systemPrompt`）：当映射中完全不存在特定群组条目，或该条目存在但未定义 `systemPrompt` 键时使用。 +1. **群组专用系统提示词**（`groups[""].systemPrompt`）：当映射中存在该特定群组条目，**并且**其定义了 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，不应用任何系统提示词。 +2. **群组通配符系统提示词**（`groups["*"].systemPrompt`）：当映射中完全不存在该特定群组条目，或者该条目存在但未定义 `systemPrompt` 键时使用。 直接消息的解析层级： -首先确定生效的 `direct` 映射：如果账户定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不进行深度合并）。然后提示词查找会在得到的单一映射上运行： +首先确定生效的 `direct` 映射：如果账户定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不进行深度合并）。然后在生成的单一映射上执行提示词查找： -1. **直接聊天特定系统提示词**（`direct[""].systemPrompt`）：当映射中存在特定对端条目，**且** 其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，并且不应用任何系统提示词。 -2. **直接聊天通配符系统提示词**（`direct["*"].systemPrompt`）：当映射中完全不存在特定对端条目，或该条目存在但未定义 `systemPrompt` 键时使用。 +1. **直接聊天专用系统提示词**（`direct[""].systemPrompt`）：当映射中存在该特定对端条目，**并且**其定义了 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，不应用任何系统提示词。 +2. **直接聊天通配符系统提示词**（`direct["*"].systemPrompt`）：当映射中完全不存在该特定对端条目，或者该条目存在但未定义 `systemPrompt` 键时使用。 注意：`dms` 仍然是轻量级的按私信历史覆盖桶（`dms..historyLimit`）；提示词覆盖位于 `direct` 下。 -**与 Telegram 多账户行为的区别：** 在 Telegram 中，在多账户设置下，根级 `groups` 会对所有账户刻意抑制 —— 即使某些账户没有定义自己的 `groups` 也是如此 —— 以防止机器人接收其并不属于的群组消息。WhatsApp 不应用此保护：对于任何未定义账户级覆盖的账户，无论配置了多少账户，根级 `groups` 和根级 `direct` 都始终会被继承。在多账户 WhatsApp 设置中，如果你希望每个账户拥有各自的群组或直接聊天提示词，请在每个账户下显式定义完整映射，而不是依赖根级默认值。 +**与 Telegram 多账户行为的区别：** 在 Telegram 中，在多账户设置下，根级 `groups` 会被有意抑制——即使某些账户没有定义自己的 `groups` 也是如此——以防止机器人接收其并不属于的群组消息。WhatsApp 不应用这一保护：无论配置了多少账户，凡是未定义账户级覆盖的账户，都会继承根级 `groups` 和根级 `direct`。在多账户 WhatsApp 设置中，如果你希望为每个账户设置群组或直接聊天提示词，应在每个账户下显式定义完整映射，而不是依赖根级默认值。 重要行为： -- `channels.whatsapp.groups` 既是按群组的配置映射，也是聊天级群组允许列表。在根级或账户作用域中，`groups["*"]` 表示该作用域“允许所有群组”。 -- 只有在你本来就希望该作用域允许所有群组时，才添加通配符群组 `systemPrompt`。如果你仍然只希望固定的一组群组 id 有资格被允许，不要将 `groups["*"]` 用作提示词默认值。相反，应在每个显式允许列表群组条目上重复该提示词。 -- 群组准入和发送者授权是两个独立检查。`groups["*"]` 会扩大可进入群组处理的群组集合，但它本身不会授权这些群组中的每个发送者。发送者访问仍然由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 单独控制。 -- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 只会在某个私信已经通过 `dmPolicy` 加上 `allowFrom` 或配对存储规则被允许之后，提供默认的直接聊天配置。 +- `channels.whatsapp.groups` 既是按群组划分的配置映射，也是聊天级群组允许列表。在根级或账户级作用域下，`groups["*"]` 都表示“该作用域下允许所有群组”。 +- 只有当你本来就希望该作用域允许所有群组时，才添加通配符群组 `systemPrompt`。如果你仍然只希望固定的一组群组 id 有资格使用，请不要将 `groups["*"]` 用作提示词默认值。应改为在每个显式列入允许列表的群组条目上重复设置该提示词。 +- 群组准入和发送者授权是分开的检查。`groups["*"]` 会扩大可以进入群组处理的群组集合，但它本身不会授权这些群组中的所有发送者。发送者访问仍然由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 单独控制。 +- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 只会在私信已经通过 `dmPolicy` 加上 `allowFrom` 或配对存储规则获准后，提供默认的直接聊天配置。 示例： @@ -578,7 +578,7 @@ WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 风格的群 channels: { whatsapp: { groups: { - // 仅当根级作用域应允许所有群组时使用。 + // 仅当根级作用域下应允许所有群组时使用。 // 适用于所有未定义自己 groups 映射的账户。 "*": { systemPrompt: "所有群组的默认提示词。" }, }, @@ -589,18 +589,18 @@ WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 风格的群 accounts: { work: { groups: { - // 该账户定义了自己的 groups，因此根级 groups 会被完全 - // 替换。若要保留通配符，也需要在此显式定义 "*"。 + // 此账户定义了自己的 groups，因此根级 groups 会被完全 + // 替换。若要保留通配符，也需要在此处显式定义 "*"。 "120363406415684625@g.us": { requireMention: false, systemPrompt: "专注于项目管理。", }, - // 仅当此账户应允许所有群组时使用。 + // 仅当此账户下应允许所有群组时使用。 "*": { systemPrompt: "工作群组的默认提示词。" }, }, direct: { - // 该账户定义了自己的 direct 映射，因此根级 direct 条目会被 - // 完全替换。若要保留通配符，也需要在此显式定义 "*"。 + // 此账户定义了自己的 direct 映射，因此根级 direct 条目会被 + // 完全替换。若要保留通配符，也需要在此处显式定义 "*"。 "+15551234567": { systemPrompt: "特定工作直接聊天的提示词。" }, "*": { systemPrompt: "工作直接聊天的默认提示词。" }, }, @@ -619,8 +619,8 @@ WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 风格的群 高信号 WhatsApp 字段： -- 访问：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups` -- 传递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel` +- 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups` +- 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel` - 多账户：`accounts..enabled`、`accounts..authDir`、账户级覆盖 - 运维：`configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*` - 会话行为：`session.dmScope`、`historyLimit`、`dmHistoryLimit`、`dms..historyLimit` diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 723ae4fa2..8a9412084 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,67 +2,67 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关 配置参考，涵盖核心 OpenClaw 键名、默认值以及指向各专用子系统参考文档的链接 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值以及指向各专用子系统参考的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-25T17:30:17Z" + generated_at: "2026-04-25T18:12:20Z" model: gpt-5.4 provider: openai - source_hash: cb0578d9e78c063f579922498b993a2fd4398c66dc01d1e89ccaa56b777467c2 + source_hash: 0b7e904455845a9559a0a8ed67b217597819f4a8abc38e6c8ecb69b6481528e8 source_path: gateway/configuration-reference.md workflow: 15 --- -`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 -本文涵盖 OpenClaw 的主要配置面，并在某个子系统拥有更深入的专用参考时提供链接。由渠道和插件自行管理的命令目录，以及深入的 memory/QMD 调节项，位于各自独立页面，而不在本页中说明。 +本页涵盖 OpenClaw 的主要配置面，并在某个子系统拥有更深入的独立参考时提供外链。由渠道和插件拥有的命令目录，以及深层的 memory/QMD 调整项，分别位于它们自己的页面，而不在本页中说明。 -代码事实依据： +代码中的真实定义： -- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 -- `config.schema.lookup` 会返回单个按路径作用域划分的 schema 节点，供下钻工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面对配置文档基线哈希进行验证 +- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 +- `config.schema.lookup` 会返回一个按路径限定的 schema 节点，供下钻工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希 -专用深入参考： +专用深度参考： -- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 -- [斜杠命令](/zh-CN/tools/slash-commands)，适用于当前内置 + 捆绑命令目录 -- 各自所属的渠道/插件页面，适用于渠道专属命令面 +- [Memory configuration reference](/zh-CN/reference/memory-config)，用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations` 以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 +- [Slash commands](/zh-CN/tools/slash-commands)，用于当前内建 + 内置的命令目录 +- 各归属渠道/插件页面，用于渠道特定的命令面 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 —— 省略时，OpenClaw 会使用安全默认值。 --- ## 渠道 -每个渠道的配置键已迁移到专用页面 —— 请参阅 -[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`， +各渠道配置键已移至独立页面 —— 请参阅 +[Configuration — channels](/zh-CN/gateway/config-channels)，了解 `channels.*`， 包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 及其他 -内置渠道（认证、访问控制、多账号、提及门控）。 +内置渠道（认证、访问控制、多账户、提及门控）。 -## 智能体默认值、多智能体、会话和消息 +## 智能体默认值、多智能体、会话与消息 -已迁移到专用页面 —— 请参阅 -[配置 — 智能体](/zh-CN/gateway/config-agents)，内容包括： +已移至独立页面 —— 请参阅 +[Configuration — agents](/zh-CN/gateway/config-agents)，其中包括： -- `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱） +- `agents.defaults.*`（工作区、模型、思考、心跳、memory、媒体、skills、沙箱） - `multiAgent.*`（多智能体路由与绑定） - `session.*`（会话生命周期、压缩、清理） - `messages.*`（消息投递、TTS、Markdown 渲染） - `talk.*`（Talk 模式） - - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保持平台默认的暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`） + - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保持平台默认的停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`） ## 工具和自定义提供商 -工具策略、实验性开关、由 provider 支持的工具配置，以及自定义 -provider / 基础 URL 设置，已迁移到专用页面 —— 请参阅 -[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 +工具策略、实验性开关、由提供商支持的工具配置，以及自定义 +提供商 / base-URL 设置已移至独立页面 —— 请参阅 +[Configuration — tools and custom providers](/zh-CN/gateway/config-tools)。 ## MCP 由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下， 供嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、 -`show`、`set` 和 `unset` 命令可管理此配置块，且在编辑配置期间不会连接到 +`show`、`set` 和 `unset` 命令可管理此配置块，而无需在编辑配置时连接到 目标服务器。 ```json5 @@ -87,16 +87,16 @@ provider / 基础 URL 设置，已迁移到专用页面 —— 请参阅 } ``` -- `mcp.servers`：已命名的 stdio 或远程 MCP 服务器定义，供公开已配置 MCP 工具的运行时使用。 -- `mcp.sessionIdleTtlMs`：面向会话作用域的内置 MCP 运行时的空闲 TTL。 +- `mcp.servers`：供运行时暴露已配置 MCP 工具的具名 stdio 或远程 MCP 服务器定义。 +- `mcp.sessionIdleTtlMs`：面向会话作用域内置 MCP 运行时的空闲 TTL。 一次性嵌入式运行会请求在运行结束时清理；此 TTL 是面向 长生命周期会话和未来调用方的兜底机制。 -- `mcp.*` 下的变更会通过释放缓存的会话 MCP 运行时来热应用。 +- `mcp.*` 下的更改会通过释放已缓存的会话 MCP 运行时来热应用。 下一次工具发现/使用时会根据新配置重新创建它们，因此被移除的 - `mcp.servers` 条目会立即被回收，而不是等待空闲 TTL 到期。 + `mcp.servers` 条目会被立即清理，而不是等待空闲 TTL 到期。 -有关运行时行为，请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 -[CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。 +运行时行为请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 +[CLI backends](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。 ## Skills @@ -123,14 +123,13 @@ provider / 基础 URL 设置，已迁移到专用页面 —— 请参阅 } ``` -- `allowBundled`：仅适用于内置技能的可选允许列表（受管理/工作区技能不受影响）。 -- `load.extraDirs`：额外的共享技能根目录（优先级最低）。 -- `install.preferBrew`：为 true 时，如果存在 `brew`， - 将优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 +- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。 +- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 +- `install.preferBrew`：为 `true` 时，若 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 - `install.nodeManager`：用于 `metadata.openclaw.install` 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使技能已内置/已安装，也会禁用该技能。 -- `entries..apiKey`：为声明了主环境变量的技能提供的便捷字段（明文字符串或 SecretRef 对象）。 +- `entries..enabled: false`：即使某个 skill 已内置/已安装，也会禁用它。 +- `entries..apiKey`：针对声明了主环境变量的 skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 --- @@ -159,44 +158,44 @@ provider / 基础 URL 设置，已迁移到专用页面 —— 请参阅 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 -- **配置变更需要重启 Gateway 网关。** -- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。 +- 设备发现可接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- **配置更改需要重启 Gateway 网关。** +- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 - `plugins.entries..apiKey`：插件级 API 密钥便捷字段（插件支持时可用）。 -- `plugins.entries..env`：插件作用域的环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持的由 bundle 提供的钩子目录。 -- `plugins.entries..hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可以从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始对话内容。 -- `plugins.entries..subagent.allowModelOverride`：显式信任此插件，使其可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：适用于受信任子智能体覆盖的规范 `provider/model` 目标的可选允许列表。仅当你确实有意允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（可在可用时由原生 OpenClaw 插件 schema 验证）。 -- 渠道插件的账号/运行时设置位于 `channels.` 下，应由所属插件 manifest 的 `channelConfigs` 元数据描述，而不是由集中式 OpenClaw 选项注册表描述。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取 provider 设置。 +- `plugins.entries..env`：插件作用域环境变量映射。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持 bundle 提供的钩子目录。 +- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始会话内容。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件，使其可为后台子智能体运行请求逐次运行级别的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：面向受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅在你确实有意允许任意模型时使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（可在原生 OpenClaw 插件 schema 可用时按其验证）。 +- 渠道插件的账户/运行时设置位于 `channels.` 下，应由归属插件 manifest 的 `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。 - `apiKey`：Firecrawl API 密钥（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - - `baseUrl`：Firecrawl API 基础 URL（默认：`https://api.firecrawl.dev`）。 - - `onlyMainContent`：仅提取页面主内容（默认：`true`）。 - - `maxAgeMs`：最大缓存保留时间，单位为毫秒（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时，单位为秒（默认：`60`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok 网页搜索）设置。 - - `enabled`：启用 X Search provider。 + - `baseUrl`：Firecrawl API base URL（默认值：`https://api.firecrawl.dev`）。 + - `onlyMainContent`：仅提取页面主体内容（默认值：`true`）。 + - `maxAgeMs`：最大缓存时长，单位为毫秒（默认值：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时秒数（默认值：`60`）。 +- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 + - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。有关阶段和阈值，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。 - - `enabled`：Dreaming 总开关（默认 `false`）。 - - `frequency`：每次完整 Dreaming 扫描的 cron 周期（默认值为 `"0 3 * * *"`）。 +- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。阶段和阈值请参阅 [Dreaming](/zh-CN/concepts/dreaming)。 + - `enabled`：dreaming 总开关（默认值 `false`）。 + - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认值为 `"0 3 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整的内存配置位于 [内存配置参考](/zh-CN/reference/memory-config)： +- 完整 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为净化后的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。 -- `plugins.slots.memory`：选择当前激活的内存插件 id，或使用 `"none"` 以禁用内存插件。 -- `plugins.slots.contextEngine`：选择当前激活的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 +- 已启用的 Claude bundle 插件也可通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 以禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动 context engine 插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 将 `plugins.installs.*` 视为受管理状态；优先使用 CLI 命令，而不是手动编辑。 + - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 -请参阅 [插件](/zh-CN/tools/plugin)。 +请参阅 [Plugins](/zh-CN/tools/plugin)。 --- @@ -249,38 +248,43 @@ provider / 基础 URL 设置，已迁移到专用页面 —— 请参阅 - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 - `tabCleanup` 会在空闲一段时间后，或当某个 会话超过其上限时，回收已跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 - 0，可分别禁用这些单独的清理模式。 + 可禁用对应的单独清理模式。 - `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此浏览器导航默认保持严格模式。 -- 仅当你明确愿意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止规则约束。 -- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受到支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 来设置显式例外。 -- 远程配置文件仅支持附加模式（禁用 start/stop/reset）。 +- 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止限制。 +- `ssrfPolicy.allowPrivateNetwork` 仍然作为旧版别名受到支持。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 +- 远程配置文件仅支持附加模式（禁用启动/停止/重置）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；使用 WS(S) - 则适用于你的 provider 直接提供 DevTools WebSocket URL 的情况。 -- 如果外部管理的 CDP 服务可通过 loopback 访问，请将该 - 配置文件的 `attachOnly: true`；否则 OpenClaw 会将该 loopback 端口视为 - 本地受管浏览器配置文件，并可能报告本地端口归属错误。 -- `existing-session` 配置文件使用 Chrome MCP 而非 CDP，并且可以附加到 - 所选主机上，或通过已连接的浏览器节点进行附加。 -- `existing-session` 配置文件可设置 `userDataDir`，以指定某个特定的 + 当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)；使用 WS(S) + 则适用于你的提供商直接给出 DevTools WebSocket URL 的情况。 +- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程以及 + `attachOnly` CDP 的可达性检查和标签页打开请求。托管的 local loopback + 配置文件会保留本地 CDP 默认值。 +- 如果某个外部管理的 CDP 服务可通过 local loopback 访问，请将该 + 配置文件的 `attachOnly: true` 打开；否则 OpenClaw 会将该 loopback 端口视为 + 本地托管浏览器配置文件，并可能报告本地端口归属错误。 +- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可在 + 所选主机上附加，或通过已连接的浏览器节点附加。 +- `existing-session` 配置文件可以设置 `userDataDir`，以指向特定的 基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 - `existing-session` 配置文件保留当前 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动的操作而不是 CSS 选择器定位、单文件上传 - 钩子、不支持对话框超时覆盖、不支持 `wait --load networkidle`，以及不支持 + 使用 snapshot/ref 驱动的操作而非 CSS 选择器定位、单文件上传 + 钩子、不支持对话框超时覆盖、不支持 `wait --load networkidle`，且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地受管 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下才需要显式设置 `cdpUrl`。 -- 本地受管配置文件可设置 `executablePath`，以覆盖该配置文件的全局 - `browser.executablePath`。用它可以让一个配置文件运行在 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有在远程 CDP 场景下 + 才需要显式设置 `cdpUrl`。 +- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 + `browser.executablePath`。可用它让一个配置文件运行在 Chrome 中，而另一个运行在 Brave 中。 -- 本地受管配置文件在进程启动后会使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP - 发现，并使用 `browser.localCdpReadyTimeoutMs` 检查启动后 CDP websocket 就绪情况。 - 在较慢的主机上，如果 Chrome 能成功启动但就绪检查与启动过程发生竞争，请提高这些值。 -- 自动检测顺序：默认浏览器（若基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- `browser.executablePath` 接受 `~` 以表示你的操作系统主目录。 -- Control 服务：仅 loopback（端口由 `gateway.port` 派生，默认值为 `18791`）。 -- `extraArgs` 会将额外启动标志附加到本地 Chromium 启动命令中（例如 +- 本地托管配置文件在进程启动后会使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP + 发现，并使用 `browser.localCdpReadyTimeoutMs` 检查 + 启动后 CDP websocket 就绪情况。在较慢主机上，如果 Chrome 能成功启动 + 但就绪检查与启动过程发生竞争，请提高这些值。 +- 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- `browser.executablePath` 接受 `~` 作为你的操作系统主目录。 +- 控制服务：仅限 loopback（端口由 `gateway.port` 派生，默认值为 `18791`）。 +- `extraArgs` 会向本地 Chromium 启动附加额外启动标志（例如 `--disable-gpu`、窗口大小设置或调试标志）。 --- @@ -299,8 +303,8 @@ provider / 基础 URL 设置，已迁移到专用页面 —— 请参阅 } ``` -- `seamColor`：原生应用 UI 外框的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 身份覆盖。未设置时回退到当前激活的智能体身份。 +- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 +- `assistant`：Control UI 身份覆盖。会回退到当前活动智能体身份。 --- @@ -377,51 +381,51 @@ provider / 基础 URL 设置，已迁移到专用页面 —— 请参阅 -- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。只有在 `local` 模式下，Gateway 网关才允许启动。 - `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` bind 会在容器内部监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或使用 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **认证**：默认必须启用。非 loopback bind 要求 Gateway 网关认证。实际使用中，这意味着共享 token/password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成一个 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设为 `token` 或 `password`。若两者均已配置但未设置 mode，则启动以及服务安装/修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅适用于受信任的本地 local loopback 部署；新手引导提示中不会提供此选项，这是有意为之。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份头（见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求使用**非 loopback** 的代理来源；同机 loopback 反向代理不满足 trusted-proxy 认证要求。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可用于满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥与设备 token 分别独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，对于相同 `{scope, clientIp}` 的失败尝试，会在写入失败记录前进行串行化。因此，同一客户端并发的错误尝试可能会在第二个请求时触发限流，而不是两个请求都以普通不匹配的方式竞争通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你明确希望 localhost 流量也受限流约束时（例如测试环境或严格代理部署），请将其设为 `false`。 -- 来自浏览器源的 WS 认证尝试始终会启用限流，且不会豁免 loopback（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 +- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或使用 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必须启用。非 loopback bind 要求 Gateway 网关认证。实际中，这意味着使用共享 token/password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成一个 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设为 `token` 或 `password`。如果两者都已配置但未设置 mode，启动以及服务安装/修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅应用于可信的本地 loopback 环境；新手引导提示中不会提供此选项。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求 **非 loopback** 的代理来源；同机 loopback 反向代理不满足 trusted-proxy 认证要求。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点 **不会** 使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机是可信的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限速器。按客户端 IP 和认证作用域生效（共享密钥和设备 token 分别独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径中，对于相同 `{scope, clientIp}` 的失败尝试，会在写入失败状态前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限速，而不是两个请求都作为普通不匹配并发通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你有意也要对 localhost 流量做限速（例如用于测试环境或严格代理部署），请设为 `false`。 +- 来自浏览器源的 WS 认证尝试始终会启用限速，且不会豁免 loopback（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 - 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` - 值进行隔离，因此来自某个 localhost 源的重复失败不会自动 + 值彼此隔离，因此某个 localhost 源的反复失败不会自动 锁定另一个源。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开访问，要求认证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 loopback 源时，这是必需项。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，启用 Host 头源回退，用于那些有意依赖 Host 头源策略的部署。 -- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须为 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境中的紧急放行 - 覆盖项，允许对受信任私有网络 IP 使用明文 `ws://`； - 默认情况下，明文连接仍仅限 loopback。没有对应的 `openclaw.json` - 配置项，并且浏览器私有网络配置（例如 - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`）不会影响 Gateway 网关 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开访问，需要认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 loopback 源时，此项为必需。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，启用 Host 请求头源回退，适用于有意依赖 Host 请求头源策略的部署。 +- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境级的 + 紧急放行覆盖项，允许向可信私有网络 IP 使用明文 `ws://`； + 默认情况下，明文连接仍仅限于 loopback。没有对应的 `openclaw.json` + 配置项，并且诸如 + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 之类的浏览器私有网络配置，也不会影响 Gateway 网关 WebSocket 客户端。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身并不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：用于官方/TestFlight iOS 构建的外部 APNs relay 的基础 HTTPS URL；这些构建会在将基于 relay 的注册发布到 Gateway 网关后使用该 relay。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时，单位为毫秒。默认值为 `10000`。 -- 基于 relay 的注册会委托给某个特定的 Gateway 网关身份。配对后的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个注册作用域的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用该已存储注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃生舱配置，用于允许 loopback HTTP relay URL。生产环境的 relay URL 应保持使用 HTTPS。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 +- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在将基于 relay 的注册信息发布到 Gateway 网关后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间，单位为毫秒。默认值为 `10000`。 +- 基于 relay 的注册会委派给某个特定 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将注册作用域的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用该已存储注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：针对上述 relay 配置的临时环境变量覆盖项。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发环境的逃生开关，用于 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 - `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧套接字阈值，单位为分钟。应保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内的最大健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：用于按渠道选择退出健康监控重启，同时保持全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖项。设置后，其优先级高于渠道级覆盖。 -- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可将 `gateway.remote.*` 用作回退。 -- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析，则解析会以关闭失败方式处理（不会被远程回退所掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。仅列出你控制的代理。loopback 条目对于同机代理/本地检测场景仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。 -- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现关闭失败行为。 -- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准首次节点设备配对，且该配对未请求任何作用域。未设置时为禁用状态。这不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估完成后，对已声明节点命令进行全局允许/拒绝塑形。 -- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（在默认拒绝列表基础上扩展）。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：在滚动一小时内，每个渠道/账户允许的健康监控最大重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：渠道级别的健康监控重启退出设置，同时保留全局监控启用。 +- `channels..accounts..healthMonitor.enabled`：多账户渠道中的账户级覆盖。设置后，其优先级高于渠道级覆盖。 +- 本地 Gateway 网关调用路径仅会在 `gateway.auth.*` 未设置时，将 `gateway.remote.*` 用作回退。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 且未解析成功，则解析会以失败关闭方式处理（不会由远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。只应列出你控制的代理。loopback 条目对同机代理/本地检测场景依然有效（例如 Tailscale Serve 或本地反向代理），但它们 **不会** 让 loopback 请求满足 `gateway.auth.mode: "trusted-proxy"` 的条件。 +- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以保持失败关闭行为。 +- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于在未请求任何作用域时自动批准首次节点设备配对。未设置时为禁用。此项不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局允许/拒绝整形。 +- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外屏蔽的工具名称（扩展默认拒绝列表）。 - `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 @@ -435,13 +439,13 @@ provider / 基础 URL 设置，已迁移到专用页面 —— 请参阅 - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` 空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。 -- 可选的响应加固头： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅针对你控制的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 获取。 +- 可选的响应加固请求头： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一主机上运行多个 Gateway 网关时，请为每个实例使用唯一的端口和状态目录： +在同一主机上运行多个 Gateway 网关时，请使用不同的端口和状态目录： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -451,7 +455,7 @@ openclaw gateway --port 19001 便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。 -请参阅 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 +请参阅 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。 ### `gateway.tls` @@ -469,10 +473,10 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅供本地/开发使用。 +- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。 +- `autoGenerate`：在未配置显式文件时，自动生成本地自签名 cert/key 对；仅用于本地/开发环境。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；请限制其访问权限。 +- `keyPath`：TLS 私钥文件的文件系统路径；应限制访问权限。 - `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。 ### `gateway.reload` @@ -489,13 +493,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制在运行时如何应用配置编辑。 - - `"off"`：忽略实时编辑；变更需要显式重启。 - - `"restart"`：配置发生变化时始终重启 Gateway 网关进程。 - - `"hot"`：不重启，直接在进程内应用变更。 - - `"hybrid"`（默认）：先尝试热重载；如有需要再回退为重启。 -- `debounceMs`：应用配置变更前的防抖窗口，单位为毫秒（非负整数）。 -- `deferralTimeoutMs`：可选的最长等待时间，单位为毫秒，用于等待进行中的操作完成后再强制重启。省略或设为 `0` 表示无限期等待，并定期记录“仍在等待”的警告。 +- `mode`：控制配置编辑在运行时如何应用。 + - `"off"`：忽略实时编辑；更改需要显式重启。 + - `"restart"`：配置变更时始终重启 Gateway 网关进程。 + - `"hot"`：在不重启的情况下于进程内应用更改。 + - `"hybrid"`（默认）：优先尝试热重载；必要时回退到重启。 +- `debounceMs`：应用配置更改前的防抖窗口，单位为毫秒（非负整数）。 +- `deferralTimeoutMs`：可选的最长等待时间，单位为毫秒，用于等待进行中的操作完成后再强制重启。省略或设为 `0` 表示无限期等待，并定期记录仍在挂起的警告。 --- @@ -533,46 +537,46 @@ openclaw gateway --port 19001 ``` 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -查询字符串中的 hook token 会被拒绝。 +拒绝使用查询字符串中的 hook token。 验证和安全说明： -- `hooks.enabled=true` 要求提供非空的 `hooks.token`。 -- `hooks.token` 必须**不同于** `gateway.auth.token`；复用 Gateway 网关 token 会被拒绝。 +- `hooks.enabled=true` 要求 `hooks.token` 为非空。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关 token 会被拒绝。 - `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果某个映射或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要此显式启用。 +- 如果某个映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该显式启用。 **端点：** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - 仅当 `hooks.allowRequestSessionKey=true` 时，才接受请求负载中的 `sessionKey`（默认：`false`）。 + - 仅当 `hooks.allowRequestSessionKey=true`（默认值：`false`）时，才接受请求负载中的 `sessionKey`。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - - 通过模板渲染得到的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 + - 模板渲染得到的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 - `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 - `match.source` 匹配通用路径中的某个负载字段。 -- 类似 `{{messages[0].subject}}` 的模板会从负载中读取值。 -- `transform` 可以指向一个返回 hook 动作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，且必须位于 `hooks.transformsDir` 范围内（绝对路径和路径穿越会被拒绝）。 -- `agentId` 会路由到特定智能体；未知 id 会回退到默认值。 +- 类似 `{{messages[0].subject}}` 的模板会从负载中读取。 +- `transform` 可指向一个返回 hook 动作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且必须位于 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 +- `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 -- `defaultSessionKey`：可选的固定会话键，用于未显式提供 `sessionKey` 的 hook 智能体运行。 -- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及由模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或 preset 使用模板化 `sessionKey` 时，它会变为必填项。 -- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会覆盖本次 hook 运行所使用的 LLM（如果已设置模型目录，则该模型必须被允许）。 +- `defaultSessionKey`：可选的固定会话键，用于 hook 智能体运行时未显式提供 `sessionKey` 的情况。 +- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。 +- `allowedSessionKeyPrefixes`：用于显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任一映射或预设使用模板化 `sessionKey` 时，它就成为必填项。 +- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。 +- `model` 会为本次 hook 运行覆盖 LLM（如果已设置模型目录，则该模型必须被允许）。 ### Gmail 集成 -- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 -- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该 preset，而不是使用默认的模板化值。 +- 内建 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 +- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 约束到匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 +- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该预设，而不是使用默认的模板化值。 ```json5 { @@ -595,7 +599,7 @@ openclaw gateway --port 19001 } ``` -- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用此行为。 +- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 - 不要在 Gateway 网关旁边单独运行另一个 `gog gmail watch serve`。 --- @@ -616,13 +620,13 @@ openclaw gateway --port 19001 - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 -- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面相同，要求 Gateway 网关认证（token/password/trusted-proxy）。 -- 节点 WebView 通常不会发送认证头；在节点完成配对并连接后，Gateway 网关会公布节点作用域的能力 URL，供 canvas/A2UI 访问使用。 -- 能力 URL 绑定到当前活动的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退机制。 -- 会将 live-reload 客户端注入到已提供的 HTML 中。 -- 为空时会自动创建初始 `index.html`。 -- 还会在 `/__openclaw__/a2ui/` 提供 A2UI。 -- 变更需要重启 Gateway 网关。 +- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。 +- 节点 WebView 通常不会发送认证头；当节点已完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问广播节点作用域的 capability URL。 +- capability URL 会绑定到当前活动的节点 WS 会话，并会很快过期。不使用基于 IP 的回退。 +- 会向所提供的 HTML 中注入 live-reload 客户端。 +- 在目录为空时自动创建起始 `index.html`。 +- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 +- 更改需要重启 Gateway 网关。 - 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 --- @@ -641,11 +645,11 @@ openclaw gateway --port 19001 } ``` -- `minimal`（默认）：从 TXT 记录中省略 `cliPath` 和 `sshPort`。 -- `full`：包含 `cliPath` 和 `sshPort`。 -- 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 +- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 +- `full`：包含 `cliPath` + `sshPort`。 +- 主机名默认值为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 -### 广域（DNS-SD） +### 广域网（DNS-SD） ```json5 { @@ -680,14 +684,14 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境中缺少对应键时，才会应用内联环境变量。 +- 仅当进程环境中缺少某个键时，才会应用内联环境变量。 - `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 - `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 -- 完整优先级请参阅 [环境](/zh-CN/help/environment)。 +- 完整优先级请参阅 [Environment](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： +你可以在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -698,19 +702,19 @@ openclaw gateway --port 19001 ``` - 仅匹配全大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/为空的变量会在配置加载时报错。 +- 缺失或为空的变量会在配置加载时报错。 - 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 -- 适用于 `$include`。 +- 对 `$include` 同样有效。 --- ## Secrets -SecretRef 是增量能力：明文值仍然可用。 +SecretRef 采用增量方式：明文值仍然可用。 ### `SecretRef` -使用如下对象结构： +请使用以下对象结构： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -722,15 +726,15 @@ SecretRef 是增量能力：明文值仍然可用。 - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`） - `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` 的 id 不得包含 `.` 或 `..` 的斜杠分隔路径段（例如 `a/../b` 会被拒绝） +- `source: "exec"` 的 id 不能包含 `.` 或 `..` 这样的斜杠分隔路径段（例如 `a/../b` 会被拒绝） ### 支持的凭证面 -- 规范矩阵：[SecretRef 凭证面](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 会定位受支持的 `openclaw.json` 凭证路径。 -- `auth-profiles.json` 中的引用会纳入运行时解析和审计覆盖范围。 +- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。 +- `auth-profiles.json` 中的 ref 已纳入运行时解析和审计覆盖范围。 -### Secret providers 配置 +### Secret 提供商配置 ```json5 { @@ -760,14 +764,14 @@ SecretRef 是增量能力：明文值仍然可用。 说明： -- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 -- 当 Windows ACL 验证不可用时，file 和 exec provider 路径会以关闭失败方式处理。仅对无法验证但你信任的路径设置 `allowInsecurePath: true`。 -- `exec` provider 要求使用绝对 `command` 路径，并通过 stdin/stdout 传输协议负载。 -- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时会验证解析后的目标路径。 -- 如果配置了 `trustedDirs`，则受信任目录检查会应用于解析后的目标路径。 -- `exec` 子进程环境默认是最小化的；请使用 `passEnv` 显式传入所需变量。 -- Secret 引用会在激活时解析为内存快照，之后请求路径只会读取该快照。 -- 激活期间会应用活动表面过滤：已启用表面上的未解析引用会导致启动/重载失败，而不活跃表面会被跳过并记录诊断信息。 +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- 当无法验证 Windows ACL 时，文件和 exec 提供商路径会以失败关闭方式处理。仅在路径可信但无法验证时，才设置 `allowInsecurePath: true`。 +- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 传输协议负载。 +- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍验证解析后的目标路径。 +- 如果配置了 `trustedDirs`，则可信目录检查会作用于解析后的目标路径。 +- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传递所需变量。 +- Secret ref 会在激活时解析为内存中的快照，之后请求路径只读取该快照。 +- 激活期间会应用活动面过滤：已启用面上的未解析 ref 会导致启动/重载失败，而非活动面则会被跳过并输出诊断信息。 --- @@ -790,12 +794,12 @@ SecretRef 是增量能力：明文值仍然可用。 ``` - 每个智能体的 profile 存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持值级别引用（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- OAuth 模式 profile（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 +- `auth-profiles.json` 支持静态凭证模式的值级 ref（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- OAuth 模式 profile（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 提供支持的 auth-profile 凭证。 - 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会进行清理。 - 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。 - 请参阅 [OAuth](/zh-CN/concepts/oauth)。 -- Secrets 运行时行为以及 `audit/configure/apply` 工具：请参阅 [Secrets 管理](/zh-CN/gateway/secrets)。 +- Secrets 运行时行为以及 `audit/configure/apply` 工具：请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -817,20 +821,20 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `billingBackoffHours`：当某个 profile 因真实 - 计费/额度不足错误失败时的基础退避时长（单位：小时，默认：`5`）。即使在 `401`/`403` 响应中，显式的计费文本 - 仍可能落入这里，但 provider 专属文本 - 匹配器仍只作用于拥有它们的 provider（例如 OpenRouter 的 +- `billingBackoffHours`：当 profile 因真正的 + 计费/余额不足错误而失败时的基础回退时长，单位为小时（默认值：`5`）。即使在 `401`/`403` 响应上，只要出现显式计费文本 + 也仍会归入此类，但提供商特定文本 + 匹配器仍只作用于拥有它们的提供商（例如 OpenRouter `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或 - organization/workspace 支出上限消息则仍归入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按 provider 覆盖计费退避时长（单位：小时）。 -- `billingMaxHours`：计费退避指数增长的上限时长（单位：小时，默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时长（单位：分钟，默认：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限时长（单位：分钟，默认：`60`）。 -- `failureWindowHours`：用于退避计数器的滚动窗口（单位：小时，默认：`24`）。 -- `overloadedProfileRotations`：同一 provider 在因过载错误失败时，切换到模型回退前允许的最大 auth-profile 轮换次数（默认：`1`）。诸如 `ModelNotReadyException` 之类的 provider 忙碌形态会归入这里。 -- `overloadedBackoffMs`：在重试过载的 provider/profile 轮换前的固定延迟（默认：`0`）。 -- `rateLimitedProfileRotations`：同一 provider 在因速率限制错误失败时，切换到模型回退前允许的最大 auth-profile 轮换次数（默认：`1`）。该速率限制桶包括 provider 形态文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 + 组织/工作区支出限制消息则仍归入 `rate_limit` 路径。 +- `billingBackoffHoursByProvider`：可选的按提供商覆盖计费回退小时数。 +- `billingMaxHours`：计费回退指数增长的小时上限（默认值：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础回退时长，单位为分钟（默认值：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 回退增长的分钟上限（默认值：`60`）。 +- `failureWindowHours`：用于回退计数器的滚动时间窗口，单位为小时（默认值：`24`）。 +- `overloadedProfileRotations`：对于过载错误，在切换到模型回退之前，同一提供商 auth-profile 允许轮换的最大次数（默认值：`1`）。诸如 `ModelNotReadyException` 之类的提供商繁忙形态归入此类。 +- `overloadedBackoffMs`：在重试过载提供商/profile 轮换前的固定延迟，单位为毫秒（默认值：`0`）。 +- `rateLimitedProfileRotations`：对于限流错误，在切换到模型回退之前，同一提供商 auth-profile 允许轮换的最大次数（默认值：`1`）。该限流桶包括提供商形态文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -852,7 +856,7 @@ SecretRef 是增量能力：明文值仍然可用。 - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 设置 `logging.file` 可使用稳定路径。 - 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：在抑制写入前允许的最大日志文件大小，单位为字节（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- `maxFileBytes`：在抑制写入前允许的最大日志文件大小，单位为字节（正整数；默认值：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -897,22 +901,22 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `enabled`：instrumentation 输出的总开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这样的通配符）。 -- `stuckSessionWarnMs`：当某个会话保持在 processing 状态时，用于发出卡住会话警告的时长阈值，单位为毫秒。 -- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 -- `otel.endpoint`：OTel 导出的收集器 URL。 +- `enabled`：instrumentation 输出的总开关（默认值：`true`）。 +- `flags`：启用定向日志输出的标志字符串数组（支持诸如 `"telegram.*"` 或 `"*"` 的通配符）。 +- `stuckSessionWarnMs`：当会话保持在处理中状态时，用于发出卡住会话警告的时长阈值，单位为毫秒。 +- `otel.enabled`：启用 OpenTelemetry 导出管道（默认值：`false`）。 +- `otel.endpoint`：用于 OTel 导出的 collector URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求一起发送的额外 HTTP/gRPC 元数据头。 -- `otel.serviceName`：资源属性中的服务名称。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。 +- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据头。 +- `otel.serviceName`：资源属性使用的服务名。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 - `otel.sampleRate`：trace 采样率，范围 `0`–`1`。 -- `otel.flushIntervalMs`：定期刷新遥测数据的间隔，单位为毫秒。 -- `otel.captureContent`：为 OTEL span 属性显式启用原始内容捕获。默认关闭。布尔值 `true` 会捕获非 system 的消息/工具内容；对象形式则允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 -- `OPENCLAW_OTEL_PRELOADED=1`：适用于已注册全局 OpenTelemetry SDK 的主机的环境开关。此时 OpenClaw 会跳过插件自有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。 -- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。 -- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认均为：`true`）。 +- `otel.flushIntervalMs`：定期刷出 telemetry 的时间间隔，单位为毫秒。 +- `otel.captureContent`：用于 OTel span 属性的原始内容捕获显式开启项。默认关闭。布尔值 `true` 会捕获非 system 消息/工具内容；对象形式则允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 +- `OPENCLAW_OTEL_PRELOADED=1`：适用于已经注册了全局 OpenTelemetry SDK 的主机的环境开关。此时 OpenClaw 会跳过由插件拥有的 SDK 启动/关闭，但仍保持诊断监听器处于活动状态。 +- `cacheTrace.enabled`：为嵌入式运行记录 cache trace 快照（默认值：`false`）。 +- `cacheTrace.filePath`：cache trace JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制 cache trace 输出中包含的内容（默认全为 `true`）。 --- @@ -934,12 +938,12 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `channel`：用于 npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：在 Gateway 网关启动时检查 npm 更新（默认：`true`）。 -- `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 -- `auto.stableDelayHours`：stable 渠道自动应用前的最小时延，单位为小时（默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：stable 渠道额外的发布扩散窗口，单位为小时（默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道执行检查的频率，单位为小时（默认：`1`；最大：`24`）。 +- `channel`：npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 +- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认值：`true`）。 +- `auto.enabled`：为包安装启用后台自动更新（默认值：`false`）。 +- `auto.stableDelayHours`：stable 渠道自动应用前的最小时延，单位为小时（默认值：`6`；最大值：`168`）。 +- `auto.stableJitterHours`：stable 渠道发布扩散的额外时间窗口，单位为小时（默认值：`12`；最大值：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率，单位为小时（默认值：`1`；最大值：`24`）。 --- @@ -972,22 +976,22 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `enabled`：全局 ACP 功能门控（默认：`false`）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可在阻止执行的同时保留 ACP 命令可用。 -- `backend`：默认 ACP 运行时后端 id（必须匹配某个已注册的 ACP 运行时插件）。 -- `defaultAgent`：当派生运行未指定显式目标时，使用的后备 ACP 目标智能体 id。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示不增加额外限制。 -- `maxConcurrentSessions`：可同时处于活动状态的 ACP 会话上限。 -- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口，单位为毫秒。 -- `stream.maxChunkChars`：在拆分流式分块投影前允许的最大分块大小。 -- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终结事件再输出。 -- `stream.hiddenBoundarySeparator`：在隐藏工具事件之后、可见文本之前插入的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次可投影的智能体输出字符上限。 -- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。 -- `stream.tagVisibility`：tag 名称到布尔可见性覆盖的记录，用于流式事件。 +- `enabled`：全局 ACP 功能开关（默认值：`false`）。 +- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认值：`true`）。设为 `false` 可在阻止执行的同时保留 ACP 命令可用。 +- `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。 +- `defaultAgent`：当 spawn 未指定显式目标时使用的 ACP 目标智能体 id 回退值。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 列表；为空表示不做额外限制。 +- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。 +- `stream.coalesceIdleMs`：流式文本的空闲刷出窗口，单位为毫秒。 +- `stream.maxChunkChars`：分割流式 block 投影前允许的最大块大小。 +- `stream.repeatSuppression`：每轮抑制重复的状态/工具行（默认值：`true`）。 +- `stream.deliveryMode`：`"live"` 为增量流式传输；`"final_only"` 则缓冲直到轮次终止事件。 +- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认值：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 轮次投影的最大智能体输出字符数。 +- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行最大字符数。 +- `stream.tagVisibility`：记录标签名称到布尔可见性覆盖值的映射，用于流式事件。 - `runtime.ttlMinutes`：ACP 会话 worker 在可被清理前的空闲 TTL，单位为分钟。 -- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 +- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。 --- @@ -1003,11 +1007,11 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `cli.banner.taglineMode` 控制横幅标语样式： - - `"random"`（默认）：轮换显示有趣/季节性标语。 +- `cli.banner.taglineMode` 控制 banner 标语样式： + - `"random"`（默认）：轮换的有趣/节日标语。 - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍会显示横幅标题/版本）。 -- 若要隐藏整个横幅（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 +- 若要隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -1031,13 +1035,13 @@ SecretRef 是增量能力：明文值仍然可用。 ## 身份 -请参阅 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。 +请参阅 [Agent defaults](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。 --- -## Bridge protocol（旧版节点，历史参考）（旧版，已移除） +## Bridge protocol（旧版节点，历史参考） -当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前，验证会失败；`openclaw doctor --fix` 可以去除未知键）。 +当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以清除未知键）。 @@ -1077,11 +1081,11 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `sessionRetention`：在从 `sessions.json` 中清理完成的隔离 cron 运行会话之前保留多长时间。也控制已归档、已删除的 cron 转录内容的清理。默认：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发裁剪前的最大大小。默认：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认：`2000`。 -- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略则不会发送认证头。 -- `webhook`：已弃用的旧版后备 webhook URL（http/https），仅用于那些仍设置了 `notify: true` 的已存储任务。 +- `sessionRetention`：完成后的隔离 cron 运行会话在从 `sessions.json` 清理前保留多久。也控制已归档的已删除 cron 转录内容的清理。默认值：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在清理前允许的最大大小。默认值：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认值：`2000`。 +- `webhookToken`：用于 cron webhook POST 投递的 bearer token（`delivery.mode = "webhook"`）；若省略则不发送认证头。 +- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍设置了 `notify: true` 的已存储任务。 ### `cron.retry` @@ -1097,11 +1101,11 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `maxAttempts`：一次性任务在瞬态错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试对应的退避延迟数组，单位为毫秒（默认：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：会触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则表示对所有瞬态类型都重试。 +- `maxAttempts`：一次性任务在瞬时错误上的最大重试次数（默认值：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试尝试使用的回退延迟数组，单位为毫秒（默认值：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则会对所有瞬时类型重试。 -仅适用于一次性 cron 任务。周期性任务使用单独的失败处理机制。 +仅适用于一次性 cron 任务。周期性任务使用单独的失败处理方式。 ### `cron.failureAlert` @@ -1119,11 +1123,11 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `enabled`：为 cron 任务启用失败告警（默认：`false`）。 -- `after`：连续失败多少次后才触发告警（正整数，最小值：`1`）。 -- `cooldownMs`：同一任务两次重复告警之间的最小间隔，单位为毫秒（非负整数）。 -- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 则向配置的 webhook 发起 POST。 -- `accountId`：用于限定告警投递范围的可选账号或渠道 id。 +- `enabled`：为 cron 任务启用失败告警（默认值：`false`）。 +- `after`：触发告警前所需的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一任务重复告警之间的最小间隔，单位为毫秒（非负整数）。 +- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 则 POST 到已配置的 webhook。 +- `accountId`：可选的账户或渠道 id，用于限定告警投递范围。 ### `cron.failureDestination` @@ -1140,16 +1144,16 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- 所有任务共享的 cron 失败通知默认目标。 +- 所有任务共用的 cron 失败通知默认目标。 - `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。 -- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用上次已知的投递渠道。 -- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。 -- `accountId`：可选的投递账号覆盖项。 +- `channel`：announce 投递的渠道覆盖值。`"last"` 会复用最后已知的投递渠道。 +- `to`：显式的 announce 目标或 webhook URL。webhook 模式下必填。 +- `accountId`：可选的投递账户覆盖值。 - 每个任务的 `delivery.failureDestination` 会覆盖这个全局默认值。 -- 当全局和每任务失败目标都未设置时，已经通过 `announce` 投递的任务在失败时会回退到其主 announce 目标。 +- 当既未设置全局也未设置每个任务的失败目标时，已经通过 `announce` 投递的任务在失败时会回退到其主 announce 目标。 - `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的任务，除非该任务的主 `delivery.mode` 为 `"webhook"`。 -请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 +请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 进行跟踪。 --- @@ -1157,28 +1161,28 @@ SecretRef 是增量能力：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| 变量 | 说明 | +| Variable | 描述 | | ------------------ | ------------------------------------------------- | | `{{Body}}` | 完整的入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史/发送者包装） | -| `{{BodyStripped}}` | 去除了群组提及的正文 | +| `{{RawBody}}` | 原始正文（不含历史记录/发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | | `{{From}}` | 发送者标识符 | | `{{To}}` | 目标标识符 | | `{{MessageSid}}` | 渠道消息 id | | `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 当创建了新会话时为 `"true"` | +| `{{IsNewSession}}` | 新会话已创建时为 `"true"` | | `{{MediaUrl}}` | 入站媒体伪 URL | | `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | +| `{{MediaType}}` | 媒体类型（图片/音频/文档/……） | | `{{Transcript}}` | 音频转录文本 | -| `{{Prompt}}` | 为 CLI 条目解析得到的媒体提示词 | -| `{{MaxChars}}` | 为 CLI 条目解析得到的最大输出字符数 | +| `{{Prompt}}` | 用于 CLI 条目的已解析媒体提示词 | +| `{{MaxChars}}` | 用于 CLI 条目的已解析最大输出字符数 | | `{{ChatType}}` | `"direct"` 或 `"group"` | | `{{GroupSubject}}` | 群组主题（尽力而为） | | `{{GroupMembers}}` | 群组成员预览（尽力而为） | | `{{SenderName}}` | 发送者显示名称（尽力而为） | | `{{SenderE164}}` | 发送者电话号码（尽力而为） | -| `{{Provider}}` | provider 提示（whatsapp、telegram、discord 等） | +| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- @@ -1199,20 +1203,20 @@ SecretRef 是增量能力：明文值仍然可用。 **合并行为：** -- 单个文件：替换所在的对象。 -- 文件数组：按顺序进行深度合并（后者覆盖前者）。 -- 同级键：在 include 之后合并（覆盖 include 的值）。 +- 单个文件：替换其所在的包含对象。 +- 文件数组：按顺序深度合并（后者覆盖前者）。 +- 同级键：在 includes 之后合并（覆盖 include 中的值）。 - 嵌套 include：最多支持 10 层深度。 -- 路径：相对于发起 include 的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）之内。仅当最终解析结果仍位于该边界内时，才允许使用绝对路径/`../` 形式。 -- 当由 OpenClaw 管理的写入仅变更某个由单文件 include 支持的顶层 section 时，写入会透传到该 include 文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。 -- 根级 include、include 数组，以及带有同级覆盖的 include，对于由 OpenClaw 管理的写入均为只读；这类写入会以关闭失败方式处理，而不是将配置拍平。 -- 错误：对缺失文件、解析错误和循环 include 提供清晰消息。 +- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。只有在最终解析结果仍位于该边界内时，才允许使用绝对路径或 `../` 形式。 +- OpenClaw 自有写入在仅变更某个由单文件 include 支持的顶层区段时，会直接写回该 include 文件。例如，`plugins install` 会将 `plugins: { $include: "./plugins.json5" }` 的更新写入 `plugins.json5`，并保持 `openclaw.json` 不变。 +- 根级 include、include 数组，以及带有同级覆盖的 include，对 OpenClaw 自有写入而言是只读的；这些写入会以失败关闭方式处理，而不是将配置展平。 +- 错误：对缺失文件、解析错误和循环 include 提供清晰的错误消息。 --- -_相关内容：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ +_相关内容：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ ## 相关 -- [配置](/zh-CN/gateway/configuration) -- [配置示例](/zh-CN/gateway/configuration-examples) +- [Configuration](/zh-CN/gateway/configuration) +- [Configuration examples](/zh-CN/gateway/configuration-examples) diff --git a/docs/zh-CN/plugins/hooks.md b/docs/zh-CN/plugins/hooks.md index d07a30ee1..b3e260201 100644 --- a/docs/zh-CN/plugins/hooks.md +++ b/docs/zh-CN/plugins/hooks.md @@ -1,29 +1,26 @@ --- read_when: - - 你正在构建一个需要 `before_tool_call`、`before_agent_reply`、消息钩子或生命周期钩子的插件 - - 你需要通过插件阻止、重写或要求批准工具调用 - - 你正在内部钩子和插件钩子之间做选择 -summary: 插件钩子：拦截智能体、工具、消息、会话和 Gateway 网关生命周期事件 + - 你正在构建一个插件，需要 `before_tool_call`、`before_agent_reply`、消息钩子或生命周期钩子 + - 你需要从插件中阻止、重写或要求批准工具调用 + - 你正在在内部钩子和插件钩子之间做选择 +summary: 插件钩子：拦截智能体、工具、消息、会话以及 Gateway 网关 生命周期事件 title: 插件钩子 x-i18n: - generated_at: "2026-04-25T05:55:26Z" + generated_at: "2026-04-25T18:12:21Z" model: gpt-5.4 provider: openai - source_hash: f263fb9064811de79fc4744ce13c5a7b9afb2d3b00330975426348af3411dc76 + source_hash: 91fa7554227cbb5d283e74c16d7e12ef524c494b8bb117a7ff4b37b49daa18af source_path: plugins/hooks.md workflow: 15 --- -插件钩子是 OpenClaw 插件的进程内扩展点。当插件需要检查或更改智能体运行、工具调用、消息流、 -会话生命周期、子智能体路由、安装流程或 Gateway 网关启动时，请使用它们。 +插件钩子是 OpenClaw 插件的进程内扩展点。当插件需要检查或更改智能体运行、工具调用、消息流、会话生命周期、子智能体路由、安装过程或 Gateway 网关 启动时，请使用它们。 -如果你想使用一个由运维人员安装的小型 `HOOK.md` 脚本来处理命令和 Gateway 网关事件，例如 -`/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup`， -请改用 [内部钩子](/zh-CN/automation/hooks)。 +如果你想要的是一个由操作员安装的小型 `HOOK.md` 脚本，用于处理命令和 Gateway 网关 事件，例如 `/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup`，则请改用 [内部钩子](/zh-CN/automation/hooks)。 ## 快速开始 -从你的插件入口中使用 `api.on(...)` 注册带类型的插件钩子： +在你的插件入口中使用 `api.on(...)` 注册类型化的插件钩子： ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -55,47 +52,46 @@ export default definePluginEntry({ }); ``` -钩子处理器按 `priority` 降序依次运行。相同优先级的钩子 -会保持注册顺序。 +钩子处理器会按 `priority` 降序依次运行。优先级相同的钩子会保留注册顺序。 ## 钩子目录 -钩子按其扩展的 surface 分组。**加粗**的名称接受一个 -决策结果（阻止、取消、覆盖或要求批准）；其余都仅用于观察。 +钩子按其扩展的表面进行分组。**加粗** 的名称接受决策结果（阻止、取消、覆盖或要求批准）；其余全部仅用于观察。 **智能体轮次** -- `before_model_resolve` — 在加载会话消息前覆盖提供商或模型 -- `before_prompt_build` — 在模型调用前添加动态上下文或系统提示词文本 -- `before_agent_start` — 仅用于兼容性的组合阶段；优先使用上面的两个钩子 -- **`before_agent_reply`** — 用合成回复或静默来短路模型轮次 +- `before_model_resolve` — 在加载会话消息之前覆盖提供商或模型 +- `before_prompt_build` — 在模型调用前添加动态上下文或系统提示文本 +- `before_agent_start` — 仅用于兼容性的组合阶段；优先使用上面两个钩子 +- **`before_agent_reply`** — 使用合成回复或静默来短路模型轮次 - `agent_end` — 观察最终消息、成功状态和运行时长 **对话观察** -- `llm_input` — 观察提供商输入（系统提示词、提示词、历史） +- `model_call_started` / `model_call_ended` — 观察已脱敏的提供商/模型调用元数据、耗时、结果以及受限的请求 ID 哈希，不包含提示词或响应内容 +- `llm_input` — 观察提供商输入（系统提示、提示、历史记录） - `llm_output` — 观察提供商输出 **工具** - **`before_tool_call`** — 重写工具参数、阻止执行或要求批准 -- `after_tool_call` — 观察工具结果、错误和持续时间 +- `after_tool_call` — 观察工具结果、错误和耗时 - **`tool_result_persist`** — 重写根据工具结果生成的助手消息 -- **`before_message_write`** — 检查或阻止正在进行的消息写入（少见） +- **`before_message_write`** — 检查或阻止进行中的消息写入（较少见） -**消息和投递** +**消息与投递** -- **`inbound_claim`** — 在智能体路由前认领入站消息（合成回复） -- `message_received` — 观察入站内容、发送者、线程和元数据 -- **`message_sending`** — 重写出站内容或取消投递 -- `message_sent` — 观察出站投递成功或失败 -- **`before_dispatch`** — 在交给渠道前检查或重写出站派发 -- **`reply_dispatch`** — 参与最终回复派发流水线 +- **`inbound_claim`** — 在智能体路由之前认领传入消息（合成回复） +- `message_received` — 观察传入内容、发送者、线程和元数据 +- **`message_sending`** — 重写传出内容或取消投递 +- `message_sent` — 观察传出投递成功或失败 +- **`before_dispatch`** — 在交给渠道前检查或重写传出分发 +- **`reply_dispatch`** — 参与最终回复分发流水线 -**会话和压缩** +**会话与压缩** - `session_start` / `session_end` — 跟踪会话生命周期边界 -- `before_compaction` / `after_compaction` — 观察或标注压缩周期 +- `before_compaction` / `after_compaction` — 观察或注释压缩周期 - `before_reset` — 观察会话重置事件（`/reset`、程序化重置） **子智能体** @@ -104,19 +100,18 @@ export default definePluginEntry({ **生命周期** -- `gateway_start` / `gateway_stop` — 随 Gateway 网关启动或停止插件自有服务 +- `gateway_start` / `gateway_stop` — 随 Gateway 网关 启动或停止由插件拥有的服务 - **`before_install`** — 检查 Skills 或插件安装扫描，并可选择阻止 ## 工具调用策略 -`before_tool_call` 接收： +`before_tool_call` 会接收： - `event.toolName` - `event.params` - 可选的 `event.runId` - 可选的 `event.toolCallId` -- 上下文字段，例如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId`，以及 - 诊断字段 `ctx.trace` +- 上下文字段，例如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId`，以及诊断字段 `ctx.trace` 它可以返回： @@ -141,33 +136,27 @@ type BeforeToolCallResult = { 规则： -- `block: true` 是终止性的，并会跳过更低优先级的处理器。 -- `block: false` 会被视为没有决策。 +- `block: true` 是终止性决策，并会跳过更低优先级的处理器。 +- `block: false` 会被视为未做决定。 - `params` 会重写执行时使用的工具参数。 -- `requireApproval` 会暂停智能体运行，并通过插件 - 批准机制向用户发起请求。`/approve` 命令既可以批准 exec，也可以批准插件批准请求。 -- 即使更高优先级的钩子请求了批准，更低优先级的 `block: true` - 仍然可以阻止执行。 -- `onResolution` 会接收最终的批准决策——`allow-once`、 - `allow-always`、`deny`、`timeout` 或 `cancelled`。 +- `requireApproval` 会暂停智能体运行，并通过插件批准机制向用户发起请求。`/approve` 命令既可批准 exec 批准，也可批准插件批准。 +- 即使更高优先级的钩子请求了批准，更低优先级的 `block: true` 仍然可以阻止调用。 +- `onResolution` 会接收最终的批准决策 — `allow-once`、`allow-always`、`deny`、`timeout` 或 `cancelled`。 -## 提示词和模型钩子 +## 提示与模型钩子 -新插件请使用分阶段钩子： +对于新插件，请使用分阶段钩子： -- `before_model_resolve`：仅接收当前提示词和附件 - 元数据。返回 `providerOverride` 或 `modelOverride`。 -- `before_prompt_build`：接收当前提示词和会话消息。 - 返回 `prependContext`、`systemPrompt`、`prependSystemContext` 或 - `appendSystemContext`。 +- `before_model_resolve`：仅接收当前提示和附件元数据。返回 `providerOverride` 或 `modelOverride`。 +- `before_prompt_build`：接收当前提示和会话消息。返回 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。 -`before_agent_start` 仍然保留用于兼容性。优先使用上面的显式钩子， -这样你的插件就不会依赖旧的组合阶段。 +`before_agent_start` 仍保留用于兼容性。优先使用上面的显式钩子，这样你的插件就不会依赖旧的组合阶段。 -当 OpenClaw 能识别当前活动运行时，`before_agent_start` 和 `agent_end` -会包含 `event.runId`。同一个值也可通过 `ctx.runId` 获取。 +当 OpenClaw 能识别当前活动运行时，`before_agent_start` 和 `agent_end` 会包含 `event.runId`。同一个值也可通过 `ctx.runId` 获取。 -需要 `llm_input`、`llm_output` 或 `agent_end` 的非内置插件，必须设置： +如果你需要的是不接收原始提示、历史记录、响应、头信息、请求体或提供商请求 ID 的提供商调用遥测，请使用 `model_call_started` 和 `model_call_ended`。这些钩子包含稳定元数据，例如 `runId`、`callId`、`provider`、`model`、可选的 `api` / `transport`、终态 `durationMs` / `outcome`，以及当 OpenClaw 能推导时提供的 `upstreamRequestIdHash`（受限的提供商请求 ID 哈希）。 + +需要 `llm_input`、`llm_output` 或 `agent_end` 的非内置插件必须设置： ```json { @@ -183,77 +172,60 @@ type BeforeToolCallResult = { } ``` -可以按插件禁用会修改提示词的钩子，方式为 -`plugins.entries..hooks.allowPromptInjection=false`。 +可修改提示的钩子可通过 `plugins.entries..hooks.allowPromptInjection=false` 为单个插件禁用。 ## 消息钩子 -将消息钩子用于渠道级路由和投递策略： +使用消息钩子来处理渠道级路由和投递策略： -- `message_received`：观察入站内容、发送者、`threadId`、`messageId`、 - `senderId`、可选的运行/会话关联信息，以及元数据。 +- `message_received`：观察传入内容、发送者、`threadId`、`messageId`、`senderId`、可选的运行/会话关联信息以及元数据。 - `message_sending`：重写 `content` 或返回 `{ cancel: true }`。 - `message_sent`：观察最终成功或失败。 -对于纯音频 TTS 回复，即使渠道负载中没有可见文本/说明， -`content` 也可能包含隐藏的朗读转录文本。重写该 `content` -只会更新钩子可见的转录文本；它不会渲染为媒体说明。 +对于仅音频的 TTS 回复，即使渠道负载中没有可见文本/说明，`content` 也可能包含隐藏的语音转录文本。重写该 `content` 只会更新钩子可见的转录文本；它不会被渲染为媒体说明。 -消息钩子上下文会在可用时暴露稳定的关联字段： -`ctx.sessionKey`、`ctx.runId`、`ctx.messageId`、`ctx.senderId`、`ctx.trace`、 -`ctx.traceId`、`ctx.spanId`、`ctx.parentSpanId` 和 `ctx.callDepth`。在读取旧版元数据之前， -优先使用这些一等字段。 +消息钩子上下文在可用时会公开稳定的关联字段： +`ctx.sessionKey`、`ctx.runId`、`ctx.messageId`、`ctx.senderId`、`ctx.trace`、`ctx.traceId`、`ctx.spanId`、`ctx.parentSpanId` 和 `ctx.callDepth`。在读取旧版元数据之前，优先使用这些一等字段。 -在使用渠道特定元数据之前，优先使用带类型的 `threadId` 和 `replyToId` 字段。 +在使用特定于渠道的元数据之前，优先使用类型化的 `threadId` 和 `replyToId` 字段。 决策规则： -- 带有 `cancel: true` 的 `message_sending` 是终止性的。 -- 带有 `cancel: false` 的 `message_sending` 会被视为没有决策。 -- 被重写的 `content` 会继续传递给更低优先级的钩子，除非后续钩子 - 取消了投递。 +- 带有 `cancel: true` 的 `message_sending` 是终止性决策。 +- 带有 `cancel: false` 的 `message_sending` 会被视为未做决定。 +- 被重写的 `content` 会继续传递给更低优先级的钩子，除非后续钩子取消投递。 ## 安装钩子 -`before_install` 会在内置的 Skills 和插件安装扫描之后运行。 -返回额外发现项，或返回 `{ block: true, blockReason }` 以停止 -安装。 +`before_install` 会在内置的 Skills 和插件安装扫描之后运行。返回附加发现结果，或返回 `{ block: true, blockReason }` 以停止安装。 -`block: true` 是终止性的。`block: false` 会被视为没有决策。 +`block: true` 是终止性决策。`block: false` 会被视为未做决定。 -## Gateway 网关生命周期 +## Gateway 网关 生命周期 -将 `gateway_start` 用于需要 Gateway 网关自有状态的插件服务。该 -上下文会暴露 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，用于 -检查和更新 cron。使用 `gateway_stop` 清理长时间运行的资源。 +对于需要 Gateway 网关 所属状态的插件服务，请使用 `gateway_start`。该上下文会公开 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，用于检查和更新 cron。使用 `gateway_stop` 清理长期运行的资源。 -不要依赖内部的 `gateway:startup` 钩子来管理插件自有运行时 -服务。 +不要依赖内部的 `gateway:startup` 钩子来运行插件自有的运行时服务。 ## 即将弃用的内容 -少量与钩子相邻的 surface 已被弃用，但仍受支持。请在下一个主要版本前 -完成迁移： +有一些与钩子相邻的表面已被弃用，但仍受支持。请在下一个主要版本发布前迁移： -- **`inbound_claim` 和 `message_received` 处理器中的纯文本渠道信封**。 - 请读取 `BodyForAgent` 和结构化用户上下文块， - 而不是解析扁平信封文本。参见 - [纯文本渠道信封 → BodyForAgent](/zh-CN/plugins/sdk-migration#active-deprecations)。 -- **`before_agent_start`** 仍保留用于兼容性。新插件应使用 - `before_model_resolve` 和 `before_prompt_build`，而不是这个组合 - 阶段。 -- **`before_tool_call` 中的 `onResolution`** 现在使用带类型的 +- **`inbound_claim` 和 `message_received` 处理器中的纯文本渠道信封**。请读取 `BodyForAgent` 和结构化用户上下文块，而不是解析扁平的信封文本。参见 + [Plaintext channel envelopes → BodyForAgent](/zh-CN/plugins/sdk-migration#active-deprecations)。 +- **`before_agent_start`** 仍保留用于兼容性。新插件应使用 `before_model_resolve` 和 `before_prompt_build`，而不是这个组合阶段。 +- **`before_tool_call` 中的 `onResolution`** 现在使用类型化的 `PluginApprovalResolution` 联合类型（`allow-once` / `allow-always` / `deny` / - `timeout` / `cancelled`），而不是自由形式的 `string`。 + `timeout` / `cancelled`），而不是自由格式的 `string`。 -完整列表——包括 memory 能力注册、提供商 thinking -profile、外部认证提供商、提供商发现类型、任务运行时 -访问器，以及 `command-auth` → `command-status` 重命名——请参见 -[插件 SDK 迁移 → 当前弃用项](/zh-CN/plugins/sdk-migration#active-deprecations)。 +完整列表 — memory capability registration、provider thinking +profile、external auth providers、provider discovery types、task runtime +accessors，以及 `command-auth` → `command-status` 重命名 — 请参见 +[Plugin SDK migration → Active deprecations](/zh-CN/plugins/sdk-migration#active-deprecations)。 ## 相关内容 -- [插件 SDK 迁移](/zh-CN/plugins/sdk-migration) — 当前弃用项和移除时间线 +- [Plugin SDK migration](/zh-CN/plugins/sdk-migration) — 当前弃用项和移除时间线 - [构建插件](/zh-CN/plugins/building-plugins) - [插件 SDK 概览](/zh-CN/plugins/sdk-overview) - [插件入口点](/zh-CN/plugins/sdk-entrypoints) diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index e4652a650..25e97193c 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -2,58 +2,57 @@ read_when: - 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 - - 你在 OpenClaw 2026.4.25 之前使用了 `api.registerEmbeddedExtensionFactory` + - 在 OpenClaw 2026.4.25 之前，你使用了 `api.registerEmbeddedExtensionFactory` - 你正在将插件更新到现代插件架构 - 你维护一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-25T09:40:22Z" + generated_at: "2026-04-25T18:12:22Z" model: gpt-5.4 provider: openai - source_hash: e3a1410d9353156b4597d16a42a931f83189680f89c320a906aa8d2c8196792f + source_hash: c7ab0369fc6e43961a41cff882b0c05653a6a1e3f919ef8a3620c868c16c02ce source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚焦且有文档说明的导入方式。如果你的插件构建于新架构之前，本指南将帮助你完成迁移。 +OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且有文档说明的导入方式。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 -## 正在发生哪些变化 +## 正在发生的变化 -旧插件系统提供了两个开放范围很广的接口，使插件可以通过单一入口点导入所需的任何内容： +旧版插件系统提供了两个高度开放的接口面，允许插件通过单一入口点导入它们所需的任何内容： -- **`openclaw/plugin-sdk/compat`** —— 单一导入路径，重新导出了数十个辅助工具。它的引入是为了在新插件架构构建期间，让旧的基于钩子的插件继续工作。 -- **`openclaw/extension-api`** —— 一个桥接层，使插件可以直接访问宿主侧辅助工具，例如嵌入式智能体运行器。 -- **`api.registerEmbeddedExtensionFactory(...)`** —— 一个已移除、仅限 Pi 的内置扩展钩子，可观察诸如 `tool_result` 之类的 embedded-runner 事件。 +- **`openclaw/plugin-sdk/compat`** — 一个会重新导出数十个辅助工具的单一导入入口。它的引入是为了在新插件架构构建期间，保持旧版基于钩子的插件继续工作。 +- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问宿主侧的辅助功能，例如嵌入式智能体运行器。 +- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除、仅限 Pi 的内置扩展钩子，可用于观察嵌入式运行器事件，例如 `tool_result`。 -这些宽泛的导入接口现已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。 +这些宽泛的导入接口现已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。 -OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已有文档说明的插件行为。破坏性契约变更必须先经过兼容适配器、诊断信息、文档以及弃用窗口。这同样适用于 SDK 导入、manifest 字段、设置 API、钩子以及运行时注册行为。 +OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有文档说明的插件行为。破坏性契约变更必须先经过兼容适配器、诊断信息、文档说明以及弃用窗口。这适用于 SDK 导入、manifest 字段、设置 API、钩子和运行时注册行为。 - 向后兼容层将在未来的某个主版本中移除。 - 仍从这些接口导入的插件届时将会失效。 - 仅限 Pi 的嵌入式扩展工厂注册现已不再加载。 + 向后兼容层将在未来的主要版本中移除。届时，仍从这些接口面导入的插件将会失效。 + 仅限 Pi 的嵌入式扩展工厂注册已经不再加载。 ## 为什么会有这项变更 -旧方式会带来一些问题： +旧方法会带来一些问题： -- **启动缓慢** —— 导入一个辅助工具会加载数十个无关模块 -- **循环依赖** —— 宽泛的重新导出使创建导入循环变得很容易 -- **API 接口不清晰** —— 无法判断哪些导出是稳定接口，哪些是内部实现 +- **启动缓慢** — 导入一个辅助工具会加载数十个无关模块 +- **循环依赖** — 宽泛的重新导出让创建导入循环变得很容易 +- **API 接口面不清晰** — 无法判断哪些导出是稳定的，哪些是内部实现 -现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有明确用途和文档化契约。 +现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有明确用途和有文档说明的契约。 -面向内置渠道的旧版 provider 便捷接口也已移除。像 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口，以及 `openclaw/plugin-sdk/telegram-core` 这样的导入路径，都是私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用更窄且通用的 SDK 子路径。在内置插件工作区内部，应将 provider 自有辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +面向内置渠道的旧版 provider 便捷接口也已移除。诸如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口，以及 `openclaw/plugin-sdk/telegram-core` 之类的导入，都是私有 monorepo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，请将 provider 自有的辅助功能保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 当前内置 provider 示例： -- Anthropic 将 Claude 专用流式辅助工具保留在它自己的 `api.ts` / `contract-api.ts` 接口中 -- OpenAI 将 provider 构建器、默认模型辅助工具和 realtime provider 构建器保留在它自己的 `api.ts` 中 -- OpenRouter 将 provider 构建器以及新手引导/配置辅助工具保留在它自己的 `api.ts` 中 +- Anthropic 在其自己的 `api.ts` / `contract-api.ts` 接口中保留了 Claude 专属的流式辅助工具 +- OpenAI 在其自己的 `api.ts` 中保留了 provider 构建器、默认模型辅助工具和实时 provider 构建器 +- OpenRouter 在其自己的 `api.ts` 中保留了 provider 构建器以及新手引导 / 配置辅助工具 ## 兼容性策略 @@ -61,12 +60,12 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 1. 添加新契约 2. 通过兼容适配器继续连接旧行为 -3. 发出诊断信息或警告，明确指出旧路径和替代方案 -4. 在测试中覆盖新旧两条路径 -5. 记录弃用信息和迁移路径 -6. 仅在已公布的迁移窗口之后移除，通常是在主版本中 +3. 发出诊断信息或警告，明确指出旧路径及替代方案 +4. 在测试中覆盖两条路径 +5. 记录弃用情况和迁移路径 +6. 仅在已宣布的迁移窗口之后移除，通常是在主要版本中 -如果某个 manifest 字段仍被接受，插件作者就可以继续使用它，直到文档和诊断信息另有说明为止。新代码应优先使用文档中说明的替代方案，但现有插件不应在普通次版本发布中被破坏。 +如果某个 manifest 字段仍然被接受，插件作者就可以继续使用它，直到文档和诊断信息另有说明。新代码应优先使用有文档说明的替代方案，但现有插件不应在普通的小版本发布中被破坏。 ## 如何迁移 @@ -74,7 +73,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 内置插件必须将仅限 Pi 的 `api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为 - 与运行时无关的中间件。 + 运行时无关的中间件。 ```typescript // Pi 和 Codex 运行时动态工具 @@ -95,36 +94,38 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 } ``` - 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前对其进行重写。 + 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前重写这些输出。 - + 具备审批能力的渠道插件现在通过 - `approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来暴露原生审批行为。 + `approvalCapability.nativeRuntime` 以及共享运行时上下文注册表来公开原生审批行为。 关键变化： - - 用 `approvalCapability.nativeRuntime` 替换 `approvalCapability.handler.loadRuntime(...)` - - 将审批专用的认证/投递从旧版 `plugin.auth` / + - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 + `approvalCapability.nativeRuntime` + - 将审批专用的凭证 / 传递逻辑从旧版 `plugin.auth` / `plugin.approvals` 连接方式迁移到 `approvalCapability` - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除； - 请将 delivery/native/render 字段迁移到 `approvalCapability` - - `plugin.auth` 仅保留用于渠道登录/登出流程；其中的审批认证钩子不再被核心读取 + 请将 delivery / native / render 字段迁移到 `approvalCapability` + - `plugin.auth` 仍保留用于渠道登录 / 登出流程；其中的审批认证 + 钩子不再被核心读取 - 通过 `openclaw/plugin-sdk/channel-runtime-context` - 注册渠道自有运行时对象，例如客户端、令牌或 Bolt 应用 + 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt 应用 - 不要从原生审批处理器发送插件自有的改道通知； - 核心现在根据实际投递结果统一处理“已路由到其他位置”的通知 - - 当将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 - `createPluginRuntime().channel` 接口。部分桩实现会被拒绝。 + 核心现在会根据实际传递结果统一处理“已路由到其他位置”的通知 + - 当将 `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 @@ -134,19 +135,19 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 // 之后 const program = applyWindowsSpawnProgramPolicy({ candidate, - // 仅为受信任的兼容性调用方设置此项，这些调用方明确接受 - // 通过 shell 中介进行回退。 + // 仅当受信任的兼容性调用方明确接受通过 shell 进行回退时， + // 才设置此项。 allowShellFallback: true, }); ``` - 如果你的调用方并非有意依赖 shell 回退，请不要设置 + 如果你的调用方并非有意依赖 shell 回退，就不要设置 `allowShellFallback`，而应改为处理抛出的错误。 - 在你的插件中搜索来自这两个已弃用接口的导入： + 在你的插件中搜索来自任一已弃用接口面的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -156,7 +157,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - 旧接口中的每个导出都映射到一个特定的现代导入路径： + 旧接口面的每个导出都映射到一个特定的现代导入路径： ```typescript // 之前（已弃用的向后兼容层） @@ -172,10 +173,10 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - 对于宿主侧辅助工具，请使用注入的插件运行时，而不是直接导入： + 对于宿主侧辅助功能，请使用注入的插件运行时，而不是直接导入： ```typescript - // 之前（已弃用的 extension-api 桥接） + // 之前（已弃用的 extension-api 桥接层） import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); @@ -185,7 +186,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 相同模式也适用于其他旧版桥接辅助工具： - | 旧导入 | 现代等价项 | + | 旧导入 | 现代等价方式 | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -210,206 +211,211 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | 规范的插件入口辅助工具 | `definePluginEntry` | + | `plugin-sdk/core` | 用于渠道入口定义 / 构建器的旧版统一重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | | `plugin-sdk/provider-entry` | 单一 provider 入口辅助工具 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助工具 | allowlist 提示、设置状态构建器 | + | `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` | 账户 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化 | + | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表 / 配置 / 操作门控辅助工具 | + | `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 | | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表/账户操作辅助工具 | + | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表 / 账户操作辅助工具 | | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入连接逻辑 | `createChannelReplyPipeline` | + | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 输入中状态连接 | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语；带内置渠道名称的 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/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语；按内置渠道命名的 schema 导出仅用于旧版兼容性 | + | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名称规范化、描述裁剪、重复 / 冲突校验 | + | `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | 账户 Status 和草稿流生命周期辅助工具 | `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` | 已弃用的兼容性 shim | 仅限旧版渠道运行时工具 | | `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/插件审批负载、审批能力/profile 辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 | - | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同一聊天操作认证 | - | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批 profile/过滤辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力/投递适配器 | + | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供具有稳定回退行为的 Telegram 命令校验辅助工具 | + | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批载荷、审批能力 / 配置文件辅助工具、原生审批路由 / 运行时辅助工具，以及结构化审批显示路径格式化 | + | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | approver 解析、同聊天操作认证 | + | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件 / 过滤器辅助工具 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力 / 投递适配器 | | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 用于热渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽范围的审批处理器运行时辅助工具；若较窄的 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/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/ssrf-runtime` | SSRF 运行时辅助工具 | pinned-dispatcher、受保护的 fetch、SSRF 策略辅助工具 | | `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` | | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 | - | `plugin-sdk/fetch-runtime` | 封装 fetch/代理辅助工具 | `resolveFetch`、代理辅助工具 | + | `plugin-sdk/fetch-runtime` | 包装的 fetch / 代理辅助工具 | `resolveFetch`、代理辅助工具 | | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`, 策略运行器 | + | `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` | 命令 Status/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | 秘密输入解析 | 秘密输入辅助工具 | + | `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` | 窄范围回复分发辅助工具 | 最终化、provider 分发和会话标签辅助工具 | | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/Markdown 分块辅助工具 | - | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 | + | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本 / markdown 分块辅助工具 | + | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + 更新时间辅助工具 | | `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 | - | `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 | - | `plugin-sdk/status-helpers` | 渠道 Status 辅助工具 | 渠道/账户 Status 摘要构建器、运行时状态默认值、问题元数据辅助工具 | + | `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` | 请求 URL 辅助工具 | 从类似请求的输入中提取字符串 URL | - | `plugin-sdk/run-command` | 定时命令辅助工具 | 带规范化 stdout/stderr 的定时命令运行器 | - | `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 工具负载提取 | 从工具结果对象中提取规范化负载 | + | `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` | 精选的本地/自托管 provider 设置辅助工具 | 自托管 provider 发现/配置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管 provider 的设置辅助工具 | 同样的自托管 provider 发现/配置辅助工具 | + | `plugin-sdk/reply-payload` | 消息回复类型 | 回复载荷类型 | + | `plugin-sdk/provider-setup` | 精选的本地 / 自托管 provider 设置辅助工具 | 自托管 provider 发现 / 配置辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管 provider 的设置辅助工具 | 与上面相同的自托管 provider 发现 / 配置辅助工具 | | `plugin-sdk/provider-auth-runtime` | provider 运行时认证辅助工具 | 运行时 API key 解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key 新手引导/profile 写入辅助工具 | - | `plugin-sdk/provider-auth-result` | provider 认证结果辅助工具 | 标准 OAuth 认证结果构建器 | + | `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key 新手引导 / 配置文件写入辅助工具 | + | `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result 构建器 | | `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 | | `plugin-sdk/provider-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-model-shared` | 共享 provider 模型 / 重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、provider 端点辅助工具以及 model-id 规范化辅助工具 | + | `plugin-sdk/provider-catalog-shared` | 共享 provider 目录辅助工具 | `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/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP / 端点能力辅助工具，包括音频转录 multipart form 辅助工具 | + | `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 / DeepSeek V4 / 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` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像/音频辅助工具导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本/日志辅助工具 | + | `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` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的指令、注册表和校验辅助工具 | | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、指令、规范化 | | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具，以及共享 WebSocket 会话辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表/解析辅助工具，以及桥接会话辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表 / 解析辅助工具，以及桥接会话辅助工具 | | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助工具 | - | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider/请求/结果类型 | + | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider / 请求 / 结果类型 | | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider/请求/结果类型 | + | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider / 请求 / 结果类型 | | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化/归约 | + | `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` | 渠道 Status 辅助工具 | 共享渠道 Status 快照/摘要辅助工具 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑/读取辅助工具 | + | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导模块导出 | + | `plugin-sdk/channel-status` | 渠道 Status 辅助工具 | 共享渠道状态快照 / 摘要辅助工具 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑 / 读取辅助工具 | | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证/保护辅助工具 | - | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/Status 和环境代理辅助原语 | + | `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 辅助工具 | Memory 管理器/配置/文件/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 嵌入契约、注册表访问、本地 provider 和通用批处理/远程辅助工具；具体远程 provider 位于其所属插件中 | + | `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 宿主 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-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 宿主 Status 别名 | 面向供应商中立的 Memory 宿主 Status 辅助工具别名 | + | `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 宿主 Status 别名 | 面向不同供应商通用的 Memory 宿主 Status 辅助工具别名 | | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助工具接口 | - | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mock | + | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mocks | -此表刻意只包含常见迁移子集，而不是完整的 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/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 +`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些接口仍然会为了 +内置插件维护和兼容性而继续导出，但它们被有意省略出常见迁移表， +也不是新插件代码的推荐目标。 -同样的规则也适用于其他内置辅助工具族，例如： +同样的规则也适用于其他内置辅助工具家族，例如： -- 浏览器支持辅助工具：`plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` +- 浏览器支持辅助工具：`plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` - Matrix：`plugin-sdk/matrix*` - LINE：`plugin-sdk/line*` - IRC：`plugin-sdk/irc*` -- 内置辅助/插件接口，例如 `plugin-sdk/googlechat`, - `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, - `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, - `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, - `plugin-sdk/twitch`, - `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, - `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, +- 内置辅助工具 / 插件接口，例如 `plugin-sdk/googlechat`、 + `plugin-sdk/zalouser`、`plugin-sdk/bluebubbles*`、 + `plugin-sdk/mattermost*`、`plugin-sdk/msteams`、 + `plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、 + `plugin-sdk/twitch`、 + `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、 + `plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、 `plugin-sdk/thread-ownership` 和 `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` 当前公开了窄范围令牌辅助接口 +`plugin-sdk/github-copilot-token` 目前公开了窄范围令牌辅助接口 `DEFAULT_COPILOT_API_BASE_URL`、 `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 -请使用与你的任务最匹配的最窄导入路径。如果你找不到某个导出，请查看 -`src/plugin-sdk/` 下的源码，或在 Discord 中提问。 +请使用与任务最匹配的最窄导入路径。如果你找不到某个导出， +请查看 `src/plugin-sdk/` 下的源码，或在 Discord 中提问。 ## 当前弃用项 -以下是适用于整个插件 SDK、provider 契约、运行时接口和 manifest 的更窄粒度弃用项。它们目前仍可使用，但会在未来的某个主版本中移除。每一项下方的条目都会将旧 API 映射到其规范替代项。 +这些更窄范围的弃用项适用于整个插件 SDK、provider 契约、 +运行时接口面和 manifest。它们目前仍可使用，但将在未来的主要版本中移除。 +每一项下方的条目都将旧 API 映射到其规范替代方案。 - **旧版（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`, - `buildCommandsMessagePaginated`, `buildHelpMessage`。 + **旧版（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`、 + `buildCommandsMessagePaginated`、`buildHelpMessage`。 - **新版（`openclaw/plugin-sdk/command-status`）**：签名相同，导出相同——只是改为从更窄的子路径导入。`command-auth` - 会将它们作为兼容桩重新导出。 + **新版（`openclaw/plugin-sdk/command-status`）**：签名相同、导出相同—— + 只是从更窄的子路径导入。`command-auth` + 会将它们作为兼容性桩重新导出。 ```typescript // 之前 @@ -428,26 +434,28 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 `openclaw/plugin-sdk/channel-mention-gating`。 **新版**：`resolveInboundMentionDecision({ facts, policy })` —— 返回一个 - 单一决策对象，而不是拆分成两个调用。 + 单一决策对象，而不是拆分为两个调用。 - 下游渠道插件（Slack、Discord、Matrix、MS Teams）已全部完成切换。 + 下游渠道插件（Slack、Discord、Matrix、Microsoft Teams）已经完成切换。 - - `openclaw/plugin-sdk/channel-runtime` 是为旧版 - 渠道插件提供的兼容垫片。不要在新代码中导入它；请使用 + + `openclaw/plugin-sdk/channel-runtime` 是用于旧版 + 渠道插件的兼容性 shim。不要在新代码中导入它；请使用 `openclaw/plugin-sdk/channel-runtime-context` 来注册运行时 对象。 `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` - 辅助工具会与原始 “actions” 渠道导出一起弃用。请改为通过具备语义的 - `presentation` 接口暴露能力——渠道插件应声明其渲染内容（卡片、按钮、选择器），而不是声明它们接受哪些原始 action 名称。 + 辅助工具已与原始 “actions” 渠道导出一起被弃用。请改为通过语义化的 + `presentation` 接口公开能力——渠道插件应声明它们渲染什么 + （卡片、按钮、选择器），而不是声明它们接受哪些原始 + action 名称。 - **旧版**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` + **旧版**：`openclaw/plugin-sdk/provider-web-search` 中的 `tool()` 工厂。 **新版**：直接在 provider 插件上实现 `createTool(...)`。 @@ -457,21 +465,22 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 **旧版**：`formatInboundEnvelope(...)`（以及 - `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建扁平的纯文本提示 envelope。 + `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建扁平的纯文本提示 + envelope。 - **新版**：`BodyForAgent` 加上结构化用户上下文块。 - 渠道插件会将路由元数据（线程、主题、reply-to、reactions）作为 - 类型化字段附加，而不是将它们拼接进提示字符串中。 - `formatAgentEnvelope(...)` 辅助工具仍支持用于合成的、面向助手的 - envelope，但入站纯文本 envelope 正在逐步淘汰。 + **新版**：`BodyForAgent` 加上结构化的用户上下文块。渠道 + 插件会将路由元数据（线程、主题、回复目标、反应）作为 + 类型化字段附加，而不是将它们拼接到一个提示字符串中。 + `formatAgentEnvelope(...)` 辅助工具仍然支持用于合成的 + 面向助手的 envelope，但入站纯文本 envelope 正在逐步淘汰。 - 受影响区域：`inbound_claim`、`message_received`，以及任何对 - `channelEnvelope` 文本进行后处理的自定义渠道插件。 + 受影响的区域：`inbound_claim`、`message_received`，以及任何对 + `channelEnvelope` 文本做后处理的自定义渠道插件。 - - 四个发现类型别名现在只是 catalog 时代类型的薄包装： + + 四个发现类型别名现在只是目录时代类型的薄包装： | 旧别名 | 新类型 | | ------------------------- | ------------------------- | @@ -480,8 +489,9 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `ProviderDiscoveryResult` | `ProviderCatalogResult` | | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - 另外还有旧版静态包 `ProviderCapabilities`——provider 插件 - 应通过 provider 运行时契约附加 capability facts，而不是通过静态对象。 + 以及旧版的 `ProviderCapabilities` 静态集合——provider 插件 + 应通过 provider 运行时契约附加能力事实， + 而不是通过静态对象。 @@ -490,22 +500,22 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 `isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)` 和 `resolveDefaultThinkingLevel(ctx)`。 - **新版**：单一的 `resolveThinkingProfile(ctx)`，返回一个 - `ProviderThinkingProfile`，其中包含规范 `id`、可选 `label`，以及 - 排序后的级别列表。OpenClaw 会按 profile 排名自动降级过期的已存储值。 + **新版**：一个统一的 `resolveThinkingProfile(ctx)`，返回一个 + `ProviderThinkingProfile`，其中包含规范的 `id`、可选的 `label`，以及 + 按等级排序的级别列表。OpenClaw 会根据配置文件等级自动降级过期的已存储值。 - 现在只需实现一个钩子，而不是三个。旧钩子在弃用窗口期间仍可使用， - 但不会与 profile 结果进行组合。 + 你只需实现一个钩子，而不是三个。旧版钩子在 + 弃用窗口期间仍然可用，但不会与 profile 结果组合使用。 - **旧版**：实现 `resolveExternalOAuthProfiles(...)`， - 但未在插件 manifest 中声明该 provider。 + **旧版**：实现 `resolveExternalOAuthProfiles(...)`，但 + 不在插件 manifest 中声明该 provider。 **新版**：在插件 manifest 中声明 `contracts.externalAuthProviders` - **并且**实现 `resolveExternalAuthProfiles(...)`。旧的 “auth - fallback” 路径会在运行时发出警告，并将在后续移除。 + **并且**实现 `resolveExternalAuthProfiles(...)`。旧版“auth + 回退”路径会在运行时发出警告，并将在未来被移除。 ```json { @@ -520,8 +530,8 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 **旧版** manifest 字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 - **新版**：将相同的环境变量查找镜像到 manifest 中的 `setup.providers[].envVars` - 中。这样可以把设置/Status 环境变量元数据集中到一个位置， + **新版**：将相同的环境变量查找信息镜像到 manifest 中的 `setup.providers[].envVars`。 + 这样可以将 setup / Status 的环境变量元数据整合到同一个位置， 并避免仅为了响应环境变量查找而启动插件运行时。 `providerAuthEnvVars` 会通过兼容适配器继续受支持， @@ -535,11 +545,11 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 `api.registerMemoryFlushPlan(...)`、 `api.registerMemoryRuntime(...)`。 - **新版**：在 memory-state API 上进行一次调用—— + **新版**：在 memory-state API 上使用一次调用—— `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。 - 相同插槽，单次注册调用。附加型 Memory 辅助工具 - （`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, + 相同的插槽，单一注册调用。附加型 Memory 辅助工具 + （`registerMemoryPromptSupplement`、`registerMemoryCorpusSupplement`、 `registerMemoryEmbeddingProvider`）不受影响。 @@ -552,16 +562,17 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | - 运行时方法 `readSession` 已弃用，改为使用 - `getSessionMessages`。签名相同；旧方法会直接调用新方法。 + 运行时方法 `readSession` 已被弃用，改为使用 + `getSessionMessages`。签名相同；旧方法会直接调用 + 新方法。 - **旧版**：`runtime.tasks.flow`（单数）返回一个实时 task-flow 访问器。 + **旧版**：`runtime.tasks.flow`（单数）返回一个活动中的 task-flow 访问器。 **新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问， - 可安全导入，且无需加载完整任务运行时。 + 这种方式可安全导入，并且不需要加载完整任务运行时。 ```typescript // 之前 @@ -573,16 +584,16 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - 已在上文“如何迁移 → 将 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 // 之前 @@ -595,9 +606,9 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 -扩展级弃用项（位于 `extensions/` 下内置渠道/provider 插件内部） -会在它们自己的 `api.ts` 和 `runtime-api.ts` -barrel 中进行跟踪。它们不会影响第三方插件契约，因此未在此列出。 +位于 `extensions/` 下内置渠道 / provider 插件内部的扩展级弃用项， +会在它们各自的 `api.ts` 和 `runtime-api.ts` +barrel 文件中进行跟踪。它们不会影响第三方插件契约，因此这里未列出。 如果你直接使用某个内置插件的本地 barrel，请在升级前先阅读该 barrel 中的弃用注释。 @@ -606,27 +617,27 @@ 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) —— 构建 provider 插件 -- [插件内部机制](/zh-CN/plugins/architecture) —— 架构深入解析 -- [插件清单](/zh-CN/plugins/manifest) —— manifest schema 参考 +- [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件 +- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 +- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 +- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建 provider 插件 +- [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析 +- [插件 Manifest](/zh-CN/plugins/manifest) — manifest schema 参考 diff --git a/docs/zh-CN/plugins/sdk-provider-plugins.md b/docs/zh-CN/plugins/sdk-provider-plugins.md index dfdb4aa54..dccbd900b 100644 --- a/docs/zh-CN/plugins/sdk-provider-plugins.md +++ b/docs/zh-CN/plugins/sdk-provider-plugins.md @@ -1,29 +1,28 @@ --- read_when: - 你正在构建一个新的模型提供商插件 - - 你想将与 OpenAI 兼容的代理或自定义 LLM 添加到 OpenClaw 中 - - 你需要理解提供商认证、目录和运行时钩子 + - 你想将一个与 OpenAI 兼容的代理或自定义 LLM 添加到 OpenClaw 中 + - 你需要了解提供商认证、目录和运行时钩子 sidebarTitle: Provider plugins summary: 为 OpenClaw 构建模型提供商插件的分步指南 title: 构建提供商插件 x-i18n: - generated_at: "2026-04-24T18:37:22Z" + generated_at: "2026-04-25T18:12:21Z" model: gpt-5.4 provider: openai - source_hash: ddfe0e61aa08dda3134728e364fbbf077fe0edfb16e31fc102adc9585bc8c1ac + source_hash: c31f73619aa8fecf1b409bbd079683fae9ba996dd6ce22bd894b47cc76d5e856 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- -本指南将带你构建一个提供商插件，为 OpenClaw 添加一个模型提供商（LLM）。完成后，你将拥有一个具备模型目录、API 密钥认证和动态模型解析能力的提供商。 +本指南将带你逐步构建一个提供商插件，把模型提供商（LLM）添加到 OpenClaw 中。完成后，你将拥有一个具备模型目录、API 密钥认证和动态模型解析能力的提供商。 - 如果你之前没有构建过任何 OpenClaw 插件，请先阅读 - [入门指南](/zh-CN/plugins/building-plugins)，了解基础的软件包结构和清单设置。 + 如果你之前从未构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基础的软件包结构和清单设置。 - 提供商插件会将模型添加到 OpenClaw 的常规推理循环中。如果模型必须通过一个拥有线程、压缩或工具事件控制权的原生智能体守护进程运行，请将该提供商与一个 [agent harness](/zh-CN/plugins/sdk-agent-harness) 配合使用，而不是把守护进程协议细节放进核心中。 + 提供商插件会将模型接入 OpenClaw 的常规推理循环。如果模型必须通过一个原生智能体守护进程运行，并由它管理线程、压缩或工具事件，那么应将该提供商与一个 [agent harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心中。 ## 演练 @@ -71,12 +70,12 @@ x-i18n: "provider": "acme-ai", "method": "api-key", "choiceId": "acme-ai-api-key", - "choiceLabel": "Acme AI API key", + "choiceLabel": "Acme AI API 密钥", "groupId": "acme-ai", "groupLabel": "Acme AI", "cliFlag": "--acme-ai-api-key", "cliOption": "--acme-ai-api-key ", - "cliDescription": "Acme AI API key" + "cliDescription": "Acme AI API 密钥" } ], "configSchema": { @@ -87,7 +86,7 @@ x-i18n: ``` - 该清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就能在不加载你的插件运行时的情况下检测凭证。若某个提供商变体应复用另一个提供商 id 的认证，请添加 `providerAuthAliases`。`modelSupport` 是可选项，它允许 OpenClaw 在运行时钩子存在之前，依据像 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你要在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必需的。 + 清单中声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测凭证。当某个提供商变体应复用另一个提供商 id 的认证时，请添加 `providerAuthAliases`。`modelSupport` 是可选的，它让 OpenClaw 能够在运行时钩子存在之前，根据像 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你要在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必需的。 @@ -163,11 +162,11 @@ x-i18n: }); ``` - 这就是一个可工作的提供商。用户现在可以运行 + 这样就得到了一个可用的提供商。用户现在可以运行 `openclaw onboard --acme-ai-api-key `，并选择 `acme-ai/acme-large` 作为他们的模型。 - 如果上游提供商使用的控制令牌与 OpenClaw 不同，请添加一个小型双向文本转换，而不是替换流路径： + 如果上游提供商使用的控制标记与 OpenClaw 不同，请添加一个小型双向文本转换，而不是替换流路径： ```typescript api.registerTextTransforms({ @@ -184,9 +183,9 @@ x-i18n: }); ``` - `input` 会在传输前重写最终系统提示词和文本消息内容。`output` 会在 OpenClaw 解析其自身控制标记或进行渠道投递之前，重写助手文本增量和最终文本。 + `input` 会在传输前重写最终的系统提示词和文本消息内容。`output` 会在 OpenClaw 解析其自身控制标记或进行渠道投递之前，重写助手文本增量和最终文本。 - 对于仅注册一个带 API 密钥认证的文本提供商、再加上一个由目录支持的单一运行时的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数： + 对于那些只注册一个带 API 密钥认证的文本提供商，并且只有一个基于目录的运行时的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数： ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -226,15 +225,11 @@ x-i18n: }); ``` - `buildProvider` 是 OpenClaw 能够解析真实提供商认证时所使用的实时目录路径。它可以执行提供商特定的发现逻辑。仅在需要展示可安全离线显示、且在认证配置完成前就能展示的条目时使用 `buildStaticProvider`；它不得依赖凭证，也不得发起网络请求。OpenClaw 的 `models list --all` 显示当前仅对内置提供商插件执行静态目录，并且是在空配置、空环境、无智能体路径和无工作区路径的条件下执行。 + `buildProvider` 是 OpenClaw 能够解析真实提供商认证时使用的实时目录路径。它可以执行特定于提供商的发现逻辑。只有在需要展示离线条目，并且这些条目在认证配置完成之前也可安全显示时，才使用 `buildStaticProvider`；它不得要求凭证，也不得发起网络请求。OpenClaw 的 `models list --all` 显示当前只会为内置提供商插件执行静态目录，并且使用空配置、空环境变量以及没有智能体 / 工作区路径的上下文。 - 如果你的认证流程还需要在新手引导期间修补 `models.providers.*`、别名以及智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数包括 - `createDefaultModelPresetAppliers(...)`、 - `createDefaultModelsPresetAppliers(...)` 和 - `createModelCatalogPresetAppliers(...)`。 + 如果你的认证流程还需要在新手引导期间补丁 `models.providers.*`、别名和智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数包括 `createDefaultModelPresetAppliers(...)`、`createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。 - 当某个提供商的原生端点在常规 `openai-completions` 传输上支持流式 usage 块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和 - `applyProviderNativeStreamingUsageCompat(...)` 会从端点能力映射中检测支持情况，因此原生 Moonshot/DashScope 风格的端点即使使用自定义提供商 id 的插件，也仍然可以启用该能力。 + 当某个提供商的原生端点在常规 `openai-completions` 传输上支持分块流式传输用量块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不要硬编码提供商 id 判断。`supportsNativeStreamingUsageCompat(...)` 和 `applyProviderNativeStreamingUsageCompat(...)` 会根据端点能力映射检测支持情况，因此原生 Moonshot / DashScope 风格的端点即使插件使用的是自定义提供商 id，也仍然可以选择启用。 @@ -243,7 +238,7 @@ x-i18n: ```typescript api.registerProvider({ - // ... id, label, auth, catalog from above + // ... 上面的 id、label、auth、catalog resolveDynamicModel: (ctx) => ({ id: ctx.modelId, @@ -260,14 +255,14 @@ x-i18n: }); ``` - 如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热——在它完成后，`resolveDynamicModel` 会再次运行。 + 如果解析需要一次网络调用，请使用 `prepareDynamicModel` 进行异步预热——它完成后会再次运行 `resolveDynamicModel`。 - - 大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商需求增加，再逐步添加钩子。 + + 大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着提供商需求增加，再逐步添加钩子。 - 共享辅助构建器现在已经覆盖最常见的重放/工具兼容性族，因此插件通常不需要手动逐个接线每个钩子： + 共享辅助构建器现在已经覆盖最常见的重放 / 工具兼容系列，因此插件通常不需要手动逐个接线每个钩子： ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -287,43 +282,43 @@ x-i18n: }); ``` - 当前可用的重放族包括： + 当前可用的重放系列： - | Family | 它会接入的内容 | 内置示例 | + | 系列 | 它会接入的内容 | 内置示例 | | --- | --- | --- | - | `openai-compatible` | 面向与 OpenAI 兼容传输的共享 OpenAI 风格重放策略，包括工具调用 id 清洗、assistant-first 顺序修正，以及在传输需要时的通用 Gemini 轮次校验 | `moonshot`, `ollama`, `xai`, `zai` | - | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知重放策略，因此基于 Anthropic 消息的传输仅在解析出的模型实际是 Claude id 时才会获得 Claude 特定的思维块清理 | `amazon-bedrock`, `anthropic-vertex` | - | `google-gemini` | 原生 Gemini 重放策略，外加启动重放清洗和带标签的 reasoning 输出模式 | `google`, `google-gemini-cli` | - | `passthrough-gemini` | 用于通过与 OpenAI 兼容的代理传输运行 Gemini 模型时的 Gemini thought-signature 清洗；不会启用原生 Gemini 重放校验或启动重写 | `openrouter`, `kilocode`, `opencode`, `opencode-go` | - | `hybrid-anthropic-openai` | 适用于在同一个插件中混合 Anthropic 消息面和与 OpenAI 兼容模型面的提供商的混合策略；可选的仅 Claude 思维块丢弃仍然仅作用于 Anthropic 一侧 | `minimax` | + | `openai-compatible` | 面向与 OpenAI 兼容传输的共享 OpenAI 风格重放策略，包括工具调用 id 清理、assistant 优先顺序修复，以及当传输需要时的通用 Gemini 轮次校验 | `moonshot`, `ollama`, `xai`, `zai` | + | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知重放策略，因此 Anthropic message 传输只有在解析后的模型实际是 Claude id 时，才会获得特定于 Claude 的 thinking block 清理 | `amazon-bedrock`, `anthropic-vertex` | + | `google-gemini` | 原生 Gemini 重放策略，加上引导重放清理和带标签的推理输出模式 | `google`, `google-gemini-cli` | + | `passthrough-gemini` | 用于通过与 OpenAI 兼容的代理传输运行 Gemini 模型时的 Gemini thought-signature 清理；不会启用原生 Gemini 重放校验或引导重写 | `openrouter`, `kilocode`, `opencode`, `opencode-go` | + | `hybrid-anthropic-openai` | 适用于在同一个插件中混合 Anthropic message 和与 OpenAI 兼容模型表面的提供商的混合策略；可选的仅 Claude thinking block 丢弃仍然只作用于 Anthropic 一侧 | `minimax` | - 当前可用的流族包括： + 当前可用的流系列： - | Family | 它会接入的内容 | 内置示例 | + | 系列 | 它会接入的内容 | 内置示例 | | --- | --- | --- | - | `google-thinking` | 共享流路径上的 Gemini thinking 负载规范化 | `google`, `google-gemini-cli` | - | `kilocode-thinking` | 共享代理流路径上的 Kilo reasoning 包装器，其中 `kilo/auto` 和不受支持的代理 reasoning id 会跳过注入的 thinking | `kilocode` | - | `moonshot-thinking` | 根据配置和 `/think` 级别对 Moonshot 二进制原生 thinking 负载进行映射 | `moonshot` | - | `minimax-fast-mode` | 共享流路径上的 MiniMax fast-mode 模型重写 | `minimax`, `minimax-portal` | - | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归属标头、`/fast`/`serviceTier`、文本详细程度、原生 Codex web search、reasoning 兼容负载塑形，以及 Responses 上下文管理 | `openai`, `openai-codex` | - | `openrouter-thinking` | 面向代理路由的 OpenRouter reasoning 包装器，集中处理不受支持模型和 `auto` 跳过逻辑 | `openrouter` | - | `tool-stream-default-on` | 面向像 Z.AI 这样希望默认启用工具流式传输、除非显式禁用的提供商的默认开启 `tool_stream` 包装器 | `zai` | + | `google-thinking` | 在共享流路径上对 Gemini thinking 负载进行规范化 | `google`, `google-gemini-cli` | + | `kilocode-thinking` | 在共享代理流路径上为 Kilo 推理提供包装，其中 `kilo/auto` 和不受支持的代理推理 id 会跳过注入的 thinking | `kilocode` | + | `moonshot-thinking` | 根据配置和 `/think` 级别映射 Moonshot 二进制原生 thinking 负载 | `moonshot` | + | `minimax-fast-mode` | 在共享流路径上重写 MiniMax fast-mode 模型 | `minimax`, `minimax-portal` | + | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归因标头、`/fast`/`serviceTier`、文本详细程度、原生 Codex Web 搜索、推理兼容负载整形，以及 Responses 上下文管理 | `openai`, `openai-codex` | + | `openrouter-thinking` | 面向代理路由的 OpenRouter 推理包装器，集中处理不受支持模型 / `auto` 跳过 | `openrouter` | + | `tool-stream-default-on` | 为像 Z.AI 这样希望默认启用工具流式传输的提供商提供默认开启的 `tool_stream` 包装器，除非被显式禁用 | `zai` | - - 每个 family builder 都由同一软件包导出的更底层公共辅助函数组合而成，当某个提供商需要偏离通用模式时，你可以改用这些辅助函数： + + 每个系列构建器都由同一软件包导出的更底层公共辅助函数组合而成；当某个提供商需要偏离常见模式时，你可以使用它们： - - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`、`buildProviderReplayFamilyHooks(...)`，以及原始重放构建器（`buildOpenAICompatibleReplayPolicy`、`buildAnthropicReplayPolicyForModel`、`buildGoogleGeminiReplayPolicy`、`buildHybridAnthropicOrOpenAIReplayPolicy`）。还导出 Gemini 重放辅助函数（`sanitizeGoogleGeminiReplayHistory`、`resolveTaggedReasoningOutputMode`）以及端点/模型辅助函数（`resolveProviderEndpoint`、`normalizeProviderId`、`normalizeGooglePreviewModelId`、`normalizeNativeXaiModelId`）。 - - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`、`buildProviderStreamFamilyHooks(...)`、`composeProviderStreamWrappers(...)`，以及共享的 OpenAI/Codex 包装器（`createOpenAIAttributionHeadersWrapper`、`createOpenAIFastModeWrapper`、`createOpenAIServiceTierWrapper`、`createOpenAIResponsesContextManagementWrapper`、`createCodexNativeWebSearchWrapper`）和共享的代理/提供商包装器（`createOpenRouterWrapper`、`createToolStreamWrapper`、`createMinimaxFastModeWrapper`）。 - - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks("gemini")`、底层 Gemini schema 辅助函数（`normalizeGeminiToolSchemas`、`inspectGeminiToolSchemas`），以及 xAI 兼容辅助函数（`resolveXaiModelCompatPatch()`、`applyXaiModelCompat(model)`）。内置的 xAI 插件结合使用 `normalizeResolvedModel` + `contributeResolvedModelCompat` 和这些辅助函数，以确保 xAI 规则由该提供商自行维护。 + - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`、`buildProviderReplayFamilyHooks(...)`，以及原始重放构建器（`buildOpenAICompatibleReplayPolicy`、`buildAnthropicReplayPolicyForModel`、`buildGoogleGeminiReplayPolicy`、`buildHybridAnthropicOrOpenAIReplayPolicy`）。还导出 Gemini 重放辅助函数（`sanitizeGoogleGeminiReplayHistory`、`resolveTaggedReasoningOutputMode`）和端点 / 模型辅助函数（`resolveProviderEndpoint`、`normalizeProviderId`、`normalizeGooglePreviewModelId`、`normalizeNativeXaiModelId`）。 + - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`、`buildProviderStreamFamilyHooks(...)`、`composeProviderStreamWrappers(...)`，以及共享的 OpenAI/Codex 包装器（`createOpenAIAttributionHeadersWrapper`、`createOpenAIFastModeWrapper`、`createOpenAIServiceTierWrapper`、`createOpenAIResponsesContextManagementWrapper`、`createCodexNativeWebSearchWrapper`）、DeepSeek V4 与 OpenAI 兼容的包装器（`createDeepSeekV4OpenAICompatibleThinkingWrapper`），以及共享代理 / 提供商包装器（`createOpenRouterWrapper`、`createToolStreamWrapper`、`createMinimaxFastModeWrapper`）。 + - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks("gemini")`、底层 Gemini schema 辅助函数（`normalizeGeminiToolSchemas`、`inspectGeminiToolSchemas`），以及 xAI 兼容辅助函数（`resolveXaiModelCompatPatch()`、`applyXaiModelCompat(model)`）。内置的 xAI 插件会结合使用 `normalizeResolvedModel` + `contributeResolvedModelCompat` 与这些辅助函数，以确保 xAI 规则由该提供商自己管理。 - 有些流辅助函数会有意保留为提供商本地实现。`@openclaw/anthropic-provider` 将 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 Anthropic 包装器构建器保留在它自己的公共 `api.ts` / `contract-api.ts` 接缝中，因为它们编码了 Claude OAuth beta 处理和 `context1m` 门控。类似地，xAI 插件也将原生 xAI Responses 塑形保留在它自己的 `wrapStreamFn` 中（`/fast` 别名、默认 `tool_stream`、不受支持的严格工具清理、xAI 特定 reasoning 负载移除）。 + 某些流辅助函数会有意保留在提供商本地。`@openclaw/anthropic-provider` 将 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 Anthropic 包装器构建器保留在它自己的公共 `api.ts` / `contract-api.ts` 接缝中，因为这些内容编码了 Claude OAuth beta 处理和 `context1m` 门控。xAI 插件同样会在它自己的 `wrapStreamFn` 中保留原生 xAI Responses 整形（`/fast` 别名、默认 `tool_stream`、不受支持的 strict-tool 清理、xAI 特有的推理负载移除）。 - 相同的软件包根模式也支撑着 `@openclaw/openai-provider`（提供商构建器、默认模型辅助函数、实时提供商构建器）和 `@openclaw/openrouter-provider`（提供商构建器，以及新手引导/配置辅助函数）。 + 同样的软件包根模式也支撑着 `@openclaw/openai-provider`（提供商构建器、默认模型辅助函数、realtime 提供商构建器）和 `@openclaw/openrouter-provider`（提供商构建器以及新手引导 / 配置辅助函数）。 - - 对于需要在每次推理调用前进行 token 交换的提供商： + + 对于那些需要在每次推理调用前进行令牌交换的提供商： ```typescript prepareRuntimeAuth: async (ctx) => { @@ -337,10 +332,10 @@ x-i18n: ``` - 对于需要自定义请求标头或请求体修改的提供商： + 对于那些需要自定义请求标头或请求体修改的提供商： ```typescript - // wrapStreamFn 返回一个从 ctx.streamFn 派生的 StreamFn + // wrapStreamFn returns a StreamFn derived from ctx.streamFn wrapStreamFn: (ctx) => { if (!ctx.streamFn) return undefined; const inner = ctx.streamFn; @@ -354,8 +349,8 @@ x-i18n: }, ``` - - 对于需要在通用 HTTP 或 WebSocket 传输上使用原生请求/会话标头或元数据的提供商： + + 对于那些需要在通用 HTTP 或 WebSocket 传输上添加原生请求 / 会话标头或元数据的提供商： ```typescript resolveTransportTurnState: (ctx) => ({ @@ -376,7 +371,7 @@ x-i18n: ``` - 对于提供用量/计费数据的提供商： + 对于那些暴露用量 / 计费数据的提供商： ```typescript resolveUsageAuth: async (ctx) => { @@ -391,73 +386,70 @@ x-i18n: - OpenClaw 会按以下顺序调用钩子。大多数提供商只会用到 2 到 3 个： + OpenClaw 会按这个顺序调用钩子。大多数提供商只会使用 2 到 3 个： | # | Hook | 何时使用 | | --- | --- | --- | - | 1 | `catalog` | 模型目录或基础 `baseUrl` 默认值 | - | 2 | `applyConfigDefaults` | 在配置具体化期间应用由提供商维护的全局默认值 | - | 3 | `normalizeModelId` | 在查找前清理旧版/预览模型 id 别名 | - | 4 | `normalizeTransport` | 在通用模型组装前清理提供商 family 的 `api` / `baseUrl` | + | 1 | `catalog` | 模型目录或 `baseUrl` 默认值 | + | 2 | `applyConfigDefaults` | 在配置具体化期间应用由提供商拥有的全局默认值 | + | 3 | `normalizeModelId` | 在查找前清理旧版 / 预览版模型 id 别名 | + | 4 | `normalizeTransport` | 在通用模型组装前清理提供商系列的 `api` / `baseUrl` | | 5 | `normalizeConfig` | 规范化 `models.providers.` 配置 | - | 6 | `applyNativeStreamingUsageCompat` | 面向配置提供商的原生流式 usage 兼容重写 | - | 7 | `resolveConfigApiKey` | 由提供商维护的环境标记认证解析 | - | 8 | `resolveSyntheticAuth` | 本地/自托管或基于配置的合成认证 | - | 9 | `shouldDeferSyntheticProfileAuth` | 将合成存储配置文件占位符降级到环境/配置认证之后 | + | 6 | `applyNativeStreamingUsageCompat` | 为配置提供商执行原生流式用量兼容重写 | + | 7 | `resolveConfigApiKey` | 由提供商拥有的环境变量标记认证解析 | + | 8 | `resolveSyntheticAuth` | 本地 / 自托管或基于配置的合成认证 | + | 9 | `shouldDeferSyntheticProfileAuth` | 让合成的已存储配置档占位符在环境变量 / 配置认证之后生效 | | 10 | `resolveDynamicModel` | 接受任意上游模型 id | - | 11 | `prepareDynamicModel` | 在解析前异步拉取元数据 | - | 12 | `normalizeResolvedModel` | 在 runner 之前重写传输 | + | 11 | `prepareDynamicModel` | 在解析前异步获取元数据 | + | 12 | `normalizeResolvedModel` | 在进入运行器前重写传输 | | 13 | `contributeResolvedModelCompat` | 为通过另一种兼容传输暴露的厂商模型提供兼容标志 | | 14 | `capabilities` | 旧版静态能力包；仅为兼容性保留 | - | 15 | `normalizeToolSchemas` | 在注册前清理由提供商维护的工具 schema | - | 16 | `inspectToolSchemas` | 由提供商维护的工具 schema 诊断 | - | 17 | `resolveReasoningOutputMode` | 带标签与原生 reasoning 输出契约 | + | 15 | `normalizeToolSchemas` | 在注册前清理由提供商拥有的工具 schema | + | 16 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 | + | 17 | `resolveReasoningOutputMode` | 带标签与原生推理输出契约 | | 18 | `prepareExtraParams` | 默认请求参数 | - | 19 | `createStreamFn` | 完全自定义的 StreamFn 传输 | - | 20 | `wrapStreamFn` | 常规流路径上的自定义标头/请求体包装器 | - | 21 | `resolveTransportTurnState` | 原生逐轮标头/元数据 | - | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话标头/冷却时间 | - | 23 | `formatApiKey` | 自定义运行时 token 形态 | + | 19 | `createStreamFn` | 完全自定义的 `StreamFn` 传输 | + | 20 | `wrapStreamFn` | 在常规流路径上的自定义标头 / 请求体包装器 | + | 21 | `resolveTransportTurnState` | 原生逐轮标头 / 元数据 | + | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话标头 / 冷却时间 | + | 23 | `formatApiKey` | 自定义运行时令牌格式 | | 24 | `refreshOAuth` | 自定义 OAuth 刷新 | | 25 | `buildAuthDoctorHint` | 认证修复指引 | - | 26 | `matchesContextOverflowError` | 由提供商维护的上下文溢出检测 | - | 27 | `classifyFailoverReason` | 由提供商维护的限流/过载分类 | - | 28 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 | + | 26 | `matchesContextOverflowError` | 由提供商拥有的上下文溢出检测 | + | 27 | `classifyFailoverReason` | 由提供商拥有的限流 / 过载分类 | + | 28 | `isCacheTtlEligible` | 提示缓存 TTL 门控 | | 29 | `buildMissingAuthMessage` | 自定义缺失认证提示 | - | 30 | `suppressBuiltInModel` | 隐藏过时的上游条目 | + | 30 | `suppressBuiltInModel` | 隐藏已过时的上游条目 | | 31 | `augmentModelCatalog` | 合成的前向兼容条目 | - | 32 | `resolveThinkingProfile` | 模型特定的 `/think` 选项集 | - | 33 | `isBinaryThinking` | 二进制 thinking 开/关兼容性 | - | 34 | `supportsXHighThinking` | `xhigh` reasoning 支持兼容性 | + | 32 | `resolveThinkingProfile` | 特定模型的 `/think` 选项集 | + | 33 | `isBinaryThinking` | 二元 thinking 开 / 关兼容性 | + | 34 | `supportsXHighThinking` | `xhigh` 推理支持兼容性 | | 35 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略兼容性 | - | 36 | `isModernModelRef` | 实时/冒烟模型匹配 | - | 37 | `prepareRuntimeAuth` | 推理前的 token 交换 | + | 36 | `isModernModelRef` | live / smoke 模型匹配 | + | 37 | `prepareRuntimeAuth` | 推理前的令牌交换 | | 38 | `resolveUsageAuth` | 自定义用量凭证解析 | | 39 | `fetchUsageSnapshot` | 自定义用量端点 | - | 40 | `createEmbeddingProvider` | 面向 memory/search 的提供商自有 embedding 适配器 | - | 41 | `buildReplayPolicy` | 自定义转录重放/压缩策略 | - | 42 | `sanitizeReplayHistory` | 通用清理后的提供商特定重放重写 | - | 43 | `validateReplayTurns` | 在嵌入式 runner 之前严格校验重放轮次 | + | 40 | `createEmbeddingProvider` | 用于内存 / 搜索的、由提供商拥有的嵌入适配器 | + | 41 | `buildReplayPolicy` | 自定义转录重放 / 压缩策略 | + | 42 | `sanitizeReplayHistory` | 在通用清理后进行特定于提供商的重放重写 | + | 43 | `validateReplayTurns` | 在嵌入式运行器之前进行严格的重放轮次校验 | | 44 | `onModelSelected` | 选择模型后的回调（例如遥测） | 运行时回退说明： - - `normalizeConfig` 会先检查匹配到的提供商，然后再检查其他具备钩子能力的提供商插件，直到某一个实际修改了配置。如果没有任何提供商钩子重写受支持的 Google family 配置项，内置的 Google 配置规范化器仍会生效。 - - `resolveConfigApiKey` 在提供商暴露该钩子时会使用该钩子。内置的 `amazon-bedrock` 路径在这里也有一个内建的 AWS 环境标记解析器，尽管 Bedrock 运行时认证本身仍使用 AWS SDK 默认链。 - - `resolveSystemPromptContribution` 允许提供商为某个模型 family 注入具备缓存感知的系统提示词指导。当某个行为属于单一提供商/模型 family，并且需要保留稳定/动态缓存拆分时，优先使用它，而不是 `before_prompt_build`。 + - `normalizeConfig` 会先检查匹配的提供商，然后再检查其他具备钩子能力的提供商插件，直到某个插件实际修改了配置为止。如果没有任何提供商钩子重写受支持的 Google 系列配置条目，内置的 Google 配置规范化器仍会生效。 + - `resolveConfigApiKey` 会在暴露该钩子时使用提供商钩子。内置的 `amazon-bedrock` 路径在这里也带有一个内建的 AWS 环境变量标记解析器，尽管 Bedrock 运行时认证本身仍然使用 AWS SDK 默认链。 + - `resolveSystemPromptContribution` 允许提供商为某个模型系列注入带缓存感知的系统提示引导。当某个行为属于单一提供商 / 模型系列，并且应保留稳定 / 动态缓存拆分时，优先使用它而不是 `before_prompt_build`。 - 有关详细说明和真实示例，请参见 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 + 如需详细说明和真实示例，请参阅 [Internals: Provider Runtime Hooks](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 - 提供商插件除了文本推理之外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、web 获取和 web 搜索。OpenClaw 将这类插件归类为 - **混合能力** 插件——这是公司插件（每个厂商一个插件）的推荐模式。请参见 - [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。 + 提供商插件除了文本推理之外，还可以注册语音、realtime 转录、realtime 语音、媒体理解、图像生成、视频生成、网页抓取和 Web 搜索。OpenClaw 将其归类为 **hybrid-capability** 插件——这是公司级插件（每个厂商一个插件）的推荐模式。参见 [Internals: Capability Ownership](/zh-CN/plugins/architecture#capability-ownership-model)。 - 在 `register(api)` 内部、你现有的 - `api.registerProvider(...)` 调用旁边注册每项能力。只选择你需要的标签页： + 在 `register(api)` 中，与现有的 `api.registerProvider(...)` 调用一起注册每项能力。只选择你需要的标签页： @@ -495,10 +487,10 @@ x-i18n: }); ``` - 对于提供商 HTTP 失败，请使用 `assertOkOrThrowProviderError(...)`，这样插件就能共享有上限的错误体读取、JSON 错误解析以及 request-id 后缀处理。 + 对于提供商 HTTP 失败，请使用 `assertOkOrThrowProviderError(...)`，这样插件就可以共享受限的错误响应体读取、JSON 错误解析和 request-id 后缀。 - - 优先使用 `createRealtimeTranscriptionWebSocketSession(...)`——这个共享辅助函数会处理代理捕获、重连退避、关闭时冲刷、就绪握手、音频排队以及关闭事件诊断。你的插件只需要映射上游事件。 + + 优先使用 `createRealtimeTranscriptionWebSocketSession(...)` —— 这个共享辅助函数会处理代理捕获、重连退避、关闭刷新、就绪握手、音频排队和关闭事件诊断。你的插件只需要映射上游事件。 ```typescript api.registerRealtimeTranscriptionProvider({ @@ -536,11 +528,9 @@ x-i18n: }); ``` - 通过 POST multipart 音频的批量 STT 提供商应使用 - `openclaw/plugin-sdk/provider-http` 中的 - `buildAudioTranscriptionFormData(...)`。该辅助函数会规范化上传文件名，包括那些为了兼容转录 API 而需要使用 M4A 风格文件名的 AAC 上传。 + 对于通过 POST 多部分音频的批量 STT 提供商，应使用 `openclaw/plugin-sdk/provider-http` 中的 `buildAudioTranscriptionFormData(...)`。这个辅助函数会规范化上传文件名，包括那些为了兼容转录 API 而需要使用 M4A 风格文件名的 AAC 上传。 - + ```typescript api.registerRealtimeVoiceProvider({ id: "acme-ai", @@ -569,11 +559,7 @@ x-i18n: ``` - 视频能力使用一种 **模式感知** 结构：`generate`、 - `imageToVideo` 和 `videoToVideo`。像 - `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` 这样的扁平聚合字段不足以干净地声明变换模式支持或禁用模式。 - 音乐生成也遵循相同模式，使用显式的 `generate` / - `edit` 块。 + 视频能力使用一种**模式感知**结构：`generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` 这样的扁平聚合字段，不足以清晰地声明转换模式支持或禁用的模式。音乐生成也遵循同样的模式，使用显式的 `generate` / `edit` 块。 ```typescript api.registerImageGenerationProvider({ @@ -594,12 +580,12 @@ x-i18n: }); ``` - + ```typescript api.registerWebFetchProvider({ id: "acme-ai-fetch", label: "Acme Fetch", - hint: "通过 Acme 的渲染后端获取页面。", + hint: "通过 Acme 的渲染后端抓取页面。", envVars: ["ACME_FETCH_API_KEY"], placeholder: "acme-...", signupUrl: "https://acme.example.com/fetch", @@ -610,7 +596,7 @@ x-i18n: acme.apiKey = value; }, createTool: () => ({ - description: "通过 Acme Fetch 获取页面。", + description: "通过 Acme Fetch 抓取页面。", parameters: {}, execute: async (args) => ({ content: [] }), }), @@ -630,7 +616,7 @@ x-i18n: ```typescript src/provider.test.ts import { describe, it, expect } from "vitest"; - // 从 index.ts 或专用文件导出你的 provider 配置对象 + // Export your provider config object from index.ts or a dedicated file import { acmeProvider } from "./provider.js"; describe("acme-ai provider", () => { @@ -670,8 +656,7 @@ clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -这里不要使用旧版的仅 Skills 发布别名；插件包应使用 -`clawhub package publish`。 +这里不要使用旧版的仅限 Skills 的发布别名；插件软件包应使用 `clawhub package publish`。 ## 文件结构 @@ -687,14 +672,14 @@ clawhub package publish your-org/your-plugin ## 目录顺序参考 -`catalog.order` 控制你的目录相对于内置提供商的合并时机： +`catalog.order` 控制你的目录相对于内置提供商何时合并： -| Order | 时机 | 使用场景 | +| 顺序 | 时机 | 用例 | | --------- | ------------- | ----------------------------------------------- | -| `simple` | 第一轮 | 纯 API 密钥提供商 | -| `profile` | 在 simple 之后 | 受认证配置文件控制的提供商 | -| `paired` | 在 profile 之后 | 合成多个相关条目 | -| `late` | 最后一轮 | 覆盖现有提供商（冲突时胜出） | +| `simple` | 第一轮 | 纯 API 密钥提供商 | +| `profile` | 在 simple 之后 | 由认证配置档控制的提供商 | +| `paired` | 在 profile 之后 | 合成多个相关条目 | +| `late` | 最后一轮 | 覆盖现有提供商（冲突时胜出） | ## 后续步骤 diff --git a/docs/zh-CN/plugins/sdk-subpaths.md b/docs/zh-CN/plugins/sdk-subpaths.md index 8bce84983..250dd66ab 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -1,27 +1,27 @@ --- read_when: - 为插件导入选择合适的 plugin-sdk 子路径 - - 审查 bundled-plugin 子路径和辅助接口 surface + - 审查内置插件子路径和辅助接口 surface summary: 插件 SDK 子路径目录：按领域分组，哪些导入位于何处 title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-25T10:48:37Z" + generated_at: "2026-04-25T18:12:19Z" model: gpt-5.4 provider: openai - source_hash: 0f2e655d660a37030c53826b8ff156ac1897ecd3e753c1b0b43c75d456e2dfba + source_hash: b143fcc177c4d0d03fbcb4058291c99a7bb9f1f7fd04cca3916a7dbb4c22fd14 source_path: plugins/sdk-subpaths.md workflow: 15 --- 插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径对外暴露。 - 本页按用途分组，整理了常用子路径。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`； - 其中也会出现保留的 bundled-plugin 辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。 + 本页按用途对常用子路径进行归类。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`； + 其中也会列出为内置插件保留的辅助子路径，但除非某个文档页面明确推荐，否则它们都属于实现细节。 - 关于插件编写指南，参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 + 有关插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 - | 子路径 | 关键导出 | + | 子路径 | 关键导出 | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | @@ -33,33 +33,33 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | + | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | 共享的设置向导辅助函数、allowlist 提示以及设置状态构建器 | + | `plugin-sdk/setup` | 共享的设置向导辅助函数、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` | 多账户配置 / action-gate 辅助函数，以及默认账户回退辅助函数 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`，以及 account-id 规范化辅助函数 | + | `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助函数，以及默认账户回退辅助函数 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-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` | 带 bundled-contract 回退的 Telegram 自定义命令规范化 / 验证辅助函数 | - | `plugin-sdk/command-gating` | 精简的命令授权 gate 辅助函数 | + | `plugin-sdk/telegram-command-config` | 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/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/conversation-runtime` | 对话 / 线程绑定、配对和已配置绑定辅助函数 | | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 | | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 | | `plugin-sdk/channel-status` | 共享的渠道 Status 快照 / 摘要辅助函数 | @@ -69,19 +69,19 @@ x-i18n: | `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` | 面向兼容性的 barrel，包含入站去抖、提及匹配、提及策略辅助函数以及 envelope 辅助函数 | - | `plugin-sdk/channel-inbound-debounce` | 精简的入站去抖辅助函数 | - | `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时接口的精简提及策略与提及文本辅助函数 | + | `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-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助函数 | | `plugin-sdk/channel-send-result` | 回复结果类型 | | `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为插件兼容性保留的已弃用原生 schema 辅助函数 | | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 | - | `plugin-sdk/channel-contract` | 渠道 contract 类型 | + | `plugin-sdk/channel-contract` | 渠道契约类型 | | `plugin-sdk/channel-feedback` | 反馈 / reaction 接线 | - | `plugin-sdk/channel-secret-runtime` | 精简的 secret-contract 辅助函数，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret 目标类型 | + | `plugin-sdk/channel-secret-runtime` | 精简的 secret 契约辅助函数，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret target 类型 | @@ -94,22 +94,22 @@ x-i18n: | `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-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 辅助函数，以及模型 ID 规范化辅助函数，例如 `normalizeNativeXaiModelId` | | `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 配置 / 选择 contract 辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助函数 | + | `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 配置 / 凭证 contract 辅助函数，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及带作用域的凭证 setter / getter | - | `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助函数 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置 / 凭证契约辅助函数，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及作用域化的凭证设置器 / 获取器 | + | `plugin-sdk/provider-web-search` | Web 搜索提供商注册 / 缓存 / 运行时辅助函数 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + diagnostics，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `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` | 新手引导配置 patch 辅助函数 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / DeepSeek V4 / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助函数 | + | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助函数，例如受保护的 fetch、传输消息转换以及可写传输事件流 | + | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 | | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助函数 | | `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助函数 | @@ -119,28 +119,28 @@ x-i18n: | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数（包括动态参数菜单格式化）、发送者授权辅助函数 | | `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | 审批者解析和同一聊天 action-auth 辅助函数 | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助函数 | | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件 / 过滤器辅助函数 | | `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 投递适配器 | | `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助函数 | - | `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量原生审批适配器加载辅助函数 | - | `plugin-sdk/approval-handler-runtime` | 更宽泛的审批处理器运行时辅助函数；如果更精简的 adapter / gateway 接口已经足够，优先使用它们 | + | `plugin-sdk/approval-handler-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` | 不含宽泛测试 barrel 的精简渠道 contract 测试辅助函数 | - | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化，以及原生会话目标辅助函数 | + | `plugin-sdk/channel-contract-testing` | 精简的渠道契约测试辅助函数，不包含宽泛的测试 barrel | + | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化以及原生会话目标辅助函数 | | `plugin-sdk/command-detection` | 共享的命令检测辅助函数 | - | `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量命令文本谓词 | - | `plugin-sdk/command-surface` | 命令体规范化和命令 surface 辅助函数 | + | `plugin-sdk/command-primitives-runtime` | 面向热渠道路径的轻量级命令文本谓词 | + | `plugin-sdk/command-surface` | 命令主体规范化和命令接口辅助函数 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret surface 的精简 secret-contract 收集辅助函数 | - | `plugin-sdk/secret-ref-runtime` | 面向 secret-contract / 配置解析的精简 `coerceSecretRef` 和 `SecretRef` 类型辅助函数 | - | `plugin-sdk/security-runtime` | 共享的信任、私信 gating、外部内容和 secret 收集辅助函数 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 接口的精简 secret 契约收集辅助函数 | + | `plugin-sdk/secret-ref-runtime` | 面向 secret 契约 / 配置解析的精简 `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/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` | 请求体大小 / 超时辅助函数 | @@ -150,32 +150,32 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/runtime` | 宽泛的运行时 / 日志 / 备份 / 插件安装辅助函数 | - | `plugin-sdk/runtime-env` | 精简的运行时 env、logger、timeout、retry 和 backoff 辅助函数 | - | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助函数 | + | `plugin-sdk/runtime-env` | 精简的运行时环境、logger、超时、重试和退避辅助函数 | + | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助函数 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | | `plugin-sdk/plugin-runtime` | 共享的插件命令 / hook / HTTP / 交互式辅助函数 | - | `plugin-sdk/hook-runtime` | 共享的 webhook / 内部钩子 pipeline 辅助函数 | - | `plugin-sdk/lazy-runtime` | 延迟运行时导入 / 绑定辅助函数，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | + | `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 网关客户端和渠道 Status patch 辅助函数 | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道 Status 补丁辅助函数 | | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助函数，以及插件配置查找辅助函数 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化，以及重复 / 冲突检查；即使 bundled Telegram contract surface 不可用时也可使用 | - | `plugin-sdk/text-autolink-runtime` | 不含宽泛 text-runtime barrel 的文件引用自动链接检测 | + | `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-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/session-store-runtime` | 会话存储路径 + `updated-at` 辅助函数 | | `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助函数 | - | `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助函数，例如 `resolveAgentRoute`, `buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享的渠道 / 账户 Status 摘要辅助函数、运行时状态默认值和问题元数据辅助函数 | + | `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/run-command` | 带超时的命令运行器，返回规范化的 stdout / stderr 结果 | | `plugin-sdk/param-readers` | 通用工具 / CLI 参数读取器 | | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 | | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | @@ -186,30 +186,30 @@ x-i18n: | `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/acp-binding-resolve-runtime` | 只读 ACP 绑定解析，不引入生命周期启动导入 | + | `plugin-sdk/agent-config-primitives` | 精简的 Agent Runtimes 配置 schema 基元 | + | `plugin-sdk/boolean-param` | 宽松的布尔参数读取器 | | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 | | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 | - | `plugin-sdk/extension-shared` | 共享的被动渠道、Status 和 ambient proxy 辅助基元 | + | `plugin-sdk/extension-shared` | 共享的被动渠道、Status 和环境代理辅助基元 | | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 | | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助函数 | - | `plugin-sdk/native-command-registry` | 原生命令注册表构建 / 序列化辅助函数 | - | `plugin-sdk/agent-harness` | 面向低层 Agent harness 的实验性受信任插件接口：harness 类型、活动运行 steer / abort 辅助函数、OpenClaw 工具桥接辅助函数、工具进度格式化 / 细节辅助函数，以及尝试结果工具函数 | + | `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助函数 | + | `plugin-sdk/agent-harness` | 面向低级智能体 harness 的实验性受信任插件接口：harness 类型、活动运行 steer / abort 辅助函数、OpenClaw 工具桥接辅助函数、工具进度格式化 / 详情辅助函数，以及尝试结果工具函数 | | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助函数 | | `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助函数 | | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 | | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 包装后的 fetch、proxy 和 pinned 查找辅助函数 | - | `plugin-sdk/runtime-fetch` | 不含 proxy / guarded-fetch 导入的、具备 dispatcher 感知能力的运行时 fetch | - | `plugin-sdk/response-limit-runtime` | 不含宽泛 media-runtime surface 的有界响应体读取器 | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和固定查找辅助函数 | + | `plugin-sdk/runtime-fetch` | 具备 dispatcher 感知能力的运行时 fetch，不引入代理 / guarded-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/session-store-runtime` | 会话存储读取辅助函数，不包含宽泛的配置写入 / 维护导入 | + | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不包含宽泛的配置 / 安全导入 | + | `plugin-sdk/string-coerce-runtime` | 精简的原始记录 / 字符串强制转换与规范化辅助函数，不包含 markdown / 日志导入 | | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 | - | `plugin-sdk/retry-runtime` | retry 配置和 retry 运行器辅助函数 | + | `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助函数 | | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助函数 | | `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | @@ -220,20 +220,20 @@ x-i18n: | --- | --- | | `plugin-sdk/media-runtime` | 共享的媒体获取 / 转换 / 存储辅助函数，以及媒体负载构建器 | | `plugin-sdk/media-store` | 精简的媒体存储辅助函数，例如 `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障转移辅助函数、候选项选择以及缺失模型提示 | + | `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障切换辅助函数、候选项选择以及缺失模型提示 | | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享的文本 / Markdown / 日志辅助函数，例如 assistant 可见文本剥离、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数，以及安全文本工具函数 | + | `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/speech` | 语音提供商类型，以及面向提供商的指令、注册表、验证和语音辅助导出 | + | `plugin-sdk/speech-core` | 共享的语音提供商类型、注册表、指令、规范化和语音辅助导出 | + | `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/video-generation-core` | 共享的视频生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 | | `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助函数 | | `plugin-sdk/webhook-path` | Webhook 路径规范化辅助函数 | | `plugin-sdk/web-media` | 共享的远程 / 本地媒体加载辅助函数 | @@ -244,38 +244,38 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | bundled memory-core 辅助接口，用于 manager / config / file / CLI 辅助函数 | + | `plugin-sdk/memory-core` | 面向 manager / config / file / CLI 辅助函数的内置 memory-core 辅助接口 | | `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 contract、注册表访问、本地 provider，以及通用批处理 / 远程辅助函数 | - | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储 engine 导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助函数 | - | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助函数 | - | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助函数 | - | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助函数 | - | `plugin-sdk/memory-core-host-status` | Memory host Status 辅助函数 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助函数 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助函数 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助函数 | - | `plugin-sdk/memory-host-core` | 面向 vendor 中立的别名，用于 memory host 核心运行时辅助函数 | - | `plugin-sdk/memory-host-events` | 面向 vendor 中立的别名，用于 memory host 事件日志辅助函数 | - | `plugin-sdk/memory-host-files` | 面向 vendor 中立的别名，用于 memory host 文件 / 运行时辅助函数 | - | `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助函数 | - | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时门面 | - | `plugin-sdk/memory-host-status` | 面向 vendor 中立的别名，用于 memory host Status 辅助函数 | - | `plugin-sdk/memory-lancedb` | bundled memory-lancedb 辅助接口 | + | `plugin-sdk/memory-core-host-engine-foundation` | Memory 主机基础引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机嵌入契约、注册表访问、本地提供商以及通用批处理 / 远程辅助函数 | + | `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 运行时门面 | + | `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` | bundled 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` | bundled Matrix 辅助 / 运行时接口 | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | bundled LINE 辅助 / 运行时接口 | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | bundled 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` | bundled 渠道兼容性 / 辅助接口 | - | 认证 / 插件特定辅助函数 | `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` | bundled 功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | 浏览器 | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置浏览器插件支持辅助函数。`browser-profiles` 导出 `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 结构。`browser-support` 仍然是兼容性 barrel。 | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助 / 运行时接口 | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助 / 运行时接口 | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 | + | 渠道专用辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/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/litellm.md b/docs/zh-CN/providers/litellm.md index aa06c3acc..d480239b1 100644 --- a/docs/zh-CN/providers/litellm.md +++ b/docs/zh-CN/providers/litellm.md @@ -1,28 +1,28 @@ --- read_when: - - 你想通过 LiteLLM proxy 路由 OpenClaw + - 你想通过 LiteLLM 代理来路由 OpenClaw - 你需要通过 LiteLLM 实现成本跟踪、日志记录或模型路由 -summary: 通过 LiteLLM Proxy 运行 OpenClaw，以实现统一模型访问和成本跟踪 +summary: 通过 LiteLLM Proxy 运行 OpenClaw，以实现统一的模型访问和成本跟踪 title: LiteLLM x-i18n: - generated_at: "2026-04-23T21:00:39Z" + generated_at: "2026-04-25T18:12:26Z" model: gpt-5.4 provider: openai - source_hash: 9da14e6ded4c9e0b54989898a982987c0a60f6f6170d10b6cd2eddcd5106630f + source_hash: f4e2cdddff8dd953b989beb4f2ed1c31dae09298dacd0cf809ef07b41358623b source_path: providers/litellm.md workflow: 15 --- -[LiteLLM](https://litellm.ai) 是一个开源 LLM 网关，为 100+ 模型提供商提供统一 API。通过 LiteLLM 路由 OpenClaw，可以获得集中式成本跟踪、日志记录，以及在无需修改 OpenClaw 配置的情况下切换后端的灵活性。 +[LiteLLM](https://litellm.ai) 是一个开源的 LLM 网关，为 100 多家模型提供商提供统一的 API。通过 LiteLLM 路由 OpenClaw，以获得集中式成本跟踪、日志记录，以及在不更改 OpenClaw 配置的情况下切换后端的灵活性。 -**为什么要将 LiteLLM 与 OpenClaw 配合使用？** +**为什么将 LiteLLM 与 OpenClaw 搭配使用？** -- **成本跟踪** —— 精确查看 OpenClaw 在所有模型上的花费 -- **模型路由** —— 无需更改配置即可在 Claude、GPT-4、Gemini、Bedrock 之间切换 -- **虚拟密钥** —— 为 OpenClaw 创建带消费限制的密钥 -- **日志记录** —— 用于调试的完整请求/响应日志 -- **回退** —— 当主提供商不可用时自动故障切换 +- **成本跟踪** — 精确查看 OpenClaw 在所有模型上的花费 +- **模型路由** — 无需更改配置，即可在 Claude、GPT-4、Gemini、Bedrock 之间切换 +- **虚拟密钥** — 为 OpenClaw 创建带有支出限制的密钥 +- **日志记录** — 完整的请求/响应日志，便于调试 +- **故障回退** — 如果你的主要提供商宕机，则自动故障转移 @@ -30,7 +30,7 @@ x-i18n: - **最适合：** 最快获得可用 LiteLLM 配置的路径。 + **最适合：** 以最快的方式完成可用的 LiteLLM 设置。 @@ -43,7 +43,7 @@ x-i18n: - **最适合：** 希望完全控制安装和配置。 + **最适合：** 完全控制安装和配置。 @@ -52,14 +52,14 @@ x-i18n: litellm --model claude-opus-4-6 ``` - + ```bash export LITELLM_API_KEY="your-litellm-key" openclaw ``` - 就这样。OpenClaw 现在会通过 LiteLLM 路由。 + 就这样。OpenClaw 现在会通过 LiteLLM 进行路由。 @@ -115,9 +115,36 @@ export LITELLM_API_KEY="sk-litellm-key" ## 高级配置 +### 图像生成 + +LiteLLM 也可以通过与 OpenAI 兼容的 `/images/generations` 和 `/images/edits` 路由，为 `image_generate` 工具提供支持。在 `agents.defaults.imageGenerationModel` 下配置一个 LiteLLM 图像模型： + +```json5 +{ + models: { + providers: { + litellm: { + baseUrl: "http://localhost:4000", + apiKey: "${LITELLM_API_KEY}", + }, + }, + }, + agents: { + defaults: { + imageGenerationModel: { + primary: "litellm/gpt-image-2", + timeoutMs: 180_000, + }, + }, + }, +} +``` + +诸如 `http://localhost:4000` 这样的 loopback LiteLLM URL 无需全局私有网络覆盖即可工作。对于局域网上托管的代理，请设置 `models.providers.litellm.request.allowPrivateNetwork: true`，因为 API 密钥将被发送到配置的代理主机。 + - 为 OpenClaw 创建一个带消费限制的专用密钥： + 为 OpenClaw 创建一个带支出限制的专用密钥： ```bash curl -X POST "http://localhost:4000/key/generate" \ @@ -135,7 +162,7 @@ export LITELLM_API_KEY="sk-litellm-key" - LiteLLM 可以将模型请求路由到不同后端。在你的 LiteLLM `config.yaml` 中进行配置： + LiteLLM 可以将模型请求路由到不同的后端。在你的 LiteLLM `config.yaml` 中进行配置： ```yaml model_list: @@ -150,49 +177,45 @@ export LITELLM_API_KEY="sk-litellm-key" api_key: os.environ/OPENAI_API_KEY ``` - OpenClaw 仍然请求 `claude-opus-4-6` —— 路由由 LiteLLM 负责处理。 + OpenClaw 会继续请求 `claude-opus-4-6` —— 路由由 LiteLLM 处理。 - - 查看 LiteLLM 的仪表盘或 API： + + 检查 LiteLLM 的仪表板或 API： ```bash - # 密钥信息 + # Key info curl "http://localhost:4000/key/info" \ -H "Authorization: Bearer sk-litellm-key" - # 消费日志 + # Spend logs curl "http://localhost:4000/spend/logs" \ -H "Authorization: Bearer $LITELLM_MASTER_KEY" ``` - + - LiteLLM 默认运行在 `http://localhost:4000` - - OpenClaw 会通过 LiteLLM 的 OpenAI 兼容 `/v1` - 代理端点进行连接 - - 通过 LiteLLM 时，不会应用 OpenAI 原生专属请求整形： - 没有 `service_tier`，没有 Responses `store`，没有提示词缓存提示，也没有 - OpenAI 推理兼容载荷整形 - - 在自定义 LiteLLM base URL 上，不会注入 - 隐藏的 OpenClaw 归因 headers（`originator`、`version`、`User-Agent`） + - OpenClaw 通过 LiteLLM 的代理式、与 OpenAI 兼容的 `/v1` 端点进行连接 + - 原生仅限 OpenAI 的请求整形不适用于通过 LiteLLM 的场景：没有 `service_tier`、没有 Responses `store`、没有提示缓存提示，也没有 OpenAI 推理兼容负载整形 + - 在自定义 LiteLLM base URL 上，不会注入隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`） -有关通用提供商配置和故障切换行为，请参见 [模型提供商](/zh-CN/concepts/model-providers)。 +有关通用提供商配置和故障转移行为，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。 ## 相关内容 - - 官方 LiteLLM 文档和 API 参考。 + + LiteLLM 官方文档和 API 参考。 - 所有提供商、模型引用和故障切换行为概览。 + 所有提供商、模型引用和故障转移行为的概览。 完整配置参考。 diff --git a/docs/zh-CN/reference/transcript-hygiene.md b/docs/zh-CN/reference/transcript-hygiene.md index 073ac9a6b..99c48113e 100644 --- a/docs/zh-CN/reference/transcript-hygiene.md +++ b/docs/zh-CN/reference/transcript-hygiene.md @@ -1,81 +1,85 @@ --- read_when: - - 你正在调试与转录结构相关的 provider 请求拒绝问题 - - 你正在修改转录清理或工具调用修复逻辑 - - 你正在调查跨 provider 的工具调用 id 不匹配问题 -summary: 参考：provider 特定的转录清理与修复规则 -title: 转录清理规范 + - 你正在调试与转录结构相关的提供商请求拒绝问题 + - 你正在更改转录清理或工具调用修复逻辑 + - 你正在调查跨提供商的工具调用 ID 不匹配问题 +summary: 参考：提供商特定的转录清理与修复规则 +title: 转录规范 x-i18n: - generated_at: "2026-04-25T05:56:41Z" + generated_at: "2026-04-25T18:12:20Z" model: gpt-5.4 provider: openai - source_hash: 00cac47fb9a238e3cb8b6ea69b47210685ca6769a31973b4aeef1d18e75d78e6 + source_hash: 880a72d4f73e195ff93f26537d3c80c88dc454691765d3d44032ff43076a07c3 source_path: reference/transcript-hygiene.md workflow: 15 --- -本文档说明在运行前（构建模型上下文时）应用于转录的**provider 特定修复**。这些是用于满足严格 provider 要求的**仅内存**调整。这些清理步骤**不会**重写磁盘上存储的 JSONL 转录；不过，在加载会话之前，单独的会话文件修复过程可能会通过丢弃无效行来重写格式错误的 JSONL 文件。发生修复时，原始文件会在会话文件旁边生成备份。 +本文档描述了在一次运行前（构建模型上下文时）应用于转录的**提供商特定修复**。其中大多数是用于满足严格提供商要求的**内存中**调整。另有一个独立的会话文件修复过程，也可能在加载会话之前重写已存储的 JSONL：要么丢弃格式错误的 JSONL 行，要么修复那些语法上有效但已知会在回放期间被提供商拒绝的持久化轮次。发生修复时，原始文件会在会话文件旁边备份。 范围包括： -- 仅运行时的提示上下文保持不进入用户可见的转录轮次 -- 工具调用 id 清理 +- 仅运行时的提示上下文，不进入用户可见的转录轮次 +- 工具调用 ID 清理 - 工具调用输入验证 - 工具结果配对修复 -- 轮次验证/排序 -- thought signature 清理 -- 图像载荷清理 -- 用户输入来源标记（用于跨会话路由提示） +- 轮次验证 / 排序 +- 思考签名清理 +- 图像负载清理 +- 用户输入来源标记（用于跨会话路由的提示） +- Bedrock Converse 回放时的空 assistant 错误轮次修复 -如果你需要转录存储细节，请参见： +如果你需要了解转录存储细节，请参见： -- [会话管理深入解析](/zh-CN/reference/session-management-compaction) +- [会话管理深度解析](/zh-CN/reference/session-management-compaction) --- ## 全局规则：运行时上下文不是用户转录 -运行时/系统上下文可以添加到某个轮次的模型提示中，但它不是最终用户撰写的内容。OpenClaw 会为 Gateway 网关回复、排队的后续操作、ACP、CLI 和嵌入式 Pi 运行保留一个单独的、面向转录的提示正文。存储的可见用户轮次使用该转录正文，而不是运行时增强后的提示。 +运行时 / 系统上下文可以添加到某一轮的模型提示中，但它不是终端用户撰写的内容。OpenClaw 会为 Gateway 网关 回复、排队的后续操作、ACP、CLI 以及嵌入式 Pi 运行保留一个面向转录的独立提示正文。已存储的可见用户轮次使用该转录正文，而不是经过运行时增强的提示。 -对于已经持久化了运行时包装器的旧会话，Gateway 网关历史记录界面会在将消息返回给 WebChat、TUI、REST 或 SSE 客户端之前应用显示投影。 +对于已经持久化了运行时包装器的旧会话，Gateway 网关 历史记录展示层会在将消息返回给 WebChat、TUI、REST 或 SSE 客户端之前应用显示投影。 --- ## 运行位置 -所有转录清理都集中在嵌入式运行器中： +所有转录规范处理都集中在嵌入式运行器中： - 策略选择：`src/agents/transcript-policy.ts` -- 清理/修复应用：`src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` +- 清理 / 修复应用：`src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` -该策略使用 `provider`、`modelApi` 和 `modelId` 来决定应用哪些规则。 +该策略使用 `provider`、`modelApi` 和 `modelId` 来决定要应用哪些处理。 -与转录清理分开的是，会话文件会在加载前按需修复： +与转录规范处理分开的是，会话文件会在加载前按需修复： - `src/agents/session-file-repair.ts` 中的 `repairSessionFileIfNeeded` -- 从 `run/attempt.ts` 和 `compact.ts`（嵌入式运行器）调用 +- 由 `run/attempt.ts` 和 `compact.ts`（嵌入式运行器）调用 --- ## 全局规则：图像清理 -图像载荷始终会被清理，以防止因大小限制导致 provider 侧拒绝（对过大的 base64 图像进行缩放/重新压缩）。 +图像负载始终会经过清理，以防因尺寸限制而被提供商拒绝 +（对过大的 base64 图像进行缩放 / 重新压缩）。 -这也有助于控制视觉能力模型下由图像驱动的 token 压力。较低的最大尺寸通常会减少 token 使用；较高的尺寸则保留更多细节。 +这也有助于控制视觉模型的图像驱动 token 压力。 +较小的最大尺寸通常会减少 token 使用量；较大的尺寸则可保留更多细节。 -实现： +实现位置： - `src/agents/pi-embedded-helpers/images.ts` 中的 `sanitizeSessionMessagesImages` - `src/agents/tool-images.ts` 中的 `sanitizeContentBlocksImages` -- 最大图像边长可通过 `agents.defaults.imageMaxDimensionPx` 配置（默认：`1200`）。 +- 最大图像边长可通过 `agents.defaults.imageMaxDimensionPx` 配置（默认值：`1200`）。 --- ## 全局规则：格式错误的工具调用 -缺少 `input` 和 `arguments` 的助手工具调用块会在构建模型上下文之前被丢弃。这可防止 provider 因部分持久化的工具调用而拒绝请求（例如，在速率限制失败之后）。 +缺少 `input` 和 `arguments` 的 assistant 工具调用块会在构建模型上下文之前被丢弃。 +这可防止提供商因部分持久化的工具调用而拒绝请求（例如，在速率限制失败之后）。 -实现： +实现位置： - `src/agents/session-transcript-repair.ts` 中的 `sanitizeToolCallInputs` - 在 `src/agents/pi-embedded-runner/replay-history.ts` 的 `sanitizeSessionHistory` 中应用 @@ -84,72 +88,85 @@ x-i18n: ## 全局规则：跨会话输入来源 -当智能体通过 `sessions_send` 向另一个会话发送提示时（包括智能体到智能体的 reply/announce 步骤），OpenClaw 会在追加转录时将创建的用户轮次持久化为： +当某个智能体通过 `sessions_send` 将提示发送到另一个会话时（包括 +智能体到智能体的回复 / 通知步骤），OpenClaw 会将创建的用户轮次持久化为： - `message.provenance.kind = "inter_session"` -该元数据会在转录追加时写入，不会更改角色 -（为了 provider 兼容性，仍保留 `role: "user"`）。转录读取器可以利用这一点，避免将路由的内部提示视为最终用户撰写的指令。 +该元数据在追加到转录时写入，不会改变角色 +（为兼容提供商，`role: "user"` 保持不变）。转录读取器可利用这一点， +避免将路由过来的内部提示当作终端用户撰写的指令。 -在重建上下文期间，OpenClaw 还会在内存中为这些用户轮次前置一个简短的 `[Inter-session message]` 标记，以便模型将其与外部最终用户指令区分开来。 +在重建上下文期间，OpenClaw 还会在内存中为这些用户轮次添加一个简短的 `[Inter-session message]` +标记前缀，以便模型将它们与外部终端用户指令区分开来。 --- -## provider 矩阵（当前行为） +## 提供商矩阵（当前行为） **OpenAI / OpenAI Codex** -- 仅图像清理。 -- 对于 OpenAI Responses/Codex 转录，丢弃孤立的 reasoning signature（后面没有内容块的独立 reasoning 项），并在模型路由切换后丢弃可重放的 OpenAI reasoning。 -- 不做工具调用 id 清理。 +- 仅进行图像清理。 +- 对于 OpenAI Responses / Codex 转录，丢弃孤立的 reasoning 签名（后面没有内容块的独立 reasoning 项）；在模型路由切换后，丢弃可回放的 OpenAI reasoning。 +- 不进行工具调用 ID 清理。 - 工具结果配对修复可能会移动真实匹配的输出，并为缺失的工具调用合成 Codex 风格的 `aborted` 输出。 -- 不做轮次验证或重排序。 -- 缺失的 OpenAI Responses 系列工具输出会被合成为 `aborted`，以匹配 Codex 重放规范化。 -- 不剥离 thought signature。 +- 不进行轮次验证或重排序。 +- 缺失的 OpenAI Responses 系列工具输出会被合成为 `aborted`，以匹配 Codex 回放规范化。 +- 不移除 thought 签名。 **Google（Generative AI / Gemini CLI / Antigravity）** -- 工具调用 id 清理：严格字母数字。 +- 工具调用 ID 清理：严格字母数字。 - 工具结果配对修复和合成工具结果。 -- 轮次验证（Gemini 风格轮次交替）。 -- Google 轮次顺序修复（如果历史以 assistant 开头，则前置一个极小的 user 引导项）。 -- Antigravity Claude：规范化 thinking signature；丢弃未签名的 thinking 块。 +- 轮次验证（Gemini 风格的轮次交替）。 +- Google 轮次排序修复（如果历史记录以 assistant 开始，则在前面加一个极小的用户引导消息）。 +- Antigravity Claude：规范化 thinking 签名；丢弃未签名的 thinking 块。 -**Anthropic / MiniMax（Anthropic 兼容）** +**Anthropic / Minimax（Anthropic 兼容）** - 工具结果配对修复和合成工具结果。 -- 轮次验证（合并连续的 user 轮次以满足严格交替要求）。 +- 轮次验证（合并连续的用户轮次，以满足严格交替要求）。 + +**Amazon Bedrock（Converse API）** + +- 空的 assistant 流错误轮次会在回放前修复为非空的回退文本块。 + Bedrock Converse 会拒绝 `content: []` 的 assistant 消息，因此 + 带有 `stopReason: "error"` 且内容为空的持久化 assistant 轮次，也会在加载前于磁盘上修复。 +- 回放会过滤 OpenClaw 投递镜像和 Gateway 网关 注入的 assistant 轮次。 +- 图像清理通过全局规则应用。 **Mistral（包括基于 model-id 的检测）** -- 工具调用 id 清理：strict9（长度为 9 的字母数字）。 +- 工具调用 ID 清理：strict9（长度为 9 的字母数字）。 **OpenRouter Gemini** -- thought signature 清理：剥离非 base64 的 `thought_signature` 值（保留 base64）。 +- 思考签名清理：移除非 base64 的 `thought_signature` 值（保留 base64）。 **其他所有情况** -- 仅图像清理。 +- 仅进行图像清理。 --- ## 历史行为（2026.1.22 之前） -在 2026.1.22 版本之前，OpenClaw 应用了多层转录清理： +在 2026.1.22 版本之前，OpenClaw 应用了多层转录规范处理： -- 每次构建上下文时都会运行一个 **transcript-sanitize 扩展**，其可以： - - 修复工具使用/结果配对。 - - 清理工具调用 id（包括保留 `_`/`-` 的非严格模式）。 -- 运行器还会执行 provider 特定清理，从而导致重复处理。 -- 另外还有一些发生在 provider 策略之外的变更，包括： - - 在持久化前从助手文本中剥离 `` 标签。 - - 丢弃空的助手错误轮次。 - - 在工具调用后裁剪助手内容。 +- 一个 **transcript-sanitize extension** 会在每次构建上下文时运行，并且可以： + - 修复工具使用 / 结果配对。 + - 清理工具调用 ID（包括保留 `_` / `-` 的非严格模式）。 +- 运行器还会执行提供商特定清理，这造成了重复处理。 +- 提供商策略之外还存在额外的变更，包括： + - 在持久化前从 assistant 文本中移除 `` 标签。 + - 丢弃空的 assistant 错误轮次。 + - 在工具调用后裁剪 assistant 内容。 -这种复杂性导致了跨 provider 的回归问题（尤其是 `openai-responses` 的 `call_id|fc_id` 配对）。2026.1.22 的清理移除了该扩展，将逻辑集中到运行器中，并让 OpenAI 除图像清理之外保持**不触碰**。 +这种复杂性导致了跨提供商回归问题（尤其是 `openai-responses` +`call_id|fc_id` 配对）。2026.1.22 的清理移除了该扩展，将 +逻辑集中到运行器中，并使 OpenAI 除图像清理外保持**不做额外处理**。 ## 相关内容 - [会话管理](/zh-CN/concepts/session) -- [会话清理](/zh-CN/concepts/session-pruning) +- [会话修剪](/zh-CN/concepts/session-pruning) diff --git a/docs/zh-CN/tools/browser.md b/docs/zh-CN/tools/browser.md index 2a14fc1ae..aabc46c2f 100644 --- a/docs/zh-CN/tools/browser.md +++ b/docs/zh-CN/tools/browser.md @@ -2,41 +2,40 @@ read_when: - 添加由智能体控制的浏览器自动化 - 调试为什么 openclaw 会干扰你自己的 Chrome - - 在 macOS 应用中实现浏览器设置 + 生命周期 + - 在 macOS 应用中实现浏览器设置和生命周期管理 summary: 集成式浏览器控制服务 + 操作命令 title: 浏览器（由 OpenClaw 管理） x-i18n: - generated_at: "2026-04-25T17:32:12Z" + generated_at: "2026-04-25T18:12:52Z" model: gpt-5.4 provider: openai - source_hash: c4a136bf08703bd108badcd01c02e961d76785f8d23d1c5035e5038963885796 + source_hash: 6379873662b21972493f62951c0fb87c4a9ec6350cec750acaf6a50235bd69c3 source_path: tools/browser.md workflow: 15 --- -OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置档案**，由智能体控制。 -它与你的个人浏览器隔离，并通过 Gateway 网关内部的一个小型本地 -控制服务进行管理（仅 loopback）。 +OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。 +它与你的个人浏览器相互隔离，并通过 Gateway 网关内部的一个小型本地控制服务进行管理 +（仅限 loopback）。 -初学者视角： +面向初学者的理解方式： -- 可以把它理解为一个**独立的、仅供智能体使用的浏览器**。 -- `openclaw` 配置档案**不会**触碰你的个人浏览器配置档案。 +- 可以把它看作一个**独立的、仅供智能体使用的浏览器**。 +- `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。 - 智能体可以在一个安全通道中**打开标签页、读取页面、点击和输入**。 -- 内置的 `user` 配置档案会通过 Chrome MCP 连接到你真实的已登录 Chrome 会话。 +- 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实的、已登录的 Chrome 会话。 -## 你将获得什么 +## 你将获得的内容 -- 一个名为 **openclaw** 的独立浏览器配置档案（默认使用橙色强调色）。 +- 一个名为 **openclaw** 的独立浏览器配置文件（默认使用橙色强调色）。 - 可预测的标签页控制（列出/打开/聚焦/关闭）。 - 智能体操作（点击/输入/拖拽/选择）、快照、截图、PDF。 -- 一个内置的 `browser-automation` Skills，在浏览器 - 插件启用时，教会智能体使用 snapshot、 - stable-tab、stale-ref 和 manual-blocker 恢复循环。 -- 可选的多配置档案支持（`openclaw`、`work`、`remote`，等等）。 +- 一个内置的 `browser-automation` Skills，当启用浏览器插件时，它会教智能体使用快照、 + 稳定标签页、过期引用和手动阻塞恢复循环。 +- 可选的多配置文件支持（`openclaw`、`work`、`remote` 等）。 -这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的表面，用于 -智能体自动化和验证。 +这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的界面， +用于智能体自动化和验证。 ## 快速开始 @@ -48,15 +47,15 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -如果你看到 “Browser disabled”，请在配置中启用它（见下文），然后重启 +如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 Gateway 网关。 -如果完全没有 `openclaw browser`，或者智能体提示浏览器工具 -不可用，请跳转到 [缺失的浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 +如果 `openclaw browser` 命令完全不存在，或者智能体提示浏览器工具不可用， +请跳转到 [缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 ## 插件控制 -默认的 `browser` 工具是一个内置插件。如果你想用另一个注册相同 `browser` 工具名称的插件替换它，请禁用它： +默认的 `browser` 工具是一个内置插件。若要用另一个注册了相同 `browser` 工具名称的插件替换它，请将其禁用： ```json5 { @@ -70,15 +69,15 @@ Gateway 网关。 } ``` -默认值要求同时设置 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。仅禁用插件会将 `openclaw browser` CLI、`browser.request` 网关方法、智能体工具和控制服务作为一个整体移除；你的 `browser.*` 配置将保持不变，以便替换方案使用。 +默认情况下，需要同时满足 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。仅禁用插件会一次性移除 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具和控制服务；你的 `browser.*` 配置会保持不变，以供替代方案使用。 浏览器配置变更需要重启 Gateway 网关，以便插件重新注册其服务。 ## 智能体指引 -工具配置档案说明：`tools.profile: "coding"` 包含 `web_search` 和 +工具配置文件说明：`tools.profile: "coding"` 包含 `web_search` 和 `web_fetch`，但不包含完整的 `browser` 工具。如果智能体或某个 -派生的子智能体需要使用浏览器自动化，请在配置档案阶段添加 browser： +派生子智能体需要使用浏览器自动化，请在配置文件阶段添加 browser： ```json5 { @@ -89,25 +88,24 @@ Gateway 网关。 } ``` -对于单个智能体，使用 `agents.list[].tools.alsoAllow: ["browser"]`。 +对于单个智能体，请使用 `agents.list[].tools.alsoAllow: ["browser"]`。 仅设置 `tools.subagents.tools.allow: ["browser"]` 还不够，因为子智能体 -策略是在配置档案过滤之后才应用的。 +策略是在配置文件过滤之后才应用的。 -浏览器插件附带两层智能体指引： +浏览器插件内置了两个层级的智能体指引： -- `browser` 工具说明包含精简的常驻契约：选择 - 正确的配置档案、在同一标签页中保持 ref、一致使用 `tabId`/标签进行标签页 - 定位，并在进行多步骤工作时加载浏览器 Skills。 -- 内置的 `browser-automation` Skills 包含更长的操作循环： - 先检查 Status/标签页、为任务标签页加标签、操作前先做快照、 - UI 变化后重新快照、对 stale ref 进行一次恢复，并将登录/2FA/captcha 或 - 摄像头/麦克风阻塞报告为手动操作，而不是猜测。 +- `browser` 工具说明携带了精简的常驻契约：选择正确的配置文件， + 在同一标签页上保持引用，使用 `tabId`/标签 来定位标签页，并在进行多步骤工作时加载浏览器 Skills。 +- 内置的 `browser-automation` Skills 则承载了更完整的操作循环： + 先检查状态/标签页，为任务标签页加标签，在操作前创建快照， + 在 UI 变化后重新快照，遇到过期引用时恢复一次，并将登录/2FA/captcha 或 + 摄像头/麦克风阻塞报告为需要手动操作，而不是猜测处理。 -插件内置 Skills 会在插件启用时列在智能体的可用 Skills 中。完整的 Skills 指令按需加载，因此日常轮次不会承担全部 token 成本。 +当插件启用时，插件内置 Skills 会出现在智能体的可用 Skills 列表中。完整的 Skills 说明会按需加载，因此日常轮次不会承担完整的 token 成本。 -## 缺失的浏览器命令或工具 +## 缺少浏览器命令或工具 -如果升级后 `openclaw browser` 变成未知命令、缺少 `browser.request`，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中遗漏了 `browser`。把它加上： +如果升级后 `openclaw browser` 无法识别，`browser.request` 缺失，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中遗漏了 `browser`。请将其加入： ```json5 { @@ -117,22 +115,22 @@ Gateway 网关。 } ``` -`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代 allowlist 成员资格——allowlist 决定插件是否加载，而工具策略只会在加载之后运行。完全移除 `plugins.allow` 也会恢复默认行为。 +`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代允许列表成员资格——允许列表控制插件是否加载，而工具策略只有在加载之后才会运行。完全移除 `plugins.allow` 也会恢复默认行为。 -## 配置档案：`openclaw` 与 `user` +## 配置文件：`openclaw` 与 `user` -- `openclaw`：受管、隔离的浏览器（不需要扩展）。 -- `user`：内置的 Chrome MCP 连接配置档案，用于连接你**真实的已登录 Chrome** +- `openclaw`：受管理、隔离的浏览器（无需扩展）。 +- `user`：内置的 Chrome MCP 附加配置文件，用于连接你**真实的、已登录的 Chrome** 会话。 对于智能体浏览器工具调用： - 默认：使用隔离的 `openclaw` 浏览器。 -- 当现有登录会话很重要，且用户 - 在电脑前可以点击/批准任何连接提示时，优先使用 `profile="user"`。 -- 当你想要某种特定浏览器模式时，`profile` 是显式覆盖项。 +- 当现有登录会话很重要，并且用户就在电脑前可以点击/批准任何附加提示时， + 优先使用 `profile="user"`。 +- 当你希望指定某种浏览器模式时，`profile` 是显式覆盖项。 -如果你希望默认使用受管模式，请设置 `browser.defaultProfile: "openclaw"`。 +如果你希望默认使用受管理模式，请设置 `browser.defaultProfile: "openclaw"`。 ## 配置 @@ -141,23 +139,23 @@ Gateway 网关。 ```json5 { browser: { - enabled: true, // 默认值：true + enabled: true, // default: true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时选择启用 - // allowPrivateNetwork: true, // 旧版别名 + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // 旧版单配置档案覆盖项 - remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒） - remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒） - localLaunchTimeoutMs: 15000, // 本地受管 Chrome 发现超时（毫秒） - localCdpReadyTimeoutMs: 8000, // 本地受管启动后 CDP 就绪超时（毫秒） - actionTimeoutMs: 60000, // 默认浏览器 act 超时（毫秒） + // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override + remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms) + remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms) + localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms) + localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms) + actionTimeoutMs: 60000, // default browser act timeout (ms) tabCleanup: { - enabled: true, // 默认值：true - idleMinutes: 120, // 设为 0 可禁用空闲清理 - maxTabsPerSession: 8, // 设为 0 可禁用按会话限制 + enabled: true, // default: true + idleMinutes: 120, // set 0 to disable idle cleanup + maxTabsPerSession: 8, // set 0 to disable the per-session cap sweepMinutes: 5, }, defaultProfile: "openclaw", @@ -193,56 +191,47 @@ Gateway 网关。 - + -- 控制服务绑定到 loopback，端口由 `gateway.port` 派生（默认 `18791` = 网关 + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会同步移动这一组派生端口。 -- 本地 `openclaw` 配置档案会自动分配 `cdpPort`/`cdpUrl`；仅远程 CDP 需要设置这些值。未设置时，`cdpUrl` 默认指向受管本地 CDP 端口。 -- `remoteCdpTimeoutMs` 适用于远程（非 loopback）CDP HTTP 可达性检查；`remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 握手。 -- `localLaunchTimeoutMs` 是本地启动的受管 Chrome - 进程暴露其 CDP HTTP 端点的预算时间。`localCdpReadyTimeoutMs` 是 - 在发现进程后等待 CDP websocket 就绪的后续预算时间。 - 在 Raspberry Pi、低端 VPS 或较旧硬件上，如果 Chromium - 启动较慢，请提高这些值。上限为 120000 ms。 -- `actionTimeoutMs` 是浏览器 `act` 请求的默认预算时间，当调用方未传 `timeoutMs` 时使用。客户端传输层会增加一个小的宽限窗口，这样长时间等待可以完成，而不会在 HTTP 边界处超时。 -- `tabCleanup` 是对主智能体浏览器会话中打开的标签页进行尽力清理。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭它们显式跟踪的标签页；主会话会保留活动标签页以供复用，然后在后台关闭空闲或超量的已跟踪标签页。 +- 控制服务绑定到 loopback 上，其端口基于 `gateway.port` 派生而来（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会使同一组中的派生端口一起变化。 +- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；仅在远程 CDP 场景中才需要设置这些值。未设置时，`cdpUrl` 默认为受管理的本地 CDP 端口。 +- `remoteCdpTimeoutMs` 适用于远程和 `attachOnly` CDP HTTP 可达性检查 + 以及标签页打开 HTTP 请求；`remoteCdpHandshakeTimeoutMs` 适用于 + 它们的 CDP WebSocket 握手。 +- `localLaunchTimeoutMs` 是本地启动的受管理 Chrome 进程暴露其 CDP HTTP 端点的时间预算。`localCdpReadyTimeoutMs` 是在进程被发现之后，用于等待 CDP websocket 就绪的后续时间预算。 + 在 Raspberry Pi、低配 VPS 或较旧硬件上，如果 Chromium + 启动较慢，请调高这些值。这些值的上限为 120000 ms。 +- `actionTimeoutMs` 是浏览器 `act` 请求的默认时间预算，当调用方未传入 `timeoutMs` 时会使用它。客户端传输层会增加一个小的宽限窗口，以便较长的等待能够完成，而不是在 HTTP 边界超时。 +- `tabCleanup` 是针对主智能体浏览器会话中打开标签页的尽力清理机制。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭它们明确跟踪的标签页；主会话则会保留活动标签页以便复用，然后在后台关闭空闲或超出数量限制的已跟踪标签页。 -- 浏览器导航和 open-tab 在导航前会进行 SSRF 防护，并在导航完成后的最终 `http(s)` URL 上尽力再次检查。 +- 浏览器导航和打开标签页会在导航前受到 SSRF 保护，并会在最终的 `http(s)` URL 上尽力再次检查。 - 在严格 SSRF 模式下，远程 CDP 端点发现和 `/json/version` 探测（`cdpUrl`）也会被检查。 -- Gateway 网关/provider 的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动为 OpenClaw 管理的浏览器启用代理。受管 Chrome 默认直接启动，因此 provider 代理设置不会削弱浏览器 SSRF 检查。 -- 若要为受管浏览器本身设置代理，请通过 `browser.extraArgs` 传递显式的 Chrome 代理标志，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。严格 SSRF 模式会阻止显式浏览器代理路由，除非你明确启用了私有网络浏览器访问。 -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅当你有意信任私有网络浏览器访问时才启用。 -- `browser.ssrfPolicy.allowPrivateNetwork` 仍支持作为旧版别名。 +- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动为 OpenClaw 管理的浏览器启用代理。受管理的 Chrome 默认直接启动，因此提供商代理设置不会削弱浏览器的 SSRF 检查。 +- 若要为受管理的浏览器本身启用代理，请通过 `browser.extraArgs` 传入显式的 Chrome 代理标志，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。严格 SSRF 模式会阻止显式浏览器代理路由，除非你已明确启用私有网络浏览器访问。 +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅在你明确相信私有网络浏览器访问时才启用。 +- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 - + -- `attachOnly: true` 表示绝不启动本地浏览器；仅在已有浏览器运行时连接。 -- `headless` 可以全局设置，也可以按本地受管配置档案设置。按配置档案设置的值会覆盖 `browser.headless`，因此一个本地启动的配置档案可以保持无头，而另一个保持可见。 -- `POST /start?headless=true` 和 `openclaw browser start --headless` 会请求一次性的 - 无头启动，仅针对本地受管配置档案，且不会重写 - `browser.headless` 或配置档案配置。现有会话、仅连接和 - 远程 CDP 配置档案会拒绝该覆盖，因为 OpenClaw 不会启动那些 - 浏览器进程。 -- 在没有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主机上，本地受管配置档案 - 会自动默认为无头模式，前提是环境或配置档案/全局 - 配置都没有显式选择有头模式。`openclaw browser status --json` +- `attachOnly: true` 表示绝不启动本地浏览器；仅在浏览器已经运行时附加。 +- `headless` 可以在全局或每个本地受管理配置文件级别设置。每个配置文件的值会覆盖 `browser.headless`，因此一个本地启动的配置文件可以保持无头模式，而另一个则保持可见。 +- `POST /start?headless=true` 和 `openclaw browser start --headless` 会为本地受管理配置文件请求一次性无头启动，而不会改写 `browser.headless` 或配置文件配置。existing-session、attach-only 和远程 CDP 配置文件会拒绝该覆盖，因为 OpenClaw 不会启动这些浏览器进程。 +- 在没有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主机上，当环境或配置文件/全局配置都未明确选择有界面模式时，本地受管理配置文件会自动默认使用无头模式。`openclaw browser status --json` 会将 `headlessSource` 报告为 `env`、`profile`、`config`、 `request`、`linux-display-fallback` 或 `default`。 -- `OPENCLAW_BROWSER_HEADLESS=1` 会为当前进程 - 强制本地受管启动使用无头模式。`OPENCLAW_BROWSER_HEADLESS=0` 会为普通 - 启动强制有头模式，并在没有显示服务器的 Linux 主机上返回可操作错误； - 但显式的 `start --headless` 请求仍会在那一次启动中优先生效。 -- `executablePath` 可以全局设置，也可以按本地受管配置档案设置。按配置档案设置的值会覆盖 `browser.executablePath`，因此不同的受管配置档案可以启动不同的 Chromium 系浏览器。 -- `color`（顶层和按配置档案）会给浏览器 UI 着色，这样你可以看到当前活动的是哪个配置档案。 -- 默认配置档案是 `openclaw`（受管独立模式）。使用 `defaultProfile: "user"` 可选择默认接入已登录的用户浏览器。 -- 自动检测顺序：系统默认浏览器（如果是 Chromium 系）；否则依次为 Chrome → Brave → Edge → Chromium → Chrome Canary。 -- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。不要为此驱动设置 `cdpUrl`。 -- 当某个 existing-session 配置档案需要连接到非默认的 Chromium 用户配置档案（Brave、Edge 等）时，请设置 `browser.profiles..userDataDir`。 +- `OPENCLAW_BROWSER_HEADLESS=1` 会为当前进程强制本地受管理启动使用无头模式。`OPENCLAW_BROWSER_HEADLESS=0` 会为常规启动强制使用有界面模式，并在没有显示服务器的 Linux 主机上返回可操作的错误；显式的 `start --headless` 请求仍会在那一次启动中具有更高优先级。 +- `executablePath` 可以在全局或每个本地受管理配置文件级别设置。每个配置文件的值会覆盖 `browser.executablePath`，因此不同的受管理配置文件可以启动不同的基于 Chromium 的浏览器。 +- `color`（顶层和每个配置文件）会为浏览器 UI 着色，以便你看出当前活动的是哪个配置文件。 +- 默认配置文件是 `openclaw`（受管理的独立模式）。使用 `defaultProfile: "user"` 可选择加入已登录用户浏览器模式。 +- 自动检测顺序：如果系统默认浏览器是基于 Chromium 的，则优先使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。 +- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。不要为该驱动设置 `cdpUrl`。 +- 当某个 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（Brave、Edge 等）时，请设置 `browser.profiles..userDataDir`。 @@ -251,7 +240,7 @@ Gateway 网关。 ## 使用 Brave（或其他基于 Chromium 的浏览器） 如果你的**系统默认**浏览器是基于 Chromium 的（Chrome/Brave/Edge 等）， -OpenClaw 会自动使用它。设置 `browser.executablePath` 可覆盖 +OpenClaw 会自动使用它。设置 `browser.executablePath` 可以覆盖 自动检测。`~` 会展开为你的操作系统主目录： ```bash @@ -259,7 +248,7 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" ``` -或者在配置中按平台设置： +或者按平台在配置中设置： @@ -291,63 +280,62 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C -按配置档案设置的 `executablePath` 仅影响由 OpenClaw -启动的本地受管配置档案。`existing-session` 配置档案则会连接到一个已经在运行的浏览器， -而远程 CDP 配置档案使用的是 `cdpUrl` 背后的浏览器。 +按配置文件设置的 `executablePath` 仅影响 OpenClaw 启动的本地受管理配置文件。 +`existing-session` 配置文件则会附加到一个已经运行中的浏览器， +而远程 CDP 配置文件会使用 `cdpUrl` 背后的浏览器。 ## 本地控制与远程控制 -- **本地控制（默认）：** Gateway 网关会启动 loopback 控制服务，并且可以启动本地浏览器。 -- **远程控制（节点主机）：** 在有浏览器的那台机器上运行一个节点主机；Gateway 网关会将浏览器操作代理到它。 -- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）来 - 连接到远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 -- 对于运行在 loopback 上的外部受管 CDP 服务（例如在 - Docker 中运行并发布到 `127.0.0.1` 的 Browserless），还要设置 `attachOnly: true`。如果是 loopback CDP - 且未设置 `attachOnly`，会被视为一个由 OpenClaw 管理的本地浏览器配置档案。 -- `headless` 仅影响由 OpenClaw 启动的本地受管配置档案。它不会重启或更改 existing-session 或远程 CDP 浏览器。 -- `executablePath` 也遵循同样的本地受管配置档案规则。在一个 - 正在运行的本地受管配置档案上更改它，会将该配置档案标记为需要重启/协调，以便 - 下一次启动时使用新的二进制文件。 +- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并且可以启动本地浏览器。 +- **远程控制（节点主机）：** 在有浏览器的机器上运行一个节点主机；Gateway 网关会将浏览器操作代理到该节点主机。 +- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）以 + 附加到一个远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 +- 对于在 loopback 上运行的外部受管理 CDP 服务（例如发布到 `127.0.0.1` 的 Docker 中的 Browserless），还需要设置 `attachOnly: true`。如果 loopback CDP + 未设置 `attachOnly`，则会被视为一个由 OpenClaw 管理的本地浏览器配置文件。 +- `headless` 仅影响 OpenClaw 启动的本地受管理配置文件。它不会重启或更改 existing-session 或远程 CDP 浏览器。 +- `executablePath` 也遵循同样的本地受管理配置文件规则。在一个 + 正在运行的本地受管理配置文件上更改它，会将该配置文件标记为需要重启/协调， + 以便下次启动时使用新的二进制文件。 -停止行为会因配置档案模式而异： +不同配置文件模式下，停止行为也不同： -- 本地受管配置档案：`openclaw browser stop` 会停止 - 由 OpenClaw 启动的浏览器进程 -- 仅连接和远程 CDP 配置档案：`openclaw browser stop` 会关闭活动的 - 控制会话，并释放 Playwright/CDP 模拟覆盖（视口、 - 配色方案、区域设置、时区、离线模式以及类似状态），即使 - 没有任何浏览器进程是由 OpenClaw 启动的 +- 本地受管理配置文件：`openclaw browser stop` 会停止由 + OpenClaw 启动的浏览器进程 +- attach-only 和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前活动的 + 控制会话，并释放 Playwright/CDP 仿真覆盖项（视口、 + 颜色方案、区域设置、时区、离线模式及类似状态），即使 + OpenClaw 并未启动任何浏览器进程 远程 CDP URL 可以包含认证信息： -- 查询参数令牌（例如 `https://provider.example?token=`） -- HTTP Basic 认证（例如 `https://user:pass@provider.example`） +- 查询参数 token（例如 `https://provider.example?token=`） +- HTTP Basic auth（例如 `https://user:pass@provider.example`） OpenClaw 在调用 `/json/*` 端点以及连接 -到 CDP WebSocket 时都会保留这些认证信息。对于令牌，优先使用 -环境变量或密钥管理器，而不是将它们提交到配置文件中。 +CDP WebSocket 时都会保留这些认证信息。对于 token，优先使用环境变量或密钥管理器， +而不是将它们提交到配置文件中。 ## 节点浏览器代理（默认零配置） -如果你在有浏览器的那台机器上运行了一个**节点主机**，OpenClaw 可以 +如果你在有浏览器的机器上运行了一个**节点主机**，OpenClaw 可以 自动将浏览器工具调用路由到该节点，而无需任何额外的浏览器配置。 这是远程网关的默认路径。 说明： - 节点主机会通过一个**代理命令**暴露其本地浏览器控制服务器。 -- 配置档案来自节点自身的 `browser.profiles` 配置（与本地相同）。 -- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空即可保留旧版/默认行为：所有已配置的配置档案都可以通过代理访问，包括配置档案创建/删除路由。 -- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有在 allowlist 中的配置档案才能被定位，而且持久化配置档案的创建/删除路由会在代理表面被阻止。 -- 如果你不想启用它，可以禁用： +- 配置文件来自节点自身的 `browser.profiles` 配置（与本地相同）。 +- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空可保留旧版/默认行为：所有已配置的配置文件仍可通过代理访问，包括配置文件创建/删除路由。 +- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为一个最小权限边界：只有在允许列表中的配置文件才可以被作为目标，并且持久化配置文件的创建/删除路由会在代理表面被阻止。 +- 如果你不想使用它，可以禁用： - 在节点上：`nodeHost.browserProxy.enabled=false` - 在网关上：`gateway.nodes.browser.mode="off"` ## Browserless（托管远程 CDP） -[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，它通过 HTTPS 和 WebSocket 暴露 -CDP 连接 URL。OpenClaw 可以使用这两种形式，但 -对于远程浏览器配置档案，最简单的选项是直接使用 Browserless 连接文档中的 WebSocket URL。 +[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，通过 HTTPS 和 WebSocket 暴露 +CDP 连接 URL。OpenClaw 可以使用任意一种形式，但 +对于远程浏览器配置文件，最简单的选项是使用 Browserless 连接文档中提供的直接 WebSocket URL。 示例： @@ -370,16 +358,16 @@ CDP 连接 URL。OpenClaw 可以使用这两种形式，但 说明： -- 将 `` 替换为你真实的 Browserless 令牌。 +- 请将 `` 替换为你真实的 Browserless token。 - 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。 -- 如果 Browserless 提供给你的是 HTTPS 基础 URL，你可以将它转换为 - `wss://` 来进行直接 CDP 连接，或者保留该 HTTPS URL，让 OpenClaw - 发现 `/json/version`。 +- 如果 Browserless 给你的是一个 HTTPS 基础 URL，你可以将其转换为 + `wss://` 以建立直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw + 去发现 `/json/version`。 -### 同一主机上的 Browserless Docker +### 在同一主机上的 Browserless Docker -当 Browserless 在 Docker 中自托管，而 OpenClaw 运行在宿主机上时， -应将 Browserless 视为一个外部受管的 CDP 服务： +当 Browserless 以 Docker 自托管，且 OpenClaw 运行在宿主机上时， +应将 Browserless 视为一个外部受管理的 CDP 服务： ```json5 { @@ -397,47 +385,47 @@ CDP 连接 URL。OpenClaw 可以使用这两种形式，但 } ``` -`browser.profiles.browserless.cdpUrl` 中的地址必须能从 -OpenClaw 进程访问到。Browserless 还必须通告一个匹配且可达的端点； -请将 Browserless 的 `EXTERNAL` 设置为同一个对 OpenClaw 可达的公共 WebSocket 基础地址，例如 +`browser.profiles.browserless.cdpUrl` 中的地址必须能够从 +OpenClaw 进程访问到。Browserless 还必须通告一个匹配的可访问端点； +请将 Browserless `EXTERNAL` 设置为同一个面向 OpenClaw 的公共 WebSocket 基址，例如 `ws://127.0.0.1:3000`、`ws://browserless:3000` 或一个稳定的私有 Docker -网络地址。如果 `/json/version` 返回的 `webSocketDebuggerUrl` 指向 -一个 OpenClaw 无法访问的地址，CDP HTTP 看起来可能是健康的，但 WebSocket -连接仍然会失败。 +网络地址。如果 `/json/version` 返回的 `webSocketDebuggerUrl` 指向一个 +OpenClaw 无法访问的地址，那么即使 CDP HTTP 看起来健康，WebSocket +附加仍然会失败。 -对于 loopback Browserless 配置档案，不要让 `attachOnly` 保持未设置。没有 -`attachOnly` 时，OpenClaw 会将这个 loopback 端口视为本地受管浏览器 -配置档案，并可能报告该端口正在使用中，但并不归 OpenClaw 所有。 +对于 loopback Browserless 配置文件，不要让 `attachOnly` 保持未设置。若未设置 +`attachOnly`，OpenClaw 会将该 loopback 端口视为本地受管理浏览器 +配置文件，并可能报告该端口正在被使用，但并不归 OpenClaw 所有。 -## 直接 WebSocket CDP provider +## 直接 WebSocket CDP 提供商 -某些托管浏览器服务暴露的是一个**直接 WebSocket** 端点，而不是 +一些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是 标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种 CDP URL 形式，并会自动选择正确的连接策略： - **HTTP(S) 发现** — `http://host[:port]` 或 `https://host[:port]`。 OpenClaw 会调用 `/json/version` 来发现 WebSocket 调试器 URL，然后 - 建立连接。没有 WebSocket 后备。 + 进行连接。没有 WebSocket 回退。 - **直接 WebSocket 端点** — `ws://host[:port]/devtools//` 或 - `wss://...`，路径为 `/devtools/browser|page|worker|shared_worker|service_worker/` - 之一。OpenClaw 会直接通过 WebSocket 握手建立连接，并完全跳过 + `wss://...`，其路径为 `/devtools/browser|page|worker|shared_worker|service_worker/`。 + OpenClaw 会直接通过 WebSocket 握手连接，并完全跳过 `/json/version`。 -- **裸 WebSocket 根路径** — `ws://host[:port]` 或 `wss://host[:port]`，没有 +- **裸 WebSocket 根路径** — `ws://host[:port]` 或 `wss://host[:port]`，且没有 `/devtools/...` 路径（例如 [Browserless](https://browserless.io)、 - [Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP - `/json/version` 发现（将 scheme 规范化为 `http`/`https`）； - 如果发现返回了 `webSocketDebuggerUrl`，就使用它，否则 OpenClaw - 会回退到裸根路径上的直接 WebSocket 握手。如果已通告的 - WebSocket 端点拒绝 CDP 握手，但配置的裸根路径 - 接受它，OpenClaw 也会回退到该根路径。这样一来，一个指向本地 Chrome 的裸 `ws://` - 仍然可以建立连接，因为 Chrome 只接受在 `/json/version` 提供的特定按目标路径上的 WebSocket - 升级，而托管 provider 在其发现 - 端点通告了一个不适合 Playwright CDP 的短期 URL 时，仍然可以使用其根 WebSocket 端点。 + [Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试进行 HTTP + `/json/version` 发现（将协议标准化为 `http`/`https`）； + 如果发现过程返回了 `webSocketDebuggerUrl`，就使用它，否则 OpenClaw + 会回退为在裸根路径上直接进行 WebSocket 握手。如果通告的 + WebSocket 端点拒绝 CDP 握手，但已配置的裸根路径 + 可以接受，那么 OpenClaw 也会回退到该根路径。这使得一个指向本地 Chrome 的裸 `ws://` + 仍然可以连接，因为 Chrome 只接受来自 `/json/version` 中特定逐目标路径的 WebSocket + 升级；而托管提供商仍然可以在其发现 + 端点通告一个不适合 Playwright CDP 的短生命周期 URL 时，使用它们的根 WebSocket 端点。 ### Browserbase -[Browserbase](https://www.browserbase.com) 是一个用于运行 -无头浏览器的云平台，内置 CAPTCHA 求解、隐身模式和住宅代理。 +[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行 +无头浏览器，内置 CAPTCHA 解决、隐身模式和住宅代理。 ```json5 { @@ -458,79 +446,79 @@ CDP URL 形式，并会自动选择正确的连接策略： 说明： -- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview 仪表板](https://www.browserbase.com/overview) 复制你的 **API Key**。 -- 将 `` 替换为你真实的 Browserbase API key。 +- [注册](https://www.browserbase.com/sign-up)，并从 [概览仪表板](https://www.browserbase.com/overview) 复制你的 **API Key**。 +- 请将 `` 替换为你真实的 Browserbase API key。 - Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此 - 不需要手动创建会话。 + 不需要手动创建会话步骤。 - 免费套餐每月允许一个并发会话和一个浏览器小时。 - 付费套餐限制请参见 [pricing](https://www.browserbase.com/pricing)。 -- 完整 API + 付费计划限制请参见 [定价](https://www.browserbase.com/pricing)。 +- 完整的 API 参考、SDK 指南和集成示例，请参见 [Browserbase 文档](https://docs.browserbase.com)。 ## 安全性 -关键概念： +核心要点： -- 浏览器控制仅限 loopback；访问通过 Gateway 网关认证或节点配对流转。 +- 浏览器控制仅限 loopback；访问通过 Gateway 网关的认证或节点配对来进行。 - 独立的 loopback 浏览器 HTTP API **仅使用共享密钥认证**： - Gateway 网关令牌 bearer 认证、`x-openclaw-password`，或带有 - 已配置网关密码的 HTTP Basic 认证。 -- Tailscale Serve 身份头和 `gateway.auth.mode: "trusted-proxy"` **不会** - 为这个独立的 loopback 浏览器 API 提供认证。 + gateway token bearer auth、`x-openclaw-password`，或带有 + 已配置 Gateway 网关密码的 HTTP Basic auth。 +- Tailscale Serve 身份头和 `gateway.auth.mode: "trusted-proxy"` + **不能**用于认证这个独立的 loopback 浏览器 API。 - 如果启用了浏览器控制且未配置共享密钥认证，OpenClaw - 会在启动时自动生成 `gateway.auth.token`，并将其持久化到配置中。 -- 当 `gateway.auth.mode` 已经是 - `password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该令牌。 -- 请将 Gateway 网关和任何节点主机保留在私有网络（Tailscale）中；避免公开暴露。 -- 将远程 CDP URL/令牌视为密钥；优先使用环境变量或密钥管理器。 + 会在启动时自动生成 `gateway.auth.token` 并将其持久化到配置中。 +- 如果 `gateway.auth.mode` 已经是 + `password`、`none` 或 `trusted-proxy`，OpenClaw **不会**自动生成该 token。 +- 请将 Gateway 网关和任何节点主机保留在私有网络中（Tailscale）；避免对公网暴露。 +- 请将远程 CDP URL/token 视为密钥；优先使用环境变量或密钥管理器。 远程 CDP 提示： -- 在可能的情况下，优先使用加密端点（HTTPS 或 WSS）以及短期令牌。 -- 避免将长期令牌直接嵌入配置文件中。 +- 尽可能优先使用加密端点（HTTPS 或 WSS）和短生命周期 token。 +- 避免将长生命周期 token 直接嵌入配置文件。 -## 配置档案（多浏览器） +## 配置文件（多浏览器） -OpenClaw 支持多个具名配置档案（路由配置）。配置档案可以是： +OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是： -- **openclaw 受管**：一个专用的基于 Chromium 的浏览器实例，拥有自己的用户数据目录 + CDP 端口 -- **remote**：一个显式的 CDP URL（运行在别处的基于 Chromium 的浏览器） -- **existing session**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome 配置档案 +- **由 OpenClaw 管理**：一个专用的基于 Chromium 的浏览器实例，拥有自己的用户数据目录 + CDP 端口 +- **远程**：显式的 CDP URL（运行在其他位置的基于 Chromium 的浏览器） +- **现有会话**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome 配置文件 默认值： -- 如果缺失，会自动创建 `openclaw` 配置档案。 -- 内置 `user` 配置档案用于 Chrome MCP existing-session 连接。 -- 除 `user` 之外，existing-session 配置档案需要显式启用；请使用 `--driver existing-session` 创建它们。 -- 本地 CDP 端口默认从 **18800–18899** 范围分配。 -- 删除配置档案会将其本地数据目录移到废纸篓。 +- 如果缺失，会自动创建 `openclaw` 配置文件。 +- `user` 配置文件内置用于 Chrome MCP existing-session 附加。 +- 除了 `user` 之外，existing-session 配置文件都需要显式启用；请使用 `--driver existing-session` 创建它们。 +- 本地 CDP 端口默认从 **18800–18899** 范围中分配。 +- 删除配置文件会将其本地数据目录移到废纸篓。 所有控制端点都接受 `?profile=`；CLI 使用 `--browser-profile`。 ## 通过 Chrome DevTools MCP 使用现有会话 OpenClaw 还可以通过官方的 -Chrome DevTools MCP 服务器连接到一个正在运行的基于 Chromium 的浏览器配置档案。这样会复用该浏览器配置档案中 +Chrome DevTools MCP 服务器附加到一个正在运行的基于 Chromium 的浏览器配置文件。这样可以复用该浏览器配置文件中 已经打开的标签页和登录状态。 官方背景和设置参考： -- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) +- [Chrome for Developers：在你的浏览器会话中使用 Chrome DevTools MCP](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) -内置配置档案： +内置配置文件： - `user` -可选：如果你想要一个不同的 -名称、颜色或浏览器数据目录，也可以创建自己的自定义 existing-session 配置档案。 +可选：如果你想使用 +不同的名称、颜色或浏览器数据目录，也可以创建你自己的自定义 existing-session 配置文件。 默认行为： -- 内置的 `user` 配置档案使用 Chrome MCP 自动连接，它会定位到 - 默认的本地 Google Chrome 配置档案。 +- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，它会连接到 + 默认的本地 Google Chrome 配置文件。 -对于 Brave、Edge、Chromium 或非默认 Chrome 配置档案，请使用 `userDataDir`： +对于 Brave、Edge、Chromium 或非默认的 Chrome 配置文件，请使用 `userDataDir`： ```json5 { @@ -549,17 +537,17 @@ Chrome DevTools MCP 服务器连接到一个正在运行的基于 Chromium 的 然后在对应的浏览器中： -1. 打开该浏览器的远程调试检查页面。 +1. 打开该浏览器用于远程调试的 inspect 页面。 2. 启用远程调试。 -3. 保持浏览器运行，并在 OpenClaw 连接时批准连接提示。 +3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。 -常见检查页面： +常见的 inspect 页面： - Chrome：`chrome://inspect/#remote-debugging` - Brave：`brave://inspect/#remote-debugging` - Edge：`edge://inspect/#remote-debugging` -实时连接冒烟测试： +实时附加冒烟测试： ```bash openclaw browser --browser-profile user start @@ -568,82 +556,82 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -成功时的表现： +成功时应看到的结果： - `status` 显示 `driver: existing-session` - `status` 显示 `transport: chrome-mcp` - `status` 显示 `running: true` - `tabs` 列出你已经打开的浏览器标签页 -- `snapshot` 返回所选活动标签页中的 ref +- `snapshot` 返回所选实时标签页中的 refs -如果连接不起作用，请检查： +如果附加不起作用，请检查： - 目标的基于 Chromium 的浏览器版本为 `144+` - 该浏览器的 inspect 页面中已启用远程调试 -- 浏览器已显示连接授权提示，并且你已接受 +- 浏览器已显示附加同意提示，且你已接受 - `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查 - 对于默认自动连接配置档案，Chrome 是否已在本地安装，但它无法 - 替你启用浏览器侧的远程调试 + 默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法 + 替你启用浏览器端的远程调试 -智能体使用： +智能体使用方式： -- 当你需要用户的已登录浏览器状态时，使用 `profile="user"`。 -- 如果你使用自定义 existing-session 配置档案，请传入那个显式配置档案名称。 -- 仅当用户在电脑前能够批准连接 +- 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。 +- 如果你使用的是自定义 existing-session 配置文件，请传入该明确的配置文件名称。 +- 只有当用户就在电脑前、可以批准附加 提示时，才选择此模式。 -- Gateway 网关或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect` +- Gateway 网关或节点主机可以生成 `npx chrome-devtools-mcp@latest --autoConnect` 说明： -- 与隔离的 `openclaw` 配置档案相比，这条路径风险更高，因为它可以 - 在你的已登录浏览器会话中执行操作。 -- 对于这个驱动，OpenClaw 不会启动浏览器；它只会连接。 +- 这条路径比隔离的 `openclaw` 配置文件风险更高，因为它可以 + 在你已登录的浏览器会话中执行操作。 +- 对于这个驱动，OpenClaw 不会启动浏览器；它只会进行附加。 - OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果 - 设置了 `userDataDir`，它会被传递进去以定位该用户数据目录。 -- existing-session 可以连接到所选主机上的浏览器，或通过已连接的 - 浏览器节点进行连接。如果 Chrome 位于别处且没有已连接的浏览器节点，请改用 + 设置了 `userDataDir`，它会被一并传递，以定位到该用户数据目录。 +- Existing-session 可以在所选主机上附加，也可以通过已连接的 + 浏览器节点附加。如果 Chrome 位于其他地方，且没有浏览器节点已连接，请改用 远程 CDP 或节点主机。 ### 自定义 Chrome MCP 启动 当默认的 -`npx chrome-devtools-mcp@latest` 流程不符合你的需要时（离线主机、 -固定版本、内置二进制文件），你可以按配置档案覆盖启动的 Chrome DevTools MCP 服务器： +`npx chrome-devtools-mcp@latest` 流程不符合你的需求时（离线主机、 +固定版本、供应商内置二进制），可按配置文件覆盖所生成的 Chrome DevTools MCP 服务器： -| 字段 | 作用 | -| ------------ | -------------------------------------------------------------------------------------------------------------------------- | -| `mcpCommand` | 要启动的可执行文件，用来替代 `npx`。按原样解析；绝对路径会被直接采用。 | -| `mcpArgs` | 原样传递给 `mcpCommand` 的参数数组。会替换默认的 `chrome-devtools-mcp@latest --autoConnect` 参数。 | +| 字段 | 作用 | +| ------------ | ---- | +| `mcpCommand` | 要生成的可执行文件，用于替代 `npx`。按原样解析；支持绝对路径。 | +| `mcpArgs` | 原样传递给 `mcpCommand` 的参数数组。会替换默认的 `chrome-devtools-mcp@latest --autoConnect` 参数。 | -当在 existing-session 配置档案上设置了 `cdpUrl` 时，OpenClaw 会跳过 -`--autoConnect`，并自动将该端点转发给 Chrome MCP： +当在 existing-session 配置文件上设置了 `cdpUrl` 时，OpenClaw 会跳过 +`--autoConnect`，并自动将端点转发给 Chrome MCP： - `http(s)://...` → `--browserUrl `（DevTools HTTP 发现端点）。 - `ws(s)://...` → `--wsEndpoint `（直接 CDP WebSocket）。 -端点标志与 `userDataDir` 不能组合使用：当设置了 `cdpUrl` 时， -Chrome MCP 启动会忽略 `userDataDir`，因为 Chrome MCP 会连接到 -该端点背后的正在运行的浏览器，而不是打开某个配置档案 +端点标志与 `userDataDir` 不能同时使用：当设置了 `cdpUrl` 时， +在 Chrome MCP 启动中会忽略 `userDataDir`，因为 Chrome MCP 会附加到 +端点背后的正在运行中的浏览器，而不是打开某个配置文件 目录。 - + -与受管的 `openclaw` 配置档案相比，existing-session 驱动的限制更多： +与受管理的 `openclaw` 配置文件相比，existing-session 驱动受到的限制更多： -- **截图** — 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面截图或基于 ref 的元素截图不需要 Playwright。 -- **操作** — `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 snapshot ref（不支持 CSS 选择器）。`click-coords` 点击可见视口坐标，不需要 snapshot ref。`click` 仅支持左键。`type` 不支持 `slowly=true`；请改用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用设置超时。`select` 接受单个值。 +- **截图** — 支持页面捕获和 `--ref` 元素捕获；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面截图或基于 ref 的元素截图不需要 Playwright。 +- **操作** — `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要使用快照 refs（不支持 CSS 选择器）。`click-coords` 点击可见视口坐标，不需要快照 ref。`click` 仅支持左键。`type` 不支持 `slowly=true`；请使用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用单独设置超时。`select` 仅接受单个值。 - **等待 / 上传 / 对话框** — `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传钩子需要 `ref` 或 `inputRef`，一次只能上传一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。 -- **仅受管功能** — 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要受管浏览器路径。 +- **仅受管理模式功能** — 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要受管理浏览器路径。 ## 隔离保证 -- **专用用户数据目录**：绝不会触碰你的个人浏览器配置档案。 -- **专用端口**：避免使用 `9222`，以防与你的开发工作流发生冲突。 -- **可预测的标签页控制**：`tabs` 会优先返回 `suggestedTargetId`，然后是 - 稳定的 `tabId` 句柄（如 `t1`）、可选标签以及原始 `targetId`。 - 智能体应复用 `suggestedTargetId`；原始 id 则保留用于 +- **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。 +- **专用端口**：避免使用 `9222`，以防与开发工作流发生冲突。 +- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后返回 + 稳定的 `tabId` 句柄，例如 `t1`、可选标签，以及原始 `targetId`。 + 智能体应复用 `suggestedTargetId`；原始 id 仍然保留，用于 调试和兼容性。 ## 浏览器选择 @@ -656,9 +644,9 @@ Chrome MCP 启动会忽略 `userDataDir`，因为 Chrome MCP 会连接到 4. Chromium 5. Chrome Canary -你可以使用 `browser.executablePath` 进行覆盖。 +你可以通过 `browser.executablePath` 进行覆盖。 -平台： +平台说明： - macOS：检查 `/Applications` 和 `~/Applications`。 - Linux：检查 `/usr/bin`、 @@ -668,25 +656,25 @@ Chrome MCP 启动会忽略 `userDataDir`，因为 Chrome MCP 会连接到 ## 控制 API（可选） -对于脚本和调试，Gateway 网关暴露了一个小型的**仅 loopback HTTP -控制 API**，以及一个匹配的 `openclaw browser` CLI（快照、ref、等待 -增强、JSON 输出、调试工作流）。完整参考见 +为了便于脚本编写和调试，Gateway 网关暴露了一个小型的**仅限 loopback 的 HTTP +控制 API**，以及一个对应的 `openclaw browser` CLI（快照、refs、等待 +增强能力、JSON 输出、调试工作流）。完整参考请参阅 [浏览器控制 API](/zh-CN/tools/browser-control)。 ## 故障排除 -对于 Linux 特定问题（尤其是 snap Chromium），请参见 +关于 Linux 特有的问题（尤其是 snap Chromium），请参阅 [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。 -对于 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参见 +关于 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参阅 [WSL2 + Windows + 远程 Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。 ### CDP 启动失败与导航 SSRF 阻止 -这是两类不同的失败，它们指向不同的代码路径。 +这是两类不同的失败，它们分别指向不同的代码路径。 -- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面是健康的。 -- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但某个页面导航目标被策略拒绝了。 +- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。 +- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但页面导航目标被策略拒绝。 常见示例： @@ -694,11 +682,11 @@ Chrome MCP 启动会忽略 `userDataDir`，因为 Chrome MCP 会连接到 - `Chrome CDP websocket for profile "openclaw" is not reachable after start` - `Remote CDP for profile "" is not reachable at ` - `Port is in use for profile "" but not by openclaw`，当一个 - loopback 外部 CDP 服务在未设置 `attachOnly: true` 的情况下被配置时 + loopback 外部 CDP 服务在未配置 `attachOnly: true` 的情况下被设置时 - 导航 SSRF 阻止： - - `open`、`navigate`、snapshot 或标签页打开流程因浏览器/网络策略错误而失败，而 `start` 和 `tabs` 仍然工作 + - `open`、`navigate`、snapshot 或标签页打开流程因浏览器/网络策略错误而失败，但 `start` 和 `tabs` 仍然可用 -使用这个最小序列来区分两者： +使用以下最小序列来区分这两者： ```bash openclaw browser --browser-profile openclaw start @@ -708,46 +696,46 @@ openclaw browser --browser-profile openclaw open https://example.com 结果解读方式： -- 如果 `start` 因 `not reachable after start` 失败，先排查 CDP 就绪性。 -- 如果 `start` 成功但 `tabs` 失败，控制平面仍然不健康。应将其视为 CDP 可达性问题，而不是页面导航问题。 -- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面已正常启动，失败发生在导航策略或目标页面上。 -- 如果 `start`、`tabs` 和 `open` 都成功，则说明基础的受管浏览器控制路径是健康的。 +- 如果 `start` 以 `not reachable after start` 失败，先排查 CDP 就绪问题。 +- 如果 `start` 成功但 `tabs` 失败，则控制平面仍不健康。应将其视为 CDP 可达性问题，而不是页面导航问题。 +- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面已启动，失败出在导航策略或目标页面上。 +- 如果 `start`、`tabs` 和 `open` 全部成功，则基本的受管理浏览器控制路径是健康的。 重要行为细节： -- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用一个默认拒绝的 SSRF 策略对象。 -- 对于本地 loopback 的 `openclaw` 受管配置档案，CDP 健康检查会有意跳过针对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制检查。 -- 导航保护是独立的。`start` 或 `tabs` 成功，并不意味着后续的 `open` 或 `navigate` 目标一定被允许。 +- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用一个失败即关闭的 SSRF 策略对象。 +- 对于本地 loopback 的 `openclaw` 受管理配置文件，CDP 健康检查会有意跳过针对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制执行。 +- 导航保护是独立的。`start` 或 `tabs` 成功，并不意味着之后的 `open` 或 `navigate` 目标一定被允许。 -安全指引： +安全建议： - **不要**默认放宽浏览器 SSRF 策略。 -- 优先使用精确的主机例外，如 `hostnameAllowlist` 或 `allowedHostnames`，而不是宽泛的私有网络访问。 -- 仅在有意信任且经过审查、并且确实需要私有网络浏览器访问的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。 +- 优先使用窄范围的主机例外，如 `hostnameAllowlist` 或 `allowedHostnames`，而不是广泛开放私有网络访问。 +- 仅在私有网络浏览器访问是明确需要且经过审查的受信环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。 -## 智能体工具 + 控制如何工作 +## 智能体工具 + 控制工作方式 -智能体获得**一个工具**来进行浏览器自动化： +智能体会获得**一个工具**用于浏览器自动化： - `browser` — doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act -它的映射方式： +映射方式如下： - `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。 -- `browser act` 使用 snapshot `ref` ID 来执行 click/type/drag/select。 -- `browser screenshot` 捕获像素（整页、元素或带标签的 ref）。 -- `browser doctor` 检查 Gateway 网关、插件、配置档案、浏览器和标签页就绪状态。 +- `browser act` 使用快照 `ref` ID 来执行点击/输入/拖拽/选择。 +- `browser screenshot` 捕获像素内容（整页、元素或带标签的 refs）。 +- `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页就绪状态。 - `browser` 接受： - - `profile` 用于选择具名浏览器配置档案（openclaw、chrome 或远程 CDP）。 - - `target`（`sandbox` | `host` | `node`）用于选择浏览器所在位置。 + - `profile`，用于选择命名浏览器配置文件（openclaw、chrome 或远程 CDP）。 + - `target`（`sandbox` | `host` | `node`），用于选择浏览器所在位置。 - 在沙箱隔离会话中，`target: "host"` 需要 `agents.defaults.sandbox.browser.allowHostControl=true`。 - 如果省略 `target`：沙箱隔离会话默认使用 `sandbox`，非沙箱隔离会话默认使用 `host`。 - - 如果已连接一个支持浏览器的节点，工具可能会自动路由到它，除非你固定指定 `target="host"` 或 `target="node"`。 + - 如果连接了具备浏览器能力的节点，工具可能会自动路由到该节点，除非你固定指定 `target="host"` 或 `target="node"`。 -这样可以让智能体保持可预测，并避免脆弱的选择器。 +这样可以让智能体保持可预测性，并避免脆弱的选择器。 ## 相关内容 -- [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具 +- [工具概览](/zh-CN/tools) — 所有可用的智能体工具 - [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的浏览器控制 -- [Security](/zh-CN/gateway/security) — 浏览器控制的风险与加固 +- [安全性](/zh-CN/gateway/security) — 浏览器控制风险与加固 diff --git a/docs/zh-CN/tools/image-generation.md b/docs/zh-CN/tools/image-generation.md index 8a6246447..742444ce6 100644 --- a/docs/zh-CN/tools/image-generation.md +++ b/docs/zh-CN/tools/image-generation.md @@ -3,27 +3,27 @@ read_when: - 通过智能体生成图像 - 配置图像生成提供商和模型 - 了解 `image_generate` 工具参数 -summary: 使用已配置的提供商生成和编辑图像（OpenAI、OpenAI Codex OAuth、Google Gemini、OpenRouter、fal、MiniMax、ComfyUI、Vydra、xAI） +summary: 使用已配置的提供商生成和编辑图像（OpenAI、OpenAI Codex OAuth、Google Gemini、OpenRouter、LiteLLM、fal、MiniMax、ComfyUI、Vydra、xAI） title: 图像生成 x-i18n: - generated_at: "2026-04-25T17:32:15Z" + generated_at: "2026-04-25T18:12:49Z" model: gpt-5.4 provider: openai - source_hash: 0eadcc8d600530d577977c4d8c8d5a08a8b1ede0ca55e37f232c823d26abb69b + source_hash: 40ec0e9a004e769b3db8b98b1a687097cb4bc6aa78dc903e4f6a17c3731156c0 source_path: tools/image-generation.md workflow: 15 --- -`image_generate` 工具让智能体使用你已配置的提供商来创建和编辑图像。生成的图像会自动作为媒体附件随智能体的回复一起发送。 +`image_generate` 工具允许智能体使用你已配置的提供商创建和编辑图像。生成的图像会作为媒体附件自动包含在智能体的回复中。 -只有在至少有一个图像生成提供商可用时，该工具才会出现。如果你在智能体工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API 密钥，或使用 OpenAI Codex OAuth 登录。 +只有在至少有一个图像生成提供商可用时，此工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API 密钥，或使用 OpenAI Codex OAuth 登录。 ## 快速开始 1. 为至少一个提供商设置 API 密钥（例如 `OPENAI_API_KEY`、`GEMINI_API_KEY` 或 `OPENROUTER_API_KEY`），或使用 OpenAI Codex OAuth 登录。 -2. 可选地设置你偏好的模型： +2. 可选：设置你偏好的模型： ```json5 { @@ -40,47 +40,48 @@ x-i18n: ``` Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 -`openai-codex` OAuth 配置文件时，OpenClaw 会通过该 OAuth 配置文件路由图像请求，而不是先尝试 `OPENAI_API_KEY`。 -显式的自定义 `models.providers.openai` 图像配置，例如 API 密钥或 -自定义/Azure base URL，会重新切回直接使用 OpenAI Images API 的路径。 -对于 LocalAI 之类兼容 OpenAI 的 LAN 端点，请保留自定义 +`openai-codex` OAuth 配置文件时，OpenClaw 会通过该 OAuth 配置文件路由图像请求， +而不是先尝试 `OPENAI_API_KEY`。显式自定义 `models.providers.openai` 图像配置， +例如 API 密钥或自定义 / Azure base URL，会重新切换回直接的 OpenAI Images API 路由。 +对于 LocalAI 这类兼容 OpenAI 的 LAN 端点，请保留自定义的 `models.providers.openai.baseUrl`，并显式启用 -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；私有/内部 +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；私有 / 内部 图像端点默认仍会被阻止。 -3. 向智能体提出请求：_“生成一张友好的机器人吉祥物图像。”_ +3. 向智能体发出请求：_“生成一张友好机器人吉祥物的图片。”_ -智能体会自动调用 `image_generate`。无需设置工具 allow-list —— 只要有可用提供商，它默认就会启用。 +智能体会自动调用 `image_generate`。不需要工具允许列表——只要有可用提供商，它默认启用。 -## 常见路径 +## 常见路由 -| Goal | Model ref | Auth | +| 目标 | 模型引用 | 认证 | | ---------------------------------------------------- | -------------------------------------------------- | ------------------------------------ | -| 使用 API 计费的 OpenAI 图像生成 | `openai/gpt-image-2` | `OPENAI_API_KEY` | -| 使用 Codex 订阅认证的 OpenAI 图像生成 | `openai/gpt-image-2` | OpenAI Codex OAuth | -| OpenRouter 图像生成 | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY` | -| Google Gemini 图像生成 | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | +| 使用 API 计费的 OpenAI 图像生成 | `openai/gpt-image-2` | `OPENAI_API_KEY` | +| 使用 Codex 订阅认证的 OpenAI 图像生成 | `openai/gpt-image-2` | OpenAI Codex OAuth | +| OpenRouter 图像生成 | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY` | +| LiteLLM 图像生成 | `litellm/gpt-image-2` | `LITELLM_API_KEY` | +| Google Gemini 图像生成 | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | -同一个 `image_generate` 工具同时处理 text-to-image 和 reference-image -编辑。单个参考图像使用 `image`，多个参考图像使用 `images`。 -当提供商支持时，`quality`、`outputFormat` 和 -OpenAI 专用的 `background` 等输出提示会被转发；当提供商不支持时， -这些提示会在结果中报告为已忽略。 +同一个 `image_generate` 工具同时处理文生图和参考图编辑。 +对单张参考图使用 `image`，对多张参考图使用 `images`。 +当提供商支持时，诸如 `quality`、`outputFormat` 以及 OpenAI 专有的 `background` +等输出提示会被转发；当提供商不支持时，工具结果中会报告这些参数被忽略。 ## 支持的提供商 -| Provider | Default model | Edit support | Auth | +| 提供商 | 默认模型 | 编辑支持 | 认证 | | ---------- | --------------------------------------- | ---------------------------------- | ----------------------------------------------------- | -| OpenAI | `gpt-image-2` | 是（最多 4 张图像） | `OPENAI_API_KEY` 或 OpenAI Codex OAuth | -| OpenRouter | `google/gemini-3.1-flash-image-preview` | 是（最多 5 张输入图像） | `OPENROUTER_API_KEY` | -| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | -| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` | -| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） | -| ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | -| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` | -| xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` | +| OpenAI | `gpt-image-2` | 是（最多 4 张图像） | `OPENAI_API_KEY` 或 OpenAI Codex OAuth | +| OpenRouter | `google/gemini-3.1-flash-image-preview` | 是（最多 5 张输入图像） | `OPENROUTER_API_KEY` | +| LiteLLM | `gpt-image-2` | 是（最多 5 张输入图像） | `LITELLM_API_KEY` | +| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | +| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` | +| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） | +| ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | +| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` | +| xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` | -使用 `action: "list"` 可以在运行时查看可用的提供商和模型： +使用 `action: "list"` 可在运行时检查可用的提供商和模型： ``` /tool image_generate action=list @@ -89,23 +90,23 @@ OpenAI 专用的 `background` 等输出提示会被转发；当提供商不支 ## 工具参数 -图像生成提示词。对 `action: "generate"` 是必填项。 +图像生成提示。对于 `action: "generate"` 为必填。 -使用 `"list"` 在运行时查看可用的提供商和模型。 +使用 `"list"` 在运行时检查可用的提供商和模型。 -提供商/模型覆盖，例如 `openai/gpt-image-2`。 +提供商 / 模型覆盖，例如 `openai/gpt-image-2`。 -用于编辑模式的单个参考图像路径或 URL。 +编辑模式下的单张参考图路径或 URL。 -用于编辑模式的多个参考图像（最多 5 张）。 +编辑模式下的多张参考图（最多 5 张）。 @@ -121,11 +122,11 @@ OpenAI 专用的 `background` 等输出提示会被转发；当提供商不支 -当提供商支持时的质量提示。 +提供商支持时使用的质量提示。 -当提供商支持时的输出格式提示。 +提供商支持时使用的输出格式提示。 @@ -133,7 +134,7 @@ OpenAI 专用的 `background` 等输出提示会被转发；当提供商不支 -可选的提供商请求超时时间，单位为毫秒。 +可选的提供商请求超时（毫秒）。 @@ -141,12 +142,12 @@ OpenAI 专用的 `background` 等输出提示会被转发；当提供商不支 -仅限 OpenAI 的提示：`background`、`moderation`、`outputCompression` 和 `user`。 +仅 OpenAI 提示：`background`、`moderation`、`outputCompression` 和 `user`。 -并非所有提供商都支持所有参数。当回退提供商支持的是相近的几何选项而不是精确请求值时，OpenClaw 会在提交前重新映射到最接近的受支持尺寸、宽高比或分辨率。对于未声明支持的提供商，不受支持的输出提示（如 `quality` 或 `outputFormat`）会被丢弃，并在工具结果中报告。 +并非所有提供商都支持所有参数。当某个后备提供商支持的是接近的几何选项而非精确请求值时，OpenClaw 会在提交前重映射到最接近的受支持尺寸、宽高比或分辨率。诸如 `quality` 或 `outputFormat` 之类不受支持的输出提示，会在未声明支持这些功能的提供商上被丢弃，并在工具结果中报告。 -工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。 +工具结果会报告实际应用的设置。当 OpenClaw 在提供商后备期间重映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值反映的是实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。 ## 配置 @@ -176,40 +177,41 @@ OpenAI 专用的 `background` 等输出提示会被转发；当提供商不支 1. 工具调用中的 **`model` 参数**（如果智能体指定了） 2. 配置中的 **`imageGenerationModel.primary`** -3. 按顺序的 **`imageGenerationModel.fallbacks`** -4. **自动检测** —— 仅使用有认证支持的提供商默认值： - - 先尝试当前默认提供商 - - 再按 provider-id 顺序尝试其余已注册的图像生成提供商 +3. 按顺序使用 **`imageGenerationModel.fallbacks`** +4. **自动检测**——仅使用有认证支持的提供商默认值： + - 当前默认提供商优先 + - 其余已注册图像生成提供商按 provider-id 顺序 -如果某个提供商失败（认证错误、速率限制等），系统会自动尝试下一个已配置候选项。如果全部失败，错误中会包含每次尝试的详细信息。 +如果某个提供商失败（认证错误、速率限制等），会自动尝试下一个已配置候选项。如果全部失败，错误中会包含每次尝试的详细信息。 说明： -- 每次调用的 `model` 覆盖是精确的：OpenClaw 只会尝试该提供商/模型， - 不会继续尝试已配置的 primary/fallback 或自动检测到的提供商。 -- 自动检测具备认证感知能力。只有当 OpenClaw 实际能对某个提供商完成认证时， - 该提供商默认值才会进入候选列表。 -- 自动检测默认启用。如需让图像生成仅使用显式的 `model`、`primary` 和 `fallbacks` - 条目，请设置 - `agents.defaults.mediaGenerationAutoProviderFallback: false`。 -- 对于较慢的图像后端，请设置 - `agents.defaults.imageGenerationModel.timeoutMs`。 +- 每次调用的 `model` 覆盖是精确匹配：OpenClaw 只尝试该提供商 / 模型， + 不会继续尝试已配置的 primary / fallback 或自动检测到的 + 提供商。 +- 自动检测具备认证感知。只有当 OpenClaw 实际能够对该提供商进行认证时， + 提供商默认值才会进入候选列表。 +- 自动检测默认启用。若你希望图像 + 生成仅使用显式的 `model`、`primary` 和 `fallbacks` + 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。 +- 对于较慢的图像后端，请设置 `agents.defaults.imageGenerationModel.timeoutMs`。 每次调用的 `timeoutMs` 工具参数会覆盖已配置的默认值。 -- 使用 `action: "list"` 可以查看当前已注册的提供商、它们的默认模型以及认证环境变量提示。 +- 使用 `action: "list"` 可检查当前已注册的提供商、 + 其默认模型以及认证环境变量提示。 ### 图像编辑 OpenAI、OpenRouter、Google、fal、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。传入参考图像路径或 URL： ``` -"把这张照片生成水彩画风格" + image: "/path/to/photo.jpg" +"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg" ``` OpenAI、OpenRouter、Google 和 xAI 通过 `images` 参数最多支持 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。 ### OpenRouter 图像模型 -OpenRouter 图像生成使用相同的 `OPENROUTER_API_KEY`，并通过 OpenRouter 的 chat completions 图像 API 路由。使用 `openrouter/` 前缀选择 OpenRouter 图像模型： +OpenRouter 图像生成使用同一个 `OPENROUTER_API_KEY`，并通过 OpenRouter 的 chat completions 图像 API 进行路由。使用带 `openrouter/` 前缀的模型来选择 OpenRouter 图像模型： ```json5 { @@ -223,28 +225,30 @@ OpenRouter 图像生成使用相同的 `OPENROUTER_API_KEY`，并通过 OpenRout } ``` -OpenClaw 会将 `prompt`、`count`、参考图像，以及兼容 Gemini 的 `aspectRatio` / `resolution` 提示转发给 OpenRouter。当前内置的 OpenRouter 图像模型快捷方式包括 `google/gemini-3.1-flash-image-preview`、`google/gemini-3-pro-image-preview` 和 `openai/gpt-5.4-image-2`；使用 `action: "list"` 可查看你已配置的插件实际公开了哪些模型。 +OpenClaw 会将 `prompt`、`count`、参考图像以及兼容 Gemini 的 `aspectRatio` / `resolution` 提示转发给 OpenRouter。当前内置的 OpenRouter 图像模型快捷项包括 `google/gemini-3.1-flash-image-preview`、`google/gemini-3-pro-image-preview` 和 `openai/gpt-5.4-image-2`；使用 `action: "list"` 可查看你当前配置的插件暴露了哪些模型。 ### OpenAI `gpt-image-2` OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果配置了 -`openai-codex` OAuth 配置文件，OpenClaw 会复用与 Codex 订阅聊天模型相同的 OAuth -配置文件，并通过 Codex Responses 后端发送图像请求。旧版 Codex base URL，例如 -`https://chatgpt.com/backend-api`，会在图像请求中规范化为 -`https://chatgpt.com/backend-api/codex`。它不会为该请求静默回退到 -`OPENAI_API_KEY`。若要强制走直接 OpenAI Images API 路由，请显式配置 -`models.providers.openai`，并提供 API 密钥、自定义 base URL 或 Azure 端点。较旧的 -`openai/gpt-image-1` 模型仍然可以显式选择，但新的 OpenAI +`openai-codex` OAuth 配置文件，OpenClaw 会复用 Codex 订阅聊天模型所使用的同一个 OAuth +配置文件，并通过 Codex Responses 后端发送图像请求。 +旧版 Codex base URL，例如 +`https://chatgpt.com/backend-api`，会被规范化为 +`https://chatgpt.com/backend-api/codex` 以用于图像请求。它不会 +在该请求中静默回退到 `OPENAI_API_KEY`。如需强制直接路由到 OpenAI +Images API，请显式配置 `models.providers.openai`，提供 API +密钥、自定义 base URL 或 Azure 端点。较旧的 +`openai/gpt-image-1` 模型仍可显式选择，但新的 OpenAI 图像生成和图像编辑请求应使用 `gpt-image-2`。 -`gpt-image-2` 同时支持 text-to-image 生成和 reference-image -编辑，且都通过同一个 `image_generate` 工具完成。OpenClaw 会将 `prompt`、 +`gpt-image-2` 同时支持文生图和参考图编辑， +并通过同一个 `image_generate` 工具实现。OpenClaw 会将 `prompt`、 `count`、`size`、`quality`、`outputFormat` 和参考图像转发给 OpenAI。 -OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；如果可能， -OpenClaw 会将它们映射为受支持的 `size`，否则工具会将它们报告为 -已忽略的覆盖项。 +OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下 +OpenClaw 会将它们映射为受支持的 `size`，否则工具会报告这些参数为 +被忽略的覆盖项。 -OpenAI 专用选项位于 `openai` 对象下： +OpenAI 专有选项位于 `openai` 对象下： ```json { @@ -259,9 +263,9 @@ OpenAI 专用选项位于 `openai` 对象下： } ``` -`openai.background` 接受 `transparent`、`opaque` 或 `auto`；透明输出要求 -`outputFormat` 为 `png` 或 `webp`。`openai.outputCompression` -适用于 JPEG/WebP 输出。 +`openai.background` 接受 `transparent`、`opaque` 或 `auto`；透明 +输出要求 `outputFormat` 为 `png` 或 `webp`。`openai.outputCompression` +适用于 JPEG / WebP 输出。 生成一张 4K 横向图像： @@ -278,57 +282,58 @@ OpenAI 专用选项位于 `openai` 对象下： 编辑一张本地参考图像： ``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="保留主体，将背景替换为明亮的摄影棚布景" image=/path/to/reference.png size=1024x1536 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536 ``` -使用多个参考图像进行编辑： +使用多张参考图进行编辑： ``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="将第一张图像中的角色身份与第二张图像中的配色方案结合起来" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 ``` -如果要通过 Azure OpenAI 部署而不是 `api.openai.com` 来路由 OpenAI 图像生成， -请参阅 OpenAI provider 文档中的 [Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。 +如需通过 Azure OpenAI 部署而不是 +`api.openai.com` 来路由 OpenAI 图像生成，请参见 OpenAI provider 文档中的 [Azure OpenAI 端点](/zh-CN/providers/openai#azure-openai-endpoints)。 -MiniMax 图像生成可通过两种内置 MiniMax 认证路径使用： +MiniMax 图像生成功能可通过两种内置的 MiniMax 认证路径使用： - `minimax/image-01`，用于 API 密钥配置 - `minimax-portal/image-01`，用于 OAuth 配置 ## 提供商能力 -| Capability | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI | +| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI | | --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- | -| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（输出由工作流定义） | 是（1 张） | 是（最多 4 张） | -| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） | -| 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 | -| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 | -| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 | 是（1K/2K） | +| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（工作流定义的输出） | 是（1 张） | 是（最多 4 张） | +| 编辑 / 参考图 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） | +| 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 | +| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 | +| 分辨率（1K / 2K / 4K） | 否 | 是 | 是 | 否 | 否 | 否 | 是（1K / 2K） | ### xAI `grok-imagine-image` -内置的 xAI 提供商在仅提示词请求时使用 `/v1/images/generations`， -而在存在 `image` 或 `images` 时使用 `/v1/images/edits`。 +内置 xAI 提供商对纯提示请求使用 `/v1/images/generations`， +当存在 `image` 或 `images` 时使用 `/v1/images/edits`。 - 模型：`xai/grok-imagine-image`、`xai/grok-imagine-image-pro` - 数量：最多 4 张 -- 参考：一个 `image` 或最多五个 `images` +- 参考图：一张 `image` 或最多五张 `images` - 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2` - 分辨率：`1K`、`2K` -- 输出：作为由 OpenClaw 管理的图像附件返回 +- 输出：以 OpenClaw 管理的图像附件形式返回 -在这些控制项尚未存在于共享的跨提供商 `image_generate` contract 中之前， -OpenClaw 有意不暴露 xAI 原生的 `quality`、`mask`、`user` 或额外的原生专属宽高比。 +在这些控制项进入跨提供商共享的 `image_generate` 契约之前， +OpenClaw 有意不暴露 xAI 原生的 `quality`、`mask`、`user` 或 +其他仅原生支持的宽高比。 ## 相关内容 - [工具概览](/zh-CN/tools) — 所有可用的智能体工具 - [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置 - [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置 -- [Google (Gemini)](/zh-CN/providers/google) — Gemini 图像提供商设置 +- [Google（Gemini）](/zh-CN/providers/google) — Gemini 图像提供商设置 - [MiniMax](/zh-CN/providers/minimax) — MiniMax 图像提供商设置 - [OpenAI](/zh-CN/providers/openai) — OpenAI Images 提供商设置 - [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置 - [xAI](/zh-CN/providers/xai) — Grok 图像、视频、搜索、代码执行和 TTS 设置 - [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — `imageGenerationModel` 配置 -- [Models](/zh-CN/concepts/models) — 模型配置和故障转移 +- [Models](/zh-CN/concepts/models) — 模型配置和故障切换 diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index b2d3e8d57..f48e3f875 100644 --- a/docs/zh-CN/tools/tts.md +++ b/docs/zh-CN/tools/tts.md @@ -3,44 +3,39 @@ read_when: - 为回复启用文本转语音 - 配置 TTS 提供商或限制 - 使用 `/tts` 命令 -summary: 用于发出回复的文本转语音（TTS） +summary: 传出回复的文本转语音（TTS） title: 文本转语音 x-i18n: - generated_at: "2026-04-25T11:16:04Z" + generated_at: "2026-04-25T18:12:55Z" model: gpt-5.4 provider: openai - source_hash: 0038157f631a308c8ff7f0eef9db2b2d686cd417c525ac37b9d21097c34d9b6a + source_hash: 2c56c42f201139a7277153a6a1409ef9a288264e0702d2940b74b08ece385718 source_path: tools/tts.md workflow: 15 --- -OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Local CLI、Microsoft、MiniMax、OpenAI、Vydra、xAI 或 Xiaomi MiMo，将发出的回复转换为音频。 -它适用于 OpenClaw 能发送音频的任何地方。 +OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Local CLI、Microsoft、MiniMax、OpenAI、Vydra、xAI 或 Xiaomi MiMo 将传出回复转换为音频。 +它适用于 OpenClaw 能够发送音频的任何场景。 ## 支持的服务 -- **ElevenLabs**（主要或回退提供商） -- **Google Gemini**（主要或回退提供商；使用 Gemini API TTS） -- **Gradium**（主要或回退提供商；支持语音便笺和电话输出） -- **Local CLI**（主要或回退提供商；运行已配置的本地 TTS 命令） -- **Microsoft**（主要或回退提供商；当前内置实现使用 `node-edge-tts`） -- **MiniMax**（主要或回退提供商；使用 T2A v2 API） -- **OpenAI**（主要或回退提供商；也用于摘要） -- **Vydra**（主要或回退提供商；共享图像、视频和语音提供商） -- **xAI**（主要或回退提供商；使用 xAI TTS API） -- **Xiaomi MiMo**（主要或回退提供商；通过 Xiaomi chat completions 使用 MiMo TTS） +- **ElevenLabs**（主提供商或回退提供商） +- **Google Gemini**（主提供商或回退提供商；使用 Gemini API TTS） +- **Gradium**（主提供商或回退提供商；支持语音便笺和电话输出） +- **Local CLI**（主提供商或回退提供商；运行已配置的本地 TTS 命令） +- **Microsoft**（主提供商或回退提供商；当前内置实现使用 `node-edge-tts`） +- **MiniMax**（主提供商或回退提供商；使用 T2A v2 API） +- **OpenAI**（主提供商或回退提供商；也用于摘要） +- **Vydra**（主提供商或回退提供商；共享的图像、视频和语音提供商） +- **xAI**（主提供商或回退提供商；使用 xAI TTS API） +- **Xiaomi MiMo**（主提供商或回退提供商；通过 Xiaomi chat completions 使用 MiMo TTS） ### 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。 +由于这一路径是公共 Web 服务，且没有公开发布的 SLA 或配额，因此应将其视为尽力而为服务。如果你需要有保障的限制和支持，请使用 OpenAI 或 ElevenLabs。 ## 可选密钥 @@ -49,9 +44,9 @@ OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Local CLI、Microso - `ELEVENLABS_API_KEY`（或 `XI_API_KEY`） - `GEMINI_API_KEY`（或 `GOOGLE_API_KEY`） - `GRADIUM_API_KEY` -- `MINIMAX_API_KEY`；MiniMax TTS 也接受 Token Plan 身份验证，可通过 +- `MINIMAX_API_KEY`；MiniMax TTS 还接受通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 - `MINIMAX_CODING_API_KEY` + `MINIMAX_CODING_API_KEY` 进行的 Token Plan 认证 - `OPENAI_API_KEY` - `VYDRA_API_KEY` - `XAI_API_KEY` @@ -59,9 +54,8 @@ OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Local CLI、Microso Local CLI 和 Microsoft 语音 **不** 需要 API 密钥。 -如果配置了多个提供商，将优先使用所选提供商，其他提供商作为回退选项。 -自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`）， -因此如果你启用摘要，该提供商也必须完成身份验证。 +如果配置了多个提供商，则会优先使用所选提供商，其他提供商作为回退选项。 +自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用摘要，该提供商也必须完成身份验证。 ## 服务链接 @@ -78,16 +72,15 @@ Local CLI 和 Microsoft 语音 **不** 需要 API 密钥。 ## 默认启用吗？ -不是。自动 TTS 默认**关闭**。可在配置中使用 -`messages.tts.auto` 启用，或在本地使用 `/tts on` 启用。 +不是。自动 TTS 默认 **关闭**。可在配置中通过 +`messages.tts.auto` 启用，或在本地通过 `/tts on` 启用。 -当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序， -选择第一个已配置的语音提供商。 +当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序选择第一个已配置的语音提供商。 ## 配置 -TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 -完整 schema 见 [Gateway 网关配置](/zh-CN/gateway/configuration)。 +TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 +完整架构请参见 [Gateway 配置](/zh-CN/gateway/configuration)。 ### 最小配置（启用 + 提供商） @@ -102,7 +95,7 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 } ``` -### OpenAI 主提供商，ElevenLabs 回退 +### OpenAI 为主，ElevenLabs 为回退 ```json5 { @@ -143,7 +136,7 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 } ``` -### Microsoft 主提供商（无 API 密钥） +### Microsoft 为主（无需 API 密钥） ```json5 { @@ -166,7 +159,7 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 } ``` -### MiniMax 主提供商 +### MiniMax 为主 ```json5 { @@ -190,14 +183,13 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 } ``` -MiniMax TTS 身份验证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是 -已存储的 `minimax-portal` OAuth/token 配置文件，然后是 Token Plan 环境变量密钥 +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 +`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。如果未显式设置 TTS +`baseUrl`，OpenClaw 可以复用已配置的 `minimax-portal` OAuth 主机用于 Token Plan 语音。 -### Google Gemini 主提供商 +### Google Gemini 为主 ```json5 { @@ -217,13 +209,11 @@ MiniMax TTS 身份验证解析顺序为 `messages.tts.providers.minimax.apiKey` } ``` -Google Gemini TTS 使用 Gemini API 密钥路径。一个限制为 Gemini API 的 -Google Cloud Console API 密钥在这里也可用，并且它与内置 Google 图像生成提供商 -使用的是同一种密钥形式。解析顺序为 +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 { @@ -247,10 +237,9 @@ Google Cloud Console API 密钥在这里也可用，并且它与内置 Google 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`。 +当前可用的实时语音为 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值为 `eve`。`language` 接受 BCP-47 标签或 `auto`。 -### Xiaomi MiMo 主提供商 +### Xiaomi MiMo 为主 ```json5 { @@ -273,12 +262,11 @@ xAI TTS 使用与内置 Grok 模型提供商相同的 `XAI_API_KEY` 路径。 } ``` -Xiaomi MiMo TTS 使用与内置 Xiaomi 模型 -提供商相同的 `XIAOMI_API_KEY` 路径。语音提供商 id 是 `xiaomi`；`mimo` -也可作为别名使用。目标文本会作为 assistant 消息发送，这与 Xiaomi 的 TTS -契约一致。可选的 `style` 会作为用户指令发送，而不会被读出。 +Xiaomi MiMo TTS 使用与内置 Xiaomi 模型提供商相同的 `XIAOMI_API_KEY` 路径。语音提供商 ID 为 `xiaomi`；也接受 `mimo` 作为别名。 +目标文本会作为助手消息发送，这与 Xiaomi 的 TTS 协议一致。 +可选的 `style` 会作为用户指令发送，不会被读出。 -### OpenRouter 主提供商 +### OpenRouter 为主 ```json5 { @@ -299,12 +287,11 @@ Xiaomi MiMo TTS 使用与内置 Xiaomi 模型 } ``` -OpenRouter TTS 使用与内置 -OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 +OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 `messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。 -### Local CLI 主提供商 +### Local CLI 为主 ```json5 { @@ -325,14 +312,12 @@ OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序 } ``` -Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}`、 -`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符会在 `args` 中展开；如果不存在 -`{{Text}}` 占位符，OpenClaw 会将要朗读的文本写入 stdin。 -`outputFormat` 接受 `mp3`、`opus` 或 `wav`。 -语音便笺目标会被转码为 Ogg/Opus，电话输出会被转码为原始 16 kHz 单声道 PCM，使用 `ffmpeg`。 -旧版提供商别名 `cli` 仍然可用，但新配置应使用 `tts-local-cli`。 +Local CLI TTS 会在网关主机上运行已配置的命令。`{{Text}}`、 +`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符会在 `args` 中展开；如果没有 `{{Text}}` 占位符，OpenClaw 会将要朗读的文本写入 stdin。`outputFormat` 接受 `mp3`、`opus` 或 `wav`。 +语音便笺目标会被转码为 Ogg/Opus，电话输出会使用 `ffmpeg` 转码为原始的 16 kHz 单声道 PCM。旧版提供商别名 +`cli` 仍然有效，但新配置应使用 `tts-local-cli`。 -### Gradium 主提供商 +### Gradium 为主 ```json5 { @@ -368,7 +353,7 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} } ``` -### 自定义限制 + 偏好设置路径 +### 自定义限制 + prefs 路径 ```json5 { @@ -383,7 +368,7 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} } ``` -### 仅在收到语音消息后用音频回复 +### 仅在传入语音消息后用音频回复 ```json5 { @@ -416,25 +401,24 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} ### 字段说明 - `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。 - - `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` **未设置**，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。 -- 旧版 `provider: "edge"` 配置可通过 `openclaw doctor --fix` 修复，并 - 重写为 `provider: "microsoft"`。 -- `summaryModel`：用于自动摘要的可选低成本模型；默认值为 `agents.defaults.model.primary`。 + - `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`，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。 +- 旧版 `provider: "edge"` 配置可由 `openclaw doctor --fix` 修复，并重写为 `provider: "microsoft"`。 +- `summaryModel`：用于自动摘要的可选低成本模型；默认为 `agents.defaults.model.primary`。 - 接受 `provider/model` 或已配置的模型别名。 -- `modelOverrides`：允许模型发出 TTS 指令（默认开启）。 +- `modelOverrides`：允许模型输出 TTS 指令（默认开启）。 - `allowProvider` 默认为 `false`（切换提供商需要显式启用）。 -- `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` 会失败。 +- `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` 会失败。 - `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`）。 +- `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` @@ -445,69 +429,67 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} - `speed`：`0.5..2.0`（1.0 = 正常） - `providers.elevenlabs.applyTextNormalization`：`auto|on|off` - `providers.elevenlabs.languageCode`：2 位 ISO 639-1 代码（例如 `en`、`de`） -- `providers.elevenlabs.seed`：整数 `0..4294967295`（尽力提供确定性） +- `providers.elevenlabs.seed`：整数 `0..4294967295`（尽力实现确定性） - `providers.minimax.baseUrl`：覆盖 MiniMax API 基础 URL（默认 `https://api.minimax.io`，环境变量：`MINIMAX_API_HOST`）。 - `providers.minimax.model`：TTS 模型（默认 `speech-2.8-hd`，环境变量：`MINIMAX_TTS_MODEL`）。 - `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.tts-local-cli.command`：用于 CLI TTS 的本地可执行文件或命令字符串。 - `providers.tts-local-cli.args`：命令参数；支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符。 -- `providers.tts-local-cli.outputFormat`：预期的 CLI 输出格式（`mp3`、`opus` 或 `wav`；音频附件默认值为 `mp3`）。 -- `providers.tts-local-cli.timeoutMs`：命令超时时间（毫秒，默认 `120000`）。 +- `providers.tts-local-cli.outputFormat`：预期的 CLI 输出格式（`mp3`、`opus` 或 `wav`；音频附件默认 `mp3`）。 +- `providers.tts-local-cli.timeoutMs`：命令超时（毫秒，默认 `120000`）。 - `providers.tts-local-cli.cwd`：可选的命令工作目录。 -- `providers.tts-local-cli.env`：命令的可选字符串环境变量覆盖项。 +- `providers.tts-local-cli.env`：命令的可选字符串环境变量覆盖。 - `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.speakerName`：当你的 TTS 提示使用命名说话人时，在朗读文本前附加的可选说话人标签。 - `providers.google.baseUrl`：覆盖 Gemini API 基础 URL。仅接受 `https://generativelanguage.googleapis.com`。 - - 如果省略 `messages.tts.providers.google.apiKey`，TTS 可以先复用 `models.providers.google.apiKey`，再回退到环境变量。 + - 如果省略 `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`：可选的自然语言风格指令，作为用户消息发送；不会被读出。 -- `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.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.responseFormat`：`mp3` 或 `pcm`（默认 `mp3`）。 - `providers.openrouter.speed`：提供商原生速度覆盖值。 - `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 output formats；并非所有格式都受内置的 Edge 后端传输支持。 + - 有效值请参见 Microsoft Speech output formats；并非所有格式都受内置的基于 Edge 的传输支持。 - `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`：百分比字符串（例如 `+10%`、`-5%`）。 -- `providers.microsoft.saveSubtitles`：在音频文件旁边写入 JSON 字幕。 +- `providers.microsoft.saveSubtitles`：在音频文件旁写入 JSON 字幕。 - `providers.microsoft.proxy`：用于 Microsoft 语音请求的代理 URL。 - `providers.microsoft.timeoutMs`：请求超时覆盖值（毫秒）。 - `edge.*`：同一组 Microsoft 设置的旧版别名。运行 - `openclaw doctor --fix` 可将持久化配置重写为 `providers.microsoft`。 + `openclaw doctor --fix` 以将持久化配置重写为 `providers.microsoft`。 -## 模型驱动的覆盖项（默认开启） +## 模型驱动的覆盖（默认开启） -默认情况下，模型**可以**为单条回复发出 TTS 指令。 -当 `messages.tts.auto` 为 `tagged` 时，这些指令是触发音频所必需的。 +默认情况下，模型**可以**为单条回复输出 TTS 指令。 +当 `messages.tts.auto` 为 `tagged` 时，必须提供这些指令才会触发音频。 -启用后，模型可以发出 `[[tts:...]]` 指令，为单条回复覆盖语音 -设置，并可选附带一个 `[[tts:text]]...[[/tts:text]]` 块，用于提供仅应出现在 -音频中的表现性标签（笑声、歌唱提示等）。 +启用后，模型可以输出 `[[tts:...]]` 指令，以覆盖单条回复的语音，还可选择输出 `[[tts:text]]...[[/tts:text]]` 块，提供只应出现在音频中的表现性标签（笑声、歌唱提示等）。 除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 -示例回复负载： +回复负载示例： ``` Here you go. @@ -516,19 +498,19 @@ 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 model id、MiniMax 模型或 Xiaomi MiMo TTS 模型）或 `google_model`（Google TTS 模型） +- `model`（OpenAI TTS 模型、ElevenLabs 模型 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` -禁用所有模型覆盖项： +禁用所有模型覆盖： ```json5 { @@ -542,7 +524,7 @@ Here you go. } ``` -可选允许列表（启用提供商切换，同时保持其他参数仍可配置）： +可选允许列表（启用提供商切换，同时保留其他参数可配置）： ```json5 { @@ -558,10 +540,10 @@ Here you go. } ``` -## 按用户偏好 +## 按用户偏好设置 -斜杠命令会将本地覆盖项写入 `prefsPath`（默认： -`~/.openclaw/settings/tts.json`，也可用 `OPENCLAW_TTS_PREFS` 或 +斜杠命令会将本地覆盖写入 `prefsPath`（默认： +`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。 存储字段： @@ -571,45 +553,39 @@ 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。 + - 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。 -- **Local CLI**：使用已配置的 `outputFormat`。语音便笺目标会 - 转换为 Ogg/Opus，电话输出会使用 `ffmpeg` 转换为原始 16 kHz 单声道 PCM。 -- **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 语音便笺格式。 +- **Local CLI**：使用已配置的 `outputFormat`。语音便笺目标会转换为 Ogg/Opus，电话输出会使用 `ffmpeg` 转换为原始的 16 kHz 单声道 PCM。 +- **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 语音便笺格式。 - **Microsoft**：使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。 - - 内置传输支持 `outputFormat`，但服务并不提供所有格式。 + - 内置传输接受 `outputFormat`，但并非所有格式都可由该服务提供。 - 输出格式值遵循 Microsoft Speech output formats（包括 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 密钥），则会跳过音频，并发送普通文本回复。 ## 流程图 @@ -631,8 +607,7 @@ Reply -> TTS enabled? 只有一个命令：`/tts`。 启用详情请参见 [斜杠命令](/zh-CN/tools/slash-commands)。 -Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 在该平台上注册 -`/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。 +Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那里将 `/voice` 注册为原生命令。文本形式的 `/tts ...` 仍然可用。 ``` /tts off @@ -650,27 +625,25 @@ Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 在该平 - 必须启用 `commands.text` 或原生命令注册。 - 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。 - `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。 -- 如果你希望默认使用 `inbound` 或 `tagged`，请使用配置。 +- 当你希望默认使用 `inbound` 或 `tagged` 时，请使用配置。 - `limit` 和 `summary` 存储在本地偏好中，而不是主配置中。 -- `/tts audio` 会生成一次性的音频回复（不会开启 TTS）。 +- `/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 输出进行转码。 +WhatsApp 会将可见文本与 PTT 语音便笺音频分开发送，因为客户端对语音便笺上的说明文字显示并不一致。 +它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是每次调用提供商请求的超时时间（毫秒）。 ## Gateway 网关 RPC -Gateway 网关方法： +Gateway 网关 方法： - `tts.status` - `tts.enable`