From d6163d1a66b3d8e44331d47fed55d4b3c218f19f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 6 Apr 2026 15:34:09 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/groups.md | 158 +- docs/zh-CN/channels/matrix.md | 645 +++--- docs/zh-CN/channels/whatsapp.md | 187 +- docs/zh-CN/concepts/model-failover.md | 301 ++- docs/zh-CN/concepts/model-providers.md | 439 ++-- docs/zh-CN/concepts/oauth.md | 127 +- docs/zh-CN/gateway/authentication.md | 114 +- docs/zh-CN/gateway/cli-backends.md | 154 +- docs/zh-CN/gateway/configuration-reference.md | 1113 +++++----- docs/zh-CN/gateway/doctor.md | 421 ++-- docs/zh-CN/gateway/index.md | 184 +- docs/zh-CN/gateway/troubleshooting.md | 311 ++- docs/zh-CN/help/faq.md | 1831 ++++++++--------- docs/zh-CN/help/testing.md | 586 +++--- ...refactor-real-plugin-sdk-workspace-plan.md | 509 +++++ docs/zh-CN/platforms/ios.md | 178 +- docs/zh-CN/plugins/architecture.md | 1162 ++++++----- docs/zh-CN/plugins/sdk-migration.md | 372 ++-- docs/zh-CN/plugins/sdk-overview.md | 457 ++-- docs/zh-CN/plugins/sdk-provider-plugins.md | 306 ++- docs/zh-CN/plugins/webhooks.md | 194 ++ docs/zh-CN/providers/anthropic.md | 156 +- docs/zh-CN/providers/openai.md | 218 +- docs/zh-CN/reference/api-usage-costs.md | 163 +- docs/zh-CN/reference/test.md | 78 +- docs/zh-CN/reference/token-use.md | 142 +- docs/zh-CN/reference/wizard.md | 166 +- docs/zh-CN/start/wizard-cli-automation.md | 33 +- docs/zh-CN/start/wizard.md | 96 +- docs/zh-CN/tools/media-overview.md | 67 + docs/zh-CN/tools/music-generation.md | 202 +- docs/zh-CN/tools/video-generation.md | 242 ++- docs/zh-CN/tts.md | 453 +--- 33 files changed, 6146 insertions(+), 5619 deletions(-) create mode 100644 docs/zh-CN/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md create mode 100644 docs/zh-CN/plugins/webhooks.md create mode 100644 docs/zh-CN/tools/media-overview.md diff --git a/docs/zh-CN/channels/groups.md b/docs/zh-CN/channels/groups.md index 70f66d558..f3e7fce1c 100644 --- a/docs/zh-CN/channels/groups.md +++ b/docs/zh-CN/channels/groups.md @@ -1,37 +1,37 @@ --- read_when: - - 更改群聊行为或提及门控时 -summary: 跨平台界面的群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo） + - 修改群聊行为或提及门控时 +summary: 跨界面群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo） title: 群组 x-i18n: - generated_at: "2026-04-05T17:47:15Z" + generated_at: "2026-04-06T15:28:01Z" model: gpt-5.4 provider: openai - source_hash: 8620de6f7f0b866bf43a307fdbec3399790f09f22a87703704b0522caba80b18 + source_hash: 83d20f2958ed6ad3354f0078553b3c6a38643ea8ef38573c40e89ebef2fa8421 source_path: channels/groups.md workflow: 15 --- # 群组 -OpenClaw 会在各个平台界面上一致地处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。 +OpenClaw 会在各个界面上一致地处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。 ## 新手简介（2 分钟） -OpenClaw “运行”在你自己的消息账号上。没有单独的 WhatsApp 机器人用户。 -如果**你**在某个群里，OpenClaw 就可以看到该群并在其中回复。 +OpenClaw “运行”在你自己的消息账号上。它不是一个单独的 WhatsApp 机器人用户。 +如果**你**在某个群里，OpenClaw 就可以看到那个群并在那里回复。 默认行为： -- 群组受限（`groupPolicy: "allowlist"`）。 +- 群组是受限的（`groupPolicy: "allowlist"`）。 - 回复需要提及，除非你明确禁用提及门控。 -也就是说：在允许名单中的发送者可以通过提及 OpenClaw 来触发它。 +换句话说：在允许列表中的发送者可以通过提及 OpenClaw 来触发它。 > 简而言之 > > - **私信访问**由 `*.allowFrom` 控制。 -> - **群组访问**由 `*.groupPolicy` + 允许名单（`*.groups`、`*.groupAllowFrom`）控制。 +> - **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。 > - **回复触发**由提及门控（`requireMention`、`/activation`）控制。 快速流程（群消息会发生什么）： @@ -43,62 +43,62 @@ requireMention? yes -> mentioned? no -> store for context only otherwise -> reply ``` -## 上下文可见性与允许名单 +## 上下文可见性与允许列表 -群组安全性涉及两种不同的控制： +群组安全涉及两种不同的控制： -- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道特定允许名单）。 -- **上下文可见性**：哪些补充上下文会被注入到模型中（回复文本、引用、线程历史、转发元数据）。 +- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道特定允许列表）。 +- **上下文可见性**：哪些补充上下文会注入到模型中（回复文本、引用、线程历史、转发元数据）。 -默认情况下，OpenClaw 优先保证正常聊天行为，并尽量按接收到的原样保留上下文。这意味着，允许名单主要决定谁可以触发操作，而不是对每一段引用或历史片段都应用的通用脱敏边界。 +默认情况下，OpenClaw 优先保持正常聊天行为，并尽量按接收到的原样保留上下文。这意味着允许列表主要决定谁可以触发操作，而不是对每一段引用或历史片段都进行统一脱敏的边界。 当前行为因渠道而异： -- 某些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 线程预置上下文、Matrix 回复/线程查询）。 -- 其他渠道仍会按接收到的原样传递引用/回复/转发上下文。 +- 某些渠道已经在特定路径上对补充上下文应用基于发送者的过滤（例如 Slack 线程预载、Matrix 回复/线程查询）。 +- 其他渠道仍然会按接收到的原样传递引用/回复/转发上下文。 加固方向（计划中）： -- `contextVisibility: "all"`（默认）保留当前“按接收原样”的行为。 -- `contextVisibility: "allowlist"` 将补充上下文过滤为仅允许名单中的发送者。 -- `contextVisibility: "allowlist_quote"` 等同于 `allowlist`，再加上一个明确的引用/回复例外。 +- `contextVisibility: "all"`（默认）保持当前“按接收原样处理”的行为。 +- `contextVisibility: "allowlist"` 会将补充上下文过滤为仅限允许列表中的发送者。 +- `contextVisibility: "allowlist_quote"` 等于 `allowlist`，再加上一条显式的引用/回复例外规则。 -在这一加固模型尚未在各渠道中一致实现之前，不同平台界面间的行为差异仍然是预期之内的。 +在这一加固模型尚未在所有渠道中一致实现之前，不同界面的行为仍会有所差异。 -![群消息流程](/images/groups-flow.svg) +![群消息流转](/images/groups-flow.svg) 如果你想要…… -| 目标 | 应设置的内容 | +| 目标 | 需要设置什么 | | -------------------------------------------- | ---------------------------------------------------------- | -| 允许所有群组，但仅在 @提及时回复 | `groups: { "*": { requireMention: true } }` | +| 允许所有群组，但只在 @提及时回复 | `groups: { "*": { requireMention: true } }` | | 禁用所有群组回复 | `groupPolicy: "disabled"` | -| 仅允许特定群组 | `groups: { "": { ... } }`（不使用 `"*"` 键） | -| 只有你能在群组中触发 | `groupPolicy: "allowlist"`，`groupAllowFrom: ["+1555..."]` | +| 只允许特定群组 | `groups: { "": { ... } }`（不使用 `"*"` 键） | +| 只有你可以在群组中触发 OpenClaw | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | ## 会话键 -- 群组会话使用 `agent:::group:` 会话键（房间/渠道使用 `agent:::channel:`）。 +- 群组会话使用 `agent:::group:` 会话键（房间/频道使用 `agent:::channel:`）。 - Telegram 论坛主题会在群组 id 后附加 `:topic:`，因此每个主题都有自己的会话。 -- 直接聊天使用主会话（或按配置为每个发送者分别使用）。 +- 私聊使用主会话（或在已配置时按发送者分开）。 - 群组会话会跳过心跳。 -## 模式：个人私信 + 公开群组（单个智能体） +## 模式：个人私信 + 公开群组（单智能体） -可以——如果你的“个人”流量是**私信**，而你的“公开”流量是**群组**，这种方式效果很好。 +可以——如果你的“个人”流量是**私信**，而“公开”流量是**群组**，这个模式效果很好。 -原因是：在单智能体模式下，私信通常会进入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main::group:`）。如果你启用 `mode: "non-main"` 的沙箱隔离，这些群组会话会在 Docker 中运行，而你的主私信会话仍在主机上运行。 +原因是：在单智能体模式下，私信通常会进入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main::group:`）。如果你启用沙箱隔离并设置 `mode: "non-main"`，这些群组会话就会在 Docker 中运行，而你的主私信会话仍然留在主机上运行。 -这会给你一个智能体“脑”（共享工作区 + 记忆），但有两种不同的执行姿态： +这样你就拥有一个智能体“脑”（共享工作区 + 记忆），但两种执行姿态： - **私信**：完整工具（主机） - **群组**：沙箱 + 受限工具（Docker） -> 如果你需要真正分离的工作区/人格（“个人”和“公开”绝不能混用），请使用第二个智能体 + 绑定。参见 [多智能体路由](/zh-CN/concepts/multi-agent)。 +> 如果你需要真正独立的工作区/角色（“个人”和“公开”绝不能混在一起），请使用第二个智能体 + 绑定。参见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。 -示例（私信在主机上运行，群组启用沙箱隔离 + 仅限消息工具）： +示例（私信在主机上，群组使用沙箱隔离且仅允许消息类工具）： ```json5 { @@ -123,7 +123,7 @@ otherwise -> reply } ``` -想要“群组只能看到文件夹 X”，而不是“完全不能访问主机”？保留 `workspaceAccess: "none"`，并只将允许名单中的路径挂载到沙箱中： +想要实现“群组只能看到文件夹 X”而不是“完全不能访问主机”？保留 `workspaceAccess: "none"`，然后只把允许列表中的路径挂载进沙箱： ```json5 { @@ -147,18 +147,18 @@ otherwise -> reply 相关内容： -- 配置键和默认值：[Gateway 网关配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) -- 调试某个工具为何被阻止：[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) +- 配置键与默认值：[Gateway 配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) +- 调试为什么某个工具被阻止：[沙箱隔离 vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) - 绑定挂载详情：[沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) ## 显示标签 - UI 标签在可用时使用 `displayName`，格式为 `:`。 -- `#room` 保留给房间/渠道；群聊使用 `g-`（小写，空格转为 `-`，保留 `#@+._-`）。 +- `#room` 保留给房间/频道；群聊使用 `g-`（小写，空格转为 `-`，保留 `#@+._-`）。 ## 群组策略 -控制每个渠道如何处理群组/房间消息： +按渠道控制如何处理群组/房间消息： ```json5 { @@ -197,8 +197,8 @@ otherwise -> reply groupPolicy: "allowlist", groupAllowFrom: ["@owner:example.org"], groups: { - "!roomId:example.org": { allow: true }, - "#alias:example.org": { allow: true }, + "!roomId:example.org": { enabled: true }, + "#alias:example.org": { enabled: true }, }, }, }, @@ -207,34 +207,34 @@ otherwise -> reply | 策略 | 行为 | | ------------- | ------------------------------------------------------------ | -| `"open"` | 群组绕过允许名单；提及门控仍然适用。 | +| `"open"` | 群组会绕过允许列表；但提及门控仍然生效。 | | `"disabled"` | 完全阻止所有群组消息。 | -| `"allowlist"` | 仅允许与配置的允许名单匹配的群组/房间。 | +| `"allowlist"` | 仅允许与已配置允许列表匹配的群组/房间。 | 说明： -- `groupPolicy` 与提及门控是分开的（后者要求使用 @提及）。 -- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（回退为显式 `allowFrom`）。 -- 私信配对批准（`*-allowFrom` 存储条目）仅适用于私信访问；群组发送者授权仍需通过群组允许名单显式配置。 -- Discord：允许名单使用 `channels.discord.guilds..channels`。 -- Slack：允许名单使用 `channels.slack.channels`。 -- Matrix：允许名单使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查询仅尽力而为，运行时无法解析的名称会被忽略。使用 `channels.matrix.groupAllowFrom` 来限制发送者；也支持按房间配置的 `users` 允许名单。 -- 群组私信是单独控制的（`channels.discord.dm.*`、`channels.slack.dm.*`）。 -- Telegram 允许名单可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀大小写不敏感。 -- 默认值为 `groupPolicy: "allowlist"`；如果你的群组允许名单为空，群组消息将被阻止。 -- 运行时安全性：当某个提供商配置块完全缺失（没有 `channels.`）时，群组策略会回退到故障关闭模式（通常为 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。 +- `groupPolicy` 与提及门控是分开的（提及门控要求 @提及）。 +- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（回退：显式 `allowFrom`）。 +- 私信配对审批（`*-allowFrom` 存储项）只适用于私信访问；群组发送者授权仍需要在群组允许列表中显式配置。 +- Discord：允许列表使用 `channels.discord.guilds..channels`。 +- Slack：允许列表使用 `channels.slack.channels`。 +- Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查询是尽力而为，运行时无法解析的名称会被忽略。使用 `channels.matrix.groupAllowFrom` 来限制发送者；也支持按房间配置的 `users` 允许列表。 +- 群组私信单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。 +- Telegram 允许列表可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀大小写不敏感。 +- 默认值是 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息会被阻止。 +- 运行时安全：当某个提供商配置块完全缺失（`channels.` 不存在）时，群组策略会回退到故障关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。 快速心智模型（群组消息的评估顺序）： 1. `groupPolicy`（open/disabled/allowlist） -2. 群组允许名单（`*.groups`、`*.groupAllowFrom`、渠道特定允许名单） +2. 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道特定允许列表） 3. 提及门控（`requireMention`、`/activation`） ## 提及门控（默认） 群组消息默认需要提及，除非按群组覆盖。默认值按子系统存放在 `*.groups."*"` 下。 -回复机器人消息会被视为隐式提及（前提是该渠道支持回复元数据）。这适用于 Telegram、WhatsApp、Slack、Discord 和 Microsoft Teams。 +回复机器人消息会被视为隐式提及（当渠道支持回复元数据时）。这适用于 Telegram、WhatsApp、Slack、Discord 和 Microsoft Teams。 ```json5 { @@ -275,26 +275,26 @@ otherwise -> reply 说明： - `mentionPatterns` 是大小写不敏感的安全正则模式；无效模式和不安全的嵌套重复形式会被忽略。 -- 提供显式提及的平台界面仍然会通过；这些模式只是回退方案。 +- 提供显式提及的界面仍然会通过；这些模式只是回退方案。 - 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时很有用）。 -- 只有在可以进行提及检测时，才会强制执行提及门控（存在原生提及或已配置 `mentionPatterns`）。 -- Discord 的默认值位于 `channels.discord.guilds."*"`（可按 guild/channel 覆盖）。 -- 群组历史上下文会在各渠道间统一包装，并且仅限于**待处理消息**（即因提及门控而被跳过的消息）；全局默认值使用 `messages.groupChat.historyLimit`，覆盖项使用 `channels..historyLimit`（或 `channels..accounts.*.historyLimit`）。设为 `0` 可禁用。 +- 只有在能够检测提及时，才会强制执行提及门控（原生提及或已配置 `mentionPatterns`）。 +- Discord 默认值位于 `channels.discord.guilds."*"`（可按 guild/channel 覆盖）。 +- 群组历史上下文会在各个渠道中统一包装，并且仅包含**待处理消息**（即因提及门控而跳过的消息）；全局默认值使用 `messages.groupChat.historyLimit`，覆盖项使用 `channels..historyLimit`（或 `channels..accounts.*.historyLimit`）。设为 `0` 可禁用。 -## 群组/渠道工具限制（可选） +## 群组/频道工具限制（可选） -某些渠道配置支持限制**特定群组/房间/渠道内部**可用的工具。 +某些渠道配置支持限制**特定群组/房间/频道内**可用的工具。 - `tools`：为整个群组允许/拒绝工具。 - `toolsBySender`：群组内按发送者覆盖。 使用显式键前缀： - `id:`、`e164:`、`username:`、`name:` 以及 `"*"` 通配符。 - 旧版无前缀键仍然接受，但仅按 `id:` 匹配。 + `id:`、`e164:`、`username:`、`name:` 和 `"*"` 通配符。 + 旧版无前缀键仍然被接受，但只会按 `id:` 匹配。 解析顺序（越具体优先级越高）： -1. 群组/渠道 `toolsBySender` 匹配 -2. 群组/渠道 `tools` +1. 群组/频道 `toolsBySender` 匹配 +2. 群组/频道 `tools` 3. 默认（`"*"`）`toolsBySender` 匹配 4. 默认（`"*"`）`tools` @@ -320,15 +320,15 @@ otherwise -> reply 说明： -- 群组/渠道工具限制会与全局/智能体工具策略叠加应用（拒绝仍然优先）。 -- 某些渠道对房间/渠道使用不同的嵌套结构（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。 +- 群组/频道工具限制是在全局/智能体工具策略之外额外应用的（deny 仍然优先）。 +- 某些渠道对房间/频道使用不同的嵌套结构（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。 -## 群组允许名单 +## 群组允许列表 -当配置了 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会作为群组允许名单。使用 `"*"` 可允许所有群组，同时仍设置默认提及行为。 +当配置了 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会充当群组允许列表。使用 `"*"` 可允许所有群组，同时仍然设置默认提及行为。 -一个常见误解是：私信配对批准并不等同于群组授权。 -对于支持私信配对的渠道，配对存储仅解锁私信。群组命令仍然需要通过配置允许名单显式授权群组发送者，例如 `groupAllowFrom` 或该渠道文档中说明的配置回退项。 +常见困惑：私信配对审批并不等同于群组授权。 +对于支持私信配对的渠道，配对存储只会解锁私信。群组命令仍然需要通过配置允许列表显式授权群组发送者，例如 `groupAllowFrom` 或该渠道文档说明的回退配置。 常见意图（可直接复制粘贴）： @@ -383,35 +383,35 @@ otherwise -> reply ## 激活（仅所有者） -群组所有者可以切换每个群组的激活方式： +群组所有者可以按群组切换激活模式： - `/activation mention` - `/activation always` -所有者由 `channels.whatsapp.allowFrom` 决定（未设置时则为机器人的自身 E.164）。请将命令作为单独一条消息发送。其他平台界面当前会忽略 `/activation`。 +所有者由 `channels.whatsapp.allowFrom` 决定（如果未设置，则使用机器人自身的 E.164）。请将命令作为单独一条消息发送。其他界面当前会忽略 `/activation`。 ## 上下文字段 -群组入站载荷会设置： +群组入站负载会设置： - `ChatType=group` - `GroupSubject`（如果已知） - `GroupMembers`（如果已知） - `WasMentioned`（提及门控结果） -- Telegram 论坛主题还会包含 `MessageThreadId` 和 `IsForum` +- Telegram 论坛主题还会包含 `MessageThreadId` 和 `IsForum`。 渠道特定说明： -- BlueBubbles 可以选择在填充 `GroupMembers` 之前，先从本地通讯录数据库中补全未命名的 macOS 群组参与者信息。该功能默认关闭，并且只会在正常群组门控通过后运行。 +- BlueBubbles 可以在填充 `GroupMembers` 之前，选择性地从本地 Contacts 数据库中补充未命名的 macOS 群组参与者信息。此功能默认关闭，并且只会在常规群组门控通过后运行。 -智能体系统提示会在新群组会话的第一轮包含一段群组简介。它会提醒模型像人类一样回复、避免使用 Markdown 表格、尽量减少空行并遵循正常聊天间距，同时避免输入字面量 `\n` 序列。 +智能体系统提示会在新群组会话的第一轮加入群组说明。它会提醒模型像人类一样回复、避免使用 Markdown 表格、尽量减少空行、遵循正常聊天间距，并避免输入字面量 `\n` 序列。 ## iMessage 细节 -- 在路由或加入允许名单时，优先使用 `chat_id:`。 +- 在路由或允许列表中优先使用 `chat_id:`。 - 列出聊天：`imsg chats --limit 20`。 - 群组回复始终会发回相同的 `chat_id`。 ## WhatsApp 细节 -有关 WhatsApp 专属行为（历史注入、提及处理细节），请参见 [群组消息](/zh-CN/channels/group-messages)。 +有关 WhatsApp 专属行为（历史注入、提及处理细节），请参见 [群消息](/zh-CN/channels/group-messages)。 diff --git a/docs/zh-CN/channels/matrix.md b/docs/zh-CN/channels/matrix.md index 340bf7034..597e28c37 100644 --- a/docs/zh-CN/channels/matrix.md +++ b/docs/zh-CN/channels/matrix.md @@ -5,10 +5,10 @@ read_when: summary: Matrix 支持状态、设置和配置示例 title: Matrix x-i18n: - generated_at: "2026-04-06T03:58:04Z" + generated_at: "2026-04-06T15:30:20Z" model: gpt-5.4 provider: openai - source_hash: 06f833bf0ede81bad69f140994c32e8cc5d1635764f95fc5db4fc5dc25f2b85e + source_hash: 22d10be40bb7c2cc197f5ab4ba7c8067b67867bff477efb374b930dd79aefe8a source_path: channels/matrix.md workflow: 15 --- @@ -16,13 +16,13 @@ x-i18n: # Matrix Matrix 是 OpenClaw 的 Matrix 内置渠道插件。 -它使用官方 `matrix-js-sdk`，并支持私信、房间、线程、媒体、表情回应、投票、位置和 E2EE。 +它使用官方的 `matrix-js-sdk`，并支持私信、房间、线程、媒体、回应、投票、位置和 E2EE。 ## 内置插件 -Matrix 作为内置插件随当前 OpenClaw 版本一同发布，因此普通的打包构建不需要单独安装。 +Matrix 作为当前 OpenClaw 版本中的内置插件提供，因此常规打包构建不需要单独安装。 -如果你使用的是较旧的构建版本，或是不包含 Matrix 的自定义安装，请手动安装： +如果你使用的是较旧版本，或是不包含 Matrix 的自定义安装，请手动安装： 从 npm 安装： @@ -42,13 +42,14 @@ openclaw plugins install ./path/to/local/matrix-plugin 1. 确保 Matrix 插件可用。 - 当前打包的 OpenClaw 版本已内置它。 - - 较旧的版本或自定义安装可以使用上述命令手动添加它。 -2. 在你的 homeserver 上创建一个 Matrix 账号。 + - 旧版/自定义安装可以使用上面的命令手动添加它。 +2. 在你的 homeserver 上创建一个 Matrix 账户。 3. 使用以下任一方式配置 `channels.matrix`： - `homeserver` + `accessToken`，或 - `homeserver` + `userId` + `password`。 4. 重启 Gateway 网关。 -5. 与机器人开始一个私信，或邀请它加入一个房间。 +5. 与机器人开始一个私信，或邀请它加入房间。 + - 只有当 `channels.matrix.autoJoin` 允许时，新的 Matrix 邀请才会生效。 交互式设置路径： @@ -60,22 +61,60 @@ openclaw configure --section channels Matrix 向导实际会询问的内容： - homeserver URL -- 认证方式：access token 或 password -- 仅当你选择 password 认证时才需要 user ID -- 可选的设备名称 +- 认证方式：访问令牌或密码 +- 仅当你选择密码认证时才询问用户 ID +- 可选设备名称 - 是否启用 E2EE -- 是否现在配置 Matrix 房间访问 +- 是否立即配置 Matrix 房间访问 需要注意的向导行为： -- 如果所选账号已经存在 Matrix 认证环境变量，并且该账号尚未在配置中保存认证信息，向导会提供环境变量快捷方式，并且只为该账号写入 `enabled: true`。 -- 当你以交互方式添加另一个 Matrix 账号时，输入的账号名称会被规范化为配置和环境变量中使用的账号 ID。例如，`Ops Bot` 会变成 `ops-bot`。 -- 私信 allowlist 提示会立即接受完整的 `@user:server` 值。显示名称仅在实时目录查找找到唯一精确匹配时可用；否则向导会要求你使用完整 Matrix ID 重试。 -- 房间 allowlist 提示会直接接受房间 ID 和别名。它们也可以实时解析已加入房间的名称，但无法解析的名称只会在设置期间按原样保留，之后会被运行时 allowlist 解析忽略。优先使用 `!room:server` 或 `#alias:server`。 -- 运行时房间/会话身份使用稳定的 Matrix 房间 ID。房间声明的别名仅作为查找输入使用，不会作为长期会话键或稳定群组身份。 -- 如需在保存前解析房间名称，请使用 `openclaw channels resolve --channel matrix "Project Room"`。 +- 如果所选账户已存在 Matrix 认证环境变量，且该账户尚未在配置中保存认证信息，向导会提供一个环境变量快捷方式，并且只会为该账户写入 `enabled: true`。 +- 当你以交互方式添加另一个 Matrix 账户时，输入的账户名会被规范化为配置和环境变量中使用的账户 ID。例如，`Ops Bot` 会变成 `ops-bot`。 +- 私信允许列表提示可立即接受完整的 `@user:server` 值。显示名仅在实时目录查找找到唯一精确匹配时才有效；否则向导会要求你使用完整的 Matrix ID 重试。 +- 房间允许列表提示可直接接受房间 ID 和别名。它们也可以实时解析已加入房间的名称，但无法解析的名称只会在设置期间按原样保留，之后在运行时允许列表解析中会被忽略。优先使用 `!room:server` 或 `#alias:server`。 +- 运行时房间/会话身份使用稳定的 Matrix 房间 ID。房间声明的别名仅作为查找输入，不作为长期会话键或稳定群组身份。 +- 要在保存前解析房间名，请使用 `openclaw channels resolve --channel matrix "Project Room"`。 -基于 token 的最小设置： + +`channels.matrix.autoJoin` 默认为 `off`。 + +如果你不设置它，机器人将不会加入受邀房间或新的私信式邀请，因此除非你先手动加入，否则它不会出现在新群组或受邀私信中。 + +将 `autoJoin: "allowlist"` 与 `autoJoinAllowlist` 一起使用可以限制它接受哪些邀请，或者如果你希望它加入每一个邀请，则设置 `autoJoin: "always"`。 + + +允许列表示例： + +```json5 +{ + channels: { + matrix: { + autoJoin: "allowlist", + autoJoinAllowlist: ["!ops:example.org", "#support:example.org"], + groups: { + "!ops:example.org": { + requireMention: true, + }, + }, + }, + }, +} +``` + +加入每一个邀请： + +```json5 +{ + channels: { + matrix: { + autoJoin: "always", + }, + }, +} +``` + +基于令牌的最小化设置： ```json5 { @@ -90,7 +129,7 @@ Matrix 向导实际会询问的内容： } ``` -基于 password 的设置（登录后会缓存 token）： +基于密码的设置（登录后会缓存令牌）： ```json5 { @@ -107,8 +146,8 @@ Matrix 向导实际会询问的内容： ``` Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 -默认账号使用 `credentials.json`；命名账号使用 `credentials-.json`。 -如果该目录中存在缓存凭证，即使当前认证没有直接在配置中设置，OpenClaw 也会在 setup、Doctor 和渠道状态发现中将 Matrix 视为已配置。 +默认账户使用 `credentials.json`；命名账户使用 `credentials-.json`。 +当此处存在缓存凭证时，即使当前认证未直接在配置中设置，OpenClaw 仍会在设置、Doctor 和渠道状态发现中将 Matrix 视为已配置。 对应的环境变量（当未设置配置键时使用）： @@ -119,7 +158,7 @@ Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -对于非默认账号，请使用按账号范围划分的环境变量： +对于非默认账户，使用带账户作用域的环境变量： - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -128,24 +167,24 @@ Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 - `MATRIX__DEVICE_ID` - `MATRIX__DEVICE_NAME` -`ops` 账号示例： +账户 `ops` 的示例： - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -对于规范化账号 ID `ops-bot`，请使用： +对于规范化后的账户 ID `ops-bot`，使用： - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix 会转义账号 ID 中的标点符号，以避免带作用域的环境变量发生冲突。 -例如，`-` 会变成 `_X2D_`，因此 `ops-prod` 会映射为 `MATRIX_OPS_X2D_PROD_*`。 +Matrix 会对账户 ID 中的标点符号进行转义，以避免带作用域的环境变量发生冲突。 +例如，`-` 会变为 `_X2D_`，因此 `ops-prod` 会映射为 `MATRIX_OPS_X2D_PROD_*`。 -只有当这些认证环境变量已经存在，且所选账号尚未在配置中保存 Matrix 认证信息时，交互式向导才会提供环境变量快捷方式。 +只有当这些认证环境变量已存在，且所选账户尚未在配置中保存 Matrix 认证时，交互式向导才会提供环境变量快捷方式。 ## 配置示例 -这是一个实用的基础配置，启用了私信配对、房间 allowlist 和 E2EE： +这是一个实用的基础配置，启用了私信配对、房间允许列表和 E2EE： ```json5 { @@ -180,14 +219,16 @@ Matrix 会转义账号 ID 中的标点符号，以避免带作用域的环境变 } ``` -`autoJoin` 适用于一般意义上的 Matrix 邀请，而不仅仅是房间/群组邀请。 -这包括新的私信式邀请。在邀请时，OpenClaw 无法可靠地知道被邀请的房间最终会被视为私信还是群组，因此所有邀请都会先经过同一个 `autoJoin` 决策。机器人加入后，如果该房间被归类为私信，`dm.policy` 仍然会生效，因此 `autoJoin` 控制加入行为，而 `dm.policy` 控制回复/访问行为。 +`autoJoin` 适用于一般的 Matrix 邀请，而不仅仅是房间/群组邀请。 +这也包括新的私信式邀请。邀请发生时，OpenClaw 还无法可靠判断受邀房间最终会被视为私信还是群组，因此所有邀请都会先经过同一个 +`autoJoin` 决策。机器人加入后并且该房间被归类为私信时，`dm.policy` 仍然适用，因此 `autoJoin` 控制加入行为，而 `dm.policy` 控制回复/访问 +行为。 ## 流式预览 Matrix 回复流式传输为选择启用。 -当你希望 OpenClaw 发送一条实时预览回复、在模型生成文本时原地编辑该预览，并在回复完成后最终定稿时，请将 `channels.matrix.streaming` 设置为 `"partial"`： +当你希望 OpenClaw 发送一个实时预览回复、在模型生成文本时原地编辑该预览，并在回复完成时最终定稿，请将 `channels.matrix.streaming` 设置为 `"partial"`： ```json5 { @@ -200,34 +241,34 @@ Matrix 回复流式传输为选择启用。 ``` - `streaming: "off"` 是默认值。OpenClaw 会等待最终回复并发送一次。 -- `streaming: "partial"` 会为当前 assistant 块创建一条可编辑的预览消息，使用普通的 Matrix 文本消息。这会保留 Matrix 传统的“先预览后完成”通知行为，因此标准客户端可能会在第一次流式预览文本时通知，而不是在完成的块上通知。 -- `streaming: "quiet"` 会为当前 assistant 块创建一条可编辑的静默预览通知。只有在你同时为最终定稿的预览编辑配置接收方推送规则时，才使用此选项。 -- `blockStreaming: true` 会启用单独的 Matrix 进度消息。启用预览流式传输后，Matrix 会为当前块保留实时草稿，并将已完成的块保留为单独消息。 -- 当启用预览流式传输且 `blockStreaming` 关闭时，Matrix 会原地编辑实时草稿，并在块或轮次结束时完成同一事件。 -- 如果预览内容已无法容纳在一个 Matrix 事件中，OpenClaw 会停止预览流式传输并回退到普通最终投递。 -- 媒体回复仍会正常发送附件。如果过期的预览已无法安全复用，OpenClaw 会在发送最终媒体回复前将其清除。 -- 预览编辑会产生额外的 Matrix API 调用。如果你希望采用最保守的限流行为，请保持关闭流式传输。 +- `streaming: "partial"` 会为当前 assistant 块创建一条可编辑的预览消息，使用普通 Matrix 文本消息。这会保留 Matrix 的旧式“先预览后通知”行为，因此标准客户端可能会在第一次流式预览文本时发出通知，而不是在完成的块发出通知。 +- `streaming: "quiet"` 会为当前 assistant 块创建一条可编辑的静默预览通知。仅当你也为最终预览编辑配置了接收者推送规则时，才使用它。 +- `blockStreaming: true` 会启用独立的 Matrix 进度消息。启用预览流式传输后，Matrix 会保留当前块的实时草稿，并将已完成的块保留为单独的消息。 +- 当预览流式传输开启且 `blockStreaming` 关闭时，Matrix 会原地编辑实时草稿，并在块或整轮完成时最终定稿同一个事件。 +- 如果预览内容已无法容纳进一个 Matrix 事件，OpenClaw 会停止预览流式传输，并回退到普通最终投递。 +- 媒体回复仍会正常发送附件。如果无法再安全重用过期预览，OpenClaw 会在发送最终媒体回复前将其删除。 +- 预览编辑会增加额外的 Matrix API 调用。如果你希望采取最保守的限流行为，请保持关闭流式传输。 `blockStreaming` 本身不会启用草稿预览。 -如需预览编辑，请使用 `streaming: "partial"` 或 `streaming: "quiet"`；只有当你还希望已完成的 assistant 块以单独进度消息保留可见时，再添加 `blockStreaming: true`。 +使用 `streaming: "partial"` 或 `streaming: "quiet"` 来启用预览编辑；只有当你还希望已完成的 assistant 块作为独立进度消息保留可见时，才额外添加 `blockStreaming: true`。 -如果你需要标准 Matrix 通知而不自定义推送规则，请使用 `streaming: "partial"` 以获得先预览的行为，或保持 `streaming` 关闭以仅在最终完成时投递。对于 `streaming: "off"`： +如果你需要标准 Matrix 通知而不使用自定义推送规则，请使用 `streaming: "partial"` 以获得“先预览”行为，或保持 `streaming` 关闭以仅进行最终投递。使用 `streaming: "off"` 时： - `blockStreaming: true` 会将每个完成的块作为普通的可通知 Matrix 消息发送。 - `blockStreaming: false` 只会将最终完成的回复作为普通的可通知 Matrix 消息发送。 -### 用于静默最终预览的自托管推送规则 +### 自托管静默最终预览的推送规则 -如果你运行自己的 Matrix 基础设施，并希望静默预览仅在块或最终回复完成时通知，请设置 `streaming: "quiet"`，并为最终定稿的预览编辑添加按用户划分的推送规则。 +如果你运行自己的 Matrix 基础设施，并希望静默预览仅在块或最终回复完成时通知，请设置 `streaming: "quiet"`，并为最终预览编辑添加每用户推送规则。 -这通常是接收方用户级别的设置，而不是 homeserver 全局配置更改： +这通常是接收方用户的设置，而不是 homeserver 全局配置更改： -开始之前的快速对应关系： +开始前的快速说明： -- recipient user = 应该接收通知的人 -- bot user = 发送回复的 OpenClaw Matrix 账号 -- 对下面的 API 调用使用接收方用户的 access token -- 在推送规则中，将 `sender` 与机器人用户的完整 MXID 匹配 +- recipient user = 应该收到通知的人 +- bot user = 发送回复的 OpenClaw Matrix 账户 +- 对下面的 API 调用使用接收方用户的访问令牌 +- 在推送规则中将 `sender` 与机器人用户的完整 MXID 匹配 1. 配置 OpenClaw 使用静默预览： @@ -241,12 +282,13 @@ Matrix 回复流式传输为选择启用。 } ``` -2. 确保接收方账号已经能收到普通的 Matrix 推送通知。静默预览规则只有在该用户已经有正常工作的 pusher/设备时才会生效。 +2. 确保接收方账户已经可以接收普通 Matrix 推送通知。静默预览规则 + 只有在该用户已经有可用的 pusher/设备时才有效。 -3. 获取接收方用户的 access token。 - - 使用接收用户的 token，而不是机器人的 token。 - - 复用现有客户端会话 token 通常最简单。 - - 如果你需要签发一个新的 token，可以通过标准 Matrix Client-Server API 登录： +3. 获取接收方用户的访问令牌。 + - 使用接收消息用户的令牌，而不是机器人的令牌。 + - 复用现有客户端会话令牌通常最简单。 + - 如果你需要签发一个新的令牌，可以通过标准 Matrix Client-Server API 登录： ```bash curl -sS -X POST \ @@ -262,7 +304,7 @@ curl -sS -X POST \ }' ``` -4. 验证接收方账号是否已经有 pusher： +4. 验证接收方账户是否已经有 pusher： ```bash curl -sS \ @@ -270,9 +312,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -如果这里没有返回活动中的 pusher/设备，请先修复普通的 Matrix 通知，再添加下面的 OpenClaw 规则。 +如果这里没有返回任何活跃的 pusher/设备，请先修复普通 Matrix 通知，然后再添加下面的 +OpenClaw 规则。 -OpenClaw 会用以下标记标识最终定稿的纯文本预览编辑： +OpenClaw 会用以下标记标识已最终定稿的纯文本预览编辑： ```json { @@ -280,7 +323,7 @@ OpenClaw 会用以下标记标识最终定稿的纯文本预览编辑： } ``` -5. 为每个应接收这些通知的接收方账号创建一个 override 推送规则： +5. 为每个应接收这些通知的接收方账户创建一个 override 推送规则： ```bash curl -sS -X PUT \ @@ -310,22 +353,22 @@ curl -sS -X PUT \ }' ``` -运行该命令前，请替换以下值： +在运行命令前替换以下值： - `https://matrix.example.org`：你的 homeserver 基础 URL -- `$USER_ACCESS_TOKEN`：接收方用户的 access token -- `openclaw-finalized-preview-botname`：该接收用户针对这个机器人的唯一规则 ID -- `@bot:example.org`：你的 OpenClaw Matrix 机器人 MXID，而不是接收用户的 MXID +- `$USER_ACCESS_TOKEN`：接收消息用户的访问令牌 +- `openclaw-finalized-preview-botname`：对此接收用户和该机器人唯一的规则 ID +- `@bot:example.org`：你的 OpenClaw Matrix 机器人 MXID，不是接收方用户的 MXID 多机器人设置的重要说明： -- 推送规则以 `ruleId` 作为键。对同一个规则 ID 重复执行 `PUT` 会更新这一条规则。 -- 如果一个接收用户需要为多个 OpenClaw Matrix 机器人账号通知，请为每个机器人创建一条规则，并为每个发送者匹配使用唯一规则 ID。 +- 推送规则以 `ruleId` 为键。对同一个规则 ID 重复运行 `PUT` 会更新同一条规则。 +- 如果同一个接收用户需要对多个 OpenClaw Matrix 机器人账户发出通知，请为每个机器人创建一条独立规则，并为每个 `sender` 匹配使用唯一规则 ID。 - 一个简单的模式是 `openclaw-finalized-preview-`，例如 `openclaw-finalized-preview-ops` 或 `openclaw-finalized-preview-support`。 -该规则是针对事件发送者进行评估的： +规则是根据事件发送者进行评估的： -- 使用接收用户的 token 进行认证 +- 使用接收方用户的令牌进行认证 - 将 `sender` 与 OpenClaw 机器人 MXID 匹配 6. 验证规则已存在： @@ -336,9 +379,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. 测试一次流式回复。在静默模式下，房间中应显示一个静默草稿预览，并且在块或轮次结束时，最终的原地编辑应触发一次通知。 +7. 测试一次流式回复。在静默模式下，房间应显示一个静默草稿预览，并且当块或整轮结束时， + 最终的原地编辑应触发一次通知。 -如果你之后需要移除该规则，请使用接收用户的 token 删除同一个规则 ID： +如果之后需要移除该规则，请使用接收方用户的令牌删除同一个规则 ID： ```bash curl -sS -X DELETE \ @@ -348,37 +392,37 @@ curl -sS -X DELETE \ 说明： -- 使用接收用户的 access token 创建规则，而不是机器人的。 -- 新的用户定义 `override` 规则会插入到默认抑制规则之前，因此不需要额外的排序参数。 -- 这只影响 OpenClaw 能够安全原地定稿的纯文本预览编辑。媒体回退和过期预览回退仍然使用普通 Matrix 投递。 -- 如果 `GET /_matrix/client/v3/pushers` 显示没有 pusher，说明该用户尚未为此账号/设备配置正常工作的 Matrix 推送投递。 +- 请使用接收方用户的访问令牌创建规则，而不是机器人的。 +- 新的用户自定义 `override` 规则会插入到默认抑制规则之前，因此不需要额外的排序参数。 +- 这只影响 OpenClaw 能够安全原地定稿的纯文本预览编辑。媒体回退和过期预览回退仍使用普通 Matrix 投递方式。 +- 如果 `GET /_matrix/client/v3/pushers` 显示没有 pusher，说明该用户在这个账户/设备上尚未启用可用的 Matrix 推送投递。 #### Synapse -对于 Synapse，通常只需完成上述设置即可： +对于 Synapse，上述设置通常本身就足够： -- 最终定稿的 OpenClaw 预览通知不需要特殊的 `homeserver.yaml` 更改。 -- 如果你的 Synapse 部署已经能发送普通的 Matrix 推送通知，那么用户 token + 上述 `pushrules` 调用就是主要设置步骤。 -- 如果你在反向代理或 worker 后运行 Synapse，请确保 `/_matrix/client/.../pushrules/` 能正确到达 Synapse。 -- 如果你使用 Synapse workers，请确保 pusher 状态正常。推送投递由主进程或 `synapse.app.pusher` / 已配置的 pusher workers 处理。 +- 不需要为最终的 OpenClaw 预览通知进行特殊的 `homeserver.yaml` 更改。 +- 如果你的 Synapse 部署已经能发送普通 Matrix 推送通知，那么用户令牌 + 上面的 `pushrules` 调用就是主要设置步骤。 +- 如果你在反向代理或 workers 后运行 Synapse，请确保 `/_matrix/client/.../pushrules/` 能正确到达 Synapse。 +- 如果你运行 Synapse workers，请确保 pusher 状态健康。推送投递由主进程或 `synapse.app.pusher` / 已配置的 pusher workers 处理。 #### Tuwunel -对于 Tuwunel，请使用与上方相同的设置流程和 push-rule API 调用： +对于 Tuwunel，使用与上面相同的设置流程和 push-rule API 调用： - 最终预览标记本身不需要任何 Tuwunel 特定配置。 -- 如果该用户的普通 Matrix 通知已经正常工作，那么用户 token + 上述 `pushrules` 调用就是主要设置步骤。 -- 如果当用户在其他设备上活跃时通知似乎消失了，请检查是否启用了 `suppress_push_when_active`。Tuwunel 在 2025 年 9 月 12 日发布的 Tuwunel 1.4.2 中添加了此选项，它可能会有意抑制向其他设备发送推送。 +- 如果该用户的普通 Matrix 通知已经正常工作，那么用户令牌 + 上面的 `pushrules` 调用就是主要设置步骤。 +- 如果用户在另一台设备上处于活跃状态时通知似乎消失，请检查是否启用了 `suppress_push_when_active`。Tuwunel 在 2025 年 9 月 12 日发布的 Tuwunel 1.4.2 中加入了此选项，它可能会在某一设备活跃时有意抑制向其他设备发送推送。 ## 加密和验证 -在加密（E2EE）房间中，出站图片事件会使用 `thumbnail_file`，因此图片预览会与完整附件一起加密。未加密房间仍使用普通的 `thumbnail_url`。无需配置——插件会自动检测 E2EE 状态。 +在加密的（E2EE）房间中，出站图像事件使用 `thumbnail_file`，因此图像预览会与完整附件一起加密。未加密房间仍使用普通的 `thumbnail_url`。无需配置——插件会自动检测 E2EE 状态。 -### Bot 到 Bot 房间 +### 机器人到机器人房间 -默认情况下，来自其他已配置 OpenClaw Matrix 账号的 Matrix 消息会被忽略。 +默认情况下，来自其他已配置 OpenClaw Matrix 账户的 Matrix 消息会被忽略。 -当你确实希望启用智能体之间的 Matrix 流量时，请使用 `allowBots`： +当你明确希望启用智能体之间的 Matrix 通信时，使用 `allowBots`： ```json5 { @@ -395,13 +439,13 @@ curl -sS -X DELETE \ } ``` -- `allowBots: true` 接受来自其他已配置 Matrix 机器人账号、且位于允许房间和私信中的消息。 -- `allowBots: "mentions"` 仅当这些消息在房间中明确提及此机器人时才接受。私信仍然允许。 -- `groups..allowBots` 会覆盖某个房间的账号级设置。 +- `allowBots: true` 会在允许的房间和私信中接受来自其他已配置 Matrix 机器人账户的消息。 +- `allowBots: "mentions"` 仅在这些消息在房间中明确提及此机器人时接受它们。私信仍然允许。 +- `groups..allowBots` 会覆盖该房间的账户级设置。 - OpenClaw 仍会忽略来自同一 Matrix 用户 ID 的消息，以避免自回复循环。 -- Matrix 在这里不提供原生 bot 标志；OpenClaw 将“由机器人撰写”视为“由此 OpenClaw Gateway 网关上另一个已配置的 Matrix 账号发送”。 +- Matrix 在这里不提供原生机器人标志；OpenClaw 将“机器人发送”视为“由此 OpenClaw Gateway 网关上另一个已配置 Matrix 账户发送”。 -当你在共享房间中启用 bot 到 bot 流量时，请使用严格的房间 allowlist 和提及要求。 +在共享房间中启用机器人到机器人流量时，请使用严格的房间允许列表和提及要求。 启用加密： @@ -431,27 +475,27 @@ openclaw matrix verify status openclaw matrix verify status --verbose ``` -在机器可读输出中包含存储的恢复密钥： +在机器可读输出中包含已存储的恢复密钥： ```bash openclaw matrix verify status --include-recovery-key --json ``` -引导交叉签名和验证状态： +初始化 cross-signing 和验证状态： ```bash openclaw matrix verify bootstrap ``` -多账号支持：使用 `channels.matrix.accounts` 配置每个账号的凭证和可选 `name`。共享模式请参阅 [配置参考](/zh-CN/gateway/configuration-reference#multi-account-all-channels)。 +多账户支持：使用 `channels.matrix.accounts` 配置每个账户的凭证和可选 `name`。共享模式请参见 [配置参考](/zh-CN/gateway/configuration-reference#multi-account-all-channels)。 -详细引导诊断： +详细 bootstrap 诊断： ```bash openclaw matrix verify bootstrap --verbose ``` -在引导前强制重置全新的交叉签名身份： +在 bootstrap 前强制重置一个新的 cross-signing 身份： ```bash openclaw matrix verify bootstrap --force-reset-cross-signing @@ -493,18 +537,19 @@ openclaw matrix verify backup restore openclaw matrix verify backup restore --verbose ``` -删除当前服务器备份并创建一个全新的备份基线。如果存储的备份密钥无法被干净地加载，此重置也可以重新创建 secret storage，以便未来冷启动时可以加载新的备份密钥： +删除当前服务器备份并创建新的备份基线。如果无法干净地加载已存储的 +备份密钥，此重置也可以重新创建秘密存储，以便未来冷启动时能够加载新的备份密钥： ```bash openclaw matrix verify backup reset --yes ``` -所有 `verify` 命令默认都保持简洁（包括安静的内部 SDK 日志），只有使用 `--verbose` 时才显示详细诊断。 +所有 `verify` 命令默认都很简洁（包括安静的内部 SDK 日志），只有使用 `--verbose` 才会显示详细诊断。 编写脚本时请使用 `--json` 获取完整的机器可读输出。 -在多账号设置中，除非你传入 `--account `，否则 Matrix CLI 命令会使用隐式的 Matrix 默认账号。 -如果你配置了多个命名账号，请先设置 `channels.matrix.defaultAccount`，否则这些隐式 CLI 操作会停止并要求你显式选择一个账号。 -每当你希望验证或设备操作明确针对某个命名账号时，请使用 `--account`： +在多账户设置中，Matrix CLI 命令会使用隐式的 Matrix 默认账户，除非你传入 `--account `。 +如果你配置了多个命名账户，请先设置 `channels.matrix.defaultAccount`，否则这些隐式 CLI 操作会停止并要求你显式选择一个账户。 +当你希望验证或设备操作显式定位到某个命名账户时，请使用 `--account`： ```bash openclaw matrix verify status --account assistant @@ -512,40 +557,42 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -当某个命名账号未启用加密或无法使用加密时，Matrix 警告和验证错误会指向该账号的配置键，例如 `channels.matrix.accounts.assistant.encryption`。 +当某个命名账户的加密被禁用或不可用时，Matrix 警告和验证错误会指向该账户的配置键，例如 `channels.matrix.accounts.assistant.encryption`。 ### “已验证” 的含义 -只有当这个 Matrix 设备被你自己的交叉签名身份验证时，OpenClaw 才会将其视为已验证。 -实际中，`openclaw matrix verify status --verbose` 会显示三个信任信号： +只有当这个 Matrix 设备被你自己的 cross-signing 身份验证后，OpenClaw 才会将其视为已验证。 +实际上，`openclaw matrix verify status --verbose` 会暴露三个信任信号： - `Locally trusted`：此设备仅被当前客户端信任 -- `Cross-signing verified`：SDK 报告该设备已通过交叉签名验证 -- `Signed by owner`：该设备由你自己的 self-signing 密钥签名 +- `Cross-signing verified`：SDK 报告该设备已通过 cross-signing 验证 +- `Signed by owner`：该设备已由你自己的 self-signing 密钥签名 -只有存在交叉签名验证或 owner-signing 时，`Verified by owner` 才会变为 `yes`。 -仅有本地信任并不足以让 OpenClaw 将设备视为完全已验证。 +只有存在 cross-signing 验证或 owner-signing 时，`Verified by owner` 才会变为 `yes`。 +仅有本地信任不足以让 OpenClaw 将该设备视为完全已验证。 -### bootstrap 会做什么 +### bootstrap 的作用 -`openclaw matrix verify bootstrap` 是用于修复和设置加密 Matrix 账号的命令。 +`openclaw matrix verify bootstrap` 是加密 Matrix 账户的修复和设置命令。 它会按顺序完成以下所有操作： -- 引导 secret storage，尽可能复用现有恢复密钥 -- 引导交叉签名并上传缺失的公开交叉签名密钥 -- 尝试标记并交叉签名当前设备 -- 如果服务器端房间密钥备份不存在，则创建一个新的备份 +- 初始化秘密存储，并尽可能复用现有恢复密钥 +- 初始化 cross-signing 并上传缺失的公共 cross-signing 密钥 +- 尝试标记并 cross-sign 当前设备 +- 如果尚不存在，则创建新的服务端房间密钥备份 -如果 homeserver 要求交互式认证才能上传交叉签名密钥，OpenClaw 会先尝试无认证上传，然后尝试使用 `m.login.dummy`，如果配置了 `channels.matrix.password`，则再尝试使用 `m.login.password`。 +如果 homeserver 需要交互式认证以上传 cross-signing 密钥，OpenClaw 会先尝试不带认证上传，然后尝试 `m.login.dummy`，若已配置 `channels.matrix.password`，再尝试 `m.login.password`。 -只有当你明确希望丢弃当前交叉签名身份并创建新身份时，才使用 `--force-reset-cross-signing`。 +仅在你明确希望丢弃当前 cross-signing 身份并创建新身份时，才使用 `--force-reset-cross-signing`。 -如果你明确希望丢弃当前房间密钥备份，并为未来消息开始一个新的备份基线，请使用 `openclaw matrix verify backup reset --yes`。 -仅当你接受无法恢复的旧加密历史将继续不可用，并且 OpenClaw 在当前备份密钥无法安全加载时可能会重新创建 secret storage 时，才这样做。 +如果你明确希望丢弃当前房间密钥备份，并为未来消息启动新的 +备份基线，请使用 `openclaw matrix verify backup reset --yes`。 +只有在你接受无法恢复的旧加密历史将继续不可用，并且 OpenClaw 可能会在当前备份 +秘密无法安全加载时重新创建秘密存储的情况下，才这样做。 ### 全新备份基线 -如果你希望保持未来加密消息正常工作，并接受失去无法恢复的旧历史，请按顺序运行以下命令： +如果你希望保持未来的加密消息可用，并接受丢失无法恢复的旧历史，请按顺序运行以下命令： ```bash openclaw matrix verify backup reset --yes @@ -553,103 +600,107 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -当你希望明确针对某个命名 Matrix 账号时，请为每条命令添加 `--account `。 +如果你希望显式指定某个命名 Matrix 账户，请在每条命令后添加 `--account `。 ### 启动行为 当 `encryption: true` 时，Matrix 默认将 `startupVerification` 设为 `"if-unverified"`。 -启动时，如果该设备仍未验证，Matrix 会在另一个 Matrix 客户端中请求自我验证；如果已有一个请求处于待处理状态，则跳过重复请求；并在重启后重试前应用本地冷却时间。 -默认情况下，失败的请求创建尝试会比成功创建请求后的重试更早再次尝试。 -如果要禁用自动启动请求，请将 `startupVerification: "off"`；如果你希望重试窗口更短或更长，请调整 `startupVerificationCooldownHours`。 +启动时，如果此设备仍未验证，Matrix 会在另一个 Matrix 客户端中请求自我验证， +在已有待处理请求时跳过重复请求，并在重启后重试前应用本地冷却时间。 +默认情况下，失败的请求创建尝试会比成功创建请求的重试更快。 +将 `startupVerification: "off"` 设为禁用自动启动请求，或者调整 `startupVerificationCooldownHours` +以获得更短或更长的重试窗口。 -启动时也会自动执行一次保守的加密引导流程。 -该流程会优先尝试复用当前的 secret storage 和交叉签名身份，并避免重置交叉签名，除非你运行显式的引导修复流程。 +启动时还会自动执行一次保守的加密 bootstrap 检查。 +该过程会优先尝试复用当前的秘密存储和 cross-signing 身份，并避免重置 cross-signing，除非你运行显式的 bootstrap 修复流程。 -如果启动时发现引导状态损坏，并且已配置 `channels.matrix.password`，OpenClaw 可以尝试更严格的修复路径。 -如果当前设备已经由 owner 签名，OpenClaw 会保留该身份，而不是自动重置它。 +如果启动时发现 bootstrap 状态损坏且已配置 `channels.matrix.password`，OpenClaw 可以尝试更严格的修复路径。 +如果当前设备已由所有者签名，OpenClaw 会保留该身份，而不会自动重置它。 -从上一版公开 Matrix 插件升级时： +从之前公开的 Matrix 插件升级时： -- OpenClaw 会在可能的情况下自动复用相同的 Matrix 账号、access token 和设备身份。 -- 在运行任何可执行的 Matrix 迁移更改之前，OpenClaw 会在 `~/Backups/openclaw-migrations/` 下创建或复用一个恢复快照。 -- 如果你使用多个 Matrix 账号，请在从旧的平面存储布局升级前设置 `channels.matrix.defaultAccount`，这样 OpenClaw 才知道哪个账号应接收该共享旧状态。 -- 如果先前的插件在本地存储了 Matrix 房间密钥备份解密密钥，启动或 `openclaw doctor --fix` 现在会自动将其导入新的恢复密钥流程。 -- 如果在准备迁移之后 Matrix access token 发生变化，启动现在会在放弃自动备份恢复前扫描同级 token-hash 存储根，以查找待恢复的旧状态。 -- 如果之后相同账号、homeserver 和用户的 Matrix access token 再次变化，OpenClaw 现在会优先复用最完整的现有 token-hash 存储根，而不是从空的 Matrix 状态目录开始。 +- OpenClaw 会在可能的情况下自动复用同一个 Matrix 账户、访问令牌和设备身份。 +- 在执行任何实际 Matrix 迁移更改前，OpenClaw 会在 `~/Backups/openclaw-migrations/` 下创建或复用恢复快照。 +- 如果你使用多个 Matrix 账户，请在从旧的平面存储布局升级前设置 `channels.matrix.defaultAccount`，以便 OpenClaw 知道哪个账户应接收该共享旧状态。 +- 如果之前的插件在本地存储了 Matrix 房间密钥备份解密密钥，启动或 `openclaw doctor --fix` 会自动将其导入新的恢复密钥流程。 +- 如果在迁移准备完成后 Matrix 访问令牌发生变化，启动现在会在放弃自动备份恢复之前扫描同级 token-hash 存储根目录以查找待恢复的旧状态。 +- 如果同一账户、homeserver 和用户之后再次更改 Matrix 访问令牌，OpenClaw 现在会优先复用最完整的现有 token-hash 存储根目录，而不是从空的 Matrix 状态目录开始。 - 在下一次 Gateway 网关启动时，已备份的房间密钥会自动恢复到新的加密存储中。 -- 如果旧插件存在从未备份的仅本地房间密钥，OpenClaw 会清楚地发出警告。这些密钥无法从之前的 rust crypto store 自动导出，因此某些旧的加密历史可能仍不可用，直到手动恢复为止。 -- 完整升级流程、限制、恢复命令和常见迁移消息，请参阅 [Matrix 迁移](/zh-CN/install/migrating-matrix)。 +- 如果旧插件存在从未备份的本地房间密钥，OpenClaw 会明确发出警告。这些密钥无法从之前的 rust crypto store 自动导出，因此某些旧加密历史可能在手动恢复前仍然不可用。 +- 完整升级流程、限制、恢复命令和常见迁移消息，请参见 [Matrix 迁移](/zh-CN/install/migrating-matrix)。 -加密运行时状态按每个账号、每个用户的 token-hash 根组织，位于 -`~/.openclaw/matrix/accounts//__//`。 -该目录会包含同步存储（`bot-storage.json`）、加密存储（`crypto/`）、 +加密的运行时状态按每账户、每用户 token-hash 根目录组织，位于 +`~/.openclaw/matrix/accounts//__//` 中。 +该目录包含同步存储（`bot-storage.json`）、加密存储（`crypto/`）、 恢复密钥文件（`recovery-key.json`）、IndexedDB 快照（`crypto-idb-snapshot.json`）、 -线程绑定（`thread-bindings.json`）和启动验证状态（`startup-verification.json`）， -前提是这些功能正在使用中。 -当 token 改变但账号身份保持不变时，OpenClaw 会为该账号/homeserver/用户元组复用最佳的现有根目录，因此之前的同步状态、加密状态、线程绑定和启动验证状态仍然可见。 +线程绑定（`thread-bindings.json`）以及启动验证状态（`startup-verification.json`）， +当这些功能被使用时都会存在。 +当令牌发生变化但账户身份保持不变时，OpenClaw 会为该 account/homeserver/user 元组复用最佳现有 +根目录，因此先前的同步状态、加密状态、线程绑定 +和启动验证状态仍然可见。 ### Node 加密存储模型 -此插件中的 Matrix E2EE 在 Node 中使用官方 `matrix-js-sdk` Rust 加密路径。 -当你希望加密状态在重启后仍然存在时，这一路径需要基于 IndexedDB 的持久化。 +此插件中的 Matrix E2EE 在 Node 中使用官方 `matrix-js-sdk` 的 Rust 加密路径。 +当你希望加密状态在重启后仍然保留时，该路径需要基于 IndexedDB 的持久化。 OpenClaw 当前在 Node 中通过以下方式提供这一能力： - 使用 `fake-indexeddb` 作为 SDK 期望的 IndexedDB API shim -- 在 `initRustCrypto` 之前，从 `crypto-idb-snapshot.json` 恢复 Rust 加密 IndexedDB 内容 -- 在初始化后和运行期间，将更新后的 IndexedDB 内容持久化回 `crypto-idb-snapshot.json` -- 使用建议性文件锁针对 `crypto-idb-snapshot.json` 串行化快照恢复和持久化，以避免 Gateway 网关运行时持久化与 CLI 维护在同一个快照文件上发生竞争 +- 在 `initRustCrypto` 之前从 `crypto-idb-snapshot.json` 恢复 Rust 加密 IndexedDB 内容 +- 在初始化后和运行时，将更新后的 IndexedDB 内容持久化回 `crypto-idb-snapshot.json` +- 通过建议性文件锁，将针对 `crypto-idb-snapshot.json` 的快照恢复与持久化串行化，以避免 Gateway 网关运行时持久化与 CLI 维护在同一个快照文件上发生竞争 -这是兼容性/存储层面的处理，不是自定义加密实现。 -该快照文件属于敏感运行时状态，并使用严格的文件权限存储。 -根据 OpenClaw 的安全模型，Gateway 网关主机和本地 OpenClaw 状态目录已处于受信任的操作员边界内，因此这主要是运行持久性问题，而不是独立的远程信任边界问题。 +这是兼容性/存储层处理，不是自定义加密实现。 +该快照文件属于敏感运行时状态，并以严格文件权限存储。 +按照 OpenClaw 的安全模型，Gateway 网关主机和本地 OpenClaw 状态目录已经处于受信任的操作员边界内，因此这主要是运行可靠性问题，而不是独立的远程信任边界。 计划中的改进： -- 为持久化 Matrix 密钥材料添加 SecretRef 支持，以便恢复密钥和相关的存储加密密钥可以从 OpenClaw secrets provider 获取，而不仅限于本地文件 +- 为持久化 Matrix 密钥材料增加 SecretRef 支持，这样恢复密钥和相关的存储加密秘密就可以来自 OpenClaw secrets 提供商，而不只是本地文件 -## 配置文件管理 +## 资料管理 -使用以下命令为所选账号更新 Matrix 自身资料： +使用以下命令为所选账户更新 Matrix 自身资料： ```bash openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -当你希望明确针对某个命名 Matrix 账号时，请添加 `--account `。 +如果你希望显式指定某个命名 Matrix 账户，请添加 `--account `。 -Matrix 可直接接受 `mxc://` 头像 URL。当你传入 `http://` 或 `https://` 头像 URL 时，OpenClaw 会先将其上传到 Matrix，然后将解析得到的 `mxc://` URL 存回 `channels.matrix.avatarUrl`（或所选账号的覆盖项）。 +Matrix 可直接接受 `mxc://` 头像 URL。当你传入 `http://` 或 `https://` 头像 URL 时，OpenClaw 会先将其上传到 Matrix，然后将解析后的 `mxc://` URL 回写到 `channels.matrix.avatarUrl`（或所选账户覆盖项）中。 ## 自动验证通知 -Matrix 现在会将验证生命周期通知直接作为 `m.notice` 消息发布到严格的私信验证房间中。 -这包括： +Matrix 现在会将验证生命周期通知直接发布到严格的私信验证房间中，作为 `m.notice` 消息。 +包括： - 验证请求通知 -- 验证就绪通知（带有明确的“通过表情符号验证”指导） +- 验证就绪通知（附带明确的“通过表情符号验证”指引） - 验证开始和完成通知 -- 可用时的 SAS 详情（表情符号和十进制数字） +- SAS 详细信息（表情符号和十进制），如果可用 来自另一个 Matrix 客户端的传入验证请求会被 OpenClaw 跟踪并自动接受。 -对于自我验证流程，OpenClaw 还会在表情符号验证可用时自动启动 SAS 流程，并确认自己这一侧。 +对于自我验证流程，当表情符号验证可用时，OpenClaw 也会自动启动 SAS 流程并确认自身这一侧。 对于来自另一个 Matrix 用户/设备的验证请求，OpenClaw 会自动接受请求，然后等待 SAS 流程正常继续。 -你仍然需要在你的 Matrix 客户端中比较表情符号或十进制 SAS，并在那里确认“它们匹配”，以完成验证。 +你仍然需要在你的 Matrix 客户端中比较表情符号或十进制 SAS，并在那里确认“它们匹配”，才能完成验证。 -OpenClaw 不会盲目自动接受自发起的重复流程。当自我验证请求已经处于待处理状态时，启动过程会跳过创建新请求。 +OpenClaw 不会盲目自动接受自发起的重复流程。如果已经有一个待处理的自我验证请求，启动时会跳过创建新请求。 -验证协议/系统通知不会转发到智能体聊天管道，因此不会产生 `NO_REPLY`。 +验证协议/系统通知不会转发到智能体聊天流水线，因此不会产生 `NO_REPLY`。 ### 设备清理 -由 OpenClaw 管理的旧 Matrix 设备可能会在账号中逐渐积累，使加密房间信任更难判断。 +旧的 OpenClaw 管理的 Matrix 设备可能会在账户中累积，并使加密房间信任更难判断。 使用以下命令列出它们： ```bash openclaw matrix devices list ``` -使用以下命令移除过时的 OpenClaw 管理设备： +使用以下命令移除过期的 OpenClaw 管理设备： ```bash openclaw matrix devices prune-stale @@ -657,65 +708,65 @@ openclaw matrix devices prune-stale ### 直接房间修复 -如果私信状态不同步，OpenClaw 最终可能会保留过时的 `m.direct` 映射，使其指向旧的单人房间，而不是当前正在使用的私信。使用以下命令检查某个对等方的当前映射： +如果直接消息状态不同步，OpenClaw 可能会出现指向旧单人房间而不是当前私信的过期 `m.direct` 映射。使用以下命令检查某个对端的当前映射： ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -使用以下命令修复它： +使用以下命令修复： ```bash openclaw matrix direct repair --user-id @alice:example.org ``` -修复会将 Matrix 特有逻辑保留在插件内部： +修复会将 Matrix 特定逻辑保留在插件内部： -- 它优先选择已经在 `m.direct` 中映射的严格 1:1 私信 -- 否则会回退到当前已加入的、与该用户之间任意严格 1:1 私信 -- 如果不存在健康的私信，它会创建一个新的直接房间，并重写 `m.direct` 使其指向该房间 +- 它会优先选择一个已映射在 `m.direct` 中的严格 1:1 私信 +- 否则会回退到与该用户当前已加入的任意严格 1:1 私信 +- 如果不存在健康的私信，它会创建一个新的直连房间，并重写 `m.direct` 指向它 -修复流程不会自动删除旧房间。它只会选择健康的私信并更新映射，以便新的 Matrix 发送、验证通知和其他直接消息流程再次指向正确的房间。 +修复流程不会自动删除旧房间。它只会选择健康的私信并更新映射，使新的 Matrix 发送、验证通知和其他直接消息流程重新定位到正确的房间。 ## 线程 -Matrix 同时支持用于自动回复和消息工具发送的原生 Matrix 线程。 +Matrix 支持原生 Matrix 线程，可用于自动回复和 message-tool 发送。 -- `dm.sessionScope: "per-user"`（默认）会保持 Matrix 私信路由以发送者为作用域，因此多个私信房间在解析到同一对等方时可以共享一个会话。 -- `dm.sessionScope: "per-room"` 会将每个 Matrix 私信房间隔离到各自独立的会话键中，同时仍使用普通私信认证和 allowlist 检查。 -- 显式 Matrix 对话绑定仍然优先于 `dm.sessionScope`，因此已绑定的房间和线程会保留其所选目标会话。 -- `threadReplies: "off"` 会保持回复在顶层，并让传入的线程消息继续使用父级会话。 -- `threadReplies: "inbound"` 仅当传入消息已处于该线程中时，才在线程中回复。 -- `threadReplies: "always"` 会让房间回复保持在线程中，以触发消息为根，并从第一条触发消息开始，通过匹配的线程范围会话路由该对话。 -- `dm.threadReplies` 仅覆盖私信的顶层设置。例如，你可以保持房间线程隔离，同时让私信保持扁平。 -- 传入的线程消息会将线程根消息作为额外智能体上下文包含进来。 -- 现在，如果目标是同一房间或同一私信用户目标，消息工具发送会自动继承当前 Matrix 线程，除非显式提供了 `threadId`。 -- 只有当当前会话元数据能够证明是同一个 Matrix 账号上的同一个私信对等方时，相同会话的私信用户目标复用才会生效；否则 OpenClaw 会回退到普通的用户范围路由。 -- 当 OpenClaw 发现某个 Matrix 私信房间与同一共享 Matrix 私信会话上的另一个私信房间发生冲突时，如果启用了线程绑定并存在 `dm.sessionScope` 提示，它会在该房间中发布一次性 `m.notice`，提示使用 `/focus` 作为逃生口。 -- Matrix 支持运行时线程绑定。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 和线程绑定的 `/acp spawn` 现在都可在 Matrix 房间和私信中使用。 +- `dm.sessionScope: "per-user"`（默认）会让 Matrix 私信路由保持按发送者划分，因此多个私信房间在解析到同一对端时可共享一个会话。 +- `dm.sessionScope: "per-room"` 会将每个 Matrix 私信房间隔离为独立会话键，同时仍使用普通私信认证和允许列表检查。 +- 显式 Matrix 会话绑定仍然优先生效，因此已绑定的房间和线程会保留其选定的目标会话。 +- `threadReplies: "off"` 会将回复保持在顶层，并让传入线程消息落在父会话上。 +- `threadReplies: "inbound"` 仅当传入消息已经在该线程中时，才在线程内回复。 +- `threadReplies: "always"` 会将房间回复保持在线程中，该线程以触发消息为根，并从第一条触发消息起，通过匹配的线程作用域会话路由该对话。 +- `dm.threadReplies` 仅覆盖私信的顶层设置。例如，你可以让房间线程保持隔离，而让私信保持扁平。 +- 传入线程消息会将线程根消息作为额外的智能体上下文包含进来。 +- 当目标是同一个房间或相同的私信用户目标时，message-tool 发送现在会自动继承当前 Matrix 线程，除非显式提供了 `threadId`。 +- 仅当当前会话元数据能证明是同一 Matrix 账户上的同一个私信对端时，才会复用同会话私信用户目标；否则 OpenClaw 会回退到普通的用户作用域路由。 +- 当 OpenClaw 发现某个 Matrix 私信房间与同一共享 Matrix 私信会话上的另一个私信房间冲突时，如果启用了线程绑定并且存在 `dm.sessionScope` 提示，它会在该房间中发布一次性的 `m.notice`，附带 `/focus` 逃生方式说明。 +- Matrix 支持运行时线程绑定。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及线程绑定的 `/acp spawn` 现在都可在 Matrix 房间和私信中使用。 - 当 `threadBindings.spawnSubagentSessions=true` 时，顶层 Matrix 房间/私信中的 `/focus` 会创建一个新的 Matrix 线程，并将其绑定到目标会话。 -- 在现有 Matrix 线程中运行 `/focus` 或 `/acp spawn --thread here` 时，则会改为绑定当前线程。 +- 在现有 Matrix 线程内运行 `/focus` 或 `/acp spawn --thread here` 时，则会绑定当前线程本身。 -## ACP 对话绑定 +## ACP 会话绑定 -Matrix 房间、私信和现有 Matrix 线程都可以被转换为持久的 ACP 工作区，而无需改变聊天界面。 +Matrix 房间、私信和现有 Matrix 线程都可以转变为持久的 ACP 工作区，而无需更改聊天界面。 -快速操作流程： +面向操作员的快速流程： - 在你想继续使用的 Matrix 私信、房间或现有线程中运行 `/acp spawn codex --bind here`。 -- 在顶层 Matrix 私信或房间中，当前私信/房间会继续作为聊天界面，未来的消息会路由到新生成的 ACP 会话。 -- 在现有 Matrix 线程内，`--bind here` 会将当前线程原地绑定。 -- `/new` 和 `/reset` 会原地重置同一个已绑定 ACP 会话。 +- 在顶层 Matrix 私信或房间中，当前私信/房间会保持为聊天界面，后续消息会路由到新建的 ACP 会话。 +- 在现有 Matrix 线程中，`--bind here` 会就地绑定当前线程。 +- `/new` 和 `/reset` 会就地重置同一个已绑定 ACP 会话。 - `/acp close` 会关闭 ACP 会话并移除绑定。 说明： - `--bind here` 不会创建子 Matrix 线程。 -- 仅当使用 `/acp spawn --thread auto|here` 且 OpenClaw 需要创建或绑定子 Matrix 线程时，才需要 `threadBindings.spawnAcpSessions`。 +- `threadBindings.spawnAcpSessions` 仅在 `/acp spawn --thread auto|here` 时需要，此时 OpenClaw 需要创建或绑定一个子 Matrix 线程。 ### 线程绑定配置 -Matrix 会继承 `session.threadBindings` 的全局默认值，也支持按渠道覆盖： +Matrix 会继承来自 `session.threadBindings` 的全局默认值，同时也支持按渠道覆盖： - `threadBindings.enabled` - `threadBindings.idleHours` @@ -728,30 +779,30 @@ Matrix 线程绑定的 spawn 标志为选择启用： - 设置 `threadBindings.spawnSubagentSessions: true` 以允许顶层 `/focus` 创建并绑定新的 Matrix 线程。 - 设置 `threadBindings.spawnAcpSessions: true` 以允许 `/acp spawn --thread auto|here` 将 ACP 会话绑定到 Matrix 线程。 -## 表情回应 +## 回应 -Matrix 支持出站表情回应操作、传入表情回应通知以及传入 ack 表情回应。 +Matrix 支持出站回应操作、传入回应通知以及传入 ack 回应。 -- 出站表情回应工具由 `channels["matrix"].actions.reactions` 控制。 -- `react` 会向特定 Matrix 事件添加一个表情回应。 -- `reactions` 会列出特定 Matrix 事件当前的表情回应摘要。 -- `emoji=""` 会移除机器人账号在该事件上的所有自身表情回应。 -- `remove: true` 只会移除机器人账号对该表情的回应。 +- 出站回应工具受 `channels["matrix"].actions.reactions` 控制。 +- `react` 会向特定 Matrix 事件添加一个回应。 +- `reactions` 会列出特定 Matrix 事件当前的回应汇总。 +- `emoji=""` 会移除机器人账户在该事件上的自身回应。 +- `remove: true` 只会移除机器人账户的指定 emoji 回应。 -Ack 表情回应按标准 OpenClaw 解析顺序处理： +Ack 回应使用标准 OpenClaw 解析顺序： - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` - 智能体身份 emoji 回退值 -Ack 表情回应作用域按以下顺序解析： +Ack 回应作用域按以下顺序解析： - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -表情回应通知模式按以下顺序解析： +回应通知模式按以下顺序解析： - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` @@ -759,29 +810,29 @@ Ack 表情回应作用域按以下顺序解析： 当前行为： -- `reactionNotifications: "own"` 会在 `m.reaction` 事件指向机器人撰写的 Matrix 消息时转发表情回应新增事件。 -- `reactionNotifications: "off"` 会禁用表情回应系统事件。 -- 表情回应移除仍不会被合成为系统事件，因为 Matrix 将其作为 redaction 呈现，而不是独立的 `m.reaction` 移除事件。 +- `reactionNotifications: "own"` 会在目标是机器人创建的 Matrix 消息时，转发新增的 `m.reaction` 事件。 +- `reactionNotifications: "off"` 会禁用回应系统事件。 +- 回应移除目前仍不会被合成为系统事件，因为 Matrix 将它们作为 redaction 暴露，而不是作为独立的 `m.reaction` 移除事件。 ## 历史上下文 -- `channels.matrix.historyLimit` 控制当 Matrix 房间消息触发智能体时，作为 `InboundHistory` 包含多少最近房间消息。 -- 它会回退到 `messages.groupChat.historyLimit`。如果两者都未设置，则有效默认值为 `0`，因此带提及门控的房间消息不会被缓冲。设置为 `0` 可禁用。 -- Matrix 房间历史仅限房间。私信仍使用普通会话历史。 -- Matrix 房间历史是待处理专用：OpenClaw 会缓冲尚未触发回复的房间消息，然后在提及或其他触发到来时快照该窗口。 -- 当前触发消息不会包含在 `InboundHistory` 中；它会保留在该轮次的主传入正文中。 -- 对同一个 Matrix 事件的重试会复用原始历史快照，而不会向前漂移到更新的房间消息。 +- `channels.matrix.historyLimit` 控制当 Matrix 房间消息触发智能体时，有多少最近的房间消息会作为 `InboundHistory` 包含进来。 +- 它会回退到 `messages.groupChat.historyLimit`。如果两者都未设置，则实际默认值为 `0`，因此受提及门控的房间消息不会被缓冲。设置为 `0` 可禁用。 +- Matrix 房间历史仅限房间。私信仍然使用普通会话历史。 +- Matrix 房间历史是仅待处理的：OpenClaw 会缓冲尚未触发回复的房间消息，然后在收到提及或其他触发时对该窗口进行快照。 +- 当前触发消息不会包含在 `InboundHistory` 中；它会保留在该轮的主传入正文中。 +- 对同一个 Matrix 事件的重试会复用原始历史快照，而不会向前漂移到较新的房间消息。 ## 上下文可见性 -Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文，例如已获取的回复文本、线程根和待处理历史。 +Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文，例如获取到的回复文本、线程根和待处理历史。 -- `contextVisibility: "all"` 是默认值。补充上下文会按接收到的内容保留。 -- `contextVisibility: "allowlist"` 会根据活动中的房间/用户 allowlist 检查，过滤补充上下文中的发送者。 -- `contextVisibility: "allowlist_quote"` 的行为类似 `allowlist`，但仍会保留一个显式引用的回复。 +- `contextVisibility: "all"` 是默认值。补充上下文会按收到时保留。 +- `contextVisibility: "allowlist"` 会将补充上下文过滤为活动房间/用户允许列表检查允许的发送者。 +- `contextVisibility: "allowlist_quote"` 的行为与 `allowlist` 类似，但仍保留一条显式引用回复。 -此设置影响的是补充上下文的可见性，而不是传入消息本身是否可以触发回复。 -触发授权仍然来自 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置。 +此设置影响的是补充上下文可见性，而不是传入消息本身是否可以触发回复。 +触发授权仍由 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置决定。 ## 私信和房间策略示例 @@ -806,7 +857,7 @@ Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文 } ``` -有关提及门控和 allowlist 行为，请参阅 [群组](/zh-CN/channels/groups)。 +有关提及门控和允许列表行为，请参阅 [群组](/zh-CN/channels/groups)。 Matrix 私信的配对示例： @@ -815,53 +866,53 @@ openclaw pairing list matrix openclaw pairing approve matrix ``` -如果某个未批准的 Matrix 用户在获得批准前持续向你发消息，OpenClaw 会复用相同的待处理配对代码，并可能在短暂冷却后再次发送提醒回复，而不是生成新的代码。 +如果未获批准的 Matrix 用户在批准前持续给你发消息，OpenClaw 会复用同一个待处理配对码，并可能在短暂冷却后再次发送提醒回复，而不是生成新的代码。 有关共享的私信配对流程和存储布局，请参阅 [配对](/zh-CN/channels/pairing)。 -## Exec 审批 +## 执行审批 -Matrix 可以作为某个 Matrix 账号的 exec 审批客户端。 +Matrix 可以作为 Matrix 账户的 exec 审批客户端。 - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers`（可选；回退到 `channels.matrix.dm.allowFrom`） +- `channels.matrix.execApprovals.approvers`（可选；会回退到 `channels.matrix.dm.allowFrom`） - `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -审批者必须是 Matrix 用户 ID，例如 `@owner:example.org`。当 `enabled` 未设置或为 `"auto"`，并且至少可以解析出一个审批者时——无论来自 `execApprovals.approvers` 还是 `channels.matrix.dm.allowFrom`——Matrix 会自动启用原生 exec 审批。设置 `enabled: false` 可显式禁用 Matrix 作为原生审批客户端。否则，审批请求会回退到其他已配置的审批路由或 exec 审批回退策略。 +审批人必须是 Matrix 用户 ID，例如 `@owner:example.org`。当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个审批人时，Matrix 会自动启用原生 exec 审批，无论审批人来自 `execApprovals.approvers` 还是 `channels.matrix.dm.allowFrom`。设置 `enabled: false` 可显式禁用 Matrix 作为原生审批客户端。否则，审批请求会回退到其他已配置的审批路由或 exec 审批回退策略。 -目前原生 Matrix 路由仅支持 exec： +目前原生 Matrix 路由仅限 exec： - `channels.matrix.execApprovals.*` 仅控制 exec 审批的原生私信/渠道路由。 -- 插件审批仍使用共享的同聊天 `/approve`，以及任何已配置的 `approvals.plugin` 转发。 -- 当 Matrix 能安全推断审批者时，它仍可以复用 `channels.matrix.dm.allowFrom` 进行插件审批授权，但不会公开单独的原生插件审批私信/渠道扇出路径。 +- 插件审批仍使用共享的同聊天 `/approve` 加上任何已配置的 `approvals.plugin` 转发。 +- 当 Matrix 可以安全推断审批人时，它仍可复用 `channels.matrix.dm.allowFrom` 进行插件审批授权，但它不会公开单独的原生插件审批私信/渠道扇出路径。 投递规则： -- `target: "dm"` 会将审批提示发送到审批者私信 -- `target: "channel"` 会将提示发送回发起的 Matrix 房间或私信 -- `target: "both"` 会同时发送到审批者私信以及发起的 Matrix 房间或私信 +- `target: "dm"` 将审批提示发送到审批人私信 +- `target: "channel"` 将提示发回原始 Matrix 房间或私信 +- `target: "both"` 会同时发送到审批人私信和原始 Matrix 房间或私信 -Matrix 审批提示会在主审批消息上预置表情回应快捷方式： +Matrix 审批提示会在主审批消息上加入回应快捷方式： - `✅` = 允许一次 - `❌` = 拒绝 -- `♾️` = 当该决策被有效 exec 策略允许时，始终允许 +- `♾️` = 在有效 exec 策略允许该决定时始终允许 -审批者可以对该消息添加表情回应，或使用回退斜杠命令：`/approve allow-once`、`/approve allow-always` 或 `/approve deny`。 +审批人可以对该消息添加回应，也可以使用后备斜杠命令：`/approve allow-once`、`/approve allow-always` 或 `/approve deny`。 -只有已解析的审批者才能批准或拒绝。渠道投递会包含命令文本，因此仅在受信任房间中启用 `channel` 或 `both`。 +只有已解析的审批人才能批准或拒绝。渠道投递包含命令文本，因此只有在受信任房间中才启用 `channel` 或 `both`。 -Matrix 审批提示复用共享的核心审批规划器。Matrix 特有的原生界面目前仅作为 exec 审批的传输层：房间/私信路由以及消息发送/更新/删除行为。 +Matrix 审批提示会复用共享核心审批规划器。Matrix 特定的原生界面仅作为 exec 审批的传输层：房间/私信路由以及消息发送/更新/删除行为。 -按账号覆盖： +按账户覆盖： - `channels.matrix.accounts..execApprovals` -相关文档：[Exec 审批](/zh-CN/tools/exec-approvals) +相关文档：[Exec approvals](/zh-CN/tools/exec-approvals) -## 多账号示例 +## 多账户示例 ```json5 { @@ -891,27 +942,31 @@ Matrix 审批提示复用共享的核心审批规划器。Matrix 特有的原生 } ``` -顶层 `channels.matrix` 值会作为命名账号的默认值，除非某个账号进行了覆盖。 -你可以使用 `groups..account`（或旧版 `rooms..account`）将继承的房间条目限定到某个 Matrix 账号。 -未设置 `account` 的条目会在所有 Matrix 账号之间共享，而设置 `account: "default"` 的条目在默认账号直接配置在顶层 `channels.matrix.*` 时仍然有效。 -部分共享认证默认值本身不会创建单独的隐式默认账号。只有当该默认值具备新的认证信息（`homeserver` 加 `accessToken`，或 `homeserver` 加 `userId` 和 `password`）时，OpenClaw 才会合成顶层 `default` 账号；命名账号仍可以仅凭 `homeserver` 加 `userId` 保持可发现状态，并在稍后由缓存凭证满足认证。 -如果 Matrix 已经恰好有一个命名账号，或 `defaultAccount` 指向现有命名账号键，那么单账号到多账号的修复/设置提升会保留该账号，而不会创建新的 `accounts.default` 条目。只有 Matrix 认证/bootstrap 键会移动到提升后的账号；共享投递策略键仍保留在顶层。 -当你希望 OpenClaw 在隐式路由、探测和 CLI 操作中优先使用某个命名 Matrix 账号时，请设置 `defaultAccount`。 -如果你配置了多个命名账号，请设置 `defaultAccount`，或为依赖隐式账号选择的 CLI 命令传入 `--account `。 -当你希望为某条命令覆盖这种隐式选择时，请将 `--account ` 传给 `openclaw matrix verify ...` 和 `openclaw matrix devices ...`。 +顶层 `channels.matrix` 值会作为命名账户的默认值，除非某个账户自行覆盖。 +你可以使用 `groups..account`（或旧版 `rooms..account`）将继承的房间条目限定到某一个 Matrix 账户。 +没有 `account` 的条目会在所有 Matrix 账户之间共享，而带有 `account: "default"` 的条目在默认账户直接配置于顶层 `channels.matrix.*` 时仍然有效。 +部分共享认证默认值本身不会创建单独的隐式默认账户。只有当该默认账户具有新的认证信息（`homeserver` 加 `accessToken`，或 `homeserver` 加 `userId` 和 `password`）时，OpenClaw 才会合成顶层 `default` 账户；命名账户仍可在稍后由缓存凭证满足认证时，通过 `homeserver` 加 `userId` 保持可发现。 +如果 Matrix 已经恰好有一个命名账户，或者 `defaultAccount` 指向现有命名账户键，那么从单账户到多账户的修复/设置升级会保留该账户，而不是创建新的 `accounts.default` 条目。只有 Matrix 认证/bootstrap 键会移动到该提升后的账户中；共享投递策略键仍保留在顶层。 +当你希望 OpenClaw 在隐式路由、探测和 CLI 操作中优先使用某个命名 Matrix 账户时，请设置 `defaultAccount`。 +如果你配置了多个命名账户，请设置 `defaultAccount`，或为依赖隐式账户选择的 CLI 命令传入 `--account `。 +当你希望对单个命令覆盖该隐式选择时，请为 `openclaw matrix verify ...` 和 `openclaw matrix devices ...` 传入 `--account `。 ## 私有/LAN homeserver -默认情况下，除非你按账号显式选择启用，否则 OpenClaw 会阻止连接私有/内部 Matrix homeserver，以提供 SSRF 保护。 +默认情况下，OpenClaw 会阻止连接私有/内部 Matrix homeserver，以防 SSRF，除非你 +按账户显式选择启用。 -如果你的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该 Matrix 账号启用 `allowPrivateNetwork`： +如果你的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该 Matrix 账户启用 +`network.dangerouslyAllowPrivateNetwork`： ```json5 { channels: { matrix: { homeserver: "http://matrix-synapse:8008", - allowPrivateNetwork: true, + network: { + dangerouslyAllowPrivateNetwork: true, + }, accessToken: "syt_internal_xxx", }, }, @@ -928,8 +983,8 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -此选择启用仅允许受信任的私有/内部目标。诸如 -`http://matrix.example.org:8008` 这样的公共明文 homeserver 仍会被阻止。尽可能优先使用 `https://`。 +此选择启用仅允许受信任的私有/内部目标。公共明文 homeserver，例如 +`http://matrix.example.org:8008`，仍会被阻止。尽可能优先使用 `https://`。 ## 代理 Matrix 流量 @@ -947,87 +1002,87 @@ openclaw matrix account add \ } ``` -命名账号可以使用 `channels.matrix.accounts..proxy` 覆盖顶层默认值。 -OpenClaw 会对运行时 Matrix 流量和账号状态探测使用相同的代理设置。 +命名账户可以用 `channels.matrix.accounts..proxy` 覆盖顶层默认值。 +OpenClaw 对运行时 Matrix 流量和账户状态探测使用相同的代理设置。 ## 目标解析 -在 OpenClaw 要求你提供房间或用户目标的任何位置，Matrix 都接受以下目标形式： +在 OpenClaw 要求你提供房间或用户目标的任何地方，Matrix 都接受以下目标格式： - 用户：`@user:server`、`user:@user:server` 或 `matrix:user:@user:server` - 房间：`!room:server`、`room:!room:server` 或 `matrix:room:!room:server` - 别名：`#alias:server`、`channel:#alias:server` 或 `matrix:channel:#alias:server` -实时目录查找会使用已登录的 Matrix 账号： +实时目录查找使用已登录的 Matrix 账户： - 用户查找会查询该 homeserver 上的 Matrix 用户目录。 -- 房间查找会直接接受显式房间 ID 和别名，然后回退到搜索该账号已加入房间的名称。 -- 已加入房间名称查找属于尽力而为。如果房间名称无法解析为 ID 或别名，运行时 allowlist 解析会忽略它。 +- 房间查找会直接接受显式房间 ID 和别名，然后回退到搜索该账户已加入的房间名称。 +- 已加入房间名称查找是尽力而为的。如果某个房间名称无法解析为 ID 或别名，它会在运行时允许列表解析中被忽略。 ## 配置参考 - `enabled`：启用或禁用该渠道。 -- `name`：账号的可选标签。 -- `defaultAccount`：配置多个 Matrix 账号时的首选账号 ID。 +- `name`：账户的可选标签。 +- `defaultAccount`：配置多个 Matrix 账户时的首选账户 ID。 - `homeserver`：homeserver URL，例如 `https://matrix.example.org`。 -- `allowPrivateNetwork`：允许此 Matrix 账号连接到私有/内部 homeserver。当 homeserver 解析到 `localhost`、LAN/Tailscale IP 或内部主机（如 `matrix-synapse`）时启用此项。 -- `proxy`：Matrix 流量的可选 HTTP(S) 代理 URL。命名账号可以用自己的 `proxy` 覆盖顶层默认值。 +- `network.dangerouslyAllowPrivateNetwork`：允许此 Matrix 账户连接到私有/内部 homeserver。当 homeserver 解析到 `localhost`、LAN/Tailscale IP 或内部主机（如 `matrix-synapse`）时启用它。 +- `proxy`：Matrix 流量的可选 HTTP(S) 代理 URL。命名账户可使用各自的 `proxy` 覆盖顶层默认值。 - `userId`：完整 Matrix 用户 ID，例如 `@bot:example.org`。 -- `accessToken`：基于 token 认证的 access token。`channels.matrix.accessToken` 和 `channels.matrix.accounts..accessToken` 支持明文值和 SecretRef 值，适用于 env/file/exec provider。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 -- `password`：基于 password 登录的密码。支持明文值和 SecretRef 值。 +- `accessToken`：基于令牌认证的访问令牌。`channels.matrix.accessToken` 和 `channels.matrix.accounts..accessToken` 支持明文值和 SecretRef 值，可跨 env/file/exec 提供商使用。参见 [Secrets Management](/zh-CN/gateway/secrets)。 +- `password`：基于密码登录的密码。支持明文值和 SecretRef 值。 - `deviceId`：显式 Matrix 设备 ID。 -- `deviceName`：password 登录时的设备显示名称。 -- `avatarUrl`：用于配置文件同步和 `set-profile` 更新的已存储自头像 URL。 +- `deviceName`：密码登录的设备显示名称。 +- `avatarUrl`：用于资料同步和 `set-profile` 更新的已存储自身头像 URL。 - `initialSyncLimit`：启动同步事件限制。 - `encryption`：启用 E2EE。 -- `allowlistOnly`：强制对私信和房间启用仅 allowlist 行为。 -- `allowBots`：允许来自其他已配置 OpenClaw Matrix 账号的消息（`true` 或 `"mentions"`）。 +- `allowlistOnly`：对私信和房间强制仅允许列表行为。 +- `allowBots`：允许来自其他已配置 OpenClaw Matrix 账户的消息（`true` 或 `"mentions"`）。 - `groupPolicy`：`open`、`allowlist` 或 `disabled`。 -- `contextVisibility`：补充房间上下文的可见性模式（`all`、`allowlist`、`allowlist_quote`）。 -- `groupAllowFrom`：房间流量的用户 ID allowlist。 -- `groupAllowFrom` 条目应为完整 Matrix 用户 ID。无法解析的名称在运行时会被忽略。 -- `historyLimit`：作为群组历史上下文包含的最大房间消息数。会回退到 `messages.groupChat.historyLimit`；如果两者都未设置，则有效默认值为 `0`。设置 `0` 可禁用。 -- `replyToMode`：`off`、`first` 或 `all`。 +- `contextVisibility`：补充房间上下文可见性模式（`all`、`allowlist`、`allowlist_quote`）。 +- `groupAllowFrom`：房间流量的用户 ID 允许列表。 +- `groupAllowFrom` 条目应为完整 Matrix 用户 ID。无法解析的名称会在运行时被忽略。 +- `historyLimit`：作为群组历史上下文包含的最大房间消息数。会回退到 `messages.groupChat.historyLimit`；如果两者都未设置，实际默认值为 `0`。设置 `0` 可禁用。 +- `replyToMode`：`off`、`first`、`all` 或 `batched`。 - `markdown`：出站 Matrix 文本的可选 Markdown 渲染配置。 -- `streaming`：`off`（默认）、`partial`、`quiet`、`true` 或 `false`。`partial` 和 `true` 会使用普通 Matrix 文本消息启用先预览的草稿更新。`quiet` 会在自托管推送规则设置中使用静默预览通知。 -- `blockStreaming`：`true` 会在草稿预览流式传输启用时，为已完成的 assistant 块启用单独进度消息。 +- `streaming`：`off`（默认）、`partial`、`quiet`、`true` 或 `false`。`partial` 和 `true` 会使用普通 Matrix 文本消息启用“先预览”草稿更新。`quiet` 会为自托管推送规则设置使用无通知预览通知。 +- `blockStreaming`：`true` 会在草稿预览流式传输开启时，为已完成的 assistant 块启用独立进度消息。 - `threadReplies`：`off`、`inbound` 或 `always`。 - `threadBindings`：线程绑定会话路由和生命周期的按渠道覆盖。 - `startupVerification`：启动时自动自我验证请求模式（`if-unverified`、`off`）。 -- `startupVerificationCooldownHours`：自动启动验证请求重试前的冷却时间。 +- `startupVerificationCooldownHours`：重试自动启动验证请求前的冷却时间。 - `textChunkLimit`：出站消息分块大小。 - `chunkMode`：`length` 或 `newline`。 - `responsePrefix`：出站回复的可选消息前缀。 -- `ackReaction`：此渠道/账号的可选 ack 表情回应覆盖。 -- `ackReactionScope`：可选的 ack 表情回应作用域覆盖（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 -- `reactionNotifications`：传入表情回应通知模式（`own`、`off`）。 +- `ackReaction`：此渠道/账户的可选 ack 回应覆盖。 +- `ackReactionScope`：可选 ack 回应作用域覆盖（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 +- `reactionNotifications`：传入回应通知模式（`own`、`off`）。 - `mediaMaxMb`：Matrix 媒体处理的媒体大小上限（MB）。适用于出站发送和传入媒体处理。 -- `autoJoin`：邀请自动加入策略（`always`、`allowlist`、`off`）。默认值：`off`。这适用于一般意义上的 Matrix 邀请，包括私信式邀请，而不仅仅是房间/群组邀请。OpenClaw 会在邀请时做出该决定，此时它还无法可靠地将加入的房间归类为私信或群组。 -- `autoJoinAllowlist`：当 `autoJoin` 为 `allowlist` 时允许的房间/别名。别名条目会在处理邀请时解析为房间 ID；OpenClaw 不会信任受邀房间声明的别名状态。 +- `autoJoin`：邀请自动加入策略（`always`、`allowlist`、`off`）。默认：`off`。这适用于一般的 Matrix 邀请，包括私信式邀请，而不仅仅是房间/群组邀请。OpenClaw 会在邀请时做出此决定，此时它还无法可靠地将加入的房间归类为私信或群组。 +- `autoJoinAllowlist`：当 `autoJoin` 为 `allowlist` 时允许的房间/别名。别名条目会在处理邀请时解析为房间 ID；OpenClaw 不信任受邀房间声明的别名状态。 - `dm`：私信策略块（`enabled`、`policy`、`allowFrom`、`sessionScope`、`threadReplies`）。 -- `dm.policy`：控制 OpenClaw 在加入房间并将其归类为私信之后的私信访问。它不会改变邀请是否会自动加入。 +- `dm.policy`：控制 OpenClaw 加入房间并将其归类为私信后的私信访问。它不会改变邀请是否自动加入。 - `dm.allowFrom` 条目应为完整 Matrix 用户 ID，除非你已经通过实时目录查找解析过它们。 -- `dm.sessionScope`：`per-user`（默认）或 `per-room`。如果你希望每个 Matrix 私信房间即使面对同一个对等方也保持独立上下文，请使用 `per-room`。 -- `dm.threadReplies`：仅私信线程策略覆盖（`off`、`inbound`、`always`）。它会覆盖顶层 `threadReplies` 设置，用于私信中的回复位置和会话隔离。 +- `dm.sessionScope`：`per-user`（默认）或 `per-room`。如果你希望即使对端相同，每个 Matrix 私信房间仍保持独立上下文，请使用 `per-room`。 +- `dm.threadReplies`：仅私信线程策略覆盖（`off`、`inbound`、`always`）。它会覆盖顶层 `threadReplies` 设置，包括私信中的回复位置和会话隔离。 - `execApprovals`：Matrix 原生 exec 审批投递（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 -- `execApprovals.approvers`：允许批准 exec 请求的 Matrix 用户 ID。当 `dm.allowFrom` 已经标识审批者时可选。 +- `execApprovals.approvers`：允许批准 exec 请求的 Matrix 用户 ID。当 `dm.allowFrom` 已经标识审批人时，此项可选。 - `execApprovals.target`：`dm | channel | both`（默认：`dm`）。 -- `accounts`：命名的按账号覆盖项。顶层 `channels.matrix` 值会作为这些条目的默认值。 -- `groups`：按房间划分的策略映射。优先使用房间 ID 或别名；无法解析的房间名称会在运行时被忽略。解析后，会话/群组身份使用稳定房间 ID，而人类可读标签仍来自房间名称。 -- `groups..account`：在多账号设置中，将某个继承房间条目限制到特定 Matrix 账号。 -- `groups..allowBots`：针对已配置机器人发送者的房间级覆盖（`true` 或 `"mentions"`）。 -- `groups..users`：按房间划分的发送者 allowlist。 -- `groups..tools`：按房间划分的工具允许/拒绝覆盖。 -- `groups..autoReply`：房间级提及门控覆盖。`true` 会禁用该房间的提及要求；`false` 会重新强制启用。 -- `groups..skills`：可选的房间级 skill 过滤器。 -- `groups..systemPrompt`：可选的房间级 system prompt 片段。 +- `accounts`：按账户命名的覆盖项。顶层 `channels.matrix` 值会作为这些条目的默认值。 +- `groups`：按房间的策略映射。优先使用房间 ID 或别名；无法解析的房间名会在运行时被忽略。会话/群组身份在解析后使用稳定的房间 ID，而人类可读标签仍来自房间名。 +- `groups..account`：在多账户设置中，将某个继承房间条目限制到特定 Matrix 账户。 +- `groups..allowBots`：对已配置机器人发送者的房间级覆盖（`true` 或 `"mentions"`）。 +- `groups..users`：按房间的发送者允许列表。 +- `groups..tools`：按房间的工具允许/拒绝覆盖。 +- `groups..autoReply`：房间级提及门控覆盖。`true` 会禁用该房间的提及要求；`false` 会强制重新开启。 +- `groups..skills`：可选的房间级 Skills 过滤器。 +- `groups..systemPrompt`：可选的房间级系统提示片段。 - `rooms`：`groups` 的旧版别名。 -- `actions`：按操作划分的工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 +- `actions`：按操作的工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 ## 相关内容 - [渠道概览](/zh-CN/channels) — 所有支持的渠道 -- [配对](/zh-CN/channels/pairing) — 私信认证与配对流程 +- [配对](/zh-CN/channels/pairing) — 私信认证和配对流程 - [群组](/zh-CN/channels/groups) — 群聊行为和提及门控 - [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由 -- [安全](/zh-CN/gateway/security) — 访问模型与加固 +- [安全性](/zh-CN/gateway/security) — 访问模型和加固 diff --git a/docs/zh-CN/channels/whatsapp.md b/docs/zh-CN/channels/whatsapp.md index 125595fce..2c81abb43 100644 --- a/docs/zh-CN/channels/whatsapp.md +++ b/docs/zh-CN/channels/whatsapp.md @@ -1,20 +1,20 @@ --- read_when: - - 处理 WhatsApp / web 渠道行为或收件箱路由时 -summary: WhatsApp 渠道支持、访问控制、传递行为和运维 + - 处理 WhatsApp/web 渠道行为或收件箱路由时 +summary: WhatsApp 渠道支持、访问控制、消息传递行为和运维 title: WhatsApp x-i18n: - generated_at: "2026-04-05T08:19:07Z" + generated_at: "2026-04-06T15:28:05Z" model: gpt-5.4 provider: openai - source_hash: c16a468b3f47fdf7e4fc3fd745b5c49c7ccebb7af0e8c87c632b78b04c583e49 + source_hash: 9e2ce84d869ace6c0bebd9ec17bdbbef997a5c31e5da410b02a19a0f103f7359 source_path: channels/whatsapp.md workflow: 15 --- # WhatsApp（Web 渠道） -状态：通过 WhatsApp Web（Baileys）已可用于生产环境。Gateway 网关拥有已关联的会话。 +状态：通过 WhatsApp Web（Baileys）可用于生产环境。Gateway 网关拥有已关联的会话。 ## 安装（按需） @@ -23,7 +23,7 @@ x-i18n: - `openclaw channels login --channel whatsapp` 也会在 插件尚未安装时提供安装流程。 - 开发渠道 + git 检出：默认使用本地插件路径。 -- Stable / Beta：默认使用 npm 包 `@openclaw/whatsapp`。 +- 稳定版/Beta 版：默认使用 npm 包 `@openclaw/whatsapp`。 你仍然可以手动安装： @@ -32,13 +32,13 @@ openclaw plugins install @openclaw/whatsapp ``` - - 对未知发件人的默认私信策略是配对。 + + 未知发件人的默认私信策略是配对。 - - 跨渠道诊断和修复操作手册。 + + 跨渠道诊断与修复操作手册。 - + 完整的渠道配置模式和示例。 @@ -69,7 +69,7 @@ openclaw plugins install @openclaw/whatsapp openclaw channels login --channel whatsapp ``` - 对于特定账户： + 对于特定账号： ```bash openclaw channels login --channel whatsapp --account work @@ -98,7 +98,7 @@ openclaw pairing approve whatsapp -OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据和设置流程都针对这种设置进行了优化，但也支持个人号码设置。） +OpenClaw 建议在条件允许时为 WhatsApp 使用单独的号码。（渠道元数据和设置流程已针对这种设置进行了优化，但也支持个人号码设置。） ## 部署模式 @@ -107,7 +107,7 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 这是最清晰的运维模式： - - 为 OpenClaw 使用独立的 WhatsApp 身份 + - OpenClaw 使用单独的 WhatsApp 身份 - 更清晰的私信允许列表和路由边界 - 更低的自聊混淆概率 @@ -127,18 +127,18 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 - 新手引导支持个人号码模式，并会写入适合自聊的基线配置： + 新手引导支持个人号码模式，并会写入适合自聊的基础配置： - `dmPolicy: "allowlist"` - `allowFrom` 包含你的个人号码 - `selfChatMode: true` - 在运行时，自聊保护基于已关联的自身号码和 `allowFrom` 生效。 + 在运行时，自聊保护会依据已关联的自身号码和 `allowFrom` 生效。 - - 在当前的 OpenClaw 渠道架构中，该消息平台渠道基于 WhatsApp Web（`Baileys`）。 + + 在当前 OpenClaw 渠道架构中，该消息平台渠道基于 WhatsApp Web（`Baileys`）。 内置聊天渠道注册表中没有单独的 Twilio WhatsApp 消息渠道。 @@ -148,12 +148,13 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 ## 运行时模型 - Gateway 网关拥有 WhatsApp socket 和重连循环。 -- 出站发送要求目标账户存在活动中的 WhatsApp 监听器。 +- 出站发送要求目标账号存在活动中的 WhatsApp 监听器。 - 状态和广播聊天会被忽略（`@status`、`@broadcast`）。 - 私聊使用私信会话规则（`session.dmScope`；默认 `main` 会将私信折叠到智能体主会话）。 - 群组会话彼此隔离（`agent::whatsapp:group:`）。 +- WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` 及其小写变体）。优先使用主机级代理配置，而不是渠道专用的 WhatsApp 代理设置。 -## 访问控制和激活 +## 访问控制与激活 @@ -164,14 +165,14 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 - `open`（要求 `allowFrom` 包含 `"*"`） - `disabled` - `allowFrom` 接受 E.164 风格的号码（内部会标准化）。 + `allowFrom` 接受 E.164 风格号码（内部会标准化）。 - 多账户覆盖：`channels.whatsapp.accounts..dmPolicy`（以及 `allowFrom`）会优先于该账户的渠道级默认值。 + 多账号覆盖：`channels.whatsapp.accounts..dmPolicy`（以及 `allowFrom`）会优先于该账号的渠道级默认值。 运行时行为细节： - - 配对关系会持久化到渠道允许存储中，并与已配置的 `allowFrom` 合并 - - 如果未配置允许列表，则默认允许已关联的自身号码 + - 配对会持久化到渠道允许存储中，并与已配置的 `allowFrom` 合并 + - 如果未配置任何允许列表，则默认允许已关联的自身号码 - 出站 `fromMe` 私信永远不会自动配对 @@ -179,9 +180,9 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 群组访问有两层： - 1. **群组成员资格允许列表**（`channels.whatsapp.groups`） - - 如果省略 `groups`，则所有群组都符合条件 - - 如果存在 `groups`，它会作为群组允许列表（允许 `"*"`） + 1. **群组成员允许列表**（`channels.whatsapp.groups`） + - 如果省略 `groups`，则所有群组都有资格 + - 如果存在 `groups`，它会作为群组允许列表使用（允许 `"*"`） 2. **群组发件人策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`） - `open`：绕过发件人允许列表 @@ -191,51 +192,51 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 发件人允许列表回退规则： - 如果未设置 `groupAllowFrom`，运行时会在可用时回退到 `allowFrom` - - 在评估提及 / 回复激活之前，会先评估发件人允许列表 + - 发件人允许列表会在提及/回复激活之前进行评估 - 注意：如果根本不存在 `channels.whatsapp` 配置块，即使设置了 `channels.defaults.groupPolicy`，运行时的群组策略回退值仍是 `allowlist`（并会记录警告日志）。 + 注意：如果根本不存在 `channels.whatsapp` 配置块，运行时群组策略回退值为 `allowlist`（并记录警告日志），即使设置了 `channels.defaults.groupPolicy` 也是如此。 - 群组回复默认需要被提及。 + 群组回复默认要求被提及。 提及检测包括： - - 明确提及机器人的 WhatsApp 提及 - - 已配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式回复机器人检测（回复发送者与机器人身份匹配） + - 对机器人身份的显式 WhatsApp 提及 + - 已配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 隐式回复给机器人的检测（回复发送者与机器人身份匹配） 安全说明： - - 引用 / 回复只会满足提及门控；**不会**授予发件人授权 - - 当 `groupPolicy: "allowlist"` 时，即使非允许列表中的发件人回复允许列表用户的消息，仍然会被阻止 + - 引用/回复只会满足提及门控；它**不会**授予发件人授权 + - 使用 `groupPolicy: "allowlist"` 时，未在允许列表中的发件人即使回复了允许列表用户的消息，仍然会被阻止 会话级激活命令： - `/activation mention` - `/activation always` - `activation` 会更新会话状态（不是全局配置）。它受 owner 门控控制。 + `activation` 会更新会话状态（而不是全局配置）。它受所有者权限控制。 ## 个人号码和自聊行为 -当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护会激活： +当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护会启用： -- 跳过自聊轮次的已读回执 -- 忽略本会导致你自己被 ping 的 mention-JID 自动触发行为 +- 跳过自聊回合的已读回执 +- 忽略原本会提醒你自己的 mention-JID 自动触发行为 - 如果未设置 `messages.responsePrefix`，自聊回复默认使用 `[{identity.name}]` 或 `[openclaw]` ## 消息标准化和上下文 - - 传入的 WhatsApp 消息会包装到共享入站封装中。 + + 传入的 WhatsApp 消息会被包装进共享的入站信封中。 - 如果存在引用回复，上下文会以如下形式附加： + 如果存在引用回复，上下文会按以下形式附加： ```text [Replying to id:] @@ -243,12 +244,12 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 [/Replying] ``` - 可用时还会填充回复元数据字段（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发件人 JID / E.164）。 + 回复元数据字段也会在可用时填充（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。 - - 仅媒体的入站消息会使用如下占位符标准化： + + 仅含媒体的入站消息会被标准化为如下占位符： - `` - `` @@ -261,7 +262,7 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 - 对于群组，当机器人最终被触发时，未处理的消息可以先缓冲并作为上下文注入。 + 对于群组，当机器人最终被触发时，未处理消息可以被缓冲并作为上下文注入。 - 默认上限：`50` - 配置：`channels.whatsapp.historyLimit` @@ -276,7 +277,7 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 - 已接受的入站 WhatsApp 消息默认启用已读回执。 + 对于已接受的入站 WhatsApp 消息，默认启用已读回执。 全局禁用： @@ -290,7 +291,7 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 } ``` - 按账户覆盖： + 按账号覆盖： ```json5 { @@ -306,7 +307,7 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 } ``` - 即使全局启用，自聊轮次也会跳过已读回执。 + 即使全局已启用，自聊回合也会跳过已读回执。 @@ -323,7 +324,7 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 - 支持图片、视频、音频（PTT 语音便笺）和文档载荷 - `audio/ogg` 会被改写为 `audio/ogg; codecs=opus` 以兼容语音便笺 - - 通过在视频发送中设置 `gifPlayback: true` 支持动画 GIF 播放 + - 通过在视频发送时设置 `gifPlayback: true` 支持动态 GIF 播放 - 发送多媒体回复载荷时，说明文字会应用到第一个媒体项 - 媒体来源可以是 HTTP(S)、`file://` 或本地路径 @@ -331,26 +332,26 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 - 入站媒体保存上限：`channels.whatsapp.mediaMaxMb`（默认 `50`） - 出站媒体发送上限：`channels.whatsapp.mediaMaxMb`（默认 `50`） - - 按账户覆盖使用 `channels.whatsapp.accounts..mediaMaxMb` - - 图片会自动优化（调整尺寸 / 质量扫描）以满足限制 + - 按账号覆盖使用 `channels.whatsapp.accounts..mediaMaxMb` + - 图片会自动优化（调整尺寸/质量扫描）以适配限制 - 媒体发送失败时，首项回退会发送文本警告，而不是静默丢弃响应 -## Reaction 级别 +## 反应级别 -`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用 emoji reaction 的广泛程度： +`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用表情反应的范围： -| 级别 | 确认 reaction | 智能体主动发起的 reaction | 说明 | -| ------------ | ------------- | ------------------------- | ------------------------------------- | -| `"off"` | 否 | 否 | 完全不使用 reaction | -| `"ack"` | 是 | 否 | 仅确认 reaction（回复前确认） | -| `"minimal"` | 是 | 是（保守） | 确认 + 带保守引导的智能体 reaction | -| `"extensive"`| 是 | 是（鼓励） | 确认 + 带鼓励性引导的智能体 reaction | +| 级别 | 确认反应 | 智能体主动发起的反应 | 描述 | +| ------------- | ------------- | ------------------------- | ------------------------------------------------ | +| `"off"` | 否 | 否 | 完全不使用反应 | +| `"ack"` | 是 | 否 | 仅确认反应（回复前确认已收到） | +| `"minimal"` | 是 | 是（保守） | 确认 + 智能体反应，采用保守指引 | +| `"extensive"` | 是 | 是（鼓励） | 确认 + 智能体反应，采用鼓励性指引 | 默认值：`"minimal"`。 -按账户覆盖使用 `channels.whatsapp.accounts..reactionLevel`。 +按账号覆盖使用 `channels.whatsapp.accounts..reactionLevel`。 ```json5 { @@ -362,10 +363,10 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 } ``` -## 确认 reaction +## 确认反应 -WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在接收入站消息时立即发送确认 reaction。 -确认 reaction 受 `reactionLevel` 门控控制 —— 当 `reactionLevel` 为 `"off"` 时会被抑制。 +WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在接收入站消息时立即发送确认反应。 +确认反应受 `reactionLevel` 控制 —— 当 `reactionLevel` 为 `"off"` 时会被抑制。 ```json5 { @@ -384,36 +385,36 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在接收入站消息时 行为说明： - 在接受入站消息后立即发送（回复前） -- 失败会被记录到日志中，但不会阻止正常回复传递 -- 群组模式 `mentions` 会在由提及触发的轮次中发送 reaction；群组激活 `always` 可绕过此检查 -- WhatsApp 使用 `channels.whatsapp.ackReaction`（这里不使用旧版 `messages.ackReaction`） +- 失败会被记录日志，但不会阻止正常回复投递 +- 群组模式 `mentions` 会在由提及触发的回合中发送反应；群组激活 `always` 会绕过此检查 +- WhatsApp 使用 `channels.whatsapp.ackReaction`（这里不会使用旧版 `messages.ackReaction`） -## 多账户和凭证 +## 多账号和凭证 - - - 账户 id 来自 `channels.whatsapp.accounts` - - 默认账户选择：如果存在则为 `default`，否则为第一个已配置的账户 id（已排序） - - 账户 id 会在内部标准化后用于查找 + + - 账号 id 来自 `channels.whatsapp.accounts` + - 默认账号选择：如果存在则为 `default`，否则为第一个已配置的账号 id（已排序） + - 账号 id 会在内部标准化以供查找 - 当前认证路径：`~/.openclaw/credentials/whatsapp//creds.json` - 备份文件：`creds.json.bak` - - `~/.openclaw/credentials/` 中的旧版默认认证在默认账户流程中仍会被识别 / 迁移 + - `~/.openclaw/credentials/` 中的旧版默认认证仍会被识别/迁移，用于默认账号流程 - `openclaw channels logout --channel whatsapp [--account ]` 会清除此账户的 WhatsApp 认证状态。 + `openclaw channels logout --channel whatsapp [--account ]` 会清除该账号的 WhatsApp 认证状态。 - 在旧版认证目录中，会保留 `oauth.json`，同时删除 Baileys 认证文件。 + 在旧版认证目录中，`oauth.json` 会被保留，而 Baileys 认证文件会被移除。 ## 工具、操作和配置写入 -- 智能体工具支持包括 WhatsApp reaction 操作（`react`）。 +- 智能体工具支持包括 WhatsApp 反应操作（`react`）。 - 操作门控： - `channels.whatsapp.actions.reactions` - `channels.whatsapp.actions.polls` @@ -423,7 +424,7 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在接收入站消息时 - 症状：渠道状态显示未关联。 + 症状：渠道状态报告显示未关联。 修复方法： @@ -435,7 +436,7 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在接收入站消息时 - 症状：账户已关联，但反复断开或尝试重连。 + 症状：已关联账号反复断开或重复尝试重连。 修复方法： @@ -449,25 +450,25 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在接收入站消息时 - 当目标账户不存在活动中的 Gateway 网关监听器时，出站发送会快速失败。 + 当目标账号不存在活动中的 Gateway 网关监听器时，出站发送会快速失败。 - 请确保 Gateway 网关正在运行，并且该账户已关联。 + 请确保 Gateway 网关正在运行且该账号已关联。 - + 按以下顺序检查： - `groupPolicy` - `groupAllowFrom` / `allowFrom` - - `groups` 允许列表项 + - `groups` 允许列表条目 - 提及门控（`requireMention` + 提及模式） - `openclaw.json`（JSON5）中的重复键：后面的条目会覆盖前面的条目，因此每个作用域只保留一个 `groupPolicy` - WhatsApp Gateway 网关运行时应使用 Node。Bun 被标记为不兼容稳定的 WhatsApp / Telegram Gateway 网关运行。 + WhatsApp Gateway 网关运行时应使用 Node。Bun 被标记为不兼容稳定的 WhatsApp/Telegram Gateway 网关运行。 @@ -475,21 +476,21 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在接收入站消息时 主要参考： -- [配置参考 - WhatsApp](/gateway/configuration-reference#whatsapp) +- [配置参考 - WhatsApp](/zh-CN/gateway/configuration-reference#whatsapp) -高信号的 WhatsApp 字段： +高信号 WhatsApp 字段： -- 访问：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups` +- 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups` - 传递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel` -- 多账户：`accounts..enabled`、`accounts..authDir`、账户级覆盖 +- 多账号：`accounts..enabled`、`accounts..authDir`、账号级覆盖 - 运维：`configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*` - 会话行为：`session.dmScope`、`historyLimit`、`dmHistoryLimit`、`dms..historyLimit` ## 相关内容 -- [配对](/channels/pairing) -- [群组](/channels/groups) -- [安全](/gateway/security) -- [渠道路由](/channels/channel-routing) -- [多智能体路由](/concepts/multi-agent) -- [故障排除](/channels/troubleshooting) +- [配对](/zh-CN/channels/pairing) +- [群组](/zh-CN/channels/groups) +- [安全](/zh-CN/gateway/security) +- [渠道路由](/zh-CN/channels/channel-routing) +- [多智能体路由](/zh-CN/concepts/multi-agent) +- [故障排除](/zh-CN/channels/troubleshooting) diff --git a/docs/zh-CN/concepts/model-failover.md b/docs/zh-CN/concepts/model-failover.md index da246248f..a4506c86c 100644 --- a/docs/zh-CN/concepts/model-failover.md +++ b/docs/zh-CN/concepts/model-failover.md @@ -1,15 +1,15 @@ --- read_when: - - 诊断认证配置档案轮换、冷却期或模型回退行为 - - 更新认证配置档案或模型的故障切换规则 - - 理解会话模型覆盖如何与回退重试交互 -summary: OpenClaw 如何轮换认证配置档案并在模型之间回退 + - 诊断凭证配置文件轮换、冷却时间或模型回退行为 + - 更新凭证配置文件或模型的故障切换规则 + - 了解会话模型覆盖如何与回退重试交互 +summary: OpenClaw 如何轮换凭证配置文件，并在模型之间执行回退 title: 模型故障切换 x-i18n: - generated_at: "2026-04-05T08:22:10Z" + generated_at: "2026-04-06T15:28:05Z" model: gpt-5.4 provider: openai - source_hash: 899041aa0854e4f347343797649fd11140a01e069e88b1fbc0a76e6b375f6c96 + source_hash: d88821e229610f236bdab3f798d5e8c173f61a77c01017cc87431126bf465e32 source_path: concepts/model-failover.md workflow: 15 --- @@ -18,10 +18,10 @@ x-i18n: OpenClaw 分两个阶段处理失败： -1. 在当前提供商内进行**认证配置档案轮换**。 -2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。 +1. 当前提供商内的**凭证配置文件轮换**。 +2. 回退到 `agents.defaults.model.fallbacks` 中的下一个模型，即**模型回退**。 -本文档解释运行时规则以及支撑这些规则的数据。 +本文档说明支撑这些行为的运行时规则和数据。 ## 运行时流程 @@ -29,26 +29,23 @@ OpenClaw 分两个阶段处理失败： 1. 当前选中的会话模型。 2. 按顺序配置的 `agents.defaults.model.fallbacks`。 -3. 如果此次运行是从覆盖开始的，则最后回到已配置的主模型。 +3. 如果本次运行起始于某个覆盖设置，则最后再使用已配置的主模型。 -在每个候选项内部，OpenClaw 会先尝试认证配置档案故障切换，然后才前进到 +在每个候选项内部，OpenClaw 会先尝试凭证配置文件故障切换，再进入 下一个模型候选项。 -高层顺序如下： +高级别流程如下： -1. 解析活动的会话模型和认证配置档案偏好。 +1. 解析当前激活的会话模型和凭证配置文件偏好。 2. 构建模型候选链。 -3. 使用认证配置档案轮换/冷却规则尝试当前提供商。 -4. 如果该提供商因值得触发故障切换的错误而耗尽，则转到下一个 +3. 按照凭证配置文件轮换 / 冷却规则尝试当前提供商。 +4. 如果该提供商因值得故障切换的错误而耗尽可用项，则移动到下一个 模型候选项。 -5. 在重试开始前持久化选中的回退覆盖，以便其他 - 会话读取方看到运行器即将使用的相同提供商/模型。 -6. 如果回退候选项失败，则仅回滚由该回退拥有的会话 - 覆盖字段，且仅当它们仍然匹配该失败候选项时才会这样做。 -7. 如果所有候选项都失败，则抛出一个带有逐次尝试 - 细节的 `FallbackSummaryError`，并在已知时包含最早的冷却过期时间。 +5. 在重试开始前持久化选中的回退覆盖，这样其他会话读取方会看到运行器即将使用的同一提供商 / 模型。 +6. 如果回退候选项失败，则仅回滚那些由回退拥有的会话覆盖字段，并且仅当它们仍匹配该失败候选项时才回滚。 +7. 如果所有候选项都失败，则抛出带有每次尝试详情及最早冷却到期时间（如果已知）的 `FallbackSummaryError`。 -这有意比“保存并恢复整个会话”更窄。回复运行器只会持久化它为回退所拥有的模型选择字段： +这刻意比“保存并恢复整个会话”更窄。回复运行器只会持久化它为回退所拥有的模型选择字段： - `providerOverride` - `modelOverride` @@ -56,108 +53,110 @@ OpenClaw 分两个阶段处理失败： - `authProfileOverrideSource` - `authProfileOverrideCompactionCount` -这样可以防止一次失败的回退重试覆盖掉更新的无关会话变更， -例如在尝试运行期间发生的手动 `/model` 更改或会话轮换更新。 +这样可以防止一次失败的回退重试覆盖更新较新的、无关的会话变更， +例如手动 `/model` 更改或在尝试运行期间发生的会话轮换更新。 -## 认证存储（keys + OAuth） +## 凭证存储（密钥 + OAuth） -OpenClaw 对 API key 和 OAuth token 都使用**认证配置档案**。 +OpenClaw 对 API 密钥和 OAuth 令牌都使用**凭证配置文件**。 -- 密钥存储在 `~/.openclaw/agents//agent/auth-profiles.json`（旧版位置：`~/.openclaw/agent/auth-profiles.json`）。 -- 配置 `auth.profiles` / `auth.order` **仅用于元数据 + 路由**（不包含密钥）。 -- 旧版仅导入 OAuth 文件：`~/.openclaw/credentials/oauth.json`（首次使用时会导入到 `auth-profiles.json`）。 +- 密钥存储在 `~/.openclaw/agents//agent/auth-profiles.json`（旧版：`~/.openclaw/agent/auth-profiles.json`）。 +- 运行时凭证路由状态存储在 `~/.openclaw/agents//agent/auth-state.json`。 +- 配置 `auth.profiles` / `auth.order` **仅用于元数据 + 路由**（不存储密钥）。 +- 仅用于旧版导入的 OAuth 文件：`~/.openclaw/credentials/oauth.json`（首次使用时会导入到 `auth-profiles.json`）。 -更多细节：[/concepts/oauth](/concepts/oauth) +更多细节：[/concepts/oauth](/zh-CN/concepts/oauth) 凭证类型： - `type: "api_key"` → `{ provider, key }` -- `type: "oauth"` → `{ provider, access, refresh, expires, email? }`（某些提供商还包括 `projectId`/`enterpriseUrl`） +- `type: "oauth"` → `{ provider, access, refresh, expires, email? }`（某些提供商还会包含 `projectId` / `enterpriseUrl`） -## 配置档案 ID +## 配置文件 ID -OAuth 登录会创建不同的配置档案，以便多个账号可以共存。 +OAuth 登录会创建不同的配置文件，以便多个账户可以共存。 -- 默认：当没有 email 可用时使用 `provider:default`。 -- 带 email 的 OAuth：`provider:`（例如 `google-antigravity:user@gmail.com`）。 +- 默认值：当没有可用邮箱时为 `provider:default`。 +- 带邮箱的 OAuth：`provider:`（例如 `google-antigravity:user@gmail.com`）。 -配置档案位于 `~/.openclaw/agents//agent/auth-profiles.json` 的 `profiles` 下。 +配置文件位于 `~/.openclaw/agents//agent/auth-profiles.json` 的 `profiles` 下。 ## 轮换顺序 -当一个提供商拥有多个配置档案时，OpenClaw 会按如下方式选择顺序： +当一个提供商有多个配置文件时，OpenClaw 会按如下方式决定顺序： 1. **显式配置**：`auth.order[provider]`（如果已设置）。 -2. **已配置配置档案**：按提供商过滤后的 `auth.profiles`。 -3. **已存储配置档案**：`auth-profiles.json` 中该提供商的条目。 +2. **已配置的配置文件**：按提供商过滤后的 `auth.profiles`。 +3. **已存储的配置文件**：`auth-profiles.json` 中该提供商对应的条目。 如果没有配置显式顺序，OpenClaw 会使用轮询顺序： -- **主排序键：** 配置档案类型（**OAuth 优先于 API key**）。 -- **次排序键：** `usageStats.lastUsed`（在每种类型内，最久未使用的优先）。 -- **冷却中/已禁用配置档案** 会移到末尾，并按最早到期时间排序。 +- **主排序键：** 配置文件类型（**OAuth 优先于 API 密钥**）。 +- **次排序键：** `usageStats.lastUsed`（越久未使用越靠前，同类型内排序）。 +- **处于冷却 / 已禁用的配置文件** 会被移到末尾，并按最早到期时间排序。 -### 会话粘性（有利于缓存） +### 会话粘性（对缓存更友好） -OpenClaw 会**按会话固定所选认证配置档案**，以保持提供商缓存处于热状态。 -它**不会**对每个请求都进行轮换。固定的配置档案会一直复用，直到： +OpenClaw 会**为每个会话固定所选的凭证配置文件**，以保持提供商缓存处于预热状态。 +它**不会**在每次请求时轮换。固定的配置文件会被重复使用，直到： - 会话被重置（`/new` / `/reset`） -- 一次压缩完成（压缩计数递增） -- 该配置档案处于冷却中/已禁用 +- 一次压缩完成（压缩计数增加） +- 该配置文件处于冷却 / 已禁用状态 -通过 `/model …@` 手动选择会为该会话设置一个**用户覆盖**， +通过 `/model …@` 进行手动选择会为该会话设置一个**用户覆盖**， 在新会话开始前不会自动轮换。 -自动固定的配置档案（由会话路由器选择）会被视为一种**偏好**： -它们会被优先尝试，但在遭遇限流/超时时，OpenClaw 可以轮换到其他配置档案。 -用户固定的配置档案会锁定在该配置档案上；如果它失败，并且配置了模型回退， -OpenClaw 会转到下一个模型，而不是切换配置档案。 +自动固定的配置文件（由会话路由器选中）被视为一种**偏好**： +它们会被优先尝试，但 OpenClaw 可能会在遇到速率限制 / 超时时轮换到其他配置文件。 +用户固定的配置文件会保持锁定在该配置文件；如果它失败且已配置模型回退， +OpenClaw 会移动到下一个模型，而不是切换配置文件。 -### 为什么 OAuth 看起来会“丢失” +### 为什么 OAuth 可能“看起来丢了” -如果同一提供商下同时存在 OAuth 配置档案和 API key 配置档案，轮询可能会在消息之间来回切换它们，除非已固定。要强制使用单一配置档案： +如果你对同一个提供商同时拥有一个 OAuth 配置文件和一个 API 密钥配置文件，在未固定时，轮询可能会在不同消息之间切换它们。若要强制使用单一配置文件： - 使用 `auth.order[provider] = ["provider:profileId"]` 固定，或 -- 使用每会话覆盖，通过带配置档案覆盖的 `/model …`（当你的 UI/聊天界面支持时）。 +- 通过 `/model …` 使用带配置文件覆盖的按会话覆盖（当你的 UI / 聊天界面支持时）。 -## 冷却期 +## 冷却时间 -当某个配置档案因认证/限流错误失败时（或者看起来像 -限流的超时），OpenClaw 会将其标记为进入冷却期，并切换到下一个配置档案。 -这个限流桶不仅包括普通的 `429`：还包括提供商 -消息，例如 `Too many concurrent requests`、`ThrottlingException`、 +当某个配置文件因凭证 / 速率限制错误（或看起来像速率限制的超时） +而失败时，OpenClaw 会将其标记为冷却中，并切换到下一个配置文件。 +这个速率限制分类比单纯的 `429` 更宽：它还包括提供商消息， +例如 `Too many concurrent requests`、`ThrottlingException`、 `concurrency limit reached`、`workers_ai ... quota limit exceeded`、 -`throttled`、`resource exhausted`，以及周期性的用量窗口限制，例如 -`weekly/monthly limit reached`。 -格式/无效请求错误（例如 Cloud Code Assist 工具调用 ID -校验失败）会被视为值得触发故障切换，并使用相同的冷却期。 -兼容 OpenAI 的 stop-reason 错误，例如 `Unhandled stop reason: error`、 -`stop reason: error` 和 `reason: error`，会被归类为超时/故障切换 +`throttled`、`resource exhausted`，以及周期性使用窗口限制， +例如 `weekly/monthly limit reached`。 +格式 / 无效请求错误（例如 Cloud Code Assist 工具调用 ID +校验失败）也会被视为值得故障切换，并使用相同的冷却时间。 +OpenAI 兼容的停止原因错误，例如 `Unhandled stop reason: error`、 +`stop reason: error` 和 `reason: error`，会被归类为超时 / 故障切换 信号。 -提供商作用域的通用服务器文本在源头匹配已知瞬时模式时，也可能归入该超时桶。例如，Anthropic 的裸 -`An unknown error occurred` 以及带有瞬时服务器文本的 JSON `api_error` -负载，例如 `internal server error`、`unknown error, 520`、`upstream error` -或 `backend error`，都会被视为值得触发故障切换的超时。 -OpenRouter 特有的通用上游文本，例如裸 `Provider returned error`，也仅在 -提供商上下文确实是 OpenRouter 时才会被视为超时。 +当来源匹配已知瞬态模式时，提供商范围的通用服务器文本也会归入该超时分类。 +例如，Anthropic 的裸文本 +`An unknown error occurred` 以及带有瞬态服务器文本的 JSON `api_error` +载荷，例如 `internal server error`、`unknown error, 520`、`upstream error` +或 `backend error`，都会被视为值得故障切换的超时。 +OpenRouter 特有的通用上游文本，例如裸文本 `Provider returned error`， +只有在提供商上下文确实是 OpenRouter 时才会被视为超时。 通用的内部回退文本，例如 `LLM request failed with an unknown error.`， 则保持保守，不会单独触发故障切换。 -限流冷却期也可以是模型作用域的： +速率限制冷却也可以按模型划分范围： -- 当已知失败模型 id 时，对于限流失败，OpenClaw 会记录 `cooldownModel`。 -- 同一提供商上的兄弟模型如果冷却期被限制在另一个模型上，仍然可以尝试。 -- 计费/禁用窗口仍会跨模型阻止整个配置档案。 +- 当已知失败的模型 ID 时，OpenClaw 会为速率限制失败记录 `cooldownModel`。 +- 当冷却限定在不同模型上时，同一提供商上的兄弟模型仍可被尝试。 +- 计费 / 已禁用窗口仍会在所有模型上阻止整个配置文件。 -冷却期使用指数退避： +冷却时间使用指数退避： - 1 分钟 - 5 分钟 - 25 分钟 - 1 小时（上限） -状态存储在 `auth-profiles.json` 的 `usageStats` 下： +状态存储在 `auth-state.json` 的 `usageStats` 下： ```json { @@ -173,17 +172,15 @@ OpenRouter 特有的通用上游文本，例如裸 `Provider returned error`， ## 计费禁用 -计费/额度失败（例如“insufficient credits” / “credit balance too low”）会被视为值得触发故障切换，但它们通常不是瞬时错误。OpenClaw 不会使用短冷却期，而是将该配置档案标记为**已禁用**（采用更长退避），然后轮换到下一个配置档案/提供商。 +计费 / 额度失败（例如“insufficient credits” / “credit balance too low”）会被视为值得故障切换，但它们通常不是瞬态错误。OpenClaw 不会设置短暂冷却，而是会将该配置文件标记为**已禁用**（使用更长的退避时间），并轮换到下一个配置文件 / 提供商。 -并不是每个看起来像计费问题的响应都是 `402`，也不是每个 HTTP `402` 都会落到 -这里。即使提供商返回的是 `401` 或 `403`，OpenClaw 也会将明确的计费文本保留在计费通道中，但提供商特定匹配器仍然局限于拥有它们的提供商（例如 OpenRouter 的 `403 Key limit -exceeded`）。与此同时，临时性的 `402` 用量窗口和 -组织/工作区支出上限错误，如果消息看起来可以重试（例如 `weekly usage limit exhausted`、`daily -limit reached, resets tomorrow` 或 `organization spending limit exceeded`），则会被归类为 `rate_limit`。 -这些情况会走短冷却/故障切换路径，而不是长时间的 -计费禁用路径。 +并非每个看起来像计费问题的响应都是 `402`，也并非每个 HTTP `402` +都会归入这里。即使提供商返回的是 `401` 或 `403`，OpenClaw 仍会将明确的计费文本保留在计费分类中，但提供商特定匹配器仍仅限于拥有它们的提供商（例如 OpenRouter 的 `403 Key limit exceeded`）。 +与此同时，临时性的 `402` 使用窗口和组织 / 工作区支出限制错误，如果消息看起来可重试（例如 `weekly usage limit exhausted`、`daily limit reached, resets tomorrow` 或 `organization spending limit exceeded`），则会被归类为 `rate_limit`。 +这些情况会继续走短冷却 / 故障切换路径，而不是长时间的 +计费禁用途径。 -状态存储在 `auth-profiles.json` 中： +状态存储在 `auth-state.json` 中： ```json { @@ -198,63 +195,54 @@ limit reached, resets tomorrow` 或 `organization spending limit exceeded`）， 默认值： -- 计费退避从 **5 小时**开始，每次计费失败翻倍，并在 **24 小时**封顶。 -- 如果某个配置档案在 **24 小时**内没有失败，退避计数器会重置（可配置）。 -- 过载重试允许在模型回退前进行 **1 次同提供商配置档案轮换**。 -- 过载重试默认使用 **0 ms 退避**。 +- 计费退避从 **5 小时**开始，每次计费失败后翻倍，并在 **24 小时**封顶。 +- 如果配置文件在 **24 小时**内未再失败，退避计数器会重置（可配置）。 +- 过载重试在模型回退前允许进行 **1 次同提供商配置文件轮换**。 +- 过载重试默认使用 **0 毫秒退避**。 ## 模型回退 -如果某个提供商的所有配置档案都失败，OpenClaw 会转到 -`agents.defaults.model.fallbacks` 中的下一个模型。这适用于认证失败、限流，以及 -耗尽配置档案轮换的超时（其他错误不会推进回退）。 +如果某个提供商的所有配置文件都失败，OpenClaw 会移动到 +`agents.defaults.model.fallbacks` 中的下一个模型。这适用于凭证失败、速率限制，以及耗尽配置文件轮换后的超时（其他错误不会推进回退）。 -与计费冷却相比，过载和限流错误处理得更激进。 -默认情况下，OpenClaw 允许一次同提供商认证配置档案重试， -然后立即切换到下一个已配置模型回退，无需等待。 -提供商繁忙信号，例如 `ModelNotReadyException`，会落入该过载 -桶。可通过 `auth.cooldowns.overloadedProfileRotations`、 +过载和速率限制错误的处理比计费冷却更激进。默认情况下， +OpenClaw 允许一次同提供商凭证配置文件重试，然后立即切换到下一个已配置的模型回退，无需等待。 +提供商繁忙信号，例如 `ModelNotReadyException`，会归入该过载分类。 +你可以使用 `auth.cooldowns.overloadedProfileRotations`、 `auth.cooldowns.overloadedBackoffMs` 和 -`auth.cooldowns.rateLimitedProfileRotations` 调整此行为。 +`auth.cooldowns.rateLimitedProfileRotations` 进行调整。 当一次运行以模型覆盖开始时（hooks 或 CLI），在尝试完任何已配置回退后， 回退仍会以 `agents.defaults.model.primary` 结束。 ### 候选链规则 -OpenClaw 会根据当前请求的 `provider/model` -和已配置回退构建候选列表。 +OpenClaw 会根据当前请求的 `provider/model` 与已配置回退构建候选列表。 规则： -- 请求的模型始终位于第一位。 -- 显式配置的回退会去重，但不会按模型 - allowlist 过滤。它们被视为显式的操作员意图。 -- 如果当前运行已经位于同一提供商家族中的某个已配置回退上， - OpenClaw 会继续使用完整的已配置链。 -- 如果当前运行所在的提供商与配置不同，并且当前 - 模型尚未成为已配置回退链的一部分，OpenClaw 不会 - 追加来自其他提供商的无关已配置回退。 -- 当运行从覆盖开始时，已配置的主模型会追加到 - 末尾，以便在前面的候选项耗尽后，候选链可以回到正常默认值。 +- 请求的模型始终排在第一位。 +- 显式配置的回退会去重，但不会按模型允许列表过滤。它们被视为运维方的显式意图。 +- 如果当前运行已经在同一提供商家族中的某个已配置回退上，OpenClaw 会继续使用完整的已配置链。 +- 如果当前运行所在的提供商与配置不同，并且该当前模型尚未包含在已配置回退链中，OpenClaw 不会附加来自其他提供商的无关已配置回退。 +- 当运行起始于某个覆盖设置时，已配置的主模型会附加到末尾，这样在较早候选项耗尽后，候选链可以回到正常默认值。 ### 哪些错误会推进回退 模型回退会在以下情况继续： -- 认证失败 -- 限流和冷却期耗尽 -- 过载/提供商繁忙错误 -- 看起来像超时的故障切换错误 +- 凭证失败 +- 速率限制和冷却耗尽 +- 过载 / 提供商繁忙错误 +- 类超时的故障切换错误 - 计费禁用 -- `LiveSessionModelSwitchError`，它会被规范化为故障切换路径，因此 - 过时的持久化模型不会产生外层重试循环 -- 当仍有剩余候选项时，其他未识别错误 +- `LiveSessionModelSwitchError`，它会被规范化为故障切换路径，这样过时的持久化模型就不会形成外层重试循环 +- 当仍有剩余候选项时，其他无法识别的错误 模型回退不会在以下情况继续： -- 非超时/非故障切换形态的显式中止 -- 应留在压缩/重试逻辑中的上下文溢出错误 +- 不属于超时 / 故障切换形态的显式中止 +- 应保留在压缩 / 重试逻辑内部的上下文溢出错误 （例如 `request_too_large`、`INVALID_ARGUMENT: input exceeds the maximum number of tokens`、`input token count exceeds the maximum number of input tokens`、`The input is too long for the model` 或 `ollama error: context @@ -263,73 +251,56 @@ length exceeded`） ### 冷却跳过与探测行为 -当某个提供商的所有认证配置档案都已经处于冷却期时，OpenClaw 并不会 -自动永远跳过该提供商。它会按每个候选项做决定： +当某个提供商的所有凭证配置文件都已经处于冷却中时，OpenClaw 不会自动永久跳过该提供商。它会针对每个候选项单独决策： -- 持久性认证失败会立即跳过整个提供商。 -- 计费禁用通常会跳过，但主候选项仍可能在节流条件下被探测， - 以便无需重启即可恢复。 -- 主候选项可能会在冷却期接近到期时被探测，并带有按提供商划分的节流。 -- 即使处于冷却期，同提供商的回退兄弟项也可以尝试，只要 - 失败看起来是瞬时的（`rate_limit`、`overloaded` 或 unknown）。 - 当限流是模型作用域且某个兄弟模型仍可能立即恢复时，这一点尤其相关。 -- 瞬时冷却探测在每次回退运行中每个提供商最多仅限一次，因此 - 单个提供商不会拖慢跨提供商回退。 +- 持续性的凭证失败会立即跳过整个提供商。 +- 计费禁用通常会跳过，但主候选项仍可能在节流条件下被探测，以便无需重启也能恢复。 +- 在接近冷却到期时，主候选项可能会被探测，并带有按提供商区分的节流限制。 +- 即使存在冷却，同提供商的回退兄弟项在失败看起来是瞬态时（`rate_limit`、`overloaded` 或未知）仍可被尝试。当速率限制是模型范围时，而兄弟模型可能仍可立即恢复，这一点尤其重要。 +- 瞬态冷却探测在每次回退运行中每个提供商最多仅允许一次，因此单个提供商不会拖慢跨提供商回退。 ## 会话覆盖与实时模型切换 -会话模型更改是共享状态。活动运行器、`/model` 命令、 -压缩/会话更新，以及实时会话协调，都会读取或写入同一个会话条目的不同部分。 +会话模型更改属于共享状态。活动运行器、`/model` 命令、 +压缩 / 会话更新，以及实时会话协调逻辑都会读取或写入同一个会话条目的不同部分。 这意味着回退重试必须与实时模型切换协调： -- 只有显式的用户驱动模型更改才会标记待处理的实时切换。包括 - `/model`、`session_status(model=...)` 和 `sessions.patch`。 -- 系统驱动的模型更改，例如回退轮换、heartbeat 覆盖， - 或压缩，本身不会标记待处理的实时切换。 -- 在回退重试开始前，回复运行器会将选中的 - 回退覆盖字段持久化到会话条目。 -- 实时会话协调会优先采用持久化的会话覆盖，而不是过时的 - 运行时模型字段。 -- 如果回退尝试失败，运行器只会回滚它写入的覆盖字段， - 并且仅在这些字段仍然与该失败候选项匹配时才会回滚。 +- 只有显式的用户驱动模型更改才会标记待处理的实时切换。这包括 `/model`、`session_status(model=...)` 和 `sessions.patch`。 +- 由系统驱动的模型更改，例如回退轮换、心跳覆盖或压缩，不会自行标记待处理的实时切换。 +- 在回退重试开始前，回复运行器会将选中的回退覆盖字段持久化到会话条目中。 +- 实时会话协调会优先使用持久化的会话覆盖，而不是过时的运行时模型字段。 +- 如果回退尝试失败，运行器只会回滚它写入的覆盖字段，并且仅当这些字段仍匹配该失败候选项时才会回滚。 -这可以防止经典竞态： +这可以防止经典竞争条件： 1. 主模型失败。 -2. 在内存中选中了回退候选项。 -3. 会话存储仍然显示旧的主模型。 +2. 回退候选项在内存中被选中。 +3. 会话存储仍显示旧的主模型。 4. 实时会话协调读取了过时的会话状态。 -5. 在回退尝试开始前，重试被拉回到旧模型。 +5. 在回退尝试开始前，重试又被拉回旧模型。 -持久化的回退覆盖封闭了这个窗口，而窄范围回滚 -则能保持较新的手动或运行时会话更改不被破坏。 +持久化的回退覆盖封住了这个窗口，而范围收窄的回滚则能保持更新的手动或运行时会话更改不受影响。 ## 可观测性与失败摘要 -`runWithModelFallback(...)` 会记录逐次尝试的细节，用于日志和 -面向用户的冷却期消息： +`runWithModelFallback(...)` 会记录每次尝试的详细信息，以供日志记录和面向用户的冷却消息使用： -- 尝试的提供商/模型 -- 原因（`rate_limit`、`overloaded`、`billing`、`auth`、`model_not_found` 以及 - 类似的故障切换原因） -- 可选的状态/代码 +- 尝试过的提供商 / 模型 +- 原因（`rate_limit`、`overloaded`、`billing`、`auth`、`model_not_found` 以及类似的故障切换原因） +- 可选的状态 / 代码 - 人类可读的错误摘要 -当所有候选项都失败时，OpenClaw 会抛出 `FallbackSummaryError`。外层 -回复运行器可利用它构建更具体的消息，例如“所有模型 -暂时都受到限流”，并在已知时包含最早的冷却过期时间。 +当所有候选项都失败时，OpenClaw 会抛出 `FallbackSummaryError`。外层回复运行器可以据此构建更具体的消息，例如“所有模型当前都受到临时速率限制”，并在已知时包含最早的冷却到期时间。 该冷却摘要是模型感知的： -- 与所尝试的 - 提供商/模型链无关的模型作用域限流会被忽略 -- 如果剩余阻塞是匹配的模型作用域限流，OpenClaw - 会报告最后一个仍然阻止该模型的匹配到期时间 +- 对于已尝试的提供商 / 模型链，无关的模型范围速率限制会被忽略 +- 如果剩余阻塞是匹配的模型范围速率限制，OpenClaw 会报告仍阻止该模型的最后一个匹配到期时间 ## 相关配置 -参见 [Gateway 网关配置](/gateway/configuration) 了解： +有关以下内容，请参见 [Gateway 网关配置](/zh-CN/gateway/configuration)： - `auth.profiles` / `auth.order` - `auth.cooldowns.billingBackoffHours` / `auth.cooldowns.billingBackoffHoursByProvider` @@ -339,4 +310,4 @@ length exceeded`） - `agents.defaults.model.primary` / `agents.defaults.model.fallbacks` - `agents.defaults.imageModel` 路由 -参见 [Models](/concepts/models) 了解更广泛的模型选择和回退概览。 +有关更广泛的模型选择与回退概览，请参见 [模型](/zh-CN/concepts/models)。 diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index 84c4c5e90..cf7d5de8d 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -5,10 +5,10 @@ read_when: summary: 模型提供商概览，包含示例配置和 CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-06T12:44:06Z" + generated_at: "2026-04-06T15:29:17Z" model: gpt-5.4 provider: openai - source_hash: ec33cbfeec86c3f79ea0ec38932eebb819eba5932024b73fcf3acbc41fbce203 + source_hash: a9c1f7f8cf09b6047a64189f7440811aafc93d01335f76969afd387cc54c7ab5 source_path: concepts/model-providers.md workflow: 15 --- @@ -20,21 +20,16 @@ x-i18n: ## 快速规则 -- 模型引用使用 `provider/model`（例如：`opencode/claude-opus-4-6`）。 -- 如果你设置了 `agents.defaults.models`，它就会成为允许列表。 +- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。 +- 如果你设置了 `agents.defaults.models`，它将成为允许列表。 - CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 -- 回退运行时规则、冷却探测和会话覆盖持久化 - 记录于 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 +- 运行时回退规则、冷却探测和会话覆盖持久化已在 [/concepts/model-failover](/zh-CN/concepts/model-failover) 中说明。 - `models.providers.*.models[].contextWindow` 是原生模型元数据； - `models.providers.*.models[].contextTokens` 是实际运行时上限。 + `models.providers.*.models[].contextTokens` 是运行时生效上限。 - 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录； - OpenClaw 会在写入 - `models.json` 之前将该输出合并到 `models.providers` 中。 -- 提供商清单可以声明 `providerAuthEnvVars`，这样通用的基于环境变量的 - 凭证探测就不需要加载插件运行时。剩余的核心环境变量 - 映射现在只用于非插件/核心提供商以及少数通用优先级 - 场景，例如 Anthropic 以 API 密钥优先的新手引导。 -- 提供商插件还可以通过以下方式拥有提供商运行时行为： + OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。 +- 提供商清单可以声明 `providerAuthEnvVars`，这样基于通用环境变量的凭证探测就不需要加载插件运行时。剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic 以 API 密钥优先的新手引导。 +- 提供商插件还可以通过 `normalizeModelId`、`normalizeTransport`、`normalizeConfig`、 `applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、 `resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、 @@ -50,196 +45,110 @@ x-i18n: `isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、 `augmentModelCatalog`、`isBinaryThinking`、`supportsXHighThinking`、 `resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、 - `prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot`，以及 - `onModelSelected`。 -- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商 - 家族、转录/工具怪癖、传输/缓存提示）。它不同于 - [公开能力模型](/zh-CN/plugins/architecture#public-capability-model)， - 后者描述的是插件注册了什么能力（文本推理、语音等）。 + `prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 以及 + `onModelSelected` + 来管理提供商运行时行为。 +- 注意：提供商运行时 `capabilities` 是共享执行器元数据（提供商家族、转录/工具特性、传输/缓存提示）。它与[公共能力模型](/zh-CN/plugins/architecture#public-capability-model)不同，后者描述的是插件注册了什么能力（文本推理、语音等）。 ## 插件拥有的提供商行为 -提供商插件现在可以拥有大多数提供商特定逻辑，而 OpenClaw 保持 -通用推理循环。 +提供商插件现在可以拥有大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。 典型划分： -- `auth[].run` / `auth[].runNonInteractive`：提供商拥有 `openclaw onboard`、`openclaw models auth` 和无头设置的 - 新手引导/登录流程 -- `wizard.setup` / `wizard.modelPicker`：提供商拥有凭证选择标签、 - 旧别名、新手引导允许列表提示，以及新手引导/模型选择器中的设置条目 +- `auth[].run` / `auth[].runNonInteractive`：提供商拥有 `openclaw onboard`、`openclaw models auth` 和无头设置的引导/登录流程 +- `wizard.setup` / `wizard.modelPicker`：提供商拥有凭证选择标签、旧别名、新手引导允许列表提示，以及新手引导/模型选择器中的设置项 - `catalog`：提供商会出现在 `models.providers` 中 -- `normalizeModelId`：提供商在查找或规范化之前 - 归一化旧版/预览模型 id -- `normalizeTransport`：提供商会在通用模型组装之前归一化传输族的 `api` / `baseUrl`； - OpenClaw 会先检查匹配的提供商， - 然后检查其他具备 hook 能力的提供商插件，直到其中一个 - 实际修改了传输 -- `normalizeConfig`：提供商会在运行时使用前归一化 `models.providers.` 配置； - OpenClaw 会先检查匹配的提供商， - 然后检查其他具备 hook 能力的提供商插件，直到其中一个 - 实际修改了配置。如果没有 - 提供商 hook 重写配置，内置的 Google 家族辅助逻辑仍会 - 归一化受支持的 Google 提供商条目。 -- `applyNativeStreamingUsageCompat`：提供商为配置型提供商应用由端点驱动的原生流式使用量兼容性重写 -- `resolveConfigApiKey`：提供商为配置型提供商解析环境变量标记凭证， - 无需强制加载完整运行时凭证。`amazon-bedrock` 在这里也有一个 - 内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 - AWS SDK 默认链。 -- `resolveSyntheticAuth`：提供商可以暴露本地/自托管或其他 - 基于配置的凭证可用性，而不持久化明文密钥 -- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置档占位符 - 标记为低于环境变量/配置型凭证的优先级 -- `resolveDynamicModel`：提供商接受本地 - 静态目录中尚未存在的模型 id -- `prepareDynamicModel`：提供商在重试动态解析之前 - 需要刷新元数据 -- `normalizeResolvedModel`：提供商需要传输或 base URL 重写 -- `contributeResolvedModelCompat`：即使其 - 厂商模型是通过另一种兼容传输到达的，提供商也会为其贡献兼容标志 -- `capabilities`：提供商发布转录/工具/提供商家族怪癖 -- `normalizeToolSchemas`：提供商在内嵌 - 运行器看到工具 schema 之前进行清理 -- `inspectToolSchemas`：提供商在归一化后暴露传输特定的 schema 警告 -- `resolveReasoningOutputMode`：提供商选择原生还是带标签的 - 推理输出契约 -- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行归一化 -- `createStreamFn`：提供商用完全 - 自定义的传输替换正常流式路径 +- `normalizeModelId`：提供商在查找或规范化之前标准化旧版/预览模型 id +- `normalizeTransport`：提供商在通用模型组装前标准化传输族 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后检查其他具备该 hook 能力的提供商插件，直到其中一个实际更改了传输 +- `normalizeConfig`：提供商在运行时使用前标准化 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，然后检查其他具备该 hook 能力的提供商插件，直到其中一个实际更改了配置。如果没有提供商 hook 重写配置，内置的 Google 家族辅助逻辑仍会标准化受支持的 Google 提供商条目。 +- `applyNativeStreamingUsageCompat`：提供商对配置型提供商应用由端点驱动的原生流式使用量兼容性重写 +- `resolveConfigApiKey`：提供商为配置型提供商解析基于环境变量标记的凭证，而无需强制加载完整运行时凭证。`amazon-bedrock` 在这里还有一个内置的 AWS 环境变量标记解析器，即使 Bedrock 运行时凭证使用的是 AWS SDK 默认链。 +- `resolveSyntheticAuth`：提供商可以公开本地/自托管或其他基于配置的凭证可用性，而无需持久化明文密钥 +- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置文件占位符标记为低于环境变量/配置支持凭证的优先级 +- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 id +- `prepareDynamicModel`：提供商在重试动态解析前需要刷新元数据 +- `normalizeResolvedModel`：提供商需要重写传输或 base URL +- `contributeResolvedModelCompat`：即使其厂商模型是通过另一种兼容传输到达，提供商也能为其贡献兼容标记 +- `capabilities`：提供商发布转录/工具/提供商家族特性 +- `normalizeToolSchemas`：提供商在嵌入式执行器看到工具 schema 之前先进行清理 +- `inspectToolSchemas`：提供商在标准化后暴露传输特定的 schema 警告 +- `resolveReasoningOutputMode`：提供商选择原生或带标签的推理输出契约 +- `prepareExtraParams`：提供商为每个模型的请求参数提供默认值或进行标准化 +- `createStreamFn`：提供商用完全自定义的传输替换常规流路径 - `wrapStreamFn`：提供商应用请求头/请求体/模型兼容包装器 -- `resolveTransportTurnState`：提供商提供每轮原生传输的 - 请求头或元数据 -- `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话 - 请求头或会话冷却策略 -- `createEmbeddingProvider`：当内存嵌入行为 - 更适合归属于提供商插件而不是核心嵌入切换层时，由提供商负责 -- `formatApiKey`：提供商将已存储的凭证配置档格式化为 - 传输所需的运行时 `apiKey` 字符串 -- `refreshOAuth`：当共享的 `pi-ai` - 刷新器不足时，由提供商负责 OAuth 刷新 -- `buildAuthDoctorHint`：当 OAuth 刷新 - 失败时，提供商追加修复指引 -- `matchesContextOverflowError`：提供商识别提供商特定的 - 上下文窗口溢出错误，而通用启发式无法识别这些错误 -- `classifyFailoverReason`：提供商将提供商特定的原始传输/API - 错误映射为回退原因，例如速率限制或过载 +- `resolveTransportTurnState`：提供商提供每轮原生传输头或元数据 +- `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话头或会话冷却策略 +- `createEmbeddingProvider`：当内存嵌入行为更适合归属提供商插件而不是核心嵌入切换板时，由提供商拥有它 +- `formatApiKey`：提供商将已存储的凭证配置文件格式化为传输所需的运行时 `apiKey` 字符串 +- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足时，由提供商负责 OAuth 刷新 +- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商附加修复指导 +- `matchesContextOverflowError`：提供商识别通用启发式会漏掉的提供商特定上下文窗口溢出错误 +- `classifyFailoverReason`：提供商将提供商特定的原始传输/API 错误映射为速率限制或过载等回退原因 - `isCacheTtlEligible`：提供商决定哪些上游模型 id 支持提示缓存 TTL -- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示 - 替换通用的凭证存储错误 -- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在 - 直接解析失败时返回厂商拥有的错误 -- `augmentModelCatalog`：提供商在 - 发现和配置合并之后追加合成/最终目录条目 +- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用凭证存储错误 +- `suppressBuiltInModel`：提供商隐藏陈旧的上游条目，并可在直接解析失败时返回厂商拥有的错误 +- `augmentModelCatalog`：在发现和配置合并后，提供商附加合成/最终目录条目 - `isBinaryThinking`：提供商拥有二元开/关思考 UX - `supportsXHighThinking`：提供商让选定模型支持 `xhigh` -- `resolveDefaultThinkingLevel`：提供商拥有某个 - 模型家族的默认 `/think` 策略 -- `applyConfigDefaults`：提供商在配置具体化期间，根据凭证模式、 - 环境变量或模型家族应用提供商特定的全局默认值 -- `isModernModelRef`：提供商拥有实时/冒烟优选模型匹配 -- `prepareRuntimeAuth`：提供商将已配置的凭证转换为短期 - 运行时令牌 -- `resolveUsageAuth`：提供商为 `/usage` - 及相关状态/报告界面解析用量/配额凭证 -- `fetchUsageSnapshot`：提供商拥有用量端点的抓取/解析逻辑， - 而核心仍然拥有摘要外壳与格式化 -- `onModelSelected`：提供商运行选择模型后的副作用，例如 - 遥测或由提供商拥有的会话记账 +- `resolveDefaultThinkingLevel`：提供商拥有某个模型家族的默认 `/think` 策略 +- `applyConfigDefaults`：提供商根据凭证模式、环境变量或模型家族，在配置具体化期间应用提供商特定的全局默认值 +- `isModernModelRef`：提供商拥有 live/smoke 首选模型匹配 +- `prepareRuntimeAuth`：提供商把已配置的凭证转换为短时效运行时令牌 +- `resolveUsageAuth`：提供商为 `/usage` 及相关状态/报告界面解析使用量/配额凭证 +- `fetchUsageSnapshot`：提供商拥有使用量端点的获取/解析逻辑，而核心仍拥有摘要外壳和格式化 +- `onModelSelected`：提供商运行选择模型后的副作用，例如遥测或提供商拥有的会话记账 当前内置示例： -- `anthropic`：Claude 4.6 向前兼容回退、凭证修复提示、用量 - 端点抓取、缓存 TTL/提供商家族元数据，以及具备凭证感知能力的全局 - 配置默认值 -- `amazon-bedrock`：由提供商拥有的上下文溢出匹配，以及针对 Bedrock 特定的节流/未就绪错误的回退 - 原因分类，另外还有共享的 `anthropic-by-model` 重放家族，用于 - Anthropic 流量上的仅 Claude 重放策略保护 -- `anthropic-vertex`：针对 Anthropic-message - 流量的仅 Claude 重放策略保护 -- `openrouter`：透传模型 id、请求包装器、提供商能力 - 提示、代理 Gemini 流量上的 Gemini thought-signature 清理、 - 通过 `openrouter-thinking` 流家族进行的代理推理注入、 - 路由元数据转发，以及缓存 TTL 策略 -- `github-copilot`：新手引导/设备登录、向前兼容模型回退、 - Claude-thinking 转录提示、运行时令牌交换，以及用量端点 - 抓取 -- `openai`：GPT-5.4 向前兼容回退、直接 OpenAI 传输 - 归一化、兼容 Codex 的缺失凭证提示、Spark 抑制、合成 - OpenAI/Codex 目录条目、thinking/live-model 策略、用量令牌别名 - 归一化（`input` / `output` 和 `prompt` / `completion` 家族）、共享的 - `openai-responses-defaults` 流家族，用于原生 OpenAI/Codex - 包装器、提供商家族元数据、为 `gpt-image-1` 注册的内置图像生成提供商， - 以及为 `sora-2` 注册的内置视频生成提供商 -- `google` 和 `google-gemini-cli`：Gemini 3.1 向前兼容回退、 - 原生 Gemini 重放校验、bootstrap 重放清理、带标签的 - 推理输出模式、现代模型匹配、为 Gemini image-preview 模型注册的内置图像生成 - 提供商，以及为 Veo 模型注册的内置 - 视频生成提供商；Gemini CLI OAuth 还 - 负责凭证配置档令牌格式化、用量令牌解析，以及面向用量界面的配额端点 - 抓取 -- `moonshot`：共享传输、由插件拥有的思考载荷归一化 -- `kilocode`：共享传输、由插件拥有的请求头、推理载荷 - 归一化、代理 Gemini thought-signature 清理，以及缓存 TTL - 策略 -- `zai`：GLM-5 向前兼容回退、`tool_stream` 默认值、缓存 TTL - 策略、二元思考/live-model 策略，以及用量凭证 + 配额抓取； - 未知的 `glm-5*` id 会从内置的 `glm-4.7` 模板合成 -- `xai`：原生 Responses 传输归一化、Grok 快速变体的 `/fast` 别名重写、 - 默认 `tool_stream`、xAI 特定的工具 schema / - 推理载荷清理，以及为 `grok-imagine-video` 注册的内置视频生成 - 提供商 -- `mistral`：由插件拥有的能力元数据 -- `opencode` 和 `opencode-go`：由插件拥有的能力元数据，加上 - 代理 Gemini thought-signature 清理 -- `alibaba`：用于直接 Wan 模型引用（例如 - `alibaba/wan2.6-t2v`）的由插件拥有的视频生成目录 -- `byteplus`：由插件拥有的目录，加上为 Seedance 文生视频/图生视频模型注册的内置 - 视频生成提供商 -- `fal`：为托管第三方 - 图像生成提供商注册的内置图像生成提供商，用于 FLUX 图像模型；以及为托管第三方视频模型注册的内置 - 视频生成提供商 +- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、使用量端点获取、缓存 TTL/提供商家族元数据，以及具备凭证感知能力的全局配置默认值 +- `amazon-bedrock`：提供商拥有的上下文溢出匹配，以及对 Bedrock 特定节流/未就绪错误的回退原因分类，外加共享的 `anthropic-by-model` 重放家族，用于 Claude 专属的 Anthropic 流量重放策略保护 +- `anthropic-vertex`：Anthropic 消息流量上的 Claude 专属重放策略保护 +- `openrouter`：透传模型 id、请求包装器、提供商能力提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族注入代理推理、转发路由元数据，以及缓存 TTL 策略 +- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude-thinking 转录提示、运行时令牌交换，以及使用量端点获取 +- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输标准化、面向 Codex 的缺失凭证提示、Spark 抑制、合成 OpenAI/Codex 目录条目、thinking/live-model 策略、使用量令牌别名标准化（`input` / `output` 和 `prompt` / `completion` 家族）、共享的 `openai-responses-defaults` 流家族用于原生 OpenAI/Codex 包装器、提供商家族元数据、为 `gpt-image-1` 注册的内置图像生成提供商，以及为 `sora-2` 注册的内置视频生成提供商 +- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、bootstrap 重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini image-preview 模型注册的内置图像生成提供商，以及为 Veo 模型注册的内置视频生成提供商；Gemini CLI OAuth 还拥有凭证配置文件令牌格式化、使用量令牌解析，以及用于使用量界面的配额端点获取 +- `moonshot`：共享传输、插件拥有的 thinking 负载标准化 +- `kilocode`：共享传输、插件拥有的请求头、推理负载标准化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略 +- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元 thinking/live-model 策略，以及使用量凭证 + 配额获取；未知的 `glm-5*` id 会从内置的 `glm-4.7` 模板合成 +- `xai`：原生 Responses 传输标准化、Grok fast 变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特定工具 schema / 推理负载清理，以及为 `grok-imagine-video` 注册的内置视频生成提供商 +- `mistral`：插件拥有的能力元数据 +- `opencode` 和 `opencode-go`：插件拥有的能力元数据，以及代理 Gemini thought-signature 清理 +- `alibaba`：针对直接 Wan 模型引用（如 `alibaba/wan2.6-t2v`）的插件拥有视频生成目录 +- `byteplus`：插件拥有的目录，以及为 Seedance 文生视频/图生视频模型注册的内置视频生成提供商 +- `fal`：为托管的第三方图像生成 FLUX 模型注册的内置图像生成提供商，以及为托管的第三方视频模型注册的内置视频生成提供商 - `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、 `stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`： - 仅由插件拥有目录 -- `qwen`：文本模型的由插件拥有目录，加上为其 - 多模态界面注册的共享 media-understanding 和视频生成提供商；Qwen 视频生成使用 - 标准 DashScope 视频端点，配合内置 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v` -- `runway`：为原生 - Runway 基于任务的模型（例如 `gen4.5`）注册的由插件拥有的视频生成提供商 -- `minimax`：由插件拥有目录、为 Hailuo 视频模型注册的内置视频生成提供商、 - 为 `image-01` 注册的内置图像生成提供商、混合 Anthropic/OpenAI 重放策略 - 选择，以及用量凭证/快照逻辑 -- `together`：由插件拥有目录，加上为 Wan 视频模型注册的内置视频生成 - 提供商 -- `xiaomi`：由插件拥有目录，加上用量凭证/快照逻辑 + 仅有插件拥有的目录 +- `qwen`：文本模型的插件拥有目录，以及为其多模态界面共享的 media-understanding 和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点和内置 Wan 模型，如 `wan2.6-t2v` 和 `wan2.7-r2v` +- `runway`：为原生 Runway 任务型模型（如 `gen4.5`）注册的插件拥有视频生成提供商 +- `minimax`：插件拥有的目录、为 Hailuo 视频模型注册的内置视频生成提供商、为 `image-01` 注册的内置图像生成提供商、混合 Anthropic/OpenAI 重放策略选择，以及使用量凭证/快照逻辑 +- `together`：插件拥有的目录，以及为 Wan 视频模型注册的内置视频生成提供商 +- `xiaomi`：插件拥有的目录，以及使用量凭证/快照逻辑 -内置的 `openai` 插件现在同时拥有这两个提供商 id：`openai` 和 +内置的 `openai` 插件现在拥有两个提供商 id：`openai` 和 `openai-codex`。 -以上涵盖了仍然适配 OpenClaw 正常传输的提供商。一个提供商 -如果需要完全自定义的请求执行器，则属于另一个更深层的扩展接口。 +以上涵盖了仍适合 OpenClaw 常规传输的提供商。需要完全自定义请求执行器的提供商，则属于另一类更深层的扩展接口。 ## API 密钥轮换 - 支持为选定提供商进行通用提供商轮换。 - 通过以下方式配置多个密钥： - - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） + - `OPENCLAW_LIVE__KEY`（单个 live 覆盖，优先级最高） - `_API_KEYS`（逗号或分号分隔列表） - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） - 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退包含在内。 -- 密钥选择顺序会保留优先级并去重。 -- 仅在速率限制响应时，请求才会使用下一个密钥重试（例如 - `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many -concurrent requests`、`ThrottlingException`、`concurrency limit reached`、 - `workers_ai ... quota limit exceeded` 或周期性的用量上限消息）。 +- 密钥选择顺序会保留优先级并去重值。 +- 仅在速率限制响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 或周期性的使用量限制消息）。 - 非速率限制失败会立即失败；不会尝试密钥轮换。 - 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。 ## 内置提供商（pi-ai 目录） -OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** -`models.providers` 配置；只需设置凭证并选择模型即可。 +OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** +`models.providers` 配置；只需设置凭证并选择一个模型。 ### OpenAI @@ -248,18 +157,17 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖） - 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro` - CLI：`openclaw onboard --auth-choice openai-api-key` -- 默认传输是 `auto`（WebSocket 优先，SSE 回退） -- 可通过 `agents.defaults.models["openai/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- OpenAI Responses WebSocket 预热默认启用，通过 `params.openaiWsWarmup` 控制（`true`/`false`） -- 可以通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先级处理 -- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射为 `api.openai.com` 上的 `service_tier=priority` -- 如果你想使用显式 tier，而不是共享的 `/fast` 开关，请使用 `params.serviceTier` +- 默认传输为 `auto`（优先 WebSocket，回退 SSE） +- 可通过 `agents.defaults.models["openai/"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`） +- 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先处理 +- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority` +- 当你想使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier` - 隐藏的 OpenClaw 归因请求头（`originator`、`version`、 - `User-Agent`）仅应用于发送到 `api.openai.com` 的原生 OpenAI 流量，不会应用于 - 通用 OpenAI 兼容代理 -- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示，以及 - OpenAI 推理兼容载荷整形；代理路由则不会 -- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 会拒绝它；Spark 被视为仅限 Codex + `User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理 +- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示以及 + OpenAI 推理兼容负载整形；代理路由则不会 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex ```json5 { @@ -274,9 +182,9 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖） - 示例模型：`anthropic/claude-opus-4-6` - CLI：`openclaw onboard --auth-choice apiKey` -- 直连公共 Anthropic 请求支持共享 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 凭证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`） -- 计费说明：对于 OpenClaw 中的 Anthropic，实际上的区分是**API 密钥**或**带 Extra Usage 的 Claude 订阅**。Anthropic 于 **2026 年 4 月 4 日太平洋时间中午 12:00 / 英国夏令时晚上 8:00** 通知 OpenClaw 用户，**OpenClaw** 的 Claude 登录路径被视为第三方 harness 用法，因此需要**额外用量**，并与订阅分开计费。我们的本地复现还显示，OpenClaw 标识提示字符串不会在 Anthropic SDK + API 密钥路径上复现。 -- Anthropic setup-token 现已再次作为旧版/手动 OpenClaw 路径可用。使用时请预期 Anthropic 已告知 OpenClaw 用户，此路径需要**额外用量**。 +- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`） +- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成下被认可的方式，除非 Anthropic 发布新政策。 +- Anthropic setup-token 仍作为受支持的 OpenClaw 令牌路径保留，但 OpenClaw 现在在可用时优先选择 Claude CLI 复用和 `claude -p`。 ```json5 { @@ -290,16 +198,16 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 凭证：OAuth（ChatGPT） - 示例模型：`openai-codex/gpt-5.4` - CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex` -- 默认传输是 `auto`（WebSocket 优先，SSE 回退） -- 可通过 `agents.defaults.models["openai-codex/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上传递 +- 默认传输为 `auto`（优先 WebSocket，回退 SSE） +- 可通过 `agents.defaults.models["openai-codex/"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上转发 - 隐藏的 OpenClaw 归因请求头（`originator`、`version`、 - `User-Agent`）仅附加到发送到 + `User-Agent`）仅会附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不会附加到通用 OpenAI 兼容代理 -- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority` -- 当 Codex OAuth 目录公开 `openai-codex/gpt-5.3-codex-spark` 时，它仍然可用；取决于权限 +- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority` +- 当 Codex OAuth 目录暴露 `openai-codex/gpt-5.3-codex-spark` 时，它仍然可用；取决于 entitlement - `openai-codex/gpt-5.4` 保留原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 -- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 之类的外部工具/工作流。 +- 策略说明：OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具/工作流。 ```json5 { @@ -321,7 +229,7 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** ### 其他订阅式托管选项 -- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商界面，以及 Alibaba DashScope 和 Coding Plan 端点映射 +- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射 - [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问 - [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点 @@ -345,17 +253,17 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 凭证：`GEMINI_API_KEY` - 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） - 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview` -- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被归一化为 `google/gemini-3-flash-preview` +- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview` - CLI：`openclaw onboard --auth-choice gemini-api-key` -- 直连 Gemini 运行还接受 `agents.defaults.models["google/"].params.cachedContent` - （或旧版 `cached_content`），用于转发提供商原生的 - `cachedContents/...` 句柄；Gemini 缓存命中会以 OpenClaw `cacheRead` 形式呈现 +- 直接 Gemini 运行还接受 `agents.defaults.models["google/"].params.cachedContent` + （或旧版 `cached_content`），以转发提供商原生的 + `cachedContents/...` 句柄；Gemini 缓存命中会在 OpenClaw 中显示为 `cacheRead` ### Google Vertex 和 Gemini CLI - 提供商：`google-vertex`、`google-gemini-cli` - 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程 -- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告在使用第三方客户端后遭到 Google 账号限制。若你选择继续，请先查看 Google 条款，并使用非关键账号。 +- 注意：OpenClaw 中的 Gemini CLI OAuth 属于非官方集成。有用户报告在使用第三方客户端后 Google 账户受到限制。若你选择继续，请查看 Google 条款并使用非关键账户。 - Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 - 先安装 Gemini CLI： - `brew install gemini-cli` @@ -363,11 +271,10 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 启用：`openclaw plugins enable google` - 登录：`openclaw models auth login --provider google-gemini-cli --set-default` - 默认模型：`google-gemini-cli/gemini-3.1-pro-preview` - - 注意：你**不需要**把 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将 - 令牌存储在 Gateway 网关主机上的凭证配置档中。 + - 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置文件中。 - 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。 - - Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 - `stats`，其中 `stats.cached` 会被归一化为 OpenClaw `cacheRead`。 + - Gemini CLI JSON 回复从 `response` 解析；使用量会回退到 + `stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。 ### Z.AI（GLM） @@ -375,8 +282,8 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 凭证：`ZAI_API_KEY` - 示例模型：`zai/glm-5` - CLI：`openclaw onboard --auth-choice zai-api-key` - - 别名：`z.ai/*` 和 `z-ai/*` 会归一化为 `zai/*` - - `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定界面 + - 别名：`z.ai/*` 和 `z-ai/*` 会标准化为 `zai/*` + - `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制指定某个具体界面 ### Vercel AI Gateway @@ -392,11 +299,10 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 示例模型：`kilocode/kilo/auto` - CLI：`openclaw onboard --auth-choice kilocode-api-key` - Base URL：`https://api.kilo.ai/api/gateway/` -- 静态回退目录附带 `kilocode/kilo/auto`；实时 - `https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时 - 目录。 -- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway - 决定，而不是在 OpenClaw 中硬编码。 +- 静态回退目录内置了 `kilocode/kilo/auto`；live + `https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时目录。 +- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 拥有， + 并非在 OpenClaw 中硬编码。 设置详情请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。 @@ -404,25 +310,20 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - OpenRouter：`openrouter`（`OPENROUTER_API_KEY`） - 示例模型：`openrouter/auto` -- 只有当请求实际发送到 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中的应用归因请求头 -- OpenRouter 特有的 Anthropic `cache_control` 标记同样只会应用到 - 已验证的 OpenRouter 路由，而不是任意代理 URL -- OpenRouter 仍然走代理风格的 OpenAI 兼容路径，因此不会转发 - 原生 OpenAI 专属的请求整形（`serviceTier`、Responses `store`、 - 提示缓存提示、OpenAI 推理兼容载荷） -- 以 Gemini 为后端的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理； - 原生 Gemini 重放校验和 bootstrap 重写仍然关闭 +- 只有当请求实际发往 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中定义的应用归因请求头 +- OpenRouter 特有的 Anthropic `cache_control` 标记同样只会作用于已验证的 OpenRouter 路由，而不会作用于任意代理 URL +- OpenRouter 仍走代理风格的 OpenAI 兼容路径，因此原生 OpenAI 专用请求整形（`serviceTier`、Responses `store`、 + 提示缓存提示、OpenAI 推理兼容负载）不会被转发 +- 基于 Gemini 的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和 bootstrap 重写不会启用 - Kilo Gateway：`kilocode`（`KILOCODE_API_KEY`） - 示例模型：`kilocode/kilo/auto` -- 以 Gemini 为后端的 Kilo 引用保留相同的代理 Gemini thought-signature - 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的提示 - 会跳过代理推理注入 +- 基于 Gemini 的 Kilo 引用保留相同的代理 Gemini thought-signature + 清理路径；`kilocode/kilo/auto` 以及其他不支持代理推理的提示会跳过代理推理注入 - MiniMax：`minimax`（API 密钥）和 `minimax-portal`（OAuth） -- 凭证：`MINIMAX_API_KEY` 用于 `minimax`；`MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` 用于 `minimax-portal` +- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` - 示例模型：`minimax/MiniMax-M2.7` 或 `minimax-portal/MiniMax-M2.7` -- MiniMax 新手引导/API 密钥设置会写入显式的 M2.7 模型定义， - 其中 `input: ["text", "image"]`；内置提供商目录会在 - 该提供商配置具体化之前将聊天引用保持为纯文本 +- MiniMax 新手引导/API 密钥设置会写入显式的 M2.7 模型定义，并带有 + `input: ["text", "image"]`；内置提供商目录会在该提供商配置具体化之前，将聊天引用保持为仅文本 - Moonshot：`moonshot`（`MOONSHOT_API_KEY`） - 示例模型：`moonshot/kimi-k2.5` - Kimi Coding：`kimi`（`KIMI_API_KEY` 或 `KIMICODE_API_KEY`） @@ -450,10 +351,9 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - xAI：`xai`（`XAI_API_KEY`） - 原生内置 xAI 请求使用 xAI Responses 路径 - `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、 - `grok-4` 和 `grok-4-0709` 重写为对应的 `*-fast` 变体 - - `tool_stream` 默认开启；设置 - `agents.defaults.models["xai/"].params.tool_stream` 为 `false` 可 - 关闭它 + `grok-4` 和 `grok-4-0709` 重写为它们的 `*-fast` 变体 + - 默认启用 `tool_stream`；设置 + `agents.defaults.models["xai/"].params.tool_stream` 为 `false` 可关闭它 - Mistral：`mistral`（`MISTRAL_API_KEY`） - 示例模型：`mistral/mistral-large-latest` - CLI：`openclaw onboard --auth-choice mistral-api-key` @@ -466,24 +366,22 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** ## 通过 `models.providers` 配置的提供商（自定义/base URL） -使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 +使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。 -下方许多内置提供商插件已经发布了默认目录。 -只有当你想覆盖默认 base URL、请求头或模型列表时， -才需要显式使用 `models.providers.` 条目。 +下面许多内置提供商插件已经发布了默认目录。 +只有当你想覆盖默认 base URL、请求头或模型列表时，才需要显式使用 `models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件提供。默认应使用内置提供商， -只有在你需要覆盖 base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： +Moonshot 作为内置提供商插件提供。默认请使用内置提供商，只有在你需要覆盖 base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： - 提供商：`moonshot` - 凭证：`MOONSHOT_API_KEY` - 示例模型：`moonshot/kimi-k2.5` - CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn` -Kimi K2 模型 ID： +Kimi K2 模型 id： [//]: # "moonshot-kimi-k2-model-refs:start" @@ -530,11 +428,11 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍然作为兼容模型 id 被接受。 +旧版 `kimi/k2p5` 仍作为兼容模型 id 被接受。 ### Volcano Engine（Doubao） -Volcano Engine（火山引擎）为中国用户提供对 Doubao 及其他模型的访问。 +Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型的访问。 - 提供商：`volcengine`（编码：`volcengine-plan`） - 凭证：`VOLCANO_ENGINE_API_KEY` @@ -549,13 +447,11 @@ Volcano Engine（火山引擎）为中国用户提供对 Doubao 及其他模型 } ``` -新手引导默认使用编码界面，但通用 `volcengine/*` +新手引导默认使用 coding 界面，但通用 `volcengine/*` 目录也会同时注册。 -在新手引导/配置模型选择器中，Volcengine 凭证选择会优先显示 -`volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载， -OpenClaw 会回退到未过滤目录，而不是显示一个空的 -提供商范围选择器。 +在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载， +OpenClaw 会回退到未过滤目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -575,7 +471,7 @@ OpenClaw 会回退到未过滤目录，而不是显示一个空的 ### BytePlus（国际版） -BytePlus ARK 为国际用户提供对与 Volcano Engine 相同模型的访问。 +BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 - 提供商：`byteplus`（编码：`byteplus-plan`） - 凭证：`BYTEPLUS_API_KEY` @@ -590,13 +486,11 @@ BytePlus ARK 为国际用户提供对与 Volcano Engine 相同模型的访问。 } ``` -新手引导默认使用编码界面，但通用 `byteplus/*` +新手引导默认使用 coding 界面，但通用 `byteplus/*` 目录也会同时注册。 -在新手引导/配置模型选择器中，BytePlus 凭证选择会优先显示 -`byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载， -OpenClaw 会回退到未过滤目录，而不是显示一个空的 -提供商范围选择器。 +在新手引导/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载， +OpenClaw 会回退到未过滤目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -648,25 +542,24 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点： - MiniMax OAuth（CN）：`--auth-choice minimax-cn-oauth` - MiniMax API 密钥（Global）：`--auth-choice minimax-global-api` - MiniMax API 密钥（CN）：`--auth-choice minimax-cn-api` -- 凭证：`MINIMAX_API_KEY` 用于 `minimax`；`MINIMAX_OAUTH_TOKEN` 或 - `MINIMAX_API_KEY` 用于 `minimax-portal` +- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 + `MINIMAX_API_KEY` 设置详情、模型选项和配置片段请参见 [/providers/minimax](/zh-CN/providers/minimax)。 -在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认禁用 thinking， -除非你显式设置它，并且 `/fast on` 会将 +在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认禁用 thinking，除非你显式设置它，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -由插件拥有的能力划分： +插件拥有的能力划分： - 文本/聊天默认保持在 `minimax/MiniMax-M2.7` - 图像生成是 `minimax/image-01` 或 `minimax-portal/image-01` -- 图像理解是在两个 MiniMax 凭证路径上都由插件拥有的 `MiniMax-VL-01` -- Web 搜索仍然使用提供商 id `minimax` +- 图像理解是在两种 MiniMax 凭证路径上都由插件拥有的 `MiniMax-VL-01` +- Web 搜索保持使用提供商 id `minimax` ### Ollama -Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API： +Ollama 作为内置提供商插件提供，并使用 Ollama 原生 API： - 提供商：`ollama` - 凭证：无需（本地服务器） @@ -686,20 +579,18 @@ ollama pull llama3.3 } ``` -当你通过 `OLLAMA_API_KEY` 选择加入时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到， -并且内置提供商插件会将 Ollama 直接添加到 -`openclaw onboard` 和模型选择器中。关于新手引导、云端/本地模式以及自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。 +当你通过 `OLLAMA_API_KEY` 选择启用时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，并且内置提供商插件会将 Ollama 直接添加到 +`openclaw onboard` 和模型选择器中。关于新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。 ### vLLM -vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容 -服务器： +vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容服务器： - 提供商：`vllm` - 凭证：可选（取决于你的服务器） - 默认 base URL：`http://127.0.0.1:8000/v1` -若要在本地选择加入自动发现（如果你的服务器不强制凭证，任意值都可以）： +要选择启用本地自动发现（如果你的服务器不强制凭证，任意值都可以）： ```bash export VLLM_API_KEY="vllm-local" @@ -719,15 +610,14 @@ export VLLM_API_KEY="vllm-local" ### SGLang -SGLang 作为内置提供商插件提供，用于高速自托管的 +SGLang 作为内置提供商插件提供，用于快速自托管的 OpenAI 兼容服务器： - 提供商：`sglang` - 凭证：可选（取决于你的服务器） - 默认 base URL：`http://127.0.0.1:30000/v1` -若要在本地选择加入自动发现（如果你的服务器不 -强制凭证，任意值都可以）： +要选择启用本地自动发现（如果你的服务器不强制凭证，任意值都可以）： ```bash export SGLANG_API_KEY="sglang-local" @@ -754,7 +644,7 @@ export SGLANG_API_KEY="sglang-local" agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, - models: { "lmstudio/my-local-model": { alias: "Local" } }, + models: { "lmstudio/my-local-model": { alias: "本地" } }, }, }, models: { @@ -766,7 +656,7 @@ export SGLANG_API_KEY="sglang-local" models: [ { id: "my-local-model", - name: "Local Model", + name: "本地模型", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -789,14 +679,11 @@ export SGLANG_API_KEY="sglang-local" - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- 建议：设置与你的代理/模型限制匹配的显式值。 -- 对于非原生端点上的 `api: "openai-completions"`（任何主机不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 -- 代理风格的 OpenAI 兼容路由也会跳过原生 OpenAI 专属的请求 - 整形：没有 `service_tier`、没有 Responses `store`、没有提示缓存提示、没有 - OpenAI 推理兼容载荷整形，也没有隐藏的 OpenClaw 归因 - 请求头。 -- 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认 OpenAI 行为（即解析到 `api.openai.com`）。 -- 出于安全考虑，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 +- 建议：设置与代理/模型限制相匹配的显式值。 +- 对于非原生端点上的 `api: "openai-completions"`（任何 host 不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 +- 代理风格的 OpenAI 兼容路由也会跳过原生 OpenAI 专用请求整形：没有 `service_tier`、没有 Responses `store`、没有提示缓存提示、没有 OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因请求头。 +- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（解析为 `api.openai.com`）。 +- 出于安全考虑，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。 ## CLI 示例 @@ -806,7 +693,7 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -另请参见：[/gateway/configuration](/zh-CN/gateway/configuration) 了解完整配置示例。 +另请参见：[/gateway/configuration](/zh-CN/gateway/configuration) 获取完整配置示例。 ## 相关内容 diff --git a/docs/zh-CN/concepts/oauth.md b/docs/zh-CN/concepts/oauth.md index 3c3a72f44..89cf81860 100644 --- a/docs/zh-CN/concepts/oauth.md +++ b/docs/zh-CN/concepts/oauth.md @@ -2,56 +2,57 @@ read_when: - 你想端到端了解 OpenClaw OAuth - 你遇到了令牌失效 / 登出问题 - - 你想使用 Claude CLI 或 OAuth 认证流程 - - 你想使用多个账户或配置文件路由 -summary: OpenClaw 中的 OAuth：令牌交换、存储与多账户模式 + - 你想了解 Claude CLI 或 OAuth 认证流程 + - 你想使用多个账号或配置文件路由 +summary: OpenClaw 中的 OAuth：令牌交换、存储与多账号模式 title: OAuth x-i18n: - generated_at: "2026-04-05T17:46:55Z" + generated_at: "2026-04-06T15:27:43Z" model: gpt-5.4 provider: openai - source_hash: 402e20dfeb6ae87a90cba5824a56a7ba3b964f3716508ea5cc48a47e5affdd73 + source_hash: 4117fee70e3e64fd3a762403454ac2b78de695d2b85a7146750c6de615921e02 source_path: concepts/oauth.md workflow: 15 --- # OAuth -OpenClaw 支持通过 OAuth 使用“订阅认证”，适用于提供此能力的提供商 -（尤其是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic，目前实际情况 +OpenClaw 支持通过 OAuth 实现“订阅认证”，适用于提供该能力的提供商 +（尤其是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic，目前实际上的区分 是： -- **Anthropic API 密钥**：标准 Anthropic API 计费 -- **OpenClaw 中的 Anthropic 订阅认证**：Anthropic 已于 **2026 年 4 月 4 日太平洋时间下午 12:00 / 英国夏令时晚上 8:00** 通知 OpenClaw - 用户，这现在需要 **Extra Usage** +- **Anthropic API key**：常规 Anthropic API 计费 +- **Anthropic Claude CLI / OpenClaw 内的订阅认证**：Anthropic 员工 + 告诉我们这种用法再次被允许 -OpenAI Codex OAuth 明确支持在 OpenClaw 这类外部工具中使用。本文说明： +OpenAI Codex OAuth 已明确支持在 OpenClaw 这类外部工具中使用。本页说明： -对于生产环境中的 Anthropic，API 密钥认证是更安全、推荐的方案。 +对于生产环境中的 Anthropic，API key 认证仍是更安全、也更推荐的路径。 -- OAuth **令牌交换**如何工作（PKCE） -- 令牌**存储**在哪里（以及原因） -- 如何处理**多个账户**（配置文件 + 每会话覆盖） +- OAuth **令牌交换** 的工作方式（PKCE） +- 令牌**存储** 在哪里（以及原因） +- 如何处理**多个账号**（配置文件 + 每会话覆盖） -OpenClaw 还支持自带 OAuth 或 API 密钥流程的**提供商插件**。可通过以下命令运行： +OpenClaw 还支持自带 OAuth 或 API‑key +流程的**提供商插件**。可通过以下命令运行： ```bash openclaw models auth login --provider ``` -## 令牌汇聚点（为什么存在） +## 令牌汇集点（为什么存在） -OAuth 提供商通常会在登录 / 刷新流程中签发**新的刷新令牌**。某些提供商（或 OAuth 客户端）可能会在为同一用户 / 应用签发新令牌时使旧的刷新令牌失效。 +OAuth 提供商通常会在登录 / 刷新流程中签发**新的刷新令牌**。某些提供商（或 OAuth 客户端）会在为同一用户 / 应用签发新令牌时，使旧的刷新令牌失效。 实际症状： -- 你同时通过 OpenClaw _以及_ Claude Code / Codex CLI 登录 → 之后其中一个会随机“被登出” +- 你同时通过 OpenClaw _和_ Claude Code / Codex CLI 登录 → 之后其中一个会随机出现“已登出” -为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为一个**令牌汇聚点**： +为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为**令牌汇集点**： -- 运行时从**同一个位置**读取凭证 -- 我们可以保留多个配置文件并以确定性的方式进行路由 -- 当凭证复用自 Codex CLI 之类的外部 CLI 时，OpenClaw +- 运行时从**一个位置**读取凭证 +- 我们可以保留多个配置文件，并以确定性的方式进行路由 +- 当凭证复用自 Codex CLI 这类外部 CLI 时，OpenClaw 会带着来源信息镜像这些凭证，并重新读取该外部来源，而不是 自己轮换刷新令牌 @@ -59,72 +60,70 @@ OAuth 提供商通常会在登录 / 刷新流程中签发**新的刷新令牌** 密钥按**每个智能体**存储： -- 认证配置文件（OAuth + API 密钥 + 可选的值级别引用）：`~/.openclaw/agents//agent/auth-profiles.json` +- 认证配置文件（OAuth + API keys + 可选的值级引用）：`~/.openclaw/agents//agent/auth-profiles.json` - 旧版兼容文件：`~/.openclaw/agents//agent/auth.json` - （发现静态 `api_key` 条目时会清理掉） + （发现静态 `api_key` 条目时会被清理） -仅用于旧版导入的文件（仍受支持，但不是主存储）： +仅用于旧版导入的文件（仍受支持，但不是主要存储）： -- `~/.openclaw/credentials/oauth.json`（首次使用时会导入到 `auth-profiles.json` 中） +- `~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`） -以上所有路径也都遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/zh-CN/gateway/configuration-reference#auth-storage) +以上所有路径同样遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/zh-CN/gateway/configuration-reference#auth-storage) -关于静态 SecretRef 和运行时快照激活行为，请参见[密钥管理](/zh-CN/gateway/secrets)。 +关于静态密钥引用和运行时快照激活行为，请参见 [Secrets Management](/zh-CN/gateway/secrets)。 ## Anthropic 旧版令牌兼容性 -Anthropic 的公开 Claude Code 文档说明，直接使用 Claude Code 会保持在 -Claude 订阅限额内。另一个层面上，Anthropic 已于 **2026 年 4 月 4 日太平洋时间下午 12:00 / 英国夏令时晚上 8:00** 告知 OpenClaw 用户，**OpenClaw 被视为第三方封装工具**。现有的 Anthropic 令牌配置文件在 OpenClaw 中在技术上仍可使用，但 Anthropic 表示，OpenClaw 路径现在要求该流量使用 **Extra -Usage**（按量付费，独立于订阅单独计费）。 +Anthropic 的公开 Claude Code 文档说明，直接使用 Claude Code 仍受 +Claude 订阅限制约束，而 Anthropic 员工告诉我们，OpenClaw 风格的 Claude +CLI 用法再次被允许。因此，OpenClaw 目前将 Claude CLI 复用和 +`claude -p` 用法视为该集成的许可方式，除非 Anthropic +发布新的政策。 -关于 Anthropic 当前的直接 Claude Code 套餐文档，请参见 [Using Claude Code +关于 Anthropic 当前直接使用 Claude Code 的套餐文档，请参见 [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) 和 [Using Claude Code with your Team or Enterprise -plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)。 +plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/). 如果你想在 OpenClaw 中使用其他订阅式选项，请参见 [OpenAI Codex](/zh-CN/providers/openai)、[Qwen Cloud Coding Plan](/zh-CN/providers/qwen)、[MiniMax Coding Plan](/zh-CN/providers/minimax) -和 [Z.AI / GLM Coding Plan](/zh-CN/providers/glm)。 +以及 [Z.AI / GLM Coding Plan](/zh-CN/providers/glm)。 -OpenClaw 现在再次开放 Anthropic setup-token，作为旧版 / 手动路径。 -Anthropic 针对 OpenClaw 的计费通知仍适用于该路径，因此 -使用时请预期 Anthropic 会对 -OpenClaw 驱动的 Claude 登录流量要求 **Extra Usage**。 +OpenClaw 也将 Anthropic setup-token 作为受支持的基于令牌的认证路径提供，但现在在可用时更优先使用 Claude CLI 复用和 `claude -p`。 ## Anthropic Claude CLI 迁移 -Anthropic 在 OpenClaw 中已不再提供受支持的本地 Claude CLI 迁移路径。 -对于 Anthropic 流量，请使用 Anthropic API 密钥；或者仅在 -已经配置好的情况下继续使用旧版基于令牌的认证，并接受 Anthropic 将该 OpenClaw 路径视为 **Extra Usage** 的前提。 +OpenClaw 再次支持复用 Anthropic Claude CLI。如果你在主机上已经有本地 +Claude 登录，新手引导 / 配置过程可以直接复用它。 ## OAuth 交换（登录如何工作） -OpenClaw 的交互式登录流程由 `@mariozechner/pi-ai` 实现，并接入各类向导 / 命令。 +OpenClaw 的交互式登录流程由 `@mariozechner/pi-ai` 实现，并接入到向导 / 命令中。 ### Anthropic setup-token -流程形态： +流程形式： 1. 从 OpenClaw 启动 Anthropic setup-token 或 paste-token 2. OpenClaw 将生成的 Anthropic 凭证存储到认证配置文件中 3. 模型选择保持为 `anthropic/...` -4. 现有的 Anthropic 认证配置文件仍可用于回滚 / 顺序控制 +4. 现有 Anthropic 认证配置文件仍然可用于回滚 / 顺序控制 ### OpenAI Codex（ChatGPT OAuth） -OpenAI Codex OAuth 明确支持在 Codex CLI 之外使用，包括 OpenClaw 工作流。 +OpenAI Codex OAuth 已明确支持在 Codex CLI 之外使用，包括 OpenClaw 工作流。 -流程形态（PKCE）： +流程形式（PKCE）： -1. 生成 PKCE verifier / challenge + 随机 `state` +1. 生成 PKCE verifier/challenge + 随机 `state` 2. 打开 `https://auth.openai.com/oauth/authorize?...` 3. 尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调 -4. 如果回调无法绑定（或者你处于远程 / 无头环境），则粘贴重定向 URL / 代码 -5. 在 `https://auth.openai.com/oauth/token` 执行交换 +4. 如果无法绑定回调（或你处于远程 / 无头环境），粘贴重定向 URL / 代码 +5. 在 `https://auth.openai.com/oauth/token` 进行交换 6. 从访问令牌中提取 `accountId`，并存储 `{ access, refresh, expires, accountId }` 向导路径为 `openclaw onboard` → 认证选项 `openai-codex`。 @@ -135,36 +134,36 @@ OpenAI Codex OAuth 明确支持在 Codex CLI 之外使用，包括 OpenClaw 工 在运行时： -- 如果 `expires` 在未来 → 使用已存储的访问令牌 -- 如果已过期 → 刷新（在文件锁保护下）并覆盖已存储的凭证 +- 如果 `expires` 还在未来 → 使用已存储的访问令牌 +- 如果已过期 → 刷新（在文件锁下进行）并覆盖已存储的凭证 - 例外：复用的外部 CLI 凭证仍由外部管理；OpenClaw - 会重新读取 CLI 认证存储，而不会自行使用复制来的刷新令牌 + 会重新读取 CLI 认证存储，绝不会自己使用复制来的刷新令牌 刷新流程是自动的；通常你不需要手动管理令牌。 -## 多个账户（配置文件）+ 路由 +## 多个账号（配置文件）+ 路由 有两种模式： -### 1）首选：分离智能体 +### 1）首选：分离的智能体 -如果你希望“个人”和“工作”永不互相影响，请使用隔离的智能体（独立会话 + 凭证 + 工作区）： +如果你希望“个人”和“工作”永不互相影响，请使用隔离的智能体（独立的会话 + 凭证 + 工作区）： ```bash openclaw agents add work openclaw agents add personal ``` -然后按每个智能体配置认证（通过向导），并将聊天路由到正确的智能体。 +然后按智能体分别配置认证（通过向导），并将聊天路由到正确的智能体。 -### 2）高级：在一个智能体中使用多个配置文件 +### 2）高级：一个智能体内的多个配置文件 -`auth-profiles.json` 支持同一提供商的多个配置文件 ID。 +`auth-profiles.json` 支持同一提供商下的多个配置文件 ID。 选择使用哪个配置文件： -- 通过配置顺序全局选择（`auth.order`） -- 通过 `/model ...@` 按会话选择 +- 通过配置排序全局指定（`auth.order`） +- 通过 `/model ...@` 按会话指定 示例（会话覆盖）： @@ -181,6 +180,6 @@ openclaw agents add personal ## 相关内容 -- [认证](/zh-CN/gateway/authentication) — 模型提供商认证概览 -- [密钥](/zh-CN/gateway/secrets) — 凭证存储与 SecretRef -- [配置参考](/zh-CN/gateway/configuration-reference#auth-storage) — 认证配置键 +- [Authentication](/zh-CN/gateway/authentication) — 模型提供商认证概览 +- [Secrets](/zh-CN/gateway/secrets) — 凭证存储与 SecretRef +- [Configuration Reference](/zh-CN/gateway/configuration-reference#auth-storage) — 认证配置键名 diff --git a/docs/zh-CN/gateway/authentication.md b/docs/zh-CN/gateway/authentication.md index 3b9c5fcad..43efb0769 100644 --- a/docs/zh-CN/gateway/authentication.md +++ b/docs/zh-CN/gateway/authentication.md @@ -1,14 +1,14 @@ --- read_when: - 调试模型认证或 OAuth 过期问题 - - 编写关于认证或凭证存储的文档 -summary: 模型认证：OAuth、API 密钥以及旧版 Anthropic setup-token + - 编写认证或凭证存储相关文档 +summary: 模型认证：OAuth、API 密钥、Claude CLI 复用，以及 Anthropic setup-token title: 认证 x-i18n: - generated_at: "2026-04-05T17:47:10Z" + generated_at: "2026-04-06T15:27:45Z" model: gpt-5.4 provider: openai - source_hash: f59ede3fcd7e692ad4132287782a850526acf35474b5bfcea29e0e23610636c2 + source_hash: 9db0ad9eccd7e3e3ca328adaad260bc4288a8ccdbe2dc0c24d9fd049b7ab9231 source_path: gateway/authentication.md workflow: 15 --- @@ -16,31 +16,31 @@ x-i18n: # 认证（模型提供商） -本页介绍的是**模型提供商**认证（API 密钥、OAuth，以及旧版 Anthropic setup-token）。关于**Gateway 网关连接**认证（token、password、trusted-proxy），请参阅 [配置](/zh-CN/gateway/configuration) 和 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)。 +本页介绍**模型提供商**认证（API 密钥、OAuth、Claude CLI 复用，以及 Anthropic setup-token）。关于 **Gateway 网关连接** 认证（令牌、密码、trusted-proxy），请参阅 [Configuration](/zh-CN/gateway/configuration) 和 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)。 -OpenClaw 支持模型提供商使用 OAuth 和 API 密钥。对于始终在线的 Gateway 网关主机，API 密钥通常是最可预测的选择。当它与你的提供商账户模型匹配时，也支持订阅制 / OAuth 流程。 +OpenClaw 支持模型提供商使用 OAuth 和 API 密钥。对于长期运行的 Gateway 网关主机，API 密钥通常是最可预测的选项。当订阅 / OAuth 流程与你的提供商账户模型匹配时，也支持这类流程。 完整的 OAuth 流程和存储布局，请参阅 [/concepts/oauth](/zh-CN/concepts/oauth)。 关于基于 SecretRef 的认证（`env`/`file`/`exec` 提供商），请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 关于 `models status --probe` 使用的凭证适用性 / 原因代码规则，请参阅 [Auth Credential Semantics](/zh-CN/auth-credential-semantics)。 -## 推荐设置（API 密钥，任意提供商） +## 推荐设置（API 密钥，适用于任何提供商） -如果你正在运行长期存活的 Gateway 网关，请先为你选择的提供商配置 API 密钥。 -对于 Anthropic，API 密钥认证是稳妥方案。OpenClaw 中 Anthropic 的订阅式认证属于旧版 setup-token 路径，应被视为**额外用量**路径，而不是套餐限额路径。 +如果你正在运行一个长期存在的 Gateway 网关，请先为你选择的提供商使用 API 密钥。 +对于 Anthropic 而言，API 密钥认证仍然是最可预测的服务器端设置，但 OpenClaw 也支持复用本地 Claude CLI 登录。 1. 在你的提供商控制台中创建一个 API 密钥。 -2. 将其放到**Gateway 网关主机**上（也就是运行 `openclaw gateway` 的机器）。 +2. 将其放在**Gateway 网关主机**上（运行 `openclaw gateway` 的机器）。 ```bash export _API_KEY="..." openclaw models status ``` -3. 如果 Gateway 网关运行在 systemd/launchd 下，建议将密钥放入 - `~/.openclaw/.env`，这样守护进程就可以读取： +3. 如果 Gateway 在 systemd/launchd 下运行，建议将密钥放在 + `~/.openclaw/.env` 中，以便守护进程可以读取： ```bash cat >> ~/.openclaw/.env <<'EOF' @@ -48,35 +48,35 @@ cat >> ~/.openclaw/.env <<'EOF' EOF ``` -然后重启守护进程（或重启你的 Gateway 网关进程），并再次检查： +然后重启守护进程（或重启你的 Gateway 网关进程）并重新检查： ```bash openclaw models status openclaw doctor ``` -如果你不想自行管理环境变量，新手引导也可以为守护进程存储 +如果你不想自己管理环境变量，新手引导可以为守护进程使用存储 API 密钥：`openclaw onboard`。 -有关环境继承（`env.shellEnv`、`~/.openclaw/.env`、systemd/launchd）的详细信息，请参阅 [帮助](/zh-CN/help)。 +关于环境继承（`env.shellEnv`、`~/.openclaw/.env`、systemd/launchd）的详细信息，请参阅 [Help](/zh-CN/help)。 -## Anthropic：旧版令牌兼容性 +## Anthropic：Claude CLI 和令牌兼容性 -Anthropic setup-token 认证在 OpenClaw 中仍可作为旧版 / 手动路径使用。Anthropic 的公开 Claude Code 文档仍然涵盖 Claude 套餐下直接在终端中使用 Claude Code，但 Anthropic 也单独告知 OpenClaw 用户，**OpenClaw** 的 Claude 登录路径会被视为第三方 harness 用法，并且需要按**额外用量**单独计费，而不包含在订阅内。 +Anthropic setup-token 认证在 OpenClaw 中仍然作为受支持的令牌路径提供。此后，Anthropic 工作人员告知我们，允许再次使用 OpenClaw 风格的 Claude CLI 用法，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成的认可方式，除非 Anthropic 发布新的政策。当主机上可用 Claude CLI 复用时，这现在是首选路径。 -若要采用最清晰的设置路径，请使用 Anthropic API 密钥。如果你必须在 OpenClaw 中保留 Anthropic 的订阅式路径，请使用旧版 setup-token 路径，并预期 Anthropic 会将其视为**额外用量**。 +对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是最可预测的设置。如果你想在同一台主机上复用现有的 Claude 登录，请在新手引导 / 配置中使用 Anthropic Claude CLI 路径。 -手动输入令牌（任意提供商；写入 `auth-profiles.json` 并更新配置）： +手动输入令牌（适用于任何提供商；会写入 `auth-profiles.json` 并更新配置）： ```bash openclaw models auth paste-token --provider openrouter ``` -静态凭证也支持 auth profile 引用： +静态凭证也支持认证配置文件引用： - `api_key` 凭证可以使用 `keyRef: { source, provider, id }` - `token` 凭证可以使用 `tokenRef: { source, provider, id }` -- OAuth 模式的 profile 不支持 SecretRef 凭证；如果 `auth.profiles..mode` 被设置为 `"oauth"`，则会拒绝该 profile 使用由 SecretRef 支持的 `keyRef`/`tokenRef` 输入。 +- OAuth 模式的配置文件不支持 SecretRef 凭证；如果 `auth.profiles..mode` 设置为 `"oauth"`，则会拒绝该配置文件中由 SecretRef 支持的 `keyRef`/`tokenRef` 输入。 适合自动化的检查（过期 / 缺失时退出码为 `1`，即将过期时为 `2`）： @@ -92,24 +92,25 @@ openclaw models status --probe 说明： -- 探测结果行可以来自 auth profile、环境变量凭证或 `models.json`。 -- 如果显式的 `auth.order.` 省略了某个已存储 profile，探测会为该 profile 报告 +- 探测行可来自认证配置文件、环境凭证或 `models.json`。 +- 如果显式的 `auth.order.` 省略了已存储的配置文件，探测会为该配置文件报告 `excluded_by_auth_order`，而不是尝试使用它。 -- 如果认证存在，但 OpenClaw 无法为该提供商解析出可探测的模型候选项，探测会报告 `status: no_model`。 -- 限流冷却可以按模型范围生效。某个 profile 对一个模型处于冷却状态时，仍可能可用于同一提供商下的兄弟模型。 +- 如果认证存在，但 OpenClaw 无法为该提供商解析出可探测的候选模型，探测会报告 + `status: no_model`。 +- 限流冷却期可以按模型范围生效。对某个模型处于冷却中的配置文件，仍然可能可用于同一提供商下的同级模型。 -可选的运维脚本文档（systemd/Termux）见这里： -[认证监控脚本](/zh-CN/help/scripts#auth-monitoring-scripts) +可选运维脚本（systemd/Termux）文档在这里： +[Auth monitoring scripts](/zh-CN/help/scripts#auth-monitoring-scripts) ## Anthropic 说明 -Anthropic `claude-cli` 后端已被移除。 +Anthropic `claude-cli` 后端现已再次受支持。 -- 在 OpenClaw 中处理 Anthropic 流量时，请使用 Anthropic API 密钥。 -- Anthropic setup-token 仍保留为旧版 / 手动路径，使用时应预期按照 Anthropic 向 OpenClaw 用户说明的**额外用量**计费。 -- `openclaw doctor` 现在会检测已移除但残留的 Anthropic Claude CLI 状态。如果存储的凭证字节仍然存在，doctor 会将它们转换回 - Anthropic token/OAuth profile。否则，doctor 会移除陈旧的 Claude CLI - 配置，并引导你使用 API 密钥或 setup-token 进行恢复。 +- Anthropic 工作人员告诉我们，这条 OpenClaw 集成路径已再次被允许。 +- 因此，OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为 + Anthropic 支持运行中的认可方式，除非 Anthropic 发布新的政策。 +- 对于长期运行的 Gateway 网关主机，以及需要明确服务器端计费控制的场景， + Anthropic API 密钥仍然是最可预测的选择。 ## 检查模型认证状态 @@ -123,29 +124,30 @@ openclaw doctor 某些提供商支持在 API 调用触发提供商限流时，使用其他密钥重试请求。 - 优先级顺序： - - `OPENCLAW_LIVE__KEY`（单个覆盖） + - `OPENCLAW_LIVE__KEY`（单个覆盖项） - `_API_KEYS` - `_API_KEY` - `_API_KEY_*` -- Google 提供商还会将 `GOOGLE_API_KEY` 作为额外回退项。 -- 同一个密钥列表在使用前会先去重。 -- OpenClaw 仅会在限流错误时使用下一个密钥重试（例如 - `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`，或 +- Google 提供商还会额外将 `GOOGLE_API_KEY` 作为回退项。 +- 相同的密钥列表在使用前会去重。 +- 只有在限流错误时，OpenClaw 才会使用下一个密钥重试（例如 + `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent +requests`、`ThrottlingException`、`concurrency limit reached`，或 `workers_ai ... quota limit exceeded`）。 - 非限流错误不会使用备用密钥重试。 -- 如果所有密钥都失败，则返回最后一次尝试的最终错误。 +- 如果所有密钥都失败，将返回最后一次尝试产生的最终错误。 ## 控制使用哪个凭证 -### 按会话控制（聊天命令） +### 按会话（聊天命令） -使用 `/model @` 为当前会话固定指定某个提供商凭证（示例 profile id：`anthropic:default`、`anthropic:work`）。 +使用 `/model @` 可为当前会话固定使用特定的提供商凭证（示例配置文件 id：`anthropic:default`、`anthropic:work`）。 -使用 `/model`（或 `/model list`）可打开精简选择器；使用 `/model status` 可查看完整视图（候选项 + 下一个 auth profile，以及在已配置时显示的提供商端点详情）。 +使用 `/model`（或 `/model list`）可打开紧凑选择器；使用 `/model status` 可查看完整视图（候选项 + 下一个认证配置文件，以及配置后显示的提供商端点详情）。 -### 按智能体控制（CLI 覆盖） +### 按智能体（CLI 覆盖） -为某个智能体设置显式的 auth profile 顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）： +为某个智能体设置显式的认证配置文件顺序覆盖（存储在该智能体的 `auth-state.json` 中）： ```bash openclaw models auth order get --provider anthropic @@ -153,16 +155,17 @@ openclaw models auth order set --provider anthropic anthropic:default openclaw models auth order clear --provider anthropic ``` -使用 `--agent ` 可指定某个智能体；省略时则使用已配置的默认智能体。 -调试顺序问题时，`openclaw models status --probe` 会将被省略的已存储 -profile 显示为 `excluded_by_auth_order`，而不是静默跳过。 -调试冷却问题时，请记住限流冷却可能只绑定到某个模型 id，而不是整个提供商 profile。 +使用 `--agent ` 可指定特定智能体；省略时则使用已配置的默认智能体。 +当你调试顺序问题时，`openclaw models status --probe` 会将被省略的 +已存储配置文件显示为 `excluded_by_auth_order`，而不是静默跳过它们。 +当你调试冷却问题时，请记住限流冷却期可能只绑定到某个模型 id， +而不是整个提供商配置文件。 ## 故障排除 ### “未找到凭证” -如果 Anthropic profile 缺失，请在**Gateway 网关主机**上配置 Anthropic API 密钥，或设置旧版 Anthropic setup-token 路径，然后重新检查： +如果缺少 Anthropic 配置文件，请在**Gateway 网关主机**上配置 Anthropic API 密钥，或设置 Anthropic setup-token 路径，然后重新检查： ```bash openclaw models status @@ -170,15 +173,6 @@ openclaw models status ### 令牌即将过期 / 已过期 -运行 `openclaw models status` 以确认是哪个 profile 即将过期。如果旧版 -Anthropic token profile 缺失或已过期，请通过 +运行 `openclaw models status` 以确认哪个配置文件即将过期。如果某个 +Anthropic 令牌配置文件缺失或已过期，请通过 setup-token 刷新该设置，或迁移到 Anthropic API 密钥。 - -如果这台机器仍保留旧构建遗留的、已移除的 Anthropic Claude CLI 状态，请运行： - -```bash -openclaw doctor --yes -``` - -如果存储的凭证字节仍然存在，Doctor 会将 `anthropic:claude-cli` 转换回 Anthropic token/OAuth。否则，它会移除陈旧的 Claude CLI -profile/config/model 引用，并保留下一步操作指引。 diff --git a/docs/zh-CN/gateway/cli-backends.md b/docs/zh-CN/gateway/cli-backends.md index 57ec8fed0..959983f21 100644 --- a/docs/zh-CN/gateway/cli-backends.md +++ b/docs/zh-CN/gateway/cli-backends.md @@ -3,42 +3,39 @@ read_when: - 当 API 提供商失败时，你想要一个可靠的回退方案 - 你正在运行 Codex CLI 或其他本地 AI CLI，并且想要复用它们 - 你想了解用于 CLI 后端工具访问的 MCP loopback 桥接 -summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退方案 +summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退 title: CLI 后端 x-i18n: - generated_at: "2026-04-06T12:42:54Z" + generated_at: "2026-04-06T15:27:53Z" model: gpt-5.4 provider: openai - source_hash: fe30bb4d5f51adcda53bf69a4f88e27832e78630ed5bfd8a33a66b6412b66f2d + source_hash: f061357f420455ad6ffaabe7fe28f1fb1b1769d73a4eb2e6f45c6eb3c2e36667 source_path: gateway/cli-backends.md workflow: 15 --- # CLI 后端（回退运行时） -当 API 提供商不可用、受到速率限制或暂时行为异常时，OpenClaw 可以将**本地 AI CLI** 作为**纯文本回退方案**运行。这种设计有意保持保守： +当 API 提供商不可用、受到速率限制或暂时行为异常时，OpenClaw 可以运行**本地 AI CLI** 作为**纯文本回退**。这是有意采取的保守设计： -- **OpenClaw 工具不会被直接注入**，但设置了 `bundleMcp: true` 的后端 - 可以通过 loopback MCP 桥接接收 Gateway 网关工具。 -- **JSONL 流式传输**，适用于支持该能力的 CLI。 -- **支持会话**（因此后续轮次可以保持连贯）。 -- 如果 CLI 接受图片路径，**图片也可以透传**。 +- **不会直接注入 OpenClaw 工具**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。 +- 支持 **JSONL 流式传输**，适用于支持它的 CLI。 +- 支持**会话**（因此后续轮次可以保持连贯）。 +- 如果 CLI 接受图片路径，**图片可以透传**。 -这被设计为一种**安全兜底机制**，而不是主要路径。当你希望获得“不管怎样都能工作”的文本回复、而不依赖外部 API 时，可以使用它。 +它的设计目标是作为**安全兜底方案**，而不是主要路径。当你希望在不依赖外部 API 的情况下获得“始终可用”的文本响应时，可以使用它。 -如果你想使用带有 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 -[ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。 +如果你想要一个具备 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。 ## 面向初学者的快速开始 -你可以**无需任何配置**使用 Codex CLI（内置的 OpenAI 插件会注册一个默认后端）： +你可以在**无需任何配置**的情况下使用 Codex CLI（内置 OpenAI 插件会注册一个默认后端）： ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -如果你的 Gateway 网关运行在 launchd/systemd 下，且 `PATH` 很精简，只需添加 -命令路径： +如果你的 Gateway 网关运行在 launchd/systemd 下，且 PATH 非常精简，只需添加命令路径： ```json5 { @@ -54,16 +51,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 } ``` -就是这样。除了 CLI 本身之外，不需要密钥，也不需要额外的凭证配置。 +就是这样。除了 CLI 本身之外，不需要密钥，也不需要额外的身份验证配置。 -如果你在 gateway host 上将某个内置 CLI 后端用作**主要消息提供商**，当你的配置 -在模型引用中或在 -`agents.defaults.cliBackends` -下明确引用了该后端时，OpenClaw 现在会自动加载其所属的内置插件。 +如果你在 Gateway 网关主机上将内置 CLI 后端用作**主要消息提供商**，现在只要你的配置在模型引用中或在 `agents.defaults.cliBackends` 下显式引用了该后端，OpenClaw 就会自动加载对应的内置插件。 -## 将其用作回退方案 +## 将其用作回退 -将某个 CLI 后端添加到你的回退列表中，这样它只会在主要模型失败时运行： +把一个 CLI 后端添加到你的回退列表中，这样它只会在主要模型失败时运行： ```json5 { @@ -84,9 +78,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 说明： -- 如果你使用 `agents.defaults.models`（允许列表），你也必须将你的 CLI 后端模型包含在其中。 -- 如果主要提供商失败（凭证、速率限制、超时），OpenClaw 将会 - 接着尝试 CLI 后端。 +- 如果你使用 `agents.defaults.models`（允许列表），你也必须把 CLI 后端模型包含进去。 +- 如果主要提供商失败（身份验证、速率限制、超时），OpenClaw 会接着尝试 CLI 后端。 ## 配置概览 @@ -96,8 +89,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 agents.defaults.cliBackends ``` -每个条目都由一个**提供商 id** 作为键（例如 `codex-cli`、`my-cli`）。 -这个提供商 id 会成为你的模型引用左侧部分： +每个条目都以一个**提供商 id** 为键（例如 `codex-cli`、`my-cli`）。 +该提供商 id 会成为你的模型引用左侧部分： ``` / @@ -142,35 +135,31 @@ agents.defaults.cliBackends 1. 根据提供商前缀（`codex-cli/...`）**选择一个后端**。 2. 使用相同的 OpenClaw 提示词和工作区上下文**构建系统提示词**。 -3. 使用会话 id（如果支持）**执行 CLI**，以保持历史记录一致。 -4. **解析输出**（JSON 或纯文本），并返回最终文本。 -5. 按后端**持久化会话 id**，使后续轮次复用同一个 CLI 会话。 +3. 如果支持，则带着会话 id **执行 CLI**，以便保持历史一致。 +4. **解析输出**（JSON 或纯文本）并返回最终文本。 +5. 按后端**持久化会话 id**，这样后续轮次就会复用同一个 CLI 会话。 - -内置的 Anthropic `claude-cli` 后端已被移除，因为 Anthropic 的 -OpenClaw 计费边界发生了变化。OpenClaw 仍然支持通用 CLI -后端，但 Anthropic API 流量应当直接使用 Anthropic 提供商， -而不是已移除的本地 Claude CLI 路径。 - + +内置 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 用法现在再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 `claude -p` 用法视为此集成的许可方式。 + ## 会话 - 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或 - `sessionArgs`（占位符 `{sessionId}`），用于在需要将该 ID 插入 - 到多个标志位时使用。 -- 如果 CLI 使用带有不同标志位的**恢复子命令**，请设置 + `sessionArgs`（占位符 `{sessionId}`），用于在需要将该 ID 插入多个标志时使用。 +- 如果 CLI 使用带有不同标志的**恢复子命令**，请设置 `resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput` - （用于非 JSON 的恢复输出）。 + （用于非 JSON 恢复）。 - `sessionMode`： - - `always`：始终发送会话 id（如果没有已存储值，则使用新的 UUID）。 - - `existing`：仅当之前已存储会话 id 时才发送。 + - `always`：始终发送会话 id（如果没有已存储值，则生成新的 UUID）。 + - `existing`：仅在之前存储过会话 id 时发送。 - `none`：从不发送会话 id。 序列化说明： - `serialize: true` 会保持同一通道运行按顺序执行。 -- 大多数 CLI 会在一个提供商通道上串行执行。 -- 当后端凭证状态发生变化时，包括重新登录、令牌轮换或凭证配置发生变化，OpenClaw 会丢弃已存储的 CLI 会话复用信息。 +- 大多数 CLI 会在单个提供商通道上串行化。 +- 当后端身份验证状态发生变化时，包括重新登录、令牌轮换或身份验证配置文件凭据变更，OpenClaw 会丢弃已存储的 CLI 会话复用。 ## 图片（透传） @@ -181,29 +170,24 @@ imageArg: "--image", imageMode: "repeat" ``` -OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些 -路径会作为 CLI 参数传递。如果缺少 `imageArg`，OpenClaw 会将 -这些文件路径附加到提示词中（路径注入），这对于那些可以从普通路径中自动 -加载本地文件的 CLI 来说已经足够。 +OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会把文件路径附加到提示词中（路径注入），这对于会从普通路径自动加载本地文件的 CLI 已经足够。 ## 输入 / 输出 -- `output: "json"`（默认）会尝试解析 JSON，并提取文本 + 会话 id。 -- 对于 Gemini CLI 的 JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 - `stats` 读取用量。 -- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终的智能体消息以及存在时的会话 - 标识符。 +- `output: "json"`（默认）会尝试解析 JSON 并提取文本 + 会话 id。 +- 对于 Gemini CLI JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。 +- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及存在时的会话标识符。 - `output: "text"` 会将 stdout 视为最终响应。 输入模式： - `input: "arg"`（默认）会将提示词作为最后一个 CLI 参数传递。 - `input: "stdin"` 会通过 stdin 发送提示词。 -- 如果提示词很长且设置了 `maxPromptArgChars`，则会改用 stdin。 +- 如果提示词非常长且设置了 `maxPromptArgChars`，则会改用 stdin。 -## 默认值（插件所有） +## 默认值（插件拥有） -内置的 OpenAI 插件也为 `codex-cli` 注册了一个默认值： +内置 OpenAI 插件还为 `codex-cli` 注册了一个默认值： - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -214,7 +198,7 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`， - `imageArg: "--image"` - `sessionMode: "existing"` -内置的 Google 插件也为 `google-gemini-cli` 注册了一个默认值： +内置 Google 插件也为 `google-gemini-cli` 注册了一个默认值： - `command: "gemini"` - `args: ["--prompt", "--output-format", "json"]` @@ -223,67 +207,63 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`， - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -前提条件：本地 Gemini CLI 必须已安装，并且可以作为 -`gemini` 在 `PATH` 中使用（`brew install gemini-cli` 或 +前提条件：本地 Gemini CLI 必须已安装，并且能通过 `PATH` 中的 +`gemini` 使用（`brew install gemini-cli` 或 `npm install -g @google/gemini-cli`）。 Gemini CLI JSON 说明： - 回复文本从 JSON 的 `response` 字段读取。 - 当 `usage` 不存在或为空时，用量会回退到 `stats`。 -- `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 -- 如果缺少 `stats.input`，OpenClaw 会根据 +- `stats.cached` 会被标准化为 OpenClaw `cacheRead`。 +- 如果 `stats.input` 缺失，OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token 数。 -只在需要时覆盖这些默认值（常见情况：使用绝对 `command` 路径）。 +仅在需要时覆盖（常见情况：使用绝对 `command` 路径）。 -## 插件所有的默认值 +## 插件拥有的默认值 -CLI 后端默认值现在已成为插件表面的一部分： +CLI 后端默认值现在属于插件表面的一部分： -- 插件使用 `api.registerCliBackend(...)` 注册它们。 -- 后端 `id` 会成为模型引用中的提供商前缀。 -- 用户在 `agents.defaults.cliBackends.` 中的配置仍会覆盖插件默认值。 +- 插件通过 `api.registerCliBackend(...)` 注册它们。 +- 后端的 `id` 会成为模型引用中的提供商前缀。 +- `agents.defaults.cliBackends.` 中的用户配置仍然会覆盖插件默认值。 - 后端特定的配置清理由插件通过可选的 - `normalizeConfig` hook 保持所有权。 + `normalizeConfig` hook 继续拥有。 ## Bundle MCP 覆盖层 -CLI 后端**不会**直接接收 OpenClaw 工具调用，但某个后端可以通过 -`bundleMcp: true` 选择启用自动生成的 MCP 配置覆盖层。 +CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 +`bundleMcp: true` 选择加入自动生成的 MCP 配置覆盖层。 当前内置行为： -- `codex-cli`：不提供 bundle MCP 覆盖层 -- `google-gemini-cli`：不提供 bundle MCP 覆盖层 +- `codex-cli`：无 bundle MCP 覆盖层 +- `google-gemini-cli`：无 bundle MCP 覆盖层 -启用 bundle MCP 时，OpenClaw 会： +启用 bundle MCP 后，OpenClaw 会： - 启动一个 loopback HTTP MCP 服务器，将 Gateway 网关工具暴露给 CLI 进程 - 使用每会话令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行身份验证 -- 将工具访问范围限定在当前会话、账户和渠道上下文内 +- 将工具访问范围限定到当前会话、账户和渠道上下文 - 为当前工作区加载已启用的 bundle-MCP 服务器 -- 将它们与任何现有的后端 `--mcp-config` 合并 -- 重写 CLI 参数，传入 `--strict-mcp-config --mcp-config ` +- 将它们与任何现有后端 `--mcp-config` 合并 +- 重写 CLI 参数以传递 `--strict-mcp-config --mcp-config ` -如果没有启用任何 MCP 服务器，当后端选择启用 bundle MCP 时，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。 +如果没有启用任何 MCP 服务器，那么当后端选择加入 bundle MCP 时，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。 ## 限制 -- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用直接注入 - 到 CLI 后端协议中。只有当后端启用 - `bundleMcp: true` 时，它们才会看到 Gateway 网关工具。 -- **流式传输是后端特定的。** 某些后端会流式输出 JSONL；其他后端则会 - 缓冲到退出时再输出。 +- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会把工具调用注入到 + CLI 后端协议中。只有当后端选择加入 `bundleMcp: true` 时，它们才能看到 Gateway 网关工具。 +- **流式传输取决于后端。** 有些后端会流式输出 JSONL；其他后端则会一直缓冲到退出。 - **结构化输出** 取决于 CLI 的 JSON 格式。 -- **Codex CLI 会话** 通过文本输出恢复（没有 JSONL），其结构化程度 - 低于初始的 `--json` 运行。但 OpenClaw 会话仍然可以 - 正常工作。 +- **Codex CLI 会话** 通过文本输出恢复（没有 JSONL），其结构性弱于初始的 `--json` 运行。不过 OpenClaw 会话仍然可以正常工作。 ## 故障排除 - **找不到 CLI**：将 `command` 设置为完整路径。 -- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。 +- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射为 CLI 模型。 - **没有会话连续性**：确保已设置 `sessionArg`，并且 `sessionMode` 不是 - `none`（Codex CLI 当前无法使用 JSON 输出进行恢复）。 + `none`（Codex CLI 目前无法使用 JSON 输出恢复）。 - **图片被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index b12eac731..7d9652649 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -1,56 +1,56 @@ --- read_when: - - 你需要精确的字段级配置语义或默认值 + - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: 每个 OpenClaw 配置键、默认值和渠道设置的完整参考 +summary: 每个 OpenClaw 配置键、默认值与渠道设置的完整参考 title: 配置参考 x-i18n: - generated_at: "2026-04-06T12:47:50Z" + generated_at: "2026-04-06T15:33:22Z" model: gpt-5.4 provider: openai - source_hash: 67e3197e2dca37f43285b8aa0e5c77ef1662e1ba28ee874d4e7cbc90e6160ca3 + source_hash: 7768cb77e1d3fc483c66f655ea891d2c32f21b247e3c1a56a919b28a37f9b128 source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 中可用的每个字段。若要查看按任务组织的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 中可用的每个字段。若需面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 —— 省略时，OpenClaw 会使用安全的默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 --- ## 渠道 -只要某个渠道的配置段存在，它就会自动启动（除非设置了 `enabled: false`）。 +每个渠道在其配置段存在时都会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | ---------------------------------------------- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储） | -| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有入站私信 | +| 私信策略 | 行为 | +| --------------------- | ---------------------------------------------------------------- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许存储中的发送者） | +| `open` | 允许所有传入私信（要求 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ---------------------------------------------- | -| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | -| `open` | 绕过群组允许列表（仍然适用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| ----------------------- | ------------------------------------------------------ | +| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | +| `open` | 绕过群组允许列表（仍会应用提及门控） | +| `disabled` | 屏蔽所有群组 / 房间消息 | `channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时作为默认值。 -配对码会在 1 小时后过期。待处理的私信配对请求在**每个渠道**中上限为 **3 个**。 -如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（失败即关闭），并在启动时发出警告。 +配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。 +如果某个提供商配置块完全缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（失败即关闭），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当会话尚未有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 +使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。只有在会话尚未设置模型覆盖时（例如通过 `/model` 设置），才会应用渠道映射。 ```json5 { @@ -91,10 +91,10 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时使用的后备群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。可选值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时的后备群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。可选值：`all`（默认，包含所有引用 / 线程 / 历史上下文）、`allowlist`（仅包含允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用 / 回复上下文）。每渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 -- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 +- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级 / 错误状态。 - `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 ### WhatsApp @@ -110,7 +110,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // 已读回执（自聊模式下为 false） groups: { "*": { requireMention: true }, }, @@ -151,8 +151,8 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 ``` - 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置的账号 ID（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖上述默认账号选择逻辑。 -- 旧版单账号 Baileys 认证目录会被 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖该默认账号选择逻辑。 +- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -188,7 +188,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress（默认：off；需显式启用以避免预览编辑速率限制） actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -211,12 +211,12 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅接受常规文件；拒绝符号链接），默认账号可回退到 `TELEGRAM_BOT_TOKEN`。 +- Bot 令牌：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 - 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 在多账号设置（2 个及以上账号 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`），以避免回退路由；若缺失或无效，`openclaw doctor` 会发出警告。 +- 在多账号设置中（2 个及以上账号 ID），请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若缺失或无效，`openclaw doctor` 会发出警告。 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范格式 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中都可用）。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中均可用）。 - 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 ### Discord @@ -272,7 +272,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress（在 Discord 上 progress 会映射为 partial） maxLinesPerMessage: 17, ui: { components: { @@ -283,7 +283,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // 为 `sessions_spawn({ thread: true })` 显式启用 }, voice: { enabled: true, @@ -319,36 +319,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Token：`channels.discord.token`，默认账号可回退到 `DISCORD_BOT_TOKEN`。 -- 提供显式 Discord `token` 的直接出站调用会为该调用使用这个 token；账号重试/策略设置仍然来自活动运行时快照中所选账号。 +- 令牌：`channels.discord.token`，默认账号可回退到 `DISCORD_BOT_TOKEN`。 +- 直接出站调用若显式提供 Discord `token`，该次调用会使用该令牌；账号级重试 / 策略设置仍来自活动运行时快照中选定的账号。 - 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 使用 `user:`（私信）或 `channel:`（服务器频道）作为投递目标；裸数字 ID 会被拒绝。 -- 服务器 slug 为小写，空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用服务器 ID。 -- 默认会忽略机器人发送的消息。`allowBots: true` 可启用它们；使用 `allowBots: "mentions"` 则只接受提及机器人的机器人消息（仍会过滤自己的消息）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及频道覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）即使消息未超过 2000 字符，也会拆分过高的消息。 +- 交付目标请使用 `user:`（私信）或 `channel:`（服务器频道）；裸数字 ID 会被拒绝。 +- Guild slug 使用小写，并将空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。 +- 默认会忽略由机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其未超过 2000 字符。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定投递/路由） - - `idleHours`：按小时计算的 Discord 不活跃自动取消聚焦覆盖（`0` 禁用） - - `maxAgeHours`：按小时计算的 Discord 硬性最大时长覆盖（`0` 禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式启用开关 -- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道/线程 ID）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 + - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定交付 / 路由） + - `idleHours`：按小时设置不活动自动取消聚焦的 Discord 覆盖（`0` 为禁用） + - `maxAgeHours`：按小时设置硬性最大存活时间的 Discord 覆盖（`0` 为禁用） + - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建 / 绑定线程的显式启用开关 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道 / 线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 - `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。 -- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入和 TTS 覆盖。 +- `channels.discord.voice` 启用 Discord 语音频道对话及可选的自动加入 + TTS 覆盖。 - `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 -- OpenClaw 还会在反复解密失败后，通过离开/重新加入语音会话来尝试恢复语音接收。 -- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 -- `channels.discord.autoPresence` 会将运行时可用性映射为机器人状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变的名称/tag 匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 +- OpenClaw 还会在重复解密失败后通过离开 / 重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔 `streaming` 值会自动迁移。 +- `channels.discord.autoPresence` 将运行时可用性映射为机器人在线状态（健康 => online，降级 => idle，耗尽 => dnd），并允许可选的状态文本覆盖。 +- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称 / 标签匹配（紧急兼容模式）。 +- `channels.discord.execApprovals`：Discord 原生 exec 审批交付与审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到原始频道，`"both"` 两边都发送。当目标包含 `"channel"` 时，按钮仅对已解析出的审批人可用。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。 + - `sessionFilter`：可选会话键模式（子串或正则）。 + - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起频道，`"both"` 两者都发。若目标包含 `"channel"`，按钮仅可由已解析出的审批人使用。 - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**表情通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（针对所有消息中的 `guilds..users`）。 +**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（所有消息中来自 `guilds..users` 的用户）。 ### Google Chat @@ -379,11 +379,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 服务账号 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 使用 `spaces/` 或 `users/` 作为投递目标。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。 +- 交付目标请使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（紧急兼容模式）。 ### Slack @@ -433,8 +433,8 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 typingReaction: "hourglass_flowing_sand", textChunkLimit: 4000, chunkMode: "length", - streaming: "partial", // off | partial | block | progress (preview mode) - nativeStreaming: true, // use Slack native streaming API when streaming=partial + streaming: "partial", // off | partial | block | progress（预览模式） + nativeStreaming: true, // 当 streaming=partial 时使用 Slack 原生流式 API mediaMaxMb: 20, execApprovals: { enabled: "auto", // true | false | "auto" @@ -448,37 +448,37 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级或每账号级）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 +- **Socket 模式**要求同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP 模式**要求 `botToken` 加 `signingSecret`（可位于根级或账号级）。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 可接受明文 字符串或 SecretRef 对象。 -- Slack 账号快照会暴露每项凭证的来源/状态字段，例如 +- Slack 账号快照会暴露每个凭证的来源 / 状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 - `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef - 配置，但当前命令/运行时路径无法解析该 secret 值。 -- `configWrites: false` 会阻止 Slack 发起的配置写入。 + `signingSecretStatus`。`configured_unavailable` 表示该账号 + 通过 SecretRef 配置，但当前命令 / 运行时路径无法解析该密钥值。 +- `configWrites: false` 会阻止由 Slack 发起的配置写入。 - 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- `channels.slack.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 -- 使用 `user:`（私信）或 `channel:` 作为投递目标。 +- `channels.slack.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔 `streaming` 值会自动迁移。 +- 交付目标请使用 `user:`（私信）或 `channel:`。 -**表情通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 为每线程（默认）或在整个频道内共享。`thread.inheritParent` 会把父频道转录内容复制到新线程。 +**线程会话隔离：** `thread.historyScope` 可按线程隔离（默认）或在频道中共享。`thread.inheritParent` 会将父频道转录复制到新线程中。 -- `typingReaction` 会在回复运行期间，临时给入站 Slack 消息添加一个表情，完成后移除。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。与 Discord 使用相同模式：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- `typingReaction` 会在回复执行期间给传入的 Slack 消息添加一个临时反应，并在完成后移除。请使用 Slack emoji 短代码，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批交付与审批人授权。其结构与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 说明 | -| ------------ | -------- | ------------------ | -| reactions | 启用 | 添加表情 + 列出表情 | -| messages | 启用 | 读取/发送/编辑/删除 | -| pins | 启用 | 置顶/取消置顶/列出 | -| memberInfo | 启用 | 成员信息 | -| emojiList | 启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | -------- | ---------------------- | +| reactions | 已启用 | 添加反应 + 列出反应 | +| messages | 已启用 | 读取 / 发送 / 编辑 / 删除 | +| pins | 已启用 | 置顶 / 取消置顶 / 列表 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义 emoji 列表 | ### Mattermost -Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -495,10 +495,10 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` "team-channel-id": { requireMention: false }, }, commands: { - native: true, // opt-in + native: true, // 显式启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // 面向反向代理 / 公网部署的可选显式 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -513,15 +513,14 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` 启用 Mattermost 原生命令时： - `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问。 -- 原生 slash 回调使用 Mattermost 在 slash 命令注册期间返回的每命令 token - 进行身份验证。如果注册失败或没有命令被激活，OpenClaw 会拒绝回调，并返回 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，且 Mattermost 服务器可访问。 +- 原生 slash 回调使用 Mattermost 在注册 slash 命令时返回的每命令令牌进行认证。如果注册失败或未激活任何命令，OpenClaw 会拒绝回调并返回 `Unauthorized: invalid command token.` -- 对于私有/tailnet/internal 回调主机，Mattermost 可能要求 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。 - 请使用主机/域名值，而不是完整 URL。 -- `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。 -- `channels.mattermost.requireMention`：在频道中回复前要求有 `@mention`。 +- 对于私有 / tailnet / 内部回调主机，Mattermost 可能要求 + `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机 / 域名。 + 请使用主机 / 域名值，而不是完整 URL。 +- `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 +- `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。 - `channels.mattermost.groups..requireMention`：每频道提及门控覆盖（`"*"` 为默认值）。 - 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 @@ -532,7 +531,7 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // 可选账号绑定 dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -544,15 +543,15 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` } ``` -**表情通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -- `channels.signal.account`：将渠道启动固定到特定 Signal 账号标识。 -- `channels.signal.configWrites`：允许或拒绝 Signal 发起的配置写入。 +- `channels.signal.account`：将渠道启动固定到特定 Signal 账号身份。 +- `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 - 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.bluebubbles` 下配置）。 +BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `channels.bluebubbles`）。 ```json5 { @@ -560,8 +559,8 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.blueb bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // serverUrl、password、webhookPath、群组控制与高级操作： + // 见 /channels/bluebubbles }, }, } @@ -569,12 +568,12 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.blueb - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 - 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 -- 完整 BlueBubbles 渠道配置记录于 [BlueBubbles](/zh-CN/channels/bluebubbles)。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 完整的 BlueBubbles 渠道配置见 [BlueBubbles](/zh-CN/channels/bluebubbles)。 ### iMessage -OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 +OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。无需守护进程或端口。 ```json5 { @@ -600,13 +599,13 @@ OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护 - 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 需要对 Messages 数据库授予完全磁盘访问权限。 +- 需要对 Messages 数据库授予 Full Disk Access。 - 优先使用 `chat_id:` 目标。可用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；为 SCP 附件抓取设置 `remoteHost`（`host` 或 `user@host`）。 -- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 -- `channels.imessage.configWrites`：允许或拒绝 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用标准化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- `cliPath` 可指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 +- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 +- SCP 使用严格的主机密钥校验，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 @@ -619,7 +618,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展支持，在 `channels.matrix` 下配置。 +Matrix 由扩展支持，配置位于 `channels.matrix`。 ```json5 { @@ -649,24 +648,25 @@ Matrix 由扩展支持，在 `channels.matrix` 下配置。 } ``` -- Token 身份验证使用 `accessToken`；密码身份验证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会让 Matrix HTTP 流量通过显式 HTTP(S) 代理。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.allowPrivateNetwork` 允许私有/internal homeserver。`proxy` 和 `allowPrivateNetwork` 是相互独立的控制项。 +- 令牌认证使用 `accessToken`；密码认证使用 `userId` + `password`。 +- `channels.matrix.proxy` 通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。命名账号可使用 `channels.matrix.accounts..proxy` 覆盖。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有 / 内部 homeserver。`proxy` 与该网络显式启用是两个独立控制项。 - `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 +- `channels.matrix.autoJoin` 默认是 `off`，因此收到邀请的房间和新建私信式邀请都会被忽略，直到你设置 `autoJoin: "allowlist"` 搭配 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 审批交付与审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（原房间）或 `"both"`。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。 + - `sessionFilter`：可选会话键模式（子串或正则）。 + - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 - 每账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归入会话：`per-user`（默认）按路由对端共享，`per-room` 为每个私信房间单独隔离。 -- Matrix 状态探测和实时目录查找与运行时流量使用相同的代理策略。 -- 完整的 Matrix 配置、目标规则和设置示例记录于 [Matrix](/zh-CN/channels/matrix)。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归入会话：`per-user`（默认）按路由对端共享，`per-room` 则将每个私信房间隔离。 +- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 +- 完整的 Matrix 配置、目标规则和设置示例见 [Matrix](/zh-CN/channels/matrix)。 ### Microsoft Teams -Microsoft Teams 由扩展支持，在 `channels.msteams` 下配置。 +Microsoft Teams 由扩展支持，配置位于 `channels.msteams`。 ```json5 { @@ -674,19 +674,19 @@ Microsoft Teams 由扩展支持，在 `channels.msteams` 下配置。 msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // appId、appPassword、tenantId、webhook、团队 / 频道策略： + // 见 /channels/msteams }, }, } ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整 Teams 配置（凭证、webhook、私信/群组策略、每团队/每频道覆盖）记录于 [Microsoft Teams](/zh-CN/channels/msteams)。 +- 完整的 Teams 配置（凭证、webhook、私信 / 群组策略、按团队 / 频道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。 ### IRC -IRC 由扩展支持，在 `channels.irc` 下配置。 +IRC 由扩展支持，配置位于 `channels.irc`。 ```json5 { @@ -709,11 +709,11 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 - 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 完整 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）记录于 [IRC](/zh-CN/channels/irc)。 +- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）见 [IRC](/zh-CN/channels/irc)。 ### 多账号（所有渠道） -为每个渠道运行多个账号（每个账号都有自己的 `accountId`）： +为单个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -734,18 +734,18 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 } ``` -- 省略 `accountId` 时使用 `default`（CLI + 路由）。 -- 环境变量 token 仅适用于 **default** 账号。 -- 基础渠道设置会应用到所有账号，除非在账号级单独覆盖。 +- 当省略 `accountId` 时，使用 `default`（CLI + 路由）。 +- 环境变量令牌仅适用于**默认**账号。 +- 基础渠道设置适用于所有账号，除非在账号级覆盖。 - 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。 -- 如果你在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加了一个非默认账号，OpenClaw 会先把带账号作用域的顶层单账号值提升到渠道账号映射中，以便原始账号继续工作。多数渠道会把它们移到 `channels..accounts.default`；Matrix 则可以保留现有匹配的命名/default 目标。 -- 现有仅渠道级绑定（无 `accountId`）仍会匹配默认账号；账号级绑定仍然是可选的。 -- `openclaw doctor --fix` 也会修复混合结构：把带账号作用域的顶层单账号值移动到为该渠道选定的提升账号中。多数渠道使用 `accounts.default`；Matrix 则可以保留现有匹配的命名/default 目标。 +- 如果你在仍使用单账号顶层渠道配置的情况下，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先把账号范围内的顶层单账号值提升到渠道账号映射中，以保证原始账号继续可用。大多数渠道会将它们移到 `channels..accounts.default`；Matrix 则可保留现有匹配的命名 / 默认目标。 +- 现有仅限渠道的绑定（无 `accountId`）仍会匹配默认账号；账号级绑定仍是可选的。 +- `openclaw doctor --fix` 也会修复混合结构：将账号范围内的顶层单账号值移动到该渠道选定的提升账号。大多数渠道使用 `accounts.default`；Matrix 则可保留现有匹配的命名 / 默认目标。 ### 其他扩展渠道 -许多扩展渠道配置为 `channels.`，并在各自的专用渠道页面中有文档说明（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -请参见完整渠道索引：[Channels](/zh-CN/channels)。 +许多扩展渠道配置为 `channels.`，并在各自的渠道页面中有文档说明（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +参见完整渠道索引：[Channels](/zh-CN/channels)。 ### 群聊提及门控 @@ -753,9 +753,9 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 **提及类型：** -- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式中会被忽略。 -- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 只有在能够检测到提及的情况下（原生提及或至少有一个模式）才会强制执行提及门控。 +- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式下会被忽略。 +- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 +- 仅在能够检测到提及（原生提及或至少一个模式）时才会强制应用提及门控。 ```json5 { @@ -768,7 +768,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或每账号）覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或每账号）覆盖。设为 `0` 可禁用。 #### 私信历史限制 @@ -785,13 +785,13 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 } ``` -解析顺序：每私信覆盖 → 提供商默认值 → 无限制（全部保留）。 +解析顺序：每私信覆盖 → 提供商默认值 → 不限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### 自聊模式 -把你自己的号码加入 `allowFrom` 即可启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码加入 `allowFrom` 可启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -817,13 +817,13 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ```json5 { commands: { - native: "auto", // register native commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // 在支持时注册原生命令 + text: true, // 解析聊天消息中的 /commands + bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, - config: false, // allow /config - debug: false, // allow /debug - restart: false, // allow /restart + gateway restart tool + config: false, // 允许 /config + debug: false, // 允许 /debug + restart: false, // 允许 /restart + gateway restart tool allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -837,14 +837,14 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 - 文本命令必须是带前导 `/` 的**独立**消息。 - `native: "auto"` 会为 Discord/Telegram 打开原生命令，而将 Slack 保持关闭。 -- 可按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除之前已注册的命令。 -- `channels.telegram.customCommands` 会添加额外 Telegram 机器人菜单项。 -- `bash: true` 启用主机 shell 的 `! `（别名：`/bash`）。需要 `tools.elevated.enabled`，并且发送者位于 `tools.elevated.allowFrom.` 中。 -- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 对普通具有写作用域的 operator 客户端仍可用。 -- `channels..configWrites` 按渠道控制配置修改（默认：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 也会控制以该账号为目标的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `allowFrom` 按提供商生效。设置后，它会成为**唯一**的授权来源（会忽略渠道允许列表/配对和 `useAccessGroups`）。 -- 当未设置 `allowFrom` 时，`useAccessGroups: false` 允许命令绕过访问组策略。 +- 每渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。 +- `channels.telegram.customCommands` 可添加额外的 Telegram 机器人菜单项。 +- `bash: true` 启用主机 shell 的 `! `。要求 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 +- `config: true` 启用 `/config`（读取 / 写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 对普通写权限的 operator 客户端仍然可用。 +- `channels..configWrites` 按渠道控制配置变更（默认：true）。 +- 对于多账号渠道，`channels..accounts..configWrites` 还会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `allowFrom` 按提供商生效。设置后，它会成为**唯一**授权来源（渠道允许列表 / 配对以及 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 允许在未设置 `allowFrom` 时，命令绕过访问组策略。 @@ -864,7 +864,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。若未设置，OpenClaw 会从工作区开始向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。未设置时，OpenClaw 会从工作区向上遍历自动检测。 ```json5 { @@ -881,9 +881,9 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // 继承 github, weather + { id: "docs", skills: ["docs-search"] }, // 替换默认值 + { id: "locked-down", skills: [] }, // 无 Skills ], }, } @@ -891,13 +891,13 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 - 省略 `agents.defaults.skills` 表示默认不限制 Skills。 - 省略 `agents.list[].skills` 表示继承默认值。 -- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。 -- 非空的 `agents.list[].skills` 列表会成为该智能体的最终集合；它 - 不会与默认值合并。 +- 设置 `agents.list[].skills: []` 表示不允许任何 Skills。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合； + 它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）的自动创建。 +禁用自动创建工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -907,9 +907,9 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.contextInjection` -控制何时将工作区引导文件注入到系统提示中。默认值：`"always"`。 +控制何时将工作区 bootstrap 文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全续接轮次（在助手完成一次响应之后）会跳过重新注入工作区引导内容，从而减小提示大小。心跳运行和压缩后的重试仍会重建上下文。 +- `"continuation-skip"`：安全续接轮次（在助手完成回复之后）会跳过重新注入工作区 bootstrap，从而减少提示大小。心跳运行和压缩后的重试仍会重建上下文。 ```json5 { @@ -919,7 +919,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.bootstrapMaxChars` -每个工作区引导文件在截断前的最大字符数。默认值：`20000`。 +每个工作区 bootstrap 文件在被截断前允许的最大字符数。默认值：`20000`。 ```json5 { @@ -929,7 +929,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.bootstrapTotalMaxChars` -注入的所有工作区引导文件的总最大字符数。默认值：`150000`。 +所有工作区 bootstrap 文件合计可注入的最大字符数。默认值：`150000`。 ```json5 { @@ -939,12 +939,12 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制在引导上下文被截断时，是否向智能体可见地注入警告文本。 +控制 bootstrap 上下文被截断时，向智能体可见的警告文本。 默认值：`"once"`。 -- `"off"`：绝不将警告文本注入系统提示。 -- `"once"`：对每个唯一的截断签名注入一次警告（推荐）。 -- `"always"`：只要存在截断，每次运行都注入警告。 +- `"off"`：永不将警告文本注入系统提示。 +- `"once"`：对每个唯一截断签名只注入一次警告（推荐）。 +- `"always"`：只要存在截断，就在每次运行时都注入警告。 ```json5 { @@ -954,11 +954,11 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图片块中最长边的最大像素尺寸。 +在调用提供商前，转录 / 工具图片块中图片最长边的最大像素值。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量和请求负载大小，尤其适用于大量截图的运行。 -较高的值会保留更多视觉细节。 +较低值通常可减少视觉 token 使用量和请求负载大小，适合截图较多的运行。 +较高值则可保留更多视觉细节。 ```json5 { @@ -968,7 +968,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.userTimezone` -系统提示上下文所用的时区（不是消息时间戳）。会回退到主机时区。 +系统提示上下文中使用的时区（不是消息时间戳）。会回退到主机时区。 ```json5 { @@ -1016,7 +1016,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // 全局默认提供商参数 pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1032,42 +1032,42 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ``` - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 字符串形式只设置主模型。 - - 对象形式设置主模型以及按顺序排列的故障转移模型。 + - 字符串形式仅设置主模型。 + - 对象形式设置主模型加有序故障切换模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 被 `image` 工具路径用作其视觉模型配置。 - - 当所选/默认模型不能接受图片输入时，也会用作后备路由。 + - 当所选 / 默认模型无法接收图片输入时，也用作后备路由。 - `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的图像生成能力，以及任何将来会生成图像的工具/插件表面。 - - 常见值：`google/gemini-3.1-flash-image-preview`（Gemini 原生图像生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-1`（OpenAI Images）。 - - 如果你直接选择某个 provider/model，也请配置相应的提供商认证/API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出有认证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的图像生成提供商。 + - 用于共享图片生成功能，以及任何未来生成图片的工具 / 插件接口。 + - 典型值：`google/gemini-3.1-flash-image-preview`（Gemini 原生图片生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-1`（OpenAI Images）。 + - 如果你直接选择某个 provider/model，也需要配置对应提供商的认证 / API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 + - 若省略，`image_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的图片生成提供商。 - `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的音乐生成能力和内置 `music_generate` 工具。 - - 常见值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断出有认证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个 provider/model，也请配置相应的提供商认证/API key。 + - 用于共享音乐生成功能以及内置 `music_generate` 工具。 + - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 + - 若省略，`music_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个 provider/model，也需要配置对应提供商的认证 / API key。 - `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的视频生成能力和内置 `video_generate` 工具。 - - 常见值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断出有认证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个 provider/model，也请配置相应的提供商认证/API key。 - - 内置的 Qwen 视频生成提供商目前最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 + - 用于共享视频生成功能以及内置 `video_generate` 工具。 + - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 + - 若省略，`video_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个 provider/model，也需要配置对应提供商的认证 / API key。 + - 内置的 Qwen 视频生成提供商当前最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 - `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被 `pdf` 工具用于模型路由。 - - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到解析后的会话/默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具在提取回退模式中考虑的默认最大页数。 -- `verboseDefault`：智能体的默认详细程度。可选值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 -- `elevatedDefault`：智能体的默认提权输出级别。可选值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置 provider，最后才回退到已配置的默认 provider（这是已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该 provider 不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是继续使用已失效、已移除的 provider 默认值。 -- `models`：已配置的模型目录和 `/model` 允许列表。每个条目可以包含 `alias`（快捷名）和 `params`（provider 专属参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 -- `params`：适用于所有模型的全局默认提供商参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（每模型）覆盖，然后 `agents.list[].params`（匹配智能体 id）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及后备添加/删除命令）会保存规范对象形式，并在可能时保留现有后备列表。 -- `maxConcurrent`：会话之间允许的最大并行智能体运行数（每个会话本身仍是串行）。默认值：4。 + - 供 `pdf` 工具用于模型路由。 + - 若省略，PDF 工具会回退到 `imageModel`，再回退到解析后的会话 / 默认模型。 +- `pdfMaxBytesMb`：当调用时未传 `maxBytesMb`，`pdf` 工具的默认 PDF 大小限制。 +- `pdfMaxPages`：`pdf` 工具中提取回退模式默认考虑的最大页数。 +- `verboseDefault`：智能体默认 verbose 级别。可选值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 +- `elevatedDefault`：智能体默认 elevated-output 级别。可选值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果省略 provider，OpenClaw 会先尝试别名，再尝试与该精确 model id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是继续使用过时的已移除提供商默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用于所有模型的全局默认提供商参数。设置于 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（每模型）覆盖，然后 `agents.list[].params`（匹配智能体 id）再按键覆盖。详情见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- 修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及后备添加 / 删除命令）会保存规范对象形式，并尽可能保留现有后备列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍串行）。默认值：4。 -**内置别名简写**（仅在模型位于 `agents.defaults.models` 中时适用）： +**内置别名简写**（仅当模型存在于 `agents.defaults.models` 中时生效）： | 别名 | 模型 | | ------------------- | -------------------------------------- | @@ -1080,15 +1080,15 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -你配置的别名始终优先于默认值。 +你自己配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 +Z.AI 的 GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 +Z.AI 模型默认启用 `tool_stream` 以支持工具调用流式传输。设置 `agents.defaults.models["zai/"].params.tool_stream` 为 `false` 可禁用。 Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -可选的 CLI 后端，用于纯文本回退运行（不调用工具）。当 API 提供商失败时，可作为备份。 +适用于纯文本后备运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备份。 ```json5 { @@ -1116,9 +1116,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- CLI 后端以文本优先；工具始终禁用。 +- CLI 后端以文本优先；工具始终被禁用。 - 当设置了 `sessionArg` 时支持会话。 -- 当 `imageArg` 接受文件路径时支持图片透传。 +- 当 `imageArg` 接受文件路径时，支持图片透传。 ### `agents.defaults.heartbeat` @@ -1129,15 +1129,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m 为禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + lightContext: false, // 默认：false；true 时仅从工作区 bootstrap 文件中保留 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 时每次心跳都在全新会话中运行（无对话历史） session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow（默认）| block + target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1147,13 +1147,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API-key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 - `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告负载。 -- `directPolicy`：直连/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行使用轻量引导上下文，并且仅保留工作区引导文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳运行都会在一个全新的会话中执行，没有此前的对话历史。与 cron 的 `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降低到约 2-5K。 -- 每智能体：设置 `agents.list[].heartbeat`。如果任意智能体定义了 `heartbeat`，则**只有这些智能体**会运行心跳。 -- 心跳会执行完整智能体轮次 —— 更短的间隔会消耗更多 token。 +- `directPolicy`：直接 / 私信交付策略。`allow`（默认）允许直接目标交付。`block` 则抑制直接目标交付，并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，心跳运行使用轻量 bootstrap 上下文，并仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳运行都在无任何先前对话历史的新会话中执行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降到约 2-5K。 +- 每智能体：设置 `agents.list[].heartbeat`。若任意智能体定义了 `heartbeat`，则**只有这些智能体**会运行心跳。 +- 心跳会运行完整的智能体轮次——间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -1166,10 +1166,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send a brief notice when compaction starts (default: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 + postCompactionSections: ["Session Startup", "Red Lines"], // [] 为禁用重新注入 + model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 + notifyUser: true, // compaction 开始时给用户发送简短通知（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1183,17 +1183,17 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 放弃单次压缩操作前允许的最大秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要时预置内置的不透明标识符保留指导。 +- `timeoutSeconds`：OpenClaw 在中止单次 compaction 操作前允许的最大秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内建的非透明标识符保留指导。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：压缩后要重新注入的可选 AGENTS.md H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。当未设置，或显式设置为该默认对时，也会接受旧版 `Every Session`/`Safety` 标题作为兼容回退。 -- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当你希望主会话继续使用一个模型，而压缩摘要在另一个模型上运行时可使用它；未设置时，压缩使用会话的主模型。 -- `notifyUser`：为 `true` 时，在压缩开始时向用户发送简短提示（例如 “Compacting context...”）。默认禁用，以保持压缩静默。 -- `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。工作区只读时会跳过。 +- `postCompactionSections`：compaction 后可选重新注入的 AGENTS.md H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置或显式设置为该默认对时，旧版 `Every Session`/`Safety` 标题也会作为兼容回退被接受。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应继续使用一个模型，而 compaction 摘要应改用另一模型时使用；未设置时，compaction 使用会话主模型。 +- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如 “Compacting context...”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：在自动 compaction 之前进行静默智能体轮次以存储持久记忆。工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 之前，从内存上下文中裁剪**旧工具结果**。**不会**修改磁盘上的会话历史。 +在发送到 LLM 前，从内存上下文中裁剪**旧工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1201,7 +1201,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // 时长（ms/s/m/h），默认单位：分钟 keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1217,19 +1217,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 启用裁剪流程。 -- `ttl` 控制何时可以再次运行裁剪（以上次缓存触达之后计算）。 -- 裁剪会先对过大的工具结果执行软裁剪，如仍有需要，再对更旧的工具结果执行硬清除。 +- `mode: "cache-ttl"` 启用裁剪过程。 +- `ttl` 控制在上次缓存触碰后，多久可以再次运行裁剪。 +- 裁剪会先对过大的工具结果执行软截断，然后在需要时对更旧的工具结果执行硬清空。 -**软裁剪** 保留开头和结尾，中间插入 `...`。 +**软截断**会保留开头和结尾，并在中间插入 `...`。 -**硬清除** 会用占位符替换整个工具结果。 +**硬清空**会用占位符替换整个工具结果。 说明： -- 图片块永远不会被裁剪/清除。 -- 比例按字符计算（近似），不是精确 token 数。 -- 如果助手消息少于 `keepLastAssistants` 条，则跳过裁剪。 +- 图片块永远不会被截断 / 清空。 +- 比例按字符计算（近似值），不是精确 token 数。 +- 若 assistant 消息少于 `keepLastAssistants`，则跳过裁剪。 @@ -1245,19 +1245,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom（使用 minMs/maxMs） }, }, } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 - 渠道覆盖：`channels..blockStreamingCoalesce`（以及每账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500ms。每智能体覆盖：`agents.list[].humanDelay`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。每智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节参见 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节见 [Streaming](/zh-CN/concepts/streaming)。 -### 输入状态指示器 +### 输入中指示器 ```json5 { @@ -1270,7 +1270,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：私聊/被提及时为 `instant`，未提及的群聊为 `message`。 +- 默认值：私聊 / 被提及时为 `instant`，未提及的群聊为 `message`。 - 每会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 @@ -1279,7 +1279,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.sandbox` -为嵌入式智能体提供可选沙箱隔离。完整指南参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南见 [Sandboxing](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1325,7 +1325,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // 也支持 SecretRefs / 内联内容： // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1382,15 +1382,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `ssh`：通用 SSH 远程运行时 - `openshell`：OpenShell 运行时 -选择 `backend: "openshell"` 时，运行时专属设置将移到 +选择 `backend: "openshell"` 时，运行时专属设置会移动到 `plugins.entries.openshell.config`。 **SSH 后端配置：** -- `target`：`user@host[:port]` 格式的 SSH 目标 +- `target`：格式为 `user@host[:port]` 的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于每作用域工作区的远程绝对根路径 -- `identityFile` / `certificateFile` / `knownHostsFile`：传给 OpenSSH 的现有本地文件 +- `workspaceRoot`：每个 scope 工作区使用的绝对远程根目录 +- `identityFile` / `certificateFile` / `knownHostsFile`：传给 OpenSSH 的本地现有文件 - `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其物化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 @@ -1399,26 +1399,26 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前，从当前激活的 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后只播种远程工作区一次 -- 之后保持远程 SSH 工作区为规范源 +- 在创建或重建后仅初始化一次远程工作区 +- 之后将远程 SSH 工作区视为规范来源 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动将远程更改同步回主机 +- 不会自动将远程变更同步回主机 - 不支持沙箱浏览器容器 **工作区访问：** -- `none`：在 `~/.openclaw/sandboxes` 下使用每作用域沙箱工作区 +- `none`：每个 scope 的沙箱工作区位于 `~/.openclaw/sandboxes` - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` -**作用域：** +**Scope：** - `session`：每会话一个容器 + 工作区 -- `agent`：每个智能体一个容器 + 工作区（默认） +- `agent`：每智能体一个容器 + 工作区（默认） - `shared`：共享容器和工作区（无跨会话隔离） **OpenShell 插件配置：** @@ -1434,10 +1434,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // 可选 + gatewayEndpoint: "https://lab.example", // 可选 + policy: "strict", // 可选 OpenShell policy id + providers: ["openai"], // 可选 autoProviders: true, timeoutSeconds: 120, }, @@ -1449,30 +1449,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在 exec 前将本地内容播种到远程，在 exec 后同步回来；本地工作区保持为规范源 -- `remote`：在创建沙箱时将本地内容播种到远程一次，之后保持远程工作区为规范源 +- `mirror`：在 exec 前将本地同步到远程，在 exec 后再同步回来；本地工作区保持为规范来源 +- `remote`：仅在创建沙箱时将本地初始化到远程一次，之后将远程工作区视为规范来源 -在 `remote` 模式下，在播种步骤之后，于 OpenClaw 之外对主机本地所做的编辑不会自动同步到沙箱中。 -传输层使用 SSH 连接到 OpenShell 沙箱，但沙箱生命周期和可选镜像同步由插件负责。 +在 `remote` 模式下，seed 步骤之后，在 OpenClaw 之外对主机本地所做的编辑不会自动同步进沙箱。 +传输使用通过 SSH 连接 OpenShell 沙箱，但插件负责沙箱生命周期及可选的 mirror 同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。要求网络出口、可写根目录和 root 用户。 -**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。 -`"host"` 被阻止。默认情况下 `"container:"` 也被阻止，除非你显式设置 +**容器默认使用 `network: "none"`** ——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 +默认会阻止 `"host"`。`"container:"` 也默认被阻止，除非你显式设置 `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急开关）。 -**入站附件** 会被暂存到活动工作区中的 `media/inbound/*`。 +**传入附件** 会被暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 挂载额外的主机目录；全局和每智能体的 binds 会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局与每智能体的 binds 会被合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短期 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。会将 noVNC URL 注入系统提示。不要求在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短时效 token URL（而不是在共享 URL 中暴露密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话将主机浏览器作为目标。 -- `network` 默认是 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确想要全局 bridge 连通性时才设置为 `bridge`。 -- `cdpSourceRange` 可选地在容器边缘将 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅为沙箱浏览器容器挂载额外主机目录。设置后（包括 `[]`）会替换浏览器容器的 `docker.binds`。 -- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： +- `allowHostControl: false`（默认）会阻止沙箱隔离会话控制主机浏览器。 +- `network` 默认是 `openclaw-sandbox-browser`（专用 bridge 网络）。仅在你明确希望使用全局 bridge 连通性时才设为 `bridge`。 +- `cdpSourceRange` 可在容器边缘将 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅会将额外主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替代浏览器容器的 `docker.binds`。 +- 启动默认值定义于 `scripts/sandbox-browser-entrypoint.sh`，并针对容器主机调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1490,17 +1490,17 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短期 token UR - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`（默认启用） - - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认 - 开启；如果你的 WebGL/3D 工作流需要它们，可用 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 关闭。 + - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` + 默认启用，如 WebGL/3D 使用确有需要，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用。 - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流 依赖它们。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设置为 `0` 使用 Chromium 的 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 调整；设为 `0` 可使用 Chromium 的 默认进程限制。 - - 当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像的基线；如需更改容器默认行为，请使用带自定义 - 入口点的自定义浏览器镜像。 + - 当启用 `noSandbox` 时，额外加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；如需修改容器默认值，请使用带自定义 + entrypoint 的自定义浏览器镜像。 @@ -1509,8 +1509,8 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短期 token UR 构建镜像： ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # 主沙箱镜像 +scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` ### `agents.list`（每智能体覆盖） @@ -1525,12 +1525,12 @@ scripts/sandbox-browser-setup.sh # optional browser image name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } + thinkingDefault: "high", // 每智能体 thinking 级别覆盖 + reasoningDefault: "on", // 每智能体 reasoning 可见性覆盖 + fastModeDefault: false, // 每智能体 fast mode 覆盖 + params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params + skills: ["docs-search"], // 设置后会替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1562,25 +1562,25 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`：稳定的智能体 ID（必填）。 -- `default`：如果设置了多个，以第一个为准（会记录警告）。如果一个都没设，列表第一项为默认。 -- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局后备）。仅覆盖 `primary` 的 cron 作业仍会继承默认后备，除非你设置 `fallbacks: []`。 -- `params`：合并到 `agents.defaults.models` 中所选模型条目之上的每智能体流参数。用于这种按智能体区分的覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的每智能体 Skills 允许列表。如果省略，智能体会在已设置时继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示不启用任何 Skills。 -- `thinkingDefault`：可选的每智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。在未设置每消息或会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的每智能体默认 reasoning 可见性（`on | off | stream`）。在未设置每消息或会话 reasoning 覆盖时适用。 -- `fastModeDefault`：可选的每智能体 fast mode 默认值（`true | false`）。在未设置每消息或会话 fast-mode 覆盖时适用。 -- `runtime`：可选的每智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，可使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `default`：若设置了多个，取第一个（会记录警告）。若一个都没设，则列表中的第一个为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局后备）。仅覆盖 `primary` 的 cron 任务仍会继承默认后备，除非你设置 `fallbacks: []`。 +- `params`：每智能体流式参数，会在 `agents.defaults.models` 中选中模型条目的基础上合并。用于像 `cacheRetention`、`temperature`、`maxTokens` 这样的智能体级覆盖，而无需复制整个模型目录。 +- `skills`：可选的每智能体 Skills 允许列表。若省略，且设置了 `agents.defaults.skills`，则继承默认值；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 +- `thinkingDefault`：可选的每智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置每消息或会话级覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的每智能体默认 reasoning 可见性（`on | off | stream`）。在未设置每消息或会话级 reasoning 覆盖时生效。 +- `fastModeDefault`：可选的每智能体 fast mode 默认值（`true | false`）。在未设置每消息或会话级 fast-mode 覆盖时生效。 +- `runtime`：可选的每智能体运行时描述符。当智能体默认应使用 ACP harness 会话时，请使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 - `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：从 `emoji` 派生 `ackReaction`，从 `name`/`emoji` 派生 `mentionPatterns`。 +- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 - `subagents.allowAgents`：`sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝目标为无沙箱的运行。 -- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 +- 沙箱继承保护：如果请求方会话处于沙箱中，`sessions_spawn` 会拒绝运行目标为非沙箱的配置。 +- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关内运行多个相互隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关内运行多个隔离智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1599,11 +1599,11 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 绑定匹配字段 -- `type`（可选）：普通路由用 `route`（缺失时默认 route），持久 ACP 对话绑定用 `acp` +- `type`（可选）：普通路由使用 `route`（未指定 type 时默认即为 route），持久 ACP 会话绑定使用 `acp`。 - `match.channel`（必填） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；渠道专用） +- `match.guildId` / `match.teamId`（可选；特定渠道专用） - `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1615,13 +1615,13 @@ scripts/sandbox-browser-setup.sh # optional browser image 5. `match.accountId: "*"`（渠道范围） 6. 默认智能体 -在每个层级内，首个匹配的 `bindings` 条目获胜。 +在每个层级内，第一个匹配的 `bindings` 条目胜出。 -对于 `type: "acp"` 条目，OpenClaw 按精确会话标识（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 按精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。 ### 每智能体访问配置 - + ```json5 { @@ -1668,7 +1668,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1714,7 +1714,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -优先级细节参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1740,22 +1740,22 @@ scripts/sandbox-browser-setup.sh # optional browser image }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // 超过该 token 数时跳过父线程 fork（0 为禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // 时长或 false + maxDiskBytes: "500mb", // 可选硬预算 + highWaterBytes: "400mb", // 可选清理目标 }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // 默认按小时计算的不活动自动取消聚焦（`0` 为禁用） + maxAgeHours: 0, // 默认按小时计算的硬性最大存活时间（`0` 为禁用） }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // 旧版（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1768,34 +1768,34 @@ scripts/sandbox-browser-setup.sh # optional browser image - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在一个渠道上下文内，每个发送者拥有独立会话。 - - `global`：一个渠道上下文中的所有参与者共享同一会话（仅在明确需要共享上下文时使用）。 -- **`dmScope`**：私信如何分组。 + - `per-sender`（默认）：在某个渠道上下文中，每个发送者拥有独立会话。 + - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 +- **`dmScope`**：私信分组方式。 - `main`：所有私信共享主会话。 - `per-peer`：按发送者 ID 跨渠道隔离。 - - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 + - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多人收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 ID 映射到带 provider 前缀的对端，用于跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。如果两者都配置，以先到期者为准。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建分叉线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 - - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个全新线程会话，而不是继承父级转录历史。 - - 设置为 `0` 可禁用此保护，并始终允许父级分叉。 +- **`identityLinks`**：将规范 ID 映射到带提供商前缀的 peer，以实现跨渠道会话共享。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。若两者都配置，则先到期者生效。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍接受为 `direct` 的别名。 +- **`parentForkMaxTokens`**：创建 forked 线程会话时，允许的父会话 `totalTokens` 上限（默认 `100000`）。 + - 若父会话的 `totalTokens` 超过该值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。 + - 设为 `0` 可禁用该保护，并始终允许父级 fork。 - **`mainKey`**：旧版字段。运行时现在始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体间交换期间，智能体之间最多允许来回回复的轮次数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链接。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 获胜。 +- **`agentToAgent.maxPingPongTurns`**：智能体之间往返交互的最大回复轮次（整数，范围：`0`–`5`）。`0` 禁用 ping-pong 链式交互。 +- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 仍为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。先匹配到的 deny 规则胜出。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 实施清理。 - - `pruneAfter`：陈旧条目的年龄阈值（默认 `30d`）。 + - `mode`：`warn` 只发警告；`enforce` 实施清理。 + - `pruneAfter`：过期条目的时间阈值（默认 `30d`）。 - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认值与 `pruneAfter` 相同；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘硬预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的工件/会话。 - - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下优先删除最旧的工件 / 会话。 + - `highWaterBytes`：预算清理后的可选目标。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的不活跃自动取消聚焦时长（`0` 禁用；提供商可覆盖） - - `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 禁用；提供商可覆盖） + - `idleHours`：默认按小时计算的不活动自动取消聚焦（`0` 为禁用；提供商可覆盖） + - `maxAgeHours`：默认按小时计算的硬性最大存活时间（`0` 为禁用；提供商可覆盖） @@ -1806,7 +1806,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // 或 "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1821,7 +1821,7 @@ scripts/sandbox-browser-setup.sh # optional browser image }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 为禁用 byChannel: { whatsapp: 5000, slack: 1500, @@ -1831,38 +1831,38 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### 响应前缀 +### 回复前缀 -每渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +每渠道 / 账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** -| 变量 | 说明 | 示例 | -| ----------------- | -------------- | --------------------------- | -| `{model}` | 简短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`, `low`, `off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ------------------ | ------------------ | --------------------------- | +| `{model}` | 短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### 确认表情 +### 确认反应 -- 默认为当前活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 +- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 每渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认表情。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态表情。 - 在 Slack 和 Discord 上，未设置时会在确认表情启用时保持状态表情开启。 - 在 Telegram 上，需显式设置为 `true` 才会启用生命周期状态表情。 +- Scope：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。 +- `messages.statusReactions.enabled`：为 Slack、Discord 和 Telegram 启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时会在确认反应启用时保持状态反应开启。 + 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 ### 入站防抖 -会把来自同一发送者的快速纯文本消息合并为一个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 +将来自同一发送者的快速连续纯文本消息合并为单次智能体轮次。媒体 / 附件会立即冲刷。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1905,12 +1905,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 会按会话覆盖。 +- `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 可按会话覆盖。 - `summaryModel` 会覆盖自动摘要时使用的 `agents.defaults.model.primary`。 - `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认是 `false`（需显式启用）。 -- API keys 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序是配置，然后 `OPENAI_TTS_BASE_URL`，最后 `https://api.openai.com/v1`。 -- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽对 model/voice 的校验。 +- API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置、然后 `OPENAI_TTS_BASE_URL`、最后 `https://api.openai.com/v1`。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容 TTS 服务器，并放宽模型 / 声音校验。 --- @@ -1940,13 +1940,13 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.` 中。 +- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。 +- 旧版平铺 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 - Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 只有在未配置任何 Talk API key 时，才会回退到 `ELEVENLABS_API_KEY`。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久再发送转录。未设置时保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `ELEVENLABS_API_KEY` 仅在未配置 Talk API key 时作为回退。 +- `providers.*.voiceAliases` 允许 Talk 指令使用友好的名称。 +- `silenceTimeoutMs` 控制用户停止说话后，Talk 模式在发送转录前等待多久。未设置时保持平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- @@ -1954,37 +1954,37 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### 工具配置文件 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前先设置一个基础允许列表： +`tools.profile` 会在应用 `tools.allow`/`tools.deny` 前设置基础允许列表： -本地新手引导会在新本地配置中、该值未设置时，默认使用 `tools.profile: "coding"`（现有显式 profile 会保留）。 +本地新手引导会在未设置时，将新的本地配置默认为 `tools.profile: "coding"`（已显式设置的配置文件会被保留）。 -| 配置文件 | 包含内容 | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | -| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | -| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | -| `full` | 无限制（与未设置相同） | +| 配置文件 | 包含内容 | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | 仅 `session_status` | +| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | +| `messaging`| `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | +| `full` | 无限制（与未设置相同） | ### 工具组 -| 组 | 工具 | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | -| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括 provider 插件） | +| 组 | 工具 | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | +| `group:openclaw` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭，也会应用。 +全局工具允许 / 拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 ```json5 { @@ -1994,7 +1994,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -进一步限制特定提供商或模型可用的工具。顺序：基础 profile → 提供商 profile → allow/deny。 +针对特定提供商或模型进一步限制工具。顺序：基础配置文件 → 提供商配置文件 → allow/deny。 ```json5 { @@ -2010,7 +2010,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.elevated` -控制沙箱外的提权 exec 访问： +控制沙箱外的 elevated exec 访问： ```json5 { @@ -2026,9 +2026,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- 每智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧。 +- 每智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 - `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 -- 提权 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认 `gateway`，当 exec 目标为 `node` 时则使用 `node`）。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 ### `tools.exec` @@ -2052,8 +2052,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设置 `enabled: true` 以启用检测。 -可在全局 `tools.loopDetection` 中定义设置，并在每智能体的 `agents.list[].tools.loopDetection` 中覆盖。 +工具循环安全检查**默认禁用**。设置 `enabled: true` 可激活检测。 +可在全局 `tools.loopDetection` 中定义，并在每智能体 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2074,13 +2074,13 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `historySize`：为循环分析保留的最大工具调用历史。 -- `warningThreshold`：发出警告前，无进展重复模式的阈值。 -- `criticalThreshold`：阻止严重循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：任意无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展行为发出警告/阻止。 -- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 +- `historySize`：用于循环分析的最大工具调用历史保留数。 +- `warningThreshold`：用于发出警告的重复无进展模式阈值。 +- `criticalThreshold`：用于阻止严重循环的更高重复阈值。 +- `globalCircuitBreakerThreshold`：任何无进展运行触发硬停止的阈值。 +- `detectors.genericRepeat`：对重复的同工具 / 同参数调用发出警告。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展模式发出警告 / 阻止。 +- `detectors.pingPong`：对交替出现的成对无进展模式发出警告 / 阻止。 - 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，校验会失败。 ### `tools.web` @@ -2091,14 +2091,14 @@ Talk 模式的默认值（macOS/iOS/Android）。 web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // 或 BRAVE_API_KEY 环境变量 maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // 可选；省略则自动检测 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2115,7 +2115,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.media` -配置入站媒体理解（图片/音频/视频）： +配置传入媒体理解（图片 / 音频 / 视频）： ```json5 { @@ -2123,7 +2123,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // 显式启用：将完成的异步音乐 / 视频直接发送到渠道 }, audio: { enabled: true, @@ -2151,9 +2151,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 **提供商条目**（`type: "provider"` 或省略）： -- `provider`：API 提供商 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） -- `model`：模型 id 覆盖 -- `profile` / `preferredProfile`：`auth-profiles.json` profile 选择 +- `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） +- `model`：模型 ID 覆盖 +- `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 **CLI 条目**（`type: "cli"`）： @@ -2162,7 +2162,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 **通用字段：** -- `capabilities`：可选列表（`image`、`audio`、`video`）。默认：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 +- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每条目覆盖。 - 失败时会回退到下一个条目。 @@ -2171,8 +2171,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 **异步完成字段：** - `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会先尝试直接投递到渠道。默认：`false` - （旧版请求者会话唤醒/模型投递路径）。 + 和 `video_generate` 任务会优先尝试直接向渠道发送。默认值：`false` + （旧版请求方会话唤醒 / 模型交付路径）。 @@ -2210,9 +2210,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 - `self`：仅当前会话键。 - `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 -- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行 per-sender 会话，可能包含其他用户）。 +- `agent`：属于当前智能体 ID 的任意会话（如果你在同一个智能体 ID 下运行按发送者拆分的会话，则可能包含其他用户）。 - `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 -- 沙箱钳制：当当前会话处于沙箱隔离中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- 沙箱钳制：当当前会话处于沙箱中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2223,11 +2223,11 @@ Talk 模式的默认值（macOS/iOS/Android）。 tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // 显式启用：设为 true 以允许内联文件附件 + maxTotalBytes: 5242880, // 所有文件总计 5 MB maxFiles: 50, - maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + maxFileBytes: 1048576, // 每个文件 1 MB + retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件 }, }, }, @@ -2237,21 +2237,21 @@ Talk 模式的默认值（macOS/iOS/Android）。 说明： - 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会被物化到子工作区的 `.openclaw/attachments//` 中，并附带一个 `.manifest.json`。 +- 文件会被物化到子工作区的 `.openclaw/attachments//` 中，并带有 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会进行严格字母表/填充校验，以及解码前大小保护。 -- 文件权限为目录 `0700`、文件 `0600`。 -- 清理遵循 `cleanup` 策略：`delete` 始终移除附件；仅当 `retainOnSessionKeep: true` 时，`keep` 才保留它们。 +- Base64 输入会使用严格的字母表 / 填充校验以及解码前大小保护。 +- 文件权限为：目录 `0700`，文件 `0600`。 +- 清理遵循 `cleanup` 策略：`delete` 总会删除附件；仅当 `retainOnSessionKeep: true` 时，`keep` 才会保留附件。 ### `tools.experimental` -实验性内置工具开关。默认关闭，除非某条运行时专属自动启用规则适用。 +实验性内置工具开关。默认关闭，除非运行时特定自动启用规则生效。 ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // 启用实验性的 update_plan }, }, } @@ -2259,9 +2259,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 说明： -- `planTool`：为非琐碎的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认：对非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。 -- 启用后，系统提示还会添加使用指导，使模型只在实质性工作中使用它，并且最多仅保留一个 `in_progress` 步骤。 +- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认值：对非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。 +- 启用后，系统提示还会加入用法指导，以便模型只在较大工作中使用它，并始终保持最多一个步骤为 `in_progress`。 ### `agents.defaults.subagents` @@ -2281,21 +2281,21 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `model`：生成子智能体的默认模型。若省略，子智能体会继承调用方的模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 允许的默认目标智能体 id 列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时时间（秒）。`0` 表示无超时。 +- `model`：生成子智能体时使用的默认模型。若省略，子智能体会继承调用方模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 可用的默认目标智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时时长（秒）。`0` 表示无超时。 - 每子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## 自定义提供商和 base URL -OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge（默认）| replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2319,42 +2319,42 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 对于自定义认证需求，使用 `authHeader: true` + `headers`。 -- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 对于匹配的 provider ID，合并优先级如下： - - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在当前 config/auth-profile 上下文中，该 provider 不是 SecretRef 管理时才优先。 - - 由 SecretRef 管理的 provider `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`），而不是持久化已解析的 secrets。 - - 由 SecretRef 管理的 provider header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`）。 - - 智能体缺失或为空的 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。 - - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；用它来限制有效上下文，而不改变原生模型元数据。 - - 当你希望配置完整重写 `models.json` 时，使用 `models.mode: "replace"`。 - - 标记持久化以源为准：标记从当前源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。 +- 使用 `authHeader: true` + `headers` 可满足自定义认证需求。 +- 可通过 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 +- 匹配 provider ID 的合并优先级： + - 非空的智能体 `models.json` 中 `baseUrl` 值优先。 + - 非空的智能体 `apiKey` 值，仅在当前配置 / auth-profile 上下文中该提供商不是 SecretRef 管理时才优先。 + - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用用 `ENV_VAR_NAME`，文件 / exec 引用用 `secretref-managed`），而不是持久化解析后的密钥。 + - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用用 `secretref-env:ENV_VAR_NAME`，文件 / exec 引用用 `secretref-managed`）。 + - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 + - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值与隐式目录值中取更高者。 + - 匹配模型的 `contextTokens` 在存在显式运行时上限时会保留；可用它限制有效上下文，而不改变原生模型元数据。 + - 当你希望配置完全重写 `models.json` 时，请使用 `models.mode: "replace"`。 + - 标记持久化遵循源权威：标记来自活动源配置快照（解析前），而不是来自运行时已解析的密钥值。 ### 提供商字段详情 -- `models.mode`：provider 目录行为（`merge` 或 `replace`）。 +- `models.mode`：提供商目录行为（`merge` 或 `replace`）。 - `models.providers`：按 provider id 键控的自定义提供商映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 +- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef / 环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，在请求中注入 `options.num_ctx`（默认：`true`）。 -- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` 头传输凭证。 +- `models.providers.*.injectNumCtxForOpenAICompat`：用于 Ollama + `openai-completions` 时，向请求中注入 `options.num_ctx`（默认：`true`）。 +- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 -- `models.providers.*.headers`：用于代理/租户路由的额外静态头。 +- `models.providers.*.headers`：用于代理 / 租户路由的额外静态 headers。 - `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 - - `request.headers`：额外头（与提供商默认值合并）。值接受 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value` 和可选 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直接连接的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都接受 SecretRef）、`serverName`、`insecureSkipVerify`。 + - `request.headers`：额外 headers（与提供商默认值合并）。值支持 SecretRef。 + - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内建认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 + - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选 `tls` 子对象。 + - `request.tls`：直连时的 TLS 覆盖。字段包括：`ca`、`cert`、`key`、`passphrase`（均支持 SecretRef）、`serverName`、`insecureSkipVerify`。 - `models.providers.*.models`：显式提供商模型目录条目。 - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。如果你想要比模型原生 `contextWindow` 更小的有效上下文预算，可使用它。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且非空、非原生的 `baseUrl`（host 不是 `api.openai.com`），OpenClaw 会在运行时强制将其设为 `false`。空或省略的 `baseUrl` 会保留默认 OpenAI 行为。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。 -- `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。 -- `plugins.entries.amazon-bedrock.config.discovery.region`：发现所用 AWS 区域。 +- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空非原生值（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制其为 `false`。空或省略 `baseUrl` 时，保留默认 OpenAI 行为。 +- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根节点。 +- `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启 / 关闭隐式发现。 +- `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选 provider-id 过滤器，用于定向发现。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新轮询间隔。 - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的后备上下文窗口。 @@ -2396,7 +2396,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -对 Cerebras 使用 `cerebras/zai-glm-4.7`；对 Z.AI 直连使用 `zai/glm-4.7`。 +Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连则使用 `zai/glm-4.7`。 @@ -2413,7 +2413,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。对 Zen 目录使用 `opencode/...` 引用，对 Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 +设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录请使用 `opencode/...` 引用，Go 目录请使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 @@ -2430,11 +2430,11 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都可作为别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 +设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 也是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` - 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 若要使用通用端点，请定义带有 base URL 覆盖的自定义提供商。 +- 对于通用端点，请定义带 base URL 覆盖的自定义提供商。 @@ -2473,11 +2473,11 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -对于中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 +中国端点请使用：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 原生 Moonshot 端点会在共享的 -`openai-completions` 传输层上声明流式使用兼容性，OpenClaw 现在根据端点 -能力而不是仅凭内置 provider id 来判定这一点。 +`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 现在基于端点 +能力而不仅仅是内置 provider id 来判断这一点。 @@ -2495,11 +2495,11 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -兼容 Anthropic 的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +Anthropic 兼容、内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2534,7 +2534,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 +Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 @@ -2578,16 +2578,16 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录现在默认仅包含 M2.7。 -在兼容 Anthropic 的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw -默认会禁用 MiniMax thinking。`/fast on` 或 -`params.fastMode: true` 会把 `MiniMax-M2.7` 重写为 +在 Anthropic 兼容的流式路径上，OpenClaw 默认关闭 MiniMax thinking， +除非你显式设置 `thinking`。`/fast on` 或 +`params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能较强的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留合并后的托管模型用于回退。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在较强硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留托管模型用于后备。 @@ -2608,7 +2608,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或明文字符串 env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2618,14 +2618,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。 +- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管 / 工作区 Skills 不受影响）。 - `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 -- `install.preferBrew`：为 true 时，若 `brew` 可用，则优先使用 Homebrew 安装器， - 否则再回退到其他安装器类型。 -- `install.nodeManager`：`metadata.openclaw.install` - 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使某个 Skill 已内置/已安装，也会禁用它。 -- `entries..apiKey`：对声明了主环境变量的 Skill 提供简便配置（明文字符串或 SecretRef 对象）。 +- `install.preferBrew`：为 true 时，如果可用 `brew`，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 +- `install.nodeManager`：`metadata.openclaw.install` 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 Skill 已内置 / 已安装，也会禁用它。 +- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷 API key 字段（明文字符串或 SecretRef 对象）。 --- @@ -2654,34 +2652,34 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- 设备发现同时接受原生 OpenClaw 插件、兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 - **配置更改需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 和受支持的 bundle 提供 hooks 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可以为后台子智能体运行请求每次运行级别的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的可选规范 `provider/model` 目标允许列表。仅当你确实打算允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（若可用，会由原生 OpenClaw 插件 schema 校验）。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web 获取提供商设置。 - - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook 和受支持的 bundle 提供的 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅在你明确想允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（若可用，将由原生 OpenClaw 插件 schema 校验）。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web 抓取提供商设置。 + - `apiKey`：Firecrawl API key（支持 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 - - `onlyMainContent`：仅提取页面主内容（默认：`true`）。 - - `maxAgeMs`：最大缓存年龄（毫秒）（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。 + - `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`：记忆 dreaming（实验性）设置。阶段和阈值参见 [Dreaming](/zh-CN/concepts/dreaming)。 + - `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 * * *"`）。 - - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供内嵌 Pi 默认值；OpenClaw 会将它们作为已清理的智能体设置应用，而不是原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动记忆插件 id，或设置为 `"none"` 以禁用记忆插件。 -- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认是 `"legacy"`，除非你安装并选择了其他引擎。 -- `plugins.installs`：CLI 管理的安装元数据，由 `openclaw plugins update` 使用。 + - phase policy 和阈值属于实现细节（不是面向用户的配置键）。 +- 启用的 Claude bundle 插件还可从 `settings.json` 贡献嵌入式 Pi 默认值；OpenClaw 会将其作为清洗后的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动 memory 插件 ID，或用 `"none"` 禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动 context engine 插件 ID；默认是 `"legacy"`，除非你安装并选择了其他 engine。 +- `plugins.installs`：CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 请将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令，而不是手动编辑。 + - 请将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 参见 [Plugins](/zh-CN/tools/plugin)。 @@ -2696,8 +2694,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // default trusted-network mode - // allowPrivateNetwork: true, // legacy alias + dangerouslyAllowPrivateNetwork: true, // 默认受信网络模式 + // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2724,27 +2722,27 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认是 `true`（受信任网络模型）。 -- 如需严格的仅公共网络浏览导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。 -- 在严格模式下，远程 CDP profile 端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受相同的私有网络阻止策略约束。 -- `ssrfPolicy.allowPrivateNetwork` 仍被支持，作为旧版别名。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认是 `true`（受信网络模型）。 +- 若要严格限制为仅公有网络浏览导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性 / 设备发现检查期间也会受到相同的私有网络阻止。 +- `ssrfPolicy.allowPrivateNetwork` 仍支持作为旧版别名。 - 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。 -- 远程 profile 为仅附加模式（禁用 start/stop/reset）。 +- 远程配置文件是仅附加模式（不可 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)； - 当提供商直接给出 DevTools WebSocket URL 时使用 WS(S)。 -- `existing-session` profile 仅限主机使用，并使用 Chrome MCP 而不是 CDP。 -- `existing-session` profile 可设置 `userDataDir`，用于指向特定的 - 基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 -- `existing-session` profile 保持当前 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动的动作而不是 CSS 选择器定位，仅支持单文件上传 - hook，不支持对话框超时覆盖，不支持 `wait --load networkidle`，也不支持 - `responsebody`、PDF 导出、下载拦截或批量动作。 -- 本地受管 `openclaw` profile 会自动分配 `cdpPort` 和 `cdpUrl`；仅在 - 远程 CDP 场景下显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（如果是基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 + 当你希望 OpenClaw 自动发现 `/json/version` 时，请使用 HTTP(S)； + 若提供商直接给出了 DevTools WebSocket URL，则请使用 WS(S)。 +- `existing-session` 配置文件仅限主机使用，并通过 Chrome MCP 而非 CDP。 +- `existing-session` 配置文件可以设置 `userDataDir` 以定位特定的 + Chromium 系浏览器配置文件，如 Brave 或 Edge。 +- `existing-session` 配置文件会保留当前 Chrome MCP 路由限制： + 仅支持 snapshot/ref 驱动的操作，而不是 CSS 选择器定位；仅支持单文件上传 + hook；不支持对话框超时覆盖、`wait --load networkidle`、`responsebody`、 + PDF 导出、下载拦截或批量操作。 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有 + 在远程 CDP 场景下才需要显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 - 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会将额外启动标志附加到本地 Chromium 启动命令中（例如 +- `extraArgs` 会为本地 Chromium 启动附加额外标志（例如 `--disable-gpu`、窗口尺寸或调试标志）。 --- @@ -2757,14 +2755,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji、短文本、图片 URL 或 data URI }, }, } ``` -- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 身份覆盖。会回退到当前活动智能体身份。 +- `seamColor`：原生应用 UI 外框的强调色（Talk Mode 气泡着色等）。 +- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。 --- @@ -2779,8 +2777,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；见 /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2797,8 +2795,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 enabled: true, basePath: "/openclaw", // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2809,12 +2807,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // 可选。默认 false。 allowRealIpFallback: false, tools: { - // Additional /tools/invoke HTTP denies + // 附加的 /tools/invoke HTTP deny deny: ["browser"], - // Remove tools from the default HTTP deny list + // 从默认 HTTP deny 列表中移除工具 allow: ["gateway"], }, push: { @@ -2831,34 +2829,29 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加）。快捷方 -- `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 认证模式。这个无 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 origin 的反复失败不会自动 +- **旧版 bind 别名**：在 `gateway.bind` 中请使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 说明**：默认的 `loopback` bind 只会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会从 `eth0` 进入，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配 `customBindHost: "0.0.0.0"`）以在所有接口上监听。 +- **认证**：默认必须启用。非 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 认证模式。该无 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 origin 的重复失败不会自动 锁定另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开，需要认证）。 -- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback origin 时为必填。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头 origin 策略的部署启用 Host 头 origin 回退。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。 +- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。若预期浏览器客户端来自非 loopback origin，则必须设置。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host header origin 策略的部署启用 Host header origin 回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端紧急开关覆盖，允许明文 `ws://` 连接到受信任的私有网络 IP；默认情况下，明文仍仅限 loopback。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 gateway 认证。 -- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建将基于 relay 的注册发布到 gateway 后，gateway 所使用的外部 APNs relay 的 base HTTPS URL。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：gateway 到 relay 的发送超时时间（毫秒）。默认值为 `10000`。 -- 基于 relay 的注册会委托给特定的 gateway 身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并向 gateway 转发一个注册作用域的发送授权。其他 gateway 不能复用这个已存储的注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发的逃生开关，允许 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 -- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设置为 `0` 可全局禁用健康监控重启。默认：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认：`30`。 -- `gateway.channelMaxRestartsPerHour`：滚动一小时内，每个渠道/账号允许的最大健康监控重启 \ No newline at end of file +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧紧急开关，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍然只允许在 loopback 上使用明文。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 +- `gateway.push.apns.relay.baseUrl`：官方 / TestFlight iOS 构建在向 Gateway 网关发布中继支持注册后，用于外部 APNs relay 的 base HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值：`10000`。 +- 由 relay 支持的注册会被委托给某个特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并向 Gateway 网关转发一个以注册为范围的发送授权。其他 Gateway 网 \ No newline at end of file diff --git a/docs/zh-CN/gateway/doctor.md b/docs/zh-CN/gateway/doctor.md index 65ff32fcf..8cd0f5b45 100644 --- a/docs/zh-CN/gateway/doctor.md +++ b/docs/zh-CN/gateway/doctor.md @@ -1,21 +1,21 @@ --- read_when: - - 添加或修改 doctor 迁移 - - 引入破坏性配置变更 + - 添加或修改 Doctor 迁移时 + - 引入破坏性配置变更时 summary: Doctor 命令：健康检查、配置迁移和修复步骤 title: Doctor x-i18n: - generated_at: "2026-04-06T12:43:39Z" + generated_at: "2026-04-06T15:29:03Z" model: gpt-5.4 provider: openai - source_hash: f20637d373c3b1be7c4a3d5424228908b5639cfded8ad5acb9c29f882d0f8d2b + source_hash: a834dc7aec79c20d17bc23d37fb5f5e99e628d964d55bd8cf24525a7ee57130c source_path: gateway/doctor.md workflow: 15 --- # Doctor -`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的配置/状态，执行健康检查，并提供可操作的修复步骤。 +`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的配置 / 状态、检查健康状况，并提供可执行的修复步骤。 ## 快速开始 @@ -29,13 +29,13 @@ openclaw doctor openclaw doctor --yes ``` -接受默认值而不提示（包括在适用时的重启/服务/沙箱修复步骤）。 +接受默认选项而不提示（包括在适用时的重启 / 服务 / 沙箱修复步骤）。 ```bash openclaw doctor --repair ``` -不经提示直接应用推荐修复（在安全的情况下进行修复 + 重启）。 +不经提示应用推荐修复（在安全情况下执行修复 + 重启）。 ```bash openclaw doctor --repair --force @@ -47,16 +47,16 @@ openclaw doctor --repair --force openclaw doctor --non-interactive ``` -在无提示的情况下运行，并且仅应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。 +无提示运行，并且只应用安全迁移（配置规范化 + 磁盘状态迁移）。跳过需要人工确认的重启 / 服务 / 沙箱操作。 检测到旧状态迁移时会自动运行。 ```bash openclaw doctor --deep ``` -扫描系统服务以查找额外的 Gateway 网关安装（`launchd`/`systemd`/`schtasks`）。 +扫描系统服务中的额外 Gateway 网关安装（launchd/systemd/schtasks）。 -如果你想在写入前查看更改，先打开配置文件： +如果你想在写入前先查看变更，请先打开配置文件： ```bash cat ~/.openclaw/openclaw.json @@ -64,67 +64,67 @@ cat ~/.openclaw/openclaw.json ## 它会做什么（摘要） -- 针对 git 安装的可选飞行前更新（仅交互式）。 +- git 安装的可选预检更新（仅交互模式）。 - UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。 - 健康检查 + 重启提示。 -- Skills 状态摘要（可用/缺失/被阻止）和插件状态。 -- 对旧版值执行配置规范化。 -- 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 -- 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪情况的浏览器迁移检查。 +- Skills 状态摘要（可用 / 缺失 / 被阻止）和插件状态。 +- 旧版值的配置规范化。 +- 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 +- 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。 - OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。 -- 针对 OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。 -- 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。 -- 旧版插件清单 contract 键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。 -- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 回退任务）。 -- 会话锁文件检查和过期锁清理。 -- 状态完整性和权限检查（会话、转录、状态目录）。 +- OpenAI Codex OAuth 配置文件的 OAuth TLS 前提条件检查。 +- 旧版磁盘状态迁移（sessions / agent 目录 / WhatsApp 认证）。 +- 旧版插件清单契约键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。 +- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery / payload 字段、payload `provider`、简单的 `notify: true` webhook 回退任务）。 +- 会话锁文件检查和过时锁清理。 +- 状态完整性和权限检查（sessions、transcripts、状态目录）。 - 本地运行时的配置文件权限检查（`chmod 600`）。 -- 模型认证健康状态：检查 OAuth 过期情况，可刷新即将过期的令牌，并报告认证配置文件的冷却/禁用状态。 +- 模型认证健康检查：检查 OAuth 过期、可刷新即将过期的令牌，并报告 auth-profile 冷却 / 禁用状态。 - 额外工作区目录检测（`~/openclaw`）。 -- 启用沙箱隔离时执行沙箱镜像修复。 +- 启用沙箱隔离时的沙箱镜像修复。 - 旧版服务迁移和额外 Gateway 网关检测。 - Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。 -- Gateway 网关运行时检查（服务已安装但未运行；缓存的 `launchd` 标签）。 +- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。 - 渠道状态警告（从正在运行的 Gateway 网关探测）。 -- supervisor 配置审计（`launchd`/`systemd`/`schtasks`）及可选修复。 +- supervisor 配置审计（launchd/systemd/schtasks）并可选修复。 - Gateway 网关运行时最佳实践检查（Node 与 Bun、版本管理器路径）。 - Gateway 网关端口冲突诊断（默认 `18789`）。 - 针对开放私信策略的安全警告。 -- 本地令牌模式下的 Gateway 网关认证检查（当不存在令牌来源时提供生成令牌；不会覆盖令牌 SecretRef 配置）。 -- Linux 上的 `systemd linger` 检查。 -- 工作区 bootstrap 文件大小检查（上下文文件的截断/接近上限警告）。 -- Shell 补全状态检查和自动安装/升级。 -- 内存搜索嵌入提供商就绪情况检查（本地模型、远程 API 密钥或 QMD 二进制文件）。 -- 源码安装检查（`pnpm` 工作区不匹配、缺失 UI 资源、缺失 `tsx` 二进制文件）。 +- 本地令牌模式下的 Gateway 网关认证检查（当没有令牌来源时提供生成令牌；不会覆盖令牌 SecretRef 配置）。 +- Linux 上的 systemd linger 检查。 +- 工作区 bootstrap 文件大小检查（针对上下文文件的截断 / 接近上限警告）。 +- Shell 补全状态检查和自动安装 / 升级。 +- Memory search embedding 提供商就绪状态检查（本地模型、远程 API 密钥或 QMD 二进制文件）。 +- 源码安装检查（pnpm workspace 不匹配、缺失 UI 资源、缺失 tsx 二进制文件）。 - 写入更新后的配置 + 向导元数据。 -## 详细行为和原理说明 +## 详细行为和原理 -### 0）可选更新（git 安装） +### 0) 可选更新（git 安装） -如果这是一个 git 检出副本，并且 doctor 以交互方式运行，它会在运行 doctor 之前提供更新选项（fetch/rebase/build）。 +如果这是一个 git 检出，并且 Doctor 正在以交互模式运行，它会先提供更新（fetch / rebase / build），然后再运行 Doctor。 -### 1）配置规范化 +### 1) 配置规范化 -如果配置包含旧版值形态（例如 `messages.ackReaction` 没有渠道特定覆盖），doctor 会将其规范化为当前 schema。 +如果配置中包含旧版值形状（例如没有渠道专用覆盖的 `messages.ackReaction`），Doctor 会将它们规范化为当前 schema。 -这也包括旧版扁平 Talk 字段。当前公开的 Talk 配置是 +这也包括旧版的 Talk 扁平字段。当前公开的 Talk 配置是 `talk.provider` + `talk.providers.`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` 形式重写到 provider 映射中。 +`talk.apiKey` 形状重写到提供商映射中。 -### 2）旧版配置键迁移 +### 2) 旧版配置键迁移 -当配置中包含已弃用键时，其他命令会拒绝运行，并要求你运行 +当配置包含已弃用的键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。 Doctor 将会： - 说明发现了哪些旧版键。 -- 显示它应用的迁移。 +- 显示它所应用的迁移。 - 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。 -Gateway 网关 在启动时检测到旧版配置格式时，也会自动运行 doctor 迁移，因此过时配置无需手动干预即可被修复。 +当 Gateway 网关在启动时检测到旧版配置格式，也会自动运行 Doctor 迁移，因此无需手动干预就能修复过时配置。 Cron 任务存储迁移由 `openclaw doctor --fix` 处理。 当前迁移包括： @@ -139,100 +139,97 @@ Cron 任务存储迁移由 `openclaw doctor --fix` 处理。 - 旧版 `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` - `routing.transcribeAudio` → `tools.media.audio.models` -- `messages.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `messages.tts.providers.` -- `channels.discord.voice.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.voice.tts.providers.` -- `channels.discord.accounts..voice.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.accounts..voice.tts.providers.` -- `plugins.entries.voice-call.config.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `plugins.entries.voice-call.config.tts.providers.` +- `messages.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` +- `channels.discord.voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.` +- `channels.discord.accounts..voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts..voice.tts.providers.` +- `plugins.entries.voice-call.config.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.` - `plugins.entries.voice-call.config.provider: "log"` → `"mock"` - `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber` - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- 对于具有命名 `accounts` 但仍残留单账户顶层渠道值的渠道，将这些账户范围的值移动到该渠道所选的提升账户中（大多数渠道使用 `accounts.default`；Matrix 可保留现有匹配的命名/默认目标） +- 对于配置了命名 `accounts`、但仍保留单账户顶层渠道值的渠道，将这些账户范围的值移动到该渠道所选的提升账户中（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的命名 / 默认目标） - `identity` → `agents.list[].identity` -- `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents） +- `agent.*` → `agents.defaults` + `tools.*`（tools / elevated / exec / sandbox / subagents） - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - 删除 `browser.relayBindHost`（旧版扩展 relay 设置） -Doctor 警告还包括针对多账户渠道的默认账户指导： +Doctor 警告还包括针对多账户渠道的账户默认值指导： -- 如果配置了两个或更多 `channels..accounts` 条目，但没有 `channels..defaultAccount` 或 `accounts.default`，doctor 会警告回退路由可能会选择意外的账户。 -- 如果 `channels..defaultAccount` 设置为未知账户 ID，doctor 会发出警告并列出已配置的账户 ID。 +- 如果配置了两个或更多 `channels..accounts` 条目，但没有 `channels..defaultAccount` 或 `accounts.default`，Doctor 会警告回退路由可能会选择意外的账户。 +- 如果 `channels..defaultAccount` 设置为未知账户 ID，Doctor 会发出警告并列出已配置的账户 ID。 -### 2b）OpenCode 提供商覆盖 +### 2b) OpenCode 提供商覆盖 如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`， 它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。 -这可能会将模型强制路由到错误的 API，或将成本归零。Doctor 会发出警告，以便你删除该覆盖并恢复按模型的 API 路由 + 成本。 +这可能会把模型强制路由到错误的 API，或将成本清零。Doctor 会发出警告，以便你移除覆盖并恢复按模型的 API 路由 + 成本。 -### 2c）浏览器迁移和 Chrome MCP 就绪情况 +### 2c) 浏览器迁移和 Chrome MCP 就绪状态 -如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，doctor 会将其规范化为当前的主机本地 Chrome MCP 连接模型： +如果你的浏览器配置仍然指向已移除的 Chrome 扩展路径，Doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型： -- `browser.profiles.*.driver: "extension"` 变为 `"existing-session"` -- 删除 `browser.relayBindHost` +- `browser.profiles.*.driver: "extension"` 会变为 `"existing-session"` +- `browser.relayBindHost` 会被移除 当你使用 `defaultProfile: -"user"` 或已配置的 `existing-session` 配置文件时，doctor 还会审计主机本地的 Chrome MCP 路径： +"user"` 或已配置的 `existing-session` 配置文件时，Doctor 还会审计主机本地 Chrome MCP 路径： -- 检查默认自动连接配置文件是否在同一主机上安装了 Google Chrome -- 检查检测到的 Chrome 版本，并在其低于 Chrome 144 时发出警告 -- 提醒你在浏览器检查页面中启用远程调试（例如 +- 检查默认自动连接配置文件所在的同一主机上是否安装了 Google Chrome +- 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告 +- 提醒你在浏览器 inspect 页面启用远程调试（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging`， 或 `edge://inspect/#remote-debugging`） -Doctor 无法为你启用 Chrome 侧设置。主机本地 Chrome MCP -仍然需要： +Doctor 无法替你启用 Chrome 侧设置。主机本地 Chrome MCP 仍然需要： -- Gateway 网关/节点主机上的 Chromium 内核浏览器 144+ +- Gateway 网关 / 节点主机上安装 Chromium 内核浏览器 144+ - 浏览器在本地运行 - 在该浏览器中启用远程调试 -- 在浏览器中批准首次连接的同意提示 +- 在浏览器中批准首次附加同意提示 -这里的就绪情况仅涉及本地连接前置条件。Existing-session 保留当前 Chrome MCP 路由限制；像 `responsebody`、PDF 导出、下载拦截和批处理操作这样的高级路由仍然需要受管浏览器或原始 CDP 配置文件。 +这里的就绪状态仅涉及本地附加前提条件。Existing-session 仍保留当前 Chrome MCP 路由限制；像 `responsebody`、PDF 导出、下载拦截和批处理操作等高级路由仍然需要托管浏览器或原始 CDP 配置文件。 -此检查**不**适用于 Docker、沙箱、remote-browser 或其他无头流程。那些流程会继续使用原始 CDP。 +此检查**不**适用于 Docker、沙箱、remote-browser 或其他无头流程。这些流程仍继续使用原始 CDP。 -### 2d）OAuth TLS 前置条件 +### 2d) OAuth TLS 前提条件 -配置了 OpenAI Codex OAuth 配置文件时，doctor 会探测 OpenAI -授权端点，以验证本地 Node/OpenSSL TLS 栈是否能够校验证书链。如果探测因证书错误失败（例如 -`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），doctor 会输出特定于平台的修复指导。在使用 Homebrew Node 的 macOS 上， -修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，该探测也会运行。 +当配置了 OpenAI Codex OAuth 配置文件时，Doctor 会探测 OpenAI 授权端点，以验证本地 Node / OpenSSL TLS 栈是否可以校验证书链。如果探测因证书错误失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），Doctor 会打印平台专用修复指引。在 macOS 上，如果使用 Homebrew Node，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，该探测也会运行。 -### 3）旧版状态迁移（磁盘布局） +### 3) 旧版状态迁移（磁盘布局） Doctor 可以将旧版磁盘布局迁移到当前结构： -- 会话存储 + 转录： +- Sessions 存储 + transcripts： - 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents//sessions/` -- 智能体目录： +- Agent 目录： - 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents//agent/` - WhatsApp 认证状态（Baileys）： - - 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外） + - 从旧版 `~/.openclaw/credentials/*.json`（不包括 `oauth.json`） - 到 `~/.openclaw/credentials/whatsapp//...`（默认账户 id：`default`） -这些迁移尽力而为且可幂等；如果留下任何旧版文件夹作为备份，doctor 会发出警告。 -Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + 智能体目录，因此历史记录/认证/模型会进入按智能体划分的路径，而无需手动运行 doctor。WhatsApp 认证则有意仅通过 `openclaw doctor` 迁移。Talk provider/provider-map 规范化现在按结构相等进行比较，因此仅键顺序不同的差异不再触发重复的无操作 `doctor --fix` 更改。 +这些迁移尽力而为且具有幂等性；如果保留了任何旧版文件夹作为备份，Doctor 会发出警告。 +Gateway 网关 / CLI 也会在启动时自动迁移旧版 sessions + agent 目录，因此历史记录 / 认证 / 模型会落到按智能体划分的路径中，而无需手动运行 Doctor。WhatsApp 认证有意只通过 `openclaw doctor` 迁移。Talk provider / provider-map 规范化现在按结构相等性比较，因此仅键顺序不同的差异不再触发重复的无操作 `doctor --fix` 变更。 -### 3a）旧版插件清单迁移 +### 3a) 旧版插件清单迁移 -Doctor 会扫描所有已安装插件清单中的已弃用顶层 capability -键（`speechProviders`、`realtimeTranscriptionProviders`、 +Doctor 会扫描所有已安装插件清单中已弃用的顶层能力键 +（`speechProviders`、`realtimeTranscriptionProviders`、 `realtimeVoiceProviders`、`mediaUnderstandingProviders`、 `imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、 -`webSearchProviders`）。发现后，它会提供将它们移动到 `contracts` -对象并原地重写清单文件。此迁移是幂等的； -如果 `contracts` 键已经具有相同的值，则会删除旧版键，而不会重复数据。 +`webSearchProviders`）。发现后，它会提示将它们移动到 `contracts` +对象中，并原地重写清单文件。此迁移是幂等的； +如果 `contracts` 键中已经有相同值，就会删除旧版键， +而不会重复数据。 -### 3b）旧版 cron 存储迁移 +### 3b) 旧版 cron 存储迁移 -Doctor 还会检查 cron 任务存储（默认是 `~/.openclaw/cron/jobs.json`， -或者在覆盖时使用 `cron.store`）中调度器仍为兼容性而接受的旧任务形态。 +Doctor 还会检查 cron 任务存储（默认为 `~/.openclaw/cron/jobs.json`， +若有覆盖则使用 `cron.store`）中旧版任务形状，这些形状调度器仍为兼容性而接受。 当前 cron 清理包括： @@ -241,231 +238,189 @@ Doctor 还会检查 cron 任务存储（默认是 `~/.openclaw/cron/jobs.json` - 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload` - 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery` - payload `provider` delivery 别名 → 显式 `delivery.channel` -- 简单旧版 `notify: true` webhook 回退任务 → 显式 `delivery.mode="webhook"` 并带有 `delivery.to=cron.webhook` +- 简单的旧版 `notify: true` webhook 回退任务 → 显式 `delivery.mode="webhook"` 且 `delivery.to=cron.webhook` -Doctor 仅会在能够不改变行为的情况下自动迁移 `notify: true` 任务。 -如果某个任务将旧版 notify 回退与现有非 webhook delivery 模式组合使用，doctor 会发出警告并将该任务留给你手动审查。 +Doctor 仅在能够不改变行为的前提下自动迁移 `notify: true` 任务。如果某个任务将旧版 notify 回退与现有的非 webhook 传递模式结合使用，Doctor 会发出警告，并将该任务留待手动审查。 -### 3c）会话锁清理 +### 3c) 会话锁清理 -Doctor 会扫描每个智能体会话目录中的过期写锁文件——即会话异常退出后遗留的文件。对于发现的每个锁文件，它会报告： -路径、PID、PID 是否仍存活、锁的年龄，以及它是否被视为过期（PID 已死亡或超过 30 分钟）。在 `--fix` / `--repair` -模式下，它会自动删除过期锁文件；否则会打印说明，并指示你使用 `--fix` 重新运行。 +Doctor 会扫描每个智能体会话目录中的过时写锁文件 —— 这些文件是会话异常退出时残留的。对每个找到的锁文件，它会报告： +路径、PID、PID 是否仍存活、锁龄，以及是否被视为过时（PID 已死或已超过 30 分钟）。在 `--fix` / `--repair` +模式下，它会自动移除过时锁文件；否则它会打印说明，并指导你使用 `--fix` 重新运行。 -### 4）状态完整性检查（会话持久化、路由和安全） +### 4) 状态完整性检查（会话持久化、路由和安全） -状态目录是运行中的核心中枢。如果它消失了，你将失去 -会话、凭证、日志和配置（除非你在别处有备份）。 +状态目录是运行时的中枢神经。如果它消失了，你会丢失 +sessions、凭证、日志和配置（除非你在其他地方有备份）。 Doctor 会检查： -- **状态目录缺失**：警告灾难性的状态丢失，提示重新创建 - 目录，并提醒你它无法恢复丢失的数据。 -- **状态目录权限**：验证可写性；提供修复权限选项 - （检测到所有者/组不匹配时会给出 `chown` 提示）。 +- **状态目录缺失**：警告灾难性的状态丢失，提示重新创建目录，并提醒你它无法恢复缺失数据。 +- **状态目录权限**：验证可写性；提供修复权限的选项 + （并在检测到 owner / group 不匹配时给出 `chown` 提示）。 - **macOS 云同步状态目录**：当状态路径解析到 iCloud Drive （`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 - `~/Library/CloudStorage/...` 下时发出警告，因为由同步支持的路径可能导致更慢的 I/O - 和锁/同步竞争。 -- **Linux SD 或 eMMC 状态目录**：当状态路径解析到 `mmcblk*` - 挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入下可能更慢且磨损更快。 -- **会话目录缺失**：`sessions/` 和会话存储目录是 - 持久保存历史记录并避免 `ENOENT` 崩溃所必需的。 -- **转录不匹配**：当最近的会话条目缺少 - 转录文件时发出警告。 -- **主会话“1 行 JSONL”**：当主转录文件只有一行时标记出来（历史没有持续累积）。 -- **多个状态目录**：当不同 home 目录下存在多个 `~/.openclaw` 文件夹， - 或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史可能在多个安装之间分裂）。 -- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在 - 远程主机上运行它（状态存储在那里）。 -- **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对 - 组/所有人可读，则会发出警告并提供收紧到 `600` 的选项。 + `~/Library/CloudStorage/...` 下时发出警告，因为同步支持路径可能导致更慢的 I/O + 以及锁 / 同步竞争。 +- **Linux SD 或 eMMC 状态目录**：当状态路径解析为 `mmcblk*` + 挂载源时发出警告，因为由 SD 或 eMMC 支持的随机 I/O 在 session 和凭证写入下可能更慢且磨损更快。 +- **Session 目录缺失**：`sessions/` 和 session 存储目录是持久化历史记录并避免 `ENOENT` 崩溃所必需的。 +- **Transcript 不匹配**：当最近的 session 条目缺少 transcript 文件时发出警告。 +- **主 Session “单行 JSONL”**：当主 transcript 只有一行时标记出来（历史没有持续累积）。 +- **多个状态目录**：当不同 home 目录中存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史可能会在不同安装之间拆分）。 +- **远程模式提醒**：如果 `gateway.mode=remote`，Doctor 会提醒你在远程主机上运行它（状态保存在那里）。 +- **配置文件权限**：如果 `~/.openclaw/openclaw.json` + 对组 / 所有人可读，会发出警告并提供收紧到 `600` 的选项。 -### 5）模型认证健康状态（OAuth 过期） +### 5) 模型认证健康状态（OAuth 过期） -Doctor 会检查认证存储中的 OAuth 配置文件，在令牌 -即将过期/已过期时发出警告，并在安全时进行刷新。如果 Anthropic -OAuth/令牌配置文件已过期，它会建议使用 Anthropic API 密钥或旧版 +Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期 / 已过期时发出警告，并在安全时刷新它们。如果 Anthropic +OAuth / 令牌配置文件已过时，它会建议使用 Anthropic API 密钥或 Anthropic setup-token 路径。 -只有在交互式运行（TTY）时才会出现刷新提示；`--non-interactive` +刷新提示仅在交互模式（TTY）下出现；`--non-interactive` 会跳过刷新尝试。 -Doctor 还会检测过时且已移除的 Anthropic Claude CLI 状态。如果旧的 -`anthropic:claude-cli` 凭证字节仍存在于 `auth-profiles.json` 中， -doctor 会将其转换回 Anthropic 令牌/OAuth 配置文件，并重写过时的 -`claude-cli/...` 模型引用以及 `agents.defaults.cliBackends.claude-cli`。 -如果这些字节已不存在，doctor 会删除过时配置并输出恢复命令。 +Doctor 还会报告因以下原因而暂时不可用的认证配置文件： -Doctor 还会报告由于以下原因而暂时不可用的认证配置文件： +- 短期冷却（限流 / 超时 / 认证失败） +- 较长时间禁用（计费 / 额度失败） -- 短暂冷却（速率限制/超时/认证失败） -- 较长时间禁用（计费/额度失败） +### 6) Hooks 模型校验 -### 6）Hooks 模型验证 +如果设置了 `hooks.gmail.model`，Doctor 会根据目录和 allowlist 校验模型引用，并在其无法解析或不被允许时发出警告。 -如果设置了 `hooks.gmail.model`，doctor 会根据 -目录和 allowlist 验证该模型引用，并在无法解析或被禁止时发出警告。 +### 7) 沙箱镜像修复 -### 7）沙箱镜像修复 +启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。 -启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。 - -### 7b）内置插件运行时依赖 +### 7b) 内置插件运行时依赖 Doctor 会验证内置插件运行时依赖（例如 Discord 插件运行时包）是否存在于 OpenClaw 安装根目录中。 -如果有任何缺失，doctor 会报告这些包，并在 +如果有缺失，Doctor 会报告这些包，并在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下安装它们。 -### 8）Gateway 网关服务迁移和清理提示 +### 8) Gateway 网关服务迁移和清理提示 -Doctor 会检测旧版 Gateway 网关服务（`launchd`/`systemd`/`schtasks`）， +Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks）， 并提供移除它们以及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。 -它还可以扫描额外的类 Gateway 网关服务并输出清理提示。 -带有配置文件名称的 OpenClaw Gateway 网关服务被视为一等公民，不会 -被标记为“额外”。 +它还可以扫描额外的类似 Gateway 网关服务并打印清理提示。 +带 profile 名称的 OpenClaw Gateway 网关服务被视为一等公民，不会被标记为“额外”。 -### 8b）启动 Matrix 迁移 +### 8b) 启动时 Matrix 迁移 当 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时， -doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照， -然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版 -加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续进行。在只读模式下（`openclaw doctor` 不带 `--fix`）此检查会被完全跳过。 +Doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照， +然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两步都不是致命的；错误会被记录，启动会继续进行。在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查会被完全跳过。 -### 9）安全警告 +### 9) 安全警告 -当某个提供商对私信开放但没有 allowlist，或 -当某个策略以危险方式配置时，doctor 会发出警告。 +当某个提供商对私信开放但没有 allowlist，或某项策略配置方式存在危险时，Doctor 会发出警告。 -### 10）systemd linger（Linux） +### 10) systemd linger（Linux） -如果作为 `systemd` 用户服务运行，doctor 会确保启用 lingering，以便 -Gateway 网关在注销后仍保持运行。 +如果作为 systemd 用户服务运行，Doctor 会确保启用了 lingering，这样 Gateway 网关在注销后仍能保持运行。 -### 11）工作区状态（Skills、插件和旧版目录） +### 11) 工作区状态（Skills、插件和旧版目录） -Doctor 会输出默认智能体的工作区状态摘要： +Doctor 会打印默认智能体的工作区状态摘要： - **Skills 状态**：统计可用、缺少要求和被 allowlist 阻止的 Skills 数量。 -- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录 - 与当前工作区并存时发出警告。 -- **插件状态**：统计已加载/已禁用/出错的插件；列出任意 - 错误对应的插件 ID；报告 bundle 插件 capability。 -- **插件兼容性警告**：标记与 - 当前运行时存在兼容性问题的插件。 -- **插件诊断**：展示由 - 插件注册表在加载时发出的任何警告或错误。 +- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。 +- **插件状态**：统计已加载 / 已禁用 / 出错的插件；列出所有错误对应的插件 ID；报告内置插件能力。 +- **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。 +- **插件诊断信息**：展示插件注册表在加载时发出的任何警告或错误。 -### 11b）Bootstrap 文件大小 +### 11b) Bootstrap 文件大小 Doctor 会检查工作区 bootstrap 文件（例如 `AGENTS.md`、 -`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过已配置的 -字符预算。它会报告每个文件的原始字符数与注入后字符数、截断 -百分比、截断原因（`max/file` 或 `max/total`），以及总注入 -字符数占总预算的比例。当文件被截断或接近限制时，doctor 会输出调优 `agents.defaults.bootstrapMaxChars` -和 `agents.defaults.bootstrapTotalMaxChars` 的建议。 +`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过已配置的字符预算。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近上限时，Doctor 会打印关于调整 `agents.defaults.bootstrapMaxChars` +和 `agents.defaults.bootstrapTotalMaxChars` 的提示。 -### 11c）Shell 补全 +### 11c) Shell 补全 Doctor 会检查当前 shell （zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全： - 如果 shell 配置文件使用较慢的动态补全模式 - （`source <(openclaw completion ...)`），doctor 会将其升级为更快的 - 缓存文件变体。 -- 如果补全已在配置文件中配置，但缓存文件缺失， - doctor 会自动重新生成缓存。 -- 如果完全未配置补全， - doctor 会提示安装它 - （仅交互模式；使用 `--non-interactive` 时跳过）。 + （`source <(openclaw completion ...)`），Doctor 会将其升级为更快的缓存文件变体。 +- 如果配置文件中已配置补全，但缓存文件缺失， + Doctor 会自动重新生成缓存。 +- 如果根本未配置补全，Doctor 会提示安装它 + （仅交互模式；`--non-interactive` 时跳过）。 运行 `openclaw completion --write-state` 可手动重新生成缓存。 -### 12）Gateway 网关认证检查（本地令牌） +### 12) Gateway 网关认证检查（本地令牌） -Doctor 会检查本地 Gateway 网关令牌认证就绪情况。 +Doctor 会检查本地 Gateway 网关令牌认证的就绪状态。 -- 如果令牌模式需要令牌但不存在令牌来源，doctor 会提供生成令牌的选项。 -- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，doctor 会发出警告，并且不会用明文覆盖它。 -- `openclaw doctor --generate-gateway-token` 仅会在未配置令牌 SecretRef 时强制生成。 +- 如果令牌模式需要令牌且没有令牌来源，Doctor 会提供生成令牌的选项。 +- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，Doctor 会发出警告，并且不会用明文覆盖它。 +- `openclaw doctor --generate-gateway-token` 仅在未配置令牌 SecretRef 时强制生成。 -### 12b）只读且感知 SecretRef 的修复 +### 12b) 只读 SecretRef 感知修复 -某些修复流程需要检查已配置的凭证，同时又不能削弱运行时快速失败行为。 +某些修复流程需要检查已配置凭证，而不削弱运行时快速失败行为。 -- `openclaw doctor --fix` 现在使用与 status 系列命令相同的只读 SecretRef 摘要模型来执行有针对性的配置修复。 -- 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的机器人凭证。 -- 如果 Telegram 机器人令牌通过 SecretRef 配置，但在当前命令路径中不可用，doctor 会报告该凭证“已配置但不可用”，并跳过自动解析，而不是崩溃或误报令牌缺失。 +- `openclaw doctor --fix` 现在使用与 status 系列命令相同的只读 SecretRef 摘要模型，以执行定向配置修复。 +- 例如：Telegram `allowFrom` / `groupAllowFrom` 的 `@username` 修复会在可用时尝试使用已配置的 bot 凭证。 +- 如果 Telegram bot 令牌通过 SecretRef 配置，但在当前命令路径中不可用，Doctor 会报告该凭证为“已配置但不可用”，并跳过自动解析，而不是崩溃或错误地将令牌报告为缺失。 -### 13）Gateway 网关健康检查 + 重启 +### 13) Gateway 网关健康检查 + 重启 -Doctor 会运行健康检查，并在 Gateway 网关看起来 -不健康时提供重启选项。 +Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。 -### 13b）内存搜索就绪情况 +### 13b) Memory search 就绪状态 -Doctor 会检查为默认智能体配置的内存搜索嵌入提供商是否已就绪。 -行为取决于已配置的 backend 和 provider： +Doctor 会检查默认智能体配置的 memory search embedding 提供商是否就绪。其行为取决于配置的后端和提供商： -- **QMD backend**：探测 `qmd` 二进制文件是否可用且可启动。 - 如果不可用，会输出修复指导，包括 npm 包和手动二进制路径选项。 -- **显式本地 provider**：检查本地模型文件或可识别的 - 远程/可下载模型 URL 是否存在。如果缺失，会建议切换到远程提供商。 -- **显式远程 provider**（`openai`、`voyage` 等）：验证 API 密钥是否 - 存在于环境或认证存储中。如果缺失，会输出可操作的修复提示。 -- **自动 provider**：先检查本地模型可用性，然后按自动选择顺序尝试每个远程 - provider。 +- **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。 + 如果不可用，会打印修复指引，包括 npm 包和手动二进制路径选项。 +- **显式本地提供商**：检查本地模型文件或可识别的远程 / 可下载模型 URL。 + 如果缺失，会建议切换到远程提供商。 +- **显式远程提供商**（`openai`、`voyage` 等）：验证环境中或认证存储中是否存在 API 密钥。若缺失，会打印可执行的修复提示。 +- **自动提供商**：先检查本地模型可用性，再按自动选择顺序尝试各个远程提供商。 -当 Gateway 网关探测结果可用时（即检查时 Gateway 网关健康），doctor 会将其结果与 CLI 可见配置进行交叉比对，并注明 -任何差异。 +当 Gateway 网关探测结果可用时（检查时 Gateway 网关健康），Doctor 会将其结果与 CLI 可见配置交叉比对，并指出任何差异。 -使用 `openclaw memory status --deep` 可在运行时验证嵌入就绪情况。 +使用 `openclaw memory status --deep` 可在运行时验证 embedding 就绪状态。 -### 14）渠道状态警告 +### 14) 渠道状态警告 -如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告 -带有建议修复方式的警告。 +如果 Gateway 网关健康，Doctor 会运行渠道状态探测，并报告带有建议修复方案的警告。 -### 15）supervisor 配置审计 + 修复 +### 15) Supervisor 配置审计 + 修复 -Doctor 会检查已安装的 supervisor 配置（`launchd`/`systemd`/`schtasks`）是否存在 -缺失或过时的默认值（例如 systemd 的 network-online 依赖项和 -重启延迟）。发现不匹配时，它会建议更新，并可以 -将服务文件/任务重写为当前默认值。 +Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少或过时默认值（例如 systemd network-online 依赖和重启延迟）。发现不匹配时，它会建议更新，并可将服务文件 / 任务重写为当前默认值。 说明： -- `openclaw doctor` 会在重写 supervisor 配置前进行提示。 +- `openclaw doctor` 在重写 supervisor 配置前会提示。 - `openclaw doctor --yes` 会接受默认修复提示。 - `openclaw doctor --repair` 会不经提示应用推荐修复。 - `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。 -- 如果令牌认证需要令牌，并且 `gateway.auth.token` 由 SecretRef 管理，doctor 在服务安装/修复时会验证 SecretRef，但不会将解析后的明文令牌值持久化到 supervisor 服务环境元数据中。 -- 如果令牌认证需要令牌，而已配置的令牌 SecretRef 无法解析，doctor 会阻止安装/修复路径，并给出可操作的指导。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，doctor 会阻止安装/修复，直到明确设置模式。 -- 对于 Linux 用户级 systemd 单元，doctor 的令牌漂移检查现在会同时包含 `Environment=` 和 `EnvironmentFile=` 来源，以便比较服务认证元数据。 -- 你始终可以通过 `openclaw gateway install --force` 强制完整重写。 +- 如果令牌认证需要令牌且 `gateway.auth.token` 由 SecretRef 管理，Doctor 在服务安装 / 修复时会校验 SecretRef，但不会把解析出的明文令牌值持久化到 supervisor 服务环境元数据中。 +- 如果令牌认证需要令牌且配置的令牌 SecretRef 未解析，Doctor 会阻止安装 / 修复路径，并提供可执行的指引。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，Doctor 会阻止安装 / 修复，直到显式设置模式。 +- 对于 Linux user-systemd 单元，Doctor 的令牌漂移检查现在同时包括 `Environment=` 和 `EnvironmentFile=` 来源，以比较服务认证元数据。 +- 你始终可以通过 `openclaw gateway install --force` 强制执行完整重写。 -### 16）Gateway 网关运行时 + 端口诊断 +### 16) Gateway 网关运行时 + 端口诊断 -Doctor 会检查服务运行时（PID、上次退出状态），并在 -服务已安装但实际上未运行时发出警告。它还会检查 -Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。 +Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。 -### 17）Gateway 网关运行时最佳实践 +### 17) Gateway 网关运行时最佳实践 -当 Gateway 网关服务运行在 Bun 上，或运行在版本管理的 Node 路径 -（`nvm`、`fnm`、`volta`、`asdf` 等）上时，doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node， -而版本管理器路径可能会在升级后失效，因为服务不会 -加载你的 shell 初始化。Doctor 会在系统 Node 安装可用时提供迁移到它的选项（Homebrew/apt/choco）。 +当 Gateway 网关服务运行在 Bun 上，或使用版本管理的 Node 路径 +（`nvm`、`fnm`、`volta`、`asdf` 等）时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径可能会在升级后失效，因为服务不会加载你的 shell init。Doctor 会在系统 Node 安装可用时提供迁移到该安装的选项（Homebrew / apt / choco）。 -### 18）配置写入 + 向导元数据 +### 18) 配置写入 + 向导元数据 -Doctor 会持久化任何配置更改，并写入向导元数据以记录此次 -doctor 运行。 +Doctor 会持久化所有配置变更，并写入向导元数据以记录此次 Doctor 运行。 -### 19）工作区提示（备份 + 内存系统） +### 19) 工作区提示（备份 + memory system） -Doctor 会在缺失时建议设置工作区内存系统，并在工作区尚未纳入 git 管理时输出备份提示。 +当工作区缺少 memory system 时，Doctor 会建议添加；如果工作区尚未纳入 git，它还会打印备份提示。 -参见 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)，获取有关 -工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南。 +有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。 diff --git a/docs/zh-CN/gateway/index.md b/docs/zh-CN/gateway/index.md index 137f8f43e..e326846b8 100644 --- a/docs/zh-CN/gateway/index.md +++ b/docs/zh-CN/gateway/index.md @@ -4,29 +4,29 @@ read_when: summary: Gateway 网关服务、生命周期和运维的运行手册 title: Gateway 网关运行手册 x-i18n: - generated_at: "2026-04-05T08:23:51Z" + generated_at: "2026-04-06T15:28:29Z" model: gpt-5.4 provider: openai - source_hash: 0ec17674370de4e171779389c83580317308a4f07ebf335ad236a47238af18e1 + source_hash: fd2c21036e88612861ef2195b8ff7205aca31386bb11558614ade8d1a54fdebd source_path: gateway/index.md workflow: 15 --- # Gateway 网关运行手册 -使用本页处理 Gateway 网关服务的 day-1 启动和 day-2 运维。 +将此页面用于 Gateway 网关服务的首日启动和后续运维。 - - 按症状组织的诊断，包含精确的命令阶梯和日志特征。 + + 按症状优先的诊断，附带精确的命令步骤和日志特征。 - + 面向任务的设置指南 + 完整配置参考。 - - SecretRef 契约、运行时快照行为，以及迁移/重载操作。 + + SecretRef 合约、运行时快照行为，以及迁移/重载操作。 - + 精确的 `secrets apply` 目标/路径规则，以及仅 ref 的 auth-profile 行为。 @@ -64,34 +64,33 @@ openclaw logs --follow openclaw channels status --probe ``` -当 Gateway 网关可访问时，这会运行按账户划分的实时渠道探测和可选审计。 -如果 Gateway 网关不可访问，CLI 会回退到仅基于配置的渠道摘要，而不是实时探测输出。 +当 Gateway 网关可达时，这会运行按账户划分的实时渠道探测和可选审计。 +如果 Gateway 网关不可达，CLI 会回退为仅基于配置的渠道摘要，而不是实时探测输出。 -Gateway 网关配置重载会监视活动配置文件路径（从 profile/状态默认值解析，或在设置了 `OPENCLAW_CONFIG_PATH` 时使用它）。 -默认模式是 `gateway.reload.mode="hybrid"`。 -首次成功加载后，运行中的进程会提供活动的内存配置快照；成功重载会以原子方式替换该快照。 +Gateway 网关配置重载会监听活动配置文件路径（从 profile/state 默认值解析，或在设置了 `OPENCLAW_CONFIG_PATH` 时使用该值）。 +默认模式为 `gateway.reload.mode="hybrid"`。 +首次成功加载后，运行中的进程会提供当前内存中的活动配置快照；成功重载后会以原子方式替换该快照。 ## 运行时模型 - 一个始终在线的进程，用于路由、控制平面和渠道连接。 -- 单个复用端口用于： +- 一个复用的单端口，用于： - WebSocket 控制/RPC - - HTTP API、OpenAI 兼容接口（`/v1/models`、`/v1/embeddings`、`/v1/chat/completions`、`/v1/responses`、`/tools/invoke`） - - 控制 UI 和 hooks + - HTTP API、与 OpenAI 兼容（`/v1/models`、`/v1/embeddings`、`/v1/chat/completions`、`/v1/responses`、`/tools/invoke`） + - Control UI 和 hooks - 默认绑定模式：`loopback`。 -- 默认要求鉴权。共享密钥部署使用 +- 默认要求身份验证。共享密钥设置使用 `gateway.auth.token` / `gateway.auth.password`（或 - `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`），而非 loopback 的 - 反向代理部署可使用 `gateway.auth.mode: "trusted-proxy"`。 + `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`），非 loopback 的反向代理设置可以使用 `gateway.auth.mode: "trusted-proxy"`。 -## OpenAI 兼容端点 +## 与 OpenAI 兼容的端点 -OpenClaw 当前最有杠杆效应的兼容接口集是： +OpenClaw 当前最有价值的兼容性接口是： - `GET /v1/models` - `GET /v1/models/{id}` @@ -99,34 +98,34 @@ OpenClaw 当前最有杠杆效应的兼容接口集是： - `POST /v1/chat/completions` - `POST /v1/responses` -为什么这组接口重要： +为什么这组接口很重要： -- 大多数 Open WebUI、LobeChat 和 LibreChat 集成会首先探测 `/v1/models`。 -- 许多 RAG 和记忆流水线依赖 `/v1/embeddings`。 -- 原生智能体客户端越来越倾向于使用 `/v1/responses`。 +- 大多数 Open WebUI、LobeChat 和 LibreChat 集成都会先探测 `/v1/models`。 +- 许多 RAG 和记忆管道都依赖 `/v1/embeddings`。 +- 原生面向智能体的客户端越来越倾向于使用 `/v1/responses`。 规划说明： -- `/v1/models` 是智能体优先的：它返回 `openclaw`、`openclaw/default` 和 `openclaw/`。 -- `openclaw/default` 是稳定别名，始终映射到配置的默认智能体。 -- 当你想覆盖后端 provider/model 时，请使用 `x-openclaw-model`；否则所选智能体的常规模型和嵌入设置仍将保持控制。 +- `/v1/models` 以智能体优先：它会返回 `openclaw`、`openclaw/default` 和 `openclaw/`。 +- `openclaw/default` 是稳定别名，始终映射到已配置的默认智能体。 +- 当你想覆盖后端提供商/模型时，请使用 `x-openclaw-model`；否则，选定智能体的常规模型和嵌入设置仍然会保持控制权。 -所有这些都运行在主 Gateway 网关端口上，并使用与 Gateway 网关其余 HTTP API 相同的受信任操作员鉴权边界。 +所有这些都运行在主 Gateway 网关端口上，并与 Gateway 网关其余 HTTP API 共享同一个受信任操作员身份验证边界。 ### 端口和绑定优先级 -| Setting | 解析顺序 | -| ------------ | ----------------------------------------------------- | -| Gateway port | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` | -| Bind mode | CLI/覆盖值 → `gateway.bind` → `loopback` | +| 设置 | 解析顺序 | +| ------------ | ------------------------------------------------------------- | +| Gateway 网关端口 | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` | +| 绑定模式 | CLI/override → `gateway.bind` → `loopback` | ### 热重载模式 -| `gateway.reload.mode` | 行为 | -| --------------------- | -------------------------------------- | -| `off` | 不重载配置 | -| `hot` | 仅应用热安全更改 | -| `restart` | 遇到需要重启的更改时重启 | +| `gateway.reload.mode` | 行为 | +| --------------------- | ------------------------------------------ | +| `off` | 不进行配置重载 | +| `hot` | 仅应用热安全变更 | +| `restart` | 遇到需要重载的变更时重启 | | `hybrid`（默认） | 安全时热应用，需要时重启 | ## 操作员命令集 @@ -143,36 +142,36 @@ openclaw logs --follow openclaw doctor ``` -`gateway status --deep` 用于额外的服务发现（LaunchDaemons/systemd system -units/schtasks），而不是更深层的 RPC 健康探测。 +`gateway status --deep` 用于额外的服务发现（LaunchDaemons/systemd 系统 +单元/schtasks），而不是更深入的 RPC 健康探测。 ## 多个 Gateway 网关（同一主机） -大多数安装应每台机器运行一个 Gateway 网关。单个 Gateway 网关可以托管多个 +大多数安装应当每台机器运行一个 Gateway 网关。单个 Gateway 网关可以托管多个 智能体和渠道。 -只有当你明确需要隔离或救援机器人时，才需要多个 Gateway 网关。 +只有当你有意需要隔离或救援机器人时，才需要多个 Gateway 网关。 -实用检查： +有用的检查： ```bash openclaw gateway status --deep openclaw gateway probe ``` -预期行为： +预期结果： -- `gateway status --deep` 可能报告 `Other gateway-like services detected (best effort)` - 并在仍存在陈旧 launchd/systemd/schtasks 安装时打印清理提示。 -- 当多个目标都有响应时，`gateway probe` 可能警告 `multiple reachable gateways`。 -- 如果这是有意为之，请为每个 Gateway 网关隔离端口、配置/状态和工作区根目录。 +- `gateway status --deep` 可能会报告 `Other gateway-like services detected (best effort)` + 并在仍然存在陈旧的 launchd/systemd/schtasks 安装时打印清理提示。 +- 当有多个目标响应时，`gateway probe` 可能会警告 `multiple reachable gateways`。 +- 如果这是有意的，请为每个 Gateway 网关隔离端口、配置/state 和工作区根目录。 -详细设置：[/gateway/multiple-gateways](/gateway/multiple-gateways)。 +详细设置：[/gateway/multiple-gateways](/zh-CN/gateway/multiple-gateways)。 ## 远程访问 首选：Tailscale/VPN。 -回退：SSH 隧道。 +备选：SSH 隧道。 ```bash ssh -N -L 18789:127.0.0.1:18789 user@host @@ -181,16 +180,15 @@ ssh -N -L 18789:127.0.0.1:18789 user@host 然后在本地将客户端连接到 `ws://127.0.0.1:18789`。 -SSH 隧道不会绕过 Gateway 网关鉴权。对于共享密钥鉴权，客户端即使通过隧道 -仍然必须发送 `token`/`password`。对于带身份模式， -请求仍然必须满足该鉴权路径。 +SSH 隧道不会绕过 Gateway 网关身份验证。对于共享密钥身份验证，即使通过隧道，客户端仍然 +必须发送 `token`/`password`。对于带身份模式，请求仍然必须满足该身份验证路径。 -参见：[Remote Gateway](/gateway/remote)、[Authentication](/gateway/authentication)、[Tailscale](/gateway/tailscale)。 +参见：[Remote Gateway](/zh-CN/gateway/remote)、[Authentication](/zh-CN/gateway/authentication)、[Tailscale](/zh-CN/gateway/tailscale)。 -## 监管和服务生命周期 +## 监督与服务生命周期 -对于接近生产环境的可靠性，请使用受监管运行。 +对于接近生产环境的可靠性，请使用受监督的运行方式。 @@ -202,11 +200,11 @@ openclaw gateway restart openclaw gateway stop ``` -LaunchAgent 标签为 `ai.openclaw.gateway`（默认）或 `ai.openclaw.`（命名 profile）。`openclaw doctor` 会审计并修复服务配置漂移。 +LaunchAgent 标签是 `ai.openclaw.gateway`（默认）或 `ai.openclaw.`（命名 profile）。`openclaw doctor` 会审计并修复服务配置漂移。 - + ```bash openclaw gateway install @@ -214,13 +212,13 @@ systemctl --user enable --now openclaw-gateway[-].service openclaw gateway status ``` -如需在注销后持续运行，请启用 lingering： +要在注销后继续持久运行，请启用 lingering： ```bash sudo loginctl enable-linger ``` -当你需要自定义安装路径时，可使用手动 user unit 示例： +当你需要自定义安装路径时，可使用以下手动用户单元示例： ```ini [Unit] @@ -253,30 +251,30 @@ openclaw gateway stop ``` 原生 Windows 托管启动使用名为 `OpenClaw Gateway` -的 Scheduled Task（命名 profile 时为 `OpenClaw Gateway ()`）。如果创建 Scheduled Task -被拒绝，OpenClaw 会回退到按用户的 Startup 文件夹启动器，该启动器指向状态目录中的 `gateway.cmd`。 +的计划任务（命名 profile 则为 `OpenClaw Gateway ()`）。如果计划任务 +创建被拒绝，OpenClaw 会回退到每用户 Startup 文件夹启动器，该启动器指向 state 目录中的 `gateway.cmd`。 -对于多用户/始终在线主机，请使用 system unit。 +对多用户/始终在线的主机，请使用系统单元。 ```bash sudo systemctl daemon-reload sudo systemctl enable --now openclaw-gateway[-].service ``` -使用与 user unit 相同的服务主体，但将其安装到 -`/etc/systemd/system/openclaw-gateway[-].service` 下，并在 -你的 `openclaw` 二进制文件位于其他位置时调整 `ExecStart=`。 +使用与用户单元相同的服务主体，但将其安装到 +`/etc/systemd/system/openclaw-gateway[-].service` 下，并在你的 `openclaw` 二进制位于其他位置时调整 +`ExecStart=`。 ## 一台主机上的多个 Gateway 网关 -大多数部署应只运行**一个** Gateway 网关。 +大多数设置应该只运行**一个** Gateway 网关。 只有在需要严格隔离/冗余时才使用多个（例如救援 profile）。 每个实例的检查清单： @@ -293,7 +291,7 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a opencla OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002 ``` -参见：[多个 Gateway 网关](/gateway/multiple-gateways)。 +参见：[Multiple gateways](/zh-CN/gateway/multiple-gateways)。 ### 开发 profile 快速路径 @@ -303,25 +301,25 @@ openclaw --dev gateway --allow-unconfigured openclaw --dev status ``` -默认值包括隔离的状态/配置以及基础 Gateway 网关端口 `19001`。 +默认值包括隔离的 state/config 和基础 Gateway 网关端口 `19001`。 ## 协议快速参考（操作员视角） -- 客户端第一帧必须是 `connect`。 +- 第一个客户端帧必须是 `connect`。 - Gateway 网关返回 `hello-ok` 快照（`presence`、`health`、`stateVersion`、`uptimeMs`、limits/policy）。 - `hello-ok.features.methods` / `events` 是保守的发现列表，而不是 - 所有可调用辅助路由的自动生成清单。 + 对每个可调用辅助路由的自动生成完整导出。 - 请求：`req(method, params)` → `res(ok/payload|error)`。 - 常见事件包括 `connect.challenge`、`agent`、`chat`、 `session.message`、`session.tool`、`sessions.changed`、`presence`、`tick`、 - `health`、`heartbeat`、配对/批准生命周期事件，以及 `shutdown`。 + `health`、`heartbeat`、配对/审批生命周期事件，以及 `shutdown`。 -智能体运行分两阶段： +智能体运行分两个阶段： 1. 立即接受确认（`status:"accepted"`） -2. 最终完成响应（`status:"ok"|"error"`），期间会穿插流式 `agent` 事件。 +2. 最终完成响应（`status:"ok"|"error"`），中间会流式发送 `agent` 事件。 -完整协议文档见：[Gateway Protocol](/gateway/protocol)。 +完整协议文档参见：[Gateway Protocol](/zh-CN/gateway/protocol)。 ## 运维检查 @@ -330,7 +328,7 @@ openclaw --dev status - 打开 WS 并发送 `connect`。 - 预期收到带快照的 `hello-ok` 响应。 -### 就绪状态 +### 就绪性 ```bash openclaw gateway status @@ -340,32 +338,32 @@ openclaw health ### 间隙恢复 -事件不会重放。若出现序列间隙，请先刷新状态（`health`、`system-presence`），然后再继续。 +事件不会重放。遇到序列缺口时，请先刷新状态（`health`、`system-presence`）再继续。 ## 常见故障特征 -| Signature | Likely issue | +| 特征 | 可能问题 | | -------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `refusing to bind gateway ... without auth` | 非 loopback 绑定但没有有效的 Gateway 网关鉴权路径 | -| `another gateway instance is already listening` / `EADDRINUSE` | 端口冲突 | -| `Gateway start blocked: set gateway.mode=local` | 配置被设为远程模式，或受损配置中缺少本地模式标记 | -| `unauthorized` during connect | 客户端与 Gateway 网关之间的鉴权不匹配 | +| `refusing to bind gateway ... without auth` | 非 loopback 绑定且没有有效的 Gateway 网关身份验证路径 | +| `another gateway instance is already listening` / `EADDRINUSE` | 端口冲突 | +| `Gateway start blocked: set gateway.mode=local` | 配置被设为远程模式，或损坏配置中缺少本地模式标记 | +| `unauthorized` during connect | 客户端与 Gateway 网关之间的身份验证不匹配 | -如需完整诊断阶梯，请使用 [Gateway 故障排除](/gateway/troubleshooting)。 +如需完整诊断步骤，请使用 [Gateway 故障排除](/zh-CN/gateway/troubleshooting)。 ## 安全保证 -- 当 Gateway 网关不可用时，Gateway protocol 客户端会快速失败（不会隐式回退到直连渠道）。 -- 非法/非 connect 的首帧会被拒绝并关闭连接。 -- 优雅关闭会在 socket 关闭前发出 `shutdown` 事件。 +- 当 Gateway 网关不可用时，Gateway 网关协议客户端会快速失败（不会隐式回退到直接渠道）。 +- 无效的首帧或非 `connect` 首帧会被拒绝并关闭连接。 +- 优雅关闭会在 socket 关闭前发送 `shutdown` 事件。 --- 相关内容： -- [故障排除](/gateway/troubleshooting) -- [后台进程](/gateway/background-process) -- [配置](/gateway/configuration) -- [健康状态](/gateway/health) -- [Doctor](/gateway/doctor) -- [鉴权](/gateway/authentication) +- [故障排除](/zh-CN/gateway/troubleshooting) +- [后台进程](/zh-CN/gateway/background-process) +- [配置](/zh-CN/gateway/configuration) +- [健康状态](/zh-CN/gateway/health) +- [Doctor](/zh-CN/gateway/doctor) +- [身份验证](/zh-CN/gateway/authentication) diff --git a/docs/zh-CN/gateway/troubleshooting.md b/docs/zh-CN/gateway/troubleshooting.md index 9be37cd86..5621af05d 100644 --- a/docs/zh-CN/gateway/troubleshooting.md +++ b/docs/zh-CN/gateway/troubleshooting.md @@ -1,22 +1,22 @@ --- read_when: - - 故障排除中心将你引导到这里进行更深入的诊断 - - 你需要带有精确命令的稳定、按症状分类的操作手册章节 -summary: 针对 Gateway 网关、渠道、自动化、节点和浏览器的深入故障排除操作手册 + - 故障排除中心将你引导到这里以进行更深入的诊断 + - 你需要按症状组织且带有精确命令的稳定操作手册章节 +summary: 针对 Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除操作手册 title: 故障排除 x-i18n: - generated_at: "2026-04-05T08:25:42Z" + generated_at: "2026-04-06T15:28:55Z" model: gpt-5.4 provider: openai - source_hash: 028226726e6adc45ca61d41510a953c4e21a3e85f3082af9e8085745c6ac3ec1 + source_hash: e0202e8858310a0bfc1c994cd37b01c3b2d6c73c8a74740094e92dc3c4c36729 source_path: gateway/troubleshooting.md workflow: 15 --- # Gateway 网关故障排除 -本页面是深入操作手册。 -如果你想先走快速分诊流程，请从 [/help/troubleshooting](/help/troubleshooting) 开始。 +本页是深度操作手册。 +如果你想先使用快速分诊流程，请先从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 ## 命令阶梯 @@ -34,11 +34,11 @@ openclaw channels status --probe - `openclaw gateway status` 显示 `Runtime: running` 和 `RPC probe: ok`。 - `openclaw doctor` 报告没有阻塞性的配置/服务问题。 -- `openclaw channels status --probe` 显示实时的逐账号传输状态，并且在支持的情况下显示探测/审计结果，例如 `works` 或 `audit ok`。 +- `openclaw channels status --probe` 显示每个账号的实时传输状态，并在支持的情况下显示探测/审计结果，例如 `works` 或 `audit ok`。 -## Anthropic 429 需要额外用量以支持长上下文 +## Anthropic 429：长上下文需要额外用量权限 -当日志/错误中包含以下内容时使用本节： +当日志/错误中包含以下内容时，请使用本节： `HTTP 429: rate_limit_error: Extra usage is required for long context requests`。 ```bash @@ -47,27 +47,27 @@ openclaw models status openclaw config get agents.defaults.models ``` -检查： +检查以下内容： -- 选中的 Anthropic Opus/Sonnet 模型启用了 `params.context1m: true`。 -- 当前的 Anthropic 凭证不具备长上下文用量资格。 -- 请求仅在需要 1M beta 路径的长会话/模型运行中失败。 +- 选定的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。 +- 当前的 Anthropic 凭证没有长上下文用量资格。 +- 请求只会在需要走 1M beta 路径的长会话/模型运行中失败。 修复选项： 1. 为该模型禁用 `context1m`，回退到普通上下文窗口。 -2. 使用带计费的 Anthropic API key，或在 Anthropic OAuth/订阅账号上启用 Anthropic Extra Usage。 +2. 使用有资格发起长上下文请求的 Anthropic 凭证，或切换为 Anthropic API key。 3. 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时，运行仍可继续。 相关内容： -- [/providers/anthropic](/providers/anthropic) -- [/reference/token-use](/reference/token-use) -- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) +- [/providers/anthropic](/zh-CN/providers/anthropic) +- [/reference/token-use](/zh-CN/reference/token-use) +- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/zh-CN/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) ## 没有回复 -如果渠道已连接但没有任何响应，请在重新连接任何内容之前先检查路由和策略。 +如果渠道已连通但没有任何响应，在重新连接任何内容之前，请先检查路由和策略。 ```bash openclaw status @@ -77,27 +77,27 @@ openclaw config get channels openclaw logs --follow ``` -检查： +检查以下内容： -- 私信发送者是否仍在等待配对批准。 +- 私信发送者的配对是否仍在等待中。 - 群组提及门控（`requireMention`、`mentionPatterns`）。 - 渠道/群组允许列表是否不匹配。 常见特征： -- `drop guild message (mention required` → 群组消息被忽略，直到出现提及。 +- `drop guild message (mention required` → 群组消息会被忽略，直到出现提及。 - `pairing request` → 发送者需要批准。 - `blocked` / `allowlist` → 发送者/渠道被策略过滤。 相关内容： -- [/channels/troubleshooting](/channels/troubleshooting) -- [/channels/pairing](/channels/pairing) -- [/channels/groups](/channels/groups) +- [/channels/troubleshooting](/zh-CN/channels/troubleshooting) +- [/channels/pairing](/zh-CN/channels/pairing) +- [/channels/groups](/zh-CN/channels/groups) -## Dashboard Control UI 连接问题 +## 仪表板 Control UI 连接问题 -当 dashboard/Control UI 无法连接时，请验证 URL、认证模式和安全上下文假设。 +当仪表板/Control UI 无法连接时，请验证 URL、认证模式和安全上下文假设。 ```bash openclaw gateway status @@ -107,45 +107,36 @@ openclaw doctor openclaw gateway status --json ``` -检查： +检查以下内容： -- 正确的探测 URL 和 dashboard URL。 +- 正确的探测 URL 和仪表板 URL。 - 客户端与 Gateway 网关之间的认证模式/token 是否不匹配。 -- 是否在需要设备身份的场景下使用了 HTTP。 +- 在需要设备身份时是否仍在使用 HTTP。 常见特征： - `device identity required` → 非安全上下文或缺少设备认证。 -- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中 - （或者你正从非 loopback 浏览器 origin 连接，但未显式 - 添加允许列表）。 -- `device nonce required` / `device nonce mismatch` → 客户端未完成 - 基于 challenge 的设备认证流程（`connect.challenge` + `device.nonce`）。 -- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的 - 负载（或使用了过期时间戳）。 -- 带有 `canRetryWithDeviceToken=true` 的 `AUTH_TOKEN_MISMATCH` → 客户端可以使用缓存设备 token 进行一次可信重试。 -- 该缓存 token 重试会复用与已配对 - 设备 token 一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留其 - 请求的作用域集合。 -- 除该重试路径外，连接认证优先级依次为：显式共享 - token/password、显式 `deviceToken`、存储的设备 token、 - 引导 token。 -- 在异步 Tailscale Serve Control UI 路径上，同一 - `{scope, ip}` 的失败尝试会在限流器记录失败之前串行化。因此，同一客户端的两个错误并发重试，第二次尝试可能显示 `retry later`，而不是两个普通的不匹配错误。 -- 来自浏览器 origin loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自同一规范化 `Origin` 的重复失败会被暂时锁定；另一个 localhost origin 会使用单独的桶。 -- 在该重试之后重复出现 `unauthorized` → 共享 token/设备 token 漂移；请刷新 token 配置，并在需要时重新批准/轮换设备 token。 -- `gateway connect failed:` → host/port/url 目标错误。 +- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 的浏览器 origin 连接，但没有显式允许列表）。 +- `device nonce required` / `device nonce mismatch` → 客户端没有完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。 +- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的负载（或使用了过期时间戳）。 +- `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备 token 执行一次受信任重试。 +- 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存 scope 集合。显式 `deviceToken` / 显式 `scopes` 调用方则会保留自己请求的 scope 集合。 +- 除该重试路径外，连接认证优先级依次为：显式共享 token/password、然后显式 `deviceToken`、然后存储的设备 token、最后是引导 token。 +- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前串行化。因此，同一客户端的两个错误并发重试，第二次可能会显示 `retry later`，而不是两个普通的不匹配。 +- 来自浏览器 origin loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自同一归一化 `Origin` 的重复失败会被临时锁定；另一个 localhost origin 会使用独立的桶。 +- 在那次重试后仍反复出现 `unauthorized` → 共享 token/设备 token 已漂移；如有需要，请刷新 token 配置并重新批准/轮换设备 token。 +- `gateway connect failed:` → 主机/端口/url 目标错误。 ### 认证详情代码速查表 -使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作： +使用失败的 `connect` 响应中的 `error.details.code` 来选择下一步操作： -| Detail code | 含义 | 建议操作 | -| ---------------------------- | ---- | -------- | -| `AUTH_TOKEN_MISSING` | 客户端未发送所需的共享 token。 | 在客户端中粘贴/设置 token 后重试。对于 dashboard 路径：运行 `openclaw config get gateway.auth.token`，然后粘贴到 Control UI 设置中。 | -| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存 token 重试会复用已存储的批准作用域；显式 `deviceToken` / `scopes` 调用方保留所请求的作用域。如果仍失败，请运行 [令牌漂移恢复清单](/cli/devices#token-drift-recovery-checklist)。 | -| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备 token 已过期或被撤销。 | 使用 [devices CLI](/cli/devices) 轮换/重新批准设备 token，然后重新连接。 | -| `PAIRING_REQUIRED` | 设备身份已知，但尚未针对该角色获得批准。 | 批准待处理请求：`openclaw devices list` 然后执行 `openclaw devices approve `。 | +| 详情代码 | 含义 | 建议操作 | +| ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AUTH_TOKEN_MISSING` | 客户端没有发送所需的共享 token。 | 在客户端中粘贴/设置 token 后重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 | +| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次受信任重试。缓存 token 重试会复用已存储且批准的 scopes；显式 `deviceToken` / `scopes` 调用方保留请求的 scopes。如果仍失败，请运行 [token 漂移恢复检查清单](/cli/devices#token-drift-recovery-checklist)。 | +| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的按设备 token 已过期或被撤销。 | 使用 [devices CLI](/cli/devices) 轮换/重新批准设备 token，然后重新连接。 | +| `PAIRING_REQUIRED` | 设备身份已知，但尚未为此角色批准。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve `。 | 设备认证 v2 迁移检查： @@ -155,30 +146,28 @@ openclaw doctor openclaw gateway status ``` -如果日志显示 nonce/signature 错误，请更新正在连接的客户端并验证它： +如果日志显示 nonce/signature 错误，请更新正在连接的客户端，并确认它： 1. 等待 `connect.challenge` -2. 对绑定 challenge 的负载进行签名 +2. 对绑定该 challenge 的负载进行签名 3. 使用相同的 challenge nonce 发送 `connect.params.device.nonce` 如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝： -- 已配对设备 token 会话只能管理**自己的**设备，除非 - 调用方还具有 `operator.admin` -- `openclaw devices rotate --scope ...` 只能请求 - 调用方当前会话已拥有的 operator 作用域 +- 已配对设备 token 会话只能管理**它们自己的**设备，除非调用方还拥有 `operator.admin` +- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的 operator scopes 相关内容： - [/web/control-ui](/web/control-ui) -- [/gateway/configuration](/gateway/configuration)（gateway 认证模式） -- [/gateway/trusted-proxy-auth](/gateway/trusted-proxy-auth) -- [/gateway/remote](/gateway/remote) +- [/gateway/configuration](/zh-CN/gateway/configuration)（Gateway 网关认证模式） +- [/gateway/trusted-proxy-auth](/zh-CN/gateway/trusted-proxy-auth) +- [/gateway/remote](/zh-CN/gateway/remote) - [/cli/devices](/cli/devices) ## Gateway 网关服务未运行 -当服务已安装但进程无法持续运行时，请使用本节。 +当服务已安装但进程无法保持运行时，请使用本节。 ```bash openclaw gateway status @@ -188,30 +177,30 @@ openclaw doctor openclaw gateway status --deep # also scan system-level services ``` -检查： +检查以下内容： -- 带退出提示的 `Runtime: stopped`。 -- 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。 +- `Runtime: stopped` 以及退出提示。 +- 服务配置不匹配（`Config (cli)` vs `Config (service)`）。 - 端口/监听器冲突。 -- 使用 `--deep` 时，是否存在额外的 launchd/systemd/schtasks 安装。 +- 使用 `--deep` 时，是否存在多余的 launchd/systemd/schtasks 安装。 - `Other gateway-like services detected (best effort)` 清理提示。 常见特征： -- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 gateway 模式，或配置文件被覆盖导致丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。 -- `refusing to bind gateway ... without auth` → 非 loopback 绑定，且没有有效的 gateway 认证路径（token/password，或在配置正确时使用 trusted-proxy）。 +- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被覆盖导致丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。 +- `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 Gateway 网关认证路径（token/password，或在已配置时使用 trusted-proxy）。 - `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。 -- `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数部署应保持每台机器一个 gateway；如果你确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host)。 +- `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数配置应保持每台机器一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。 相关内容： -- [/gateway/background-process](/gateway/background-process) -- [/gateway/configuration](/gateway/configuration) -- [/gateway/doctor](/gateway/doctor) +- [/gateway/background-process](/zh-CN/gateway/background-process) +- [/gateway/configuration](/zh-CN/gateway/configuration) +- [/gateway/doctor](/zh-CN/gateway/doctor) ## Gateway 网关探测警告 -当 `openclaw gateway probe` 能连接到某个目标，但仍打印警告块时，请使用本节。 +当 `openclaw gateway probe` 确实探测到某个目标，但仍输出警告块时，请使用本节。 ```bash openclaw gateway probe @@ -219,27 +208,27 @@ openclaw gateway probe --json openclaw gateway probe --ssh user@gateway-host ``` -检查： +检查以下内容： - JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。 -- 该警告是否与 SSH 回退、多个 Gateway 网关、缺失作用域或未解析认证引用有关。 +- 警告是否与 SSH 回退、多个 Gateway 网关、缺少 scopes 或未解析的 auth 引用有关。 常见特征： -- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了直接的已配置/loopback 目标。 -- `multiple reachable gateways detected` → 有多个目标响应。通常意味着有意的多 Gateway 网关部署，或存在过期/重复监听器。 -- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份或使用带有 `operator.read` 的凭证。 -- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在当前命令路径中，该目标失败时认证材料不可用。 +- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了直接配置的/loopback 目标。 +- `multiple reachable gateways detected` → 有多个目标做出了响应。这通常意味着你有意配置了多个 Gateway 网关，或者存在过期/重复监听器。 +- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受 scope 限制；请配对设备身份或使用带有 `operator.read` 的凭证。 +- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在该命令路径中，失败目标的认证材料不可用。 相关内容： - [/cli/gateway](/cli/gateway) -- [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host) -- [/gateway/remote](/gateway/remote) +- [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host) +- [/gateway/remote](/zh-CN/gateway/remote) -## 渠道已连接但消息不流动 +## 渠道已连接但消息不流转 -如果渠道状态显示已连接，但消息流已停止，请重点检查策略、权限和渠道特定投递规则。 +如果渠道状态显示已连接，但消息流转中断，请重点检查策略、权限和渠道特定的投递规则。 ```bash openclaw channels status --probe @@ -249,28 +238,28 @@ openclaw logs --follow openclaw config get channels ``` -检查： +检查以下内容： - 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。 - 群组允许列表和提及要求。 -- 缺失的渠道 API 权限/作用域。 +- 是否缺少渠道 API 权限/scopes。 常见特征： - `mention required` → 消息因群组提及策略而被忽略。 -- `pairing` / 待批准痕迹 → 发送者尚未获批。 +- `pairing` / 待批准跟踪 → 发送者尚未获批。 - `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → 渠道认证/权限问题。 相关内容： -- [/channels/troubleshooting](/channels/troubleshooting) -- [/channels/whatsapp](/channels/whatsapp) -- [/channels/telegram](/channels/telegram) -- [/channels/discord](/channels/discord) +- [/channels/troubleshooting](/zh-CN/channels/troubleshooting) +- [/channels/whatsapp](/zh-CN/channels/whatsapp) +- [/channels/telegram](/zh-CN/channels/telegram) +- [/channels/discord](/zh-CN/channels/discord) -## Cron 和 heartbeat 投递 +## Cron 和心跳投递 -如果 cron 或 heartbeat 未运行或未投递，请先验证调度器状态，然后检查投递目标。 +如果 cron 或心跳没有运行，或者运行了但未投递，请先验证调度器状态，再检查投递目标。 ```bash openclaw cron status @@ -280,31 +269,31 @@ openclaw system heartbeat last openclaw logs --follow ``` -检查： +检查以下内容： -- 是否启用了 cron，且存在下次唤醒时间。 -- 作业运行历史状态（`ok`、`skipped`、`error`）。 -- heartbeat 跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 +- Cron 已启用，并且存在下一次唤醒时间。 +- 任务运行历史状态（`ok`、`skipped`、`error`）。 +- 心跳跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 常见特征： - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。 - `cron: timer tick failed` → 调度器 tick 失败；请检查文件/日志/运行时错误。 -- 带有 `reason=quiet-hours` 的 `heartbeat skipped` → 当前不在活跃时间窗口内。 -- 带有 `reason=empty-heartbeat-file` 的 `heartbeat skipped` → `HEARTBEAT.md` 存在，但仅包含空行 / Markdown 标题，因此 OpenClaw 会跳过模型调用。 -- 带有 `reason=no-tasks-due` 的 `heartbeat skipped` → `HEARTBEAT.md` 包含 `tasks:` 块，但在本次 tick 中没有任何任务到期。 -- `heartbeat: unknown accountId` → heartbeat 投递目标使用了无效的账号 id。 -- 带有 `reason=dm-blocked` 的 `heartbeat skipped` → heartbeat 目标被解析为私信式目标，而 `agents.defaults.heartbeat.directPolicy`（或每智能体覆盖）设置为 `block`。 +- `heartbeat skipped` 且 `reason=quiet-hours` → 当前不在活跃时间窗口内。 +- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / Markdown 标题，因此 OpenClaw 会跳过模型调用。 +- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但这一轮 tick 中没有任务到期。 +- `heartbeat: unknown accountId` → 心跳投递目标的 account id 无效。 +- `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标被解析为私信式目标，而 `agents.defaults.heartbeat.directPolicy`（或按智能体覆盖项）设置为 `block`。 相关内容： -- [/automation/cron-jobs#troubleshooting](/automation/cron-jobs#troubleshooting) -- [/automation/cron-jobs](/automation/cron-jobs) -- [/gateway/heartbeat](/gateway/heartbeat) +- [/automation/cron-jobs#troubleshooting](/zh-CN/automation/cron-jobs#troubleshooting) +- [/automation/cron-jobs](/zh-CN/automation/cron-jobs) +- [/gateway/heartbeat](/zh-CN/gateway/heartbeat) -## 节点已配对但工具失败 +## 已配对节点的工具失败 -如果节点已配对但工具调用失败，请分别排查前台状态、权限和审批状态。 +如果节点已配对，但工具仍然失败，请分别检查前台状态、权限和批准状态。 ```bash openclaw nodes status @@ -314,28 +303,28 @@ openclaw logs --follow openclaw status ``` -检查： +检查以下内容： -- 节点是否在线并具有预期能力。 -- 相机/麦克风/定位/屏幕的操作系统权限是否已授予。 -- Exec 审批和允许列表状态。 +- 节点在线，并具有预期能力。 +- 相机/麦克风/定位/屏幕的 OS 权限已授予。 +- exec 批准和允许列表状态。 常见特征： -- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须处于前台。 -- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。 -- `SYSTEM_RUN_DENIED: approval required` → exec 审批待处理。 +- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须位于前台。 +- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少 OS 权限。 +- `SYSTEM_RUN_DENIED: approval required` → exec 批准仍在等待。 - `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表阻止。 相关内容： -- [/nodes/troubleshooting](/nodes/troubleshooting) -- [/nodes/index](/nodes/index) -- [/tools/exec-approvals](/tools/exec-approvals) +- [/nodes/troubleshooting](/zh-CN/nodes/troubleshooting) +- [/nodes/index](/zh-CN/nodes/index) +- [/tools/exec-approvals](/zh-CN/tools/exec-approvals) ## 浏览器工具失败 -当浏览器工具操作失败，但 gateway 本身是健康的时，请使用本节。 +当浏览器工具操作失败，但 Gateway 网关本身是健康的，请使用本节。 ```bash openclaw browser status @@ -345,43 +334,43 @@ openclaw logs --follow openclaw doctor ``` -检查： +检查以下内容： - 是否设置了 `plugins.allow` 且其中包含 `browser`。 - 浏览器可执行文件路径是否有效。 -- CDP 配置档案是否可达。 -- 对于 `existing-session` / `user` 配置档案，本地 Chrome 是否可用。 +- CDP profile 是否可达。 +- `existing-session` / `user` profiles 是否有本地 Chrome 可用。 常见特征： -- `unknown command "browser"` 或 `unknown command 'browser'` → 内置 browser 插件被 `plugins.allow` 排除了。 -- 在 `browser.enabled=true` 的情况下 browser 工具缺失 / 不可用 → `plugins.allow` 排除了 `browser`，因此插件从未加载。 +- `unknown command "browser"` 或 `unknown command 'browser'` → 内置 browser 插件被 `plugins.allow` 排除。 +- 在 `browser.enabled=true` 时 browser 工具缺失 / 不可用 → `plugins.allow` 排除了 `browser`，因此插件从未加载。 - `Failed to start Chrome CDP on port` → 浏览器进程启动失败。 - `browser.executablePath not found` → 配置的路径无效。 - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议，例如 `file:` 或 `ftp:`。 -- `browser.cdpUrl has invalid port` → 配置的 CDP URL 具有错误或超出范围的端口。 -- `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置档案没有打开的本地 Chrome 标签页。 -- `Remote CDP for profile "" is not reachable` → 从 gateway 主机无法访问配置的远程 CDP 端点。 -- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only 配置档案没有可达目标，或者 HTTP 端点虽有响应，但 CDP WebSocket 仍无法打开。 -- `Playwright is not available in this gateway build; '' is unsupported.` → 当前 gateway 安装缺少完整的 Playwright 包；ARIA 快照和基础页面截图仍可工作，但导航、AI 快照、基于 CSS 选择器的元素截图和 PDF 导出仍不可用。 -- `fullPage is not supported for element screenshots` → 截图请求同时混用了 `--full-page` 与 `--ref` 或 `--element`。 -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 截图调用必须使用页面捕获或快照 `--ref`，不能使用 CSS `--element`。 -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传 hook 需要使用快照引用，而不是 CSS 选择器。 -- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置档案上每次调用只发送一个上传文件。 -- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置档案上的对话框 hook 不支持超时覆盖。 -- `response body is not supported for existing-session profiles yet.` → `responsebody` 仍需要托管浏览器或原始 CDP 配置档案。 -- attach-only 或远程 CDP 配置档案上的过期 viewport / dark-mode / locale / offline 覆盖 → 运行 `openclaw browser stop --browser-profile ` 以关闭当前活动控制会话，并释放 Playwright/CDP 仿真状态，而无需重启整个 gateway。 +- `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。 +- `No Chrome tabs found for profile="user"` → Chrome MCP attach profile 没有打开的本地 Chrome 标签页。 +- `Remote CDP for profile "" is not reachable` → 从 Gateway 网关主机无法访问配置的远程 CDP 端点。 +- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile 没有可达目标，或者 HTTP 端点虽然响应了，但 CDP WebSocket 仍无法打开。 +- `Playwright is not available in this gateway build; '' is unsupported.` → 当前 Gateway 网关安装缺少完整的 Playwright 包；ARIA 快照和基础页面截图仍可能可用，但导航、AI 快照、基于 CSS 选择器的元素截图和 PDF 导出仍不可用。 +- `fullPage is not supported for element screenshots` → 截图请求同时使用了 `--full-page` 和 `--ref` 或 `--element`。 +- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 截图调用必须使用页面捕获或快照 `--ref`，而不是 CSS `--element`。 +- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要使用快照引用，而不是 CSS 选择器。 +- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP profiles 上，每次调用只能发送一个上传文件。 +- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP profiles 上的对话框钩子不支持超时覆盖。 +- `response body is not supported for existing-session profiles yet.` → `responsebody` 仍然需要托管浏览器或原始 CDP profile。 +- attach-only 或远程 CDP profiles 上出现陈旧的视口 / 深色模式 / 语言环境 / 离线覆盖 → 运行 `openclaw browser stop --browser-profile ` 关闭活动控制会话，并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。 相关内容： -- [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting) -- [/tools/browser](/tools/browser) +- [/tools/browser-linux-troubleshooting](/zh-CN/tools/browser-linux-troubleshooting) +- [/tools/browser](/zh-CN/tools/browser) -## 如果你升级后突然出现故障 +## 如果你升级后突然出现问题 -大多数升级后的故障都是配置漂移，或之前宽松、现在开始强制执行的默认值所致。 +大多数升级后的故障都源于配置漂移，或是现在开始强制执行更严格的默认值。 -### 1) 认证和 URL 覆盖行为已改变 +### 1) 认证和 URL 覆盖行为发生了变化 ```bash openclaw gateway status @@ -390,17 +379,17 @@ openclaw config get gateway.remote.url openclaw config get gateway.auth.mode ``` -检查要点： +检查什么： -- 如果 `gateway.mode=remote`，CLI 调用可能指向远程目标，而你的本地服务其实是正常的。 -- 显式 `--url` 调用不会回退到已存储凭证。 +- 如果 `gateway.mode=remote`，CLI 调用可能会指向远程，而你的本地服务本身其实没问题。 +- 显式 `--url` 调用不会回退到已存储的凭证。 常见特征： - `gateway connect failed:` → URL 目标错误。 - `unauthorized` → 端点可达，但认证错误。 -### 2) 绑定和认证护栏更严格了 +### 2) 绑定和认证防护更严格了 ```bash openclaw config get gateway.bind @@ -410,17 +399,17 @@ openclaw gateway status openclaw logs --follow ``` -检查要点： +检查什么： -- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 gateway 认证路径：共享 token/password 认证，或正确配置的非 loopback `trusted-proxy` 部署。 -- `gateway.token` 之类的旧键不能替代 `gateway.auth.token`。 +- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token/password 认证，或正确配置的非 loopback `trusted-proxy` 部署。 +- 像 `gateway.token` 这样的旧键不能替代 `gateway.auth.token`。 常见特征： -- `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 gateway 认证路径。 -- `RPC probe: failed` 且运行时显示为 running → gateway 存活，但使用当前 auth/url 无法访问。 +- `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 Gateway 网关认证路径。 +- `RPC probe: failed` 且运行时正在运行 → Gateway 网关是活的，但以当前 auth/url 无法访问。 -### 3) 配对和设备身份状态已改变 +### 3) 配对和设备身份状态发生了变化 ```bash openclaw devices list @@ -429,17 +418,17 @@ openclaw logs --follow openclaw doctor ``` -检查要点： +检查什么： -- dashboard/节点是否存在待批准设备。 -- 在策略或身份变更后，私信配对批准是否待处理。 +- 仪表板/节点是否存在待批准的设备审批。 +- 策略或身份变更后，是否存在待批准的私信配对审批。 常见特征： - `device identity required` → 设备认证未满足。 -- `pairing required` → 发送者/设备必须获得批准。 +- `pairing required` → 发送者/设备必须先获批。 -如果检查之后服务配置与运行时仍不一致，请从同一个配置档案/状态目录重新安装服务元数据： +如果检查后服务配置和运行时仍不一致，请使用相同的 profile/state 目录重新安装服务元数据： ```bash openclaw gateway install --force @@ -448,6 +437,6 @@ openclaw gateway restart 相关内容： -- [/gateway/pairing](/gateway/pairing) -- [/gateway/authentication](/gateway/authentication) -- [/gateway/background-process](/gateway/background-process) +- [/gateway/pairing](/zh-CN/gateway/pairing) +- [/gateway/authentication](/zh-CN/gateway/authentication) +- [/gateway/background-process](/zh-CN/gateway/background-process) diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md index 1684dae3e..d7f83082d 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -1,23 +1,23 @@ --- read_when: - - 回答常见的设置、安装、新手引导或运行时支持问题时 - - 在进行更深入调试之前，对用户报告的问题进行初步排查时 -summary: 关于 OpenClaw 设置、配置和使用的常见问题 + - 回答常见的设置、安装、新手引导或运行时支持问题 + - 在深入调试前对用户报告的问题进行初步分流 +summary: 关于 OpenClaw 设置、配置和使用的常见问题解答 title: 常见问题 x-i18n: - generated_at: "2026-04-06T12:48:32Z" + generated_at: "2026-04-06T15:34:08Z" model: gpt-5.4 provider: openai - source_hash: 391262b77c6c9b35253fd46b7d6fab324816c3cc25830f322f840fad0c9f58cf + source_hash: bddcde55cf4bcec4913aadab4c665b235538104010e445e4c99915a1672b1148 source_path: help/faq.md workflow: 15 --- # 常见问题 -简明解答，以及针对真实场景部署（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障切换）的更深入故障排除。关于运行时诊断，请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。关于完整配置参考，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +提供快速解答，以及适用于真实环境的更深入故障排除（本地开发、VPS、多智能体、OAuth / API 密钥、模型故障切换）。有关运行时诊断，请参见 [故障排除](/zh-CN/gateway/troubleshooting)。有关完整配置参考，请参见 [配置](/zh-CN/gateway/configuration)。 -## 如果出现故障，最初的六十秒 +## 如果出了问题，最初的六十秒 1. **快速状态（第一项检查）** @@ -25,7 +25,7 @@ x-i18n: openclaw status ``` - 快速本地摘要：操作系统 + 更新、Gateway 网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（当 Gateway 网关可达时）。 + 快速本地摘要：操作系统 + 更新、Gateway 网关 / 服务可达性、智能体 / 会话、提供商配置 + 运行时问题（当 Gateway 网关可达时）。 2. **可粘贴的报告（可安全分享）** @@ -33,7 +33,7 @@ x-i18n: openclaw status --all ``` - 只读诊断，附带日志尾部（令牌已脱敏）。 + 只读诊断，附带日志尾部（令牌已打码）。 3. **守护进程 + 端口状态** @@ -41,7 +41,7 @@ x-i18n: openclaw gateway status ``` - 显示监督器运行状态与 RPC 可达性、探测目标 URL，以及服务可能使用了哪个配置。 + 显示监督器运行时与 RPC 可达性、探测目标 URL，以及服务可能使用了哪个配置。 4. **深度探测** @@ -49,10 +49,10 @@ x-i18n: openclaw status --deep ``` - 运行实时 Gateway 网关健康探测，包括在支持时的渠道探测 - （需要可达的 Gateway 网关）。参阅 [Health](/zh-CN/gateway/health)。 + 运行实时 Gateway 网关健康探测，包括支持时的渠道探测 + （需要可访问的 Gateway 网关）。参见 [健康状态](/zh-CN/gateway/health)。 -5. **跟踪最新日志** +5. **查看最新日志** ```bash openclaw logs --follow @@ -64,7 +64,7 @@ x-i18n: tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - 文件日志与服务日志是分开的；请参阅 [Logging](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 + 文件日志与服务日志是分开的；参见 [日志记录](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 6. **运行 Doctor（修复）** @@ -72,7 +72,7 @@ x-i18n: openclaw doctor ``` - 修复/迁移配置与状态 + 运行健康检查。参阅 [Doctor](/zh-CN/gateway/doctor)。 + 修复 / 迁移配置 / 状态并运行健康检查。参见 [Doctor](/zh-CN/gateway/doctor)。 7. **Gateway 网关快照** @@ -81,39 +81,39 @@ x-i18n: openclaw health --verbose # 出错时显示目标 URL + 配置路径 ``` - 向正在运行的 Gateway 网关请求完整快照（仅 WS）。参阅 [Health](/zh-CN/gateway/health)。 + 向正在运行的 Gateway 网关请求完整快照（仅 WS）。参见 [健康状态](/zh-CN/gateway/health)。 -## 快速开始和首次运行设置 +## 快速开始与首次运行设置 - - 使用一个能**看到你的机器**的本地 AI 智能体。这比在 Discord 里提问 - 有效得多，因为大多数“我卡住了”的情况其实都是**本地配置或环境问题**， - 远程协助者无法直接检查。 + + 使用能够**看到你的机器**的本地 AI 智能体。这比在 Discord 里提问要有效得多， + 因为大多数“我卡住了”的情况都是**本地配置或环境问题**， + 远程帮助者无法直接检查。 - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - 这些工具可以读取仓库、运行命令、检查日志，并帮助修复你机器层面的 - 设置问题（PATH、服务、权限、认证文件）。通过可修改的（git）安装方式， - 把**完整源代码检出**交给它们： + 这些工具可以读取仓库、运行命令、检查日志，并帮助修复你机器级别的 + 设置问题（PATH、服务、权限、凭证文件）。请通过可修改的 + hackable（git）安装方式，把**完整源码检出**提供给它们： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 这会**从 git 检出**安装 OpenClaw，因此智能体可以读取代码 + 文档， - 并准确理解你当前运行的版本。之后你始终可以通过重新运行安装程序并去掉 - `--install-method git` 切回稳定版。 + 这会从 **git 检出**安装 OpenClaw，因此智能体可以读取代码 + 文档， + 并基于你正在运行的确切版本进行推理。你之后始终可以通过重新运行安装器、 + 并去掉 `--install-method git` 切回稳定版。 - 提示：让智能体先**规划并监督**修复过程（逐步进行），然后只执行 - 必要的命令。这样改动会更小，也更容易审计。 + 提示：让智能体先**规划并监督**修复过程（逐步进行），然后只执行必要的 + 命令。这样能让变更保持较小，也更容易审计。 如果你发现了真实的 bug 或修复，请提交 GitHub issue 或发送 PR： [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - 先从这些命令开始（在求助时分享输出）： + 先从这些命令开始（寻求帮助时请附上输出）： ```bash openclaw status @@ -123,44 +123,44 @@ x-i18n: 它们的作用： - - `openclaw status`：快速查看 Gateway 网关/智能体健康状态 + 基础配置。 - - `openclaw models status`：检查提供商认证 + 模型可用性。 - - `openclaw doctor`：验证并修复常见的配置/状态问题。 + - `openclaw status`：快速查看 Gateway 网关 / 智能体健康状态 + 基本配置。 + - `openclaw models status`：检查提供商凭证 + 模型可用性。 + - `openclaw doctor`：验证并修复常见配置 / 状态问题。 其他有用的 CLI 检查：`openclaw status --all`、`openclaw logs --follow`、 `openclaw gateway status`、`openclaw health --verbose`。 - 快速调试循环：[如果出现故障，最初的六十秒](#first-60-seconds-if-something-is-broken)。 - 安装文档：[Install](/zh-CN/install)、[Installer flags](/zh-CN/install/installer)、[Updating](/zh-CN/install/updating)。 + 快速调试循环：[如果出了问题，最初的六十秒](#first-60-seconds-if-something-is-broken)。 + 安装文档：[安装](/zh-CN/install)、[安装器标志](/zh-CN/install/installer)、[更新](/zh-CN/install/updating)。 - + 常见的 Heartbeat 跳过原因： - - `quiet-hours`：当前不在已配置的活跃时间窗口内 - - `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白/仅标题脚手架内容 - - `no-tasks-due`：`HEARTBEAT.md` 任务模式已启用，但当前没有任何任务间隔到期 - - `alerts-disabled`：所有 Heartbeat 可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭） + - `quiet-hours`：不在配置的活跃时间窗口内 + - `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但仅包含空白 / 只有标题的脚手架内容 + - `no-tasks-due`：`HEARTBEAT.md` 任务模式已启用，但尚无任何任务间隔到期 + - `alerts-disabled`：所有 heartbeat 可见性均已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭） - 在任务模式下，只有在一次真实的 Heartbeat 运行 - 完成后，才会推进到期时间戳。被跳过的运行不会将任务标记为已完成。 + 在任务模式下，只有在一次真实 heartbeat 运行完成后，任务的到期时间戳才会推进。 + 被跳过的运行不会将任务标记为已完成。 - 文档：[Heartbeat](/zh-CN/gateway/heartbeat)、[Automation & Tasks](/zh-CN/automation)。 + 文档：[Heartbeat](/zh-CN/gateway/heartbeat)、[自动化与任务](/zh-CN/automation)。 - - 仓库推荐从源码运行并使用新手引导： + + 仓库推荐从源码运行，并使用新手引导： ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - 该向导还可以自动构建 UI 资源。完成新手引导后，你通常会在 **18789** 端口运行 Gateway 网关。 + 向导也可以自动构建 UI 资源。完成新手引导后，你通常会在 **18789** 端口运行 Gateway 网关。 - 从源码安装（贡献者/开发者）： + 从源码开始（贡献者 / 开发者）： ```bash git clone https://github.com/openclaw/openclaw.git @@ -171,90 +171,90 @@ x-i18n: openclaw onboard ``` - 如果你还没有全局安装，可以通过 `pnpm openclaw onboard` 来运行。 + 如果你还没有全局安装，可以通过 `pnpm openclaw onboard` 运行它。 - - 向导会在新手引导完成后立即使用一个干净的（不带令牌的）仪表板 URL 打开你的浏览器，并且也会在摘要中打印该链接。请保持该标签页打开；如果没有自动启动，就在同一台机器上复制/粘贴打印出的 URL。 + + 向导会在新手引导完成后立即使用一个干净的（非 token 化）仪表盘 URL 打开你的浏览器，并在摘要中打印该链接。请保持该标签页打开；如果它没有自动启动，请在同一台机器上复制 / 粘贴打印出的 URL。 - + **localhost（同一台机器）：** - 打开 `http://127.0.0.1:18789/`。 - - 如果它要求共享密钥认证，请将已配置的令牌或密码粘贴到 Control UI 设置中。 - - 令牌来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 + - 如果它要求共享密钥身份验证，请将已配置的 token 或密码粘贴到 Control UI 设置中。 + - Token 来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 - 密码来源：`gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果尚未配置共享密钥，可以通过 `openclaw doctor --generate-gateway-token` 生成一个令牌。 + - 如果尚未配置共享密钥，可使用 `openclaw doctor --generate-gateway-token` 生成 token。 - **不在 localhost：** + **不在 localhost 上：** - - **Tailscale Serve**（推荐）：保持绑定 loopback，运行 `openclaw gateway --tailscale serve`，打开 `https:///`。如果 `gateway.auth.allowTailscale` 为 `true`，身份头会满足 Control UI/WebSocket 认证要求（无需粘贴共享密钥，假定 Gateway 网关主机可信）；HTTP API 仍然需要共享密钥认证，除非你明确使用私有入口 `none` 或受信任代理 HTTP 认证。 - 来自同一客户端的错误并发 Serve 认证尝试会在失败认证限速器记录前被串行化，因此第二次错误重试可能已经显示 `retry later`。 - - **tailnet 绑定**：运行 `openclaw gateway --bind tailnet --token ""`（或配置密码认证），打开 `http://:18789/`，然后在仪表板设置中粘贴匹配的共享密钥。 - - **身份感知反向代理**：让 Gateway 网关保持在一个非 loopback 的受信任代理后面，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开代理 URL。 - - **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。共享密钥认证在隧道上传输时仍然适用；如果出现提示，请粘贴已配置的令牌或密码。 + - **Tailscale Serve**（推荐）：保持绑定 loopback，运行 `openclaw gateway --tailscale serve`，打开 `https:///`。如果 `gateway.auth.allowTailscale` 为 `true`，身份标头将满足 Control UI / WebSocket 身份验证要求（无需粘贴共享密钥，默认信任 Gateway 网关主机）；HTTP API 仍然需要共享密钥身份验证，除非你明确使用私有入口 `none` 或受信任代理 HTTP 身份验证。 + 来自同一客户端的并发 Serve 错误身份验证尝试，会在失败身份验证限速器记录之前被串行化，因此第二次错误重试可能已经显示 `retry later`。 + - **Tailnet 绑定**：运行 `openclaw gateway --bind tailnet --token ""`（或配置密码身份验证），打开 `http://:18789/`，然后在仪表盘设置中粘贴对应的共享密钥。 + - **具身份感知的反向代理**：将 Gateway 网关放在非 loopback 的受信任代理之后，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开代理 URL。 + - **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。通过隧道时仍适用共享密钥身份验证；如果出现提示，请粘贴已配置的 token 或密码。 - 关于绑定模式和认证细节，请参阅 [Dashboard](/web/dashboard) 和 [Web surfaces](/web)。 + 参见 [仪表盘](/web/dashboard) 和 [Web 界面](/web) 了解绑定模式与身份验证细节。 - + 它们控制的是不同层级： - - `approvals.exec`：将审批提示转发到聊天目标 - - `channels..execApprovals`：让该渠道作为 exec 审批的原生审批客户端 + - `approvals.exec`：将审批提示转发到聊天目的地 + - `channels..execApprovals`：使该渠道充当 exec 审批的原生审批客户端 - 主机 exec 策略仍然是真正的审批门禁。聊天配置只控制审批 - 提示出现在哪里，以及人们如何回应。 + 主机 exec 策略仍然是真正的审批门槛。聊天配置只控制审批提示 + 出现在什么地方，以及人们如何回复它们。 - 在大多数设置中，你**不**需要同时启用两者： + 在大多数设置中，你**不需要**同时使用两者： - - 如果聊天本身已经支持命令和回复，那么同一聊天中的 `/approve` 会通过共享路径生效。 - - 如果某个受支持的原生渠道可以安全推断审批人，OpenClaw 现在会在 `channels..execApprovals.enabled` 未设置或为 `"auto"` 时自动启用私信优先的原生审批。 - - 当存在原生审批卡片/按钮时，该原生 UI 是主路径；只有当工具结果表明聊天审批不可用或手动审批是唯一途径时，智能体才应包含手动 `/approve` 命令。 - - 只有当提示还需要转发到其他聊天或明确的运维房间时，才使用 `approvals.exec`。 - - 只有当你明确希望把审批提示发回原始房间/主题时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 - - 插件审批则是另外一套：默认使用同一聊天中的 `/approve`，可选 `approvals.plugin` 转发，并且只有部分原生渠道会在其之上保留原生插件审批处理。 + - 如果聊天本身已经支持命令和回复，那么同一聊天内的 `/approve` 会通过共享路径工作。 + - 如果某个受支持的原生渠道可以安全推断审批人，而 `channels..execApprovals.enabled` 未设置或为 `"auto"`，OpenClaw 现在会自动启用“优先私信”的原生审批。 + - 当存在原生审批卡片 / 按钮时，该原生 UI 是主路径；只有在工具结果表明聊天审批不可用或手动审批是唯一方式时，智能体才应包含手动 `/approve` 命令。 + - 仅当提示还必须转发到其他聊天或明确的运维房间时，才使用 `approvals.exec`。 + - 仅当你明确希望将审批提示回发到原始房间 / 主题时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 + - 插件审批则再次独立：它们默认使用同一聊天内的 `/approve`，可选 `approvals.plugin` 转发，并且只有部分原生渠道会在此之上保留原生插件审批处理。 - 简而言之：转发用于路由，原生客户端配置用于更丰富的渠道特定 UX。 - 参阅 [Exec Approvals](/zh-CN/tools/exec-approvals)。 + 简而言之：转发用于路由，原生客户端配置用于提供更丰富的渠道特定 UX。 + 参见 [Exec 审批](/zh-CN/tools/exec-approvals)。 - 需要 Node **>= 22**。推荐使用 `pnpm`。**不推荐**使用 Bun 运行 Gateway 网关。 + 需要 Node **>= 22**。推荐使用 `pnpm`。Gateway 网关**不推荐**使用 Bun。 - 可以。Gateway 网关非常轻量——文档中写明个人使用场景下 **512 MB - 1 GB RAM**、**1 个核心** 和大约 **500 MB** - 磁盘空间就足够，并且注明 **Raspberry Pi 4 可以运行它**。 + 可以。Gateway 网关很轻量——文档中写明个人使用场景下 **512 MB - 1 GB 内存**、**1 核**、约 **500 MB** + 磁盘就足够，并注明 **Raspberry Pi 4 可以运行它**。 - 如果你想留出更多余量（日志、媒体、其他服务），推荐使用 **2 GB**， - 但这不是硬性最低要求。 + 如果你想要更多余量（日志、媒体、其他服务），推荐 **2 GB**，但 + 这并不是硬性最低要求。 - 提示：小型 Pi/VPS 可以托管 Gateway 网关，而你可以在笔记本/手机上配对**节点**， - 以实现本地屏幕/摄像头/画布或命令执行。参阅 [Nodes](/zh-CN/nodes)。 + 提示：小型 Pi / VPS 可以托管 Gateway 网关，而你可以在笔记本 / 手机上配对 **节点**，用于 + 本地屏幕 / 摄像头 / Canvas 或命令执行。参见 [节点](/zh-CN/nodes)。 - - 简短回答：可以运行，但要预期会遇到一些边角问题。 + + 简短回答：能用，但要预期会有一些粗糙边缘。 - 使用 **64 位**操作系统，并保持 Node >= 22。 - - 优先使用**可修改的（git）安装**，这样你可以查看日志并快速更新。 - - 先不要启用 channels/Skills，然后逐个添加。 + - 优先使用 **hackable（git）安装**，这样你可以查看日志并快速更新。 + - 先在没有渠道 / Skills 的情况下启动，然后逐个添加。 - 如果遇到奇怪的二进制问题，通常是 **ARM 兼容性**问题。 - 文档：[Linux](/zh-CN/platforms/linux)、[Install](/zh-CN/install)。 + 文档：[Linux](/zh-CN/platforms/linux)、[安装](/zh-CN/install)。 - - 该界面依赖 Gateway 网关可达且已认证。TUI 也会在首次 hatch 时自动发送 + + 该界面依赖 Gateway 网关可达并且已通过身份验证。TUI 也会在首次 hatch 时自动发送 “Wake up, my friend!”。如果你看到这行字却**没有回复**， - 且 token 仍然为 0，说明智能体从未真正运行。 + 且 token 始终为 0，说明智能体根本没有运行。 1. 重启 Gateway 网关： @@ -262,7 +262,7 @@ x-i18n: openclaw gateway restart ``` - 2. 检查状态 + 认证： + 2. 检查状态 + 凭证： ```bash openclaw status @@ -276,78 +276,76 @@ x-i18n: openclaw doctor ``` - 如果 Gateway 网关是远程的，请确保隧道/Tailscale 连接正常，并且 UI - 指向了正确的 Gateway 网关。参阅 [Remote access](/zh-CN/gateway/remote)。 + 如果 Gateway 网关在远程环境中，请确保隧道 / Tailscale 连接已建立，并且 UI + 指向了正确的 Gateway 网关。参见 [远程访问](/zh-CN/gateway/remote)。 - - 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。这会 - 让你的机器人“完全保持一致”（记忆、会话历史、认证和渠道 - 状态），前提是你复制了**这两个**位置： + + 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。这样会 + 保持你的机器人“完全不变”（记忆、会话历史、凭证和渠道 + 状态），前提是你复制了**这两个位置**： 1. 在新机器上安装 OpenClaw。 2. 从旧机器复制 `$OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）。 3. 复制你的工作区（默认：`~/.openclaw/workspace`）。 4. 运行 `openclaw doctor` 并重启 Gateway 网关服务。 - 这会保留配置、认证档案、WhatsApp 凭据、会话和记忆。如果你处于 - 远程模式，请记住会话存储和工作区都由 gateway 主机持有。 + 这样会保留配置、凭证配置文件、WhatsApp 凭证、会话和记忆。如果你处于 + 远程模式，请记住会话存储和工作区归 Gateway 网关主机所有。 - **重要：**如果你只把工作区提交/推送到 GitHub，你备份的是 - **记忆 + 引导文件**，但**不是**会话历史或认证。这些都位于 + **重要：**如果你只是把工作区 commit / push 到 GitHub，你备份的是 + **记忆 + 引导文件**，但**不包括**会话历史或凭证。这些内容存储在 `~/.openclaw/` 下（例如 `~/.openclaw/agents//sessions/`）。 - 相关内容：[Migrating](/zh-CN/install/migrating)、[磁盘上的存储位置](#where-things-live-on-disk)、 - [Agent workspace](/zh-CN/concepts/agent-workspace)、[Doctor](/zh-CN/gateway/doctor)、 - [Remote mode](/zh-CN/gateway/remote)。 + 相关内容：[迁移](/zh-CN/install/migrating)、[磁盘上的文件位置](#where-things-live-on-disk)、 + [智能体工作区](/zh-CN/concepts/agent-workspace)、[Doctor](/zh-CN/gateway/doctor)、 + [远程模式](/zh-CN/gateway/remote)。 - + 查看 GitHub 更新日志： [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 最新条目位于顶部。如果最顶部的部分标记为 **Unreleased**，则下一节带日期的 - 部分就是最新发布版本。条目按 **Highlights**、**Changes** 和 - **Fixes** 分组（必要时还会有 docs/其他部分）。 + 最新条目在最上方。如果最顶部部分标记为 **Unreleased**，则下一个带日期的 + 部分就是最新已发布版本。条目按 **Highlights**、**Changes** 和 + **Fixes** 分组（需要时还会有 docs / other 部分）。 - 某些 Comcast/Xfinity 连接会被 Xfinity - Advanced Security 错误地拦截 `docs.openclaw.ai`。请禁用它或将 `docs.openclaw.ai` - 加入允许列表，然后重试。 - 也请通过这里帮助我们解除拦截：[https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。 + 某些 Comcast / Xfinity 连接会错误地通过 Xfinity + Advanced Security 屏蔽 `docs.openclaw.ai`。请禁用它或将 `docs.openclaw.ai` 加入白名单，然后重试。 + 也请通过这里帮助我们解除屏蔽：[https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。 - 如果你仍然无法访问该站点，文档也镜像在 GitHub 上： + 如果你仍然无法访问该站点，文档在 GitHub 上也有镜像： [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - - **稳定版**和 **beta** 是 **npm dist-tag**，不是两条独立的代码线： + + **Stable** 和 **beta** 是 **npm dist-tag**，不是独立的代码线： - `latest` = 稳定版 - `beta` = 用于测试的早期构建 - 通常，一个稳定版本会先发布到 **beta**，然后通过一次显式 - 提升步骤把同一个版本移动到 `latest`。维护者在需要时也可以 - 直接发布到 `latest`。这就是为什么 beta 和稳定版在提升后 - 可能指向**同一个版本**。 + 通常，一个稳定版会先发布到 **beta**，然后通过一次明确的 + 提升步骤将同一版本移动到 `latest`。维护者也可以在必要时 + 直接发布到 `latest`。这就是为什么 beta 与 stable 在提升后可能指向**同一个版本**。 - 查看更改内容： + 查看变更内容： [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 关于安装一行命令以及 beta 和 dev 的区别，请参阅下面的折叠项。 + 有关安装单行命令以及 beta 与 dev 的区别，请参见下方的折叠项。 - - **Beta** 是 npm dist-tag `beta`（提升后可能与 `latest` 相同）。 - **Dev** 是 `main` 的滚动头部版本（git）；发布时使用 npm dist-tag `dev`。 + + **Beta** 是 npm dist-tag `beta`（提升后可能与 `latest` 一致）。 + **Dev** 是 `main` 的移动头部（git）；发布后使用 npm dist-tag `dev`。 - 一行命令（macOS/Linux）： + 单行命令（macOS / Linux）： ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta @@ -357,15 +355,15 @@ x-i18n: curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Windows 安装程序（PowerShell）： + Windows 安装器（PowerShell）： [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - 更多细节：[Development channels](/zh-CN/install/development-channels) 和 [Installer flags](/zh-CN/install/installer)。 + 更多细节：[开发渠道](/zh-CN/install/development-channels) 和 [安装器标志](/zh-CN/install/installer)。 - - 有两个选项： + + 有两种方式： 1. **Dev 渠道（git 检出）：** @@ -375,15 +373,15 @@ x-i18n: 这会切换到 `main` 分支并从源码更新。 - 2. **可修改安装（来自安装站点）：** + 2. **Hackable 安装（来自安装站点）：** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 这样你会得到一个本地仓库，可以编辑，然后通过 git 更新。 + 这样你会得到一个可本地编辑的仓库，然后可以通过 git 更新。 - 如果你更喜欢手动进行干净克隆，请使用： + 如果你更喜欢手动做一个干净克隆，请使用： ```bash git clone https://github.com/openclaw/openclaw.git @@ -392,42 +390,42 @@ x-i18n: pnpm build ``` - 文档：[Update](/cli/update)、[Development channels](/zh-CN/install/development-channels)、 - [Install](/zh-CN/install)。 + 文档：[更新](/cli/update)、[开发渠道](/zh-CN/install/development-channels)、 + [安装](/zh-CN/install)。 - + 粗略参考： - **安装：**2 - 5 分钟 - - **新手引导：**5 - 15 分钟，取决于你配置了多少渠道/模型 + - **新手引导：**5 - 15 分钟，取决于你配置了多少渠道 / 模型 - 如果它卡住了，请使用 [Installer stuck](#quick-start-and-first-run-setup) - 以及 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。 + 如果卡住，请参考 [安装器卡住了](#quick-start-and-first-run-setup) + 和 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。 - - 重新运行安装程序，并启用**详细输出**： + + 使用**详细输出**重新运行安装器： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - 带详细输出的 beta 安装： + 安装 beta 并启用详细输出： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - 对于可修改的（git）安装： + 对于 hackable（git）安装： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose ``` - Windows（PowerShell）等效方式： + Windows（PowerShell）等效方法： ```powershell # install.ps1 目前还没有专用的 -Verbose 标志。 @@ -436,44 +434,44 @@ x-i18n: Set-PSDebug -Trace 0 ``` - 更多选项：[Installer flags](/zh-CN/install/installer)。 + 更多选项：[安装器标志](/zh-CN/install/installer)。 - 两个常见的 Windows 问题： + Windows 上有两个常见问题： **1）npm 错误 spawn git / git not found** - 安装 **Git for Windows**，并确保 `git` 在你的 PATH 中。 - - 关闭并重新打开 PowerShell，然后重新运行安装程序。 + - 关闭并重新打开 PowerShell，然后重新运行安装器。 **2）安装后 openclaw is not recognized** - - 你的 npm 全局 bin 文件夹不在 PATH 中。 + - 你的 npm 全局 bin 目录不在 PATH 中。 - 检查路径： ```powershell npm config get prefix ``` - - 将该目录添加到你的用户 PATH（Windows 上不需要 `\bin` 后缀；在大多数系统中它是 `%AppData%\npm`）。 - - 更新 PATH 后，关闭并重新打开 PowerShell。 + - 将该目录添加到你的用户 PATH 中（Windows 上无需 `\bin` 后缀；大多数系统上它是 `%AppData%\npm`）。 + - 更新 PATH 后关闭并重新打开 PowerShell。 - 如果你想要最顺滑的 Windows 设置体验，请使用 **WSL2**，而不是原生 Windows。 + 如果你想获得最顺畅的 Windows 设置体验，请使用 **WSL2**，而不是原生 Windows。 文档：[Windows](/zh-CN/platforms/windows)。 - + 这通常是原生 Windows shell 中控制台代码页不匹配导致的。 症状： - - `system.run`/`exec` 输出中的中文显示为乱码 - - 同一命令在另一个终端配置中显示正常 + - `system.run` / `exec` 输出中的中文显示为乱码 + - 同一命令在其他终端配置文件中显示正常 - PowerShell 中的快速变通方法： + PowerShell 中的快速解决方法： ```powershell chcp 65001 @@ -488,67 +486,67 @@ x-i18n: openclaw gateway restart ``` - 如果你在最新 OpenClaw 上仍能复现该问题，请在这里跟踪/报告： + 如果你在最新版 OpenClaw 中仍能复现该问题，请在这里跟踪 / 报告： - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - 使用**可修改的（git）安装**，这样你就可以在本地拥有完整源码和文档，然后 - 从该文件夹中向你的机器人（或 Claude/Codex）提问， - 这样它就能读取仓库并给出精确回答。 + + 使用 **hackable（git）安装**，这样你就能在本地拥有完整源码和文档，然后 + 从该文件夹中向你的机器人（或 Claude / Codex）提问， + 它就能读取仓库并给出精确答案。 ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 更多细节：[Install](/zh-CN/install) 和 [Installer flags](/zh-CN/install/installer)。 + 更多细节：[安装](/zh-CN/install) 和 [安装器标志](/zh-CN/install/installer)。 - - 简短回答：按照 Linux 指南，然后运行新手引导。 + + 简短回答：按照 Linux 指南操作，然后运行新手引导。 - Linux 快速路径 + 服务安装：[Linux](/zh-CN/platforms/linux)。 - 完整演练：[入门指南](/zh-CN/start/getting-started)。 - - 安装程序 + 更新：[Install & updates](/zh-CN/install/updating)。 + - 安装器 + 更新：[安装与更新](/zh-CN/install/updating)。 - - 任何 Linux VPS 都可以。先在服务器上安装，然后通过 SSH/Tailscale 访问 Gateway 网关。 + + 任何 Linux VPS 都可以。安装到服务器上，然后通过 SSH / Tailscale 访问 Gateway 网关。 指南：[exe.dev](/zh-CN/install/exe-dev)、[Hetzner](/zh-CN/install/hetzner)、[Fly.io](/zh-CN/install/fly)。 - 远程访问：[Gateway remote](/zh-CN/gateway/remote)。 + 远程访问：[Gateway 网关远程访问](/zh-CN/gateway/remote)。 - - 我们提供一个**托管中心**，汇总常见提供商。选择一个并按照指南操作： + + 我们维护了一个**托管中心**，收录常见提供商。选择其中一个并按照指南操作： - - [VPS hosting](/zh-CN/vps)（所有提供商集中在一处） + - [VPS 托管](/zh-CN/vps)（所有提供商集中在一处） - [Fly.io](/zh-CN/install/fly) - [Hetzner](/zh-CN/install/hetzner) - [exe.dev](/zh-CN/install/exe-dev) - 在云中它的工作方式是：**Gateway 网关运行在服务器上**，而你通过 - Control UI（或 Tailscale/SSH）从笔记本/手机访问它。你的状态 + 工作区 - 都保存在服务器上，因此请将主机视为唯一事实来源并做好备份。 + 云中工作方式如下：**Gateway 网关运行在服务器上**，你通过 Control UI + （或 Tailscale / SSH）从笔记本 / 手机上访问它。你的状态 + 工作区 + 存储在服务器上，因此请将主机视为事实来源并做好备份。 - 你可以将**节点**（Mac/iOS/Android/无头）配对到这个云端 Gateway 网关， - 以访问本地屏幕/摄像头/画布，或在笔记本上运行命令，同时让 + 你可以将 **节点**（Mac / iOS / Android / 无头设备）配对到该云端 Gateway 网关，以访问 + 本地屏幕 / 摄像头 / Canvas，或在笔记本上运行命令，同时将 Gateway 网关保留在云中。 - 中心页：[Platforms](/zh-CN/platforms)。远程访问：[Gateway remote](/zh-CN/gateway/remote)。 - 节点：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 + 中心：[平台](/zh-CN/platforms)。远程访问：[Gateway 网关远程访问](/zh-CN/gateway/remote)。 + 节点：[节点](/zh-CN/nodes)、[节点 CLI](/cli/nodes)。 - + 简短回答：**可以，但不推荐**。更新流程可能会重启 - Gateway 网关（这会中断当前会话），可能需要一个干净的 git 检出， - 还可能提示你确认。更安全的做法是由操作员在 shell 中执行更新。 + Gateway 网关（这会中断当前会话），可能需要一个干净的 git 检出，并且 + 可能会要求确认。更安全的方式：由操作员在 shell 中运行更新。 使用 CLI： @@ -560,207 +558,226 @@ x-i18n: openclaw update --no-restart ``` - 如果你必须从智能体中自动化： + 如果你必须从智能体中自动化执行： ```bash openclaw update --yes --no-restart openclaw gateway restart ``` - 文档：[Update](/cli/update)、[Updating](/zh-CN/install/updating)。 + 文档：[更新](/cli/update)、[更新说明](/zh-CN/install/updating)。 `openclaw onboard` 是推荐的设置路径。在**本地模式**下，它会引导你完成： - - **模型/认证设置**（提供商 OAuth、API 密钥、Anthropic 旧版 setup-token，以及 LM Studio 之类的本地模型选项） + - **模型 / 凭证设置**（提供商 OAuth、API 密钥、Anthropic setup-token，以及 LM Studio 等本地模型选项） - **工作区**位置 + 引导文件 - - **Gateway 网关设置**（bind/port/auth/tailscale） + - **Gateway 网关设置**（bind / port / auth / tailscale） - **渠道**（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage，以及像 QQ Bot 这样的内置渠道插件） - - **守护进程安装**（macOS 上为 LaunchAgent；Linux/WSL2 上为 systemd 用户单元） - - **健康检查**和 **Skills** 选择 + - **守护进程安装**（macOS 上为 LaunchAgent；Linux / WSL2 上为 systemd user unit） + - **健康检查** 和 **Skills** 选择 - 如果你配置的模型未知或缺少认证，它也会发出警告。 + 如果你配置的模型未知或缺少凭证，它也会发出警告。 - 不需要。你可以通过 **API 密钥**（Anthropic/OpenAI/其他）来运行 OpenClaw， - 也可以使用**纯本地模型**，这样你的数据就会保留在设备上。订阅（Claude - Pro/Max 或 OpenAI Codex）只是认证这些提供商的可选方式。 + 不需要。你可以通过 **API 密钥**（Anthropic / OpenAI / 其他）运行 OpenClaw，也可以使用 + **仅本地模型**，这样你的数据就能保留在自己的设备上。订阅（Claude + Pro / Max 或 OpenAI Codex）只是这些提供商的可选身份验证方式。 - 对于 OpenClaw 中的 Anthropic，实际区别是： + 对于 OpenClaw 中的 Anthropic，实际可分为： - **Anthropic API 密钥**：正常的 Anthropic API 计费 - - **OpenClaw 中的 Claude 订阅认证**：Anthropic 于 - **2026 年 4 月 4 日太平洋时间下午 12:00 / 英国夏令时晚上 8:00** 告知 OpenClaw 用户， - 这需要**Extra Usage**，并且会在订阅之外单独计费 + - **OpenClaw 中的 Claude CLI / Claude 订阅凭证**：Anthropic 工作人员 + 告诉我们，这种用法再次被允许，因此除非 Anthropic 发布新政策， + 否则 OpenClaw 会将 `claude -p` + 用法视为该集成的许可用法 - 我们的本地复现还表明，`claude -p --append-system-prompt ...` 在附加提示中标识 - OpenClaw 时，也可能触发同样的 Extra Usage 限制； - 而在 Anthropic SDK + API 密钥路径中，使用相同的提示字符串 - 则**不会**复现这一阻断。OpenAI Codex OAuth 明确 - 支持在 OpenClaw 这样的外部工具中使用。 + 对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是 + 更可预测的设置方式。OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部 + 工具。 - OpenClaw 还支持其他托管型订阅选项，包括 + OpenClaw 还支持其他托管式订阅方案，包括 **Qwen Cloud Coding Plan**、**MiniMax Coding Plan** 和 **Z.AI / GLM Coding Plan**。 文档：[Anthropic](/zh-CN/providers/anthropic)、[OpenAI](/zh-CN/providers/openai)、 [Qwen Cloud](/zh-CN/providers/qwen)、 [MiniMax](/zh-CN/providers/minimax)、[GLM Models](/zh-CN/providers/glm)、 - [Local models](/zh-CN/gateway/local-models)、[Models](/zh-CN/concepts/models)。 + [本地模型](/zh-CN/gateway/local-models)、[模型](/zh-CN/concepts/models)。 - 可以，但请将其视为**带 Extra Usage 的 Claude 订阅认证**。 + 可以。 - Claude Pro/Max 订阅并不包含 API 密钥。在 OpenClaw 中，这 - 意味着 Anthropic 针对 OpenClaw 的计费通知仍然适用：订阅 - 流量需要 **Extra Usage**。如果你希望使用 Anthropic 且不经过 - 这条 Extra Usage 路径，请改用 Anthropic API 密钥。 + Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 + 除非 Anthropic 发布新政策，否则 + OpenClaw 会将 Claude 订阅凭证和 `claude -p` 用法视为该集成的许可用法。如果你想要 + 最可预测的服务器端设置，请改用 Anthropic API 密钥。 - - 支持，但当前支持的理解方式是： + + 支持。 - - 在 OpenClaw 中使用订阅认证 Anthropic，意味着 **Extra Usage** - - 在 OpenClaw 中不走这条路径使用 Anthropic，则意味着 **API 密钥** + Anthropic 工作人员告诉我们，这种用法再次被允许，因此除非 Anthropic 发布新政策， + 否则 OpenClaw 会将 + Claude CLI 复用和 `claude -p` 用法视为该集成的许可用法。 - Anthropic setup-token 仍然可作为 OpenClaw 中的旧版/手动路径使用， - Anthropic 针对 OpenClaw 的计费通知在该路径中仍然适用。我们 - 还在本地使用直接的 - `claude -p --append-system-prompt ...` 时复现了相同的计费限制， - 条件是附加提示中明确标识了 OpenClaw，而相同的提示字符串在 - Anthropic SDK + API 密钥路径中则**不会**复现。 - - 对于生产环境或多用户工作负载，Anthropic API 密钥认证是 - 更安全、更推荐的选择。如果你想在 OpenClaw 中使用其他订阅式托管 - 选项，请参阅 [OpenAI](/zh-CN/providers/openai)、[Qwen / Model - Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 - [GLM Models](/zh-CN/providers/glm)。 + Anthropic setup-token 仍然作为受支持的 OpenClaw token 路径提供，但在可用时，OpenClaw 现在更偏好 Claude CLI 复用和 `claude -p`。 + 对于生产环境或多用户工作负载，Anthropic API 密钥凭证仍然是 + 更安全、更可预测的选择。如果你想在 OpenClaw 中使用其他托管式订阅选项， + 参见 [OpenAI](/zh-CN/providers/openai)、[Qwen / Model + Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [GLM + Models](/zh-CN/providers/glm)。 -这意味着你在当前时间窗口中的 **Anthropic 配额/速率限制** 已耗尽。如果你 -使用 **Claude CLI**，请等待该窗口重置，或升级你的套餐。如果你 +这意味着你当前窗口的 **Anthropic 配额 / 速率限制** 已耗尽。如果你 +使用 **Claude CLI**，请等待窗口重置或升级你的套餐。如果你 使用 **Anthropic API 密钥**，请检查 Anthropic Console -中的用量/计费情况，并按需提高限制。 +中的使用量 / 计费，并根据需要提高限制。 - 如果消息明确写着： - `Extra usage is required for long context requests`，说明该请求正在尝试使用 - Anthropic 的 1M 上下文 beta（`context1m: true`）。这只有在你的 - 凭据具备长上下文计费资格时才有效（API 密钥计费或 + 如果消息明确是： + `Extra usage is required for long context requests`，说明请求正尝试使用 + Anthropic 的 1M 上下文 beta（`context1m: true`）。这仅在你的 + 凭证具备长上下文计费资格时可用（API 密钥计费，或 启用了 Extra Usage 的 OpenClaw Claude 登录路径）。 - 提示：设置一个**后备模型**，这样在某个提供商被限流时，OpenClaw 仍能继续回复。 - 参阅 [Models](/cli/models)、[OAuth](/zh-CN/concepts/oauth) 和 + 提示：设置一个**回退模型**，这样当某个提供商受到速率限制时，OpenClaw 仍可继续回复。 + 参见 [模型](/cli/models)、[OAuth](/zh-CN/concepts/oauth) 和 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。 - 支持。OpenClaw 内置了 **Amazon Bedrock（Converse）** 提供商。当存在 AWS 环境标记时，OpenClaw 可以自动发现 Bedrock 的流式/文本模型目录，并将其作为隐式 `amazon-bedrock` 提供商合并；否则你也可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled` 或手动添加一个提供商条目。参阅 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [Model providers](/zh-CN/providers/models)。如果你更偏好托管密钥流程，在 Bedrock 前面加一个兼容 OpenAI 的代理仍然是有效选项。 + 支持。OpenClaw 内置了 **Amazon Bedrock（Converse）** 提供商。当 AWS 环境标记存在时，OpenClaw 可以自动发现支持流式 / 文本的 Bedrock 目录，并将其合并为隐式的 `amazon-bedrock` 提供商；否则，你也可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled` 或添加手动提供商条目。参见 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [模型提供商](/zh-CN/providers/models)。如果你更喜欢托管式密钥流程，在 Bedrock 前面使用 OpenAI 兼容代理仍然是可行的选择。 - - OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code（Codex）**。新手引导可以运行 OAuth 流程，并会在合适时将默认模型设置为 `openai-codex/gpt-5.4`。参阅 [Model providers](/zh-CN/concepts/model-providers) 和 [Onboarding（CLI）](/zh-CN/start/wizard)。 + + OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code（Codex）**。新手引导可以运行 OAuth 流程，并在适用时将默认模型设置为 `openai-codex/gpt-5.4`。参见 [模型提供商](/zh-CN/concepts/model-providers) 和 [设置向导（CLI）](/zh-CN/start/wizard)。 - - 支持。OpenClaw 完全支持 **OpenAI Code（Codex）订阅 OAuth**。 - OpenAI 明确允许在 OpenClaw 这样的外部工具/工作流中 - 使用订阅 OAuth。新手引导可以为你运行该 OAuth 流程。 + + OpenClaw 将这两条路径分开处理： - 参阅 [OAuth](/zh-CN/concepts/oauth)、[Model providers](/zh-CN/concepts/model-providers) 和 [Onboarding（CLI）](/zh-CN/start/wizard)。 + - `openai-codex/gpt-5.4` = ChatGPT / Codex OAuth + - `openai/gpt-5.4` = 直接 OpenAI Platform API + + 在 OpenClaw 中，ChatGPT / Codex 登录连接到 `openai-codex/*` 路径， + 而不是直接的 `openai/*` 路径。如果你想要 OpenClaw 中的直接 API 路径， + 请设置 `OPENAI_API_KEY`（或等效的 OpenAI 提供商配置）。 + 如果你想在 OpenClaw 中使用 ChatGPT / Codex 登录，请使用 `openai-codex/*`。 - - Gemini CLI 使用的是**插件认证流程**，而不是在 `openclaw.json` 中填写 client id 或 secret。 + + `openai-codex/*` 使用 Codex OAuth 路径，其可用配额窗口由 + OpenAI 管理，并且取决于你的套餐。在实践中，这些限制可能与 + ChatGPT 网站 / 应用的体验不同，即使两者绑定到同一个账户也是如此。 - 步骤： + OpenClaw 可以在 + `openclaw models status` 中显示当前可见的提供商使用量 / 配额窗口，但它不会凭空发明或将 ChatGPT Web + 权益标准化为直接 API 访问。如果你想使用直接的 OpenAI Platform + 计费 / 限额路径，请通过 API 密钥使用 `openai/*`。 - 1. 在本地安装 Gemini CLI，使 `gemini` 位于 `PATH` 中 + + + + 支持。OpenClaw 完整支持 **OpenAI Code（Codex）订阅 OAuth**。 + OpenAI 明确允许在 OpenClaw 这类外部工具 / 工作流中 + 使用订阅 OAuth。新手引导可以为你运行 OAuth 流程。 + + 参见 [OAuth](/zh-CN/concepts/oauth)、[模型提供商](/zh-CN/concepts/model-providers) 和 [设置向导（CLI）](/zh-CN/start/wizard)。 + + + + + Gemini CLI 使用的是**插件凭证流程**，而不是 `openclaw.json` 中的 client id 或 secret。 + + 步骤如下： + + 1. 在本地安装 Gemini CLI，使 `gemini` 可在 `PATH` 中找到 - Homebrew：`brew install gemini-cli` - npm：`npm install -g @google/gemini-cli` 2. 启用插件：`openclaw plugins enable google` 3. 登录：`openclaw models auth login --provider google-gemini-cli --set-default` 4. 登录后的默认模型：`google-gemini-cli/gemini-3.1-pro-preview` - 5. 如果请求失败，请在 gateway 主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID` + 5. 如果请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID` - 这会将 OAuth 令牌存储在 gateway 主机上的认证档案中。详情： [Model providers](/zh-CN/concepts/model-providers)。 + 这会把 OAuth token 存储到 Gateway 网关主机上的凭证配置文件中。详情： [模型提供商](/zh-CN/concepts/model-providers)。 - - 通常不适合。OpenClaw 需要较大的上下文 + 强安全性；小模型容易截断并泄漏信息。如果你一定要这样做，请在本地运行你能承载的**最大**模型构建（LM Studio），并参阅 [/gateway/local-models](/zh-CN/gateway/local-models)。更小/量化更重的模型会增加提示注入风险——参阅 [Security](/zh-CN/gateway/security)。 + + 通常不适合。OpenClaw 需要大上下文 + 强安全性；小显存模型会截断并泄露。如果你一定要用，请在本地（LM Studio）运行你能承载的**最大**模型构建，并参见 [/gateway/local-models](/zh-CN/gateway/local-models)。更小 / 更量化的模型会增加 prompt injection 风险——参见 [安全](/zh-CN/gateway/security)。 - - 请选择固定区域的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供了美国托管选项；选择美国托管变体即可将数据保留在该区域。你仍然可以通过使用 `models.mode: "merge"` 将 Anthropic/OpenAI 一起列出，这样在遵守所选区域提供商的前提下，也能保留后备选项。 + + 选择区域固定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供美国托管选项；选择美国托管变体即可让数据保留在该区域内。你仍然可以通过 `models.mode: "merge"` 同时列出 Anthropic / OpenAI，使回退保持可用，同时遵守你选择的区域化提供商。 - - 不需要。OpenClaw 可运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选项——有些人 - 会买一台作为常开主机，但小型 VPS、家用服务器或 Raspberry Pi 级别的机器也能胜任。 + + 不需要。OpenClaw 可运行于 macOS 或 Linux（Windows 可通过 WSL2）。Mac mini 是可选的——有些人 + 会买一台作为常开主机，但小型 VPS、家用服务器或 Raspberry Pi 级别设备也可以。 - 你只在需要**仅限 macOS 的工具**时才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）——BlueBubbles 服务器可以运行在任何 Mac 上，而 Gateway 网关可以运行在 Linux 或其他地方。如果你需要其他仅限 macOS 的工具，请在 Mac 上运行 Gateway 网关，或配对一个 macOS 节点。 + 只有在使用 **仅限 macOS 的工具** 时，你才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）——BlueBubbles 服务器运行在任意 Mac 上，而 Gateway 网关可以运行在 Linux 或其他地方。如果你想使用其他仅限 macOS 的工具，请在 Mac 上运行 Gateway 网关，或配对一个 macOS 节点。 - 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、[Mac remote mode](/zh-CN/platforms/mac/remote)。 + 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[节点](/zh-CN/nodes)、[Mac 远程模式](/zh-CN/platforms/mac/remote)。 - - 你需要**某个已登录 Messages 的 macOS 设备**。它**不一定**要是 Mac mini—— + + 你需要某个**已登录 Messages 的 macOS 设备**。它**不一定**是 Mac mini—— 任何 Mac 都可以。对于 iMessage，请**使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）——BlueBubbles 服务器运行在 macOS 上，而 Gateway 网关可以运行在 Linux 或其他地方。 常见设置： - - 在 Linux/VPS 上运行 Gateway 网关，并在任意登录了 Messages 的 Mac 上运行 BlueBubbles 服务器。 - - 如果你想要最简单的单机设置，就把所有内容都运行在 Mac 上。 + - 在 Linux / VPS 上运行 Gateway 网关，在任意已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。 + - 如果你想要最简单的单机设置，也可以把所有内容都运行在 Mac 上。 - 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、 - [Mac remote mode](/zh-CN/platforms/mac/remote)。 + 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[节点](/zh-CN/nodes)、 + [Mac 远程模式](/zh-CN/platforms/mac/remote)。 - + 可以。**Mac mini 可以运行 Gateway 网关**，而你的 MacBook Pro 可以作为 - **节点**（配套设备）连接。节点不运行 Gateway 网关——它们提供额外 - 的能力，比如该设备上的屏幕/摄像头/画布以及 `system.run`。 + **节点**（配套设备）连接。节点不会运行 Gateway 网关——它们会提供额外 + 功能，例如该设备上的屏幕 / 摄像头 / Canvas 和 `system.run`。 常见模式： - - Gateway 网关运行在 Mac mini 上（始终在线）。 + - Gateway 网关运行在 Mac mini 上（常开）。 - MacBook Pro 运行 macOS 应用或节点主机，并与 Gateway 网关配对。 - - 使用 `openclaw nodes status` / `openclaw nodes list` 查看状态。 + - 使用 `openclaw nodes status` / `openclaw nodes list` 查看它。 - 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 + 文档：[节点](/zh-CN/nodes)、[节点 CLI](/cli/nodes)。 - + **不推荐**使用 Bun。我们观察到运行时 bug，尤其是在 WhatsApp 和 Telegram 上。 - 稳定的 Gateway 网关请使用 **Node**。 + 稳定运行的 Gateway 网关请使用 **Node**。 - 如果你仍然想尝试 Bun，请仅在非生产 Gateway 网关上 - 且不要搭配 WhatsApp/Telegram 使用。 + 如果你仍然想尝试 Bun，请在非生产 Gateway 网关上 + 进行，并且不要启用 WhatsApp / Telegram。 - - `channels.telegram.allowFrom` 填的是**人工发送者的 Telegram 用户 ID**（数字）。 + + `channels.telegram.allowFrom` 是**真人发送者的 Telegram 用户 ID**（数字）。 它不是机器人用户名。 - 新手引导接受 `@username` 输入，并会将其解析为数字 ID，但 OpenClaw 授权只使用数字 ID。 + 新手引导接受 `@username` 输入并将其解析为数字 ID，但 OpenClaw 的授权只使用数字 ID。 - 更安全的方式（无需第三方机器人）： + 更安全的做法（无需第三方机器人）： - 给你的机器人发私信，然后运行 `openclaw logs --follow` 并读取 `from.id`。 @@ -768,26 +785,25 @@ x-i18n: - 给你的机器人发私信，然后调用 `https://api.telegram.org/bot/getUpdates` 并读取 `message.from.id`。 - 第三方方式（隐私性较低）： + 第三方方式（隐私性较差）： - - 给 `@userinfobot` 或 `@getidsbot` 发私信。 + - 向 `@userinfobot` 或 `@getidsbot` 发送私信。 - 参阅 [/channels/telegram](/zh-CN/channels/telegram#access-control-and-activation)。 + 参见 [/channels/telegram](/zh-CN/channels/telegram#access-control-and-activation)。 - + 可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信** - （peer `kind: "direct"`，发送者 E.164 例如 `+15551234567`）绑定到不同的 `agentId`， - 这样每个人都会拥有自己的工作区和会话存储。回复仍然来自**同一个 WhatsApp 账号**，而私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）在整个 WhatsApp 账号层面是全局的。参阅 [Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。 + （peer `kind: "direct"`，发送者 E.164 格式如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都有自己的工作区和会话存储。回复仍然会来自**同一个 WhatsApp 账户**，而私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）则在该 WhatsApp 账户级别全局生效。参见 [多智能体路由](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。 - - 可以。使用多智能体路由：为每个智能体设置其各自的默认模型，然后将入站路由（提供商账号或特定 peer）绑定到各个智能体。示例配置见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。另请参阅 [Models](/zh-CN/concepts/models) 和 [Configuration](/zh-CN/gateway/configuration)。 + + 可以。使用多智能体路由：为每个智能体设置各自的默认模型，然后将入站路由（提供商账户或特定 peer）绑定到各自智能体。示例配置位于 [多智能体路由](/zh-CN/concepts/multi-agent)。另请参见 [模型](/zh-CN/concepts/models) 和 [配置](/zh-CN/gateway/configuration)。 - - 可以。Homebrew 支持 Linux（Linuxbrew）。快速设置： + + 可以。Homebrew 支持 Linux（Linuxbrew）。快速设置如下： ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" @@ -796,25 +812,25 @@ x-i18n: brew install ``` - 如果你通过 systemd 运行 OpenClaw，请确保服务的 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样 `brew` 安装的工具才能在非登录 shell 中被解析。 - 最近的构建也会在 Linux systemd 服务中预置常见用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在设置时遵循 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。 + 如果你通过 systemd 运行 OpenClaw，请确保服务 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样 `brew` 安装的工具就能在非登录 shell 中被解析。 + 最近的构建还会在 Linux systemd 服务中预置常见用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在设置时遵循 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。 - - - **可修改的（git）安装：**完整源码检出、可编辑，最适合贡献者。 - 你需要在本地构建，并可修改代码/文档。 + + - **Hackable（git）安装：**完整源码检出，可编辑，最适合贡献者。 + 你需要在本地运行构建，并可以修改代码 / 文档。 - **npm install：**全局 CLI 安装，没有仓库，最适合“直接运行”。 更新来自 npm dist-tag。 - 文档：[入门指南](/zh-CN/start/getting-started)、[Updating](/zh-CN/install/updating)。 + 文档：[入门指南](/zh-CN/start/getting-started)、[更新](/zh-CN/install/updating)。 - - 可以。安装另一种形式后，运行 Doctor，使 gateway 服务指向新的入口点。 - 这**不会删除你的数据**——它只会更改 OpenClaw 代码安装。你的状态 - （`~/.openclaw`）和工作区（`~/.openclaw/workspace`）都不会被触碰。 + + 可以。安装另一种方式后，运行 Doctor，让 Gateway 网关服务指向新的入口点。 + 这**不会删除你的数据**——它只会更改 OpenClaw 代码安装方式。你的状态 + （`~/.openclaw`）和工作区（`~/.openclaw/workspace`）会保持不变。 从 npm 切换到 git： @@ -835,223 +851,220 @@ x-i18n: openclaw gateway restart ``` - Doctor 会检测 gateway 服务入口点不匹配，并提供重写服务配置以匹配当前安装的选项（在自动化中使用 `--repair`）。 + Doctor 会检测 Gateway 网关服务入口点不匹配，并提供将服务配置重写为匹配当前安装的选项（在自动化中使用 `--repair`）。 - 备份建议：参阅 [备份策略](#where-things-live-on-disk)。 + 备份建议：参见 [备份策略](#where-things-live-on-disk)。 - - 简短回答：**如果你想要 24/7 的可靠性，就用 VPS**。如果你想要 - 最低使用门槛，并且能接受睡眠/重启，那么就在本地运行。 + + 简短回答：**如果你想要 24 / 7 可靠性，就用 VPS**。如果你更在意 + 最低摩擦，并且能接受休眠 / 重启，那就在本地运行。 - **笔记本电脑（本地 Gateway 网关）** + **笔记本（本地 Gateway 网关）** - - **优点：**没有服务器成本，可直接访问本地文件，有可见的浏览器窗口。 - - **缺点：**睡眠/网络中断 = 断连，操作系统更新/重启会打断运行，必须保持唤醒。 + - **优点：**无需服务器成本，直接访问本地文件，可见的浏览器窗口。 + - **缺点：**休眠 / 网络中断 = 连接断开，操作系统更新 / 重启会中断，必须保持唤醒。 - **VPS / 云端** + **VPS / 云** - - **优点：**始终在线，网络稳定，没有笔记本睡眠问题，更容易长期运行。 - - **缺点：**通常是无头运行（使用截图），只能远程访问文件，更新时必须通过 SSH。 + - **优点：**常开、网络稳定、没有笔记本休眠问题、更容易持续运行。 + - **缺点：**通常是无头运行（需使用截图），只能远程访问文件，你必须通过 SSH 更新。 - **OpenClaw 特定说明：**WhatsApp/Telegram/Slack/Mattermost/Discord 都可以在 VPS 上良好运行。真正的取舍只有**无头浏览器**与**可见窗口**。参阅 [Browser](/zh-CN/tools/browser)。 + **OpenClaw 特定说明：**WhatsApp / Telegram / Slack / Mattermost / Discord 都能在 VPS 上正常工作。唯一真正的权衡是**无头浏览器**与可见窗口之间的差异。参见 [浏览器](/zh-CN/tools/browser)。 - **推荐默认方案：**如果你之前遇到过 gateway 断连，优先用 VPS。本地运行非常适合你正在积极使用 Mac、并希望访问本地文件或通过可见浏览器进行 UI 自动化的场景。 + **推荐默认方案：**如果你之前遇到过 Gateway 网关断连，请使用 VPS。本地运行非常适合你在积极使用 Mac，并希望访问本地文件或使用可见浏览器进行 UI 自动化的情况。 - - 不是必须，但为了可靠性和隔离性，**推荐这样做**。 + + 不是必需的，但**出于可靠性和隔离考虑，推荐这样做**。 - - **专用主机（VPS/Mac mini/Pi）：**始终在线，更少睡眠/重启中断，权限更清晰，更容易持续运行。 - - **共享笔记本/台式机：**非常适合测试和活跃使用，但要预期机器睡眠或更新时会暂停。 + - **专用主机（VPS / Mac mini / Pi）：**常开，较少受到休眠 / 重启影响，权限更干净，更容易持续运行。 + - **共享笔记本 / 台式机：**完全适合测试和日常主动使用，但当机器休眠或更新时，预计会有暂停。 - 如果你想兼顾两者，请把 Gateway 网关放在专用主机上，并把你的笔记本配对为一个**节点**，用于本地屏幕/摄像头/exec 工具。参阅 [Nodes](/zh-CN/nodes)。 - 关于安全指南，请阅读 [Security](/zh-CN/gateway/security)。 + 如果你想两全其美，可以将 Gateway 网关放在专用主机上，并把你的笔记本配对为**节点**，用于本地屏幕 / 摄像头 / exec 工具。参见 [节点](/zh-CN/nodes)。 + 有关安全指导，请阅读 [安全](/zh-CN/gateway/security)。 - OpenClaw 很轻量。对于一个基础 Gateway 网关 + 一个聊天渠道： + OpenClaw 很轻量。对于基础 Gateway 网关 + 单个聊天渠道： - - **绝对最低配置：**1 vCPU、1 GB RAM、约 500 MB 磁盘。 - - **推荐配置：**1 - 2 vCPU、2 GB RAM 或更高，以留出余量（日志、媒体、多个渠道）。Node 工具和浏览器自动化可能更耗资源。 + - **绝对最低：**1 vCPU、1 GB 内存、约 500 MB 磁盘。 + - **推荐：**1 - 2 vCPU、2 GB 内存或更多余量（用于日志、媒体、多渠道）。Node 工具和浏览器自动化可能比较吃资源。 - 操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在这些系统上测试最充分。 + 操作系统：请使用 **Ubuntu LTS**（或任何现代 Debian / Ubuntu）。Linux 安装路径在这些系统上测试最充分。 - 文档：[Linux](/zh-CN/platforms/linux)、[VPS hosting](/zh-CN/vps)。 + 文档：[Linux](/zh-CN/platforms/linux)、[VPS 托管](/zh-CN/vps)。 - - 可以。请将虚拟机视为 VPS：它需要始终在线、可被访问，并且拥有足够的 - RAM 来运行 Gateway 网关和你启用的任何渠道。 + + 可以。将 VM 视为 VPS：它需要始终在线、可访问，并且有足够的 + 内存供 Gateway 网关和你启用的任何渠道使用。 基线建议： - - **绝对最低配置：**1 vCPU、1 GB RAM。 - - **推荐配置：**如果你运行多个渠道、浏览器自动化或媒体工具，则建议 2 GB RAM 或更多。 - - **操作系统：**Ubuntu LTS 或其他现代 Debian/Ubuntu。 + - **绝对最低：**1 vCPU、1 GB 内存。 + - **推荐：**如果运行多个渠道、浏览器自动化或媒体工具，建议 2 GB 内存或更多。 + - **操作系统：**Ubuntu LTS 或其他现代 Debian / Ubuntu。 - 如果你使用 Windows，**WSL2 是最容易的虚拟机式设置**，并且工具兼容性最好。 - 参阅 [Windows](/zh-CN/platforms/windows)、[VPS hosting](/zh-CN/vps)。 - 如果你在虚拟机中运行 macOS，请参阅 [macOS VM](/zh-CN/install/macos-vm)。 + 如果你使用 Windows，**WSL2 是最简单的 VM 风格设置**，并且工具兼容性最好。 + 参见 [Windows](/zh-CN/platforms/windows)、[VPS 托管](/zh-CN/vps)。 + 如果你在 VM 中运行 macOS，请参见 [macOS VM](/zh-CN/install/macos-vm)。 -## 什么是 OpenClaw？ +## OpenClaw 是什么？ - - OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息界面上回复你（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及像 QQ Bot 这样的内置渠道插件），并且在支持的平台上还可以提供语音 + 实时画布。**Gateway 网关**是始终在线的控制平面；助手本身才是产品。 + + OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息界面上回复你（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及像 QQ Bot 这样的内置渠道插件），并且在受支持的平台上还可以提供语音 + 实时 Canvas。**Gateway 网关**是始终在线的控制平面；这个助手本身才是产品。 - OpenClaw 不是“只是一个 Claude 包装器”。它是一个**本地优先的控制平面**，让你可以在**自己的硬件上** - 运行一个强大的助手，并通过你已经使用的聊天应用访问它，同时具备 - 有状态会话、记忆和工具——而不必把工作流控制权交给托管型 + OpenClaw 不只是“Claude 包装器”。它是一个**本地优先的控制平面**，让你可以在**自己的硬件**上运行一个强大的助手，通过你已经在使用的聊天应用访问，并且具备有状态的会话、记忆和工具——而无需把你的工作流控制权交给托管式 SaaS。 亮点： - - **你的设备，你的数据：**在任何你想要的地方运行 Gateway 网关（Mac、Linux、VPS），并将 + - **你的设备，你的数据：**可以在任何你想要的地方运行 Gateway 网关（Mac、Linux、VPS），并将 工作区 + 会话历史保留在本地。 - - **真实渠道，而不是 Web 沙箱：**WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， + - **真实渠道，而非 Web 沙箱：**WhatsApp / Telegram / Slack / Discord / Signal / iMessage 等， 以及在受支持平台上的移动语音和 Canvas。 - - **与模型无关：**使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 - 及故障切换。 - - **纯本地选项：**运行本地模型，这样**所有数据都可以保留在你的设备上**。 - - **多智能体路由：**按渠道、账号或任务拆分不同智能体，每个都有自己的 - 工作区和默认设置。 - - **开源且可改造：**可检查、扩展并自行托管，无供应商锁定。 + - **模型无关：**使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 + 和故障切换。 + - **仅本地选项：**运行本地模型，这样**所有数据都可以保留在你的设备上**。 + - **多智能体路由：**按渠道、账户或任务拆分智能体，每个智能体拥有自己的 + 工作区和默认值。 + - **开源且可修改：**可检查、扩展并自托管，无厂商锁定。 - 文档：[Gateway](/zh-CN/gateway)、[Channels](/zh-CN/channels)、[Multi-agent](/zh-CN/concepts/multi-agent)、 - [Memory](/zh-CN/concepts/memory)。 + 文档：[Gateway 网关](/zh-CN/gateway)、[渠道](/zh-CN/channels)、[多智能体](/zh-CN/concepts/multi-agent)、 + [记忆](/zh-CN/concepts/memory)。 - - 很适合作为第一个项目的内容： + + 适合作为起步的项目： - - 搭建网站（WordPress、Shopify，或简单静态站点）。 - - 制作移动应用原型（大纲、界面、API 计划）。 + - 搭建一个网站（WordPress、Shopify 或简单静态站点）。 + - 原型设计一个移动应用（大纲、界面、API 计划）。 - 整理文件和文件夹（清理、命名、打标签）。 - - 连接 Gmail 并自动生成摘要或跟进事项。 + - 连接 Gmail 并自动生成摘要或后续跟进。 它可以处理大型任务，但当你把任务拆分成多个阶段，并 - 使用子智能体并行工作时，效果通常最好。 + 使用子智能体并行工作时，效果最好。 - - 日常收益通常体现在： + + 日常高价值场景通常包括： - - **个人简报：**总结你的收件箱、日历以及你关心的新闻。 - - **研究和起草：**快速研究、总结，以及为邮件或文档生成初稿。 - - **提醒和跟进：**由 cron 或 heartbeat 驱动的提醒和清单。 - - **浏览器自动化：**填写表单、收集数据、重复执行网页任务。 - - **跨设备协作：**从手机发送任务，让 Gateway 网关在服务器上运行，然后在聊天中收到结果。 + - **个人简报：**汇总你关心的收件箱、日历和新闻。 + - **研究与起草：**快速研究、总结，以及邮件或文档的初稿。 + - **提醒与跟进：**由 cron 或 heartbeat 驱动的提醒和清单。 + - **浏览器自动化：**填写表单、收集数据、重复执行 Web 任务。 + - **跨设备协作：**在手机上发出任务，让 Gateway 网关在服务器上执行，然后把结果发回聊天。 - 对于**研究、资格筛选和起草**，可以。它可以扫描网站、建立候选名单、 - 总结潜在客户，并撰写外联文案或广告文案草稿。 + 可以用于**研究、筛选和起草**。它可以扫描网站、建立候选清单、 + 总结潜在客户，并撰写外联或广告文案草稿。 - 对于**外联或广告投放**，请保持人工参与。避免垃圾信息，遵守当地法律和 + 但对于**外联或广告投放**，请务必让人工参与。避免垃圾信息，遵守当地法律和 平台政策，并在发送前审查所有内容。最安全的模式是让 OpenClaw 起草，由你审批。 - 文档：[Security](/zh-CN/gateway/security)。 + 文档：[安全](/zh-CN/gateway/security)。 - - OpenClaw 是一个**个人助手**和协调层，而不是 IDE 替代品。对于仓库内最快的直接编码循环， - 请使用 Claude Code 或 Codex。使用 OpenClaw 的场景是，当你 - 需要持久记忆、跨设备访问和工具编排时。 + + OpenClaw 是一个**个人助手**和协作层，而不是 IDE 替代品。在仓库内进行最快的直接编码循环时， + 请使用 Claude Code 或 Codex。当你 + 需要持久记忆、跨设备访问和工具编排时，请使用 OpenClaw。 优势： - - **持久记忆 + 工作区**，跨会话保留 + - **跨会话的持久记忆 + 工作区** - **多平台访问**（WhatsApp、Telegram、TUI、WebChat） - **工具编排**（浏览器、文件、调度、hooks） - - **始终在线的 Gateway 网关**（运行在 VPS 上，从任何地方交互） - - 通过 **Nodes** 实现本地浏览器/屏幕/摄像头/exec + - **始终在线的 Gateway 网关**（可运行在 VPS 上，随处交互） + - 用于本地浏览器 / 屏幕 / 摄像头 / exec 的**节点** 展示页：[https://openclaw.ai/showcase](https://openclaw.ai/showcase) -## Skills 和自动化 +## Skills 与自动化 - - 使用托管覆盖，而不是编辑仓库副本。把你的修改放到 `~/.openclaw/skills//SKILL.md` 中（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加一个文件夹）。优先级顺序为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此托管覆盖仍然会优先于内置 Skills，而无需触碰 git。如果你需要全局安装某个 skill，但只希望某些智能体可见，请将共享副本保存在 `~/.openclaw/skills` 中，并通过 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有真正值得上游合并的修改才应保存在仓库中并通过 PR 提交。 + + 使用托管覆盖，而不是编辑仓库副本。将你的更改放到 `~/.openclaw/skills//SKILL.md` 中（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加文件夹）。优先级为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此托管覆盖仍会在不修改 git 的情况下覆盖内置 skills。如果你需要全局安装某个 skill，但只希望部分智能体可见，请将共享副本放在 `~/.openclaw/skills` 中，并通过 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游合并的更改才应该保留在仓库里并以 PR 形式提交。 - - 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一个会话中将其视为 `/skills`。如果某个 skill 只应对特定智能体可见，请搭配 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 + + 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一次会话中将其视为 `/skills`。如果该 skill 只应对特定智能体可见，请同时搭配 `agents.defaults.skills` 或 `agents.list[].skills`。 当前支持的模式有： - - **Cron 任务**：隔离作业可为每个作业设置 `model` 覆盖。 - - **子智能体**：将任务路由到默认模型不同的独立智能体。 - - **按需切换**：使用 `/model` 随时切换当前会话模型。 + - **Cron 任务**：隔离任务可为每个任务设置 `model` 覆盖。 + - **子智能体**：将任务路由到拥有不同默认模型的独立智能体。 + - **按需切换**：随时使用 `/model` 切换当前会话模型。 - 参阅 [Cron jobs](/zh-CN/automation/cron-jobs)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [Slash commands](/zh-CN/tools/slash-commands)。 + 参见 [Cron 任务](/zh-CN/automation/cron-jobs)、[多智能体路由](/zh-CN/concepts/multi-agent) 和 [斜杠命令](/zh-CN/tools/slash-commands)。 - - 对长任务或并行任务，请使用**子智能体**。子智能体在自己的会话中运行， - 返回摘要，并保持主聊天保持响应。 + + 对于耗时较长或可并行的任务，请使用**子智能体**。子智能体运行在自己的会话中， + 返回摘要，并保持主聊天响应流畅。 - 你可以让机器人“为这个任务启动一个子智能体”，或者使用 `/subagents`。 - 在聊天中使用 `/status` 可查看 Gateway 网关当前正在做什么（以及它是否繁忙）。 + 你可以要求机器人“为这个任务启动一个子智能体”，或者使用 `/subagents`。 + 使用聊天中的 `/status` 查看 Gateway 网关当前正在做什么（以及它是否繁忙）。 - Token 提示：长任务和子智能体都会消耗 token。如果你在意成本，请通过 `agents.defaults.subagents.model` - 为子智能体设置一个更便宜的模型。 + Token 提示：长任务和子智能体都会消耗 token。如果你关心成本，请通过 `agents.defaults.subagents.model` 为子智能体设置更便宜的模型。 - 文档：[Sub-agents](/zh-CN/tools/subagents)、[Background Tasks](/zh-CN/automation/tasks)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)。 - - 使用线程绑定。你可以将一个 Discord 线程绑定到某个子智能体或会话目标，这样该线程中的后续消息就会持续进入那个绑定的会话。 + + 使用线程绑定。你可以将 Discord 线程绑定到子智能体或会话目标，这样该线程中的后续消息会持续停留在该绑定会话中。 基本流程： - - 使用 `sessions_spawn` 并设置 `thread: true` 启动（如果希望持续跟进，也可设置 `mode: "session"`）。 - - 或者通过 `/focus ` 手动绑定。 + - 使用 `sessions_spawn` 启动并设置 `thread: true`（以及可选的 `mode: "session"`，用于持久后续跟进）。 + - 或通过 `/focus ` 手动绑定。 - 使用 `/agents` 检查绑定状态。 - 使用 `/session idle ` 和 `/session max-age ` 控制自动取消聚焦。 - 使用 `/unfocus` 解除线程绑定。 - 所需配置： + 必需配置： - - 全局默认：`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 + - 全局默认值：`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 - Discord 覆盖：`channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`。 - 在 spawn 时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 - 文档：[Sub-agents](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[Configuration Reference](/zh-CN/gateway/configuration-reference)、[Slash commands](/zh-CN/tools/slash-commands)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[配置参考](/zh-CN/gateway/configuration-reference)、[斜杠命令](/zh-CN/tools/slash-commands)。 - - 先检查解析出的请求方路由： + + 先检查解析后的请求方路由： - - 完成模式下的子智能体投递会优先使用任何已绑定的线程或会话路由（如果存在）。 - - 如果完成来源只携带了一个渠道，OpenClaw 会退回到请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），以便直接投递仍然可以成功。 - - 如果既没有绑定路由，也没有可用的存储路由，则直接投递可能失败，结果会退回到排队的会话投递，而不是立即发到聊天中。 + - 完成模式下的子智能体投递会优先使用任何已绑定的线程或对话路由。 + - 如果完成来源仅携带渠道，OpenClaw 会退回到请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），这样直接投递仍可能成功。 + - 如果既不存在绑定路由，也没有可用的存储路由，直接投递可能失败，结果会退回到排队的会话投递，而不是立即发送到聊天。 - 无效或过时的目标仍可能导致退回到队列，或最终投递失败。 - - 如果子任务最后一个可见的助手回复正好是静默令牌 `NO_REPLY` / `no_reply`，或正好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发布先前的陈旧进度。 - - 如果子任务在仅执行工具调用后超时，则公告可能会将其压缩成一个简短的部分进度摘要，而不是回放原始工具输出。 + - 如果子会话中最后一条可见的 assistant 回复是完全静默 token `NO_REPLY` / `no_reply`，或恰好为 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发布更早的过时进度。 + - 如果子任务只进行了工具调用后就超时，公告可能会将其折叠为简短的部分进度摘要，而不是回放原始工具输出。 调试： @@ -1059,19 +1072,19 @@ x-i18n: openclaw tasks show ``` - 文档：[Sub-agents](/zh-CN/tools/subagents)、[Background Tasks](/zh-CN/automation/tasks)、[Session Tools](/zh-CN/concepts/session-tool)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)、[会话工具](/zh-CN/concepts/session-tool)。 Cron 在 Gateway 网关进程内部运行。如果 Gateway 网关没有持续运行， - 定时任务就不会执行。 + 已计划的任务就不会执行。 检查清单： - 确认 cron 已启用（`cron.enabled`），并且未设置 `OPENCLAW_SKIP_CRON`。 - - 检查 Gateway 网关是否正在 24/7 持续运行（没有睡眠/重启）。 - - 验证任务的时区设置（`--tz` 与主机时区）。 + - 检查 Gateway 网关是否 24 / 7 运行（无休眠 / 重启）。 + - 验证任务时区设置（`--tz` 与主机时区）。 调试： @@ -1080,22 +1093,22 @@ x-i18n: openclaw cron runs --id --limit 50 ``` - 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Automation & Tasks](/zh-CN/automation)。 + 文档：[Cron 任务](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)。 - + 先检查投递模式： - - `--no-deliver` / `delivery.mode: "none"` 表示不期望任何外部消息。 - - 缺失或无效的公告目标（`channel` / `to`）意味着运行器跳过了对外投递。 - - 渠道认证失败（`unauthorized`、`Forbidden`）意味着运行器尝试投递了，但凭据阻止了它。 - - 静默的隔离结果（只有 `NO_REPLY` / `no_reply`）会被视为有意不投递，因此运行器也会抑制排队回退投递。 + - `--no-deliver` / `delivery.mode: "none"` 表示不期望有任何外部消息。 + - 缺失或无效的公告目标（`channel` / `to`）表示运行器跳过了出站投递。 + - 渠道凭证失败（`unauthorized`、`Forbidden`）表示运行器尝试了投递，但凭证阻止了它。 + - 静默的隔离结果（只有 `NO_REPLY` / `no_reply`）会被视为有意不可投递，因此运行器也会抑制排队的回退投递。 - 对于隔离的 cron 作业，最终投递由运行器负责。系统期望 - 智能体返回一段纯文本摘要供运行器发送。`--no-deliver` 会让 - 该结果只保留在内部；它并不会让智能体改为直接通过 - message 工具发送。 + 对于隔离的 cron 任务，运行器负责最终投递。智能体应当 + 返回纯文本摘要，供运行器发送。`--no-deliver` 会让 + 该结果保持内部状态；它并不会让智能体改为通过 + message 工具直接发送。 调试： @@ -1104,26 +1117,26 @@ x-i18n: openclaw tasks show ``` - 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Background Tasks](/zh-CN/automation/tasks)。 + 文档：[Cron 任务](/zh-CN/automation/cron-jobs)、[后台任务](/zh-CN/automation/tasks)。 - + 这通常是实时模型切换路径，而不是重复调度。 - 隔离的 cron 在活动运行抛出 `LiveSessionModelSwitchError` 时， - 可以持久化一个运行时模型切换并重试。重试会保留切换后的 - 提供商/模型；如果切换中带有新的认证档案覆盖，cron + 隔离的 cron 可以在活动运行抛出 `LiveSessionModelSwitchError` 时， + 持久化一个运行时模型切换并进行重试。该重试会保留切换后的 + 提供商 / 模型，如果这次切换携带了新的凭证配置文件覆盖，cron 也会在重试前将其持久化。 相关选择规则： - - 如果适用，Gmail hook 模型覆盖优先级最高。 - - 然后是每个作业的 `model`。 - - 然后是任何已存储的 cron 会话模型覆盖。 - - 最后才是正常的智能体/默认模型选择。 + - 适用时，Gmail hook 模型覆盖优先级最高。 + - 其次是每个任务的 `model`。 + - 再其次是任何存储的 cron 会话模型覆盖。 + - 最后是正常的智能体 / 默认模型选择。 - 重试循环是有界的。在初始尝试加上 2 次切换重试之后， + 重试循环是有界的。初次尝试加上 2 次切换重试之后， cron 会中止，而不是无限循环。 调试： @@ -1133,13 +1146,13 @@ x-i18n: openclaw tasks show ``` - 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[cron CLI](/cli/cron)。 + 文档：[Cron 任务](/zh-CN/automation/cron-jobs)、[cron CLI](/cli/cron)。 - 使用原生 `openclaw skills` 命令，或直接将 Skills 放入你的工作区。macOS Skills UI 在 Linux 上不可用。 - 浏览 Skills： [https://clawhub.ai](https://clawhub.ai)。 + 使用原生 `openclaw skills` 命令，或将 skills 放入你的工作区。macOS Skills UI 在 Linux 上不可用。 + 可在 [https://clawhub.ai](https://clawhub.ai) 浏览 skills。 ```bash openclaw skills search "calendar" @@ -1153,40 +1166,39 @@ x-i18n: ``` 原生 `openclaw skills install` 会写入当前工作区的 `skills/` - 目录。只有当你想发布或 - 同步你自己的 Skills 时，才需要另外安装 `clawhub` CLI。对于跨智能体共享安装，请把 skill 放到 - `~/.openclaw/skills` 下，并在你想缩小可见范围时使用 `agents.defaults.skills` 或 - `agents.list[].skills`。 + 目录。只有当你想发布或同步自己的 skills 时，才需要安装单独的 `clawhub` CLI。对于跨智能体共享安装，请将 skill 放在 + `~/.openclaw/skills` 下，并使用 `agents.defaults.skills` 或 + `agents.list[].skills` 来缩小哪些智能体可见它。 - + 可以。使用 Gateway 网关调度器： - - **Cron jobs** 用于定时或周期性任务（跨重启持久化）。 - - **Heartbeat** 用于“主会话”的周期性检查。 - - **隔离作业** 用于自主智能体，它们会发布摘要或投递到聊天中。 + - **Cron 任务**：用于计划任务或周期性任务（重启后仍会保留）。 + - **Heartbeat**：用于“主会话”的周期性检查。 + - **隔离任务**：用于自主智能体，可发布摘要或投递到聊天。 - 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Automation & Tasks](/zh-CN/automation)、 + 文档：[Cron 任务](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)、 [Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件控制，且只有在它们对**Gateway 主机**满足条件时，Skills 才会出现在系统提示中。在 Linux 上，仅限 `darwin` 的 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖这种限制。 + + 不能直接运行。macOS skills 受 `metadata.openclaw.os` 以及所需二进制文件控制，只有在 **Gateway 网关主机** 上符合条件时，这些 skills 才会出现在 system prompt 中。在 Linux 上，`darwin` 专属 skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖这些限制。 你有三种受支持的模式： - **选项 A - 在 Mac 上运行 Gateway 网关（最简单）。** - 在 macOS 二进制文件所在的地方运行 Gateway 网关，然后从 Linux 通过 [remote mode](#gateway-ports-already-running-and-remote-mode) 或 Tailscale 连接。由于 Gateway 主机是 macOS，这些 Skills 会正常加载。 + **方案 A：在 Mac 上运行 Gateway 网关（最简单）。** + 在具备 macOS 二进制文件的机器上运行 Gateway 网关，然后通过 [远程模式](#gateway-ports-already-running-and-remote-mode) 或 Tailscale 从 Linux 连接。由于 Gateway 网关主机是 macOS，这些 skills 会正常加载。 - **选项 B - 使用 macOS 节点（无需 SSH）。** - 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并将 Mac 上的**Node Run Commands** 设为 “Always Ask” 或 “Always Allow”。当节点上存在所需二进制文件时，OpenClaw 可以将这些仅限 macOS 的 Skills 视为可用。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择 “Always Ask”，并在提示中批准 “Always Allow”，该命令就会被加入允许列表。 + **方案 B：使用 macOS 节点（无需 SSH）。** + 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设置为 “Always Ask” 或 “Always Allow”。当所需二进制文件存在于该节点上时，OpenClaw 可以将这些仅限 macOS 的 skills 视为可用。智能体会通过 `nodes` 工具运行这些 skills。如果你选择 “Always Ask”，在提示中批准 “Always Allow” 会将该命令加入允许列表。 - **选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。** - Gateway 网关保留在 Linux 上，但让所需的 CLI 二进制文件解析为在 Mac 上执行的 SSH 包装器。然后覆盖该 skill，使其允许 Linux，从而保持其可用。 + **方案 C：通过 SSH 代理 macOS 二进制文件（高级）。** + 将 Gateway 网关保留在 Linux 上，但让所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖该 skill，使其允许 Linux，从而保持可用。 - 1. 为该二进制文件创建一个 SSH 包装器（示例：Apple Notes 的 `memo`）： + 1. 为该二进制文件创建 SSH 包装器（示例：Apple Notes 的 `memo`）： ```bash #!/usr/bin/env bash @@ -1195,7 +1207,7 @@ x-i18n: ``` 2. 将该包装器放到 Linux 主机的 `PATH` 中（例如 `~/bin/memo`）。 - 3. 覆盖 skill 元数据（工作区或 `~/.openclaw/skills`）以允许 Linux： + 3. 覆盖 skill 元数据（工作区或 `~/.openclaw/skills`），以允许 Linux： ```markdown --- @@ -1205,209 +1217,211 @@ x-i18n: --- ``` - 4. 启动一个新会话，以刷新 Skills 快照。 + 4. 启动一个新会话，使 skills 快照刷新。 - + 目前没有内置。 - 选项： + 可选方式： - - **自定义 skill / plugin：**最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 - - **浏览器自动化：**无需写代码，但速度更慢、脆弱性更高。 + - **自定义 skill / 插件：**最适合可靠的 API 访问（Notion / HeyGen 都有 API）。 + - **浏览器自动化：**无需代码，但速度较慢，也更脆弱。 - 如果你想为每个客户保留上下文（例如代理机构工作流），一个简单模式是： + 如果你想为每个客户保留上下文（例如代理机构工作流），一个简单的模式是： - 每个客户一个 Notion 页面（上下文 + 偏好 + 当前工作）。 - - 让智能体在每次会话开始时获取该页面。 + - 让智能体在会话开始时拉取该页面。 - 如果你想要原生集成，请提交功能请求，或者构建一个针对这些 API 的 skill。 + 如果你想要原生集成，请提交功能请求，或构建一个 + 面向这些 API 的 skill。 - 安装 Skills： + 安装 skills： ```bash openclaw skills install openclaw skills update --all ``` - 原生安装会落在当前工作区的 `skills/` 目录中。对于跨智能体共享的 Skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果只有某些智能体应该看到共享安装，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。某些 Skills 需要通过 Homebrew 安装二进制文件；在 Linux 上这意味着 Linuxbrew（参见上面的 Homebrew Linux FAQ 条目）。参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 + 原生安装会进入当前工作区的 `skills/` 目录。对于跨智能体共享的 skills，请将它们放在 `~/.openclaw/skills//SKILL.md` 中。如果共享安装只应对部分智能体可见，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。有些 skills 依赖通过 Homebrew 安装的二进制文件；在 Linux 上这意味着 Linuxbrew（见上面的 Homebrew Linux 常见问题）。参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 - - 使用内置的 `user` 浏览器配置，它会通过 Chrome DevTools MCP 进行连接： + + 使用内置的 `user` 浏览器配置文件，它会通过 Chrome DevTools MCP 连接： ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - 如果你想使用自定义名称，请创建一个显式 MCP 配置： + 如果你想要自定义名称，请创建显式 MCP 配置文件： ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - 这条路径仅适用于本地主机。如果 Gateway 网关运行在别处，那么要么在浏览器所在机器上运行一个节点主机，要么改用远程 CDP。 + 这条路径是主机本地的。如果 Gateway 网关运行在其他地方，请在浏览器所在机器上运行一个节点主机，或改用远程 CDP。 - `existing-session` / `user` 当前限制： + `existing-session` / `user` 当前的限制： - - 操作是基于 ref 驱动，而不是基于 CSS 选择器 + - 操作基于 ref，而不是基于 CSS 选择器 - 上传需要 `ref` / `inputRef`，并且当前一次只支持一个文件 - - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要托管浏览器或原始 CDP 配置 + - `responsebody`、PDF 导出、下载拦截和批量操作仍需要托管浏览器或原始 CDP 配置文件 -## 沙箱隔离和记忆 +## 沙箱隔离与记忆 - - 有。参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。关于 Docker 特定设置（完整 Gateway 网关在 Docker 中运行或沙箱镜像），请参阅 [Docker](/zh-CN/install/docker)。 + + 有。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。对于 Docker 专用设置（Docker 中的完整 gateway 或沙箱镜像），参见 [Docker](/zh-CN/install/docker)。 - - 默认镜像以安全优先方式运行，并使用 `node` 用户，因此它 - 不包含系统软件包、Homebrew 或内置浏览器。若要获得更完整的设置： + + 默认镜像以安全为先，并以 `node` 用户运行，因此它 + 不包含系统包、Homebrew 或内置浏览器。若要获得更完整的设置： - - 通过 `OPENCLAW_HOME_VOLUME` 持久化 `/home/node`，使缓存得以保留。 + - 使用 `OPENCLAW_HOME_VOLUME` 持久化 `/home/node`，以便缓存得以保留。 - 通过 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像。 - - 通过内置 CLI 安装 Playwright 浏览器： + - 使用内置 CLI 安装 Playwright 浏览器： `node /app/node_modules/playwright-core/cli.js install chromium` - - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径已持久化。 + - 设置 `PLAYWRIGHT_BROWSERS_PATH` 并确保该路径被持久化。 - 文档：[Docker](/zh-CN/install/docker)、[Browser](/zh-CN/tools/browser)。 + 文档：[Docker](/zh-CN/install/docker)、[浏览器](/zh-CN/tools/browser)。 - - 可以——前提是你的私密流量是**私信**，而公开流量是**群组**。 + + 可以——前提是你的私人流量是**私信**，而公开流量是**群组**。 - 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/渠道会话（非主键）会在 Docker 中运行，而主私信会话则保留在主机上。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 + 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组 / 渠道会话（非主键）会在 Docker 中运行，而主私信会话仍在主机上运行。然后通过 `tools.sandbox.tools` 限制沙箱会话中可用的工具。 - 设置演练 + 示例配置：[Groups: personal DMs + public groups](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) + 设置演练 + 示例配置：[群组：私人私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) - 关键配置参考：[Gateway configuration](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) + 关键配置参考：[Gateway 网关配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) - 将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局和每智能体 bind 会合并；当 `scope: "shared"` 时，每智能体 bind 会被忽略。对任何敏感内容请使用 `:ro`，并记住 bind 会绕过沙箱文件系统边界。 + 将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局绑定与按智能体绑定会合并；当 `scope: "shared"` 时，会忽略按智能体绑定。对于任何敏感内容，请使用 `:ro`，并记住绑定会绕过沙箱文件系统边界。 - OpenClaw 会同时依据规范化路径以及通过最深已存在祖先解析出来的规范路径来验证 bind 源。这意味着即便最后一个路径段尚不存在，通过符号链接父级逃逸也会被安全地失败关闭，而且在符号链接解析后，allowed-root 检查仍然会生效。 + OpenClaw 会根据规范化路径以及通过最深层现有祖先解析得到的规范路径，双重验证绑定源。这意味着即使最后一个路径段尚不存在，通过符号链接父目录逃逸也会被默认拒绝，并且在符号链接解析后仍会应用允许根路径检查。 - 关于示例和安全说明，请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 + 示例与安全说明请参见 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 - OpenClaw 的记忆其实就是智能体工作区中的 Markdown 文件： + OpenClaw 的记忆就是智能体工作区中的 Markdown 文件： - `memory/YYYY-MM-DD.md` 中的每日笔记 - - `MEMORY.md` 中整理过的长期笔记（仅主/私密会话） + - `MEMORY.md` 中整理过的长期笔记（仅主 / 私有会话） - OpenClaw 还会运行一个**静默的预压缩记忆刷新**，提醒模型 - 在自动压缩前写下持久笔记。这只会在工作区可写时运行 - （只读沙箱会跳过）。参阅 [Memory](/zh-CN/concepts/memory)。 + OpenClaw 还会运行一个**静默的压缩前记忆刷新**，提醒模型 + 在自动压缩前写入持久笔记。它只会在工作区 + 可写时运行（只读沙箱会跳过）。参见 [记忆](/zh-CN/concepts/memory)。 - 让机器人**把事实写入记忆**。长期笔记应放在 `MEMORY.md` 中， - 短期上下文则放在 `memory/YYYY-MM-DD.md` 中。 + 请让机器人**把事实写入记忆**。长期笔记应写入 `MEMORY.md`， + 短期上下文则写入 `memory/YYYY-MM-DD.md`。 - 这是我们仍在持续改进的领域。提醒模型存储记忆会有帮助； - 它知道该怎么做。如果它仍然总忘记，请确认 Gateway 网关每次运行时都在使用同一个 + 这仍然是我们正在改进的领域。提醒模型存储记忆会有帮助； + 它会知道该怎么做。如果它仍然经常遗忘，请确认 Gateway 网关每次运行时都在使用同一个 工作区。 - 文档：[Memory](/zh-CN/concepts/memory)、[Agent workspace](/zh-CN/concepts/agent-workspace)。 + 文档：[记忆](/zh-CN/concepts/memory)、[智能体工作区](/zh-CN/concepts/agent-workspace)。 - 记忆文件保存在磁盘上，会一直存在，直到你删除它们。限制来自你的 - 存储空间，而不是模型。**会话上下文** - 仍然受模型上下文窗口限制，因此长对话可能会被压缩或截断。这就是为什么 - 有记忆搜索——它只会把相关部分重新拉回到上下文中。 + 记忆文件存储在磁盘上，并会一直保留，直到你删除它们。限制来自你的 + 存储空间，而不是模型。**会话上下文**仍然受模型 + 上下文窗口限制，因此长对话可能会被压缩或截断。这也是为什么会有 + 记忆搜索——它只会把相关部分重新拉回上下文。 - 文档：[Memory](/zh-CN/concepts/memory)、[Context](/zh-CN/concepts/context)。 + 文档：[记忆](/zh-CN/concepts/memory)、[上下文](/zh-CN/concepts/context)。 - 只有在你使用**OpenAI embeddings** 时才需要。Codex OAuth 仅涵盖聊天/补全， + 只有当你使用 **OpenAI embeddings** 时才需要。Codex OAuth 只覆盖聊天 / completions， **不**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 - Codex CLI 登录）**对语义记忆搜索没有帮助。OpenAI embeddings + Codex CLI 登录）**并不能帮助启用语义记忆搜索。OpenAI embeddings 仍然需要真实的 API 密钥（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 - 如果你没有显式设置提供商，只要它 - 能解析出 API 密钥，OpenClaw 就会自动选择一个提供商（认证档案、`models.providers.*.apiKey` 或环境变量）。 - 如果能解析出 OpenAI 密钥，它会优先选择 OpenAI；否则如果能解析出 Gemini 密钥， - 就选择 Gemini；然后是 Voyage，再然后是 Mistral。如果没有可用的远程密钥， - 记忆搜索会保持禁用状态，直到你完成配置。如果你已经配置并存在本地模型路径，OpenClaw - 会优先使用 `local`。只有在你显式设置 - `memorySearch.provider = "ollama"` 时，才支持 Ollama。 + 如果你没有显式设置提供商，只要 OpenClaw + 能解析出 API 密钥（凭证配置文件、`models.providers.*.apiKey` 或环境变量），它就会自动选择提供商。 + 如果能解析出 OpenAI 密钥，它会优先选择 OpenAI；否则如果能解析出 Gemini 密钥，则使用 Gemini； + 再之后是 Voyage，然后是 Mistral。如果没有可用的远程密钥，记忆 + 搜索会保持禁用，直到你进行配置。如果你已经配置了本地模型路径 + 并且该路径存在，OpenClaw + 会优先选择 `local`。当你显式设置 + `memorySearch.provider = "ollama"` 时，也支持 Ollama。 - 如果你更倾向于保持本地化，请设置 `memorySearch.provider = "local"`（并可选设置 + 如果你更想保持本地化，请设置 `memorySearch.provider = "local"`（并可选设置 `memorySearch.fallback = "none"`）。如果你想使用 Gemini embeddings，请设置 `memorySearch.provider = "gemini"` 并提供 `GEMINI_API_KEY`（或 - `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或 local** embedding - 模型——设置细节参见 [Memory](/zh-CN/concepts/memory)。 + `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或 local** + embedding 模型——设置详情请参见 [记忆](/zh-CN/concepts/memory)。 -## 磁盘上的存储位置 +## 磁盘上的文件位置 - - 不会——**OpenClaw 的状态保存在本地**，但**外部服务仍然会看到你发给它们的内容**。 + + 不是——**OpenClaw 的状态保存在本地**，但**外部服务仍然会看到你发送给它们的内容**。 - - **默认本地：**会话、记忆文件、配置和工作区都保存在 Gateway 网关主机上 + - **默认本地：**会话、记忆文件、配置和工作区位于 Gateway 网关主机上 （`~/.openclaw` + 你的工作区目录）。 - - **必须远程：**你发送给模型提供商（Anthropic/OpenAI 等）的消息会进入 - 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会在 + - **因需要而远程：**你发送给模型提供商（Anthropic / OpenAI / 等）的消息会发送到 + 它们的 API，聊天平台（WhatsApp / Telegram / Slack / 等）也会在 它们的服务器上存储消息数据。 - - **你可以控制暴露范围：**使用本地模型会让提示保留在你的机器上，但渠道 - 流量仍然会通过对应渠道的服务器。 + - **足迹由你控制：**使用本地模型可将 prompts 保留在你的机器上，但渠道 + 流量仍会经过相应渠道的服务器。 - 相关内容：[Agent workspace](/zh-CN/concepts/agent-workspace)、[Memory](/zh-CN/concepts/memory)。 + 相关内容：[智能体工作区](/zh-CN/concepts/agent-workspace)、[记忆](/zh-CN/concepts/memory)。 所有内容都位于 `$OPENCLAW_STATE_DIR` 下（默认：`~/.openclaw`）： - | 路径 | 用途 | - | --------------------------------------------------------------- | ----------------------------------------------------------------- | - | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到认证档案中） | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 认证档案（OAuth、API 密钥，以及可选的 `keyRef`/`tokenRef`） | - | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef 提供商可选的基于文件的 secret 负载 | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目已清理） | - | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp//creds.json`） | - | `$OPENCLAW_STATE_DIR/agents/` | 每智能体状态（agentDir + sessions） | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史和状态（按智能体区分） | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体区分） | + | Path | Purpose | + | --------------------------------------------------------------- | ------------------------------------------------------------------ | + | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到凭证配置文件） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 凭证配置文件（OAuth、API 密钥，以及可选的 `keyRef` / `tokenRef`） | + | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef 提供商的可选文件后备密钥载荷 | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目已清除） | + | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp//creds.json`） | + | `$OPENCLAW_STATE_DIR/agents/` | 每个智能体的状态（agentDir + sessions） | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史与状态（每个智能体） | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（每个智能体） | 旧版单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 - 你的**工作区**（AGENTS.md、记忆文件、Skills 等）是分开的，通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 + 你的**工作区**（AGENTS.md、记忆文件、skills 等）是独立的，并通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 这些文件位于**智能体工作区**中，而不是 `~/.openclaw`。 - - **工作区（按智能体）：**`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 - `MEMORY.md`（如果缺少 `MEMORY.md`，则使用旧版回退 `memory.md`）、 + - **工作区（按智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 + `MEMORY.md`（若无 `MEMORY.md` 则回退到旧版 `memory.md`）、 `memory/YYYY-MM-DD.md`、可选的 `HEARTBEAT.md`。 - - **状态目录（`~/.openclaw`）：**配置、渠道/提供商状态、认证档案、会话、日志， - 以及共享 Skills（`~/.openclaw/skills`）。 + - **状态目录（`~/.openclaw`）**：配置、渠道 / 提供商状态、凭证配置文件、会话、日志， + 以及共享 skills（`~/.openclaw/skills`）。 - 默认工作区为 `~/.openclaw/workspace`，可通过以下方式配置： + 默认工作区是 `~/.openclaw/workspace`，可通过以下方式配置： ```json5 { @@ -1415,44 +1429,44 @@ x-i18n: } ``` - 如果机器人在重启后“忘记了”东西，请确认 Gateway 网关每次启动时都在使用同一个 - 工作区（并记住：远程模式使用的是**gateway 主机** - 的工作区，而不是你本地笔记本的工作区）。 + 如果机器人在重启后“忘记”了内容，请确认 Gateway 网关在每次启动时都在使用同一个 + 工作区（并记住：远程模式使用的是**Gateway 网关主机上的** + 工作区，而不是你的本地笔记本）。 - 提示：如果你想保留某个持久行为或偏好，请让机器人**把它写进 + 提示：如果你想保留某个持久行为或偏好，请让机器人**将其写入 AGENTS.md 或 MEMORY.md**，而不是依赖聊天历史。 - 参阅 [Agent workspace](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 + 参见 [智能体工作区](/zh-CN/concepts/agent-workspace) 和 [记忆](/zh-CN/concepts/memory)。 - 把你的**智能体工作区**放进一个**私有** git 仓库中，并备份到某个 - 私有位置（例如 GitHub 私有仓库）。这样可以保存记忆 + AGENTS/SOUL/USER - 文件，也让你以后可以恢复助手的“思维”。 + 将你的**智能体工作区**放入一个**私有** git 仓库，并备份到某个 + 私有位置（例如 GitHub 私有仓库）。这样可以保留记忆 + AGENTS / SOUL / USER + 文件，并让你以后恢复助手的“心智”。 - **不要**提交 `~/.openclaw` 下的任何内容（凭据、会话、令牌或加密的 secret 负载）。 + **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、token 或加密后的 secrets 载荷）。 如果你需要完整恢复，请分别备份工作区和状态目录 - （见上面的迁移问题）。 + （参见上面的迁移问题）。 - 文档：[Agent workspace](/zh-CN/concepts/agent-workspace)。 + 文档：[智能体工作区](/zh-CN/concepts/agent-workspace)。 - 请参阅专门指南：[Uninstall](/zh-CN/install/uninstall)。 + 请参见专门指南：[卸载](/zh-CN/install/uninstall)。 - 可以。工作区是**默认 cwd** 和记忆锚点，而不是硬性沙箱。 - 相对路径会在工作区内解析，但绝对路径可以访问主机上的其他 - 位置，除非启用了沙箱隔离。如果你需要隔离，请使用 - [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或每个智能体的沙箱设置。如果你 - 希望某个仓库成为默认工作目录，可以把该智能体的 - `workspace` 指向仓库根目录。OpenClaw 仓库只是源码；除非你明确想让智能体在其中工作， - 否则请让工作区与其分离。 + 可以。工作区是**默认 cwd** 和记忆锚点，而不是硬沙箱。 + 相对路径会在工作区内解析，但绝对路径仍可访问其他 + 主机位置，除非启用了沙箱隔离。如果你需要隔离，请使用 + [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或按智能体的沙箱设置。如果你 + 想把某个仓库作为默认工作目录，请将该智能体的 + `workspace` 指向仓库根目录。OpenClaw 仓库只是源代码；除非你有意让智能体在其中工作，否则请将 + 工作区与其分开。 - 示例（以仓库为默认 cwd）： + 示例（将仓库作为默认 cwd）： ```json5 { @@ -1467,29 +1481,29 @@ x-i18n: - 会话状态由**gateway 主机**持有。如果你处于远程模式，那么你关心的会话存储位于远程机器上，而不是你的本地笔记本。参阅 [Session management](/zh-CN/concepts/session)。 + 会话状态归**Gateway 网关主机**所有。如果你处于远程模式，那么你关心的会话存储位于远程机器上，而不是本地笔记本。参见 [会话管理](/zh-CN/concepts/session)。 ## 配置基础 - - OpenClaw 会从 `$OPENCLAW_CONFIG_PATH` 读取一个可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： + + OpenClaw 从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： ``` $OPENCLAW_CONFIG_PATH ``` - 如果该文件不存在，它会使用较为安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 + 如果该文件不存在，它会使用相对安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 - - 非 loopback 绑定**需要一个有效的 gateway 认证路径**。实际来说，这意味着： + + 非 loopback 绑定**要求有效的 gateway auth 路径**。实际上这意味着： - - 共享密钥认证：令牌或密码 - - 在配置正确的非 loopback 身份感知反向代理后使用 `gateway.auth.mode: "trusted-proxy"` + - 共享密钥身份验证：token 或密码 + - 配置正确的非 loopback、具身份感知的反向代理后，使用 `gateway.auth.mode: "trusted-proxy"` ```json5 { @@ -1505,31 +1519,31 @@ x-i18n: 说明： - - `gateway.remote.token` / `.password` **本身不会**启用本地 gateway 认证。 - - 仅当 `gateway.auth.*` 未设置时，本地调用路径才可以将 `gateway.remote.*` 作为回退。 - - 对于密码认证，请改为设置 `gateway.auth.mode: "password"` 加上 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，则解析会失败关闭（不会被远程回退掩盖）。 - - 共享密钥 Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行认证（存储在应用/UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这样的携带身份模式则使用请求头。避免把共享密钥放进 URL 中。 - - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机上的 loopback 反向代理仍然**不能**满足 trusted-proxy 认证要求。trusted proxy 必须是一个已配置的非 loopback 来源。 + - `gateway.remote.token` / `.password` **不会**自行启用本地 gateway 身份验证。 + - 只有在 `gateway.auth.*` 未设置时，本地调用路径才能使用 `gateway.remote.*` 作为回退。 + - 对于密码身份验证，请设置 `gateway.auth.mode: "password"` 加上 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 + - 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析，则会默认拒绝解析（不会用远程回退掩盖）。 + - 共享密钥 Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行身份验证（存储在应用 / UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这样的带身份模式则改用请求头。避免把共享密钥放在 URL 中。 + - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机上的 loopback 反向代理**仍然不会**满足 trusted-proxy 身份验证要求。受信任代理必须是配置好的非 loopback 来源。 - - OpenClaw 默认强制执行 gateway 认证，包括 loopback。在正常默认路径下，这意味着令牌认证：如果没有显式配置认证路径，gateway 启动时会解析为 token 模式并自动生成一个令牌，将其保存到 `gateway.auth.token` 中，因此**本地 WS 客户端也必须进行认证**。这样可以阻止其他本地进程调用 Gateway 网关。 + + OpenClaw 默认强制启用 gateway 身份验证，包括 loopback。在正常默认路径中，这意味着 token 身份验证：如果没有显式配置身份验证路径，gateway 启动会解析为 token 模式并自动生成一个 token，将其保存到 `gateway.auth.token`，因此**本地 WS 客户端也必须进行身份验证**。这样可以阻止其他本地进程调用 Gateway 网关。 - 如果你偏好其他认证路径，可以显式选择密码模式（或，对非 loopback 身份感知反向代理使用 `trusted-proxy`）。如果你**真的**想开放 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 可以随时为你生成令牌：`openclaw doctor --generate-gateway-token`。 + 如果你更喜欢其他身份验证路径，可以显式选择密码模式（或者，对于非 loopback 的具身份感知反向代理，使用 `trusted-proxy`）。如果你**确实**想开放 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 可随时为你生成 token：`openclaw doctor --generate-gateway-token`。 - - Gateway 网关会监控配置并支持热重载： + + Gateway 网关会监视配置并支持热重载： - - `gateway.reload.mode: "hybrid"`（默认）：安全改动热应用，关键改动则重启 + - `gateway.reload.mode: "hybrid"`（默认）：安全更改热应用，关键更改则重启 - 也支持 `hot`、`restart`、`off` - + 在配置中设置 `cli.banner.taglineMode`： ```json5 @@ -1542,24 +1556,24 @@ x-i18n: } ``` - - `off`：隐藏标语文本，但保留横幅标题/版本行。 + - `off`：隐藏标语文本，但保留横幅标题 / 版本行。 - `default`：始终使用 `All your chats, one OpenClaw.`。 - - `random`：轮换有趣/季节性标语（默认行为）。 - - 如果你希望完全不显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `random`：轮换有趣 / 季节性标语（默认行为）。 + - 如果你完全不想要横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 - `web_fetch` 无需 API 密钥即可使用。`web_search` 取决于你选择的 + `web_fetch` 无需 API 密钥即可工作。`web_search` 则取决于你选择的 提供商： - - 基于 API 的提供商，如 Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily，需要按照正常方式配置 API 密钥。 - - Ollama Web 搜索 无需密钥，但它使用你配置的 Ollama 主机，并要求执行 `ollama signin`。 - - DuckDuckGo 无需密钥，但它是一个非官方的基于 HTML 的集成。 - - SearXNG 无需密钥/可自托管；请配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 + - 基于 API 的提供商，如 Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily，需要按正常方式配置 API 密钥。 + - Ollama Web 搜索 不需要密钥，但它使用你配置的 Ollama 主机，并要求 `ollama signin`。 + - DuckDuckGo 不需要密钥，但这是一个非官方的基于 HTML 的集成。 + - SearXNG 是免密钥 / 自托管的；请配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 - **推荐：**运行 `openclaw configure --section web` 并选择一个提供商。 - 环境变量替代方式： + **推荐方式：**运行 `openclaw configure --section web` 并选择一个提供商。 + 环境变量替代方案： - Brave：`BRAVE_API_KEY` - Exa：`EXA_API_KEY` @@ -1602,53 +1616,53 @@ x-i18n: ``` 提供商特定的 Web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 - 旧版 `tools.web.search.*` 提供商路径目前仍会为了兼容性而临时加载，但不应在新配置中继续使用。 - Firecrawl 的 web-fetch 回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 + 出于兼容性考虑，旧版 `tools.web.search.*` 提供商路径目前仍可加载，但不应再用于新配置。 + Firecrawl 的 Web 抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 说明： - - 如果你使用允许列表，请添加 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 - - `web_fetch` 默认启用（除非被显式禁用）。 - - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭据中自动检测第一个已就绪的 fetch 回退提供商。目前内置提供商是 Firecrawl。 + - 如果你使用允许列表，请添加 `web_search` / `web_fetch` / `x_search` 或 `group:web`。 + - `web_fetch` 默认启用（除非显式禁用）。 + - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个已就绪的抓取回退提供商。目前内置提供商是 Firecrawl。 - 守护进程会从 `~/.openclaw/.env`（或服务环境）读取环境变量。 - 文档：[Web tools](/zh-CN/tools/web)。 + 文档：[Web 工具](/zh-CN/tools/web)。 - - `config.apply` 会替换**整个配置**。如果你发送的是部分对象，其他所有内容 - 都会被移除。 + + `config.apply` 会替换**整个配置**。如果你传入的是部分对象，其余内容 + 都会被删除。 恢复方法： - 从备份恢复（git 或复制的 `~/.openclaw/openclaw.json`）。 - - 如果没有备份，请重新运行 `openclaw doctor` 并重新配置渠道/模型。 - - 如果这是意料之外的行为，请提交 bug，并附上你最后已知的配置或任何备份。 - - 本地编码智能体通常可以根据日志或历史重建一个可工作的配置。 + - 如果没有备份，请重新运行 `openclaw doctor` 并重新配置渠道 / 模型。 + - 如果这不是预期行为，请提交 bug，并附上你最后已知的配置或任何备份。 + - 本地编码智能体通常可以根据日志或历史记录重建一个可工作的配置。 - 避免方式： + 避免方法： - - 小改动使用 `openclaw config set`。 - - 交互式编辑使用 `openclaw configure`。 - - 当你不确定精确路径或字段结构时，先用 `config.schema.lookup`；它会返回一个浅层 schema 节点以及直接子项摘要，方便逐层钻取。 - - 对于部分 RPC 编辑，请使用 `config.patch`；仅在需要整体替换完整配置时才使用 `config.apply`。 - - 如果你是在智能体运行中使用仅所有者可用的 `gateway` 工具，它仍然会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会被规范化到相同受保护 exec 路径的旧版 `tools.bash.*` 别名）。 + - 小改动请使用 `openclaw config set`。 + - 交互式编辑请使用 `openclaw configure`。 + - 当你不确定确切路径或字段结构时，先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点和直接子项摘要，便于逐层钻取。 + - 对于部分 RPC 编辑，请使用 `config.patch`；仅在确实需要完整替换配置时才使用 `config.apply`。 + - 如果你在智能体运行中使用仅限所有者的 `gateway` 工具，它仍会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会规范化到相同受保护 exec 路径的旧版 `tools.bash.*` 别名）。 - 文档：[Config](/cli/config)、[Configure](/cli/configure)、[Doctor](/zh-CN/gateway/doctor)。 + 文档：[配置](/cli/config)、[配置向导](/cli/configure)、[Doctor](/zh-CN/gateway/doctor)。 - - 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上**节点**和**智能体**： + + 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）配合**节点**和**智能体**： - - **Gateway 网关（中央）：**持有渠道（Signal/WhatsApp）、路由和会话。 - - **节点（设备）：**Mac/iOS/Android 作为外设连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 - - **智能体（工作者）：**不同职责的独立“大脑”/工作区（例如“Hetzner 运维”“个人数据”）。 - - **子智能体：**当你想并行处理时，从主智能体中派生后台工作。 - - **TUI：**连接到 Gateway 网关并切换智能体/会话。 + - **Gateway 网关（中心）：**负责渠道（Signal / WhatsApp）、路由和会话。 + - **节点（设备）：**Mac / iOS / Android 作为外设连接，暴露本地工具（`system.run`、`canvas`、`camera`）。 + - **智能体（workers）：**拥有各自工作区 / 角色的独立“大脑”（例如“Hetzner 运维”“个人数据”）。 + - **子智能体：**当你想并行处理时，从主智能体中启动后台任务。 + - **TUI：**连接到 Gateway 网关并切换智能体 / 会话。 - 文档：[Nodes](/zh-CN/nodes)、[Remote access](/zh-CN/gateway/remote)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[TUI](/web/tui)。 + 文档：[节点](/zh-CN/nodes)、[远程访问](/zh-CN/gateway/remote)、[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[TUI](/web/tui)。 @@ -1666,47 +1680,46 @@ x-i18n: } ``` - 默认值是 `false`（有头）。无头模式更容易触发某些网站的反机器人检查。参阅 [Browser](/zh-CN/tools/browser)。 + 默认是 `false`（有头模式）。无头模式更容易在某些站点触发反机器人检查。参见 [浏览器](/zh-CN/tools/browser)。 - 无头模式使用的是**相同的 Chromium 引擎**，适用于大多数自动化场景（表单、点击、抓取、登录）。主要区别是： + 无头模式使用**相同的 Chromium 引擎**，适用于大多数自动化场景（表单、点击、抓取、登录）。主要区别在于： - - 没有可见的浏览器窗口（如果需要视觉确认，请使用截图）。 - - 某些网站对无头模式下的自动化更严格（CAPTCHA、反机器人）。 - 例如，X/Twitter 通常会阻止无头会话。 + - 没有可见浏览器窗口（如果你需要视觉信息，请使用截图）。 + - 某些站点对无头模式下的自动化更严格（CAPTCHA、反机器人）。 + 例如，X / Twitter 常常会阻止无头会话。 - 将 `browser.executablePath` 设置为你的 Brave 二进制文件（或任何基于 Chromium 的浏览器），然后重启 Gateway 网关。 - 完整配置示例请参阅 [Browser](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)。 + 将 `browser.executablePath` 设置为你的 Brave 二进制文件（或任意基于 Chromium 的浏览器），然后重启 Gateway 网关。 + 完整配置示例请参见 [浏览器](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)。 -## 远程 Gateway 网关和节点 +## 远程 Gateway 网关与节点 - - Telegram 消息由**gateway**处理。gateway 运行智能体， - 只有在需要节点工具时才会通过**Gateway WebSocket** - 调用节点： + + Telegram 消息由 **gateway** 处理。gateway 运行智能体， + 只有在需要节点工具时，才会通过 **Gateway WebSocket** 调用节点： Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - 节点不会看到入站提供商流量；它们只接收节点 RPC 调用。 + 节点看不到入站提供商流量；它们只接收节点 RPC 调用。 - 简短回答：**把你的电脑配对成一个节点**。Gateway 网关运行在别处，但它可以 - 通过 Gateway WebSocket 在你的本地机器上调用 `node.*` 工具（屏幕、摄像头、系统）。 + 简短回答：**将你的电脑配对为节点**。Gateway 网关运行在其他地方，但它可以 + 通过 Gateway WebSocket 在你的本地机器上调用 `node.*` 工具（屏幕、摄像头、system）。 典型设置： - 1. 在始终在线的主机（VPS/家庭服务器）上运行 Gateway 网关。 - 2. 让 Gateway 主机和你的电脑加入同一个 tailnet。 - 3. 确保 Gateway WS 可达（tailnet 绑定或 SSH 隧道）。 - 4. 在本地打开 macOS 应用，并以**Remote over SSH** 模式（或直接 tailnet） - 连接，使其可以注册为一个节点。 + 1. 在常开主机（VPS / 家庭服务器）上运行 Gateway 网关。 + 2. 将 Gateway 网关主机和你的电脑放到同一个 tailnet 中。 + 3. 确保 Gateway 网关 WS 可访问（tailnet 绑定或 SSH 隧道）。 + 4. 在本地打开 macOS 应用，并以**通过 SSH 远程连接**模式（或直接 tailnet） + 连接，以便它注册为节点。 5. 在 Gateway 网关上批准该节点： ```bash @@ -1714,90 +1727,90 @@ x-i18n: openclaw devices approve ``` - 不需要单独的 TCP bridge；节点通过 Gateway WebSocket 进行连接。 + 不需要单独的 TCP bridge；节点通过 Gateway WebSocket 连接。 - 安全提醒：配对一个 macOS 节点意味着该机器上允许 `system.run`。 - 只配对你信任的设备，并阅读 [Security](/zh-CN/gateway/security)。 + 安全提醒：配对 macOS 节点意味着允许在该机器上运行 `system.run`。 + 只配对你信任的设备，并查看 [安全](/zh-CN/gateway/security)。 - 文档：[Nodes](/zh-CN/nodes)、[Gateway protocol](/zh-CN/gateway/protocol)、[macOS remote mode](/zh-CN/platforms/mac/remote)、[Security](/zh-CN/gateway/security)。 + 文档：[节点](/zh-CN/nodes)、[Gateway 网关协议](/zh-CN/gateway/protocol)、[macOS 远程模式](/zh-CN/platforms/mac/remote)、[安全](/zh-CN/gateway/security)。 先检查基础项： - - Gateway 网关是否正在运行：`openclaw gateway status` - - Gateway 网关健康状况：`openclaw status` - - 渠道健康状况：`openclaw channels status` + - Gateway 网关正在运行：`openclaw gateway status` + - Gateway 网关健康状态：`openclaw status` + - 渠道健康状态：`openclaw channels status` - 然后验证认证和路由： + 然后验证身份验证和路由： - - 如果你使用 Tailscale Serve，确保 `gateway.auth.allowTailscale` 设置正确。 - - 如果你通过 SSH 隧道连接，请确认本地隧道已建立并指向正确端口。 - - 确认你的允许列表（私信或群组）包含你的账号。 + - 如果你使用 Tailscale Serve，请确认 `gateway.auth.allowTailscale` 设置正确。 + - 如果你通过 SSH 隧道连接，请确认本地隧道已建立，并指向正确端口。 + - 确认你的允许列表（私信或群组）包含你的账户。 - 文档：[Tailscale](/zh-CN/gateway/tailscale)、[Remote access](/zh-CN/gateway/remote)、[Channels](/zh-CN/channels)。 + 文档：[Tailscale](/zh-CN/gateway/tailscale)、[远程访问](/zh-CN/gateway/remote)、[渠道](/zh-CN/channels)。 - + 可以。没有内置的“机器人对机器人”桥接，但你可以通过几种 - 可靠方式实现： + 可靠方式将其接起来： - **最简单的方式：**使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 - 让 Bot A 给 Bot B 发消息，然后让 Bot B 正常回复。 + **最简单方式：**使用两个机器人都能访问的普通聊天渠道（Telegram / Slack / WhatsApp）。 + 让机器人 A 给机器人 B 发消息，然后让机器人 B 像平常一样回复。 - **CLI 桥接（通用）：**运行一个脚本，调用另一个 Gateway 网关的 - `openclaw agent --message ... --deliver`，目标是另一个机器人 - 正在监听的聊天。如果其中一个机器人在远程 VPS 上，请让你的 CLI 指向那个远程 Gateway 网关， - 可通过 SSH/Tailscale（见 [Remote access](/zh-CN/gateway/remote)）实现。 + **CLI 桥接（通用）：**运行一个脚本，通过 + `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，目标设为另一个机器人 + 正在监听的聊天。如果某个机器人位于远程 VPS 上，请通过 SSH / Tailscale + 将你的 CLI 指向该远程 Gateway 网关（参见 [远程访问](/zh-CN/gateway/remote)）。 - 示例模式（从一台能访问目标 Gateway 网关的机器上运行）： + 示例模式（在一台能访问目标 Gateway 网关的机器上运行）： ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - 提示：添加一个保护措施，防止两个机器人无限循环（仅回应提及、渠道 - 允许列表，或“不要回复机器人消息”的规则）。 + 提示：增加一个防护措施，避免两个机器人无限循环回复（仅回应提及、 + 渠道允许列表，或“不要回复机器人消息”的规则）。 - 文档：[Remote access](/zh-CN/gateway/remote)、[Agent CLI](/cli/agent)、[Agent send](/zh-CN/tools/agent-send)。 + 文档：[远程访问](/zh-CN/gateway/remote)、[智能体 CLI](/cli/agent)、[智能体发送](/zh-CN/tools/agent-send)。 不需要。一个 Gateway 网关可以托管多个智能体，每个智能体都有自己的工作区、默认模型 - 和路由。这是正常设置，也比 - 每个智能体一个 VPS 便宜且简单得多。 + 和路由。这是正常设置，比每个智能体运行一个 VPS + 更便宜也更简单。 - 只有在你需要硬隔离（安全边界）或非常不同、你不想共享的配置时， - 才需要分别使用不同的 VPS。否则，保持一个 Gateway 网关， + 只有在你需要硬隔离（安全边界）或 + 不想共享的截然不同配置时，才需要单独的 VPS。否则，保留一个 Gateway 网关， 并使用多个智能体或子智能体即可。 - - 有——节点是从远程 Gateway 网关访问你笔记本的首选方式，而且它们 - 不只是提供 shell 访问。Gateway 网关运行在 macOS/Linux（Windows 通过 WSL2）上，并且 - 非常轻量（小型 VPS 或 Raspberry Pi 级别机器就足够；4 GB RAM 已很充足），所以一种常见 - 设置是始终在线的主机 + 你的笔记本作为节点。 + + 有——节点是从远程 Gateway 网关访问你笔记本的首选方式，而且 + 它们提供的不仅仅是 shell 访问。Gateway 网关运行于 macOS / Linux（Windows 通过 WSL2），并且 + 十分轻量（小型 VPS 或 Raspberry Pi 级设备就足够；4 GB 内存完全够用），因此一种常见 + 设置是常开主机 + 你的笔记本作为节点。 - - **不需要入站 SSH。**节点主动连接到 Gateway WebSocket，并使用设备配对。 - - **更安全的执行控制。**`system.run` 在那台笔记本上会受到节点允许列表/审批控制。 - - **更多设备工具。**节点除 `system.run` 外，还暴露 `canvas`、`camera` 和 `screen`。 - - **本地浏览器自动化。**将 Gateway 网关放在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或通过 Chrome MCP 连接到主机上的本地 Chrome。 + - **无需入站 SSH。**节点主动连接到 Gateway WebSocket，并使用设备配对。 + - **更安全的执行控制。**`system.run` 在该笔记本上受节点允许列表 / 审批控制。 + - **更多设备工具。**节点除了 `system.run` 外，还暴露 `canvas`、`camera` 和 `screen`。 + - **本地浏览器自动化。**将 Gateway 网关放在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或通过 Chrome MCP 连接主机上的本地 Chrome。 - SSH 适合临时 shell 访问，但节点对于持续性的智能体工作流和 - 设备自动化更简单。 + SSH 适合临时 shell 访问，但对于持续的智能体工作流和 + 设备自动化，节点更简单。 - 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)、[Browser](/zh-CN/tools/browser)。 + 文档：[节点](/zh-CN/nodes)、[节点 CLI](/cli/nodes)、[浏览器](/zh-CN/tools/browser)。 - - 不会。除非你是有意运行隔离配置文件（见 [Multiple gateways](/zh-CN/gateway/multiple-gateways)），否则每台主机只应运行**一个 gateway**。节点是连接到 - gateway 的外设（iOS/Android 节点，或菜单栏应用中的 macOS “node mode”）。关于无头节点 - 主机和 CLI 控制，请参阅 [Node host CLI](/cli/node)。 + + 不会。除非你有意运行隔离配置文件（参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)），否则每台主机上只应运行**一个 gateway**。节点是连接到 + gateway 的外设（iOS / Android 节点，或菜单栏应用中的 macOS “node mode”）。有关无头节点 + 主机和 CLI 控制，请参见 [节点主机 CLI](/cli/node)。 对 `gateway`、`discovery` 和 `canvasHost` 的更改需要完整重启。 @@ -1807,14 +1820,14 @@ x-i18n: 有。 - `config.schema.lookup`：在写入前检查一个配置子树，包括其浅层 schema 节点、匹配的 UI 提示和直接子项摘要 - - `config.get`：获取当前快照 + 哈希 - - `config.patch`：安全的局部更新（大多数 RPC 编辑的首选） - - `config.apply`：校验 + 替换完整配置，然后重启 - - 仅所有者可用的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径 + - `config.get`：获取当前快照 + hash + - `config.patch`：安全的部分更新（大多数 RPC 编辑推荐） + - `config.apply`：验证并替换完整配置，然后重启 + - 仅限所有者的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会被规范化到同样受保护的 exec 路径 - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1822,12 +1835,12 @@ x-i18n: } ``` - 这会设置你的工作区，并限制谁可以触发机器人。 + 这会设置你的工作区，并限制哪些人可以触发机器人。 - 最小步骤： + 最简步骤如下： 1. **在 VPS 上安装并登录** @@ -1837,31 +1850,31 @@ x-i18n: ``` 2. **在你的 Mac 上安装并登录** - - 使用 Tailscale 应用，并登录到同一个 tailnet。 + - 使用 Tailscale 应用并登录到同一个 tailnet。 3. **启用 MagicDNS（推荐）** - - 在 Tailscale 管理控制台中启用 MagicDNS，这样 VPS 就有了稳定名称。 + - 在 Tailscale 管理控制台中启用 MagicDNS，让 VPS 拥有稳定名称。 4. **使用 tailnet 主机名** - SSH：`ssh user@your-vps.tailnet-xxxx.ts.net` - - Gateway WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` + - Gateway 网关 WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` - 如果你希望无需 SSH 也能使用 Control UI，请在 VPS 上使用 Tailscale Serve： + 如果你想在不使用 SSH 的情况下访问 Control UI，请在 VPS 上使用 Tailscale Serve： ```bash openclaw gateway --tailscale serve ``` - 这样会让 gateway 保持绑定 loopback，并通过 Tailscale 暴露 HTTPS。参阅 [Tailscale](/zh-CN/gateway/tailscale)。 + 这样会让 gateway 保持绑定到 loopback，并通过 Tailscale 暴露 HTTPS。参见 [Tailscale](/zh-CN/gateway/tailscale)。 - Serve 会暴露**Gateway Control UI + WS**。节点通过同一个 Gateway WS 端点连接。 + Serve 会暴露 **Gateway 网关 Control UI + WS**。节点通过同一个 Gateway WS 端点连接。 推荐设置： 1. **确保 VPS 和 Mac 在同一个 tailnet 中**。 2. **在 Remote 模式下使用 macOS 应用**（SSH 目标可以是 tailnet 主机名）。 - 应用会将 Gateway 端口建立隧道，并作为一个节点连接。 + 应用会隧道化 Gateway 端口，并作为节点连接。 3. **在 gateway 上批准该节点**： ```bash @@ -1869,19 +1882,18 @@ x-i18n: openclaw devices approve ``` - 文档：[Gateway protocol](/zh-CN/gateway/protocol)、[Discovery](/zh-CN/gateway/discovery)、[macOS remote mode](/zh-CN/platforms/mac/remote)。 + 文档：[Gateway 网关协议](/zh-CN/gateway/protocol)、[设备发现](/zh-CN/gateway/discovery)、[macOS 远程模式](/zh-CN/platforms/mac/remote)。 - - 如果你只需要第二台笔记本上的**本地工具**（屏幕/摄像头/exec），就把它添加为 - **节点**。这样可以保持单个 Gateway 网关，并避免重复配置。当前本地节点工具 + + 如果你只需要第二台笔记本上的**本地工具**（屏幕 / 摄像头 / exec），请把它添加为 + **节点**。这样可以保持单一 Gateway 网关，并避免重复配置。目前本地节点工具 仅支持 macOS，但我们计划扩展到其他操作系统。 - 只有在你需要**硬隔离**或两个完全独立的机器人时， - 才应该安装第二个 Gateway 网关。 + 只有在你需要**硬隔离**或两个完全独立的机器人时，才安装第二个 Gateway 网关。 - 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)、[Multiple gateways](/zh-CN/gateway/multiple-gateways)。 + 文档：[节点](/zh-CN/nodes)、[节点 CLI](/cli/nodes)、[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 @@ -1890,14 +1902,14 @@ x-i18n: - OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并额外加载： + OpenClaw 会从父进程（shell、launchd / systemd、CI 等）读取环境变量，并另外加载： - 当前工作目录中的 `.env` - - 来自 `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`）的全局回退 `.env` + - 来自 `~/.openclaw/.env` 的全局回退 `.env`（即 `$OPENCLAW_STATE_DIR/.env`） 这两个 `.env` 文件都不会覆盖现有环境变量。 - 你还可以在配置中定义内联环境变量（仅在进程环境中缺失时应用）： + 你也可以在配置中定义内联环境变量（仅当进程环境中缺失时应用）： ```json5 { @@ -1908,15 +1920,15 @@ x-i18n: } ``` - 关于完整优先级和来源，请参阅 [/environment](/zh-CN/help/environment)。 + 完整优先级和来源请参见 [/environment](/zh-CN/help/environment)。 - - 两个常见修复方式： + + 两种常见修复方式： - 1. 将缺失的密钥放入 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境，它们也会被读取。 - 2. 启用 shell 导入（可选的便捷功能）： + 1. 将缺失的键放入 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境，也能读取到。 + 2. 启用 shell 导入（自选便利功能）： ```json5 { @@ -1929,27 +1941,27 @@ x-i18n: } ``` - 这会运行你的登录 shell，并且只导入缺失的预期键名（绝不覆盖已有值）。环境变量等价项： + 这会运行你的登录 shell，并且只导入缺失的预期键名（绝不覆盖）。对应环境变量： `OPENCLAW_LOAD_SHELL_ENV=1`、`OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`。 - - `openclaw models status` 显示的是是否启用了**shell 环境导入**。“Shell env: off” - **不**意味着你的环境变量缺失——它只是表示 OpenClaw 不会 - 自动加载你的登录 shell。 + + `openclaw models status` 报告的是**是否启用了 shell 环境导入**。“Shell env: off” + **并不**意味着你的环境变量缺失——它只是表示 OpenClaw 不会自动加载 + 你的登录 shell。 - 如果 Gateway 网关作为服务运行（launchd/systemd），它不会继承你的 shell - 环境。解决方式如下： + 如果 Gateway 网关作为服务运行（launchd / systemd），它不会继承你的 shell + 环境。可通过以下任一方式修复： - 1. 把令牌放到 `~/.openclaw/.env` 中： + 1. 将 token 放入 `~/.openclaw/.env`： ``` COPILOT_GITHUB_TOKEN=... ``` 2. 或启用 shell 导入（`env.shellEnv.enabled: true`）。 - 3. 或将它添加到配置中的 `env` 块里（仅在缺失时应用）。 + 3. 或把它加入配置中的 `env` 块（仅在缺失时应用）。 然后重启 gateway 并重新检查： @@ -1957,24 +1969,24 @@ x-i18n: openclaw models status ``` - Copilot 令牌从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 - 参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 + Copilot token 读取自 `COPILOT_GITHUB_TOKEN`（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 + 参见 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 -## 会话和多聊天 +## 会话与多个聊天 - 发送 `/new` 或 `/reset` 作为独立消息。参阅 [Session management](/zh-CN/concepts/session)。 + 发送 `/new` 或 `/reset` 作为独立消息。参见 [会话管理](/zh-CN/concepts/session)。 - 会话可以在 `session.idleMinutes` 后过期，但这**默认是禁用的**（默认值为 **0**）。 - 将其设置为正值即可启用空闲过期。启用后，在空闲期之后收到的**下一条** + 会话会在 `session.idleMinutes` 到期后过期，但该功能**默认关闭**（默认值 **0**）。 + 将其设置为正值即可启用空闲过期。启用后，空闲期之后的**下一条** 消息会为该聊天键启动一个新的会话 ID。 - 这不会删除对话记录——它只会开启一个新会话。 + 这不会删除转录——只是开始一个新会话。 ```json5 { @@ -1986,16 +1998,16 @@ x-i18n: - - 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调者 - 智能体，以及多个拥有各自工作区和模型的工作智能体。 + + 有，通过**多智能体路由**和**子智能体**。你可以创建一个协调者 + 智能体，以及若干拥有各自工作区和模型的工作智能体。 - 不过，这更适合作为一个**有趣的实验**。它很耗 token，而且通常 - 不如一个机器人配多个会话高效。我们通常设想的模式是：一个你与之对话的机器人， - 通过不同会话处理并行工作。这个机器人 - 也可以在需要时启动子智能体。 + 不过，这更适合作为一个**有趣的实验**。它会消耗大量 token，而且通常 + 不如使用一个机器人配合多个独立会话高效。我们通常设想的模式 + 是：你与一个机器人交流，用不同会话并行处理工作。该 + 机器人也可以在需要时启动子智能体。 - 文档：[Multi-agent routing](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[Agents CLI](/cli/agents)。 + 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[智能体 CLI](/cli/agents)。 @@ -2005,15 +2017,15 @@ x-i18n: 有帮助的做法： - - 让机器人总结当前状态并将其写入文件。 + - 让机器人总结当前状态并写入文件。 - 在长任务前使用 `/compact`，切换主题时使用 `/new`。 - - 将重要上下文保存在工作区，并让机器人重新读取。 - - 对长任务或并行工作使用子智能体，这样主聊天会更小。 - - 如果这种情况经常出现，请选择上下文窗口更大的模型。 + - 将重要上下文保留在工作区中，并让机器人重新读取它。 + - 对于长任务或并行工作，使用子智能体，这样主聊天会更小。 + - 如果这种情况经常发生，请选择上下文窗口更大的模型。 - + 使用 reset 命令： ```bash @@ -2034,24 +2046,24 @@ x-i18n: 说明： - - 如果新手引导检测到已有配置，也会提供**重置**选项。参阅 [Onboarding（CLI）](/zh-CN/start/wizard)。 - - 如果你使用了 profile（`--profile` / `OPENCLAW_PROFILE`），请分别重置每个状态目录（默认是 `~/.openclaw-`）。 - - 开发重置：`openclaw gateway --dev --reset`（仅开发环境；会清空开发配置 + 凭据 + 会话 + 工作区）。 + - 如果检测到现有配置，新手引导也会提供 **Reset**。参见 [设置向导（CLI）](/zh-CN/start/wizard)。 + - 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 + - 开发重置：`openclaw gateway --dev --reset`（仅开发用途；会清除开发配置 + 凭证 + 会话 + 工作区）。 - - 使用以下方式之一： + + 请使用以下方法之一： - - **压缩**（保留对话，但总结较早轮次）： + - **压缩**（保留对话，但总结较旧轮次）： ``` /compact ``` - 或使用 `/compact ` 来引导摘要方式。 + 或使用 `/compact ` 来指导摘要内容。 - - **重置**（为同一个聊天键创建新的会话 ID）： + - **重置**（为同一聊天键创建新的会话 ID）： ``` /new @@ -2060,50 +2072,50 @@ x-i18n: 如果这种情况持续发生： - - 启用或调整**会话修剪**（`agents.defaults.contextPruning`）以裁剪旧工具输出。 + - 启用或调整**会话裁剪**（`agents.defaults.contextPruning`）以修剪旧工具输出。 - 使用上下文窗口更大的模型。 - 文档：[Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)、[Session management](/zh-CN/concepts/session)。 + 文档：[压缩](/zh-CN/concepts/compaction)、[会话裁剪](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 - - 这是提供商的校验错误：模型发出了一个缺少必需 - `input` 的 `tool_use` 块。通常意味着会话历史陈旧或已损坏（常见于长线程 - 或工具/schema 变更之后）。 + + 这是一个提供商校验错误：模型发出了一个 `tool_use` 块，但缺少必需的 + `input`。这通常意味着会话历史已过时或损坏（常见于长线程 + 或工具 / schema 变更之后）。 - 解决方法：发送 `/new` 作为独立消息，开始一个新会话。 + 修复方法：通过 `/new`（独立消息）开启一个新会话。 - - Heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。可以调整或禁用它： + + Heartbeat 默认每 **30m** 运行一次（使用 OAuth 凭证时为 **1h**）。可以调整或禁用它们： ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // 或 "0m" 来禁用 + every: "2h", // 或 "0m" 以禁用 }, }, }, } ``` - 如果 `HEARTBEAT.md` 存在但实际上为空（仅有空行和 markdown + 如果 `HEARTBEAT.md` 存在但实际上为空（仅包含空行和 Markdown 标题如 `# Heading`），OpenClaw 会跳过 heartbeat 运行以节省 API 调用。 如果文件不存在，heartbeat 仍会运行，并由模型决定要做什么。 - 每智能体覆盖使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 + 按智能体覆盖请使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不需要。OpenClaw 运行在**你自己的账号**上，所以如果你在群组里，OpenClaw 就能看到它。 + + 不需要。OpenClaw 运行在**你自己的账号**上，所以只要你在群组里，OpenClaw 就能看到它。 默认情况下，群组回复会被阻止，直到你允许发送者（`groupPolicy: "allowlist"`）。 - 如果你只希望**你自己**能够触发群组回复： + 如果你希望只有**你自己**能够触发群组回复： ```json5 { @@ -2119,163 +2131,163 @@ x-i18n: - 选项 1（最快）：跟踪日志，并在群组中发送一条测试消息： + 方式 1（最快）：查看日志，并在群里发送一条测试消息： ```bash openclaw logs --follow --json ``` - 查找以 `@g.us` 结尾的 `chatId`（或 `from`），例如： + 找到以 `@g.us` 结尾的 `chatId`（或 `from`），例如： `1234567890-1234567890@g.us`。 - 选项 2（如果已配置/加入允许列表）：从配置中列出群组： + 方式 2（如果已配置 / 已加入允许列表）：从配置中列出群组： ```bash openclaw directory groups list --channel whatsapp ``` - 文档：[WhatsApp](/zh-CN/channels/whatsapp)、[Directory](/cli/directory)、[Logs](/cli/logs)。 + 文档：[WhatsApp](/zh-CN/channels/whatsapp)、[目录](/cli/directory)、[日志](/cli/logs)。 - + 两个常见原因： - - 提及门控已开启（默认）。你必须 @ 提及机器人（或匹配 `mentionPatterns`）。 - - 你配置了 `channels.whatsapp.groups` 但没有包含 `"*"`，并且该群组不在允许列表中。 + - 提及门控已启用（默认）。你必须 @ 提及机器人（或匹配 `mentionPatterns`）。 + - 你配置了 `channels.whatsapp.groups`，但没有包含 `"*"`，而且该群组不在允许列表中。 - 参阅 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 + 参见 [群组](/zh-CN/channels/groups) 和 [群组消息](/zh-CN/channels/group-messages)。 - - 直接聊天默认会归并到主会话。群组/渠道有各自的会话键，而 Telegram 话题 / Discord 线程则是独立会话。参阅 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 + + 直接聊天默认会折叠到主会话。群组 / 渠道拥有各自的会话键，Telegram 主题 / Discord 线程也都是独立会话。参见 [群组](/zh-CN/channels/groups) 和 [群组消息](/zh-CN/channels/group-messages)。 - 没有硬性上限。几十个（甚至几百个）都没问题，但请注意： + 没有硬性限制。几十个（甚至上百个）都可以，但请注意： - - **磁盘增长：**会话 + 转录存放在 `~/.openclaw/agents//sessions/` 下。 - - **Token 成本：**智能体越多，模型并发使用越多。 - - **运维开销：**每智能体的认证档案、工作区和渠道路由。 + - **磁盘增长：**会话 + 转录文件存储在 `~/.openclaw/agents//sessions/` 下。 + - **Token 成本：**更多智能体意味着更多并发模型使用。 + - **运维开销：**按智能体划分的凭证配置文件、工作区和渠道路由。 提示： - - 每个智能体保持一个**活跃**工作区（`agents.defaults.workspace`）。 - - 如果磁盘增长，请修剪旧会话（删除 JSONL 或 store 条目）。 - - 使用 `openclaw doctor` 发现零散工作区和档案不匹配问题。 + - 每个智能体保留一个**活跃**工作区（`agents.defaults.workspace`）。 + - 如果磁盘增长，裁剪旧会话（删除 JSONL 或存储条目）。 + - 使用 `openclaw doctor` 发现游离工作区和配置文件不匹配问题。 - + 可以。使用**多智能体路由**来运行多个隔离的智能体，并按 - 渠道/账号/peer 路由入站消息。Slack 作为一个渠道受到支持，并且可以绑定到特定智能体。 + 渠道 / 账户 / peer 路由入站消息。Slack 支持作为一个渠道，并且可以绑定到特定智能体。 - 浏览器访问能力很强，但并不等于“做人类能做的一切”——反机器人机制、CAPTCHA 和 MFA - 仍然可能阻止自动化。若要实现最可靠的浏览器控制，请使用主机上的本地 Chrome MCP， + 浏览器访问能力很强，但并不等于“人能做的都能做”——反机器人机制、CAPTCHA 和 MFA + 仍然会阻止自动化。若要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， 或在实际运行浏览器的机器上使用 CDP。 最佳实践设置： - - 始终在线的 Gateway 网关主机（VPS/Mac mini）。 + - 常开 Gateway 网关主机（VPS / Mac mini）。 - 每个角色一个智能体（bindings）。 - 将 Slack 渠道绑定到这些智能体。 - - 需要时通过 Chrome MCP 或节点使用本地浏览器。 + - 在需要时通过 Chrome MCP 或节点使用本地浏览器。 - 文档：[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 - [Browser](/zh-CN/tools/browser)、[Nodes](/zh-CN/nodes)。 + 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 + [浏览器](/zh-CN/tools/browser)、[节点](/zh-CN/nodes)。 -## 模型：默认值、选择、别名、切换 +## 模型：默认值、选择、别名与切换 - OpenClaw 的默认模型就是你设置在： + OpenClaw 的默认模型就是你设置为： ``` agents.defaults.model.primary ``` - 模型以 `provider/model` 的形式引用（例如：`openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才会退回到已配置默认提供商这一已弃用的兼容路径。如果该提供商已不再暴露已配置的默认模型，OpenClaw 会退回到第一个已配置的提供商/模型，而不是暴露一个陈旧的、已被移除的提供商默认值。你仍然应该**显式**设置 `provider/model`。 + 模型以 `provider/model` 的形式引用（例如：`openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试对该精确模型 ID 进行唯一的已配置提供商匹配，最后才退回到已配置的默认提供商这一已废弃的兼容路径。如果该提供商不再暴露已配置的默认模型，OpenClaw 会退回到第一个已配置的提供商 / 模型，而不是继续暴露一个过时、已移除提供商的默认值。你仍然应该**显式**设置 `provider/model`。 - **推荐默认选择：**使用你提供商栈中可用的最新一代最强模型。 - **对于启用了工具或要处理不可信输入的智能体：**优先考虑模型能力，而不是成本。 - **对于日常/低风险聊天：**使用更便宜的后备模型，并按智能体角色进行路由。 + **推荐默认值：**使用你提供商栈中最新一代、能力最强的模型。 + **对于启用工具或面对不可信输入的智能体：**优先考虑模型能力，而不是成本。 + **对于日常 / 低风险聊天：**使用更便宜的回退模型，并按智能体角色进行路由。 - MiniMax 有自己的文档：[MiniMax](/zh-CN/providers/minimax) 和 - [Local models](/zh-CN/gateway/local-models)。 + MiniMax 有单独的文档：[MiniMax](/zh-CN/providers/minimax) 和 + [本地模型](/zh-CN/gateway/local-models)。 - 经验法则：对于高风险任务，使用**你能负担得起的最佳模型**；对于日常 - 聊天或总结，则使用更便宜的模型。你可以为每个智能体路由模型，并使用子智能体来 - 并行处理长任务（每个子智能体都会消耗 token）。参阅 [Models](/zh-CN/concepts/models) 和 - [Sub-agents](/zh-CN/tools/subagents)。 + 经验法则：对高风险工作使用**你负担得起的最佳模型**，而对日常 + 聊天或摘要使用更便宜的模型。你可以按智能体路由模型，并使用子智能体并行化 + 长任务（每个子智能体都会消耗 token）。参见 [模型](/zh-CN/concepts/models) 和 + [子智能体](/zh-CN/tools/subagents)。 - 强烈警告：较弱/过度量化的模型更容易受到提示 - 注入和不安全行为的影响。参阅 [Security](/zh-CN/gateway/security)。 + 强烈警告：较弱 / 过度量化的模型更容易受到 prompt + injection 和不安全行为的影响。参见 [安全](/zh-CN/gateway/security)。 - 更多背景：[Models](/zh-CN/concepts/models)。 + 更多背景：[模型](/zh-CN/concepts/models)。 - 使用**模型命令**，或只编辑**模型**字段。避免整体替换配置。 + 使用**模型命令**或仅编辑**模型**字段。避免完整替换配置。 安全选项： - - 在聊天中使用 `/model`（快速、按会话） - - `openclaw models set ...`（只更新模型配置） + - 在聊天中使用 `/model`（快速，按会话） + - `openclaw models set ...`（仅更新模型配置） - `openclaw configure --section model`（交互式） - 编辑 `~/.openclaw/openclaw.json` 中的 `agents.defaults.model` - 除非你确实打算替换整个配置，否则不要用部分对象调用 `config.apply`。 - 对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。lookup 负载会提供规范化路径、浅层 schema 文档/约束以及直接子项摘要， - 适合做局部更新。 - 如果你已经覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。 + 除非你确实打算替换整个配置，否则避免对部分对象使用 `config.apply`。 + 对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。lookup 载荷会给出规范化路径、浅层 schema 文档 / 约束以及直接子项摘要。 + 用于部分更新。 + 如果你确实覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。 - 文档：[Models](/zh-CN/concepts/models)、[Configure](/cli/configure)、[Config](/cli/config)、[Doctor](/zh-CN/gateway/doctor)。 + 文档：[模型](/zh-CN/concepts/models)、[配置向导](/cli/configure)、[配置](/cli/config)、[Doctor](/zh-CN/gateway/doctor)。 - - 可以。对于本地模型，Ollama 是最简单的方案。 + + 可以。Ollama 是本地模型最简单的路径。 - 最快捷的设置： + 最快设置方式： 1. 从 `https://ollama.com/download` 安装 Ollama 2. 拉取一个本地模型，例如 `ollama pull glm-4.7-flash` - 3. 如果你还想使用云模型，运行 `ollama signin` + 3. 如果你还想使用云模型，请运行 `ollama signin` 4. 运行 `openclaw onboard` 并选择 `Ollama` 5. 选择 `Local` 或 `Cloud + Local` 说明： - - `Cloud + Local` 会同时给你云模型和本地 Ollama 模型 + - `Cloud + Local` 会同时提供云模型和你的本地 Ollama 模型 - 像 `kimi-k2.5:cloud` 这样的云模型不需要本地 pull - - 如需手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/` + - 如需手动切换，可使用 `openclaw models list` 和 `openclaw models set ollama/` - 安全说明：更小或量化程度很高的模型更容易受到提示 - 注入影响。对于任何可使用工具的机器人，我们都强烈建议使用**大模型**。 - 如果你仍然想使用小模型，请启用沙箱隔离和严格的工具允许列表。 + 安全说明：较小或高度量化的模型更容易受到 prompt + injection 的影响。对于任何能够使用工具的机器人，我们强烈推荐**大模型**。 + 如果你仍想使用小模型，请启用沙箱隔离和严格的工具允许列表。 - 文档：[Ollama](/zh-CN/providers/ollama)、[Local models](/zh-CN/gateway/local-models)、 - [Model providers](/zh-CN/concepts/model-providers)、[Security](/zh-CN/gateway/security)、 + 文档：[Ollama](/zh-CN/providers/ollama)、[本地模型](/zh-CN/gateway/local-models)、 + [模型提供商](/zh-CN/concepts/model-providers)、[安全](/zh-CN/gateway/security)、 [沙箱隔离](/zh-CN/gateway/sandboxing)。 - - 这些部署可能不同，而且会随时间变化；并不存在固定的提供商推荐。 - - 请在每个 gateway 上使用 `openclaw models status` 检查当前运行时设置。 - - 对于安全敏感/启用了工具的智能体，请使用当前可用的最新一代最强模型。 + - 这些部署可能不同，并且会随时间变化；没有固定的提供商推荐。 + - 在每个 gateway 上使用 `openclaw models status` 检查当前运行时设置。 + - 对于安全敏感 / 启用工具的智能体，请使用当前可用的最新一代最强模型。 - 将 `/model` 命令作为独立消息发送： + 使用 `/model` 命令作为独立消息： ``` /model sonnet @@ -2287,56 +2299,56 @@ x-i18n: /model gemini-flash-lite ``` - 这些是内置别名。可以通过 `agents.defaults.models` 添加自定义别名。 + 这些是内置别名。自定义别名可通过 `agents.defaults.models` 添加。 你可以使用 `/model`、`/model list` 或 `/model status` 列出可用模型。 - `/model`（以及 `/model list`）会显示一个紧凑的编号选择器。按编号选择： + `/model`（以及 `/model list`）会显示一个紧凑的编号选择器。通过数字选择： ``` /model 3 ``` - 你还可以为提供商强制指定某个认证档案（按会话）： + 你还可以为该提供商强制指定特定凭证配置文件（按会话）： ``` /model opus@anthropic:default /model opus@anthropic:work ``` - 提示：`/model status` 会显示当前哪个智能体处于活跃状态、正在使用哪个 `auth-profiles.json` 文件，以及下一个会尝试哪个认证档案。 - 还会在可用时显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 + 提示：`/model status` 会显示当前活跃的是哪个智能体、正在使用哪个 `auth-profiles.json` 文件，以及下一个将尝试哪个凭证配置文件。 + 如果可用，它还会显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 - **如何取消通过 @profile 设定的固定档案？** + **如何取消固定我通过 @profile 设置的配置文件？** - 重新运行 `/model`，**不要**带 `@profile` 后缀： + 重新运行 `/model`，但**不要**带上 `@profile` 后缀： ``` /model anthropic/claude-opus-4-6 ``` 如果你想回到默认值，请从 `/model` 中选择它（或发送 `/model `）。 - 使用 `/model status` 确认当前激活的是哪个认证档案。 + 使用 `/model status` 确认当前活动的凭证配置文件。 - - 可以。将一个设为默认模型，并在需要时切换： + + 可以。把一个设为默认值，并在需要时切换： - - **快速切换（按会话）：**日常任务使用 `/model gpt-5.4`，编码时使用 `/model openai-codex/gpt-5.4` 配合 Codex OAuth。 - - **默认值 + 切换：**将 `agents.defaults.model.primary` 设为 `openai/gpt-5.4`，编码时切换到 `openai-codex/gpt-5.4`（或者反过来）。 - - **子智能体：**将编码任务路由到默认模型不同的子智能体。 + - **快速切换（按会话）：**日常任务使用 `/model gpt-5.4`，编码使用 `/model openai-codex/gpt-5.4` 搭配 Codex OAuth。 + - **默认值 + 切换：**将 `agents.defaults.model.primary` 设为 `openai/gpt-5.4`，然后在编码时切换到 `openai-codex/gpt-5.4`（或反过来）。 + - **子智能体：**将编码任务路由到具有不同默认模型的子智能体。 - 参阅 [Models](/zh-CN/concepts/models) 和 [Slash commands](/zh-CN/tools/slash-commands)。 + 参见 [模型](/zh-CN/concepts/models) 和 [斜杠命令](/zh-CN/tools/slash-commands)。 - - 你可以使用会话切换或配置默认值： + + 你可以使用会话级开关，或配置默认值： - **按会话：**当会话正在使用 `openai/gpt-5.4` 或 `openai-codex/gpt-5.4` 时，发送 `/fast on`。 - - **按模型默认值：**将 `agents.defaults.models["openai/gpt-5.4"].params.fastMode` 设为 `true`。 - - **Codex OAuth 也适用：**如果你也使用 `openai-codex/gpt-5.4`，请在该模型下设置相同标志。 + - **按模型默认值：**设置 `agents.defaults.models["openai/gpt-5.4"].params.fastMode` 为 `true`。 + - **Codex OAuth 也适用：**如果你也使用 `openai-codex/gpt-5.4`，请在其上设置相同标志。 示例： @@ -2361,37 +2373,37 @@ x-i18n: } ``` - 对于 OpenAI，fast mode 会在支持的原生 Responses 请求上映射为 `service_tier = "priority"`。会话中的 `/fast` 覆盖优先于配置默认值。 + 对于 OpenAI，快速模式会在支持的原生 Responses 请求上映射为 `service_tier = "priority"`。会话级 `/fast` 覆盖优先于配置默认值。 - 参阅 [Thinking and fast mode](/zh-CN/tools/thinking) 和 [OpenAI fast mode](/zh-CN/providers/openai#openai-fast-mode)。 + 参见 [Thinking 与快速模式](/zh-CN/tools/thinking) 和 [OpenAI 快速模式](/zh-CN/providers/openai#openai-fast-mode)。 - + 如果设置了 `agents.defaults.models`，它就会成为 `/model` 和任何 - 会话覆盖的**允许列表**。选择一个不在该列表中的模型会返回： + 会话覆盖的**允许列表**。选择不在该列表中的模型会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` - 该错误会**代替**正常回复返回。解决方法：将该模型加入 + 该错误会**替代**正常回复返回。修复方法：将该模型添加到 `agents.defaults.models`，移除允许列表，或从 `/model list` 中选择一个模型。 - - 这意味着**提供商未配置**（未找到 MiniMax 提供商配置或认证 - 档案），因此无法解析该模型。 + + 这意味着**提供商未配置**（未找到 MiniMax 提供商配置或凭证 + 配置文件），因此无法解析该模型。 - 修复清单： + 修复检查清单： - 1. 升级到当前 OpenClaw 版本（或从源码 `main` 运行），然后重启 gateway。 - 2. 确保已配置 MiniMax（通过向导或 JSON），或环境变量/认证档案中 - 已存在 MiniMax 认证，以便注入匹配提供商 - （`minimax` 使用 `MINIMAX_API_KEY`，`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或已存储的 MiniMax - OAuth）。 - 3. 为你的认证路径使用精确模型 ID（区分大小写）： + 1. 升级到当前 OpenClaw 版本（或直接从源码 `main` 运行），然后重启 gateway。 + 2. 确保 MiniMax 已配置（向导或 JSON），或者环境变量 / 凭证配置文件中存在 + MiniMax 凭证，以便注入匹配的提供商 + （`MINIMAX_API_KEY` 对应 `minimax`，`MINIMAX_OAUTH_TOKEN` 或已存储的 MiniMax + OAuth 对应 `minimax-portal`）。 + 3. 为你的凭证路径使用精确模型 ID（区分大小写）： API 密钥设置使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`， OAuth 设置使用 `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed`。 @@ -2401,17 +2413,17 @@ x-i18n: openclaw models list ``` - 然后从列表中选择（或在聊天中使用 `/model list`）。 + 并从列表中选择（或在聊天中使用 `/model list`）。 - 参阅 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。 + 参见 [MiniMax](/zh-CN/providers/minimax) 和 [模型](/zh-CN/concepts/models)。 - - 可以。将**MiniMax 设为默认值**，并在需要时**按会话**切换模型。 - 后备是为**错误**准备的，而不是“高难任务”，所以请使用 `/model` 或单独的智能体。 + + 可以。将 **MiniMax 作为默认值**，并在需要时**按会话** + 切换模型。回退是为**错误**准备的，不是为“困难任务”准备的，因此请使用 `/model` 或单独的智能体。 - **选项 A：按会话切换** + **方案 A：按会话切换** ```json5 { @@ -2434,18 +2446,18 @@ x-i18n: /model gpt ``` - **选项 B：分开智能体** + **方案 B：分离智能体** - 智能体 A 默认：MiniMax - 智能体 B 默认：OpenAI - 按智能体路由，或使用 `/agent` 切换 - 文档：[Models](/zh-CN/concepts/models)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[MiniMax](/zh-CN/providers/minimax)、[OpenAI](/zh-CN/providers/openai)。 + 文档：[模型](/zh-CN/concepts/models)、[多智能体路由](/zh-CN/concepts/multi-agent)、[MiniMax](/zh-CN/providers/minimax)、[OpenAI](/zh-CN/providers/openai)。 - 是的。OpenClaw 附带了一些默认简写（仅当模型存在于 `agents.defaults.models` 中时才生效）： + 是的。OpenClaw 附带一些默认简写（仅当模型存在于 `agents.defaults.models` 中时适用）： - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2460,7 +2472,7 @@ x-i18n: - + 别名来自 `agents.defaults.models..alias`。示例： ```json5 @@ -2511,12 +2523,12 @@ x-i18n: } ``` - 如果你引用了某个 provider/model，但缺少所需的提供商密钥，就会收到运行时认证错误（例如 `No API key found for provider "zai"`）。 + 如果你引用了某个 provider / model，但缺少所需的 provider 密钥，你会得到运行时凭证错误（例如 `No API key found for provider "zai"`）。 - **添加新智能体后提示 No API key found for provider** + **添加新智能体后出现 No API key found for provider** - 这通常意味着**新智能体**的认证存储为空。认证是按智能体区分的， - 存储于： + 这通常意味着**新智能体**的凭证存储为空。凭证是按智能体存储的， + 路径为： ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2524,39 +2536,39 @@ x-i18n: 修复选项： - - 运行 `openclaw agents add ` 并在向导中配置认证。 - - 或把主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir` 中。 + - 运行 `openclaw agents add ` 并在向导中配置凭证。 + - 或者将主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir`。 - **不要**在多个智能体之间复用 `agentDir`；这会导致认证/会话冲突。 + **不要**在多个智能体之间复用 `agentDir`；这会导致凭证 / 会话冲突。 -## 模型故障切换和 “All models failed” +## 模型故障切换与 “All models failed” - 故障切换分两个阶段： + 故障切换分两个阶段发生： - 1. 同一提供商内的**认证档案轮换**。 - 2. **模型后备**到 `agents.defaults.model.fallbacks` 中的下一个模型。 + 1. 同一提供商内的**凭证配置文件轮换**。 + 2. 回退到 `agents.defaults.model.fallbacks` 中的下一个模型，即**模型回退**。 - 对失败的档案会应用冷却时间（指数退避），因此即便某个提供商被限流或暂时失败，OpenClaw 仍能继续响应。 + 冷却时间会应用到失败的配置文件上（指数退避），因此即使某个提供商受到速率限制或暂时故障，OpenClaw 仍可继续响应。 - 限流桶不仅包括普通的 `429` 响应。OpenClaw - 还会将诸如 `Too many concurrent requests`、 + 速率限制分类不仅包含普通 `429` 响应。OpenClaw + 还会将 `Too many concurrent requests`、 `ThrottlingException`、`concurrency limit reached`、 `workers_ai ... quota limit exceeded`、`resource exhausted` 以及周期性 - 用量窗口限制（`weekly/monthly limit reached`）之类的消息视为值得故障切换的 - 限流情况。 + 使用窗口限制（`weekly/monthly limit reached`）视为值得故障切换的 + 速率限制。 - 某些看似计费相关的响应并不是 `402`，而某些 HTTP `402` - 响应也仍会保留在该瞬时故障桶中。如果提供商在 `401` 或 `403` 上返回了 + 某些看起来像计费问题的响应并不是 `402`，而某些 HTTP `402` + 响应也仍然属于瞬态分类。如果某个提供商在 `401` 或 `403` 上返回了 明确的计费文本，OpenClaw 仍可将其保留在 - 计费类别中，但提供商特定的文本匹配器会保持限定在 - 拥有该逻辑的提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。如果某个 `402` - 消息看起来更像是可重试的用量窗口限制或 - 组织/工作区支出上限（`daily limit reached, resets tomorrow`、 + 计费分类中，但提供商特定的文本匹配器仍仅限于对应提供商 + （例如 OpenRouter 的 `Key limit exceeded`）。如果某条 `402` + 消息看起来像是可重试的使用窗口或 + 组织 / 工作区支出限制（`daily limit reached, resets tomorrow`、 `organization spending limit exceeded`），OpenClaw 会将其视为 `rate_limit`，而不是长期计费禁用。 @@ -2564,55 +2576,30 @@ x-i18n: `request_too_large`、`input exceeds the maximum number of tokens`、 `input token count exceeds the maximum number of input tokens`、 `input is too long for the model` 或 `ollama error: context length - exceeded` 这样的特征会保留在压缩/重试路径中，而不会推进模型后备。 + exceeded` 这样的特征会停留在压缩 / 重试路径中，而不会推进模型 + 回退。 - 通用服务器错误文本的判断范围会刻意比“任何带 - unknown/error 的内容”更窄。OpenClaw 的确会把提供商上下文中的瞬时错误形态 - 视为值得故障切换的超时/过载信号，例如 Anthropic 的裸 - `An unknown error occurred`、OpenRouter 的裸 + 通用服务器错误文本的处理故意比“任何包含 + unknown / error 的内容”更窄。OpenClaw 确实会将提供商范围的瞬态形式 + 视为值得故障切换的超时 / 过载信号，例如 Anthropic 裸文本 `An unknown error occurred`、OpenRouter 裸文本 `Provider returned error`、停止原因错误如 `Unhandled stop reason: - error`、带瞬时服务器文本的 JSON `api_error` 负载 + error`、带有瞬态服务器文本的 JSON `api_error` 载荷 （`internal server error`、`unknown error, 520`、`upstream error`、`backend - error`），以及诸如 `ModelNotReadyException` 之类的提供商繁忙错误，只要提供商上下文匹配。 - 通用内部回退文本，比如 `LLM request failed with an unknown - error.`，本身会保持保守，不会单独触发模型后备。 + error`），以及 `ModelNotReadyException` 之类的提供商繁忙错误， + 但前提是提供商上下文 + 确实匹配。 + 像 `LLM request failed with an unknown + error.` 这样的通用内部回退文本则保持保守，不会单独触发模型回退。 - 这意味着系统尝试使用认证档案 ID `anthropic:default`，但无法在预期的认证存储中找到对应凭据。 + 这表示系统尝试使用凭证配置文件 ID `anthropic:default`，但在预期的凭证存储中找不到与之对应的凭证。 - **修复清单：** + **修复检查清单：** - - **确认认证档案存放位置**（新路径与旧路径） + - **确认凭证配置文件所在位置**（新路径与旧路径） - 当前：`~/.openclaw/agents//agent/auth-profiles.json` - 旧版：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） - **确认 Gateway 网关已加载你的环境变量** - - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但 Gateway 网关通过 systemd/launchd 运行，它可能不会继承。请将它放入 `~/.openclaw/.env` 或启用 `env.shellEnv`。 - - **确保你编辑的是正确的智能体** - - 多智能体设置意味着可能存在多个 `auth-profiles.json` 文件。 - - **做一次模型/认证状态检查** - - 使用 `openclaw models status` 查看已配置模型以及提供商是否已认证。 - - **针对 “No credentials found for profile anthropic” 的修复清单** - - 这意味着当前运行被固定到了一个 Anthropic 认证档案，但 Gateway 网关 - 在其认证存储中找不到它。 - - - **使用 Claude CLI** - - 在 gateway 主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 - - **如果你想改用 API 密钥** - - 将 `ANTHROPIC_API_KEY` 放入**gateway 主机**上的 `~/.openclaw/.env`。 - - 清除任何强制使用缺失档案的固定顺序： - - ```bash - openclaw models auth order clear --provider anthropic - ``` - - - **确认你是在 gateway 主机上运行命令** - - 在远程模式下，认证档案位于 gateway 机器上，而不是你的笔记本上。 - - - - - 如果你的模型配置将 Google Gemini 作为后备（或你切 \ No newline at end of file + - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd / launchd 运行 Gateway 网关，它可能不会继承该变量。请将其放入 `~/.openclaw/.env`，或 \ No newline at end of file diff --git a/docs/zh-CN/help/testing.md b/docs/zh-CN/help/testing.md index 68912ca7c..46a1bb1e6 100644 --- a/docs/zh-CN/help/testing.md +++ b/docs/zh-CN/help/testing.md @@ -1,135 +1,136 @@ --- read_when: - 在本地或 CI 中运行测试时 - - 为模型 / 提供商缺陷添加回归测试时 + - 为模型/提供商 bug 添加回归测试时 - 调试 Gateway 网关 + 智能体行为时 -summary: 测试工具包：单元 / e2e / live 测试套件、Docker 运行器，以及每类测试覆盖的内容 +summary: 测试套件：单元/e2e/live 套件、Docker 运行器，以及各类测试覆盖内容 title: 测试 x-i18n: - generated_at: "2026-04-06T12:44:29Z" + generated_at: "2026-04-06T15:30:41Z" model: gpt-5.4 provider: openai - source_hash: b18d68d08b851dea994af250f7cb833a34523601d04fd2f118def9777c961b55 + source_hash: a2c8af6ff9cbef3d148f9d51016d9bc35b069a4467fb72874be265872ca13da1 source_path: help/testing.md workflow: 15 --- # 测试 -OpenClaw 有三个 Vitest 测试套件（单元 / 集成、e2e、live）以及一小组 Docker 运行器。 +OpenClaw 有三类 Vitest 套件（单元/集成、e2e、live）以及少量 Docker 运行器。 本文档是一份“我们如何测试”的指南： -- 每个测试套件覆盖什么（以及它刻意 _不_ 覆盖什么） -- 常见工作流该运行哪些命令（本地、推送前、调试） -- live 测试如何发现凭证并选择模型 / 提供商 -- 如何为真实世界中的模型 / 提供商问题添加回归测试 +- 每个套件覆盖什么内容（以及它刻意**不**覆盖什么） +- 常见工作流应运行哪些命令（本地、推送前、调试） +- live 测试如何发现凭证并选择模型/提供商 +- 如何为真实世界中的模型/提供商问题添加回归测试 ## 快速开始 -大多数时候： +大多数情况下： -- 完整门槛检查（预期在推送前执行）：`pnpm build && pnpm check && pnpm test` -- 在配置较充足的机器上更快地运行本地完整测试套件：`pnpm test:max` -- 直接使用 Vitest 观察模式循环（现代 projects 配置）：`pnpm test:watch` -- 现在直接指定文件也会路由扩展 / 渠道路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- 完整 gate（推送前预期要运行）：`pnpm build && pnpm check && pnpm test` +- 在配置较好的机器上更快地运行本地完整套件：`pnpm test:max` +- 直接进入 Vitest watch 循环：`pnpm test:watch` +- 现在直接指定文件也会路由扩展/渠道路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -当你修改了测试或想获得更多信心时： +当你修改了测试或希望获得更高信心时： -- 覆盖率门槛检查：`pnpm test:coverage` -- E2E 测试套件：`pnpm test:e2e` +- 覆盖率 gate：`pnpm test:coverage` +- E2E 套件：`pnpm test:e2e` -调试真实提供商 / 模型时（需要真实凭证）： +当你调试真实提供商/模型时（需要真实凭证）： -- Live 测试套件（模型 + Gateway 网关 工具 / 图像探测）：`pnpm test:live` -- 安静地只跑一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Live 套件（模型 + Gateway 网关工具/图像探测）：`pnpm test:live` +- 安静地只针对一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` -提示：如果你只需要一个失败用例，优先使用下面介绍的 allowlist 环境变量来缩小 live 测试范围。 +提示：当你只需要定位一个失败用例时，优先通过下面描述的允许列表环境变量缩小 live 测试范围。 -## 测试套件（各自运行位置） +## 测试套件（各自在哪里运行） -可以把这些测试套件理解为“真实度逐步增加”（同时不稳定性 / 成本也逐步增加）： +可以把这些套件理解为“现实性逐步增强”（同时波动性/成本也逐步上升）： ### 单元 / 集成（默认） - 命令：`pnpm test` - 配置：通过 `vitest.config.ts` 使用原生 Vitest `projects` -- 文件：`src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 下的核心 / 单元测试清单，以及由 `vitest.unit.config.ts` 覆盖的白名单 `ui` Node 测试 +- 文件：`src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 下的 core/unit 测试清单，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` Node 测试 - 范围： - 纯单元测试 - - 进程内集成测试（Gateway 网关 身份验证、路由、工具、解析、配置） - - 已知缺陷的确定性回归测试 + - 进程内集成测试（Gateway 网关认证、路由、工具、解析、配置） + - 已知 bug 的确定性回归测试 - 预期： - 在 CI 中运行 - 不需要真实密钥 - 应该快速且稳定 -- Projects 说明： - - `pnpm test`、`pnpm test:watch` 和 `pnpm test:changed` 现在都使用同一份原生 Vitest 根级 `projects` 配置。 - - 直接文件过滤现在会通过根项目图原生路由，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 无需自定义包装器也能工作。 +- 项目说明： + - 未指定目标的 `pnpm test` 仍然使用原生 Vitest 根 `projects` 配置。 + - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会先将显式文件/目录目标路由到作用域更小的 lane，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不必承担完整根项目启动开销。 + - `pnpm test:changed` 会在 diff 仅涉及可路由的源文件/测试文件时，把变更的 git 路径展开到相同的 scoped lane；若修改了配置/设置，则仍会回退到更宽泛的根项目重跑。 + - 选定的 `plugin-sdk` 和 `commands` 测试也会路由到专门的轻量 lane，跳过 `test/setup-openclaw-runtime.ts`；有状态/运行时较重的文件仍保留在现有 lane 上。 + - 选定的 `plugin-sdk` 和 `commands` 辅助源文件也会在 changed 模式运行时映射到这些轻量 lane 中的显式同级测试，因此辅助文件变更不会导致该目录下整个重型套件重跑。 - 嵌入式运行器说明： - 当你修改消息工具发现输入或压缩运行时上下文时， - 请同时保留两个层级的覆盖。 - - 为纯路由 / 规范化边界添加有针对性的辅助函数回归测试。 - - 同时也要保持嵌入式运行器集成测试套件健康： + 需要同时保持两层覆盖。 + - 为纯路由/标准化边界添加聚焦的辅助回归测试。 + - 同时还要确保嵌入式运行器集成套件保持健康： `src/agents/pi-embedded-runner/compact.hooks.test.ts`、 - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`，以及 + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` 以及 `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - 这些测试套件用于验证带作用域的 id 和压缩行为仍然会沿真实的 - `run.ts` / `compact.ts` 路径传递；仅有辅助函数测试 - 不能充分替代这些集成路径。 -- 线程池说明： + - 这些套件会验证作用域 id 和压缩行为仍然通过真实的 `run.ts` / `compact.ts` 路径流动；仅辅助层测试并不足以替代这些集成路径。 +- 池说明： - 基础 Vitest 配置现在默认使用 `threads`。 - - 共享 Vitest 配置也固定了 `isolate: false`，并在根 projects、e2e 和 live 配置中使用非隔离运行器。 - - 根级 UI 通道保留其 `jsdom` 设置和优化器，但现在也运行在共享的非隔离运行器上。 - - `pnpm test` 从根级 `vitest.config.ts` projects 配置继承相同的 `threads` + `isolate: false` 默认值。 - - 共享的 `scripts/run-vitest.mjs` 启动器现在默认还会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。如果你需要与原生 V8 行为做对比，可设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`。 -- 快速本地迭代说明： - - `pnpm test:changed` 会使用原生 projects 配置并带上 `--changed origin/main` 运行。 - - `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的原生 projects 配置，只是使用更高的 worker 上限。 - - 本地 worker 自动缩放现在有意采取更保守策略，并且当主机平均负载已经较高时也会回退，因此默认情况下多个并发 Vitest 运行对系统的影响更小。 - - 基础 Vitest 配置会将 projects / config 文件标记为 `forceRerunTriggers`，以便在测试布线发生变化时 changed 模式的重跑仍然正确。 - - 在受支持的主机上，该配置保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你想为直接性能分析指定一个明确的缓存位置，可设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。 + - 共享 Vitest 配置还固定了 `isolate: false`，并在根项目、e2e 和 live 配置中使用非隔离运行器。 + - 根 UI lane 保留了其 `jsdom` 设置和优化器，但现在也运行在共享的非隔离运行器上。 + - `pnpm test` 继承了根 `vitest.config.ts` 项目配置中的相同 `threads` + `isolate: false` 默认值。 + - 共享的 `scripts/run-vitest.mjs` 启动器现在还会默认给 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。如果你需要与原生 V8 行为对比，请设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`。 +- 本地快速迭代说明： + - `pnpm test:changed` 会在变更路径可清晰映射到更小套件时路由到 scoped lane。 + - `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由行为，只是提高了 worker 上限。 + - 本地 worker 自动缩放现在有意更保守，并且在主机平均负载已较高时也会退避，因此默认情况下多个并发 Vitest 运行对机器的影响会更小。 + - 基础 Vitest 配置将项目/配置文件标记为 `forceRerunTriggers`，从而在测试接线发生变化时保证 changed 模式的重跑仍然正确。 + - 在受支持主机上，该配置会保持 `OPENCLAW_VITEST_FS_MODULE_CACHE` 启用；如果你想为直接分析指定一个明确的缓存位置，请设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。 - 性能调试说明： - - `pnpm test:perf:imports` 会启用 Vitest 导入耗时报告以及导入明细输出。 - - `pnpm test:perf:imports:changed` 会将相同的分析视图限制为自 `origin/main` 以来变更的文件。 - - `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动和转换开销写入主线程 CPU profile。 - - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元测试套件写入运行器 CPU + 堆 profile。 + - `pnpm test:perf:imports` 会启用 Vitest 导入时长报告以及导入拆解输出。 + - `pnpm test:perf:imports:changed` 会将同样的分析视图限定到自 `origin/main` 以来发生变化的文件。 + - `pnpm test:perf:profile:main` 会为 Vitest/Vite 启动和 transform 开销写出主线程 CPU profile。 + - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元测试套件写出运行器 CPU + heap profile。 -### E2E（Gateway 网关 冒烟测试） +### E2E（Gateway 网关冒烟） - 命令：`pnpm test:e2e` - 配置：`vitest.e2e.config.ts` - 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts` - 运行时默认值： - - 使用 Vitest `threads` 且 `isolate: false`，与仓库其余部分保持一致。 + - 使用 Vitest `threads` 且 `isolate: false`，与仓库其他部分一致。 - 使用自适应 worker（CI：最多 2 个，本地：默认 1 个）。 - 默认以静默模式运行，以减少控制台 I/O 开销。 - 常用覆盖项： - - `OPENCLAW_E2E_WORKERS=` 强制设置 worker 数量（上限为 16）。 - - `OPENCLAW_E2E_VERBOSE=1` 重新启用详细控制台输出。 + - `OPENCLAW_E2E_WORKERS=`：强制设置 worker 数量（上限 16）。 + - `OPENCLAW_E2E_VERBOSE=1`：重新启用详细控制台输出。 - 范围： - - 多实例 Gateway 网关 端到端行为 - - WebSocket / HTTP 接口、节点配对以及更重的网络场景 + - 多实例 Gateway 网关端到端行为 + - WebSocket/HTTP 接口、节点配对和更重的网络交互 - 预期： - 在 CI 中运行（当流水线启用时） - 不需要真实密钥 - - 比单元测试有更多可变因素（可能更慢） + - 比单元测试有更多运动部件（可能更慢） -### E2E：OpenShell 后端冒烟测试 +### E2E：OpenShell 后端冒烟 - 命令：`pnpm test:e2e:openshell` - 文件：`test/openshell-sandbox.e2e.test.ts` - 范围： - 通过 Docker 在主机上启动一个隔离的 OpenShell Gateway 网关 - - 从临时本地 Dockerfile 创建一个沙箱 - - 通过真实的 `sandbox ssh-config` + SSH exec 运行 OpenClaw 的 OpenShell 后端 - - 通过沙箱 fs bridge 验证远端标准文件系统行为 + - 从一个临时本地 Dockerfile 创建沙箱 + - 通过真实的 `sandbox ssh-config` + SSH exec 测试 OpenClaw 的 OpenShell 后端 + - 通过沙箱 fs bridge 验证远程规范文件系统行为 - 预期： - - 仅在选择加入时运行；不属于默认的 `pnpm test:e2e` 执行内容 - - 需要本地 `openshell` CLI 和可用的 Docker daemon - - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 Gateway 网关 和沙箱 + - 仅按需启用；不属于默认 `pnpm test:e2e` 运行 + - 需要本地 `openshell` CLI 以及可用的 Docker daemon + - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 Gateway 网关和沙箱 - 常用覆盖项： - - `OPENCLAW_E2E_OPENSHELL=1`：在手动运行更广泛的 e2e 测试套件时启用该测试 + - `OPENCLAW_E2E_OPENSHELL=1`：在手动运行更宽泛 e2e 套件时启用该测试 - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`：指向非默认 CLI 二进制或包装脚本 ### Live（真实提供商 + 真实模型） @@ -137,127 +138,127 @@ OpenClaw 有三个 Vitest 测试套件（单元 / 集成、e2e、live）以及 - 命令：`pnpm test:live` - 配置：`vitest.live.config.ts` - 文件：`src/**/*.live.test.ts` -- 默认：由 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`） +- 默认：由 `pnpm test:live` **启用**（会设置 `OPENCLAW_LIVE_TEST=1`） - 范围： - - “这个提供商 / 模型在 _今天_ 配合真实凭证是否真的能工作？” - - 捕捉提供商格式变化、工具调用怪癖、身份验证问题和限流行为 + - “这个提供商/模型今天在真实凭证下是否真的可用？” + - 捕获提供商格式变化、工具调用怪癖、认证问题和限流行为 - 预期： - - 设计上不以 CI 稳定为目标（真实网络、真实提供商策略、配额、故障） - - 需要花钱 / 消耗速率限制 - - 优先运行缩小范围的子集，而不是“全部” -- Live 运行会读取 `~/.profile`，以补齐缺失的 API 密钥。 -- 默认情况下，live 运行仍然会隔离 `HOME`，并将配置 / 身份验证材料复制到临时测试 home 中，这样单元测试夹具就不会修改你真实的 `~/.openclaw`。 -- 仅当你明确需要 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 -- `pnpm test:live` 现在默认以更安静的模式运行：它会保留 `[live] ...` 进度输出，但会抑制额外的 `~/.profile` 提示，并静音 Gateway 网关 启动日志 / Bonjour 噪音。如果你想恢复完整启动日志，可设置 `OPENCLAW_LIVE_TEST_QUIET=0`。 -- API 密钥轮换（提供商专属）：设置 `*_API_KEYS`，使用逗号 / 分号格式，或设置 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或者通过 `OPENCLAW_LIVE_*_KEY` 进行逐个 live 覆盖；测试在收到限流响应时会重试。 -- 进度 / 心跳输出： - - Live 测试套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获较安静，较长时间的提供商调用也能显示为仍在活动。 - - `vitest.live.config.ts` 禁用了 Vitest 控制台拦截，因此在 live 运行期间，提供商 / Gateway 网关 进度行会立即流式输出。 - - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型心跳。 - - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 Gateway 网关 / 探测心跳。 + - 设计上不是 CI 稳定项（真实网络、真实提供商策略、配额、故障） + - 会花钱 / 消耗速率限制 + - 优先运行缩小后的子集，而不是“全部” +- Live 运行会读取 `~/.profile` 以获取缺失的 API 密钥。 +- 默认情况下，live 运行仍会隔离 `HOME`，并将配置/认证材料复制到临时测试 home 中，这样单元测试 fixture 不会改动你真实的 `~/.openclaw`。 +- 仅当你明确需要让 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 +- `pnpm test:live` 现在默认使用更安静的模式：保留 `[live] ...` 进度输出，但会抑制额外的 `~/.profile` 提示，并静音 Gateway 网关引导日志/Bonjour 噪声。如果你希望恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。 +- API 密钥轮换（提供商特定）：设置逗号/分号格式的 `*_API_KEYS`，或 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），也可以通过 `OPENCLAW_LIVE_*_KEY` 做每个 live 运行的覆盖；测试会在遇到限流响应时重试。 +- 进度/心跳输出： + - Live 套件现在会向 stderr 输出进度行，因此即使 Vitest 控制台捕获处于安静模式，长时间的提供商调用也能显示正在运行。 + - `vitest.live.config.ts` 禁用了 Vitest 控制台拦截，因此提供商/Gateway 网关进度行会在 live 运行期间立即流出。 + - 用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整 direct-model 心跳。 + - 用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 Gateway 网关/探测心跳。 -## 我应该运行哪个测试套件？ +## 我应该运行哪个套件？ -使用这个决策表： +请使用下面这张决策表： -- 编辑逻辑 / 测试：运行 `pnpm test`（如果改动较多，再加上 `pnpm test:coverage`） -- 触及 Gateway 网关 网络 / WS 协议 / 配对：加跑 `pnpm test:e2e` -- 调试“我的 bot 挂了” / 提供商专属失败 / 工具调用：运行缩小范围的 `pnpm test:live` +- 编辑逻辑/测试：运行 `pnpm test`（如果改动较多，也运行 `pnpm test:coverage`） +- 涉及 Gateway 网关网络 / WS 协议 / 配对：增加 `pnpm test:e2e` +- 调试“我的 bot 挂了” / 提供商特定失败 / 工具调用：运行缩小后的 `pnpm test:live` ## Live：Android 节点能力扫描 - 测试：`src/gateway/android-node.capabilities.live.test.ts` - 脚本：`pnpm android:test:integration` -- 目标：调用连接的 Android 节点当前发布的**每一条命令**，并断言命令契约行为。 +- 目标：调用已连接 Android 节点**当前宣告的每一条命令**，并断言命令契约行为。 - 范围： - - 需要预先满足条件 / 手动设置（该测试套件不会安装 / 运行 / 配对应用）。 - - 针对所选 Android 节点逐条验证 Gateway 网关 `node.invoke`。 -- 所需预先设置： - - Android 应用已经连接并配对到 Gateway 网关。 + - 需预先手动完成设置（该套件不会安装/运行/配对应用）。 + - 针对所选 Android 节点，逐条验证 Gateway 网关 `node.invoke`。 +- 所需预设： + - Android 应用已连接并配对到 Gateway 网关。 - 应用保持在前台。 - - 为你期望通过的能力授予权限 / 捕获授权。 -- 可选目标覆盖： + - 已授予你希望通过的能力所需的权限/捕获同意。 +- 可选目标覆盖项： - `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。 - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。 - 完整 Android 设置详情：[Android App](/zh-CN/platforms/android) -## Live：模型冒烟测试（profile keys） +## Live：模型冒烟（profile keys） -Live 测试分成两层，这样我们可以隔离失败原因： +Live 测试分成两层，以便隔离失败点： -- “直接模型”告诉我们提供商 / 模型是否至少能用给定密钥正常响应。 -- “Gateway 网关 冒烟测试”告诉我们完整的 Gateway 网关 + 智能体流水线是否适用于该模型（会话、历史、工具、沙箱策略等）。 +- “Direct model” 告诉我们：在给定密钥下，提供商/模型是否至少能响应。 +- “Gateway smoke” 告诉我们：该模型在完整 Gateway 网关 + 智能体流水线中是否工作正常（会话、历史、工具、沙箱策略等）。 ### 第 1 层：直接模型补全（无 Gateway 网关） - 测试：`src/agents/models.profiles.live.test.ts` - 目标： - - 枚举发现到的模型 - - 使用 `getApiKeyForModel` 选择你有凭证的模型 - - 为每个模型运行一次小型补全（在需要时也运行有针对性的回归测试） + - 枚举已发现的模型 + - 使用 `getApiKeyForModel` 选择你具有凭证的模型 + - 对每个模型执行一个小型补全（并在需要时执行针对性回归） - 启用方式： - - `pnpm test:live`（或直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） -- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，它是 modern 的别名）才能真正运行该测试套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关 冒烟测试 -- 如何选择模型： - - `OPENCLAW_LIVE_MODELS=modern` 运行 modern allowlist（Opus / Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） + - `pnpm test:live`（或在直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） +- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，是 modern 的别名）才会真正运行该套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关冒烟 +- 选择模型的方法： + - `OPENCLAW_LIVE_MODELS=modern` 运行 modern allowlist（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - `OPENCLAW_LIVE_MODELS=all` 是 modern allowlist 的别名 - - 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（逗号分隔的 allowlist） -- 如何选择提供商： - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的 allowlist） + - 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（逗号分隔允许列表） +- 选择提供商的方法： + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔允许列表） - 密钥来源： - 默认：profile 存储和环境变量回退 - - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以强制**仅使用 profile 存储** -- 存在原因： - - 将“提供商 API 坏了 / 密钥无效”与“Gateway 网关 智能体流水线坏了”分离 - - 容纳小而隔离的回归测试（例如：OpenAI Responses / Codex Responses 推理重放 + 工具调用流程） + - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用 profile 存储** +- 该层存在的原因： + - 将“提供商 API 坏了 / 密钥无效”与“Gateway 网关智能体流水线坏了”分离 + - 容纳小而隔离的回归测试（例如：OpenAI Responses/Codex Responses 的推理回放 + 工具调用流程） -### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（也就是 “@openclaw” 实际在做什么） +### 第 2 层：Gateway 网关 + dev 智能体冒烟（也就是 “@openclaw” 实际在做什么） - 测试：`src/gateway/gateway-models.profiles.live.test.ts` - 目标： - 启动一个进程内 Gateway 网关 - - 创建 / 修补一个 `agent:dev:*` 会话（每次运行都覆盖模型） - - 迭代有密钥的模型，并断言： + - 创建/修补一个 `agent:dev:*` 会话（每次运行按模型覆盖） + - 遍历带密钥的模型并断言： - “有意义的”响应（无工具） - - 真实工具调用可用（read 探测） - - 可选的额外工具探测（exec+read 探测） - - OpenAI 回归路径（仅工具调用 → 后续跟进）继续可用 -- 探测细节（这样你可以快速解释失败）： - - `read` 探测：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 它并回显该 nonce。 - - `exec+read` 探测：测试要求智能体通过 `exec` 将一个 nonce 写入临时文件，然后再 `read` 回来。 - - 图像探测：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat `。 + - 真实工具调用可用（read probe） + - 可选的额外工具探测可用（exec+read probe） + - OpenAI 回归路径（仅工具调用 → 后续跟进）仍然有效 +- Probe 细节（这样你可以快速解释失败）： + - `read` probe：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件后回显 nonce。 + - `exec+read` probe：测试会要求智能体用 `exec` 将 nonce 写入一个临时文件，然后再 `read` 读回。 + - 图像 probe：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat `。 - 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。 - 启用方式： - - `pnpm test:live`（或直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） -- 如何选择模型： - - 默认：modern allowlist（Opus / Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） + - `pnpm test:live`（或在直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） +- 选择模型的方法： + - 默认：modern allowlist（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是 modern allowlist 的别名 - - 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号分隔列表）来缩小范围 -- 如何选择提供商（避免“OpenRouter 全量”）： - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔的 allowlist） -- 工具 + 图像探测在这个 live 测试中始终启用： - - `read` 探测 + `exec+read` 探测（工具压力测试） - - 当模型声明支持图像输入时，会运行图像探测 - - 流程（高层级）： - - 测试生成一个带有 “CAT” + 随机代码的小型 PNG（`src/gateway/live-image-probe.ts`） + - 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）以缩小范围 +- 选择提供商的方法（避免“OpenRouter 全都跑一遍”）： + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔允许列表） +- 在这个 live 测试中，工具 + 图像探测始终开启： + - `read` probe + `exec+read` probe（工具压力测试） + - 当模型宣告支持图像输入时会运行 image probe + - 流程（高层概览）： + - 测试生成一个带有 “CAT” + 随机代码的小 PNG（`src/gateway/live-image-probe.ts`） - 通过 `agent` `attachments: [{ mimeType: "image/png", content: "" }]` 发送 - - Gateway 网关 将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） - - 嵌入式智能体向模型转发一条多模态用户消息 - - 断言：回复包含 `cat` + 该代码（OCR 容错：允许少量错误） + - Gateway 网关将附件解析到 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） + - 嵌入式智能体将多模态用户消息转发给模型 + - 断言：回复包含 `cat` + 代码（OCR 容忍少量小错误） -提示：要查看你的机器上可以测试什么（以及精确的 `provider/model` id），请运行： +提示：如果你想查看自己机器上能测试什么（以及精确的 `provider/model` id），请运行： ```bash openclaw models list openclaw models list --json ``` -## Live：CLI 后端冒烟测试（Codex CLI 或其他本地 CLI） +## Live：CLI 后端冒烟（Codex CLI 或其他本地 CLI） - 测试：`src/gateway/gateway-cli-backend.live.test.ts` -- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线，而不触碰你的默认配置。 +- 目标：在不触碰你的默认配置的情况下，使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线。 - 启用： - - `pnpm test:live`（或直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） + - `pnpm test:live`（或在直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） - `OPENCLAW_LIVE_CLI_BACKEND=1` - 默认值： - 模型：`codex-cli/gpt-5.4` @@ -267,10 +268,10 @@ openclaw models list --json - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会注入到提示词中）。 - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 通过 CLI 参数而不是提示词注入传递图像文件路径。 - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）用于控制在设置 `IMAGE_ARG` 时如何传递图像参数。 - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮并验证恢复流程。 + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会被注入提示词）。 + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 将图像文件路径作为 CLI 参数传递，而不是注入到提示词中。 + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）控制在设置 `IMAGE_ARG` 时图像参数的传递方式。 + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮消息并验证 resume 流程。 示例： @@ -289,31 +290,31 @@ pnpm test:docker:live-cli-backend 说明： - Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。 -- 它会在仓库 Docker 镜像内，以非 root 的 `node` 用户身份运行 live CLI 后端冒烟测试。 -- 对于 `codex-cli`，它会将 Linux 版 `@openai/codex` 包安装到可缓存的可写前缀 `OPENCLAW_DOCKER_CLI_TOOLS_DIR`（默认：`~/.cache/openclaw/docker-cli-tools`）中。 +- 它会在仓库 Docker 镜像中以非 root 的 `node` 用户身份运行 live CLI 后端冒烟。 +- 对于 `codex-cli`，它会将 Linux `@openai/codex` 包安装到一个可缓存的可写前缀 `OPENCLAW_DOCKER_CLI_TOOLS_DIR`（默认：`~/.cache/openclaw/docker-cli-tools`）中。 -## Live：ACP 绑定冒烟测试（`/acp spawn ... --bind here`） +## Live：ACP 绑定冒烟（`/acp spawn ... --bind here`） - 测试：`src/gateway/gateway-acp-bind.live.test.ts` - 目标：使用 live ACP 智能体验证真实 ACP 会话绑定流程： - 发送 `/acp spawn --bind here` - 就地绑定一个合成的消息渠道会话 - - 在同一会话上发送普通后续消息 - - 验证后续消息确实落入已绑定的 ACP 会话记录 + - 在同一会话上发送一条普通跟进消息 + - 验证跟进内容落入已绑定的 ACP 会话转录中 - 启用： - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - 默认值： - ACP 智能体：`claude` - - 合成渠道：类似 Slack 私信 的会话上下文 + - 合成渠道：Slack 私信风格的会话上下文 - ACP 后端：`acpx` - 覆盖项： - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - 说明： - - 这个通道使用 Gateway 网关 `chat.send` 接口，并带有仅管理员可用的合成来源路由字段，这样测试就能附加消息渠道上下文，而无需假装对外投递。 - - 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用内置 `acpx` 插件的内建智能体注册表来选择 ACP 测试智能体。 + - 该 lane 使用 Gateway 网关 `chat.send` 接口，并通过仅管理员可用的合成 originating-route 字段附加消息渠道上下文，而不是假装对外发送。 + - 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用嵌入式 `acpx` 插件内建的智能体注册表来选择对应 ACP harness 智能体。 示例： @@ -332,42 +333,42 @@ pnpm test:docker:live-acp-bind Docker 说明： - Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。 -- 它会读取 `~/.profile`，将匹配的 CLI 身份验证材料暂存到容器中，把 `acpx` 安装到可写 npm 前缀，然后在缺失时安装请求的 live CLI（`@anthropic-ai/claude-code` 或 `@openai/codex`）。 -- 在 Docker 内部，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，这样 acpx 就能保留从已读取 profile 中获得的提供商环境变量，以供子测试 CLI 使用。 +- 它会读取 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，将 `acpx` 安装到可写 npm 前缀中，然后在缺失时安装所需的 live CLI（`@anthropic-ai/claude-code` 或 `@openai/codex`）。 +- 在 Docker 内部，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，这样 acpx 能让来自已读取 profile 的提供商环境变量继续对其子 harness CLI 可见。 ### 推荐的 live 配方 -范围窄、明确的 allowlist 最快，也最不容易波动： +范围小且显式的允许列表速度最快，也最不容易波动： -- 单模型，直接（无 Gateway 网关）： +- 单个模型，direct（无 Gateway 网关）： - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- 单模型，Gateway 网关 冒烟测试： +- 单个模型，Gateway 网关冒烟： - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- 多个提供商上的工具调用： +- 跨多个提供商的工具调用： - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- 聚焦 Google（Gemini API key + Antigravity）： - - Gemini（API key）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- 聚焦 Google（Gemini API 密钥 + Antigravity）： + - Gemini（API 密钥）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` 说明： -- `google/...` 使用 Gemini API（API key）。 -- `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist 风格的智能体端点）。 -- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（单独的身份验证 + 工具行为差异）。 -- Gemini API 与 Gemini CLI： - - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / profile auth）；这也是大多数用户提到 “Gemini” 时的含义。 - - CLI：OpenClaw 调用本地 `gemini` 二进制；它有自己的身份验证，并且行为可能不同（流式传输 / 工具支持 / 版本偏差）。 +- `google/...` 使用 Gemini API（API 密钥）。 +- `google-antigravity/...` 使用 Antigravity OAuth bridge（类似 Cloud Code Assist 风格的智能体端点）。 +- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（单独的认证 + 工具行为差异）。 +- Gemini API 与 Gemini CLI 的区别： + - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / profile 认证）；大多数用户说的 “Gemini” 指的就是这个。 + - CLI：OpenClaw 会调用本地 `gemini` 二进制；它有自己的认证，并且行为可能不同（流式传输/工具支持/版本偏差）。 ## Live：模型矩阵（我们覆盖什么） -这里没有固定的“CI 模型列表”（live 是可选加入的），但以下是建议在有密钥的开发机器上定期覆盖的**推荐**模型。 +没有固定的“CI 模型列表”（live 为按需启用），但以下是**推荐**在有密钥的开发机器上定期覆盖的模型。 -### Modern 冒烟测试集（工具调用 + 图像） +### Modern 冒烟集合（工具调用 + 图像） -这是我们预期应持续保持可用的“常用模型”运行： +这是我们期望持续保持可用的“常见模型”运行集合： - OpenAI（非 Codex）：`openai/gpt-5.4`（可选：`openai/gpt-5.4-mini`） - OpenAI Codex：`openai-codex/gpt-5.4` @@ -377,12 +378,12 @@ Docker 说明： - Z.AI（GLM）：`zai/glm-4.7` - MiniMax：`minimax/MiniMax-M2.7` -运行带工具 + 图像的 Gateway 网关 冒烟测试： +运行带工具 + 图像的 Gateway 网关冒烟： `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### 基线：工具调用（Read + 可选 Exec） -每个提供商系列至少选一个： +每个提供商家族至少选一个： - OpenAI：`openai/gpt-5.4`（或 `openai/gpt-5.4-mini`） - Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`） @@ -390,51 +391,51 @@ Docker 说明： - Z.AI（GLM）：`zai/glm-4.7` - MiniMax：`minimax/MiniMax-M2.7` -可选的附加覆盖（有更好，没有也可以）： +可选额外覆盖（有更好，没有也可以）： - xAI：`xai/grok-4`（或最新可用版本） -- Mistral：`mistral/`…（选择一个你已启用、具备 “tools” 能力的模型） +- Mistral：`mistral/`…（选择一个你已启用、支持工具的模型） - Cerebras：`cerebras/`…（如果你有访问权限） - LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式） ### 视觉：图像发送（附件 → 多模态消息） -在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个具备图像能力的模型（Claude / Gemini / OpenAI 支持视觉的变体等），以覆盖图像探测。 +在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude/Gemini/支持视觉的 OpenAI 变体等），以覆盖图像 probe。 ### 聚合器 / 替代 Gateway 网关 -如果你启用了相应密钥，我们也支持通过以下方式测试： +如果你启用了对应密钥，我们也支持通过以下方式测试： -- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 找出支持工具 + 图像的候选项） -- OpenCode：Zen 用 `opencode/...`，Go 用 `opencode-go/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 身份验证） +- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选） +- OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证） -你也可以在 live 矩阵中加入更多提供商（如果你有凭证 / 配置）： +你还可以将更多提供商纳入 live 矩阵（如果你有凭证/配置）： - 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot` -- 通过 `models.providers`（自定义端点）：`minimax`（云 / API），以及任意 OpenAI / Anthropic 兼容代理（LM Studio、vLLM、LiteLLM 等） +- 通过 `models.providers`（自定义端点）：`minimax`（云/API），以及任何 OpenAI/Anthropic 兼容代理（LM Studio、vLLM、LiteLLM 等） -提示：不要试图在文档中硬编码“所有模型”。权威列表始终是你机器上的 `discoverModels(...)` 返回结果 + 当前可用的密钥。 +提示：不要试图在文档里硬编码“所有模型”。权威列表始终是你机器上 `discoverModels(...)` 的返回结果 + 当前可用的密钥。 -## 凭证（切勿提交） +## 凭证（绝不提交） Live 测试发现凭证的方式与 CLI 相同。实际含义如下： -- 如果 CLI 能工作，live 测试通常也能找到相同的密钥。 -- 如果 live 测试提示“无凭证”，就像调试 `openclaw models list` / 模型选择那样去调试。 +- 如果 CLI 可用，live 测试也应该能找到相同的密钥。 +- 如果 live 测试提示“无凭证”，排查方式应与排查 `openclaw models list` / 模型选择相同。 -- 按智能体划分的 auth profiles：`~/.openclaw/agents//agent/auth-profiles.json`（这就是 live 测试中 “profile keys” 的含义） +- 每个智能体的认证 profile：`~/.openclaw/agents//agent/auth-profiles.json`（这就是 live 测试里 “profile keys” 的含义） - 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`） -- 旧版状态目录：`~/.openclaw/credentials/`（如存在，会复制进暂存的 live home，但它不是主 profile-key 存储） -- 默认情况下，live 本地运行会将当前活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 身份验证目录复制到临时测试 home；暂存配置中的 `agents.*.workspace` / `agentDir` 路径覆盖会被去除，这样探测就不会落到你真实主机工作区上。 +- 旧版状态目录：`~/.openclaw/credentials/`（若存在会复制到暂存的 live home 中，但它不是主 profile-key 存储） +- 本地 live 运行默认会将当前配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到一个临时测试 home 中；在该暂存配置里会移除 `agents.*.workspace` / `agentDir` 路径覆盖，这样 probe 就不会落到你真实主机工作区上。 -如果你想依赖环境变量密钥（例如导出在你的 `~/.profile` 中），请在本地测试前运行 `source ~/.profile`，或者使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。 +如果你想依赖环境变量中的密钥（例如在你的 `~/.profile` 中导出），请在本地测试前运行 `source ~/.profile`，或者使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。 ## Deepgram live（音频转录） - 测试：`src/media-understanding/providers/deepgram/audio.live.test.ts` - 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## BytePlus 编码计划 live +## BytePlus 编码规划 live - 测试：`src/agents/byteplus.live.test.ts` - 启用：`BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` @@ -445,9 +446,9 @@ Live 测试发现凭证的方式与 CLI 相同。实际含义如下： - 测试：`extensions/comfy/comfy.live.test.ts` - 启用：`OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - 范围： - - 覆盖内置 comfy 图像、视频和 `music_generate` 路径 - - 除非配置了 `models.providers.comfy.`，否则会跳过各项能力 - - 在修改 comfy 工作流提交、轮询、下载或插件注册后很有用 + - 测试内置 comfy 图像、视频和 `music_generate` 路径 + - 若未配置 `models.providers.comfy.`，则会跳过对应能力 + - 在修改 comfy 工作流提交、轮询、下载或插件注册后特别有用 ## 图像生成 live @@ -456,8 +457,8 @@ Live 测试发现凭证的方式与 CLI 相同。实际含义如下： - 范围： - 枚举每个已注册的图像生成提供商插件 - 在探测前从你的登录 shell（`~/.profile`）中加载缺失的提供商环境变量 - - 默认优先使用 live / 环境变量 API 密钥，而不是已存储的 auth profiles，这样 `auth-profiles.json` 里的过期测试密钥就不会掩盖真实的 shell 凭证 - - 跳过没有可用 auth / profile / model 的提供商 + - 默认优先使用 live/env API 密钥，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖你 shell 中真实可用的凭证 + - 跳过没有可用认证/profile/模型的提供商 - 通过共享运行时能力运行标准图像生成变体： - `google:flash-generate` - `google:pro-generate` @@ -470,108 +471,177 @@ Live 测试发现凭证的方式与 CLI 相同。实际含义如下： - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- 可选身份验证行为： - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile-store 身份验证并忽略仅环境变量的覆盖 +- 可选认证行为： + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile 存储认证并忽略仅环境变量的覆盖 ## 音乐生成 live - 测试：`extensions/music-generation-providers.live.test.ts` - 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - 范围： - - 覆盖共享内置 music-generation 提供商路径 + - 测试共享的内置音乐生成提供商路径 - 当前覆盖 Google 和 MiniMax - 在探测前从你的登录 shell（`~/.profile`）中加载提供商环境变量 - - 跳过没有可用 auth / profile / model 的提供商 + - 默认优先使用 live/env API 密钥，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖你 shell 中真实可用的凭证 + - 跳过没有可用认证/profile/模型的提供商 + - 在可用时运行两个已声明的运行时模式： + - `generate`：仅使用提示词输入 + - `edit`：当提供商声明 `capabilities.edit.enabled` 时 + - 当前共享 lane 覆盖： + - `google`：`generate`、`edit` + - `minimax`：`generate` + - `comfy`：使用单独的 Comfy live 文件，不在这个共享扫描中 - 可选缩小范围： - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` +- 可选认证行为： + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile 存储认证并忽略仅环境变量的覆盖 -## Docker 运行器（可选的“在 Linux 中可工作”检查） +## 视频生成 live -这些 Docker 运行器分为两类： +- 测试：`extensions/video-generation-providers.live.test.ts` +- 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` +- 范围： + - 测试共享的内置视频生成提供商路径 + - 在探测前从你的登录 shell（`~/.profile`）中加载提供商环境变量 + - 默认优先使用 live/env API 密钥，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖你 shell 中真实可用的凭证 + - 跳过没有可用认证/profile/模型的提供商 + - 在可用时运行两个已声明的运行时模式： + - `generate`：仅使用提示词输入 + - `imageToVideo`：当提供商声明 `capabilities.imageToVideo.enabled` 时 + - `videoToVideo`：当提供商声明 `capabilities.videoToVideo.enabled` 且所选提供商/模型在共享扫描中接受基于 buffer 的本地视频输入时 + - 当前 `videoToVideo` live 覆盖： + - `google` + - `openai` + - 仅当所选模型是 `runway/gen4_aleph` 时包含 `runway` + - 当前在共享扫描中已声明但跳过的 `videoToVideo` 提供商： + - `alibaba`、`qwen`、`xai`，因为这些路径目前要求远程 `http(s)` / MP4 参考 URL +- 可选缩小范围： + - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` + - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` +- 可选认证行为： + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile 存储认证并忽略仅环境变量的覆盖 -- Live 模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像内运行各自匹配的 profile-key live 文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），同时挂载你的本地配置目录和工作区（如果已挂载，也会读取 `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。 -- Docker live 运行器默认使用更小的冒烟测试上限，以便完整 Docker 扫描仍然具有可行性： +## Docker 运行器（可选的“在 Linux 中可用”检查） + +这些 Docker 运行器分成两类： + +- Live 模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像中运行各自匹配的 profile-key live 文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），并挂载你的本地配置目录和工作区（如果挂载了 `~/.profile` 也会先读取）。对应的本地入口点分别是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。 +- Docker live 运行器默认会使用更小的冒烟上限，以便完整的 Docker 扫描仍然可行： `test:docker:live-models` 默认设置 `OPENCLAW_LIVE_MAX_MODELS=12`，并且 `test:docker:live-gateway` 默认设置 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、 - `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`，以及 + `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` 和 `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你 - 明确想进行更大的穷举扫描时，再覆盖这些环境变量。 -- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次 live Docker 镜像，然后在两个 live Docker 通道中复用它。 -- 容器冒烟测试运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels` 和 `test:docker:plugins` 会启动一个或多个真实容器，并验证更高层级的集成路径。 + 明确希望执行更大的全量扫描时，可覆盖这些环境变量。 +- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次 live Docker 镜像，然后在两个 live Docker lane 中复用它。 +- 容器冒烟运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels` 和 `test:docker:plugins` 会启动一个或多个真实容器，并验证更高层的集成路径。 -Live 模型 Docker 运行器还会只绑定挂载所需的 CLI auth home（若运行未缩小范围，则挂载所有受支持项），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就可以刷新令牌，而不会修改主机 auth 存储： +Live 模型 Docker 运行器还会只绑定挂载所需的 CLI 认证 home（如果运行未缩小范围，则挂载所有支持的 home），然后在运行前将其复制到容器 home 中，以便外部 CLI OAuth 可以刷新令牌而不修改主机认证存储： -- 直接模型：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`） -- ACP 绑定冒烟测试：`pnpm test:docker:live-acp-bind`（脚本：`scripts/test-live-acp-bind-docker.sh`） -- CLI 后端冒烟测试：`pnpm test:docker:live-cli-backend`（脚本：`scripts/test-live-cli-backend-docker.sh`） +- Direct models：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`） +- ACP 绑定冒烟：`pnpm test:docker:live-acp-bind`（脚本：`scripts/test-live-acp-bind-docker.sh`） +- CLI 后端冒烟：`pnpm test:docker:live-cli-backend`（脚本：`scripts/test-live-cli-backend-docker.sh`） - Gateway 网关 + dev 智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`） -- Open WebUI live 冒烟测试：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`） +- Open WebUI live 冒烟：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`） - 新手引导向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`） -- Gateway 网关 网络（两个容器、WS 身份验证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`） -- MCP 渠道桥接（已播种的 Gateway 网关 + stdio bridge + 原始 Claude notification-frame 冒烟测试）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`） -- 插件（安装冒烟测试 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`） +- Gateway 网关网络（两个容器、WS 认证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`） +- MCP 渠道桥接（种子 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`） +- 插件（安装冒烟 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`） -Live 模型 Docker 运行器还会以只读方式绑定挂载当前检出内容，并在容器内将其暂存到临时 workdir 中。这能让运行时镜像保持精简，同时仍然针对你本地的确切源码 / 配置运行 Vitest。暂存步骤会跳过大型本地专用缓存和应用构建产物，例如 `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地 `.build` 或 Gradle 输出目录，这样 Docker live 运行就不会花数分钟复制机器专属产物。它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，因此 Gateway 网关 live 探测不会在容器里启动真实的 Telegram / Discord / 等渠道 worker。`test:docker:live-models` 仍然运行 `pnpm test:live`，因此当你需要缩小或排除该 Docker 通道中的 Gateway 网关 live 覆盖时，也要一并传入 `OPENCLAW_LIVE_GATEWAY_*`。`test:docker:openwebui` 是一个更高层级的兼容性冒烟测试：它会启动一个启用了 OpenAI 兼容 HTTP 端点的 OpenClaw Gateway 网关 容器，启动一个指向该 Gateway 网关 的固定版 Open WebUI 容器，通过 Open WebUI 完成登录，验证 `/api/models` 暴露了 `openclaw/default`，然后通过 Open WebUI 的 `/api/chat/completions` 代理发送一条真实聊天请求。首次运行可能明显更慢，因为 Docker 可能需要拉取 Open WebUI 镜像，而 Open WebUI 也可能需要完成自身的冷启动设置。这个通道需要一个可用的 live 模型密钥，而 `OPENCLAW_PROFILE_FILE`（默认 `~/.profile`）是在 Docker 化运行中提供它的主要方式。成功运行会打印一个小型 JSON 负载，例如 `{ "ok": true, "model": "openclaw/default", ... }`。`test:docker:mcp-channels` 刻意保持确定性，不需要真实的 Telegram、Discord 或 iMessage 账号。它会启动一个已播种的 Gateway 网关 容器，启动第二个容器来运行 `openclaw mcp serve`，然后通过真实的 stdio MCP bridge 验证路由会话发现、记录读取、附件元数据、实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。通知检查会直接检查原始 stdio MCP 帧，因此该冒烟测试验证的是 bridge 实际发出了什么，而不只是某个特定客户端 SDK 恰好暴露了什么。 +Live 模型 Docker 运行器还会以只读方式绑定挂载当前检出， +并将其暂存到容器内的临时 workdir 中。这样既能保持运行时 +镜像精简，又能让 Vitest 针对你当前本地的源文件/配置准确运行。 +暂存步骤会跳过大型本地专用缓存和应用构建输出，例如 +`.pnpm-store`、`.worktrees`、`__openclaw_vitest__` 以及应用本地 `.build` 或 +Gradle 输出目录，因此 Docker live 运行不会花上数分钟去复制 +机器专属产物。 +它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 Gateway 网关 live probe 就不会在容器内启动 +真实的 Telegram/Discord 等渠道 worker。 +`test:docker:live-models` 仍会运行 `pnpm test:live`，因此当你需要缩小范围或排除该 Docker lane 中的 Gateway 网关 +live 覆盖时，也要一并传入 +`OPENCLAW_LIVE_GATEWAY_*`。 +`test:docker:openwebui` 是一个更高层的兼容性冒烟：它会启动一个 +启用了 OpenAI 兼容 HTTP 端点的 OpenClaw Gateway 网关容器， +再针对该 Gateway 网关启动一个固定版本的 Open WebUI 容器，通过 +Open WebUI 登录，验证 `/api/models` 暴露出 `openclaw/default`，然后通过 +Open WebUI 的 `/api/chat/completions` 代理发送一条真实聊天请求。 +第一次运行可能明显更慢，因为 Docker 可能需要拉取 +Open WebUI 镜像，而 Open WebUI 也可能需要完成其自身的冷启动设置。 +这个 lane 需要一个可用的 live 模型密钥，而 `OPENCLAW_PROFILE_FILE` +（默认 `~/.profile`）是在 Docker 运行中提供该密钥的主要方式。 +成功运行会打印一个小型 JSON 载荷，例如 `{ "ok": true, "model": +"openclaw/default", ... }`。 +`test:docker:mcp-channels` 被有意设计为确定性测试，不需要 +真实的 Telegram、Discord 或 iMessage 账号。它会启动一个带种子数据的 Gateway 网关 +容器，再启动第二个容器执行 `openclaw mcp serve`，然后 +通过真实的 stdio MCP bridge 验证路由会话发现、转录读取、附件元数据、 +live 事件队列行为、出站发送路由，以及 Claude 风格的渠道 + +权限通知。通知检查会直接检查原始 stdio MCP 帧， +因此该冒烟验证的是 bridge 实际发出了什么， +而不只是某个特定客户端 SDK 恰好对外暴露了什么。 -手动 ACP 自然语言线程冒烟测试（不在 CI 中）： +手动 ACP 自然语言线程冒烟（非 CI）： - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- 保留这个脚本以供回归 / 调试工作流使用。未来可能还需要它来验证 ACP 线程路由，因此不要删除它。 +- 请保留这个脚本用于回归/调试工作流。它未来可能还会再次用于 ACP 线程路由验证，因此不要删除它。 常用环境变量： - `OPENCLAW_CONFIG_DIR=...`（默认：`~/.openclaw`）挂载到 `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...`（默认：`~/.openclaw/workspace`）挂载到 `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）挂载到 `/home/node/.profile`，并在运行测试前读取 -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于缓存 Docker 内部的 CLI 安装 -- `$HOME` 下的外部 CLI 身份验证目录 / 文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...` +- `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）挂载到 `/home/node/.profile`，并在运行测试前先读取 +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于 Docker 内缓存 CLI 安装 +- `$HOME` 下的外部 CLI 认证目录/文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...` - 默认目录：`.minimax` - 默认文件：`~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` - - 缩小提供商范围的运行只会挂载由 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的所需目录 / 文件 - - 手动覆盖方式：`OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`，或逗号列表，例如 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 缩小运行范围 -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 在容器内过滤提供商 -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 确保凭证来自 profile store（而不是环境变量） -- `OPENCLAW_OPENWEBUI_MODEL=...` 选择 Gateway 网关 为 Open WebUI 冒烟测试暴露的模型 -- `OPENCLAW_OPENWEBUI_PROMPT=...` 覆盖 Open WebUI 冒烟测试使用的 nonce 检查提示词 + - 缩小到特定提供商的运行只会挂载由 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的所需目录/文件 + - 可手动覆盖：`OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`，或逗号列表，例如 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用于缩小运行范围 +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 用于过滤容器内提供商 +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 确保凭证来自 profile 存储（而不是环境变量） +- `OPENCLAW_OPENWEBUI_MODEL=...` 选择 Gateway 网关为 Open WebUI 冒烟暴露的模型 +- `OPENCLAW_OPENWEBUI_PROMPT=...` 覆盖 Open WebUI 冒烟使用的 nonce 检查提示词 - `OPENWEBUI_IMAGE=...` 覆盖固定的 Open WebUI 镜像标签 ## 文档完整性检查 修改文档后运行文档检查：`pnpm check:docs`。 -如需同时检查页内标题锚点，运行完整 Mintlify 锚点验证：`pnpm docs:check-links:anchors`。 +当你还需要完整的 Mintlify 锚点校验（包括页内标题检查）时，运行：`pnpm docs:check-links:anchors`。 -## 离线回归测试（CI 安全） +## 离线回归（CI 安全） -这些是不依赖真实提供商的“真实流水线”回归测试： +这些是在不接入真实提供商的情况下，覆盖“真实流水线”的回归测试： -- Gateway 网关 工具调用（模拟 OpenAI，真实 Gateway 网关 + 智能体循环）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”） -- Gateway 网关 向导（WS `wizard.start` / `wizard.next`，写入配置 + 强制身份验证）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”） +- Gateway 网关工具调用（模拟 OpenAI，真实 Gateway 网关 + 智能体循环）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”） +- Gateway 网关向导（WS `wizard.start`/`wizard.next`，强制写入 config + auth）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”） ## 智能体可靠性评估（Skills） -我们已经有一些 CI 安全的测试，它们的行为类似“智能体可靠性评估”： +我们已经有一些 CI 安全的测试，其行为类似“智能体可靠性评估”： - 通过真实 Gateway 网关 + 智能体循环进行模拟工具调用（`src/gateway/gateway.test.ts`）。 -- 验证会话布线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。 +- 验证会话接线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。 -对于 Skills，仍然缺少的内容（参见 [Skills](/zh-CN/tools/skills)）： +对于 Skills（参见 [Skills](/zh-CN/tools/skills)），当前仍缺少： -- **决策能力：** 当提示词中列出 Skills 时，智能体是否会选择正确的技能（或避开无关技能）？ -- **合规性：** 智能体是否会在使用前读取 `SKILL.md`，并遵守必需的步骤 / 参数？ +- **决策能力：** 当提示词中列出 Skills 时，智能体是否会选择正确的 Skill（或避开无关 Skill）？ +- **合规性：** 智能体在使用前是否会读取 `SKILL.md`，并遵循要求的步骤/参数？ - **工作流契约：** 断言工具顺序、会话历史延续以及沙箱边界的多轮场景。 未来的评估应优先保持确定性： -- 一个使用模拟提供商的场景运行器，用于断言工具调用 + 顺序、技能文件读取和会话布线。 -- 一小组面向技能的场景测试（使用 vs 避免、门控、提示词注入）。 -- 只有在 CI 安全测试套件建立之后，才增加可选的 live 评估（选择加入、环境变量门控）。 +- 一个使用模拟提供商的场景运行器，用于断言工具调用 + 顺序、Skill 文件读取以及会话接线。 +- 一小组面向 Skill 的场景（使用 vs 避免、门控、提示注入）。 +- 只有在 CI 安全套件到位后，再提供可选的 live 评估（按需启用、受环境变量控制）。 ## 契约测试（插件和渠道形状） -契约测试用于验证每个已注册插件和渠道都符合其接口契约。它们会遍历所有发现到的插件，并运行一组形状和行为断言。默认的 `pnpm test` 单元通道会刻意跳过这些共享接缝和冒烟测试文件；当你触及共享渠道或提供商接口时，请显式运行契约命令。 +契约测试用于验证每个已注册插件和渠道是否符合其 +接口契约。它们会遍历所有已发现插件，并运行一套 +形状和行为断言。默认的 `pnpm test` 单元 lane 会刻意 +跳过这些共享接缝和冒烟文件；当你修改共享渠道或提供商接口时， +请显式运行契约命令。 ### 命令 @@ -586,11 +656,11 @@ Live 模型 Docker 运行器还会以只读方式绑定挂载当前检出内容 - **plugin** - 基本插件形状（id、名称、能力） - **setup** - 设置向导契约 - **session-binding** - 会话绑定行为 -- **outbound-payload** - 消息负载结构 +- **outbound-payload** - 消息载荷结构 - **inbound** - 入站消息处理 -- **actions** - 渠道动作处理器 +- **actions** - 渠道操作处理器 - **threading** - 线程 ID 处理 -- **directory** - 目录 / 花名册 API +- **directory** - 目录/成员列表 API - **group-policy** - 群组策略执行 ### 提供商状态契约 @@ -604,32 +674,32 @@ Live 模型 Docker 运行器还会以只读方式绑定挂载当前检出内容 位于 `src/plugins/contracts/*.contract.test.ts`： -- **auth** - 身份验证流程契约 -- **auth-choice** - 身份验证选择 / 选择逻辑 +- **auth** - 认证流程契约 +- **auth-choice** - 认证方式/选择 - **catalog** - 模型目录 API - **discovery** - 插件发现 - **loader** - 插件加载 - **runtime** - 提供商运行时 -- **shape** - 插件形状 / 接口 +- **shape** - 插件形状/接口 - **wizard** - 设置向导 ### 何时运行 -- 在修改 plugin-sdk 导出或子路径之后 -- 在添加或修改渠道或提供商插件之后 -- 在重构插件注册或发现逻辑之后 +- 修改 `plugin-sdk` 导出或子路径之后 +- 新增或修改渠道插件或提供商插件之后 +- 重构插件注册或发现逻辑之后 契约测试会在 CI 中运行，不需要真实 API 密钥。 ## 添加回归测试（指南） -当你修复 live 中发现的提供商 / 模型问题时： +当你修复了一个在 live 中发现的提供商/模型问题时： -- 如果可能，添加一个 CI 安全的回归测试（模拟 / 存根提供商，或捕获确切的请求形状转换） -- 如果它本质上只能通过 live 复现（限流、身份验证策略），让 live 测试保持范围小，并通过环境变量选择加入 -- 优先定位到能捕获该缺陷的最小层级： - - 提供商请求转换 / 重放缺陷 → 直接模型测试 - - Gateway 网关 会话 / 历史 / 工具流水线缺陷 → Gateway 网关 live 冒烟测试或 CI 安全的 Gateway 网关 模拟测试 -- SecretRef 遍历防护： - - `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个示例目标，然后断言遍历段 exec id 会被拒绝。 - - 如果你在 `src/secrets/target-registry-data.ts` 中新增一个 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会在目标 id 未分类时故意失败，这样新类别就无法被悄悄跳过。 +- 如果可能，添加一个 CI 安全的回归测试（模拟/存根提供商，或捕获确切的请求形状转换） +- 如果问题天然只能在 live 中复现（限流、认证策略），请让 live 测试保持范围小，并通过环境变量按需启用 +- 优先瞄准能捕获该 bug 的最小层级： + - 提供商请求转换/回放 bug → direct models 测试 + - Gateway 网关会话/历史/工具流水线 bug → Gateway 网关 live 冒烟或 CI 安全的 Gateway 网关模拟测试 +- SecretRef 遍历防护规则： + - `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类推导出一个采样目标，然后断言会拒绝 traversal-segment exec id。 + - 如果你在 `src/secrets/target-registry-data.ts` 中添加了新的 `includeInPlan` SecretRef 目标家族，请更新该测试中的 `classifyTargetClass`。该测试会在遇到未分类目标 id 时有意失败，以防新的类别被静默跳过。 diff --git a/docs/zh-CN/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md b/docs/zh-CN/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md new file mode 100644 index 000000000..382d87b44 --- /dev/null +++ b/docs/zh-CN/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md @@ -0,0 +1,509 @@ +--- +date: 2026-04-05T00:00:00Z +status: active +title: 重构：逐步将 plugin-sdk 变成真正的工作区包 +type: refactor +x-i18n: + generated_at: "2026-04-06T15:29:40Z" + model: gpt-5.4 + provider: openai + source_hash: ea1ca41846363c506a0db6dbca746e840d7c71ca82bbfc5277af9e2ae7f6b070 + source_path: plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md + workflow: 15 +--- + +# 重构：逐步将 plugin-sdk 变成真正的工作区包 + +## 概述 + +该计划在 `packages/plugin-sdk` 下为插件 SDK 引入一个真正的工作区包，并用它让第一批少量扩展选择性地接入由编译器强制执行的包边界。目标是让非法相对导入在普通 `tsc` 下对选定的一组内置 provider 扩展直接失败，而不强制进行全仓库迁移，也不制造一个巨大的合并冲突面。 + +关键的渐进式动作是在一段时间内并行运行两种模式： + +| 模式 | 导入形态 | 使用者 | 强制机制 | +| ----------- | ------------------------ | ------------------------------------ | -------------------------------------------- | +| 旧模式 | `openclaw/plugin-sdk/*` | 所有现有未选择接入的扩展 | 保持当前宽松行为 | +| 选择接入模式 | `@openclaw/plugin-sdk/*` | 仅第一批扩展 | 包本地 `rootDir` + 项目引用 | + +## 问题框架 + +当前仓库导出了一个庞大的公共插件 SDK 表面，但它并不是真正的工作区包。而是： + +- 根 `tsconfig.json` 将 `openclaw/plugin-sdk/*` 直接映射到 + `src/plugin-sdk/*.ts` +- 未选择接入先前实验的扩展仍然共享这种 + 全局源码别名行为 +- 只有在允许的 SDK 导入不再解析到扩展包之外的原始仓库源码后，添加 `rootDir` 才会生效 + +这意味着仓库可以描述期望的边界策略，但 TypeScript 无法对大多数扩展清晰地强制执行它。 + +你需要一条渐进式路径，以便： + +- 让 `plugin-sdk` 变得真实 +- 将 SDK 迁移为名为 `@openclaw/plugin-sdk` 的工作区包 +- 在第一个 PR 中只改动大约 10 个扩展 +- 暂时让其余扩展树继续使用旧方案，等待后续清理 +- 避免把 `tsconfig.plugin-sdk.dts.json` + postinstall 生成声明文件的流程作为第一批 rollout 的主要机制 + +## 需求追踪 + +- R1. 在 `packages/` 下为插件 SDK 创建一个真正的工作区包。 +- R2. 将新包命名为 `@openclaw/plugin-sdk`。 +- R3. 为新的 SDK 包提供独立的 `package.json` 和 `tsconfig.json`。 +- R4. 在迁移窗口期间，为未选择接入的扩展保留旧的 + `openclaw/plugin-sdk/*` 导入可用。 +- R5. 在第一个 PR 中只让少量第一批扩展选择接入。 +- R6. 对第一批扩展，离开其包根目录的相对导入必须以失败关闭。 +- R7. 第一批扩展必须通过包依赖和 TS 项目引用来使用 SDK， + 而不是通过根 `paths` 别名。 +- R8. 该计划必须避免为编辑器正确性引入全仓库强制性的 postinstall 生成步骤。 +- R9. 第一批 rollout 必须能以中等规模 PR 的形式审阅和合并， + 而不是一次全仓库 300+ 文件的重构。 + +## 范围边界 + +- 第一个 PR 不进行所有内置扩展的完整迁移。 +- 第一个 PR 不要求删除 `src/plugin-sdk`。 +- 第一个 PR 不要求立即将每个根构建或测试路径都改为使用新包。 +- 不尝试为每个未选择接入的扩展都强制提供 VS Code 红线提示。 +- 不为扩展树其余部分做大范围 lint 清理。 +- 除了导入解析、包归属和对选择接入扩展的边界强制之外，不引入大的运行时行为变化。 + +## 上下文与研究 + +### 相关代码和模式 + +- `pnpm-workspace.yaml` 已经包含 `packages/*` 和 `extensions/*`，因此在 `packages/plugin-sdk` 下添加新的工作区包符合现有仓库布局。 +- 现有工作区包，例如 `packages/memory-host-sdk/package.json` + 和 `packages/plugin-package-contract/package.json`，已经使用以 `src/*.ts` 为根的包本地 `exports` 映射。 +- 根 `package.json` 当前通过 `./plugin-sdk` + 和 `./plugin-sdk/*` 导出 SDK 表面，其后端为 `dist/plugin-sdk/*.js` 和 + `dist/plugin-sdk/*.d.ts`。 +- `src/plugin-sdk/entrypoints.ts` 和 `scripts/lib/plugin-sdk-entrypoints.json` + 已经充当 SDK 表面的规范入口点清单。 +- 根 `tsconfig.json` 当前映射： + - `openclaw/plugin-sdk` -> `src/plugin-sdk/index.ts` + - `openclaw/plugin-sdk/*` -> `src/plugin-sdk/*.ts` +- 先前的边界实验表明，只有在允许的 SDK 导入不再解析到扩展包之外的原始源码后，包本地 `rootDir` 才会对非法相对导入生效。 + +### 第一批扩展集合 + +该计划假定第一批是 provider 较重的一组，因为它们最不容易牵涉复杂的渠道运行时边缘情况： + +- `extensions/anthropic` +- `extensions/exa` +- `extensions/firecrawl` +- `extensions/groq` +- `extensions/mistral` +- `extensions/openai` +- `extensions/perplexity` +- `extensions/tavily` +- `extensions/together` +- `extensions/xai` + +### 第一批 SDK 表面清单 + +第一批扩展当前导入的是一组可控的 SDK 子路径。初始的 `@openclaw/plugin-sdk` 包只需要覆盖这些： + +- `agent-runtime` +- `cli-runtime` +- `config-runtime` +- `core` +- `image-generation` +- `media-runtime` +- `media-understanding` +- `plugin-entry` +- `plugin-runtime` +- `provider-auth` +- `provider-auth-api-key` +- `provider-auth-login` +- `provider-auth-runtime` +- `provider-catalog-shared` +- `provider-entry` +- `provider-http` +- `provider-model-shared` +- `provider-onboard` +- `provider-stream-family` +- `provider-stream-shared` +- `provider-tools` +- `provider-usage` +- `provider-web-fetch` +- `provider-web-search` +- `realtime-transcription` +- `realtime-voice` +- `runtime-env` +- `secret-input` +- `security-runtime` +- `speech` +- `testing` + +### 制度性经验 + +- 该工作树中没有相关的 `docs/solutions/` 条目。 + +### 外部参考 + +- 该计划不需要外部研究。仓库中已经包含相关的工作区包和 SDK 导出模式。 + +## 关键技术决策 + +- 在迁移期间引入 `@openclaw/plugin-sdk` 作为新的工作区包，同时保留旧的根 `openclaw/plugin-sdk/*` 表面。 + 理由：这样可以让第一批扩展集合迁移到真正的包解析方式，而无需同时更改所有扩展和所有根构建路径。 + +- 使用专门的选择接入边界基础配置，例如 + `extensions/tsconfig.package-boundary.base.json`，而不是替换所有人现有的扩展基础配置。 + 理由：仓库在迁移期间需要同时支持旧模式和选择接入模式两种扩展模式。 + +- 对第一批扩展使用指向 + `packages/plugin-sdk/tsconfig.json` 的 TS 项目引用，并为选择接入边界模式设置 + `disableSourceOfProjectReferenceRedirect`。 + 理由：这为 `tsc` 提供了真实的包图，同时抑制编辑器和编译器回退到原始源码遍历。 + +- 在第一批中保持 `@openclaw/plugin-sdk` 为私有。 + 理由：眼下的目标是内部边界强制与迁移安全，而不是在表面尚未稳定之前就发布第二份外部 SDK 合约。 + +- 第一轮实现只迁移第一批 SDK 子路径，其余部分保留兼容桥接。 + 理由：在一个 PR 中物理移动 `src/plugin-sdk/*.ts` 下全部 315 个文件，正是这个计划试图避免的合并冲突面。 + +- 第一批不要依赖 `scripts/postinstall-bundled-plugins.mjs` 来构建 SDK 声明文件。 + 理由：显式的构建/引用流程更容易理解，也能让仓库行为更可预测。 + +## 开放问题 + +### 规划期间已解决 + +- 哪些扩展应纳入第一批？ + 使用上面列出的 10 个 provider/web-search 扩展，因为它们在结构上比更重的渠道包更独立。 + +- 第一个 PR 是否应替换整个扩展树？ + 不。第一个 PR 应并行支持两种模式，并且只让第一批选择接入。 + +- 第一批是否应要求 postinstall 声明构建？ + 不。包/引用图应显式可见，CI 应有意运行相关的包本地 typecheck。 + +### 延后到实现阶段 + +- 第一批包是否可以仅通过项目引用直接指向包本地 `src/*.ts`，还是 + `@openclaw/plugin-sdk` 包仍需要一个小型声明文件发射步骤。 + 这是一个由实现阶段决定的 TS 图验证问题。 + +- 根 `openclaw` 包是否应立即将第一批 SDK 子路径代理到 + `packages/plugin-sdk` 的输出，还是继续使用 + `src/plugin-sdk` 下生成的兼容 shim。 + 这是一个兼容性和构建形态细节问题，取决于哪种最小实现路径能保持 CI 绿色。 + +## 高层技术设计 + +> 此处用于说明预期方法，属于供审阅参考的方向性指导，而不是实现规范。实施该变更的智能体应将其视为上下文，而不是需要照抄的代码。 + +```mermaid +flowchart TB + subgraph Legacy["旧模式扩展（不变）"] + L1["extensions/*\nopenclaw/plugin-sdk/*"] + L2["根 tsconfig paths"] + L1 --> L2 + L2 --> L3["src/plugin-sdk/*"] + end + + subgraph OptIn["第一批扩展"] + O1["10 个选择接入的扩展"] + O2["extensions/tsconfig.package-boundary.base.json"] + O3["rootDir = '.'\n项目引用"] + O4["@openclaw/plugin-sdk"] + O1 --> O2 + O2 --> O3 + O3 --> O4 + end + + subgraph SDK["新的工作区包"] + P1["packages/plugin-sdk/package.json"] + P2["packages/plugin-sdk/tsconfig.json"] + P3["packages/plugin-sdk/src/.ts"] + P1 --> P2 + P2 --> P3 + end + + O4 --> SDK +``` + +## 实施单元 + +- [ ] **单元 1：引入真正的 `@openclaw/plugin-sdk` 工作区包** + +**目标：** 为 SDK 创建一个真正的工作区包，使其能够拥有第一批子路径表面，而不强制进行全仓库迁移。 + +**需求：** R1、R2、R3、R8、R9 + +**依赖：** 无 + +**文件：** + +- 创建：`packages/plugin-sdk/package.json` +- 创建：`packages/plugin-sdk/tsconfig.json` +- 创建：`packages/plugin-sdk/src/index.ts` +- 创建：第一批 SDK 子路径对应的 `packages/plugin-sdk/src/*.ts` +- 修改：仅在需要调整包 glob 时修改 `pnpm-workspace.yaml` +- 修改：`package.json` +- 修改：`src/plugin-sdk/entrypoints.ts` +- 修改：`scripts/lib/plugin-sdk-entrypoints.json` +- 测试：`src/plugins/contracts/plugin-sdk-workspace-package.contract.test.ts` + +**方法：** + +- 添加一个名为 `@openclaw/plugin-sdk` 的新工作区包。 +- 初始只包含第一批 SDK 子路径，而不是整个 315 文件树。 +- 如果直接移动某个第一批入口点会导致 diff 过大，那么第一个 PR + 可以先在 `packages/plugin-sdk/src` 中以薄包装器的形式引入该子路径， + 然后在后续 PR 中再把该子路径簇的真正规范源码切换到该包。 +- 复用现有入口点清单机制，以便在一个规范位置声明第一批包表面。 +- 在工作区包成为新的选择接入合约时，继续保留根包导出供旧用户使用。 + +**应遵循的模式：** + +- `packages/memory-host-sdk/package.json` +- `packages/plugin-package-contract/package.json` +- `src/plugin-sdk/entrypoints.ts` + +**测试场景：** + +- 正常路径：工作区包导出计划中列出的每个第一批子路径，且没有缺失任何所需的第一批导出。 +- 边缘情况：当重新生成第一批入口列表或将其与规范清单比较时，包导出元数据保持稳定。 +- 集成：引入新的工作区包后，根包中的旧版 SDK 导出仍然存在。 + +**验证：** + +- 仓库中存在一个有效的 `@openclaw/plugin-sdk` 工作区包， + 具有稳定的第一批导出映射，并且根 `package.json` + 中没有旧版导出回归。 + +- [ ] **单元 2：为包级强制边界扩展添加选择接入的 TS 边界模式** + +**目标：** 定义选择接入扩展将使用的 TS 配置模式，同时为其他所有扩展保留现有扩展 TS 行为不变。 + +**需求：** R4、R6、R7、R8、R9 + +**依赖：** 单元 1 + +**文件：** + +- 创建：`extensions/tsconfig.package-boundary.base.json` +- 创建：`tsconfig.boundary-optin.json` +- 修改：`extensions/xai/tsconfig.json` +- 修改：`extensions/openai/tsconfig.json` +- 修改：`extensions/anthropic/tsconfig.json` +- 修改：`extensions/mistral/tsconfig.json` +- 修改：`extensions/groq/tsconfig.json` +- 修改：`extensions/together/tsconfig.json` +- 修改：`extensions/perplexity/tsconfig.json` +- 修改：`extensions/tavily/tsconfig.json` +- 修改：`extensions/exa/tsconfig.json` +- 修改：`extensions/firecrawl/tsconfig.json` +- 测试：`src/plugins/contracts/extension-package-project-boundaries.test.ts` +- 测试：`test/extension-package-tsc-boundary.test.ts` + +**方法：** + +- 为旧模式扩展保留 `extensions/tsconfig.base.json`。 +- 添加一个新的选择接入基础配置，它： + - 设置 `rootDir: "."` + - 引用 `packages/plugin-sdk` + - 启用 `composite` + - 在需要时禁用项目引用源码重定向 +- 添加一个专用的第一批 typecheck 解决方案配置，而不是在同一个 PR 中重塑根仓库 TS 项目。 + +**执行说明：** 在把模式扩展到全部 10 个扩展前，先从一个已选择接入扩展的失败包本地 canary typecheck 开始。 + +**应遵循的模式：** + +- 先前边界工作中的现有包本地扩展 `tsconfig.json` 模式 +- 来自 `packages/memory-host-sdk` 的工作区包模式 + +**测试场景：** + +- 正常路径：每个已选择接入的扩展都能通过包边界 TS 配置成功 typecheck。 +- 错误路径：对于已选择接入扩展，来自 `../../src/cli/acp-cli.ts` 的 canary 非法相对导入会以 `TS6059` 失败。 +- 集成：未选择接入的扩展保持不变，不需要参与新的解决方案配置。 + +**验证：** + +- 针对这 10 个已选择接入扩展有一个专用的 typecheck 图，而且其中之一的错误相对导入会通过普通 `tsc` 失败。 + +- [ ] **单元 3：将第一批扩展迁移到 `@openclaw/plugin-sdk`** + +**目标：** 让第一批扩展通过依赖元数据、项目引用和包名导入来使用真正的 SDK 包。 + +**需求：** R5、R6、R7、R9 + +**依赖：** 单元 2 + +**文件：** + +- 修改：`extensions/anthropic/package.json` +- 修改：`extensions/exa/package.json` +- 修改：`extensions/firecrawl/package.json` +- 修改：`extensions/groq/package.json` +- 修改：`extensions/mistral/package.json` +- 修改：`extensions/openai/package.json` +- 修改：`extensions/perplexity/package.json` +- 修改：`extensions/tavily/package.json` +- 修改：`extensions/together/package.json` +- 修改：`extensions/xai/package.json` +- 修改：上述 10 个扩展根目录下当前引用 `openclaw/plugin-sdk/*` + 的生产与测试导入 + +**方法：** + +- 将 `@openclaw/plugin-sdk: workspace:*` 添加到第一批扩展的 + `devDependencies`。 +- 将这些包中的 `openclaw/plugin-sdk/*` 导入替换为 + `@openclaw/plugin-sdk/*`。 +- 保持扩展内部本地导入通过诸如 `./api.ts` 和 `./runtime-api.ts` 这样的本地 barrel。 +- 本 PR 中不修改未选择接入的扩展。 + +**应遵循的模式：** + +- 现有扩展本地导入 barrel（`api.ts`、`runtime-api.ts`） +- 其他 `@openclaw/*` 工作区包所使用的包依赖形态 + +**测试场景：** + +- 正常路径：每个已迁移扩展在导入改写后，仍然能通过其现有插件测试完成注册/加载。 +- 边缘情况：已选择接入扩展集合中的仅测试用 SDK 导入，仍然可以通过新包正确解析。 +- 集成：已迁移扩展在 typecheck 时不再依赖根 `openclaw/plugin-sdk/*` + 别名路径。 + +**验证：** + +- 第一批扩展可以基于 `@openclaw/plugin-sdk` 构建和测试， + 不需要旧的根 SDK 别名路径。 + +- [ ] **单元 4：在部分迁移期间保留旧版兼容性** + +**目标：** 在 SDK 以旧版和新包两种形式同时存在的迁移期间，让仓库其余部分继续正常工作。 + +**需求：** R4、R8、R9 + +**依赖：** 单元 1-3 + +**文件：** + +- 修改：根据需要修改第一批兼容 shim 对应的 `src/plugin-sdk/*.ts` +- 修改：`package.json` +- 修改：组装 SDK 工件的构建或导出管线 +- 测试：`src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts` +- 测试：`src/plugins/contracts/plugin-sdk-index.bundle.test.ts` + +**方法：** + +- 保留根 `openclaw/plugin-sdk/*` 作为未迁移旧扩展以及尚未迁移的外部使用者的兼容性表面。 +- 对已移动到 `packages/plugin-sdk` 的第一批子路径，使用生成的 shim 或根导出代理接线。 +- 在这个阶段不要尝试淘汰根 SDK 表面。 + +**应遵循的模式：** + +- 通过 `src/plugin-sdk/entrypoints.ts` 生成现有根 SDK 导出 +- 根 `package.json` 中现有的包导出兼容性 + +**测试场景：** + +- 正常路径：在新包存在后，非选择接入扩展的旧版根 SDK 导入仍然可以解析。 +- 边缘情况：迁移窗口期间，第一批某个子路径可以同时通过旧的根表面和新的包表面工作。 +- 集成：plugin-sdk index/bundle 合约测试继续看到一致的公共表面。 + +**验证：** + +- 仓库同时支持旧模式和选择接入模式两种 SDK 使用方式，而不会破坏未变更的扩展。 + +- [ ] **单元 5：添加有范围限制的强制机制并记录迁移合约** + +**目标：** 落地 CI 和贡献者指南，以便对第一批强制执行新行为，而不假装整个扩展树都已迁移。 + +**需求：** R5、R6、R8、R9 + +**依赖：** 单元 1-4 + +**文件：** + +- 修改：`package.json` +- 修改：应运行选择接入边界 typecheck 的 CI 工作流文件 +- 修改：`AGENTS.md` +- 修改：`docs/plugins/sdk-overview.md` +- 修改：`docs/plugins/sdk-entrypoints.md` +- 修改：`docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` + +**方法：** + +- 添加一个显式的第一批 gate，例如为 + `packages/plugin-sdk` 加上 10 个已选择接入扩展运行专用的 `tsc -b` 解决方案。 +- 记录仓库现在同时支持旧模式和选择接入模式两种扩展模式，以及新的扩展边界工作应优先采用新包路径。 +- 记录下一批迁移规则，以便后续 PR 能在不重新争论架构的前提下添加更多扩展。 + +**应遵循的模式：** + +- `src/plugins/contracts/` 下现有的合约测试 +- 解释分阶段迁移的现有文档更新方式 + +**测试场景：** + +- 正常路径：新的第一批 typecheck gate 对工作区包和已选择接入扩展通过。 +- 错误路径：在某个已选择接入扩展中引入新的非法相对导入，会导致有范围限制的 typecheck gate 失败。 +- 集成：CI 尚不要求未选择接入扩展满足新的包边界模式。 + +**验证：** + +- 第一批强制路径已有文档、测试且可运行，而不会强制整个扩展树迁移。 + +## 全系统影响 + +- **交互图：** 该工作会影响 SDK 规范源码、根包导出、扩展包元数据、TS 图布局和 CI 验证。 +- **错误传播：** 主要的预期失败模式将变成已选择接入扩展中的编译期 TS + 错误（`TS6059`），而不是仅靠自定义脚本失败。 +- **状态生命周期风险：** 双表面迁移会引入根兼容导出与新工作区包之间的漂移风险。 +- **API 表面一致性：** 在过渡期间，第一批子路径必须通过 + `openclaw/plugin-sdk/*` 和 `@openclaw/plugin-sdk/*` + 两种方式保持语义完全一致。 +- **集成覆盖：** 仅靠单元测试不够；必须有具备范围限制的包图 typecheck 才能证明边界成立。 +- **未改变的不变量：** 未选择接入的扩展在 PR 1 中保持当前行为。该计划并不声称实现了全仓库导入边界强制。 + +## 风险与依赖 + +| 风险 | 缓解措施 | +| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| 第一批包仍然会解析回原始源码，导致 `rootDir` 实际上没有以失败关闭 | 将首个实现步骤设为对一个已选择接入扩展进行包引用 canary 验证，在扩展到整个集合前先验证 | +| 一次移动过多 SDK 源码会重现最初的合并冲突问题 | 第一个 PR 只移动第一批子路径，并保留根兼容桥接 | +| 旧版和新 SDK 表面在语义上发生漂移 | 保持单一入口点清单，添加兼容性合约测试，并明确双表面一致性要求 | +| 根仓库的构建/测试路径意外以不可控方式开始依赖新包 | 使用专用的选择接入解决方案配置，并将全仓库 TS 拓扑变更排除在第一个 PR 之外 | + +## 分阶段交付 + +### 第一阶段 + +- 引入 `@openclaw/plugin-sdk` +- 定义第一批子路径表面 +- 证明一个已选择接入扩展可以通过 `rootDir` 以失败关闭 + +### 第二阶段 + +- 让 10 个第一批扩展选择接入 +- 为其他所有扩展保留根兼容性 + +### 第三阶段 + +- 在后续 PR 中添加更多扩展 +- 将更多 SDK 子路径迁移到工作区包 +- 仅在旧扩展集合消失后再淘汰根兼容性 + +## 文档 / 运维说明 + +- 第一个 PR 应明确说明自己是双模式迁移，而不是全仓库强制完成。 +- 迁移指南应让后续 PR 可以轻松通过相同的包/依赖/引用模式添加更多扩展。 + +## 来源与参考 + +- 先前计划：`docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` +- 工作区配置：`pnpm-workspace.yaml` +- 现有 SDK 入口点清单：`src/plugin-sdk/entrypoints.ts` +- 现有根 SDK 导出：`package.json` +- 现有工作区包模式： + - `packages/memory-host-sdk/package.json` + - `packages/plugin-package-contract/package.json` diff --git a/docs/zh-CN/platforms/ios.md b/docs/zh-CN/platforms/ios.md index fea913bf4..786205e0b 100644 --- a/docs/zh-CN/platforms/ios.md +++ b/docs/zh-CN/platforms/ios.md @@ -1,15 +1,15 @@ --- read_when: - - 配对或重新连接 iOS 节点 - - 从源码运行 iOS 应用 - - 调试 gateway 发现或 canvas 命令 + - 配对或重新连接 iOS 节点时 + - 从源码运行 iOS 应用时 + - 调试 Gateway 网关发现或 canvas 命令时 summary: iOS 节点应用：连接到 Gateway 网关、配对、canvas 和故障排除 title: iOS 应用 x-i18n: - generated_at: "2026-04-05T08:37:38Z" + generated_at: "2026-04-06T15:29:25Z" model: gpt-5.4 provider: openai - source_hash: 1e9d9cec58afd4003dff81d3e367bfbc6a634c1b229e433e08fd78fbb5f2e5a9 + source_hash: f3e0a6e33e72d4c9f1f17ef70a1b67bae9ebe4a2dca16677ea6b28d0ddac1b4e source_path: platforms/ios.md workflow: 15 --- @@ -21,16 +21,16 @@ x-i18n: ## 它的作用 - 通过 WebSocket 连接到 Gateway 网关（LAN 或 tailnet）。 -- 提供节点能力：Canvas、屏幕快照、摄像头捕获、位置、对话模式、语音唤醒。 +- 提供节点能力：Canvas、屏幕快照、相机采集、位置、对讲模式、语音唤醒。 - 接收 `node.invoke` 命令并上报节点状态事件。 ## 要求 -- 在另一台设备上运行的 Gateway 网关（macOS、Linux，或通过 WSL2 运行的 Windows）。 +- Gateway 网关运行在另一台设备上（macOS、Linux，或通过 WSL2 运行的 Windows）。 - 网络路径： - 通过 Bonjour 处于同一 LAN，**或** - - 通过单播 DNS-SD 的 tailnet（示例域名：`openclaw.internal.`），**或** - - 手动输入主机 / 端口（回退方案）。 + - 通过 tailnet 使用单播 DNS-SD（示例域名：`openclaw.internal.`），**或** + - 手动输入主机/端口（回退方案）。 ## 快速开始（配对 + 连接） @@ -40,17 +40,17 @@ x-i18n: openclaw gateway --port 18789 ``` -2. 在 iOS 应用中，打开设置并选择一个已发现的 gateway，或者启用 Manual Host 并输入主机 / 端口。 +2. 在 iOS 应用中，打开 Settings 并选择一个已发现的 Gateway 网关（或者启用 Manual Host 并输入主机/端口）。 -3. 在 gateway 主机上批准配对请求： +3. 在 Gateway 网关主机上批准配对请求： ```bash openclaw devices list openclaw devices approve ``` -如果应用在认证详情（角色 / scopes / 公钥）变更后重试配对， -之前处于待处理状态的请求会被替换，并创建新的 `requestId`。 +如果应用在认证详情（角色/scopes/公钥）变更后重试配对， +之前待处理的请求会被新请求取代，并创建新的 `requestId`。 请在批准前再次运行 `openclaw devices list`。 4. 验证连接： @@ -60,10 +60,10 @@ openclaw nodes status openclaw gateway call node.list --params "{}" ``` -## 官方构建的基于中继的推送 +## 官方构建使用基于 relay 的推送 -官方发布的 iOS 构建使用外部推送中继，而不是将原始 APNs -令牌直接发布到 gateway。 +官方发布的 iOS 构建会使用外部推送 relay，而不是将原始 APNs +token 直接发布到 Gateway 网关。 Gateway 网关侧要求： @@ -81,78 +81,78 @@ Gateway 网关侧要求： } ``` -流程工作方式如下： +流程工作方式： -- iOS 应用使用 App Attest 和应用回执向中继注册。 -- 中继返回一个不透明的 relay handle，以及一个按注册范围限定的发送授权。 -- iOS 应用会获取已配对 gateway 的身份，并将其包含在中继注册中，因此该基于中继的注册会委托给那个特定的 gateway。 -- 应用会通过 `push.apns.register` 将该基于中继的注册转发给已配对的 gateway。 -- gateway 会将该已存储的 relay handle 用于 `push.test`、后台唤醒和唤醒提醒。 -- gateway 的中继 base URL 必须与官方 / TestFlight iOS 构建中内置的中继 URL 一致。 -- 如果应用之后连接到不同的 gateway，或者连接到内置了不同中继 base URL 的构建，它会刷新中继注册，而不是复用旧绑定。 +- iOS 应用使用 App Attest 和应用收据向 relay 注册。 +- relay 返回一个不透明的 relay handle 以及一个按注册范围授予的发送许可。 +- iOS 应用会获取已配对 Gateway 网关的身份，并将其包含在 relay 注册中，因此这个基于 relay 的注册会委托给该特定 Gateway 网关。 +- 应用通过 `push.apns.register` 将该基于 relay 的注册转发给已配对的 Gateway 网关。 +- Gateway 网关将使用这个已存储的 relay handle 来执行 `push.test`、后台唤醒和唤醒提示。 +- Gateway 网关的 relay 基础 URL 必须与官方/TestFlight iOS 构建中固化的 relay URL 一致。 +- 如果应用之后连接到不同的 Gateway 网关，或者连接到使用不同 relay 基础 URL 的构建，它会刷新 relay 注册，而不是复用旧绑定。 -对于此路径，gateway **不**需要的内容： +对于这一路径，Gateway 网关**不**需要： -- 不需要部署范围的中继令牌。 -- 对于官方 / TestFlight 的基于中继发送，不需要直接的 APNs 密钥。 +- 不需要全局部署级 relay token。 +- 对于官方/TestFlight 的 relay 转发发送，不需要直接 APNs key。 -预期的运维流程： +预期的操作流程： -1. 安装官方 / TestFlight iOS 构建。 -2. 在 gateway 上设置 `gateway.push.apns.relay.baseUrl`。 -3. 将应用与 gateway 配对，并让它完成连接。 -4. 在应用拿到 APNs 令牌、运维会话已连接且中继注册成功后，应用会自动发布 `push.apns.register`。 -5. 之后，`push.test`、重连唤醒和唤醒提醒就可以使用已存储的基于中继的注册。 +1. 安装官方/TestFlight iOS 构建。 +2. 在 Gateway 网关上设置 `gateway.push.apns.relay.baseUrl`。 +3. 将应用与 Gateway 网关配对，并让它完成连接。 +4. 当应用已经拿到 APNs token、operator 会话已连接且 relay 注册成功后，它会自动发布 `push.apns.register`。 +5. 之后，`push.test`、重连唤醒和唤醒提示就可以使用这个已存储的基于 relay 的注册。 兼容性说明： -- `OPENCLAW_APNS_RELAY_BASE_URL` 仍可作为 gateway 的临时环境变量覆盖项使用。 +- `OPENCLAW_APNS_RELAY_BASE_URL` 仍可作为 Gateway 网关的临时环境变量覆盖项使用。 ## 认证与信任流程 -中继的存在是为了强制执行两个约束，而这些约束是官方 iOS 构建在直接由 gateway 发送 APNs 时无法提供的： +之所以引入 relay，是为了强制执行两个“在官方 iOS 构建上直接由 Gateway 网关连接 APNs 无法提供”的约束： -- 只有通过 Apple 分发的真实 OpenClaw iOS 构建才能使用托管中继。 -- gateway 只能向与该特定 gateway 配对的 iOS 设备发送基于中继的推送。 +- 只有通过 Apple 分发的真实 OpenClaw iOS 构建才能使用托管 relay。 +- Gateway 网关只能为与该特定 Gateway 网关配对过的 iOS 设备发送基于 relay 的推送。 逐跳说明： 1. `iOS app -> gateway` - - 应用首先通过常规 Gateway 网关认证流程与 gateway 配对。 - - 这会给应用一个已认证的节点会话，以及一个已认证的运维会话。 - - 运维会话用于调用 `gateway.identity.get`。 + - 应用首先通过正常的 Gateway 网关认证流程与 Gateway 网关配对。 + - 这会给应用一个已认证的节点会话以及一个已认证的 operator 会话。 + - operator 会话用于调用 `gateway.identity.get`。 2. `iOS app -> relay` - - 应用通过 HTTPS 调用中继注册端点。 - - 注册包含 App Attest 证明和应用回执。 - - 中继会验证 bundle ID、App Attest 证明和 Apple 回执，并要求使用官方 / 生产分发路径。 - - 这就是为什么本地 Xcode / 开发构建无法使用托管中继。本地构建可能是已签名的，但不满足中继所要求的官方 Apple 分发证明。 + - 应用通过 HTTPS 调用 relay 注册端点。 + - 注册内容包括 App Attest 证明和应用收据。 + - relay 会验证 bundle ID、App Attest 证明和 Apple 收据，并要求使用官方/生产分发路径。 + - 这就是为什么本地 Xcode/dev 构建无法使用托管 relay。虽然本地构建可以签名，但它不满足 relay 所要求的官方 Apple 分发证明。 3. `gateway identity delegation` - - 在中继注册之前，应用会通过 `gateway.identity.get` 获取已配对 gateway 的身份。 - - 应用会在中继注册载荷中包含该 gateway 身份。 - - 中继返回一个 relay handle 和一个按注册范围限定的发送授权，并将其委托给该 gateway 身份。 + - 在 relay 注册前，应用会通过 `gateway.identity.get` 获取已配对 Gateway 网关的身份。 + - 应用会将这个 Gateway 网关身份包含到 relay 注册负载中。 + - relay 返回一个 relay handle 和一个按注册范围授予的发送许可，这些都被委托给该 Gateway 网关身份。 4. `gateway -> relay` - - gateway 会存储来自 `push.apns.register` 的 relay handle 和发送授权。 - - 在执行 `push.test`、重连唤醒和唤醒提醒时，gateway 会使用它自己的设备身份对发送请求进行签名。 - - 中继会根据注册时委托的 gateway 身份，验证已存储的发送授权以及 gateway 签名。 - - 即使另一个 gateway 以某种方式获得了该 handle，也无法复用这个已存储的注册。 + - Gateway 网关会存储来自 `push.apns.register` 的 relay handle 和发送许可。 + - 在执行 `push.test`、重连唤醒和唤醒提示时，Gateway 网关会使用它自己的设备身份对发送请求签名。 + - relay 会依据注册时委托的 Gateway 网关身份，同时验证已存储的发送许可和 Gateway 网关签名。 + - 即使其他 Gateway 网关设法拿到了这个 handle，也不能复用该已存储注册。 5. `relay -> APNs` - - 中继持有用于官方构建的生产 APNs 凭证和原始 APNs 令牌。 - - 对于基于中继的官方构建，gateway 永远不会存储原始 APNs 令牌。 - - 中继会代表已配对的 gateway 将最终推送发送到 APNs。 + - relay 持有生产 APNs 凭证以及官方构建的原始 APNs token。 + - 对于基于 relay 的官方构建，Gateway 网关永远不会存储原始 APNs token。 + - relay 代表已配对的 Gateway 网关向 APNs 发送最终推送。 -创建此设计的原因： +为什么要这样设计： -- 让生产 APNs 凭证不出现在用户的 gateway 中。 -- 避免在 gateway 上存储官方构建的原始 APNs 令牌。 -- 仅允许官方 / TestFlight OpenClaw 构建使用托管中继。 -- 防止一个 gateway 向属于另一个 gateway 的 iOS 设备发送唤醒推送。 +- 让生产 APNs 凭证不落到用户 Gateway 网关上。 +- 避免在 Gateway 网关上存储官方构建的原始 APNs token。 +- 仅允许官方/TestFlight OpenClaw 构建使用托管 relay。 +- 防止某个 Gateway 网关向属于另一个 Gateway 网关的 iOS 设备发送唤醒推送。 -本地 / 手动构建仍然使用直接 APNs。如果你在不使用中继的情况下测试这些构建， -gateway 仍然需要直接 APNs 凭证： +本地/手动构建仍然使用直连 APNs。如果你在不使用 relay 的情况下测试这些构建， +Gateway 网关仍然需要直连 APNs 凭证： ```bash export OPENCLAW_APNS_TEAM_ID="TEAMID" @@ -160,23 +160,39 @@ export OPENCLAW_APNS_KEY_ID="KEYID" export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)" ``` +这些是 Gateway 网关主机运行时环境变量，不是 Fastlane 设置。`apps/ios/fastlane/.env` 只存储 +App Store Connect / TestFlight 认证信息，例如 `ASC_KEY_ID` 和 `ASC_ISSUER_ID`；它不会为本地 iOS 构建配置 +直连 APNs 投递。 + +推荐的 Gateway 网关主机存储方式： + +```bash +mkdir -p ~/.openclaw/credentials/apns +chmod 700 ~/.openclaw/credentials/apns +mv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8 +chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8 +export OPENCLAW_APNS_PRIVATE_KEY_PATH="$HOME/.openclaw/credentials/apns/AuthKey_KEYID.p8" +``` + +不要提交 `.p8` 文件，也不要将它放在仓库检出目录下。 + ## 发现路径 ### Bonjour（LAN） -iOS 应用会在 `local.` 上浏览 `_openclaw-gw._tcp`，并在已配置时浏览相同的 -广域 DNS-SD 发现域。同一 LAN 上的 gateways 会自动通过 `local.` 出现； -跨网络发现可以使用已配置的广域域名，而无需更改 beacon 类型。 +iOS 应用会在 `local.` 上浏览 `_openclaw-gw._tcp`，并在已配置时浏览同一个 +广域 DNS-SD 发现域。同一 LAN 上的 Gateway 网关会通过 `local.` 自动出现； +跨网络发现则可以使用已配置的广域域名，而无需更改 beacon 类型。 ### Tailnet（跨网络） -如果 mDNS 被阻止，请使用单播 DNS-SD 区域（选择一个域名；示例： +如果 mDNS 被阻止，请使用单播 DNS-SD 区域（选择一个域名；例如： `openclaw.internal.`）和 Tailscale split DNS。 -CoreDNS 示例请参见 [Bonjour](/gateway/bonjour)。 +CoreDNS 示例请参见 [Bonjour](/zh-CN/gateway/bonjour)。 -### 手动主机 / 端口 +### 手动主机/端口 -在设置中，启用 **Manual Host** 并输入 gateway 主机 + 端口（默认 `18789`）。 +在 Settings 中启用 **Manual Host**，然后输入 Gateway 网关主机 + 端口（默认 `18789`）。 ## Canvas + A2UI @@ -188,10 +204,10 @@ openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"ur 说明： -- Gateway 网关的 canvas host 提供 `/__openclaw__/canvas/` 和 `/__openclaw__/a2ui/`。 -- 它由 Gateway 网关 HTTP 服务器提供（与 `gateway.port` 相同的端口，默认 `18789`）。 -- 当广播了 canvas host URL 时，iOS 节点会在连接时自动导航到 A2UI。 -- 使用 `canvas.navigate` 和 `{"url":""}` 可返回内置 scaffold。 +- Gateway 网关 canvas host 提供 `/__openclaw__/canvas/` 和 `/__openclaw__/a2ui/`。 +- 它由 Gateway 网关 HTTP 服务器提供（与 `gateway.port` 使用同一个端口，默认 `18789`）。 +- 当广播了 canvas host URL 时，iOS 节点会在连接后自动跳转到 A2UI。 +- 使用 `canvas.navigate` 和 `{"url":""}` 可返回内置脚手架。 ### Canvas eval / snapshot @@ -203,20 +219,20 @@ openclaw nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaSc openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}' ``` -## 语音唤醒 + 对话模式 +## 语音唤醒 + 对讲模式 -- 设置中提供语音唤醒和对话模式。 -- iOS 可能会挂起后台音频；当应用未处于活动状态时，应将语音功能视为尽力而为。 +- 语音唤醒和对讲模式可在 Settings 中启用。 +- iOS 可能会暂停后台音频；当应用不处于活动状态时，语音功能应视为尽力而为。 ## 常见错误 -- `NODE_BACKGROUND_UNAVAILABLE`：请将 iOS 应用切换到前台（canvas / camera / screen 命令需要它处于前台）。 -- `A2UI_HOST_NOT_CONFIGURED`：Gateway 网关未广播 canvas host URL；请检查 [Gateway 配置](/gateway/configuration) 中的 `canvasHost`。 +- `NODE_BACKGROUND_UNAVAILABLE`：请将 iOS 应用切到前台（canvas/相机/屏幕命令需要前台状态）。 +- `A2UI_HOST_NOT_CONFIGURED`：Gateway 网关没有广播 canvas host URL；请检查 [Gateway 配置](/zh-CN/gateway/configuration) 中的 `canvasHost`。 - 配对提示始终不出现：运行 `openclaw devices list` 并手动批准。 -- 重装后重连失败：Keychain 配对令牌已被清除；请重新配对节点。 +- 重装后重连失败：Keychain 配对 token 已被清除；请重新配对节点。 ## 相关文档 -- [配对](/channels/pairing) -- [设备发现](/gateway/discovery) -- [Bonjour](/gateway/bonjour) +- [配对](/zh-CN/channels/pairing) +- [设备发现](/zh-CN/gateway/discovery) +- [Bonjour](/zh-CN/gateway/bonjour) diff --git a/docs/zh-CN/plugins/architecture.md b/docs/zh-CN/plugins/architecture.md index d8ba597dd..293d13ccd 100644 --- a/docs/zh-CN/plugins/architecture.md +++ b/docs/zh-CN/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - 构建或调试原生 OpenClaw 插件 - - 了解插件能力模型或归属边界 + - 理解插件能力模型或归属边界 - 处理插件加载流水线或注册表 - - 实现提供商运行时钩子或渠道插件 + - 实现提供商运行时 hook 或渠道插件 sidebarTitle: Internals summary: 插件内部机制：能力模型、归属、契约、加载流水线和运行时辅助工具 title: 插件内部机制 x-i18n: - generated_at: "2026-04-06T12:45:34Z" + generated_at: "2026-04-06T15:32:43Z" model: gpt-5.4 provider: openai - source_hash: b2f7f48bd5599b9897aa851fb25d501d9643d76f66084f5867b3866fec91cef6 + source_hash: 8780d364f6784e4d44b4160f5c6b24fe34aaf31dec1b6ac5b06a90d54ac0403c source_path: plugins/architecture.md workflow: 15 --- @@ -20,129 +20,156 @@ x-i18n: 这是**深度架构参考**。如需实用指南，请参阅： - - [安装和使用插件](/zh-CN/tools/plugin) — 用户指南 - - [入门指南](/zh-CN/plugins/building-plugins) — 第一个插件教程 - - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建一个消息渠道 - - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建一个模型提供商 - - [SDK 概览](/zh-CN/plugins/sdk-overview) — 导入映射和注册 API + - [Install and use plugins](/zh-CN/tools/plugin) —— 用户指南 + - [入门指南](/zh-CN/plugins/building-plugins) —— 第一个插件教程 + - [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins) —— 构建一个消息渠道 + - [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins) —— 构建一个模型提供商 + - [SDK 概览](/zh-CN/plugins/sdk-overview) —— 导入映射和注册 API 本页介绍 OpenClaw 插件系统的内部架构。 -## 公开能力模型 +## 公共能力模型 -能力是 OpenClaw 内部公开的**原生插件**模型。每个原生 OpenClaw 插件都会针对一个或多个能力类型进行注册： +能力是 OpenClaw 内部公开的**原生插件**模型。每个 +原生 OpenClaw 插件都会针对一种或多种能力类型进行注册： -| 能力 | 注册方式 | 示例插件 | -| -------------------- | ------------------------------------------------ | ------------------------------------ | -| 文本推理 | `api.registerProvider(...)` | `openai`, `anthropic` | -| CLI 推理后端 | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| 语音 | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| 图像生成 | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| 音乐生成 | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| 视频生成 | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Web 抓取 | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Web 搜索 | `api.registerWebSearchProvider(...)` | `google` | -| 渠道 / 消息传递 | `api.registerChannel(...)` | `msteams`, `matrix` | +| Capability | Registration method | Example plugins | +| ---------------------- | ------------------------------------------------ | ------------------------------------ | +| 文本推理 | `api.registerProvider(...)` | `openai`, `anthropic` | +| CLI 推理后端 | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| 语音 | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| 图像生成 | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| 音乐生成 | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| 视频生成 | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Web 抓取 | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Web 搜索 | `api.registerWebSearchProvider(...)` | `google` | +| 渠道 / 消息 | `api.registerChannel(...)` | `msteams`, `matrix` | -一个注册了零个能力、但提供钩子、工具或服务的插件，被称为**仅旧版 hook** 插件。这种模式仍然得到完整支持。 +一个注册了零个能力、但提供 hooks、工具或服务的插件，属于**旧版仅 hook** 插件。这种模式仍然完全受支持。 ### 外部兼容性立场 -能力模型已经落地到 core 中，并且当前已用于内置 / 原生插件，但外部插件兼容性仍需要比“它已导出，因此已冻结”更严格的标准。 +能力模型已经在 core 中落地，并且当前已被内置 / 原生插件使用， +但外部插件兼容性仍然需要比“它已导出，因此就是冻结的”更严格的标准。 当前指导如下： -- **现有外部插件：** 保持基于 hook 的集成可用；将其视为兼容性的基准线 -- **新的内置 / 原生插件：** 优先使用显式能力注册，而不是特定厂商的直接深入访问或新的仅 hook 设计 -- **采用能力注册的外部插件：** 可以这样做，但在文档未明确将某个契约标记为稳定前，应将能力专用辅助工具接口视为仍在演进中 +- **现有外部插件：** 保持基于 hook 的集成继续工作；将其视为 + 兼容性基线 +- **新的内置 / 原生插件：** 优先选择显式能力注册，而不是 + 提供商特定的深度调用或新的仅 hook 设计 +- **采用能力注册的外部插件：** 允许这样做，但除非文档明确将某个契约标记为稳定，否则应将能力专用辅助工具 surface 视为持续演进中 实用规则： - 能力注册 API 是预期的发展方向 -- 在过渡期间，旧版 hooks 仍然是外部插件最安全、最不易破坏的路径 -- 并非所有已导出的辅助工具子路径都同等稳定；优先使用文档记录的精简契约，而不是顺带暴露的辅助导出 +- 在过渡期间，旧版 hooks 仍然是对外部插件最安全、最不易破坏的路径 +- 已导出的辅助工具子路径并不完全等价；优先使用文档化的狭窄契约， + 而不是偶然导出的辅助工具 ### 插件形态 -OpenClaw 会根据每个已加载插件的实际注册行为（而不仅是静态元数据）将其分类为以下形态之一： +OpenClaw 会根据每个已加载插件的实际注册行为来将其归类为某种形态 +（而不只是依据静态元数据）： -- **plain-capability** -- 只注册一种能力类型（例如像 `mistral` 这样的仅提供商插件） -- **hybrid-capability** -- 注册多种能力类型（例如 `openai` 同时拥有文本推理、语音、媒体理解和图像生成） -- **hook-only** -- 仅注册 hooks（类型化或自定义），没有能力、工具、命令或服务 -- **non-capability** -- 注册工具、命令、服务或路由，但不注册任何能力 +- **plain-capability** —— 恰好注册一种能力类型（例如仅提供商的 + 插件，如 `mistral`） +- **hybrid-capability** —— 注册多种能力类型（例如 + `openai` 拥有文本推理、语音、媒体理解和图像生成） +- **hook-only** —— 只注册 hooks（类型化或自定义），没有能力、 + 工具、命令或服务 +- **non-capability** —— 注册工具、命令、服务或路由，但没有能力 -使用 `openclaw plugins inspect ` 可查看插件的形态和能力拆分。详见 [CLI 参考](/cli/plugins#inspect)。 +使用 `openclaw plugins inspect ` 可查看插件的形态和能力细分。 +详情请参阅 [CLI reference](/cli/plugins#inspect)。 ### 旧版 hooks -`before_agent_start` hook 仍作为仅 hook 插件的兼容路径继续受支持。现实中仍有旧版插件依赖它。 +`before_agent_start` hook 仍作为仅 hook 插件的兼容路径而受支持。 +现实中的旧版插件仍依赖它。 方向如下： -- 保持它可用 -- 将其文档标记为旧版 -- 对模型 / 提供商覆盖工作，优先使用 `before_model_resolve` -- 对提示词变更工作，优先使用 `before_prompt_build` -- 只有在真实使用量下降，并且 fixture 覆盖证明迁移安全后，才考虑移除 +- 保持其继续工作 +- 在文档中将其标记为旧版 +- 对于模型 / 提供商覆盖工作，优先使用 `before_model_resolve` +- 对于提示词变更工作，优先使用 `before_prompt_build` +- 只有在真实使用量下降，并且 fixture 覆盖证明迁移安全后才移除 ### 兼容性信号 -当你运行 `openclaw doctor` 或 `openclaw plugins inspect ` 时，可能会看到以下标签之一： +当你运行 `openclaw doctor` 或 `openclaw plugins inspect ` 时， +你可能会看到以下标签之一： -| 信号 | 含义 | -| ------------------------ | ---------------------------------------------------------- | -| **config valid** | 配置解析正常，插件可成功解析 | -| **compatibility advisory** | 插件使用受支持但较旧的模式（例如 `hook-only`） | -| **legacy warning** | 插件使用了 `before_agent_start`，该用法已弃用 | -| **hard error** | 配置无效或插件加载失败 | +| Signal | Meaning | +| -------------------------- | ------------------------------------------------------------ | +| **配置有效** | 配置可正常解析，插件也能解析 | +| **兼容性提示** | 插件使用受支持但较旧的模式（例如 `hook-only`） | +| **旧版警告** | 插件使用 `before_agent_start`，该功能已弃用 | +| **硬错误** | 配置无效或插件加载失败 | -`hook-only` 和 `before_agent_start` 目前都不会导致你的插件中断——`hook-only` 只是提示性信息，而 `before_agent_start` 只会触发警告。这些信号也会显示在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 +`hook-only` 和 `before_agent_start` 目前都不会破坏你的插件 —— `hook-only` +只是提示，而 `before_agent_start` 只会触发警告。这些信号也会出现在 +`openclaw status --all` 和 `openclaw plugins doctor` 中。 ## 架构概览 -OpenClaw 的插件系统有四层： +OpenClaw 的插件系统由四层组成： 1. **清单 + 发现** - OpenClaw 会从配置路径、工作区根目录、全局扩展根目录以及内置扩展中查找候选插件。发现过程会先读取原生 `openclaw.plugin.json` 清单以及受支持的 bundle 清单。 + OpenClaw 会从已配置路径、工作区根目录、 + 全局扩展根目录以及内置扩展中查找候选插件。 + 发现过程会优先读取原生 `openclaw.plugin.json` 清单以及受支持的 bundle 清单。 2. **启用 + 校验** - core 会决定某个已发现插件是启用、禁用、阻止，还是被选中用于某个独占槽位（例如 memory）。 + Core 决定某个已发现插件是启用、禁用、阻止，还是 + 被选入某个独占槽位（如 memory）。 3. **运行时加载** - 原生 OpenClaw 插件会通过 jiti 在进程内加载，并将能力注册到中央注册表中。兼容 bundle 会被规范化为注册表记录，而无需导入运行时代码。 -4. **接口消费** - OpenClaw 的其余部分会读取注册表，以暴露工具、渠道、提供商设置、hooks、HTTP 路由、CLI 命令和服务。 + 原生 OpenClaw 插件通过 jiti 在进程内加载，并将能力注册到中央注册表中。兼容 bundle 会被规范化为注册表记录，而不导入运行时代码。 +4. **Surface 消费** + OpenClaw 的其余部分读取注册表，以暴露工具、渠道、提供商 + 设置、hooks、HTTP 路由、CLI 命令和服务。 -对于插件 CLI 而言，根命令发现被拆分为两个阶段： +对于插件 CLI，本身的根命令发现分为两个阶段： -- 解析阶段元数据来自 `registerCli(..., { descriptors: [...] })` -- 真正的插件 CLI 模块可以保持惰性加载，并在首次调用时注册 +- 解析时元数据来自 `registerCli(..., { descriptors: [...] })` +- 真正的插件 CLI 模块可以保持懒加载，并在首次调用时注册 -这样既能让插件自有的 CLI 代码留在插件内部，又能让 OpenClaw 在解析前预留根命令名称。 +这样既能让插件拥有自己的 CLI 代码，又能让 OpenClaw 在解析之前保留根命令名称。 -重要的设计边界： +重要的设计边界是： -- 发现 + 配置校验应当基于**清单 / schema 元数据**完成，而无需执行插件代码 +- 发现 + 配置校验应当能够基于**清单 / schema 元数据** + 在不执行插件代码的前提下工作 - 原生运行时行为来自插件模块的 `register(api)` 路径 -这种分离让 OpenClaw 能在完整运行时尚未激活前，就校验配置、解释缺失 / 禁用插件，并构建 UI / schema 提示。 +这种拆分使 OpenClaw 能够在完整运行时尚未激活前，校验配置、 +解释缺失 / 已禁用插件，并构建 UI / schema 提示。 -### 渠道插件与共享消息工具 +### 渠道插件和共享 message 工具 -对于常规聊天操作，渠道插件不需要单独注册发送 / 编辑 / 响应工具。OpenClaw 在 core 中保留一个共享的 `message` 工具，而渠道插件负责其背后的渠道专属发现和执行。 +对于普通聊天操作，渠道插件不需要单独注册发送 / 编辑 / 反应工具。 +OpenClaw 在 core 中保留一个共享的 `message` 工具，而 +渠道插件拥有其背后的渠道专用发现和执行逻辑。 当前边界如下： -- core 负责共享 `message` 工具宿主、提示词接线、会话 / 线程记录，以及执行分发 -- 渠道插件负责作用域操作发现、能力发现，以及任何渠道专属 schema 片段 -- 渠道插件负责提供商专属的会话会话语法，例如会话 id 如何编码线程 id，或如何从父会话继承 -- 渠道插件通过其 action adapter 执行最终操作 +- core 拥有共享 `message` 工具宿主、提示词接线、session / thread + 记录和执行分发 +- 渠道插件拥有作用域动作发现、能力发现，以及任何 + 渠道专用 schema 片段 +- 渠道插件拥有提供商专用的 session 会话语法，例如 + 会话 id 如何编码 thread id，或如何从父会话继承 +- 渠道插件通过其动作适配器执行最终动作 -对于渠道插件，SDK 接口为 `ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一发现调用让插件可以将其可见操作、能力和 schema 扩展一起返回，从而避免这些部分彼此漂移。 +对于渠道插件，SDK surface 是 +`ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的发现调用可让插件一起返回其可见动作、能力和 schema +贡献，从而避免这些部分彼此漂移。 -core 会在发现步骤中传入运行时作用域。重要字段包括： +Core 会将运行时作用域传入该发现步骤。重要字段包括： - `accountId` - `currentChannelId` @@ -151,87 +178,119 @@ core 会在发现步骤中传入运行时作用域。重要字段包括： - `sessionKey` - `sessionId` - `agentId` -- 受信任入站 `requesterSenderId` +- 可信入站 `requesterSenderId` -这对于上下文敏感型插件很重要。渠道可以基于当前账户、当前房间 / 线程 / 消息，或受信任的请求方身份，来隐藏或暴露消息操作，而不需要在 core `message` 工具中硬编码渠道专属分支。 +这对于上下文敏感插件非常重要。渠道可以根据当前活跃账户、 +当前房间 / 线程 / 消息，或可信请求者身份来隐藏或暴露 +消息动作，而无需在 core 的 `message` 工具中硬编码渠道专用分支。 -这也是为什么嵌入式 runner 路由变更仍然属于插件工作：runner 负责将当前聊天 / 会话身份转发到插件发现边界，使共享 `message` 工具在当前轮次暴露正确的渠道自有接口。 +这也是为什么嵌入式 runner 路由变更仍然是插件工作：runner +负责将当前聊天 / 会话身份转发到插件发现边界，以便共享的 +`message` 工具能够为当前轮次暴露正确的渠道自有 surface。 -对于渠道自有的执行辅助工具，内置插件应将执行运行时保留在它们自己的扩展模块中。core 不再拥有位于 `src/agents/tools` 下的 Discord、Slack、Telegram 或 WhatsApp 消息操作运行时。我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，内置插件应直接从其扩展自有模块导入本地运行时代码。 +对于渠道自有的执行辅助工具，内置插件应将执行运行时保留在 +自己的扩展模块中。Core 不再在 `src/agents/tools` 下拥有 +Discord、Slack、Telegram 或 WhatsApp 的消息动作运行时。 +我们不会单独发布 `plugin-sdk/*-action-runtime` 子路径，内置 +插件应直接从其自有扩展模块中导入本地运行时代码。 -同样的边界也适用于一般意义上的提供商命名 SDK 接缝：core 不应导入面向 Slack、Discord、Signal、WhatsApp 或类似扩展的渠道专用便捷 barrel。如果 core 需要某种行为，要么消费内置插件自己的 `api.ts` / `runtime-api.ts` barrel，要么将该需求提升为共享 SDK 中一个精简的通用能力。 +同样的边界也适用于一般性的提供商命名 SDK 接缝：core +不应导入 Slack、Discord、Signal、WhatsApp 或类似扩展的 +渠道专用便捷 barrel。如果 core 需要某种行为， +要么消费内置插件自己的 `api.ts` / `runtime-api.ts` barrel， +要么将该需求提升为共享 SDK 中狭窄的通用能力。 -对于投票，当前有两条执行路径： +对于投票，具体有两条执行路径： -- `outbound.sendPoll` 是适用于符合通用投票模型的渠道的共享基线 -- `actions.handleAction("poll")` 是渠道专属投票语义或额外投票参数的首选路径 +- `outbound.sendPoll` 是适用于符合通用投票模型渠道的共享基线 +- `actions.handleAction("poll")` 是渠道专用投票语义或额外投票参数的首选路径 -现在，core 会先尝试插件投票分发，只有在插件拒绝处理该操作后，才会回退到共享投票解析。这使插件自有的投票处理器能够接受渠道专属投票字段，而不会先被通用投票解析器阻挡。 +Core 现在会等到插件投票分发拒绝该动作后，才延迟执行共享投票解析， +因此插件自有的投票处理器可以接受渠道专用投票字段，而不会先被 +通用投票解析器阻塞。 -完整启动顺序请参阅[加载流水线](#load-pipeline)。 +完整启动顺序请参阅 [Load pipeline](#load-pipeline)。 ## 能力归属模型 -OpenClaw 将原生插件视为某个**公司**或某个**功能**的归属边界，而不是一堆无关集成的杂项集合。 +OpenClaw 将原生插件视为某个**公司**或某项**功能**的归属边界， +而不是一堆无关集成的杂糅包。 这意味着： -- 一个公司插件通常应拥有该公司的所有 OpenClaw 面向接口 -- 一个功能插件通常应拥有其引入的完整功能接口 -- 渠道应消费共享 core 能力，而不是临时重复实现提供商行为 +- 一个公司插件通常应拥有该公司的所有 OpenClaw 对外 surface +- 一个功能插件通常应拥有它引入的完整功能 surface +- 渠道应消费共享 core 能力，而不是临时重新实现 + 提供商行为 示例： -- 内置 `openai` 插件拥有 OpenAI 模型提供商行为，以及 OpenAI 的语音 + 实时语音 + 媒体理解 + 图像生成行为 -- 内置 `elevenlabs` 插件拥有 ElevenLabs 语音行为 -- 内置 `microsoft` 插件拥有 Microsoft 语音行为 -- 内置 `google` 插件拥有 Google 模型提供商行为，以及 Google 的媒体理解 + 图像生成 + Web 搜索行为 -- 内置 `firecrawl` 插件拥有 Firecrawl Web 抓取行为 -- 内置 `minimax`、`mistral`、`moonshot` 和 `zai` 插件拥有它们各自的媒体理解后端 -- 内置 `qwen` 插件拥有 Qwen 文本提供商行为，以及媒体理解和视频生成行为 -- `voice-call` 插件是一个功能插件：它拥有呼叫传输、工具、CLI、路由和 Twilio 媒体流桥接，但它消费共享的语音以及实时转写和实时语音能力，而不是直接导入厂商插件 +- 内置的 `openai` 插件拥有 OpenAI 模型提供商行为，以及 OpenAI + 语音 + 实时语音 + 媒体理解 + 图像生成行为 +- 内置的 `elevenlabs` 插件拥有 ElevenLabs 语音行为 +- 内置的 `microsoft` 插件拥有 Microsoft 语音行为 +- 内置的 `google` 插件拥有 Google 模型提供商行为，以及 Google + 媒体理解 + 图像生成 + Web 搜索行为 +- 内置的 `firecrawl` 插件拥有 Firecrawl Web 抓取行为 +- 内置的 `minimax`、`mistral`、`moonshot` 和 `zai` 插件拥有各自的 + 媒体理解后端 +- `qwen` 内置插件拥有 Qwen 文本提供商行为，以及 + 媒体理解和视频生成行为 +- `voice-call` 插件是一个功能插件：它拥有通话传输、工具、 + CLI、路由和 Twilio 媒体流桥接，但它消费共享的语音 + 以及实时转录和实时语音能力，而不是直接导入提供商插件 -预期的最终状态是： +期望中的最终状态是： -- 即使 OpenAI 同时覆盖文本模型、语音、图像和未来的视频，它也只存在于一个插件中 -- 其他厂商也可以为自己的接口范围采用同样方式 -- 渠道不需要关心哪个厂商插件拥有该提供商；它们只消费 core 暴露的共享能力契约 +- OpenAI 即使跨越文本模型、语音、图像和未来视频，也仍驻留在同一个插件中 +- 其他提供商也可以用同样方式拥有自己的完整 surface area +- 渠道不关心哪个提供商插件拥有该提供商；它们消费的是 + core 暴露的共享能力契约 -这是关键区别： +这就是关键区别： - **plugin** = 归属边界 - **capability** = 多个插件都可以实现或消费的 core 契约 -因此，如果 OpenClaw 新增一个如视频这样的领域，第一个问题不应该是“哪个提供商应硬编码视频处理？”而应该是“core 的视频能力契约是什么？”一旦该契约存在，厂商插件就可以针对它进行注册，渠道 / 功能插件也可以消费它。 +因此，如果 OpenClaw 添加一个新领域，例如视频，首要问题不是 +“哪个提供商应该硬编码视频处理？” 首要问题是“core 的视频能力契约是什么？” +一旦该契约存在，提供商插件就可以注册到它上面， +而渠道 / 功能插件也可以消费它。 如果该能力尚不存在，通常正确的做法是： 1. 在 core 中定义缺失的能力 2. 通过插件 API / 运行时以类型化方式暴露它 -3. 让渠道 / 功能围绕该能力接线 -4. 允许厂商插件注册实现 +3. 让渠道 / 功能接入该能力 +4. 让提供商插件注册实现 -这样可以在保持明确归属的同时，避免 core 行为依赖某个单一厂商或某条一次性的插件专用代码路径。 +这样既能保持归属明确，又能避免 core 行为依赖单一提供商 +或某个一次性的插件专用代码路径。 ### 能力分层 -在决定代码归属位置时，请使用以下思维模型： +在决定代码归属时，可使用以下思维模型： -- **core 能力层**：共享编排、策略、回退、配置合并规则、传递语义和类型化契约 -- **厂商插件层**：厂商专属 API、认证、模型目录、语音合成、图像生成、未来的视频后端、用量端点 -- **渠道 / 功能插件层**：Slack / Discord / voice-call 等集成，它们消费 core 能力并在某个接口上呈现出来 +- **core 能力层**：共享编排、策略、回退、配置 + 合并规则、传递语义和类型化契约 +- **提供商插件层**：提供商专用 API、认证、模型目录、语音 + 合成、图像生成、未来的视频后端、用量端点 +- **渠道 / 功能插件层**：Slack / Discord / voice-call 等集成， + 它们消费 core 能力并在某个 surface 上呈现出来 -例如，TTS 采用以下形态： +例如，TTS 遵循如下形态： - core 拥有回复时 TTS 策略、回退顺序、偏好和渠道传递 - `openai`、`elevenlabs` 和 `microsoft` 拥有合成实现 -- `voice-call` 消费电话场景的 TTS 运行时辅助工具 +- `voice-call` 消费电话 TTS 运行时辅助工具 -未来的能力也应优先遵循相同模式。 +未来能力也应优先遵循同样模式。 ### 多能力公司插件示例 -一个公司插件从外部看应当是内聚的。如果 OpenClaw 对模型、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、Web 抓取和 Web 搜索都有共享契约，那么某个厂商就可以在一个地方拥有其全部接口： +从外部看，一个公司插件应该具备内聚感。如果 OpenClaw 拥有用于 +模型、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、 +Web 抓取和 Web 搜索的共享契约，那么一个提供商可以在同一处拥有其所有 surface： ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -285,177 +344,213 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -关键不在于精确的辅助工具名称，而在于其结构： +重要的不是确切的辅助工具名称，而是整体形态： -- 一个插件拥有该厂商接口 +- 一个插件拥有该提供商 surface - core 仍然拥有能力契约 -- 渠道和功能插件消费 `api.runtime.*` 辅助工具，而不是厂商代码 +- 渠道和功能插件消费 `api.runtime.*` 辅助工具，而不是提供商代码 - 契约测试可以断言插件注册了它声称拥有的能力 ### 能力示例：视频理解 -OpenClaw 已将图像 / 音频 / 视频理解视为一种共享能力。同样的归属模型也适用于这里： +OpenClaw 已经将图像 / 音频 / 视频理解视为一种共享能力。 +同样的归属模型也适用于这里： 1. core 定义媒体理解契约 -2. 厂商插件按需注册 `describeImage`、`transcribeAudio` 和 `describeVideo` -3. 渠道和功能插件消费共享 core 行为，而不是直接接线到厂商代码 +2. 提供商插件按需注册 `describeImage`、`transcribeAudio` 和 + `describeVideo` +3. 渠道和功能插件消费共享的 core 行为，而不是直接接线到提供商代码 -这样可以避免把某个提供商对视频的假设固化进 core。插件拥有厂商接口；core 拥有能力契约和回退行为。 +这样就能避免将某个提供商的视频假设固化进 core。插件拥有 +提供商 surface；core 拥有能力契约和回退行为。 -视频生成已经使用同样的顺序：core 拥有类型化能力契约和运行时辅助工具，厂商插件针对其注册 `api.registerVideoGenerationProvider(...)` 实现。 +视频生成也已经遵循同样顺序：core 拥有类型化能力契约和 +运行时辅助工具，而提供商插件注册 +`api.registerVideoGenerationProvider(...)` 实现。 -需要一个具体的发布清单？请参阅[能力扩展手册](/zh-CN/plugins/architecture)。 +需要具体的发布检查清单吗？请参阅 +[能力扩展手册](/zh-CN/plugins/architecture)。 -## 契约与约束执行 +## 契约和约束执行 -插件 API 接口被有意设计为类型化并集中在 `OpenClawPluginApi` 中。该契约定义了受支持的注册点，以及插件可以依赖的运行时辅助工具。 +插件 API surface 被有意类型化并集中定义在 +`OpenClawPluginApi` 中。该契约定义了受支持的注册点以及 +插件可以依赖的运行时辅助工具。 -这很重要，因为： +其重要性在于： -- 插件作者获得一个稳定的内部标准 -- core 可以拒绝重复归属，例如两个插件注册同一个 provider id -- 启动时可以为格式错误的注册提供可执行的诊断信息 -- 契约测试可以约束内置插件归属并防止静默漂移 +- 插件作者拥有统一且稳定的内部标准 +- core 可以拒绝重复归属，例如两个插件注册相同的 + provider id +- 启动阶段可以为格式错误的注册暴露可执行诊断信息 +- 契约测试可以强制内置插件归属，防止无声漂移 -存在两层约束执行： +约束执行有两层： 1. **运行时注册约束** - 插件注册表会在插件加载时校验注册。例如：重复的 provider id、重复的 speech provider id，以及格式错误的注册，都会产生插件诊断，而不是未定义行为。 + 插件在加载时，插件注册表会校验其注册。例如： + 重复 provider id、重复 speech provider id 和格式错误的 + 注册会产生插件诊断信息，而不是未定义行为。 2. **契约测试** - 在测试运行期间，内置插件会被捕获到契约注册表中，以便 OpenClaw 显式断言归属。当前这被用于模型提供商、语音提供商、Web 搜索提供商和内置注册归属。 + 在测试运行期间，内置插件会被捕获到契约注册表中，以便 + OpenClaw 能明确断言归属。如今这用于模型 + 提供商、语音提供商、Web 搜索提供商以及内置注册归属。 -实际效果是，OpenClaw 可以预先知道哪个插件拥有哪个接口。这使得 core 和渠道能够无缝组合，因为归属是声明式、类型化且可测试的，而不是隐式的。 +其实际效果是，OpenClaw 可以预先知道哪个插件拥有哪个 +surface。这使 core 和渠道能够无缝组合，因为归属是声明式、 +类型化且可测试的，而不是隐式的。 -### 哪些内容应属于契约 +### 什么应属于契约 好的插件契约应当是： -- 类型化的 -- 精简的 -- 能力专用的 +- 类型化 +- 小而精 +- 能力专用 - 由 core 拥有 - 可被多个插件复用 -- 可被渠道 / 功能消费，而无需了解厂商细节 +- 可被渠道 / 功能消费，而无需了解提供商细节 不好的插件契约包括： -- 隐藏在 core 中的厂商专属策略 -- 绕过注册表的一次性插件逃生口 -- 渠道代码直接深入某个厂商实现 -- 不属于 `OpenClawPluginApi` 或 `api.runtime` 的临时运行时对象 +- 隐藏在 core 中的提供商专用策略 +- 绕过注册表的一次性插件逃逸口 +- 直接深入某个提供商实现的渠道代码 +- 不属于 `OpenClawPluginApi` 或 + `api.runtime` 的临时运行时对象 -如果有疑问，请提升抽象层级：先定义能力，再让插件接入。 +如果拿不准，就提升抽象层级：先定义能力，再让插件接入它。 ## 执行模型 -原生 OpenClaw 插件会与 Gateway 网关**在同一进程内**运行。它们**不**在沙箱中运行。一个已加载的原生插件与 core 代码具有相同的进程级信任边界。 +原生 OpenClaw 插件与 Gateway 网关**运行在同一进程内**。 +它们没有沙箱隔离。已加载的原生插件与 core 代码处于相同的进程级信任边界。 -影响如下： +含义如下： - 原生插件可以注册工具、网络处理器、hooks 和服务 - 原生插件中的 bug 可能导致 gateway 崩溃或不稳定 - 恶意原生插件等同于在 OpenClaw 进程内执行任意代码 -兼容 bundle 默认更安全，因为 OpenClaw 当前将其视为元数据 / 内容包。在当前版本中，这主要意味着内置 Skills。 +兼容 bundle 默认更安全，因为 OpenClaw 当前将其视为 +元数据 / 内容包。当前版本里，这主要指内置 +Skills。 -对于非内置插件，请使用 allowlist 和显式安装 / 加载路径。应将工作区插件视为开发时代码，而不是生产默认项。 +对于非内置插件，请使用 allowlist 和显式安装 / 加载路径。将 +工作区插件视为开发期代码，而不是生产默认项。 -对于内置工作区包名，请确保插件 id 锚定在 npm 名称中：默认使用 `@openclaw/`，或使用经批准的类型后缀，如 `-provider`、`-plugin`、`-speech`、`-sandbox` 或 `-media-understanding`，前提是该包刻意暴露更窄的插件角色。 +对于内置工作区包名，请保持插件 id 锚定在 npm +包名中：默认使用 `@openclaw/`，或者使用批准的类型后缀，如 +`-provider`、`-plugin`、`-speech`、`-sandbox` 或 +`-media-understanding`，前提是该包有意暴露更狭窄的插件角色。 重要信任说明： - `plugins.allow` 信任的是**插件 id**，而不是来源出处。 -- 如果某个工作区插件与一个内置插件拥有相同 id，并且该工作区插件被启用 / 加入 allowlist，它会有意遮蔽内置副本。 -- 这属于正常且有用的行为，适用于本地开发、补丁测试和热修复。 +- 与内置插件拥有相同 id 的工作区插件，在启用 / 加入 allowlist 后，会有意遮蔽内置副本。 +- 这是一种正常且有用的机制，适用于本地开发、补丁测试和热修复。 ## 导出边界 -OpenClaw 导出的是能力，而不是实现层面的便捷接口。 +OpenClaw 导出的是能力，而不是实现便捷性。 -请保持能力注册为公开接口，同时收紧非契约辅助工具导出： +保持能力注册为公共内容。削减非契约辅助工具导出： - 内置插件专用辅助工具子路径 -- 不打算作为公开 API 的运行时管线子路径 -- 厂商专用便捷辅助工具 -- 属于实现细节的设置 / 新手引导辅助工具 +- 不打算作为公共 API 的运行时接线子路径 +- 提供商专用便捷辅助工具 +- 属于实现细节的 setup / onboarding 辅助工具 -出于兼容性和内置插件维护需要，一些内置插件辅助工具子路径仍保留在生成的 SDK 导出映射中。当前示例包括 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 以及若干 `plugin-sdk/matrix*` 接缝。应将这些视为保留的实现细节导出，而不是新第三方插件推荐采用的 SDK 模式。 +出于兼容性和内置插件维护需要，某些内置插件辅助工具子路径 +仍保留在生成的 SDK 导出映射中。当前示例包括 +`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 +`plugin-sdk/zalo-setup`，以及若干 `plugin-sdk/matrix*` 接缝。请将这些视为保留的实现细节导出，而不是新第三方插件推荐使用的 SDK 模式。 ## 加载流水线 -在启动时，OpenClaw 大致会执行以下步骤： +启动时，OpenClaw 大致会执行以下步骤： 1. 发现候选插件根目录 -2. 读取原生或兼容 bundle 的清单及包元数据 -3. 拒绝不安全候选项 -4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、`slots`、`load.paths`） -5. 决定每个候选项的启用状态 +2. 读取原生或兼容 bundle 的清单和包元数据 +3. 拒绝不安全的候选项 +4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、 + `slots`、`load.paths`） +5. 为每个候选项决定启用状态 6. 通过 jiti 加载已启用的原生模块 -7. 调用原生 `register(api)`（或 `activate(api)` —— 旧版别名）hooks，并将注册收集到插件注册表中 -8. 向命令 / 运行时接口暴露注册表 +7. 调用原生 `register(api)`（或 `activate(api)` —— 旧版别名）hook，并将注册项收集到插件注册表中 +8. 将注册表暴露给命令 / 运行时 surface -`activate` 是 `register` 的旧版别名——加载器会解析存在的那个（`def.register ?? def.activate`），并在相同位置调用它。所有内置插件都使用 `register`；新插件请优先使用 `register`。 +`activate` 是 `register` 的旧版别名 —— 加载器会解析两者中存在的那个（`def.register ?? def.activate`），并在同一时机调用它。所有内置插件都使用 `register`；新插件请优先使用 `register`。 -安全门禁发生在**运行时执行之前**。当入口逃逸出插件根目录、路径对所有人可写，或者对于非内置插件来说路径所有权看起来可疑时，候选项会被阻止。 +安全门槛发生在**运行时执行之前**。当入口逃离插件根目录、 +路径对全世界可写，或对于非内置插件而言路径归属看起来可疑时， +候选项会被阻止。 ### 清单优先行为 -清单是控制平面的事实来源。OpenClaw 用它来： +清单是控制平面的真实来源。OpenClaw 用它来： -- 标识插件 -- 发现已声明的渠道 / Skills / 配置 schema 或 bundle 能力 +- 识别插件 +- 发现声明的渠道 / Skills / 配置 schema 或 bundle 能力 - 校验 `plugins.entries..config` -- 补充 Control UI 标签 / 占位文本 +- 增强 Control UI 标签 / 占位符 - 显示安装 / 目录元数据 -对于原生插件，运行时模块是数据平面部分。它会注册实际行为，例如 hooks、工具、命令或提供商流程。 +对于原生插件，运行时模块是数据平面部分。它注册诸如 +hooks、工具、命令或提供商流程等实际行为。 ### 加载器会缓存什么 -OpenClaw 会保留以下短生命周期的进程内缓存： +OpenClaw 会保留短期的进程内缓存，用于： - 发现结果 - 清单注册表数据 - 已加载的插件注册表 -这些缓存可减少突发启动和重复命令的开销。可以将它们视为短期性能缓存，而不是持久化机制。 +这些缓存可减少突发式启动和重复命令开销。可以放心地将它们视为 +短生命周期性能缓存，而不是持久化。 性能说明： -- 设置 `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` 或 `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` 可禁用这些缓存。 -- 使用 `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` 和 `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` 调整缓存窗口。 +- 设置 `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` 或 + `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` 可禁用这些缓存。 +- 使用 `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` 和 + `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` 调整缓存窗口。 ## 注册表模型 -已加载的插件不会直接修改任意 core 全局状态。它们会注册到一个中央插件注册表中。 +已加载插件不会直接变更各种 core 全局状态。它们会注册到一个 +中央插件注册表中。 -注册表会跟踪： +该注册表会跟踪： -- 插件记录（身份、来源、起源、状态、诊断） +- 插件记录（身份、来源、出处、状态、诊断信息） - 工具 - 旧版 hooks 和类型化 hooks - 渠道 - 提供商 -- Gateway RPC 处理器 +- Gateway 网关 RPC 处理器 - HTTP 路由 - CLI 注册器 - 后台服务 - 插件自有命令 -随后，core 功能会从该注册表读取内容，而不是直接与插件模块通信。这样可保持加载为单向流： +随后，core 功能会从该注册表中读取，而不是直接与插件模块交互。 +这让加载保持单向： - 插件模块 -> 注册表注册 - core 运行时 -> 注册表消费 -这种分离对可维护性很重要。它意味着大多数 core 接口只需要一个集成点：“读取注册表”，而不是“为每个插件模块单独特判”。 +这种分离对于可维护性非常重要。它意味着多数 core surface +只需要一个集成点：“读取注册表”，而不是“为每个插件模块写特殊分支”。 ## 会话绑定回调 -绑定会话的插件可以在批准被解决后做出反应。 +绑定会话的插件可以在审批结果解析后作出响应。 -使用 `api.onConversationBindingResolved(...)`，可在绑定请求获批或被拒后收到回调： +使用 `api.onConversationBindingResolved(...)` 可在绑定请求被批准或拒绝后接收回调： ```ts export default { @@ -479,20 +574,23 @@ export default { - `status`：`"approved"` 或 `"denied"` - `decision`：`"allow-once"`、`"allow-always"` 或 `"deny"` -- `binding`：针对已批准请求的已解析绑定 -- `request`：原始请求摘要、分离提示、发送者 id 和会话元数据 +- `binding`：已批准请求对应的解析后绑定 +- `request`：原始请求摘要、detach 提示、发送者 id 和 + 会话元数据 -该回调仅用于通知。它不会改变谁被允许绑定会话，并且它会在 core 审批处理完成后运行。 +此回调仅用于通知。它不会改变谁被允许绑定会话， +并且它会在 core 审批处理完成后运行。 ## 提供商运行时 hooks -提供商插件现在有两层： +提供商插件现在分为两层： -- 清单元数据：`providerAuthEnvVars` 用于在运行时加载前进行廉价的环境变量认证查找，`providerAuthChoices` 用于在运行时加载前提供廉价的新手引导 / 认证选项标签和 CLI flag 元数据 -- 配置时 hooks：`catalog` / 旧版 `discovery`，以及 `applyConfigDefaults` -- 运行时 hooks：`normalizeModelId`、`normalizeTransport`、`normalizeConfig`、 +- 清单元数据：`providerAuthEnvVars` 用于在运行时加载前进行廉价的环境认证查找，`providerAuthChoices` 用于在运行时加载前为新手引导 / 认证选择标签和 CLI flag 元数据提供廉价支持 +- 配置时 hooks：`catalog` / 旧版 `discovery` 以及 `applyConfigDefaults` +- 运行时 hooks：`normalizeModelId`、`normalizeTransport`、 + `normalizeConfig`、 `applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、 - `resolveSyntheticAuth`、`resolveExternalOAuthProfiles`、 + `resolveSyntheticAuth`、`resolveExternalAuthProfiles`、 `shouldDeferSyntheticProfileAuth`、 `resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、 `contributeResolvedModelCompat`、`capabilities`、 @@ -509,66 +607,74 @@ export default { `buildReplayPolicy`、 `sanitizeReplayHistory`、`validateReplayTurns`、`onModelSelected` -OpenClaw 仍然拥有通用智能体循环、故障切换、转录处理和工具策略。这些 hooks 是提供商专属行为的扩展接口，而无需实现完整的自定义推理传输层。 +OpenClaw 仍拥有通用智能体循环、故障转移、transcript 处理和 +工具策略。这些 hooks 是提供商专用行为的扩展 surface， +无需整套自定义推理传输实现。 -当提供商有基于环境变量的凭据，并且通用认证 / 状态 / 模型选择器路径需要在不加载插件运行时的情况下看到它们时，请使用清单中的 `providerAuthEnvVars`。当新手引导 / 认证选项 CLI 接口需要在不加载提供商运行时的情况下知道该提供商的 choice id、分组标签和简单单 flag 认证接线时，请使用清单中的 `providerAuthChoices`。而提供商运行时中的 `envVars` 则应保留给面向运维者的提示，例如新手引导标签或 OAuth client id / client secret 设置变量。 +当某个提供商具有基于环境变量的凭证，并且希望通用认证 / 状态 / 模型选择器路径在不加载插件运行时的情况下看到它们时，请使用清单中的 `providerAuthEnvVars`。当新手引导 / 认证选择 CLI surface 应该在不加载提供商运行时的前提下了解该提供商的 choice id、分组标签和简单的单 flag 认证接线时，请使用清单中的 `providerAuthChoices`。将提供商运行时 `envVars` 保留给面向运维人员的提示，例如新手引导标签或 OAuth +client-id / client-secret 设置环境变量。 -### Hook 顺序与使用方式 +### Hook 顺序和使用场景 -对于模型 / 提供商插件，OpenClaw 大致按以下顺序调用 hooks。 -“何时使用”列是快速决策指南。 +对于模型 / 提供商插件，OpenClaw 大致按如下顺序调用 hooks。 +“何时使用”一栏是快速决策指南。 -| # | Hook | 作用 | 何时使用 | -| --- | --------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | 在生成 `models.json` 时将提供商配置发布到 `models.providers` | 提供商拥有目录或 base URL 默认值 | -| 2 | `applyConfigDefaults` | 在配置实体化期间应用提供商自有的全局配置默认值 | 默认值依赖认证模式、环境或提供商模型家族语义 | -| -- | _(built-in model lookup)_ | OpenClaw 会先尝试正常的注册表 / 目录路径 | _(不是插件 hook)_ | -| 3 | `normalizeModelId` | 在查找前规范化旧版或预览 model id 别名 | 提供商拥有规范模型解析前的别名清理逻辑 | -| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商家族的 `api` / `baseUrl` | 提供商拥有同一传输家族中自定义提供商 id 的传输清理逻辑 | -| 5 | `normalizeConfig` | 在运行时 / 提供商解析前规范化 `models.providers.` | 提供商需要将配置清理逻辑放在插件内；内置 Google 家族辅助工具也会为受支持的 Google 配置项提供兜底规范化 | -| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式用量兼容性重写 | 提供商需要针对端点驱动的原生流式用量元数据修复 | -| 7 | `resolveConfigApiKey` | 在加载运行时认证前，为配置提供商解析环境标记认证 | 提供商拥有自己的环境标记 API key 解析逻辑；`amazon-bedrock` 也在这里内置了 AWS 环境标记解析器 | -| 8 | `resolveSyntheticAuth` | 在不持久化明文的前提下暴露本地 / 自托管或基于配置的认证 | 提供商可使用 synthetic / 本地凭据标记运行 | -| 9 | `resolveExternalOAuthProfiles` | 覆盖外部 OAuth 配置文件；默认 `persistence` 为 `runtime-only`，适用于 CLI / 应用自有凭据 | 提供商复用外部 OAuth 凭据，而不持久化复制的 refresh token | -| 10 | `shouldDeferSyntheticProfileAuth` | 在 env / 配置驱动认证之后降低已存储 synthetic profile 占位项的优先级 | 提供商存储了 synthetic 占位 profile，且不应让它们优先生效 | -| 11 | `resolveDynamicModel` | 为尚未存在于本地注册表中的提供商自有 model id 提供同步回退 | 提供商接受任意上游 model id | -| 12 | `prepareDynamicModel` | 先进行异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 前需要网络元数据 | -| 13 | `normalizeResolvedModel` | 在嵌入式 runner 使用已解析模型前进行最终重写 | 提供商需要传输重写，但仍使用 core 传输 | -| 14 | `contributeResolvedModelCompat` | 为另一个兼容传输下的厂商模型贡献兼容标记 | 提供商能在代理传输上识别自己的模型，而不接管该提供商 | -| 15 | `capabilities` | 由共享 core 逻辑使用的提供商自有转录 / 工具元数据 | 提供商需要转录 / 提供商家族特有行为 | -| 16 | `normalizeToolSchemas` | 在嵌入式 runner 看到工具 schema 之前进行规范化 | 提供商需要传输家族级别的 schema 清理 | -| 17 | `inspectToolSchemas` | 在规范化后暴露提供商自有 schema 诊断 | 提供商希望给出关键字警告，而不把提供商专用规则教给 core | -| 18 | `resolveReasoningOutputMode` | 选择原生或带标签的推理输出契约 | 提供商需要使用带标签的 reasoning / final output，而不是原生字段 | -| 19 | `prepareExtraParams` | 在通用流式选项包装器前做请求参数规范化 | 提供商需要默认请求参数或每提供商参数清理 | -| 20 | `createStreamFn` | 用自定义传输完全替换正常流路径 | 提供商需要自定义线路协议，而不仅仅是包装器 | -| 21 | `wrapStreamFn` | 在应用通用包装器后进一步包装流函数 | 提供商需要请求头 / 请求体 / 模型兼容包装，而不是自定义传输 | -| 22 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | 提供商希望通用传输发送提供商原生的轮次身份 | -| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | 提供商希望通用 WS 传输调整会话头或回退策略 | -| 24 | `formatApiKey` | 认证 profile 格式化器：将已存储 profile 转为运行时 `apiKey` 字符串 | 提供商存储额外认证元数据，并需要自定义运行时 token 形态 | -| 25 | `refreshOAuth` | 为自定义刷新端点或刷新失败策略覆盖 OAuth 刷新逻辑 | 提供商不适配共享的 `pi-ai` 刷新器 | -| 26 | `buildAuthDoctorHint` | 当 OAuth 刷新失败时附加修复提示 | 提供商需要在刷新失败后提供自有认证修复指导 | -| 27 | `matchesContextOverflowError` | 提供商自有的上下文窗口溢出匹配器 | 提供商具有通用启发式无法识别的原始溢出错误 | -| 28 | `classifyFailoverReason` | 提供商自有的故障切换原因分类 | 提供商可以将原始 API / 传输错误映射为限流 / 过载等 | -| 29 | `isCacheTtlEligible` | 面向代理 / 回传提供商的提示词缓存策略 | 提供商需要代理专用的缓存 TTL 门控 | -| 30 | `buildMissingAuthMessage` | 替换通用缺失认证恢复消息 | 提供商需要提供商专属的缺失认证恢复提示 | -| 31 | `suppressBuiltInModel` | 抑制陈旧上游模型，并可选返回面向用户的错误提示 | 提供商需要隐藏陈旧的上游条目，或用厂商提示替换它们 | -| 32 | `augmentModelCatalog` | 在发现后附加 synthetic / 最终目录条目 | 提供商需要在 `models list` 和选择器中加入 synthetic 的前向兼容条目 | -| 33 | `isBinaryThinking` | 面向二值 thinking 提供商的开 / 关推理开关 | 提供商只暴露二值 thinking 开 / 关 | -| 34 | `supportsXHighThinking` | 为选定模型提供 `xhigh` 推理支持 | 提供商只想对部分模型启用 `xhigh` | -| 35 | `resolveDefaultThinkingLevel` | 为特定模型家族确定默认 `/think` 级别 | 提供商拥有某模型家族的默认 `/think` 策略 | -| 36 | `isModernModelRef` | 面向 live profile 过滤器和 smoke 选择的 modern model 匹配器 | 提供商拥有 live / smoke 首选模型匹配逻辑 | -| 37 | `prepareRuntimeAuth` | 在推理前立即将已配置凭据交换为实际运行时 token / key | 提供商需要 token 交换或短期请求凭据 | -| 38 | `resolveUsageAuth` | 为 `/usage` 及相关状态接口解析用量 / 计费凭据 | 提供商需要自定义的用量 / 配额 token 解析，或不同的用量凭据 | -| 39 | `fetchUsageSnapshot` | 在认证解析后抓取并规范化提供商专属用量 / 配额快照 | 提供商需要提供商专属的用量端点或负载解析器 | -| 40 | `createEmbeddingProvider` | 为 memory / 搜索构建提供商自有的 embedding adapter | memory embedding 行为应归属于提供商插件 | -| 41 | `buildReplayPolicy` | 返回一个控制提供商转录处理方式的 replay policy | 提供商需要自定义转录策略（例如去除 thinking block） | -| 42 | `sanitizeReplayHistory` | 在通用转录清理后重写 replay 历史 | 提供商需要超出共享压缩辅助工具之外的 replay 重写 | -| 43 | `validateReplayTurns` | 在嵌入式 runner 之前对 replay turn 做最终校验或重塑 | 提供商传输在通用净化后需要更严格的 turn 校验 | -| 44 | `onModelSelected` | 运行提供商自有的模型选中后副作用 | 当模型变为活动状态时，提供商需要遥测或自有状态处理 | +| # | Hook | What it does | When to use | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | 在生成 `models.json` 期间将提供商配置发布到 `models.providers` | 提供商拥有目录或 base URL 默认值 | +| 2 | `applyConfigDefaults` | 在配置实体化期间应用提供商自有的全局配置默认值 | 默认值依赖认证模式、环境或提供商模型族语义 | +| -- | _(内置模型查找)_ | OpenClaw 会先尝试正常的注册表 / 目录路径 | _(不是插件 hook)_ | +| 3 | `normalizeModelId` | 在查找前规范化旧版或预览版 model-id 别名 | 提供商在规范模型解析前拥有别名清理逻辑 | +| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商族的 `api` / `baseUrl` | 提供商拥有同一传输族中自定义 provider id 的传输清理逻辑 | +| 5 | `normalizeConfig` | 在运行时 / 提供商解析前规范化 `models.providers.` | 提供商需要将配置清理逻辑与插件放在一起；内置 Google 族辅助工具也会为受支持的 Google 配置条目提供后备兼容清理 | +| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式用量兼容改写 | 提供商需要基于端点驱动的原生流式用量元数据修复 | +| 7 | `resolveConfigApiKey` | 在运行时认证加载前为配置提供商解析 env-marker 认证 | 提供商拥有自有的 env-marker API 密钥解析；`amazon-bedrock` 在此处也有内置 AWS env-marker 解析器 | +| 8 | `resolveSyntheticAuth` | 在不持久化明文的情况下暴露本地 / 自托管或配置支持的认证 | 提供商可以使用 synthetic / 本地凭证标记运行 | +| 9 | `resolveExternalAuthProfiles` | 叠加提供商自有的外部认证配置文件；CLI / 应用自有凭证的默认 `persistence` 为 `runtime-only` | 提供商可复用外部认证凭证，而无需持久化复制后的刷新令牌 | +| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的 synthetic 配置文件占位符置于 env / 配置支持认证之后 | 提供商存储了不应具有优先级的 synthetic 占位配置文件 | +| 11 | `resolveDynamicModel` | 为尚未进入本地注册表的提供商自有模型 id 提供同步回退 | 提供商接受任意上游模型 id | +| 12 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 前需要网络元数据 | +| 13 | `normalizeResolvedModel` | 在嵌入式 runner 使用已解析模型前做最终改写 | 提供商需要传输改写，但仍使用 core 传输 | +| 14 | `contributeResolvedModelCompat` | 为位于另一兼容传输后的提供商模型贡献兼容标志 | 提供商能在不接管提供商本身的情况下，于代理传输中识别自己的模型 | +| 15 | `capabilities` | 供共享 core 逻辑使用的提供商自有 transcript / 工具元数据 | 提供商需要 transcript / 提供商族怪癖信息 | +| 16 | `normalizeToolSchemas` | 在嵌入式 runner 看到工具 schema 之前规范化它们 | 提供商需要传输族 schema 清理 | +| 17 | `inspectToolSchemas` | 在规范化后暴露提供商自有 schema 诊断信息 | 提供商希望给出关键字警告，而无需让 core 学习提供商专用规则 | +| 18 | `resolveReasoningOutputMode` | 选择原生还是带标签的推理输出契约 | 提供商需要使用带标签的推理 / 最终输出，而不是原生字段 | +| 19 | `prepareExtraParams` | 在通用流选项包装器之前执行请求参数规范化 | 提供商需要默认请求参数或提供商专用参数清理 | +| 20 | `createStreamFn` | 用自定义传输完全替换正常流路径 | 提供商需要自定义线协议，而不仅仅是包装器 | +| 21 | `wrapStreamFn` | 在应用完通用包装器后再包裹流函数 | 提供商需要请求头 / 请求体 / 模型兼容包装器，而不需要自定义传输 | +| 22 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | 提供商希望通用传输发送提供商原生轮次身份 | +| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | 提供商希望通用 WS 传输调整会话头或回退策略 | +| 24 | `formatApiKey` | 认证配置文件格式化器：已存储配置文件变为运行时 `apiKey` 字符串 | 提供商存储额外认证元数据，并需要自定义运行时令牌形状 | +| 25 | `refreshOAuth` | 为自定义刷新端点或刷新失败策略覆盖 OAuth 刷新逻辑 | 提供商不适配共享的 `pi-ai` 刷新器 | +| 26 | `buildAuthDoctorHint` | 在 OAuth 刷新失败时追加修复提示 | 提供商需要在刷新失败后给出提供商自有认证修复指引 | +| 27 | `matchesContextOverflowError` | 提供商自有的上下文窗口溢出错误匹配器 | 提供商有一些通用启发式无法捕捉的原始溢出错误 | +| 28 | `classifyFailoverReason` | 提供商自有的故障转移原因分类 | 提供商能将原始 API / 传输错误映射为限流 / 过载等 | +| 29 | `isCacheTtlEligible` | 代理 / 回传提供商的提示词缓存策略 | 提供商需要代理专用缓存 TTL 门控 | +| 30 | `buildMissingAuthMessage` | 替换通用缺失认证恢复消息 | 提供商需要提供商专用的缺失认证恢复提示 | +| 31 | `suppressBuiltInModel` | 过时上游模型抑制，并可选给出用户可见错误提示 | 提供商需要隐藏过时上游条目，或用提供商提示替代 | +| 32 | `augmentModelCatalog` | 在发现后追加 synthetic / 最终目录条目 | 提供商需要在 `models list` 和选择器中加入 synthetic 的前向兼容条目 | +| 33 | `isBinaryThinking` | 为 binary-thinking 提供商提供开 / 关式推理切换 | 提供商只暴露二元推理开 / 关 | +| 34 | `supportsXHighThinking` | 为部分模型提供 `xhigh` 推理支持 | 提供商希望仅在部分模型上启用 `xhigh` | +| 35 | `resolveDefaultThinkingLevel` | 为特定模型族解析默认 `/think` 级别 | 提供商拥有某个模型族的默认 `/think` 策略 | +| 36 | `isModernModelRef` | 用于实时配置文件过滤器和 smoke 选择的现代模型匹配器 | 提供商拥有 live / smoke 首选模型匹配逻辑 | +| 37 | `prepareRuntimeAuth` | 在推理前把已配置凭证交换成实际运行时令牌 / 密钥 | 提供商需要令牌交换或短期请求凭证 | +| 38 | `resolveUsageAuth` | 为 `/usage` 和相关状态 surface 解析用量 / 计费凭证 | 提供商需要自定义用量 / 配额令牌解析或不同的用量凭证 | +| 39 | `fetchUsageSnapshot` | 在认证解析后抓取并规范化提供商专用的用量 / 配额快照 | 提供商需要提供商专用用量端点或负载解析器 | +| 40 | `createEmbeddingProvider` | 为 memory / search 构建提供商自有 embedding 适配器 | Memory embedding 行为应归属于提供商插件 | +| 41 | `buildReplayPolicy` | 返回一个控制 transcript 处理的 replay 策略 | 提供商需要自定义 transcript 策略（例如剥离 thinking 块） | +| 42 | `sanitizeReplayHistory` | 在通用 transcript 清理后重写 replay 历史 | 提供商需要在共享压缩辅助工具之外执行提供商专用 replay 改写 | +| 43 | `validateReplayTurns` | 在嵌入式 runner 之前，对 replay 轮次做最终校验或重塑 | 提供商传输在通用净化后需要更严格的轮次校验 | +| 44 | `onModelSelected` | 运行提供商自有的选择后副作用 | 提供商在模型激活时需要遥测或提供商自有状态 | -`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配的提供商插件，然后回退到其他具备 hook 能力的提供商插件，直到其中一个真正修改 model id 或 transport / config 为止。这样可使别名 / 兼容提供商 shim 继续工作，而无需调用方知道哪个内置插件拥有该重写。如果没有提供商 hook 重写受支持的 Google 家族配置项，则内置 Google 配置规范化器仍会执行该兼容性清理。 +`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查 +匹配到的提供商插件，然后再回退到其他具备 hook 能力的提供商插件， +直到其中某一个确实改变 model id 或 transport / config。这样无需让调用方知道哪个内置插件拥有该改写，也能让 +别名 / 兼容提供商 shim 正常工作。如果没有任何提供商 hook +改写受支持的 Google 族配置条目，内置 Google 配置规范化器仍会应用该兼容清理。 -如果提供商需要完全自定义的线路协议或自定义请求执行器，那就是另一类扩展。这些 hooks 面向的是仍运行在 OpenClaw 正常推理循环上的提供商行为。 +如果提供商需要完全自定义的线协议或自定义请求执行器， +那是另一类扩展。这些 hooks 适用于仍运行在 OpenClaw 正常推理循环上的提供商行为。 ### 提供商示例 @@ -630,101 +736,108 @@ api.registerProvider({ `resolveUsageAuth`、`fetchUsageSnapshot`、`isCacheTtlEligible`、 `resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef` 和 `wrapStreamFn`，因为它拥有 Claude 4.6 前向兼容、 - 提供商家族提示、认证修复指导、用量端点集成、 - 提示词缓存资格、认证感知配置默认值、Claude - 默认 / 自适应 thinking 策略，以及 Anthropic 专属的流整形能力，用于 beta headers、`/fast` / `serviceTier` 和 `context1m`。 -- Anthropic 的 Claude 专属流辅助工具目前保留在内置插件自己的公开 `api.ts` / `contract-api.ts` 接缝中。该包接口 + 提供商族提示、认证修复指引、用量端点集成、 + prompt cache 适用性、具备认证感知的配置默认值、Claude + 默认 / 自适应 thinking 策略，以及 Anthropic 专用的流整形，用于 + beta headers、`/fast` / `serviceTier` 和 `context1m`。 +- Anthropic 的 Claude 专用流辅助工具目前保留在内置插件自有的 + 公共 `api.ts` / `contract-api.ts` 接缝中。该包 surface 导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 `resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 - Anthropic 包装器构建器，而不是仅为某一个提供商的 beta header 规则去扩展通用 SDK。 + Anthropic 包装器构建器，而不是为了某个提供商的 beta-header 规则扩展通用 SDK。 - OpenAI 使用 `resolveDynamicModel`、`normalizeResolvedModel` 和 `capabilities`，以及 `buildMissingAuthMessage`、`suppressBuiltInModel`、 `augmentModelCatalog`、`supportsXHighThinking` 和 `isModernModelRef`， 因为它拥有 GPT-5.4 前向兼容、直接 OpenAI - `openai-completions` -> `openai-responses` 规范化、面向 Codex 的认证 + `openai-completions` -> `openai-responses` 规范化、具备 Codex 感知的认证 提示、Spark 抑制、synthetic OpenAI 列表条目，以及 GPT-5 的 thinking / - live model 策略；`openai-responses-defaults` 流家族拥有共享的原生 OpenAI Responses 包装器，用于 attribution headers、 - `/fast`/`serviceTier`、文本详细度、本地 Codex Web 搜索、 - reasoning 兼容负载整形以及 Responses 上下文管理。 -- OpenRouter 使用 `catalog`，以及 `resolveDynamicModel` 和 - `prepareDynamicModel`，因为该提供商是透传型的，可能在 OpenClaw 的静态目录更新前就暴露新的 - model id；它还使用 - `capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，以便将 - 提供商专属请求头、路由元数据、reasoning 补丁和 - 提示词缓存策略留在 core 外部。它的 replay policy 来自 + live-model 策略；`openai-responses-defaults` 流家族拥有共享的原生 OpenAI Responses 包装器，用于 attribution headers、 + `/fast`/`serviceTier`、文本冗长度、原生 Codex Web 搜索、 + reasoning-compat 负载整形和 Responses 上下文管理。 +- OpenRouter 使用 `catalog` 以及 `resolveDynamicModel` 和 + `prepareDynamicModel`，因为该提供商是透传的，可能在 + OpenClaw 的静态目录更新之前暴露新的模型 id；它还使用 + `capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，以使 + 提供商专用请求头、路由元数据、推理补丁和 + prompt cache 策略不进入 core。它的 replay 策略来自 `passthrough-gemini` 家族，而 `openrouter-thinking` 流家族 - 负责代理 reasoning 注入以及不支持模型 / `auto` 的跳过逻辑。 + 拥有代理推理注入和对不支持模型 / `auto` 的跳过逻辑。 - GitHub Copilot 使用 `catalog`、`auth`、`resolveDynamicModel` 和 - `capabilities`，以及 `prepareRuntimeAuth` 和 `fetchUsageSnapshot`，因为它 - 需要提供商自有的设备登录、模型回退行为、Claude 转录特性、 - GitHub token -> Copilot token 交换以及提供商自有的用量端点。 + `capabilities`，以及 `prepareRuntimeAuth` 和 `fetchUsageSnapshot`， + 因为它需要提供商自有的设备登录、模型回退行为、Claude transcript 怪癖、GitHub token -> Copilot token 交换， + 以及提供商自有的用量端点。 - OpenAI Codex 使用 `catalog`、`resolveDynamicModel`、 `normalizeResolvedModel`、`refreshOAuth` 和 `augmentModelCatalog`，以及 - `prepareExtraParams`、`resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它 - 仍运行在 core OpenAI 传输之上，但拥有自己的传输 / base URL + `prepareExtraParams`、`resolveUsageAuth` 和 `fetchUsageSnapshot`， + 因为它仍运行在 core 的 OpenAI 传输上，但拥有自己的 transport / base URL 规范化、OAuth 刷新回退策略、默认传输选择、 - synthetic Codex 目录条目以及 ChatGPT 用量端点集成；它与直接 OpenAI 共用相同的 `openai-responses-defaults` 流家族。 + synthetic Codex 目录条目和 ChatGPT 用量端点集成；它 + 与直接 OpenAI 共用同一个 `openai-responses-defaults` 流家族。 - Google AI Studio 和 Gemini CLI OAuth 使用 `resolveDynamicModel`、 `buildReplayPolicy`、`sanitizeReplayHistory`、 `resolveReasoningOutputMode`、`wrapStreamFn` 和 `isModernModelRef`，因为 `google-gemini` replay 家族拥有 Gemini 3.1 前向兼容回退、 原生 Gemini replay 校验、bootstrap replay 净化、带标签的 - reasoning 输出模式以及 modern model 匹配逻辑，而 + 推理输出模式和现代模型匹配，而 `google-thinking` 流家族拥有 Gemini thinking 负载规范化； Gemini CLI OAuth 还使用 `formatApiKey`、`resolveUsageAuth` 和 - `fetchUsageSnapshot` 来处理 token 格式化、token 解析和配额端点接线。 + `fetchUsageSnapshot` 来处理令牌格式化、令牌解析和配额端点接线。 - Anthropic Vertex 通过 `anthropic-by-model` replay 家族使用 `buildReplayPolicy`， - 这样 Claude 专属 replay 清理就能仅作用于 Claude id，而不是所有 `anthropic-messages` 传输。 + 以便 Claude 专用 replay 清理只作用于 Claude id， + 而不是作用于所有 `anthropic-messages` 传输。 - Amazon Bedrock 使用 `buildReplayPolicy`、`matchesContextOverflowError`、 `classifyFailoverReason` 和 `resolveDefaultThinkingLevel`，因为它拥有 - Bedrock 专属的 throttle / not-ready / context-overflow 错误分类能力， - 适用于 Anthropic-on-Bedrock 流量；其 replay policy 仍共享相同的 - 仅限 Claude 的 `anthropic-by-model` 保护。 -- OpenRouter、Kilocode、Opencode 和 Opencode Go 通过 `passthrough-gemini` replay 家族使用 `buildReplayPolicy`，因为它们通过 OpenAI 兼容传输代理 Gemini - 模型，需要进行 Gemini thought-signature 净化，但不需要原生 Gemini replay 校验或 - bootstrap 重写。 + 适用于 Anthropic-on-Bedrock 流量的 Bedrock 专用限流 / 未就绪 / 上下文溢出错误分类；其 replay 策略仍共享同样的 + 仅 Claude 的 `anthropic-by-model` 守卫。 +- OpenRouter、Kilocode、Opencode 和 Opencode Go 通过 `buildReplayPolicy` + 使用 `passthrough-gemini` replay 家族，因为它们通过 OpenAI + 兼容传输代理 Gemini 模型，并且需要 Gemini + thought-signature 净化，而不需要原生 Gemini replay 校验或 + bootstrap 改写。 - MiniMax 通过 - `hybrid-anthropic-openai` replay 家族使用 `buildReplayPolicy`，因为同一个提供商同时拥有 - Anthropic message 和 OpenAI 兼容语义；它会在 Anthropic 一侧保留仅限 Claude 的 - thinking block 丢弃逻辑，同时将 reasoning - 输出模式覆盖回原生，而 `minimax-fast-mode` 流家族则拥有共享流路径上的 - fast mode 模型重写能力。 -- Moonshot 使用 `catalog` 和 `wrapStreamFn`，因为它仍使用共享的 - OpenAI 传输，但需要提供商自有的 thinking 负载规范化；`moonshot-thinking` 流家族将配置和 `/think` 状态映射到其原生二值 thinking 负载。 + `hybrid-anthropic-openai` replay 家族使用 `buildReplayPolicy`， + 因为同一个提供商同时拥有 Anthropic-message 和 OpenAI 兼容语义；它在 + Anthropic 侧保留仅 Claude 的 thinking 块丢弃，同时将推理 + 输出模式重写回原生，而 `minimax-fast-mode` 流家族则在共享流路径上拥有 + fast-mode 模型改写。 +- Moonshot 使用 `catalog` 以及 `wrapStreamFn`，因为它仍使用共享 + OpenAI 传输，但需要提供商自有的 thinking 负载规范化；`moonshot-thinking` 流家族会将配置以及 `/think` 状态映射到其 + 原生二元 thinking 负载。 - Kilocode 使用 `catalog`、`capabilities`、`wrapStreamFn` 和 - `isCacheTtlEligible`，因为它需要提供商自有请求头、 - reasoning 负载规范化、Gemini 转录提示以及 Anthropic - cache TTL 门控；`kilocode-thinking` 流家族负责在共享代理流路径中保留 Kilo thinking - 注入，同时跳过 `kilo/auto` 和其他不支持显式 reasoning 负载的代理模型 id。 + `isCacheTtlEligible`，因为它需要提供商自有的请求头、 + 推理负载规范化、Gemini transcript 提示，以及 Anthropic + cache-TTL 门控；`kilocode-thinking` 流家族会在共享代理流路径上保持 Kilo + thinking 注入，同时跳过 `kilo/auto` 和其他不支持显式推理负载的代理模型 id。 - Z.AI 使用 `resolveDynamicModel`、`prepareExtraParams`、`wrapStreamFn`、 `isCacheTtlEligible`、`isBinaryThinking`、`isModernModelRef`、 `resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它拥有 GLM-5 回退、 - `tool_stream` 默认值、二值 thinking UX、modern model 匹配，以及 - 用量认证 + 配额抓取；`tool-stream-default-on` 流家族将默认开启的 - `tool_stream` 包装器从各提供商手写胶水代码中抽离出来。 + `tool_stream` 默认值、二元 thinking UX、现代模型匹配， + 以及用量认证和配额抓取；`tool-stream-default-on` 流家族将默认开启的 + `tool_stream` 包装器从各提供商的手写胶水层中抽离出来。 - xAI 使用 `normalizeResolvedModel`、`normalizeTransport`、 `contributeResolvedModelCompat`、`prepareExtraParams`、`wrapStreamFn`、 `resolveSyntheticAuth`、`resolveDynamicModel` 和 `isModernModelRef`， - 因为它拥有原生 xAI Responses 传输规范化、Grok fast mode - 别名重写、默认 `tool_stream`、strict tool / reasoning payload + 因为它拥有原生 xAI Responses 传输规范化、Grok fast-mode + 别名改写、默认 `tool_stream`、strict-tool / reasoning-payload 清理、插件自有工具的回退认证复用、前向兼容 Grok - 模型解析，以及提供商自有的兼容性补丁，例如 xAI tool schema - profile、不受支持的 schema 关键字、原生 `web_search`，以及 HTML entity - 工具调用参数解码。 -- Mistral、OpenCode Zen 和 OpenCode Go 仅使用 `capabilities`，以将 - 转录 / 工具特性留在 core 外部。 -- 仅目录型内置提供商，例如 `byteplus`、`cloudflare-ai-gateway`、 + 模型解析，以及 xAI 工具 schema profile、不支持的 schema 关键字、原生 `web_search` 和 HTML entity + 工具调用参数解码等提供商自有兼容补丁。 +- Mistral、OpenCode Zen 和 OpenCode Go 仅使用 `capabilities`，以让 + transcript / 工具怪癖逻辑不进入 core。 +- 仅目录型内置提供商，如 `byteplus`、`cloudflare-ai-gateway`、 `huggingface`、`kimi-coding`、`nvidia`、`qianfan`、 - `synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine`，仅使用 - `catalog`。 -- Qwen 将 `catalog` 用于其文本提供商，同时为其多模态接口注册共享的媒体理解和视频生成能力。 -- MiniMax 和 Xiaomi 使用 `catalog` 加上 usage hooks，因为它们的 `/usage` - 行为属于插件自有，即使推理仍通过共享传输运行。 + `synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine` + 仅使用 `catalog`。 +- Qwen 为其文本提供商使用 `catalog`，并为其多模态 surface + 使用共享的媒体理解和视频生成注册。 +- MiniMax 和 Xiaomi 使用 `catalog` 加上 usage hooks， + 因为尽管推理仍通过共享传输运行，但它们的 `/usage` + 行为归插件所有。 ## 运行时辅助工具 -插件可以通过 `api.runtime` 访问部分选定的 core 辅助工具。以 TTS 为例： +插件可以通过 `api.runtime` 访问部分 core 辅助工具。对于 TTS： ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -745,14 +858,14 @@ const voices = await api.runtime.tts.listVoices({ 说明： -- `textToSpeech` 返回常规 core TTS 输出负载，适用于文件 / 语音便笺接口。 -- 使用 core `messages.tts` 配置和提供商选择。 -- 返回 PCM 音频 buffer + sample rate。插件必须自行进行重采样 / 编码以适配提供商。 -- `listVoices` 对每个提供商来说是可选的。可将其用于厂商自有的语音选择器或设置流程。 -- 语音列表可以包含更丰富的元数据，例如语言区域、性别和个性标签，以支持提供商感知的选择器。 -- 当前 OpenAI 和 ElevenLabs 支持电话场景。Microsoft 不支持。 +- `textToSpeech` 返回适用于文件 / 语音便笺 surface 的普通 core TTS 输出负载。 +- 使用 core 的 `messages.tts` 配置和提供商选择逻辑。 +- 返回 PCM 音频缓冲区 + 采样率。插件必须为提供商自行重采样 / 编码。 +- `listVoices` 对每个提供商来说是可选的。可将它用于提供商自有语音选择器或设置流程。 +- 语音列表可包含更丰富的元数据，例如 locale、gender 和 personality tags，以便用于感知提供商的选择器。 +- OpenAI 和 ElevenLabs 目前支持电话语音。Microsoft 不支持。 -插件也可以通过 `api.registerSpeechProvider(...)` 注册语音提供商。 +插件也可以通过 `api.registerSpeechProvider(...)` 注册 speech providers。 ```ts api.registerSpeechProvider({ @@ -772,14 +885,14 @@ api.registerSpeechProvider({ 说明： -- 将 TTS 策略、回退和回复投递保留在 core 中。 -- 对厂商自有合成行为使用语音提供商。 -- 旧版 Microsoft `edge` 输入会被规范化为 `microsoft` provider id。 -- 推荐的归属模型是面向公司的：随着 OpenClaw 增加这些 - 能力契约，一个厂商插件可以同时拥有文本、语音、图像和未来媒体提供商。 +- 将 TTS 策略、回退和回复传递保留在 core 中。 +- 使用 speech providers 来承载提供商自有合成行为。 +- 旧版 Microsoft `edge` 输入会被规范化到 `microsoft` provider id。 +- 首选归属模型是面向公司的：随着 OpenClaw 添加这些 + 能力契约，一个提供商插件可以拥有文本、语音、图像和未来媒体提供商。 -对于图像 / 音频 / 视频理解，插件会注册一个类型化的 -媒体理解提供商，而不是通用 key/value 包： +对于图像 / 音频 / 视频理解，插件应注册一个类型化的 +媒体理解提供商，而不是通用键值包： ```ts api.registerMediaUnderstandingProvider({ @@ -794,11 +907,12 @@ api.registerMediaUnderstandingProvider({ 说明： - 将编排、回退、配置和渠道接线保留在 core 中。 -- 将厂商行为保留在提供商插件中。 -- 增量扩展应保持类型化：新的可选方法、新的可选结果字段、新的可选能力。 -- 视频生成已经遵循相同模式： +- 将提供商行为保留在提供商插件中。 +- 增量扩展应保持类型化：新的可选方法、新的可选 + 结果字段、新的可选能力。 +- 视频生成也已经遵循相同模式： - core 拥有能力契约和运行时辅助工具 - - 厂商插件注册 `api.registerVideoGenerationProvider(...)` + - 提供商插件注册 `api.registerVideoGenerationProvider(...)` - 功能 / 渠道插件消费 `api.runtime.videoGeneration.*` 对于媒体理解运行时辅助工具，插件可以调用： @@ -816,7 +930,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -对于音频转写，插件可以使用媒体理解运行时或较旧的 STT 别名： +对于音频转录，插件可以使用媒体理解运行时， +也可以使用旧版 STT 别名： ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -829,9 +944,9 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ 说明： -- `api.runtime.mediaUnderstanding.*` 是图像 / 音频 / 视频理解的首选共享接口。 -- 使用 core 媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。 -- 当没有产生转写输出时，返回 `{ text: undefined }`（例如输入被跳过 / 不受支持）。 +- `api.runtime.mediaUnderstanding.*` 是图像 / 音频 / 视频理解的首选共享 surface。 +- 使用 core 的媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。 +- 当未产生转录输出时返回 `{ text: undefined }`（例如输入被跳过 / 不受支持）。 - `api.runtime.stt.transcribeAudioFile(...)` 仍保留为兼容性别名。 插件还可以通过 `api.runtime.subagent` 启动后台子智能体运行： @@ -848,14 +963,14 @@ const result = await api.runtime.subagent.run({ 说明： -- `provider` 和 `model` 是按次运行覆盖项，不会持久改变会话设置。 -- OpenClaw 仅对受信任调用方接受这些覆盖字段。 -- 对于插件自有回退运行，运维者必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式启用。 -- 使用 `plugins.entries..subagent.allowedModels` 将受信任插件限制到特定规范 `provider/model` 目标，或设置为 `"*"` 以显式允许任意目标。 -- 不受信任的插件子智能体运行仍可工作，但覆盖请求会被拒绝，而不是静默回退。 +- `provider` 和 `model` 是每次运行的可选覆盖项，不会持久化为 session 变更。 +- OpenClaw 仅对可信调用者接受这些覆盖字段。 +- 对于插件自有回退运行，运维人员必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式启用。 +- 使用 `plugins.entries..subagent.allowedModels` 可将可信插件限制为特定的规范化 `provider/model` 目标，或使用 `"*"` 来显式允许任意目标。 +- 不可信插件的子智能体运行仍可工作，但覆盖请求会被拒绝，而不是静默回退。 对于 Web 搜索，插件可以消费共享运行时辅助工具，而不是 -深入智能体工具接线： +深入智能体工具接线层： ```ts const providers = api.runtime.webSearch.listProviders({ @@ -876,9 +991,9 @@ const result = await api.runtime.webSearch.search({ 说明： -- 将提供商选择、凭据解析和共享请求语义保留在 core 中。 -- 对厂商专属搜索传输使用 Web 搜索提供商。 -- `api.runtime.webSearch.*` 是功能 / 渠道插件需要搜索行为但不依赖智能体工具包装器时的首选共享接口。 +- 将提供商选择、凭证解析和共享请求语义保留在 core 中。 +- 使用 Web 搜索提供商来承载提供商专用搜索传输。 +- `api.runtime.webSearch.*` 是功能 / 渠道插件在不依赖智能体工具包装器的情况下需要搜索行为时的首选共享 surface。 ### `api.runtime.imageGeneration` @@ -894,11 +1009,11 @@ const providers = api.runtime.imageGeneration.listProviders({ ``` - `generate(...)`：使用已配置的图像生成提供商链生成图像。 -- `listProviders(...)`：列出可用图像生成提供商及其能力。 +- `listProviders(...)`：列出可用的图像生成提供商及其能力。 ## Gateway 网关 HTTP 路由 -插件可以使用 `api.registerHttpRoute(...)` 暴露 HTTP 端点。 +插件可以通过 `api.registerHttpRoute(...)` 暴露 HTTP 端点。 ```ts api.registerHttpRoute({ @@ -916,27 +1031,28 @@ api.registerHttpRoute({ 路由字段： - `path`：Gateway 网关 HTTP 服务器下的路由路径。 -- `auth`：必填。使用 `"gateway"` 以要求普通 Gateway 网关认证，或使用 `"plugin"` 以进行插件自主管理的认证 / webhook 校验。 +- `auth`：必填。使用 `"gateway"` 以要求普通 Gateway 网关认证，或使用 `"plugin"` 以要求插件管理的认证 / webhook 校验。 - `match`：可选。`"exact"`（默认）或 `"prefix"`。 -- `replaceExisting`：可选。允许同一个插件替换它自己现有的路由注册。 +- `replaceExisting`：可选。允许同一插件替换其现有路由注册。 - `handler`：当路由处理了请求时返回 `true`。 说明： -- `api.registerHttpHandler(...)` 已被移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。 +- `api.registerHttpHandler(...)` 已移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。 - 插件路由必须显式声明 `auth`。 -- 除非 `replaceExisting: true`，否则精确 `path + match` 冲突会被拒绝，并且一个插件不能替换另一个插件的路由。 -- 不同 `auth` 级别的重叠路由会被拒绝。请仅在相同 auth 级别内保留 `exact` / `prefix` 的贯通链。 -- `auth: "plugin"` 路由**不会**自动获得运维者运行时作用域。它们用于插件自主管理的 webhook / 签名校验，而不是特权 Gateway 网关辅助调用。 -- `auth: "gateway"` 路由运行在 Gateway 网关请求运行时作用域内，但该作用域被有意设计得较为保守： - - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会让插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` - - 受信任的、带身份的 HTTP 模式（例如 `trusted-proxy` 或私有入口上的 `gateway.auth.mode = "none"`）仅在显式存在该 header 时才会尊重 `x-openclaw-scopes` - - 如果这些带身份的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退到 `operator.write` -- 实用规则：不要假设一个经过 gateway 认证的插件路由天然就是管理员接口。如果你的路由需要仅管理员行为，请要求使用带身份的认证模式，并记录清楚显式 `x-openclaw-scopes` header 契约。 +- 除非设置 `replaceExisting: true`，否则精确的 `path + match` 冲突会被拒绝，而且一个插件不能替换另一个插件的路由。 +- 不同 `auth` 级别的重叠路由会被拒绝。请仅在相同认证级别下保留 `exact` / `prefix` 的透传链。 +- `auth: "plugin"` 路由**不会**自动接收运维人员运行时作用域。它们用于插件自管的 webhook / 签名校验，而不是特权 Gateway 网关辅助调用。 +- `auth: "gateway"` 路由运行在 Gateway 网关请求运行时作用域中，但该作用域有意保持保守： + - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` + - 受信任的带身份 HTTP 模式（例如 `trusted-proxy` 或私有入口上的 `gateway.auth.mode = "none"`）仅在显式存在该头时才会遵守 `x-openclaw-scopes` + - 如果这些带身份的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退为 `operator.write` +- 实用规则：不要假设 gateway-auth 插件路由天然就是隐式管理员 surface。如果你的路由需要仅管理员行为，请要求使用带身份的认证模式，并记录清楚显式 `x-openclaw-scopes` 头契约。 ## 插件 SDK 导入路径 -在编写插件时，请使用 SDK 子路径，而不是单体式的 `openclaw/plugin-sdk` 导入： +在编写插件时，请使用 SDK 子路径，而不是整体式的 +`openclaw/plugin-sdk` 导入： - `openclaw/plugin-sdk/plugin-entry` 用于插件注册原语。 - `openclaw/plugin-sdk/core` 用于通用共享的面向插件契约。 @@ -954,17 +1070,17 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-reply-pipeline`、 `openclaw/plugin-sdk/command-auth`、 `openclaw/plugin-sdk/secret-input` 和 - `openclaw/plugin-sdk/webhook-ingress`，用于共享设置 / 认证 / 回复 / webhook - 接线。`channel-inbound` 是 debounce、提及匹配、 - envelope 格式化以及入站 envelope 上下文辅助工具的共享归属位置。 - `channel-setup` 是精简的可选安装设置接缝。 + `openclaw/plugin-sdk/webhook-ingress`，用于共享 setup / auth / reply / webhook + 接线。`channel-inbound` 是 debounce、mention 匹配、 + envelope 格式化和入站 envelope 上下文辅助工具的共享归属地。 + `channel-setup` 是狭窄的可选安装 setup 接缝。 `setup-runtime` 是 `setupEntry` / - 延迟启动所使用的运行时安全设置接口，包括导入安全的设置 patch adapters。 - `setup-adapter-runtime` 是感知环境的账户设置 adapter 接缝。 + 延迟启动使用的运行时安全 setup surface，包括导入安全的 setup patch adapters。 + `setup-adapter-runtime` 是具备环境感知的账户 setup adapter 接缝。 `setup-tools` 是小型 CLI / archive / docs 辅助工具接缝（`formatCliCommand`、 `detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、 `CONFIG_DIR`）。 -- 领域子路径，例如 `openclaw/plugin-sdk/channel-config-helpers`、 +- 领域子路径，如 `openclaw/plugin-sdk/channel-config-helpers`、 `openclaw/plugin-sdk/allow-from`、 `openclaw/plugin-sdk/channel-config-schema`、 `openclaw/plugin-sdk/telegram-command-config`、 @@ -981,66 +1097,68 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/runtime-store` 和 `openclaw/plugin-sdk/directory-runtime`，用于共享运行时 / 配置辅助工具。 `telegram-command-config` 是 Telegram 自定义 - 命令规范化 / 校验的精简公开接缝，即使内置 - Telegram 契约接口暂时不可用，它也保持可用。 - `text-runtime` 是共享的文本 / Markdown / 日志接缝，包括 - 面向 assistant 可见文本剥离、Markdown 渲染 / 分块辅助工具、脱敏 - 辅助工具、directive tag 辅助工具以及 safe-text 实用工具。 -- 审批专用的渠道接缝应优先使用插件上的单一 `approvalCapability` - 契约。然后 core 通过这一项能力读取审批认证、投递、渲染和 - 原生路由行为，而不是将审批行为混入无关的插件字段。 -- `openclaw/plugin-sdk/channel-runtime` 已弃用，仅作为 - 旧版插件的兼容性 shim 保留。新代码应导入更窄的通用原语，而仓库代码不应新增对该 shim 的导入。 -- 内置扩展内部实现仍然是私有的。外部插件应仅使用 - `openclaw/plugin-sdk/*` 子路径。OpenClaw core / 测试代码可以使用 - 某个插件包根目录下的仓库公开入口点，例如 `index.js`、`api.js`、 - `runtime-api.js`、`setup-entry.js` 以及更精细的文件，例如 - `login-qr-api.js`。绝不要从 core 或另一个扩展中导入某个插件包的 `src/*`。 + 命令规范化 / 校验的狭窄公共接缝，即使内置 + Telegram 契约 surface 暂时不可用，它也仍可用。 + `text-runtime` 是共享的 text / markdown / logging 接缝，包括 + 面向 assistant 可见文本剥离、markdown 渲染 / 分块辅助工具、脱敏 + 辅助工具、directive-tag 辅助工具和安全文本实用工具。 +- 审批专用的渠道接缝应优先在插件上使用一个 `approvalCapability` + 契约。然后 core 会通过该单一能力来读取审批认证、传递、渲染和 + 原生路由行为，而不是将审批行为混入不相关的插件字段。 +- `openclaw/plugin-sdk/channel-runtime` 已弃用，目前仅作为 + 旧插件的兼容 shim 保留。新代码应导入更狭窄的通用原语， + 仓库代码也不应新增对该 shim 的导入。 +- 内置扩展内部机制仍保持私有。外部插件应仅使用 + `openclaw/plugin-sdk/*` 子路径。OpenClaw core / test 代码可使用 + 插件包根目录下的仓库公共入口点，例如 `index.js`、`api.js`、 + `runtime-api.js`、`setup-entry.js`，以及诸如 + `login-qr-api.js` 之类的狭窄作用域文件。绝不要从 core 或其他扩展中导入插件包的 `src/*`。 - 仓库入口点拆分： `/api.js` 是辅助工具 / 类型 barrel， `/runtime-api.js` 是仅运行时 barrel， `/index.js` 是内置插件入口， - `/setup-entry.js` 是设置插件入口。 + `/setup-entry.js` 是 setup 插件入口。 - 当前内置提供商示例： - - Anthropic 使用 `api.js` / `contract-api.js` 提供 Claude 流辅助工具，例如 - `wrapAnthropicProviderStream`、beta header 辅助工具以及 `service_tier` + - Anthropic 使用 `api.js` / `contract-api.js` 提供 Claude 流辅助工具， + 如 `wrapAnthropicProviderStream`、beta-header 辅助工具和 `service_tier` 解析。 - - OpenAI 使用 `api.js` 提供提供商构建器、默认模型辅助工具以及 - 实时提供商构建器。 - - OpenRouter 使用 `api.js` 提供其提供商构建器以及新手引导 / 配置 - 辅助工具，而 `register.runtime.js` 仍可为仓库内使用重新导出通用 + - OpenAI 使用 `api.js` 提供 provider builder、默认模型辅助工具和 + realtime provider builder。 + - OpenRouter 使用 `api.js` 提供其 provider builder 以及 onboarding / config + 辅助工具，而 `register.runtime.js` 仍可为仓库本地使用重新导出通用 `plugin-sdk/provider-stream` 辅助工具。 -- facade 加载的公开入口点会优先使用当前活动的运行时配置快照； - 当 OpenClaw 尚未提供运行时快照时，则回退到磁盘上的已解析配置文件。 -- 通用共享原语仍然是首选公开 SDK 契约。仍然存在一小部分保留的、兼容性用途的内置渠道品牌化辅助工具接缝。应将它们视为内置维护 / 兼容性接缝，而不是新的第三方导入目标；新的跨渠道契约仍应落在通用 `plugin-sdk/*` 子路径或插件本地 `api.js` / +- 由 facade 加载的公共入口点会优先选择活动运行时配置快照； + 如果 OpenClaw 尚未提供运行时快照，则回退到磁盘上的已解析配置文件。 +- 通用共享原语仍是首选公共 SDK 契约。仍然存在一小组保留的、 + 兼容性用的内置渠道品牌辅助工具接缝。请将这些视为内置维护 / + 兼容性接缝，而不是新的第三方导入目标；新的跨渠道契约仍应落在通用 `plugin-sdk/*` 子路径或插件本地 `api.js` / `runtime-api.js` barrel 上。 兼容性说明： -- 新代码请避免使用根 `openclaw/plugin-sdk` barrel。 -- 优先使用精简稳定原语。更新的 setup / pairing / reply / +- 新代码应避免使用根 `openclaw/plugin-sdk` barrel。 +- 优先使用狭窄且稳定的原语。较新的 setup / pairing / reply / feedback / contract / inbound / threading / command / secret-input / webhook / infra / - allowlist / status / message-tool 子路径是新内置和外部插件工作的预期契约。 + allowlist / status / message-tool 子路径，是新的 + 内置和外部插件工作的预期契约。 目标解析 / 匹配应放在 `openclaw/plugin-sdk/channel-targets`。 - 消息操作门控和 reaction message id 辅助工具应放在 + Message action 门控和 reaction message-id 辅助工具应放在 `openclaw/plugin-sdk/channel-actions`。 -- 默认情况下，内置扩展专用辅助工具 barrel 并不稳定。如果某个 - 辅助工具只被某个内置扩展需要，请将它保留在扩展本地 - `api.js` 或 `runtime-api.js` 接缝后面，而不是提升为 - `openclaw/plugin-sdk/`。 -- 新的共享辅助工具接缝应当是通用的，而不是带渠道品牌的。共享目标 - 解析应归于 `openclaw/plugin-sdk/channel-targets`；渠道专属 - 内部实现则应保留在所属插件的本地 `api.js` 或 `runtime-api.js` - 接缝之后。 +- 内置扩展专用辅助工具 barrel 默认不稳定。如果某个 + 辅助工具只被内置扩展需要，请将其保留在该扩展本地的 + `api.js` 或 `runtime-api.js` 接缝后面，而不是将其提升到 + `openclaw/plugin-sdk/` 中。 +- 新的共享辅助工具接缝应当是通用的，而不是渠道品牌化的。共享目标 + 解析属于 `openclaw/plugin-sdk/channel-targets`；渠道专用 + 内部机制应保留在对应插件本地的 `api.js` 或 `runtime-api.js` + 接缝后面。 - 像 `image-generation`、 - `media-understanding` 和 `speech` 这样的能力专用子路径之所以存在，是因为 - 当前内置 / 原生插件正在使用它们。但这并不自动意味着其中每个导出辅助工具 - 都是长期冻结的外部契约。 + `media-understanding` 和 `speech` 这样的能力专用子路径之所以存在，是因为内置 / 原生插件今天就在使用它们。它们的存在本身并不意味着每个导出的辅助工具都是长期冻结的外部契约。 -## 消息工具 schema +## Message 工具 schema -插件应拥有渠道专属的 `describeMessageTool(...)` schema -扩展。请将提供商专属字段保留在插件中，而不要放入共享 core。 +插件应拥有渠道专用的 `describeMessageTool(...)` schema +贡献。请将提供商专用字段保留在插件中，而不要放入共享 core。 对于共享的可移植 schema 片段，请复用通过 `openclaw/plugin-sdk/channel-actions` 导出的通用辅助工具： @@ -1048,107 +1166,113 @@ api.registerHttpRoute({ - `createMessageToolButtonsSchema()` 用于按钮网格式负载 - `createMessageToolCardSchema()` 用于结构化卡片负载 -如果某个 schema 形状只对一个提供商有意义，请在该插件自己的 -源码中定义它，而不要将其提升到共享 SDK 中。 +如果某个 schema 形状只对某一个提供商有意义， +请将它定义在该插件自己的源码中，而不要提升到共享 SDK。 ## 渠道目标解析 -渠道插件应拥有渠道专属的目标语义。请保持共享 -outbound host 的通用性，并使用消息 adapter 接口处理提供商规则： +渠道插件应拥有渠道专用的目标语义。保持共享出站宿主的通用性， +并使用消息适配器 surface 来处理提供商规则： -- `messaging.inferTargetChatType({ to })` 决定规范化目标在目录查找前 +- `messaging.inferTargetChatType({ to })` 决定标准化目标在目录查找前 应被视为 `direct`、`group` 还是 `channel`。 -- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉 core 某个 - 输入是否应直接跳到类 id 解析，而不是目录搜索。 -- `messaging.targetResolver.resolveTarget(...)` 是在规范化之后或目录未命中后， - core 需要最终提供商自有解析时的插件回退。 -- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后拥有 - 提供商专属的会话路由构建逻辑。 +- `messaging.targetResolver.looksLikeId(raw, normalized)` 告知 core + 某个输入是否应直接跳到类 id 解析，而不是进行目录搜索。 +- `messaging.targetResolver.resolveTarget(...)` 是插件的回退逻辑， + 当 core 在规范化后或目录未命中后需要做最终的提供商自有解析时使用。 +- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后， + 拥有提供商专用的 session 路由构建逻辑。 -推荐拆分方式： +推荐拆分如下： -- 使用 `inferTargetChatType` 处理应在搜索 peers / groups 之前发生的类别决策。 -- 使用 `looksLikeId` 处理“将其视为显式 / 原生 target id”的检查。 -- 使用 `resolveTarget` 处理提供商专属的规范化回退，而不是广泛的目录搜索。 -- 将提供商原生 id（例如 chat id、thread id、JID、handle 和 room id）保留在 `target` 值或提供商专属参数中，而不要放进通用 SDK 字段。 +- 对于应在搜索 peers / groups 之前完成的类别判定，使用 `inferTargetChatType`。 +- 对于“将其视为显式 / 原生目标 id”这类判断，使用 `looksLikeId`。 +- 对于提供商专用的规范化回退，使用 `resolveTarget`， + 而不是把它用于宽泛的目录搜索。 +- 将 chat ids、thread ids、JIDs、handles 和 room ids 这类提供商原生 id + 保留在 `target` 值或提供商专用参数中，而不是放进通用 SDK 字段。 -## 配置驱动目录 +## 配置支持的目录 -对于从配置派生目录条目的插件，请将该逻辑保留在插件中，并复用 -`openclaw/plugin-sdk/directory-runtime` 中的共享辅助工具。 +那些从配置中派生目录条目的插件，应将这部分逻辑保留在插件中， +并复用 `openclaw/plugin-sdk/directory-runtime` +中的共享辅助工具。 -当某个渠道需要配置驱动的 peers / groups 时，请使用这种方式，例如： +当某个渠道需要由配置支持的 peers / groups 时，请使用这种方式，例如： - 由 allowlist 驱动的私信 peers - 已配置的渠道 / 群组映射 -- 账户作用域的静态目录回退 +- 按账户划分的静态目录回退 -`directory-runtime` 中的共享辅助工具仅处理通用操作： +`directory-runtime` 中的共享辅助工具只处理通用操作： - 查询过滤 - 限制应用 - 去重 / 规范化辅助工具 - 构建 `ChannelDirectoryEntry[]` -渠道专属的账户检查和 id 规范化应保留在插件实现中。 +渠道专用的账户检查和 id 规范化应保留在插件实现中。 ## 提供商目录 -提供商插件可以通过 -`registerProvider({ catalog: { run(...) { ... } } })` 定义用于推理的模型目录。 +提供商插件可以使用 +`registerProvider({ catalog: { run(...) { ... } } })` 为推理定义模型目录。 -`catalog.run(...)` 返回与 OpenClaw 写入 -`models.providers` 的相同结构： +`catalog.run(...)` 返回的形状与 OpenClaw 写入 +`models.providers` 的内容相同： -- `{ provider }` 表示一个 provider 条目 -- `{ providers }` 表示多个 provider 条目 +- `{ provider }` 表示一个提供商条目 +- `{ providers }` 表示多个提供商条目 -当插件拥有提供商专属 model id、base URL 默认值或受认证门控的模型元数据时，请使用 `catalog`。 +当插件拥有提供商专用模型 id、base URL 默认值， +或受认证门控的模型元数据时，请使用 `catalog`。 `catalog.order` 控制插件目录相对于 OpenClaw 内置隐式提供商的合并时机： -- `simple`：普通 API key 或环境变量驱动的提供商 -- `profile`：当存在 auth profiles 时出现的提供商 -- `paired`：会合成多个关联 provider 条目的提供商 +- `simple`：普通 API 密钥或环境驱动的提供商 +- `profile`：认证配置文件存在时出现的提供商 +- `paired`：合成多个相关提供商条目的提供商 - `late`：最后一轮，在其他隐式提供商之后 -后出现的提供商在 key 冲突时会获胜，因此插件可以有意用相同 provider id 覆盖内置 provider 条目。 +较晚的提供商在键冲突时获胜，因此插件可以有意用相同的 provider id +覆盖某个内置提供商条目。 兼容性： -- `discovery` 仍可用作旧版别名 +- `discovery` 仍可作为旧版别名使用 - 如果同时注册了 `catalog` 和 `discovery`，OpenClaw 会使用 `catalog` ## 只读渠道检查 -如果你的插件注册了一个渠道，建议同时实现 +如果你的插件注册了一个渠道，请优先同时实现 `plugin.config.inspectAccount(cfg, accountId)` 和 `resolveAccount(...)`。 原因： -- `resolveAccount(...)` 是运行时路径。它可以假设凭据 - 已完全实体化，并在缺失必要 secret 时快速失败。 -- 像 `openclaw status`、`openclaw status --all`、 - `openclaw channels status`、`openclaw channels resolve` 以及 doctor / config - 修复流程这样的只读命令路径，不应为了描述配置就去实体化运行时凭据。 +- `resolveAccount(...)` 是运行时路径。它可以假定凭证 + 已完全实体化，并且在必需密钥缺失时快速失败。 +- 只读命令路径，例如 `openclaw status`、`openclaw status --all`、 + `openclaw channels status`、`openclaw channels resolve`，以及 doctor / 配置 + 修复流程，不应仅为了描述配置就必须实体化运行时凭证。 推荐的 `inspectAccount(...)` 行为： -- 仅返回描述性的账户状态。 +- 只返回描述性的账户状态。 - 保留 `enabled` 和 `configured`。 -- 在相关时包含凭据来源 / 状态字段，例如： - - `tokenSource`, `tokenStatus` - - `botTokenSource`, `botTokenStatus` - - `appTokenSource`, `appTokenStatus` - - `signingSecretSource`, `signingSecretStatus` -- 你不需要返回原始 token 值来报告只读可用性。返回 - `tokenStatus: "available"`（以及匹配的 source 字段）就足够用于状态类命令。 -- 当凭据通过 SecretRef 配置，但在当前命令路径中不可用时，请使用 `configured_unavailable`。 +- 在相关时包含凭证来源 / 状态字段，例如： + - `tokenSource`、`tokenStatus` + - `botTokenSource`、`botTokenStatus` + - `appTokenSource`、`appTokenStatus` + - `signingSecretSource`、`signingSecretStatus` +- 你不需要仅为了报告只读可用性而返回原始令牌值。返回 + `tokenStatus: "available"`（以及匹配的来源字段）就足以支持 status 类命令。 +- 当凭证通过 SecretRef 配置，但在当前命令路径中不可用时，使用 `configured_unavailable`。 -这样只读命令就能报告“已配置，但在当前命令路径中不可用”，而不是崩溃或错误地将账户报告为未配置。 +这样只读命令就可以报告“已配置，但在该命令路径中不可用”， +而不会崩溃，也不会错误地将账户报告为未配置。 -## 包集合 +## Package packs 一个插件目录可以包含带有 `openclaw.extensions` 的 `package.json`： @@ -1162,56 +1286,56 @@ outbound host 的通用性，并使用消息 adapter 接口处理提供商规则 } ``` -每个条目都会变成一个插件。如果该 pack 列出多个扩展，则插件 id -会变为 `name/`。 +每个条目都会变成一个插件。如果该 pack 列出了多个扩展，则插件 id +会变成 `name/`。 -如果你的插件导入了 npm 依赖，请在该目录中安装它们，以确保 -`node_modules` 可用（`npm install` / `pnpm install`）。 +如果你的插件导入了 npm 依赖，请在该目录中安装它们， +以便 `node_modules` 可用（`npm install` / `pnpm install`）。 -安全护栏：每个 `openclaw.extensions` 条目在解析 symlink 后都必须仍位于插件 -目录内部。任何逃逸出包目录的条目都会被拒绝。 +安全护栏：每个 `openclaw.extensions` 条目在解析符号链接后都必须留在插件 +目录内。逃离包目录的条目会被拒绝。 -安全说明：`openclaw plugins install` 安装插件依赖时使用 -`npm install --omit=dev --ignore-scripts`（无生命周期脚本，运行时无 dev dependencies）。请保持插件依赖树为“纯 JS / TS”，并避免依赖需要 `postinstall` 构建的包。 +安全说明：`openclaw plugins install` 会使用 +`npm install --omit=dev --ignore-scripts` 安装插件依赖 +（无生命周期脚本，运行时也不安装 dev dependencies）。请保持插件依赖树为“纯 JS / TS”，并避免需要 `postinstall` 构建的包。 -可选：`openclaw.setupEntry` 可以指向一个轻量级、仅用于设置的模块。 -当 OpenClaw 需要为一个已禁用的渠道插件提供设置接口，或者 -当某个渠道插件已启用但尚未配置时，它会加载 `setupEntry`，而不是完整插件入口。这样在你的主插件入口同时接线工具、hooks 或其他仅运行时代码时， -可以让启动和设置更轻量。 +可选：`openclaw.setupEntry` 可指向一个轻量级的仅 setup 模块。 +当 OpenClaw 需要为已禁用的渠道插件提供 setup surface， +或者当渠道插件已启用但尚未配置时，它会加载 `setupEntry` +而不是完整插件入口。这样在你的主插件入口还会接线工具、hooks 或其他仅运行时代码时，可以让启动和 setup 更轻量。 可选：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -可以让渠道插件在 Gateway 网关监听前的启动阶段也使用相同的 `setupEntry` 路径， -即使该渠道已经配置完成。 +可让渠道插件在 Gateway 网关监听前的启动阶段中，即使该渠道已经配置完成，也使用同样的 `setupEntry` 路径。 -仅当 `setupEntry` 完整覆盖了 Gateway 网关开始监听前必须存在的启动接口时才应使用此选项。实践中，这意味着设置入口 +仅当 `setupEntry` 能完全覆盖 Gateway 网关开始监听前必须存在的启动 surface 时，才使用此选项。实际而言，这意味着 setup entry 必须注册启动所依赖的每一项渠道自有能力，例如： - 渠道注册本身 - 任何必须在 Gateway 网关开始监听前可用的 HTTP 路由 -- 任何在同一时间窗口内必须存在的 Gateway 网关方法、工具或服务 +- 任何在同一窗口内必须存在的 gateway 方法、工具或服务 -如果你的完整入口仍然拥有任何必需的启动能力，请不要启用 -此标志。应保持默认行为，让 OpenClaw 在启动期间加载完整入口。 +如果你的完整入口仍拥有任何所需启动能力，请不要启用此标志。 +保持插件使用默认行为，让 OpenClaw 在启动期间加载完整入口。 -内置渠道也可以发布仅设置用途的契约接口辅助工具，供 core 在完整 -渠道运行时加载前查询。当前设置提升接口包括： +内置渠道也可以发布仅 setup 的契约 surface 辅助工具，供 core +在完整渠道运行时加载前查询。当前 setup 提升 surface 为： - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -当 core 需要将旧版单账户渠道配置提升到 -`channels..accounts.*`，且无需加载完整插件入口时，就会使用该接口。 -Matrix 是当前的内置示例：当已存在命名账户时，它只会将 auth / bootstrap 键迁移到一个已命名的提升账户中，并且可以保留已配置的非规范 default account key，而不是总是创建 +当 core 需要在不加载完整插件入口的情况下，将旧版单账户渠道配置提升到 +`channels..accounts.*` 时，它会使用该 surface。 +Matrix 是当前内置示例：当命名账户已存在时，它只会将认证 / bootstrap 键移动到某个已命名的提升账户中，并且它可以保留已配置的非规范默认账户键，而不是始终创建 `accounts.default`。 -这些设置 patch adapters 使内置契约接口发现保持惰性。导入 -时间保持轻量；提升接口只会在首次使用时加载，而不是在模块导入时重新进入内置渠道启动流程。 +这些 setup patch adapters 让内置契约 surface 的发现保持懒加载。 +导入时保持轻量；提升 surface 只会在首次使用时加载，而不会在模块导入时重新进入内置渠道启动流程。 -当这些启动接口包含 Gateway 网关 RPC 方法时，请保持它们位于 -插件专属前缀下。core 管理命名空间（`config.*`、 +当这些启动 surface 包含 Gateway 网关 RPC 方法时，请将它们保留在 +插件专用前缀下。Core 管理员命名空间（`config.*`、 `exec.approvals.*`、`wizard.*`、`update.*`）仍然保留，并始终解析为 -`operator.admin`，即使某个插件请求了更窄的作用域。 +`operator.admin`，即使某个插件请求了更狭窄的作用域。 示例： @@ -1230,7 +1354,8 @@ Matrix 是当前的内置示例：当已存在命名账户时，它只会将 aut ### 渠道目录元数据 -渠道插件可以通过 `openclaw.channel` 宣传设置 / 发现元数据，并通过 `openclaw.install` 提供安装提示。这样可让 core 保持无数据。 +渠道插件可以通过 `openclaw.channel` 宣传 setup / discovery 元数据， +并通过 `openclaw.install` 宣传安装提示。这使 core 目录保持无数据化。 示例： @@ -1258,37 +1383,39 @@ Matrix 是当前的内置示例：当已存在命名账户时，它只会将 aut } ``` -除最小示例外，其他有用的 `openclaw.channel` 字段包括： +除最小示例外，其他有用的 `openclaw.channel` 字段还包括： -- `detailLabel`：更丰富目录 / 状态接口中的次级标签 +- `detailLabel`：用于更丰富目录 / 状态 surface 的次级标签 - `docsLabel`：覆盖文档链接文本 -- `preferOver`：该目录条目应优先于的低优先级插件 / 渠道 id -- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：用于选择界面文案控制 -- `markdownCapable`：将渠道标记为支持 Markdown，以供出站格式决策使用 -- `exposure.configured`：设为 `false` 时，在已配置渠道列表接口中隐藏该渠道 -- `exposure.setup`：设为 `false` 时，在交互式设置 / 配置选择器中隐藏该渠道 -- `exposure.docs`：将渠道标记为内部 / 私有，用于文档导航接口 -- `showConfigured` / `showInSetup`：仍接受的旧版兼容别名；优先使用 `exposure` -- `quickstartAllowFrom`：让渠道接入标准快速开始 `allowFrom` 流程 -- `forceAccountBinding`：即使只存在一个账户，也要求显式账户绑定 -- `preferSessionLookupForAnnounceTarget`：在解析 announce target 时优先进行会话查找 +- `preferOver`：此目录条目应优先于的低优先级插件 / 渠道 id +- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择 surface 的文案控制字段 +- `markdownCapable`：将该渠道标记为支持 markdown，以便用于出站格式决策 +- `exposure.configured`：设为 `false` 时，在已配置渠道列表 surface 中隐藏该渠道 +- `exposure.setup`：设为 `false` 时，在交互式 setup / configure 选择器中隐藏该渠道 +- `exposure.docs`：将该渠道标记为内部 / 私有，以供文档导航 surface 使用 +- `showConfigured` / `showInSetup`：为兼容性仍接受的旧版别名；优先使用 `exposure` +- `quickstartAllowFrom`：使该渠道接入标准快速开始 `allowFrom` 流程 +- `forceAccountBinding`：即使只有一个账户，也要求显式账户绑定 +- `preferSessionLookupForAnnounceTarget`：在解析 announce 目标时优先使用 session 查找 -OpenClaw 还可以合并**外部渠道目录**（例如 MPM -注册表导出）。将 JSON 文件放到以下任一位置： +OpenClaw 还可以合并**外部渠道目录**（例如某个 MPM +注册表导出）。将 JSON 文件放在以下位置之一： - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（使用逗号 / 分号 / `PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧版别名。 +或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（以逗号 / 分号 / `PATH` 分隔）。每个文件都应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧版别名。 ## 上下文引擎插件 -上下文引擎插件拥有会话上下文编排能力，用于摄取、组装和压缩。请在你的插件中通过 -`api.registerContextEngine(id, factory)` 注册它们，然后通过 +上下文引擎插件拥有会话上下文的编排职责，包括摄取、组装和压缩。 +在你的插件中通过 +`api.registerContextEngine(id, factory)` 注册它们，然后用 `plugins.slots.contextEngine` 选择活动引擎。 -当你的插件需要替换或扩展默认上下文流水线，而不仅仅是增加 memory 搜索或 hooks 时，请使用此方式。 +当你的插件需要替换或扩展默认上下文流水线，而不只是添加 +memory search 或 hooks 时，请使用这种方式。 ```ts export default function (api) { @@ -1307,7 +1434,7 @@ export default function (api) { } ``` -如果你的引擎**并不**拥有压缩算法，请保持 `compact()` +如果你的引擎**不**拥有压缩算法，请保持 `compact()` 已实现，并显式委托它： ```ts @@ -1335,41 +1462,40 @@ export default function (api) { ## 添加新能力 -当插件需要当前 API 无法适配的行为时，不要通过私有深入访问绕过 +当插件需要当前 API 无法适配的行为时，不要通过私有深度调用绕过 插件系统。请添加缺失的能力。 推荐顺序： 1. 定义 core 契约 - 明确共享行为中哪些由 core 拥有：策略、回退、配置合并、 - 生命周期、面向渠道的语义，以及运行时辅助工具形状。 -2. 添加类型化插件注册 / 运行时接口 - 以最小但有用的类型化能力接口扩展 `OpenClawPluginApi` 和 / 或 `api.runtime`。 -3. 接线 core + 渠道 / 功能消费者 + 确定 core 应拥有的共享行为：策略、回退、配置合并、 + 生命周期、面向渠道的语义以及运行时辅助工具形状。 +2. 添加类型化插件注册 / 运行时 surface + 用最小但有用的类型化能力 surface 扩展 `OpenClawPluginApi` 和 / 或 `api.runtime`。 +3. 接入 core + 渠道 / 功能消费者 渠道和功能插件应通过 core 消费新能力， - 而不是直接导入某个厂商实现。 -4. 注册厂商实现 - 厂商插件随后针对该能力注册自己的后端。 + 而不是直接导入某个提供商实现。 +4. 注册提供商实现 + 然后由提供商插件将其后端注册到该能力上。 5. 添加契约覆盖 - 添加测试，以便随着时间推移，归属和注册形状保持明确。 + 添加测试，以便归属和注册形状随时间保持明确。 -这就是 OpenClaw 如何在保持明确主张的同时，不会被硬编码到某一个 -提供商世界观中。具体的文件清单和完整示例，请参阅[能力扩展手册](/zh-CN/plugins/architecture)。 +这正是 OpenClaw 在保持明确主张的同时，又不被某个提供商世界观写死的方式。具体的文件检查清单和完整示例请参阅 [能力扩展手册](/zh-CN/plugins/architecture)。 -### 能力清单 +### 能力检查清单 -当你添加一个新能力时，实现通常应同时涉及以下接口： +添加新能力时，通常应一起改动以下 surface： - `src//types.ts` 中的 core 契约类型 - `src//runtime.ts` 中的 core runner / 运行时辅助工具 -- `src/plugins/types.ts` 中的插件 API 注册接口 +- `src/plugins/types.ts` 中的插件 API 注册 surface - `src/plugins/registry.ts` 中的插件注册表接线 -- 当功能 / 渠道插件需要消费它时，位于 `src/plugins/runtime/*` 的插件运行时暴露层 +- 当功能 / 渠道插件需要消费它时，`src/plugins/runtime/*` 中的插件运行时暴露层 - `src/test-utils/plugin-registration.ts` 中的捕获 / 测试辅助工具 - `src/plugins/contracts/registry.ts` 中的归属 / 契约断言 -- `docs/` 中面向运维者 / 插件的文档 +- `docs/` 中的运维人员 / 插件文档 -如果这些接口中的某一个缺失，通常意味着该能力还没有真正完成集成。 +如果其中某个 surface 缺失，通常意味着这个能力尚未完全集成。 ### 能力模板 @@ -1405,9 +1531,9 @@ const clip = await api.runtime.videoGeneration.generate({ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -这样规则就很简单： +这让规则保持简单： - core 拥有能力契约 + 编排 -- 厂商插件拥有厂商实现 +- 提供商插件拥有提供商实现 - 功能 / 渠道插件消费运行时辅助工具 -- 契约测试使归属保持明确 +- 契约测试让归属保持明确 diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 2fdb7b778..1e5fc2631 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -1,63 +1,72 @@ --- read_when: - - 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 - - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 + - 你看到了 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 警告 + - 你看到了 OPENCLAW_EXTENSION_API_DEPRECATED 警告 - 你正在将插件更新到现代插件架构 - - 你在维护一个外部 OpenClaw 插件 + - 你在维护外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-06T04:10:54Z" + generated_at: "2026-04-06T15:30:36Z" model: gpt-5.4 provider: openai - source_hash: 94f12d1376edd8184714cc4dbea4a88fa8ed652f65e9365ede6176f3bf441b33 + source_hash: 770eca214dcd7c7c22ee507d4bb4359b505a29c9ecd4458f7b5e1362c5cd0d6e source_path: plugins/sdk-migration.md workflow: 15 --- # 插件 SDK 迁移 -OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚焦且有文档说明的导入方式。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 +OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚焦且有文档记录的导入方式。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 ## 正在发生什么变化 -旧版插件系统提供了两个高度开放的接口，使插件能够从单一入口点导入所需的任何内容： +旧版插件系统提供了两个高度开放的接口，使插件可以通过单一入口点导入所需的任何内容： -- **`openclaw/plugin-sdk/compat`** — 一个单一导入入口，会重新导出数十个辅助工具。它的引入是为了在新插件架构构建期间，让较旧的基于 hook 的插件继续工作。 -- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问宿主端辅助工具，例如嵌入式智能体运行器。 +- **`openclaw/plugin-sdk/compat`** — 一个单一导入点，重新导出数十个辅助函数。它的引入是为了在新插件架构构建期间，让旧版基于 hook 的插件继续工作。 +- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问宿主侧辅助函数，例如嵌入式智能体执行器。 -这两个接口现在都已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 +这两个接口现在都已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 - 向后兼容层将在未来的一个主版本中移除。 - 仍然从这些接口导入的插件届时将会中断。 + 向后兼容层将在未来的主版本中移除。 + 仍从这些接口导入的插件届时将会失效。 ## 为什么会有这个变化 -旧方法会带来一些问题： +旧方法带来了很多问题： -- **启动缓慢** — 导入一个辅助工具会加载数十个无关模块 -- **循环依赖** — 宽泛的重新导出很容易造成导入环 -- **API 接口不清晰** — 无法区分哪些导出是稳定的，哪些是内部实现 +- **启动缓慢** — 导入一个辅助函数会加载数十个无关模块 +- **循环依赖** — 宽泛的重新导出让导入环路更容易出现 +- **API 接口不清晰** — 无法判断哪些导出是稳定的，哪些属于内部实现 -现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有清晰的用途和有文档说明的契约。 +现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`） +都是一个小型、自包含模块，拥有明确用途和文档化契约。 -用于内置渠道的旧版提供商便捷接口也已移除。像 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带有渠道品牌的辅助接口以及 `openclaw/plugin-sdk/telegram-core` 这样的导入，都是私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区中，请将提供商自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +面向内置渠道的旧版提供商便捷接口也已经移除。类似 +`openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、 +`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、 +带渠道品牌的辅助接口，以及 +`openclaw/plugin-sdk/telegram-core` +这类导入路径，都是私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，请将提供商拥有的辅助函数保存在该插件自己的 +`api.ts` 或 `runtime-api.ts` 中。 当前内置提供商示例： -- Anthropic 将 Claude 专用的流式辅助工具保留在自己的 `api.ts` / `contract-api.ts` 接口中 -- OpenAI 将提供商构建器、默认模型辅助工具以及 realtime 提供商构建器保留在自己的 `api.ts` 中 -- OpenRouter 将提供商构建器以及新手引导 / 配置辅助工具保留在自己的 `api.ts` 中 +- Anthropic 将 Claude 专用流辅助函数保存在其自己的 `api.ts` / + `contract-api.ts` 接口中 +- OpenAI 将提供商构建器、默认模型辅助函数和实时提供商构建器保存在其自己的 `api.ts` 中 +- OpenRouter 将提供商构建器以及新手引导/配置辅助函数保存在其自己的 + `api.ts` 中 ## 如何迁移 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在未解析的 Windows - `.cmd`/`.bat` 包装器会默认以失败关闭，除非你显式传入 + `.cmd`/`.bat` 包装器将默认以失败关闭，除非你显式传入 `allowShellFallback: true`。 ```typescript @@ -73,13 +82,13 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚 }); ``` - 如果你的调用方并非有意依赖 shell 回退，请不要设置 + 如果你的调用方并不有意依赖 shell 回退，请不要设置 `allowShellFallback`，而应改为处理抛出的错误。 - 在你的插件中搜索来自这两个已弃用接口的导入： + 在你的插件中搜索来自以下任一已弃用接口的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -89,7 +98,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚 - 旧接口中的每个导出都映射到一个特定的现代导入路径： + 旧接口中的每个导出，都映射到一个特定的现代导入路径： ```typescript // Before (deprecated backwards-compatibility layer) @@ -105,7 +114,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚 import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - 对于宿主端辅助工具，请使用注入的插件运行时，而不是直接导入： + 对于宿主侧辅助函数，请使用注入的插件运行时，而不是直接导入： ```typescript // Before (deprecated extension-api bridge) @@ -116,9 +125,9 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚 const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - 其他旧版桥接辅助工具同样适用这一模式： + 相同模式也适用于其他旧版桥接辅助函数： - | 旧导入 | 现代等价项 | + | 旧导入 | 现代等价写法 | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -126,7 +135,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚 | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | session store helpers | `api.runtime.agent.session.*` | + | 会话存储辅助函数 | `api.runtime.agent.session.*` | @@ -143,195 +152,198 @@ 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` | 单一提供商入口辅助工具 | `defineSingleProviderPluginEntry` | + | `plugin-sdk/provider-entry` | 单提供商入口辅助函数 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享的设置向导辅助工具 | allowlist 提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 可安全导入的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托式设置代理 | - | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表 / 配置 / 操作门控辅助工具 | - | `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`，account-id 规范化 | - | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表 / 账户操作辅助工具 | - | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/setup` | 共享设置向导辅助函数 | 允许列表提示、设置状态构建器 | + | `plugin-sdk/setup-runtime` | 设置时运行时辅助函数 | 导入安全的设置补丁适配器、查找说明辅助函数、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | + | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助函数 | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | 设置工具辅助函数 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | 多账户辅助函数 | 账户列表/配置/动作门控辅助函数 | + | `plugin-sdk/account-id` | 账户 id 辅助函数 | `DEFAULT_ACCOUNT_ID`、账户 id 标准化 | + | `plugin-sdk/account-resolution` | 账户查找辅助函数 | 账户查找 + 默认回退辅助函数 | + | `plugin-sdk/account-helpers` | 窄接口账户辅助函数 | 账户列表/账户动作辅助函数 | + | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, 以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 输入中状态联动 | `createChannelReplyPipeline` | + | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 输入中状态布线 | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 渠道配置 schema 类型 | - | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复 / 冲突校验 | - | `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` | + | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助函数 | 命令名称标准化、描述裁剪、重复/冲突校验 | + | `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | 账户状态跟踪 | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope 构建器辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享的记录并分发辅助工具 | - | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助工具 | - | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享的出站媒体加载 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份 / 发送委托辅助工具 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 用于旧版字段布局的智能体媒体负载构建器 | - | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅限旧版渠道运行时工具 | + | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助函数 | 共享路由 + envelope 构建辅助函数 | + | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助函数 | 共享记录与分发辅助函数 | + | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助函数 | + | `plugin-sdk/outbound-media` | 出站媒体辅助函数 | 共享出站媒体加载 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助函数 | 出站身份/发送委托辅助函数 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助函数 | 线程绑定生命周期和适配器辅助函数 | + | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助函数 | 面向旧字段布局的智能体媒体负载构建器 | + | `plugin-sdk/channel-runtime` | 已弃用兼容 shim | 仅旧版渠道运行时工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | 宽泛的运行时辅助工具 | 运行时 / 日志 / 备份 / 插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | logger / runtime env、超时、重试和退避辅助工具 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / hooks / http / 交互辅助工具 | - | `plugin-sdk/hook-runtime` | Hook 管道辅助工具 | 共享 webhook / 内部 hook 管道辅助工具 | - | `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 | - | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 | - | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 | - | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供具备稳定回退的 Telegram 命令校验辅助工具 | - | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批负载、审批能力 / 配置文件辅助工具、本地审批路由 / 运行时辅助工具 | - | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同聊天操作认证 | - | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件 / 过滤辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力 / 投递适配器 | - | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复负载辅助工具 | - | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和密钥收集辅助工具 | - | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 | - | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | pinned-dispatcher、受保护 fetch、SSRF 策略辅助工具 | - | `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 | - | `plugin-sdk/fetch-runtime` | 包装后的 fetch / 代理辅助工具 | `resolveFetch`、代理辅助工具 | - | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 | - | `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | allowlist 输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送方授权辅助工具、命令注册表辅助工具 | - | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 | - | `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标工具 | - | `plugin-sdk/webhook-request-guards` | webhook 请求体守卫辅助工具 | 请求体读取 / 限制辅助工具 | + | `plugin-sdk/runtime` | 宽接口运行时辅助函数 | 运行时/日志/备份/插件安装辅助函数 | + | `plugin-sdk/runtime-env` | 窄接口运行时环境辅助函数 | Logger/运行时环境、超时、重试和退避辅助函数 | + | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助函数 | 插件命令/hooks/http/交互式辅助函数 | + | `plugin-sdk/hook-runtime` | Hook 管道辅助函数 | 共享 webhook/内部 hook 管道辅助函数 | + | `plugin-sdk/lazy-runtime` | 延迟运行时辅助函数 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程辅助函数 | 共享 exec 辅助函数 | + | `plugin-sdk/cli-runtime` | CLI 运行时辅助函数 | 命令格式化、等待、版本辅助函数 | + | `plugin-sdk/gateway-runtime` | Gateway 网关辅助函数 | Gateway 网关客户端和渠道状态补丁辅助函数 | + | `plugin-sdk/config-runtime` | 配置辅助函数 | 配置加载/写入辅助函数 | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助函数 | 当内置 Telegram 契约接口不可用时，提供稳定回退的 Telegram 命令校验辅助函数 | + | `plugin-sdk/approval-runtime` | 审批提示辅助函数 | exec/插件审批负载、审批能力/配置文件辅助函数、原生审批路由/运行时辅助函数 | + | `plugin-sdk/approval-auth-runtime` | 审批凭证辅助函数 | 审批人解析、同聊天动作凭证 | + | `plugin-sdk/approval-client-runtime` | 审批客户端辅助函数 | 原生 exec 审批配置文件/过滤辅助函数 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助函数 | 原生审批能力/投递适配器 | + | `plugin-sdk/approval-native-runtime` | 审批目标辅助函数 | 原生审批目标/账户绑定辅助函数 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助函数 | exec/插件审批回复负载辅助函数 | + | `plugin-sdk/security-runtime` | 安全辅助函数 | 共享信任、私信门控、外部内容和密钥收集辅助函数 | + | `plugin-sdk/ssrf-policy` | SSRF 策略辅助函数 | 主机允许列表和私有网络策略辅助函数 | + | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助函数 | 固定 dispatcher、受保护 fetch、SSRF 策略辅助函数 | + | `plugin-sdk/collection-runtime` | 有界缓存辅助函数 | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助函数 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | 错误格式化辅助函数 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助函数 | + | `plugin-sdk/fetch-runtime` | 包装过的 fetch/代理辅助函数 | `resolveFetch`、代理辅助函数 | + | `plugin-sdk/host-runtime` | 主机标准化辅助函数 | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | 重试辅助函数 | `RetryConfig`, `retryAsync`、策略执行器 | + | `plugin-sdk/allow-from` | 允许列表格式化 | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | 允许列表输入映射 | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | 命令门控和命令接口辅助函数 | `resolveControlCommandGate`、发送者授权辅助函数、命令注册表辅助函数 | + | `plugin-sdk/secret-input` | Secret 输入解析 | Secret 输入辅助函数 | + | `plugin-sdk/webhook-ingress` | webhook 请求辅助函数 | webhook 目标工具函数 | + | `plugin-sdk/webhook-request-guards` | webhook 请求体防护辅助函数 | 请求体读取/限制辅助函数 | | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | finalize + provider 分发辅助工具 | - | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-dispatch-runtime` | 窄接口回复分发辅助函数 | 最终化 + 提供商分发辅助函数 | + | `plugin-sdk/reply-history` | 回复历史辅助函数 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本 / markdown 分块辅助工具 | - | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 | - | `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 | - | `plugin-sdk/routing` | 路由 / session-key 辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、session-key 规范化辅助工具 | - | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道 / 账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | - | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 | - | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug / 字符串规范化辅助工具 | - | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类似请求的输入中提取字符串 URL | - | `plugin-sdk/run-command` | 定时命令辅助工具 | 带标准化 stdout / stderr 的定时命令运行器 | - | `plugin-sdk/param-readers` | 参数读取器 | 通用工具 / CLI 参数读取器 | + | `plugin-sdk/reply-chunking` | 回复分块辅助函数 | 文本/markdown 分块辅助函数 | + | `plugin-sdk/session-store-runtime` | 会话存储辅助函数 | 存储路径 + updated-at 辅助函数 | + | `plugin-sdk/state-paths` | 状态路径辅助函数 | 状态和 OAuth 目录辅助函数 | + | `plugin-sdk/routing` | 路由/会话键辅助函数 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键标准化辅助函数 | + | `plugin-sdk/status-helpers` | 渠道状态辅助函数 | 渠道/账户状态摘要构建器、运行时状态默认值、问题元数据辅助函数 | + | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助函数 | 共享目标解析器辅助函数 | + | `plugin-sdk/string-normalization-runtime` | 字符串标准化辅助函数 | slug/字符串标准化辅助函数 | + | `plugin-sdk/request-url` | 请求 URL 辅助函数 | 从类请求输入中提取字符串 URL | + | `plugin-sdk/run-command` | 定时命令辅助函数 | 带标准化 stdout/stderr 的定时命令执行器 | + | `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 | | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | - | `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 | - | `plugin-sdk/logging-core` | 日志辅助工具 | 子系统 logger 和脱敏辅助工具 | - | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 | + | `plugin-sdk/temp-path` | 临时路径辅助函数 | 共享临时下载路径辅助函数 | + | `plugin-sdk/logging-core` | 日志辅助函数 | 子系统 logger 和脱敏辅助函数 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助函数 | Markdown 表格模式辅助函数 | | `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 | - | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助工具 | 自托管提供商发现 / 配置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助工具 | 同样的自托管提供商发现 / 配置辅助工具 | - | `plugin-sdk/provider-auth-runtime` | 提供商运行时认证辅助工具 | 运行时 API key 解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | 提供商 API key 设置辅助工具 | API key 新手引导 / 配置文件写入辅助工具 | - | `plugin-sdk/provider-auth-result` | 提供商 auth-result 辅助工具 | 标准 OAuth auth-result 构建器 | - | `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助工具 | 共享交互式登录辅助工具 | - | `plugin-sdk/provider-env-vars` | 提供商环境变量辅助工具 | 提供商认证环境变量查找辅助工具 | - | `plugin-sdk/provider-model-shared` | 共享提供商 model / replay 辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具以及 model-id 规范化辅助工具 | - | `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助工具 | - | `plugin-sdk/provider-http` | 提供商 HTTP 辅助工具 | 通用提供商 HTTP / endpoint 能力辅助工具 | - | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助工具 | web-fetch 提供商注册 / 缓存辅助工具 | - | `plugin-sdk/provider-web-search` | 提供商 web-search 辅助工具 | web-search 提供商注册 / 缓存 / 配置辅助工具 | - | `plugin-sdk/provider-tools` | 提供商工具 / schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | 提供商用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他提供商用量辅助工具 | - | `plugin-sdk/provider-stream` | 提供商流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助工具 | + | `plugin-sdk/provider-setup` | 精选本地/自托管提供商设置辅助函数 | 自托管提供商发现/配置辅助函数 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助函数 | 相同的自托管提供商发现/配置辅助函数 | + | `plugin-sdk/provider-auth-runtime` | 提供商运行时凭证辅助函数 | 运行时 API 密钥解析辅助函数 | + | `plugin-sdk/provider-auth-api-key` | 提供商 API 密钥设置辅助函数 | API 密钥新手引导/配置文件写入辅助函数 | + | `plugin-sdk/provider-auth-result` | 提供商 auth-result 辅助函数 | 标准 OAuth auth-result 构建器 | + | `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助函数 | 共享交互式登录辅助函数 | + | `plugin-sdk/provider-env-vars` | 提供商环境变量辅助函数 | 提供商凭证环境变量查找辅助函数 | + | `plugin-sdk/provider-model-shared` | 共享提供商模型/重放辅助函数 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、提供商端点辅助函数和模型 id 标准化辅助函数 | + | `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助函数 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助函数 | + | `plugin-sdk/provider-http` | 提供商 HTTP 辅助函数 | 通用提供商 HTTP/端点能力辅助函数 | + | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助函数 | web-fetch 提供商注册/缓存辅助函数 | + | `plugin-sdk/provider-web-search` | 提供商 web-search 辅助函数 | Web 搜索提供商注册/缓存/配置辅助函数 | + | `plugin-sdk/provider-tools` | 提供商工具/schema 兼容辅助函数 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助函数，如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | 提供商使用量辅助函数 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他提供商使用量辅助函数 | + | `plugin-sdk/provider-stream` | 提供商流包装辅助函数 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装辅助函数 | | `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取 / 转换 / 存储辅助工具以及媒体负载构建器 | - | `plugin-sdk/media-generation-runtime` | 共享 media-generation 辅助工具 | 图像 / 视频 / 音乐生成的共享故障切换辅助工具、候选项选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | media-understanding 辅助工具 | media understanding 提供商类型以及面向提供商的图像 / 音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 对智能体可见文本的剥离、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具以及相关文本 / 日志辅助工具 | - | `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音辅助工具 | 语音提供商类型以及面向提供商的 directive、注册表和校验辅助工具 | - | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转写辅助工具 | 提供商类型和注册表辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | 提供商类型和注册表辅助工具 | - | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障切换、认证和注册表辅助工具 | - | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider / request / result 类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider / request / result 类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化 / 归约 | - | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道 config-schema 原语 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 | - | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 | - | `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照 / 摘要辅助工具 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑 / 读取辅助工具 | - | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证 / 守卫辅助工具 | - | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态辅助原语 | - | `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和路由安装辅助工具 | - | `plugin-sdk/webhook-path` | webhook 路径辅助工具 | webhook 路径规范化辅助工具 | - | `plugin-sdk/web-media` | 共享 web 媒体辅助工具 | 远程 / 本地媒体加载辅助工具 | + | `plugin-sdk/media-runtime` | 共享媒体辅助函数 | 媒体获取/转换/存储辅助函数，以及媒体负载构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助函数 | 图像/视频/音乐生成的共享回退辅助函数、候选选择和缺失模型提示 | + | `plugin-sdk/media-understanding` | 媒体理解辅助函数 | 媒体理解提供商类型，以及面向提供商的图像/音频辅助函数导出 | + | `plugin-sdk/text-runtime` | 共享文本辅助函数 | 助手可见文本剥离、markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数、安全文本工具函数，以及相关文本/日志辅助函数 | + | `plugin-sdk/text-chunking` | 文本分块辅助函数 | 出站文本分块辅助函数 | + | `plugin-sdk/speech` | 语音辅助函数 | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助函数 | + | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、标准化 | + | `plugin-sdk/realtime-transcription` | 实时转录辅助函数 | 提供商类型和注册表辅助函数 | + | `plugin-sdk/realtime-voice` | 实时语音辅助函数 | 提供商类型和注册表辅助函数 | + | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、回退、凭证和注册表辅助函数 | + | `plugin-sdk/music-generation` | 音乐生成辅助函数 | 音乐生成提供商/请求/结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、回退辅助函数、提供商查找和模型引用解析 | + | `plugin-sdk/video-generation` | 视频生成辅助函数 | 视频生成提供商/请求/结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、回退辅助函数、提供商查找和模型引用解析 | + | `plugin-sdk/interactive-runtime` | 交互式回复辅助函数 | 交互式回复负载标准化/归并 | + | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄接口渠道 config-schema 原语 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助函数 | 渠道配置写入授权辅助函数 | + | `plugin-sdk/channel-plugin-common` | 共享渠道前导层 | 共享渠道插件前导导出 | + | `plugin-sdk/channel-status` | 渠道状态辅助函数 | 共享渠道状态快照/摘要辅助函数 | + | `plugin-sdk/allowlist-config-edit` | 允许列表配置辅助函数 | 允许列表配置编辑/读取辅助函数 | + | `plugin-sdk/group-access` | 群组访问辅助函数 | 共享群组访问决策辅助函数 | + | `plugin-sdk/direct-dm` | 直接私信辅助函数 | 共享直接私信凭证/防护辅助函数 | + | `plugin-sdk/extension-shared` | 共享扩展辅助函数 | 被动渠道/状态和环境代理辅助原语 | + | `plugin-sdk/webhook-targets` | webhook 目标辅助函数 | webhook 目标注册表和路由安装辅助函数 | + | `plugin-sdk/webhook-path` | webhook 路径辅助函数 | webhook 路径标准化辅助函数 | + | `plugin-sdk/web-media` | 共享 Web 媒体辅助函数 | 远程/本地媒体加载辅助函数 | | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用方重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | memory manager / config / file / CLI 辅助接口 | - | `plugin-sdk/memory-core-engine-runtime` | memory engine 运行时门面 | memory index / search 运行时门面 | - | `plugin-sdk/memory-core-host-engine-foundation` | memory host foundation engine | memory host foundation engine 导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | memory host embedding engine | memory host embedding engine 导出 | - | `plugin-sdk/memory-core-host-engine-qmd` | memory host QMD engine | memory host QMD engine 导出 | - | `plugin-sdk/memory-core-host-engine-storage` | memory host storage engine | memory host storage engine 导出 | - | `plugin-sdk/memory-core-host-multimodal` | memory host multimodal 辅助工具 | memory host multimodal 辅助工具 | - | `plugin-sdk/memory-core-host-query` | memory host query 辅助工具 | memory host query 辅助工具 | - | `plugin-sdk/memory-core-host-secret` | memory host secret 辅助工具 | memory host secret 辅助工具 | - | `plugin-sdk/memory-core-host-events` | memory host 事件日志辅助工具 | memory host 事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | memory host 状态辅助工具 | memory host 状态辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | memory host CLI 运行时 | memory host CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | memory host 核心运行时 | memory host 核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | memory host 文件 / 运行时辅助工具 | memory host 文件 / 运行时辅助工具 | - | `plugin-sdk/memory-host-core` | memory host 核心运行时别名 | 面向厂商中立的 memory host 核心运行时辅助工具别名 | - | `plugin-sdk/memory-host-events` | memory host 事件日志别名 | 面向厂商中立的 memory host 事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | memory host 文件 / 运行时别名 | 面向厂商中立的 memory host 文件 / 运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助工具 | 面向 memory 邻接插件的共享托管 markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 活跃 memory 搜索门面 | 惰性 active-memory search-manager 运行时门面 | - | `plugin-sdk/memory-host-status` | memory host 状态别名 | 面向厂商中立的 memory host 状态辅助工具别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | memory-lancedb 辅助接口 | - | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mocks | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助函数 | 内存管理器/配置/文件/CLI 辅助接口 | + | `plugin-sdk/memory-core-engine-runtime` | 内存引擎运行时门面 | 内存索引/搜索运行时门面 | + | `plugin-sdk/memory-core-host-engine-foundation` | 内存宿主基础引擎 | 内存宿主基础引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | 内存宿主嵌入引擎 | 内存宿主嵌入引擎导出 | + | `plugin-sdk/memory-core-host-engine-qmd` | 内存宿主 QMD 引擎 | 内存宿主 QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | 内存宿主存储引擎 | 内存宿主存储引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | 内存宿主多模态辅助函数 | 内存宿主多模态辅助函数 | + | `plugin-sdk/memory-core-host-query` | 内存宿主查询辅助函数 | 内存宿主查询辅助函数 | + | `plugin-sdk/memory-core-host-secret` | 内存宿主 secret 辅助函数 | 内存宿主 secret 辅助函数 | + | `plugin-sdk/memory-core-host-events` | 内存宿主事件日志辅助函数 | 内存宿主事件日志辅助函数 | + | `plugin-sdk/memory-core-host-status` | 内存宿主状态辅助函数 | 内存宿主状态辅助函数 | + | `plugin-sdk/memory-core-host-runtime-cli` | 内存宿主 CLI 运行时 | 内存宿主 CLI 运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-core` | 内存宿主核心运行时 | 内存宿主核心运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-files` | 内存宿主文件/运行时辅助函数 | 内存宿主文件/运行时辅助函数 | + | `plugin-sdk/memory-host-core` | 内存宿主核心运行时别名 | 面向厂商中立的内存宿主核心运行时辅助函数别名 | + | `plugin-sdk/memory-host-events` | 内存宿主事件日志别名 | 面向厂商中立的内存宿主事件日志辅助函数别名 | + | `plugin-sdk/memory-host-files` | 内存宿主文件/运行时别名 | 面向厂商中立的内存宿主文件/运行时辅助函数别名 | + | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助函数 | 适用于 memory 邻接插件的共享托管 markdown 辅助函数 | + | `plugin-sdk/memory-host-search` | 活跃内存搜索门面 | 惰性活跃内存 search-manager 运行时门面 | + | `plugin-sdk/memory-host-status` | 内存宿主状态别名 | 面向厂商中立的内存宿主状态辅助函数别名 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助函数 | memory-lancedb 辅助接口 | + | `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/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` 当前公开的窄范围 token 辅助接口为 +`plugin-sdk/github-copilot-token` 目前公开了窄接口令牌辅助接口： `DEFAULT_COPILOT_API_BASE_URL`、 `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 -请使用与任务最匹配的最窄导入路径。如果你找不到某个导出，请查看 `src/plugin-sdk/` 中的源代码，或在 Discord 中提问。 +请使用与任务最匹配的最窄导入路径。如果你找不到某个导出，请查看 +`src/plugin-sdk/` 中的源码，或在 Discord 中提问。 ## 移除时间线 | 时间 | 会发生什么 | | ---------------------- | ----------------------------------------------------------------------- | | **现在** | 已弃用接口会发出运行时警告 | -| **下一个主版本** | 已弃用接口将被移除；仍在使用它们的插件将会失败 | +| **下一个主版本** | 已弃用接口将被移除；仍在使用它们的插件将会失效 | -所有核心插件都已经完成迁移。外部插件应在下一个主版本之前完成迁移。 +所有核心插件都已完成迁移。外部插件应在下一个主版本之前完成迁移。 ## 临时抑制警告 -在迁移期间，你可以设置这些环境变量： +在你迁移期间，可以设置以下环境变量： ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run @@ -343,7 +355,7 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ## 相关内容 - [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件 -- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考 +- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 - [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析 diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index 335c9437d..b86691ef2 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -1,26 +1,26 @@ --- read_when: - - 你需要知道应该从哪个 SDK 子路径导入 - - 你想查看 OpenClawPluginApi 上所有注册方法的参考 - - 你正在查找某个特定的 SDK 导出 + - 你需要了解应该从哪个 SDK 子路径导入 + - 你想查阅 OpenClawPluginApi 上所有注册方法的参考说明 + - 你正在查找某个特定的 SDK 导出项 sidebarTitle: SDK Overview summary: 导入映射、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-04-06T12:44:55Z" + generated_at: "2026-04-06T15:30:53Z" model: gpt-5.4 provider: openai - source_hash: e045097753f33d13d570f6ce5297d2a7c0f0ad8b31515d0d9021386c8004354c + source_hash: a08fa2d63e82ec921d63310eeede4ef868c452471402a55a1133deeaf78db0a8 source_path: plugins/sdk-overview.md workflow: 15 --- # 插件 SDK 概览 -插件 SDK 是插件与核心之间的类型化契约。本页是关于 **该导入什么** 以及 **你可以注册什么** 的参考。 +插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考文档。 - **在找操作指南？** + **在找操作指南吗？** - 第一个插件？从 [入门指南](/zh-CN/plugins/building-plugins) 开始 - 渠道插件？参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins) - 提供商插件？参见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins) @@ -35,22 +35,29 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -每个子路径都是一个小型、独立的模块。这可以保持快速启动，并防止循环依赖问题。对于渠道特定的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更宽泛的汇总接口和共享辅助工具，例如 `buildChannelConfigSchema`。 +每个子路径都是一个小型、自包含模块。这样可以保持启动速度快，并防止循环依赖问题。对于特定于渠道的入口/构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 留给更广泛的总入口表面和共享辅助函数，例如 `buildChannelConfigSchema`。 -不要添加或依赖以提供商命名的便捷扩展点，例如 +不要添加或依赖带提供商名称的便捷接缝，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、 `openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或 -带有渠道品牌的辅助扩展点。内置插件应在它们自己的 `api.ts` 或 `runtime-api.ts` barrel 中组合通用 SDK 子路径，而核心则应使用这些插件本地 barrel，或在需求确实跨渠道时添加一个狭义的通用 SDK 契约。 +带渠道品牌的辅助接缝。内置插件应在其自己的 `api.ts` 或 `runtime-api.ts` +barrel 中组合通用 SDK 子路径，而核心则应使用这些插件本地 barrel， +或者在需求确实跨渠道时添加一个窄而通用的 SDK 契约。 -生成的导出映射中仍包含一小部分内置插件辅助扩展点，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅为内置插件维护和兼容性而存在；它们有意未列入下方的常用表格中，也不是新的第三方插件推荐使用的导入路径。 +生成的导出映射中仍然包含一小部分内置插件辅助接缝，例如 +`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、 +`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些 +子路径仅用于内置插件维护和兼容性；它们在下方的常用表中被有意省略， +也不是新第三方插件推荐使用的导入路径。 ## 子路径参考 最常用的子路径，按用途分组。完整的 200+ 子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 -保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其提升为公共接口，否则请将这些视为实现细节/兼容性接口。 +保留的内置插件辅助子路径仍会出现在该生成列表中。 +除非某个文档页面明确将其提升为公开接口，否则应将其视为实现细节/兼容性表面。 -### 插件入口 +### 插件入口点 | 子路径 | 关键导出 | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | @@ -66,43 +73,43 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup` | 共享的设置向导辅助函数、允许列表提示、设置状态构建器 | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户配置/操作门控辅助工具、默认账户回退辅助工具 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 | - | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 狭义账户列表/账户操作辅助工具 | + | `plugin-sdk/account-core` | 多账号配置/操作门禁辅助函数、默认账号回退辅助函数 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、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` | 带内置契约回退的 Telegram 自定义命令规范化/验证辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 自定义命令归一化/校验辅助函数，带内置契约回退 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 | - | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 | - | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 | - | `plugin-sdk/outbound-runtime` | 出站身份/发送委托辅助工具 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 | + | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助函数 | + | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助函数 | + | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助函数 | + | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助函数 | + | `plugin-sdk/outbound-runtime` | 出站身份/发送委托辅助函数 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 | | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 | - | `plugin-sdk/conversation-runtime` | 对话/线程绑定、配对和已配置绑定辅助工具 | - | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 | - | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 | - | `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助工具 | - | `plugin-sdk/channel-config-primitives` | 狭义渠道配置 schema 原语 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 | + | `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助函数 | + | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 | + | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 | + | `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助函数 | + | `plugin-sdk/channel-config-primitives` | 窄范围渠道配置 schema 基元 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 | | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 | - | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 共享直接私信认证/守卫辅助工具 | - | `plugin-sdk/interactive-runtime` | 交互式回复负载规范化/归约辅助工具 | - | `plugin-sdk/channel-inbound` | 防抖、提及匹配、envelope 辅助工具 | + | `plugin-sdk/allowlist-config-edit` | 允许列表配置编辑/读取辅助函数 | + | `plugin-sdk/group-access` | 共享群组访问决策辅助函数 | + | `plugin-sdk/direct-dm` | 共享直接私信认证/防护辅助函数 | + | `plugin-sdk/interactive-runtime` | 交互式回复负载归一化/缩减辅助函数 | + | `plugin-sdk/channel-inbound` | 去抖、提及匹配、envelope 辅助函数 | | `plugin-sdk/channel-send-result` | 回复结果类型 | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 | + | `plugin-sdk/channel-targets` | 目标解析/匹配辅助函数 | | `plugin-sdk/channel-contract` | 渠道契约类型 | | `plugin-sdk/channel-feedback` | 反馈/反应接线 | @@ -111,102 +118,102 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管提供商的设置辅助工具 | + | `plugin-sdk/provider-setup` | 精选的本地/self-hosted 提供商设置辅助函数 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容 self-hosted 提供商设置辅助函数 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助工具，例如 `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | - | `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助工具 | - | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 | + | `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助函数 | + | `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助函数，例如 `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 | + | `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助函数 | + | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助工具，以及如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及 `normalizeNativeXaiModelId` 等 model-id 归一化辅助函数 | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具 | - | `plugin-sdk/provider-web-fetch` | 网页抓取提供商注册/缓存辅助工具 | - | `plugin-sdk/provider-web-search` | 网页搜索提供商注册/缓存/配置辅助工具 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助工具 | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 等 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | - | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 | - | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 | + | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助函数 | + | `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助函数 | + | `plugin-sdk/provider-web-search` | Web 搜索提供商注册/缓存/配置辅助函数 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 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-onboard` | 新手引导配置补丁辅助函数 | + | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助函数 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 | - | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助工具 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助工具 | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助函数 | + | `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助函数 | | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | - | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助工具 | - | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 | - | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | - | `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助工具 | + | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账号绑定辅助函数 | + | `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助函数 | + | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 | + | `plugin-sdk/command-detection` | 共享命令检测辅助函数 | + | `plugin-sdk/command-surface` | 命令体归一化和命令表面辅助函数 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和秘密收集辅助工具 | - | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 | - | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助工具 | - | `plugin-sdk/secret-input` | 秘密输入解析辅助工具 | - | `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助工具 | - | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 | + | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助函数 | + | `plugin-sdk/ssrf-policy` | 主机允许列表和私有网络 SSRF 策略辅助函数 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 防护的 fetch 和 SSRF 策略辅助函数 | + | `plugin-sdk/secret-input` | secret 输入解析辅助函数 | + | `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助函数 | + | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助函数 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 宽泛的运行时/日志/备份/插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 狭义运行时环境、logger、timeout、retry 和 backoff 辅助工具 | + | `plugin-sdk/runtime` | 广义运行时/日志/备份/插件安装辅助函数 | + | `plugin-sdk/runtime-env` | 窄范围运行时环境、logger、超时、重试和退避辅助函数 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共享插件命令/hook/HTTP/交互式辅助工具 | - | `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 管道辅助工具 | - | `plugin-sdk/lazy-runtime` | 延迟运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程 exec 辅助工具 | - | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 | - | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 | - | `plugin-sdk/config-runtime` | 配置加载/写入辅助工具 | - | `plugin-sdk/telegram-command-config` | 即使内置 Telegram 契约接口不可用，也可用的 Telegram 命令名/描述规范化及重复/冲突检查 | - | `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、auth/profile 辅助工具、原生路由/运行时辅助工具 | - | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、heartbeat、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 狭义回复分发/最终化辅助工具 | - | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/交互式辅助函数 | + | `plugin-sdk/hook-runtime` | 共享 webhook/internal hook 流水线辅助函数 | + | `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程 exec 辅助函数 | + | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助函数 | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 | + | `plugin-sdk/config-runtime` | 配置加载/写入辅助函数 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述归一化和重复/冲突检查，即使内置 Telegram 契约表面不可用时也可使用 | + | `plugin-sdk/approval-runtime` | exec/插件审批辅助函数、审批能力构建器、认证/profile 辅助函数、原生路由/运行时辅助函数 | + | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助函数、分块、分发、心跳、回复规划器 | + | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发/完成辅助函数 | + | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 狭义文本/markdown 分块辅助工具 | - | `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 | - | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 | - | `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助工具、运行时状态默认值，以及问题元数据辅助工具 | - | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 | - | `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助工具 | + | `plugin-sdk/reply-chunking` | 窄范围文本/Markdown 分块辅助函数 | + | `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助函数 | + | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助函数 | + | `plugin-sdk/routing` | 路由/会话键/账号绑定辅助函数，例如 `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | 共享渠道/账号状态摘要辅助函数、运行时状态默认值和问题元数据辅助函数 | + | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助函数 | + | `plugin-sdk/string-normalization-runtime` | slug/字符串归一化辅助函数 | | `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL | - | `plugin-sdk/run-command` | 带定时功能的命令运行器，返回规范化的 stdout/stderr 结果 | - | `plugin-sdk/param-readers` | 常用工具/CLI 参数读取器 | + | `plugin-sdk/run-command` | 带计时的命令运行器，返回归一化 stdout/stderr 结果 | + | `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 | | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | - | `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 | - | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 | - | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助工具 | - | `plugin-sdk/json-store` | 小型 JSON 状态读取/写入辅助工具 | - | `plugin-sdk/file-lock` | 可重入 file-lock 辅助工具 | - | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 | - | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 | - | `plugin-sdk/agent-config-primitives` | 狭义智能体运行时配置 schema 原语 | + | `plugin-sdk/temp-path` | 共享临时下载路径辅助函数 | + | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助函数 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助函数 | + | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 | + | `plugin-sdk/file-lock` | 可重入文件锁辅助函数 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 | + | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助函数 | + | `plugin-sdk/agent-config-primitives` | 窄范围智能体运行时 config-schema 基元 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | - | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | - | `plugin-sdk/device-bootstrap` | 设备引导和配对 token 辅助工具 | - | `plugin-sdk/extension-shared` | 共享被动渠道和状态辅助原语 | - | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 | - | `plugin-sdk/skill-commands-runtime` | skill 命令列表辅助工具 | - | `plugin-sdk/native-command-registry` | 原生命令注册表构建/序列化辅助工具 | - | `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 | - | `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助工具 | - | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | - | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 | - | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和 pinned 查找辅助工具 | - | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | - | `plugin-sdk/retry-runtime` | retry 配置和 retry 运行器辅助工具 | - | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 | + | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 | + | `plugin-sdk/device-bootstrap` | 设备引导和配对 token 辅助函数 | + | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 | + | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助函数 | + | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助函数 | + | `plugin-sdk/native-command-registry` | 原生命令注册表/build/serialize 辅助函数 | + | `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助函数 | + | `plugin-sdk/infra-runtime` | 系统事件/心跳辅助函数 | + | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | + | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和固定查找辅助函数 | + | `plugin-sdk/host-runtime` | 主机名和 SCP 主机归一化辅助函数 | + | `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助函数 | + | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助函数 | | `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | @@ -214,73 +221,73 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/media-runtime` | 共享媒体抓取/转换/存储辅助工具，以及媒体负载构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型提示 | + | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助函数以及媒体负载构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助函数、候选选择和缺失模型提示 | | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本/markdown/日志辅助工具，例如助手可见文本剥离、markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具和安全文本工具 | - | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的指令、注册表和验证辅助工具 | - | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、指令和规范化辅助工具 | - | `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | + | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助函数，例如 assistant 可见文本剥离、Markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 | + | `plugin-sdk/text-chunking` | 出站文本分块辅助函数 | + | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助函数 | + | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和归一化辅助函数 | + | `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助函数 | + | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 | | `plugin-sdk/image-generation` | 图像生成提供商类型 | - | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助工具 | + | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助函数 | | `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | | `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | - | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助工具 | - | `plugin-sdk/webhook-path` | webhook 路径规范化辅助工具 | - | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助工具 | + | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助函数 | + | `plugin-sdk/webhook-path` | webhook 路径归一化辅助函数 | + | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助函数 | | `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于 manager/config/file/CLI 辅助工具 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时门面 | - | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding engine 导出 | - | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 | - | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 | - | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 | - | `plugin-sdk/memory-host-core` | Memory host 核心运行时辅助工具的供应商中立别名 | - | `plugin-sdk/memory-host-events` | Memory host 事件日志辅助工具的供应商中立别名 | - | `plugin-sdk/memory-host-files` | Memory host 文件/运行时辅助工具的供应商中立别名 | - | `plugin-sdk/memory-host-markdown` | 用于 memory 邻接插件的共享托管 markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时门面 | - | `plugin-sdk/memory-host-status` | Memory host 状态辅助工具的供应商中立别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助表面，用于 manager/config/file/CLI 辅助函数 | + | `plugin-sdk/memory-core-engine-runtime` | 内存索引/搜索运行时门面 | + | `plugin-sdk/memory-core-host-engine-foundation` | 内存 host foundation 引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | 内存 host embedding 引擎导出 | + | `plugin-sdk/memory-core-host-engine-qmd` | 内存 host QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | 内存 host storage 引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | 内存 host 多模态辅助函数 | + | `plugin-sdk/memory-core-host-query` | 内存 host 查询辅助函数 | + | `plugin-sdk/memory-core-host-secret` | 内存 host secret 辅助函数 | + | `plugin-sdk/memory-core-host-events` | 内存 host 事件日志辅助函数 | + | `plugin-sdk/memory-core-host-status` | 内存 host 状态辅助函数 | + | `plugin-sdk/memory-core-host-runtime-cli` | 内存 host CLI 运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-core` | 内存 host 核心运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-files` | 内存 host 文件/运行时辅助函数 | + | `plugin-sdk/memory-host-core` | 面向厂商中立的 memory host 核心运行时辅助函数别名 | + | `plugin-sdk/memory-host-events` | 面向厂商中立的内存 host 事件日志辅助函数别名 | + | `plugin-sdk/memory-host-files` | 面向厂商中立的内存 host 文件/运行时辅助函数别名 | + | `plugin-sdk/memory-host-markdown` | 用于内存相邻插件的共享托管 Markdown 辅助函数 | + | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活跃内存运行时门面 | + | `plugin-sdk/memory-host-status` | 面向厂商中立的内存 host 状态辅助函数别名 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助表面 | | 家族 | 当前子路径 | 预期用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置浏览器插件支持辅助工具（`browser-support` 仍是兼容性 barrel） | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时接口 | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时接口 | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 | - | 渠道特定辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助扩展点 | - | 认证/插件特定辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助扩展点；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 browser 插件支持辅助函数（`browser-support` 仍是兼容性 barrel） | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时表面 | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时表面 | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助表面 | + | 特定于渠道的辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助接缝 | + | 认证/插件特定辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | ## 注册 API -`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，包含以下方法： +`register(api)` 回调会收到一个带有以下方法的 `OpenClawPluginApi` 对象： ### 能力注册 -| 方法 | 注册内容 | +| 方法 | 注册的内容 | | ------------------------------------------------ | -------------------------------- | | `api.registerProvider(...)` | 文本推理（LLM） | | `api.registerCliBackend(...)` | 本地 CLI 推理后端 | @@ -292,19 +299,19 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `api.registerImageGenerationProvider(...)` | 图像生成 | | `api.registerMusicGenerationProvider(...)` | 音乐生成 | | `api.registerVideoGenerationProvider(...)` | 视频生成 | -| `api.registerWebFetchProvider(...)` | 网页抓取 / 爬取提供商 | -| `api.registerWebSearchProvider(...)` | 网页搜索 | +| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 | +| `api.registerWebSearchProvider(...)` | Web 搜索 | ### 工具与命令 -| 方法 | 注册内容 | +| 方法 | 注册的内容 | | ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | 智能体工具（必需，或 `{ optional: true }`） | +| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） | | `api.registerCommand(def)` | 自定义命令（绕过 LLM） | ### 基础设施 -| 方法 | 注册内容 | +| 方法 | 注册的内容 | | ---------------------------------------------- | --------------------------------------- | | `api.registerHook(events, handler, opts?)` | 事件 hook | | `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | @@ -312,20 +319,22 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `api.registerCli(registrar, opts?)` | CLI 子命令 | | `api.registerService(service)` | 后台服务 | | `api.registerInteractiveHandler(registration)` | 交互式处理器 | -| `api.registerMemoryPromptSupplement(builder)` | 附加式 memory 邻接提示词部分 | -| `api.registerMemoryCorpusSupplement(adapter)` | 附加式 memory 搜索/读取语料 | +| `api.registerMemoryPromptSupplement(builder)` | 附加型内存相邻提示区段 | +| `api.registerMemoryCorpusSupplement(adapter)` | 附加型内存搜索/读取语料 | 保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、 -`update.*`）始终保持为 `operator.admin`，即使某个插件尝试为 Gateway 网关 方法分配更窄的作用域也是如此。对于插件自有方法，优先使用插件专属前缀。 +`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 +Gateway 网关方法 scope 也是如此。对于插件自有方法，优先使用特定于插件的前缀。 ### CLI 注册元数据 `api.registerCli(registrar, opts?)` 接受两类顶层元数据： -- `commands`：由该 registrar 拥有的显式命令根 -- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析期命令描述符 +- `commands`：由 registrar 拥有的显式命令根 +- `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析期命令描述符 -如果你希望某个插件命令在普通根 CLI 路径中保持延迟加载，请提供 `descriptors`，覆盖该 registrar 暴露的每一个顶层命令根。 +如果你希望插件命令在普通根 CLI 路径中保持惰性加载， +请提供覆盖该 registrar 暴露的每个顶层命令根的 `descriptors`。 ```typescript api.registerCli( @@ -337,7 +346,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Manage Matrix accounts, verification, devices, and profile state", + description: "管理 Matrix 账号、验证、设备和 profile 状态", hasSubcommands: true, }, ], @@ -345,114 +354,126 @@ api.registerCli( ); ``` -仅在你不需要延迟根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍然受支持，但它不会安装基于 descriptor 的占位符来实现解析期延迟加载。 +只有在你不需要惰性根 CLI 注册时，才单独使用 `commands`。 +这种预加载兼容路径仍受支持，但它不会为解析期惰性加载安装基于 +descriptor 的占位符。 ### CLI 后端注册 -`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。 +`api.registerCliBackend(...)` 允许插件拥有本地 +AI CLI 后端（例如 `codex-cli`）的默认配置。 -- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。 +- 后端 `id` 会成为模型引用中像 `codex-cli/gpt-5` 这样的提供商前缀。 - 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的结构。 -- 用户配置仍然优先。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.` 合并覆盖到插件默认值之上。 -- 当某个后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧的 flag 结构）。 +- 用户配置仍然优先。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.` 合并到插件默认值之上。 +- 当某个后端在合并后需要兼容性重写时，请使用 `normalizeConfig` + （例如归一化旧的 flag 结构）。 -### 独占插槽 +### 独占槽位 -| 方法 | 注册内容 | +| 方法 | 注册的内容 | | ------------------------------------------ | ------------------------------------- | -| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只能激活一个） | -| `api.registerMemoryPromptSection(builder)` | Memory 提示词部分构建器 | -| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 | -| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 | +| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个活动实例） | +| `api.registerMemoryPromptSection(builder)` | 内存提示区段构建器 | +| `api.registerMemoryFlushPlan(resolver)` | 内存刷新计划解析器 | +| `api.registerMemoryRuntime(runtime)` | 内存运行时适配器 | -### Memory embedding 适配器 +### 内存嵌入适配器 -| 方法 | 注册内容 | +| 方法 | 注册的内容 | | ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory embedding 适配器 | +| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的内存嵌入适配器 | - `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 - `registerMemoryRuntime` 仅限 Memory 插件使用。 -- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个 embedding 适配器 ID（例如 `openai`、`gemini` 或插件自定义的 ID）。 + `registerMemoryRuntime` 是内存插件的独占能力。 +- `registerMemoryEmbeddingProvider` 允许活动内存插件注册一个 + 或多个嵌入适配器 id（例如 `openai`、`gemini` 或插件自定义 id）。 - 用户配置（例如 `agents.defaults.memorySearch.provider` 和 - `agents.defaults.memorySearch.fallback`）会解析为这些已注册的适配器 ID。 + `agents.defaults.memorySearch.fallback`）会基于这些已注册 + 的适配器 id 进行解析。 ### 事件与生命周期 -| 方法 | 作用 | +| 方法 | 功能 | | -------------------------------------------- | ----------------------------- | | `api.on(hookName, handler, opts?)` | 类型化生命周期 hook | -| `api.onConversationBindingResolved(handler)` | 对话绑定回调 | +| `api.onConversationBindingResolved(handler)` | 会话绑定回调 | -### hook 决策语义 +### Hook 决策语义 -- `before_tool_call`：返回 `{ block: true }` 为终止结果。一旦任一处理器设置它，较低优先级的处理器将被跳过。 -- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 -- `before_install`：返回 `{ block: true }` 为终止结果。一旦任一处理器设置它，较低优先级的处理器将被跳过。 -- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 -- `reply_dispatch`：返回 `{ handled: true, ... }` 为终止结果。一旦任一处理器声明已分发，较低优先级的处理器和默认模型分发路径将被跳过。 -- `message_sending`：返回 `{ cancel: true }` 为终止结果。一旦任一处理器设置它，较低优先级的处理器将被跳过。 -- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。 +- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置该值，较低优先级处理器会被跳过。 +- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（等同于省略 `block`），而不是覆盖。 +- `before_install`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置该值，较低优先级处理器会被跳过。 +- `before_install`：返回 `{ block: false }` 会被视为未作决定（等同于省略 `block`），而不是覆盖。 +- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任意处理器声明已分发，较低优先级处理器和默认模型分发路径都会被跳过。 +- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任意处理器设置该值，较低优先级处理器会被跳过。 +- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（等同于省略 `cancel`），而不是覆盖。 ### API 对象字段 -| 字段 | 类型 | 描述 | +| 字段 | 类型 | 说明 | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | 插件 ID | +| `api.id` | `string` | 插件 id | | `api.name` | `string` | 显示名称 | | `api.version` | `string?` | 插件版本（可选） | | `api.description` | `string?` | 插件描述（可选） | | `api.source` | `string` | 插件源路径 | | `api.rootDir` | `string?` | 插件根目录（可选） | -| `api.config` | `OpenClawConfig` | 当前配置快照（如果可用，则为活动内存中运行时快照） | -| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件特定配置 | -| `api.runtime` | `PluginRuntime` | [插件运行时](/zh-CN/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | 作用域 logger（`debug`, `info`, `warn`, `error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置之前的轻量窗口 | +| `api.config` | `OpenClawConfig` | 当前配置快照（如可用，则为活动内存运行时快照） | +| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件专用配置 | +| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | 有作用域的 logger（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口前的轻量启动/设置窗口 | | `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | ## 内部模块约定 -在你的插件内部，使用本地 barrel 文件进行内部导入： +在你的插件内部，请使用本地 barrel 文件进行内部导入： ``` my-plugin/ - api.ts # 供外部使用方使用的公共导出 - runtime-api.ts # 仅供内部使用的运行时导出 + api.ts # 面向外部使用方的公共导出 + runtime-api.ts # 仅内部使用的运行时导出 index.ts # 插件入口点 setup-entry.ts # 仅设置用的轻量入口（可选） ``` - 不要在生产代码中通过 `openclaw/plugin-sdk/` + 绝不要在生产代码中通过 `openclaw/plugin-sdk/` 导入你自己的插件。内部导入应通过 `./api.ts` 或 - `./runtime-api.ts` 进行。SDK 路径仅是对外契约。 + `./runtime-api.ts`。SDK 路径仅是对外契约。 -通过门面加载的内置插件公共接口（`api.ts`、`runtime-api.ts`、 -`index.ts`、`setup-entry.ts` 以及类似公共入口文件）现在会在 OpenClaw 已经运行时优先使用活动运行时配置快照。如果尚不存在运行时快照，它们会回退到磁盘上的已解析配置文件。 +通过门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、 +`index.ts`、`setup-entry.ts` 以及类似公共入口文件）现在会在 +OpenClaw 已经运行时优先使用活动运行时配置快照。 +如果运行时快照尚不存在，它们会回退到磁盘上解析得到的配置文件。 -当某个辅助工具刻意属于提供商特定内容，且尚不适合放入通用 SDK 子路径时，提供商插件也可以暴露一个狭义的插件本地契约 barrel。当前内置示例：Anthropic 提供商将它的 Claude 流辅助工具保留在自己的公共 `api.ts` / `contract-api.ts` 接口中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升为通用 `plugin-sdk/*` 契约。 +当某个辅助函数明确是提供商特定、且暂时还不属于通用 SDK +子路径时，提供商插件也可以暴露一个窄范围的插件本地契约 barrel。 +当前内置示例：Anthropic 提供商将其 Claude +流辅助函数保留在自己的公共 `api.ts` / `contract-api.ts` 接缝中，而不是把 Anthropic beta-header 和 `service_tier` 逻辑提升到通用 +`plugin-sdk/*` 契约中。 其他当前内置示例： - `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、 - 默认模型辅助工具和实时提供商构建器 + 默认模型辅助函数和实时提供商构建器 - `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及 - 新手引导/配置辅助工具 + 新手引导/配置辅助函数 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。 - 如果某个辅助工具确实是共享的，请将其提升到中立的 SDK 子路径， + 如果某个辅助函数确实需要共享，请将其提升到中立的 SDK 子路径， 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他 - 面向能力的接口，而不是让两个插件彼此耦合。 + 面向能力的表面，而不是将两个插件耦合在一起。 ## 相关内容 - [入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` 选项 -- [插件运行时](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考 +- [运行时](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考 - [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema - [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则 -- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用接口迁移 -- [插件内部机制](/zh-CN/plugins/architecture) — 深入的架构和能力模型 +- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移 +- [插件内部机制](/zh-CN/plugins/architecture) — 深度架构和能力模型 diff --git a/docs/zh-CN/plugins/sdk-provider-plugins.md b/docs/zh-CN/plugins/sdk-provider-plugins.md index a5f1a03b8..f6789d50c 100644 --- a/docs/zh-CN/plugins/sdk-provider-plugins.md +++ b/docs/zh-CN/plugins/sdk-provider-plugins.md @@ -1,33 +1,31 @@ --- read_when: - - 你正在构建一个新的模型提供商插件 - - 你想为 OpenClaw 添加一个兼容 OpenAI 的代理或自定义 LLM - - 你需要了解提供商认证、目录和运行时 hooks + - 你正在构建一个新的模型 provider 插件 + - 你想为 OpenClaw 添加一个与 OpenAI 兼容的代理或自定义 LLM + - 你需要了解 provider 身份验证、目录和运行时 hooks sidebarTitle: Provider Plugins -summary: 在 OpenClaw 中构建模型提供商插件的分步指南 +summary: 构建 OpenClaw 模型 provider 插件的分步指南 title: 构建提供商插件 x-i18n: - generated_at: "2026-04-06T12:45:00Z" + generated_at: "2026-04-06T15:30:57Z" model: gpt-5.4 provider: openai - source_hash: 89e7402742c87cb31265db1d98b34ca17ba57ad1c61952fa8c7da834306986f5 + source_hash: 4da82a353e1bf4fe6dc09e14b8614133ac96565679627de51415926014bd3990 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # 构建提供商插件 -本指南将带你构建一个提供商插件，为 OpenClaw 添加一个模型提供商 -（LLM）。完成后，你将拥有一个具备模型目录、 -API 密钥认证和动态模型解析能力的提供商。 +本指南将带你构建一个 provider 插件，为 OpenClaw 添加一个模型 provider +（LLM）。完成后，你将拥有一个具备模型目录、API 密钥身份验证和动态模型解析的 provider。 如果你之前从未构建过任何 OpenClaw 插件，请先阅读 - [入门指南](/zh-CN/plugins/building-plugins) 了解基本包 - 结构和清单设置。 + [入门指南](/zh-CN/plugins/building-plugins) 以了解基本包结构和清单设置。 -## 操作演练 +## 演练 @@ -86,18 +84,12 @@ API 密钥认证和动态模型解析能力的提供商。 ``` - 清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测 - 凭证。`modelSupport` 是可选的， - 它让 OpenClaw 能够在运行时 hooks 存在之前，从像 - `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你在 - ClawHub 上发布该提供商，那么 `package.json` 中的 - `openclaw.compat` 和 `openclaw.build` 字段 - 是必需的。 + 清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测凭证。`modelSupport` 是可选的，它允许 OpenClaw 在运行时 hooks 存在之前，就根据像 `acme-large` 这样的简写模型 id 自动加载你的 provider 插件。如果你要在 ClawHub 上发布 provider，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必需的。 - - 一个最小可用的提供商需要 `id`、`label`、`auth` 和 `catalog`： + + 一个最小可用的 provider 需要 `id`、`label`、`auth` 和 `catalog`： ```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -168,13 +160,12 @@ API 密钥认证和动态模型解析能力的提供商。 }); ``` - 这样就是一个可工作的提供商。用户现在可以 + 这就是一个可工作的 provider。用户现在可以 `openclaw onboard --acme-ai-api-key ` 并选择 `acme-ai/acme-large` 作为他们的模型。 - 对于只注册一个文本提供商、使用 API 密钥 - 认证且只有单个基于目录的运行时的内置提供商，优先使用更窄的 - `defineSingleProviderPluginEntry(...)` 帮助器： + 对于只注册一个文本 provider、使用 API 密钥身份验证并带有单个目录支持运行时的内置 provider，优先使用更窄的 + `defineSingleProviderPluginEntry(...)` 辅助函数： ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -209,28 +200,23 @@ API 密钥认证和动态模型解析能力的提供商。 }); ``` - 如果你的认证流程在新手引导期间还需要修补 `models.providers.*`、别名以及 - 智能体默认模型，请使用 - `openclaw/plugin-sdk/provider-onboard` 中的 preset 帮助器。最窄的帮助器是 + 如果你的身份验证流程在新手引导期间还需要修补 `models.providers.*`、别名以及智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数是 `createDefaultModelPresetAppliers(...)`、 `createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。 - 当某个提供商的原生端点在普通 - `openai-completions` 传输上支持分块流式传输 usage blocks 时，优先使用 - `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录帮助器，而不是硬编码 - provider-id 检查。`supportsNativeStreamingUsageCompat(...)` 和 - `applyProviderNativeStreamingUsageCompat(...)` 会从端点 capability 映射中检测支持情况，因此即使插件使用自定义 provider id，原生 Moonshot/DashScope 风格的端点仍可选择启用。 + 当 provider 的原生端点在常规 `openai-completions` 传输上支持流式 usage 块时，优先使用 + `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码 provider-id 检查。`supportsNativeStreamingUsageCompat(...)` 和 + `applyProviderNativeStreamingUsageCompat(...)` 会从端点能力映射中检测支持情况，因此即使插件使用的是自定义 provider id，原生 Moonshot/DashScope 风格端点也仍然可以选择接入。 - 如果你的提供商接受任意模型 ID（例如代理或路由器）， - 请添加 `resolveDynamicModel`： + 如果你的 provider 接受任意模型 ID（例如代理或路由器），请添加 `resolveDynamicModel`： ```typescript api.registerProvider({ - // ... id, label, auth, catalog from above + // ... 上面的 id、label、auth、catalog resolveDynamicModel: (ctx) => ({ id: ctx.modelId, @@ -247,17 +233,15 @@ API 密钥认证和动态模型解析能力的提供商。 }); ``` - 如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步 - 预热 —— 完成后会再次运行 `resolveDynamicModel`。 + 如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热——在它完成后，`resolveDynamicModel` 会再次运行。 - - 大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商需求增加， - 再逐步添加 hooks。 + + 大多数 provider 只需要 `catalog` + `resolveDynamicModel`。根据你的 provider 需求逐步添加 hooks。 - 共享帮助器构建器现在已经覆盖最常见的 replay/tool-compat - 系列，因此插件通常不需要手动逐个接线每个 hook： + 共享辅助构建器现在已经覆盖了最常见的 replay/tool-compat + 家族，因此插件通常不需要再逐个手工接线每个 hook： ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -277,15 +261,15 @@ API 密钥认证和动态模型解析能力的提供商。 }); ``` - 当前可用的 replay families： + 当前可用的 replay 家族： - | Family | 它会接入什么 | + | Family | 接入内容 | | --- | --- | - | `openai-compatible` | 面向 OpenAI 兼容传输的共享 OpenAI 风格 replay 策略，包括 tool-call-id 清理、assistant-first 顺序修复，以及在传输需要时启用通用 Gemini turn 验证 | - | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知 replay 策略，因此 Anthropic-message 传输仅在解析后的模型实际是 Claude id 时才会获得 Claude 特定的 thinking-block 清理 | + | `openai-compatible` | 面向与 OpenAI 兼容传输的共享 OpenAI 风格 replay 策略，包括 tool-call-id 清理、assistant 优先顺序修正，以及在传输需要时的通用 Gemini 轮次校验 | + | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知 replay 策略，因此 Anthropic-message 传输只有在解析出的模型实际是 Claude id 时，才会获得 Claude 专属的 thinking 块清理 | | `google-gemini` | 原生 Gemini replay 策略，加上 bootstrap replay 清理和带标签的 reasoning-output 模式 | - | `passthrough-gemini` | 针对通过 OpenAI 兼容代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini replay 验证或 bootstrap 重写 | - | `hybrid-anthropic-openai` | 适用于在一个插件中混合 Anthropic-message 和 OpenAI 兼容模型面的提供商的混合策略；可选的仅 Claude thinking-block 丢弃仍然限定在 Anthropic 一侧 | + | `passthrough-gemini` | 针对通过与 OpenAI 兼容代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini replay 校验或 bootstrap 重写 | + | `hybrid-anthropic-openai` | 适用于在单个插件中混合 Anthropic-message 和与 OpenAI 兼容模型表面的 provider 的混合策略；可选的仅 Claude thinking-block 丢弃仍然限定在 Anthropic 一侧 | 真实的内置示例： @@ -295,17 +279,17 @@ API 密钥认证和动态模型解析能力的提供商。 - `minimax`：`hybrid-anthropic-openai` - `moonshot`、`ollama`、`xai` 和 `zai`：`openai-compatible` - 当前可用的 stream families： + 当前可用的流式家族： - | Family | 它会接入什么 | + | Family | 接入内容 | | --- | --- | - | `google-thinking` | 共享流路径上的 Gemini thinking 负载规范化 | - | `kilocode-thinking` | 共享代理流路径上的 Kilo reasoning 包装器，其中 `kilo/auto` 和不受支持的代理 reasoning id 会跳过注入的 thinking | - | `moonshot-thinking` | 根据配置 + `/think` 级别进行 Moonshot 二进制原生 thinking 负载映射 | + | `google-thinking` | 共享流路径上的 Gemini thinking 负载标准化 | + | `kilocode-thinking` | 共享代理流路径上的 Kilo reasoning 包装器，其中 `kilo/auto` 和不支持的代理 reasoning id 会跳过注入的 thinking | + | `moonshot-thinking` | 基于配置和 `/think` 级别的 Moonshot 二进制原生 thinking 负载映射 | | `minimax-fast-mode` | 共享流路径上的 MiniMax fast-mode 模型重写 | - | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归因头、`/fast`/`serviceTier`、文本详细程度、原生 Codex web search、reasoning-compat 负载整形，以及 Responses 上下文管理 | - | `openrouter-thinking` | 面向代理路由的 OpenRouter reasoning 包装器，并由中心统一处理不支持的模型/`auto` 跳过 | - | `tool-stream-default-on` | 对于像 Z.AI 这类希望默认启用工具流式传输的提供商，在未显式禁用时默认开启 `tool_stream` 的包装器 | + | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归属标头、`/fast`/`serviceTier`、文本详细度、原生 Codex Web 搜索、reasoning 兼容负载整形，以及 Responses 上下文管理 | + | `openrouter-thinking` | 面向代理路由的 OpenRouter reasoning 包装器，其中不支持模型/`auto` 跳过由中心统一处理 | + | `tool-stream-default-on` | 针对像 Z.AI 这类 provider 的默认开启 `tool_stream` 包装器，除非显式禁用 | 真实的内置示例： @@ -317,8 +301,8 @@ API 密钥认证和动态模型解析能力的提供商。 - `openrouter`：`openrouter-thinking` - `zai`：`tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared` 还会导出 replay-family - 枚举，以及这些 family 所构建于其上的共享帮助器。常见公开导出包括： + `openclaw/plugin-sdk/provider-model-shared` 还导出了 replay-family + 枚举，以及这些家族构建所复用的共享辅助函数。常见公共导出包括： - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` @@ -326,14 +310,13 @@ API 密钥认证和动态模型解析能力的提供商。 `buildAnthropicReplayPolicyForModel(...)`、 `buildGoogleGeminiReplayPolicy(...)` 和 `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - - Gemini replay 帮助器，例如 `sanitizeGoogleGeminiReplayHistory(...)` + - Gemini replay 辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)` 和 `resolveTaggedReasoningOutputMode()` - - 端点/模型帮助器，例如 `resolveProviderEndpoint(...)`、 + - 端点/模型辅助函数，例如 `resolveProviderEndpoint(...)`、 `normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)` 和 `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` 同时公开 family 构建器以及这些 family 复用的公共包装器帮助器。常见公开导出 - 包括： + `openclaw/plugin-sdk/provider-stream` 同时暴露家族构建器和这些家族复用的公共包装辅助函数。常见公共导出包括： - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` @@ -344,49 +327,44 @@ API 密钥认证和动态模型解析能力的提供商。 `createOpenAIServiceTierWrapper(...)`、 `createOpenAIResponsesContextManagementWrapper(...)` 和 `createCodexNativeWebSearchWrapper(...)` - - 共享代理/提供商包装器，例如 `createOpenRouterWrapper(...)`、 + - 共享代理/provider 包装器，例如 `createOpenRouterWrapper(...)`、 `createToolStreamWrapper(...)` 和 `createMinimaxFastModeWrapper(...)` - 一些 stream 帮助器会有意保持为 provider-local。当前内置 + 某些流式辅助函数会有意保留为 provider 本地。当前内置 示例：`@openclaw/anthropic-provider` 从其公共 `api.ts` / - `contract-api.ts` 接缝导出 + `contract-api.ts` 接缝中导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 - `resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及更底层的 Anthropic 包装器构建器。 - 这些帮助器仍保持 Anthropic 特定，因为 - 它们还编码了 Claude OAuth beta 处理和 `context1m` gating。 + `resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 Anthropic 包装器构建器。这些辅助函数仍然保持 Anthropic 专属，因为它们还编码了 Claude OAuth beta 处理和 `context1m` gating。 - 其他内置提供商也会在行为无法跨 family 清晰共享时，将 - transport-specific 包装器保留在本地。当前示例：内置 xAI 插件将原生 xAI Responses 整形保留在其自己的 + 其他内置 provider 也会在行为无法在家族间干净共享时，将传输专属包装器保留为本地。当前示例：内置 xAI 插件将原生 xAI Responses 整形保留在自己的 `wrapStreamFn` 中，包括 `/fast` 别名重写、默认 `tool_stream`、 - 不支持的 strict-tool 清理，以及 xAI 特有的 reasoning-payload - 移除。 + 不支持的 strict-tool 清理，以及 xAI 专属 reasoning 负载移除。 - `openclaw/plugin-sdk/provider-tools` 当前公开一个共享 - tool-schema family 以及共享 schema/compat 帮助器： + `openclaw/plugin-sdk/provider-tools` 当前暴露一个共享 + tool-schema 家族，以及共享的 schema/compat 辅助函数： - - `ProviderToolCompatFamily` 记录了当前共享 family 清单。 - - `buildProviderToolCompatFamilyHooks("gemini")` 会为需要 Gemini 安全工具 schema 的提供商接入 Gemini schema - 清理 + 诊断。 + - `ProviderToolCompatFamily` 记录当前共享家族清单。 + - `buildProviderToolCompatFamilyHooks("gemini")` 为需要 Gemini 安全工具 schema 的 provider 接入 Gemini schema 清理 + 诊断。 - `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` - 是底层的公共 Gemini schema 帮助器。 - - `resolveXaiModelCompatPatch()` 返回内置 xAI compat patch： + 是底层公开的 Gemini schema 辅助函数。 + - `resolveXaiModelCompatPatch()` 返回内置 xAI compat 补丁： `toolSchemaProfile: "xai"`、不支持的 schema 关键字、原生 `web_search` 支持，以及 HTML 实体 tool-call 参数解码。 - - `applyXaiModelCompat(model)` 会在解析后的模型进入 runner 之前，对其应用同样的 xAI compat patch。 + - `applyXaiModelCompat(model)` 会在模型进入运行器前，将同一份 xAI compat 补丁应用到已解析模型上。 真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加上 - `contributeResolvedModelCompat`，使 compat 元数据归提供商所有，而不是在 core 中硬编码 xAI 规则。 + `contributeResolvedModelCompat`，以保持该 compat 元数据由 provider 自己拥有，而不是在核心中硬编码 xAI 规则。 - 同样的 package-root 模式也支持其他内置提供商： + 同样的包根模式也支撑其他内置 provider： - - `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、 - 默认模型帮助器和实时提供商构建器 - - `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器 - 以及 onboarding/配置帮助器 + - `@openclaw/openai-provider`：`api.ts` 导出 provider 构建器、 + 默认模型辅助函数和 realtime provider 构建器 + - `@openclaw/openrouter-provider`：`api.ts` 导出 provider 构建器 + 以及新手引导/配置辅助函数 - 对于需要在每次推理调用前执行令牌交换的提供商： + 对于需要在每次推理调用前进行令牌交换的 provider： ```typescript prepareRuntimeAuth: async (ctx) => { @@ -399,8 +377,8 @@ API 密钥认证和动态模型解析能力的提供商。 }, ``` - - 对于需要自定义请求头或请求体修改的提供商： + + 对于需要自定义请求标头或请求体修改的 provider： ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -417,8 +395,8 @@ API 密钥认证和动态模型解析能力的提供商。 }, ``` - - 对于在通用 HTTP 或 WebSocket 传输上需要原生请求/会话头或元数据的提供商： + + 对于需要在通用 HTTP 或 WebSocket 传输上附加原生请求/会话标头或元数据的 provider： ```typescript resolveTransportTurnState: (ctx) => ({ @@ -438,8 +416,8 @@ API 密钥认证和动态模型解析能力的提供商。 }), ``` - - 对于暴露 usage/计费数据的提供商： + + 对于暴露用量/计费数据的 provider： ```typescript resolveUsageAuth: async (ctx) => { @@ -453,85 +431,81 @@ API 密钥认证和动态模型解析能力的提供商。 - - OpenClaw 会按以下顺序调用 hooks。大多数提供商只会使用 2-3 个： + + OpenClaw 按以下顺序调用 hooks。大多数 provider 只会使用 2-3 个： - | # | Hook | 何时使用 | + | # | Hook | 使用时机 | | --- | --- | --- | - | 1 | `catalog` | 模型目录或默认 `baseUrl` | - | 2 | `applyConfigDefaults` | 配置物化期间由提供商拥有的全局默认值 | - | 3 | `normalizeModelId` | 查找前对旧版/预览模型 id 别名进行清理 | - | 4 | `normalizeTransport` | 通用模型组装前，对 provider-family 的 `api` / `baseUrl` 进行清理 | - | 5 | `normalizeConfig` | 规范化 `models.providers.` 配置 | - | 6 | `applyNativeStreamingUsageCompat` | 对配置提供商执行原生流式 usage compat 重写 | - | 7 | `resolveConfigApiKey` | 由提供商拥有的环境标记认证解析 | - | 8 | `resolveSyntheticAuth` | 本地/自托管或基于配置的 synthetic auth | - | 9 | `shouldDeferSyntheticProfileAuth` | 将 synthetic 存储配置文件占位符降级到 env/config auth 之后 | + | 1 | `catalog` | 模型目录或 base URL 默认值 | + | 2 | `applyConfigDefaults` | 在配置实体化期间应用 provider 自有的全局默认值 | + | 3 | `normalizeModelId` | 在查找前清理旧版/预览版模型 id 别名 | + | 4 | `normalizeTransport` | 在通用模型组装前清理 provider-family 的 `api` / `baseUrl` | + | 5 | `normalizeConfig` | 标准化 `models.providers.` 配置 | + | 6 | `applyNativeStreamingUsageCompat` | 面向配置 provider 的原生流式 usage compat 重写 | + | 7 | `resolveConfigApiKey` | provider 自有的环境变量标记身份验证解析 | + | 8 | `resolveSyntheticAuth` | 本地/自托管或配置支持的 synthetic auth | + | 9 | `shouldDeferSyntheticProfileAuth` | 将 synthetic 的已存储 profile 占位符降到 env/config auth 之后 | | 10 | `resolveDynamicModel` | 接受任意上游模型 ID | - | 11 | `prepareDynamicModel` | 解析前异步获取元数据 | - | 12 | `normalizeResolvedModel` | runner 之前的传输重写 | + | 11 | `prepareDynamicModel` | 在解析前异步获取元数据 | + | 12 | `normalizeResolvedModel` | 在运行器前进行传输重写 | - 运行时回退说明： + 运行时回退说明： - - `normalizeConfig` 会先检查匹配的提供商，然后检查其他 - 具备 hook 能力的提供商插件，直到其中某个插件实际更改配置。 - 如果没有任何提供商 hook 重写受支持的 Google-family 配置条目， - 内置 Google 配置规范化仍会应用。 - - `resolveConfigApiKey` 会在公开时使用提供商 hook。内置 - `amazon-bedrock` 路径在这里也有内建的 AWS 环境标记解析器， - 尽管 Bedrock 运行时认证本身仍使用 AWS SDK 默认 - 链。 - | 13 | `contributeResolvedModelCompat` | 为另一个兼容传输背后的厂商模型提供 compat 标志 | - | 14 | `capabilities` | 旧版静态 capability 包；仅为兼容性保留 | - | 15 | `normalizeToolSchemas` | 注册前由提供商拥有的工具 schema 清理 | - | 16 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 | - | 17 | `resolveReasoningOutputMode` | 带标签与原生 reasoning-output 契约 | + - `normalizeConfig` 会先检查匹配的 provider，然后再检查其他 + 具备 hook 能力的 provider 插件，直到其中一个实际修改了配置。 + 如果没有任何 provider hook 重写受支持的 Google-family 配置条目， + 则仍会应用内置 Google 配置标准化器。 + - `resolveConfigApiKey` 在暴露该 hook 时会使用 provider hook。内置的 + `amazon-bedrock` 路径在这里也有一个内建 AWS 环境变量标记解析器， + 即便 Bedrock 运行时身份验证本身仍然使用 AWS SDK 默认链。 + | 13 | `contributeResolvedModelCompat` | 面向运行在另一种兼容传输后的厂商模型的 compat 标志 | + | 14 | `capabilities` | 旧版静态能力包；仅为兼容性保留 | + | 15 | `normalizeToolSchemas` | 在注册前由 provider 自有进行工具 schema 清理 | + | 16 | `inspectToolSchemas` | 由 provider 自有进行工具 schema 诊断 | + | 17 | `resolveReasoningOutputMode` | 带标签与原生 reasoning-output 合约 | | 18 | `prepareExtraParams` | 默认请求参数 | - | 19 | `createStreamFn` | 完全自定义的 `StreamFn` 传输 | - | 20 | `wrapStreamFn` | 普通流路径上的自定义头/请求体包装器 | - | 21 | `resolveTransportTurnState` | 原生逐轮请求头/元数据 | - | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话头/冷却时间 | + | 19 | `createStreamFn` | 完全自定义的 StreamFn 传输 | + | 20 | `wrapStreamFn` | 常规流路径上的自定义标头/请求体包装器 | + | 21 | `resolveTransportTurnState` | 原生逐轮标头/元数据 | + | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话标头/冷却策略 | | 23 | `formatApiKey` | 自定义运行时令牌形态 | | 24 | `refreshOAuth` | 自定义 OAuth 刷新 | - | 25 | `buildAuthDoctorHint` | 认证修复指导 | - | 26 | `matchesContextOverflowError` | 由提供商拥有的溢出检测 | - | 27 | `classifyFailoverReason` | 由提供商拥有的限流/过载分类 | - | 28 | `isCacheTtlEligible` | 提示缓存 TTL 门控 | - | 29 | `buildMissingAuthMessage` | 自定义缺失认证提示 | - | 30 | `suppressBuiltInModel` | 隐藏过时的上游行 | - | 31 | `augmentModelCatalog` | synthetic 前向兼容行 | + | 25 | `buildAuthDoctorHint` | 身份验证修复指引 | + | 26 | `matchesContextOverflowError` | provider 自有的上下文溢出检测 | + | 27 | `classifyFailoverReason` | provider 自有的速率限制/过载分类 | + | 28 | `isCacheTtlEligible` | 提示词缓存 TTL gating | + | 29 | `buildMissingAuthMessage` | 自定义缺失身份验证提示 | + | 30 | `suppressBuiltInModel` | 隐藏过时的上游条目 | + | 31 | `augmentModelCatalog` | synthetic 前向兼容条目 | | 32 | `isBinaryThinking` | 二进制 thinking 开/关 | | 33 | `supportsXHighThinking` | `xhigh` reasoning 支持 | | 34 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略 | | 35 | `isModernModelRef` | 实时/smoke 模型匹配 | - | 36 | `prepareRuntimeAuth` | 推理前令牌交换 | - | 37 | `resolveUsageAuth` | 自定义 usage 凭证解析 | - | 38 | `fetchUsageSnapshot` | 自定义 usage 端点 | - | 39 | `createEmbeddingProvider` | 用于内存/搜索的由提供商拥有的嵌入适配器 | + | 36 | `prepareRuntimeAuth` | 推理前的令牌交换 | + | 37 | `resolveUsageAuth` | 自定义用量凭证解析 | + | 38 | `fetchUsageSnapshot` | 自定义用量端点 | + | 39 | `createEmbeddingProvider` | 面向 memory/search 的 provider 自有嵌入适配器 | | 40 | `buildReplayPolicy` | 自定义转录 replay/压缩策略 | - | 41 | `sanitizeReplayHistory` | 通用清理之后的 provider-specific replay 重写 | - | 42 | `validateReplayTurns` | 嵌入 runner 之前的严格 replay-turn 验证 | - | 43 | `onModelSelected` | 选择后的回调（例如遥测） | + | 41 | `sanitizeReplayHistory` | 通用清理后的 provider 专属 replay 重写 | + | 42 | `validateReplayTurns` | 嵌入式运行器前的严格 replay 轮次校验 | + | 43 | `onModelSelected` | 选择模型后的回调（例如遥测） | 提示词调优说明： - - `resolveSystemPromptContribution` 允许提供商为某个模型 family 注入缓存感知的 - system-prompt 指导。对于属于某个提供商/模型 - family 且应保留稳定/动态缓存拆分的行为， - 优先使用它，而不是 + - `resolveSystemPromptContribution` 允许 provider 为某个模型家族注入缓存感知的系统提示词指导。对于属于某个 provider/模型家族并且应该保留稳定/动态缓存拆分的行为，优先使用它，而不是 `before_prompt_build`。 - 关于详细说明和真实示例，请参见 - [内部机制：提供商运行时 hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。 + 有关详细说明和真实示例，请参见 + [内部机制：提供商运行时 Hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。 - 提供商插件除了文本推理之外，还可以注册语音、实时转录、实时 - 语音、媒体理解、图像生成、视频生成、网页抓取 - 和网页搜索： + provider 插件除了文本推理外，还可以注册 speech、realtime transcription、realtime + voice、media understanding、image generation、video generation、web fetch + 和 web search： ```typescript register(api) { @@ -639,15 +613,16 @@ API 密钥认证和动态模型解析能力的提供商。 } ``` - OpenClaw 会将其归类为**混合能力**插件。这是 - 公司级插件（每个厂商一个插件）的推荐模式。参见 + OpenClaw 会将其归类为**混合能力**插件。这是公司级插件（每个厂商一个插件）的推荐模式。参见 [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。 - 对于视频生成，优先使用上面展示的感知模式 capability 结构： - `generate`、`imageToVideo` 和 `videoToVideo`。较旧的扁平字段，如 - `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` 仍可作为聚合回退上限使用， - 但它们无法同样清晰地描述每种模式的限制或 - 被禁用的转换模式。 + 对于视频生成，优先使用上面展示的模式感知能力形态： + `generate`、`imageToVideo` 和 `videoToVideo`。像 + `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` 这样的扁平聚合字段，不足以干净地表达变换模式支持或已禁用模式。 + + 音乐生成 provider 也应遵循同样的模式： + `generate` 用于仅提示词生成，`edit` 用于基于参考图像的生成。像 `maxInputImages`、 + `supportsLyrics` 和 `supportsFormat` 这样的扁平聚合字段，不足以表达 edit 支持；显式的 `generate` / `edit` 块才是预期合约。 @@ -655,7 +630,7 @@ API 密钥认证和动态模型解析能力的提供商。 ```typescript src/provider.test.ts import { describe, it, expect } from "vitest"; - // Export your provider config object from index.ts or a dedicated file + // 从 index.ts 或单独文件导出你的 provider 配置对象 import { acmeProvider } from "./provider.js"; describe("acme-ai provider", () => { @@ -688,7 +663,7 @@ API 密钥认证和动态模型解析能力的提供商。 ## 发布到 ClawHub -提供商插件的发布方式与任何其他外部代码插件相同： +Provider 插件的发布方式与任何其他外部代码插件相同： ```bash clawhub package publish your-org/your-plugin --dry-run @@ -707,24 +682,23 @@ clawhub package publish your-org/your-plugin ├── index.ts # definePluginEntry + registerProvider └── src/ ├── provider.test.ts # 测试 - └── usage.ts # Usage 端点（可选） + └── usage.ts # 用量端点（可选） ``` ## 目录顺序参考 -`catalog.order` 控制你的目录相对于内置 -提供商何时合并： +`catalog.order` 控制你的目录相对于内置 provider 的合并时机： -| Order | 时机 | 使用场景 | +| Order | 时机 | 使用场景 | | --------- | ------------- | ----------------------------------------------- | -| `simple` | 第一轮 | 纯 API 密钥提供商 | -| `profile` | 在 simple 之后 | 受 auth profiles 控制的提供商 | +| `simple` | 第一轮 | 纯 API 密钥 provider | +| `profile` | 在 simple 之后 | 由 auth profile 控制的 provider | | `paired` | 在 profile 之后 | 合成多个相关条目 | -| `late` | 最后一轮 | 覆盖现有提供商（冲突时胜出） | +| `late` | 最后一轮 | 覆盖现有 provider（冲突时胜出） | ## 后续步骤 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 如果你的插件还提供一个渠道 -- [插件运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 帮助器（TTS、搜索、subagent） +- [插件运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、子智能体） - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 - [插件内部机制](/zh-CN/plugins/architecture#provider-runtime-hooks) — hook 细节和内置示例 diff --git a/docs/zh-CN/plugins/webhooks.md b/docs/zh-CN/plugins/webhooks.md new file mode 100644 index 000000000..e58227607 --- /dev/null +++ b/docs/zh-CN/plugins/webhooks.md @@ -0,0 +1,194 @@ +--- +read_when: + - 你希望从外部系统触发或驱动 TaskFlows + - 你正在配置内置的 Webhooks 插件 +summary: Webhooks 插件：面向受信任外部自动化的已认证 TaskFlow 入口 +title: Webhooks 插件 +x-i18n: + generated_at: "2026-04-06T15:30:37Z" + model: gpt-5.4 + provider: openai + source_hash: a5da12a887752ec6ee853cfdb912db0ae28512a0ffed06fe3828ef2eee15bc9d + source_path: plugins/webhooks.md + workflow: 15 +--- + +# Webhooks（插件） + +Webhooks 插件会添加已认证的 HTTP 路由，将外部自动化绑定到 OpenClaw TaskFlows。 + +当你希望让一个受信任的系统，例如 Zapier、n8n、CI 作业或内部服务，在不先编写自定义插件的情况下创建并驱动受管 TaskFlows 时，请使用它。 + +## 运行位置 + +Webhooks 插件运行在 Gateway 网关进程内。 + +如果你的 Gateway 网关运行在另一台机器上，请在该 Gateway 网关主机上安装并配置此插件，然后重启 Gateway 网关。 + +## 配置路由 + +在 `plugins.entries.webhooks.config` 下设置配置： + +```json5 +{ + plugins: { + entries: { + webhooks: { + enabled: true, + config: { + routes: { + zapier: { + path: "/plugins/webhooks/zapier", + sessionKey: "agent:main:main", + secret: { + source: "env", + provider: "default", + id: "OPENCLAW_WEBHOOK_SECRET", + }, + controllerId: "webhooks/zapier", + description: "Zapier TaskFlow bridge", + }, + }, + }, + }, + }, + }, +} +``` + +路由字段： + +- `enabled`：可选，默认为 `true` +- `path`：可选，默认为 `/plugins/webhooks/` +- `sessionKey`：必填，拥有绑定 TaskFlows 的会话 +- `secret`：必填，共享密钥或 SecretRef +- `controllerId`：可选，用于已创建受管流程的 controller id +- `description`：可选，供操作员使用的备注 + +支持的 `secret` 输入： + +- 纯字符串 +- 带 `source: "env" | "file" | "exec"` 的 SecretRef + +如果某个基于 secret 的路由在启动时无法解析其 secret，插件会跳过该路由，并记录一条警告，而不是暴露一个损坏的端点。 + +## 安全模型 + +每条路由都被信任为能够使用其配置的 `sessionKey` 所拥有的 TaskFlow 权限进行操作。 + +这意味着该路由可以检查和修改该会话拥有的 TaskFlows，因此你应该： + +- 为每条路由使用强且唯一的密钥 +- 优先使用 secret 引用，而不是内联明文密钥 +- 将路由绑定到最适合该工作流的最小会话范围 +- 只暴露你需要的特定 webhook 路径 + +该插件会应用： + +- 共享密钥认证 +- 请求体大小和超时保护 +- 固定窗口限流 +- 进行中请求数量限制 +- 通过 `api.runtime.taskFlow.bindSession(...)` 实现按所有者绑定的 TaskFlow 访问 + +## 请求格式 + +发送 `POST` 请求时使用： + +- `Content-Type: application/json` +- `Authorization: Bearer ` 或 `x-openclaw-webhook-secret: ` + +示例： + +```bash +curl -X POST https://gateway.example.com/plugins/webhooks/zapier \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer YOUR_SHARED_SECRET' \ + -d '{"action":"create_flow","goal":"Review inbound queue"}' +``` + +## 支持的操作 + +该插件当前接受以下 JSON `action` 值： + +- `create_flow` +- `get_flow` +- `list_flows` +- `find_latest_flow` +- `resolve_flow` +- `get_task_summary` +- `set_waiting` +- `resume_flow` +- `finish_flow` +- `fail_flow` +- `request_cancel` +- `cancel_flow` +- `run_task` + +### `create_flow` + +为该路由绑定的会话创建一个受管 TaskFlow。 + +示例： + +```json +{ + "action": "create_flow", + "goal": "Review inbound queue", + "status": "queued", + "notifyPolicy": "done_only" +} +``` + +### `run_task` + +在现有受管 TaskFlow 内创建一个受管子任务。 + +允许的运行时有： + +- `subagent` +- `acp` + +示例： + +```json +{ + "action": "run_task", + "flowId": "flow_123", + "runtime": "acp", + "childSessionKey": "agent:main:acp:worker", + "task": "Inspect the next message batch" +} +``` + +## 响应结构 + +成功响应返回： + +```json +{ + "ok": true, + "routeId": "zapier", + "result": {} +} +``` + +被拒绝的请求返回： + +```json +{ + "ok": false, + "routeId": "zapier", + "code": "not_found", + "error": "TaskFlow not found.", + "result": {} +} +``` + +该插件会有意从 webhook 响应中清除 owner/session 元数据。 + +## 相关文档 + +- [插件运行时 SDK](/zh-CN/plugins/sdk-runtime) +- [Hooks 和 Webhooks 概览](/zh-CN/automation/hooks) +- [CLI Webhooks](/cli/webhooks) diff --git a/docs/zh-CN/providers/anthropic.md b/docs/zh-CN/providers/anthropic.md index 3b13378ef..a4a17495f 100644 --- a/docs/zh-CN/providers/anthropic.md +++ b/docs/zh-CN/providers/anthropic.md @@ -1,46 +1,28 @@ --- read_when: - 你想在 OpenClaw 中使用 Anthropic 模型 -summary: 在 OpenClaw 中通过 API 密钥使用 Anthropic Claude +summary: 在 OpenClaw 中通过 API 密钥或 Claude CLI 使用 Anthropic Claude title: Anthropic x-i18n: - generated_at: "2026-04-06T12:44:41Z" + generated_at: "2026-04-06T15:31:06Z" model: gpt-5.4 provider: openai - source_hash: 6af35571debf5889b63e3b4f6a05aa4e046f39740287e6e1c492916ca00df44b + source_hash: 423928fd36c66729985208d4d3f53aff1f94f63b908df85072988bdc41d5cf46 source_path: providers/anthropic.md workflow: 15 --- # Anthropic（Claude） -Anthropic 构建了 **Claude** 模型家族，并通过 API 提供访问。 -在 OpenClaw 中，新的 Anthropic 设置应使用 API 密钥。现有的旧版 -Anthropic token 配置文件如果已经完成配置，运行时仍会继续支持。 +Anthropic 构建了 **Claude** 模型家族，并通过 API 和 +Claude CLI 提供访问。在 OpenClaw 中，Anthropic API 密钥和 Claude CLI 复用都受支持。如果现有的旧版 Anthropic 令牌配置文件已经配置好，运行时仍会继续使用它们。 -对于 OpenClaw 中的 Anthropic，计费拆分如下： +Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此只要 Anthropic 没有发布新的政策，OpenClaw 就会将 Claude CLI 复用和 `claude -p` 用法视为此集成下被认可的方式。 -- **Anthropic API 密钥**：标准 Anthropic API 计费。 -- **OpenClaw 内的 Claude 订阅凭证**：Anthropic 于 - **2026 年 4 月 4 日 PT 时间中午 12:00 / BST 时间晚上 8:00** - 告知 OpenClaw 用户，这会被视为 - 第三方 harness 使用，并需要 **Extra Usage**（按量计费， - 与订阅分开计费）。 +对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是最清晰、最可预测的生产路径。如果你已经在主机上使用 Claude CLI，OpenClaw 可以直接复用该登录状态。 -我们的本地复现结果也符合这一拆分： - -- 直接执行 `claude -p` 可能仍然可用 -- `claude -p --append-system-prompt ...` 在提示词标识出 OpenClaw 时， - 可能触发 Extra Usage 保护 -- 在 Anthropic SDK + `ANTHROPIC_API_KEY` 路径上，相同的类 OpenClaw - 系统提示词**不会**复现该拦截 - -因此，实际规则是：**Anthropic API 密钥，或启用了 -Extra Usage 的 Claude 订阅**。如果你想要最清晰的生产环境路径，请使用 Anthropic API -密钥。 - -Anthropic 当前的公开文档： +Anthropic 当前公开文档： - [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference) - [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview) @@ -57,7 +39,7 @@ Plan](/zh-CN/providers/glm)。 ## 选项 A：Anthropic API 密钥 -**最适合：** 标准 API 访问和按量计费。 +**最适合：** 标准 API 访问和按使用量计费。 请在 Anthropic Console 中创建你的 API 密钥。 ### CLI 设置 @@ -82,7 +64,7 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" ## Thinking 默认值（Claude 4.6） - 当未设置显式 thinking 级别时，Anthropic Claude 4.6 模型在 OpenClaw 中默认使用 `adaptive` thinking。 -- 你可以按消息覆盖（`/think:`），或在模型参数中覆盖： +- 你可以按消息覆盖（`/think:`），或在模型参数中设置： `agents.defaults.models["anthropic/"].params.thinking`。 - 相关 Anthropic 文档： - [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking) @@ -90,10 +72,10 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" ## 快速模式（Anthropic API） -OpenClaw 的共享 `/fast` 开关也支持直连公开 Anthropic 流量，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证请求。 +OpenClaw 的共享 `/fast` 开关也支持直接公共 Anthropic 流量，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证请求。 -- `/fast on` 映射到 `service_tier: "auto"` -- `/fast off` 映射到 `service_tier: "standard_only"` +- `/fast on` 映射为 `service_tier: "auto"` +- `/fast off` 映射为 `service_tier: "standard_only"` - 配置默认值： ```json5 @@ -112,23 +94,23 @@ OpenClaw 的共享 `/fast` 开关也支持直连公开 Anthropic 流量，包括 重要限制： -- OpenClaw 只会为直连 `api.anthropic.com` 的请求注入 Anthropic service tier。如果你通过代理或 Gateway 网关路由 `anthropic/*`，`/fast` 不会修改 `service_tier`。 -- 如果同时设置了显式的 Anthropic `serviceTier` 或 `service_tier` 模型参数，它们会覆盖 `/fast` 默认值。 -- Anthropic 会在响应中的 `usage.service_tier` 返回实际生效的 tier。对于没有 Priority Tier 容量的账户，`service_tier: "auto"` 仍可能解析为 `standard`。 +- OpenClaw 仅对直接发往 `api.anthropic.com` 的请求注入 Anthropic service tier。如果你通过代理或 Gateway 网关路由 `anthropic/*`，`/fast` 不会改动 `service_tier`。 +- 如果同时设置了显式 Anthropic `serviceTier` 或 `service_tier` 模型参数，则它们会覆盖 `/fast` 默认值。 +- Anthropic 会在响应中的 `usage.service_tier` 下报告实际生效的层级。对于没有 Priority Tier 容量的账户，`service_tier: "auto"` 仍可能解析为 `standard`。 -## 提示词缓存（Anthropic API） +## 提示缓存（Anthropic API） -OpenClaw 支持 Anthropic 的提示词缓存功能。这是**仅 API** 功能；旧版 Anthropic token 凭证不会应用缓存设置。 +OpenClaw 支持 Anthropic 的提示缓存功能。这是**仅限 API**的；旧版 Anthropic 令牌凭证不会遵循缓存设置。 ### 配置 -在你的模型配置中使用 `cacheRetention` 参数： +在模型配置中使用 `cacheRetention` 参数： -| Value | Cache Duration | Description | -| ------- | -------------- | ------------------ | -| `none` | 不缓存 | 禁用提示词缓存 | -| `short` | 5 分钟 | API 密钥凭证的默认值 | -| `long` | 1 小时 | 扩展缓存 | +| 值 | 缓存时长 | 说明 | +| ------- | -------------- | ------------------------ | +| `none` | 不缓存 | 禁用提示缓存 | +| `short` | 5 分钟 | API 密钥凭证的默认值 | +| `long` | 1 小时 | 扩展缓存 | ```json5 { @@ -146,11 +128,11 @@ OpenClaw 支持 Anthropic 的提示词缓存功能。这是**仅 API** 功能； ### 默认值 -当使用 Anthropic API 密钥认证时，OpenClaw 会自动为所有 Anthropic 模型应用 `cacheRetention: "short"`（5 分钟缓存）。你可以在配置中显式设置 `cacheRetention` 来覆盖此行为。 +当使用 Anthropic API 密钥凭证时，OpenClaw 会自动对所有 Anthropic 模型应用 `cacheRetention: "short"`（5 分钟缓存）。你可以通过在配置中显式设置 `cacheRetention` 来覆盖此值。 ### 按智能体覆盖 cacheRetention -请将模型级参数作为基线，然后通过 `agents.list[].params` 覆盖特定智能体。 +将模型级参数作为基线，然后通过 `agents.list[].params` 覆盖特定智能体。 ```json5 { @@ -165,29 +147,29 @@ OpenClaw 支持 Anthropic 的提示词缓存功能。这是**仅 API** 功能； }, list: [ { id: "research", default: true }, - { id: "alerts", params: { cacheRetention: "none" } }, // 仅覆盖这个智能体 + { id: "alerts", params: { cacheRetention: "none" } }, // 仅覆盖此智能体 ], }, } ``` -与缓存相关参数的配置合并顺序： +与缓存相关的参数配置合并顺序： 1. `agents.defaults.models["provider/model"].params` 2. `agents.list[].params`（匹配 `id`，按键覆盖） -这样，你就可以让一个智能体保留长期缓存，同时让同一模型上的另一个智能体禁用缓存，以避免在突发 / 低复用流量下产生写入成本。 +这样，同一模型上的一个智能体可以保留长期缓存，而另一个智能体则可以关闭缓存，以避免在突发/低复用流量下产生写入成本。 ### Bedrock Claude 说明 -- Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）在配置时接受 `cacheRetention` 透传。 +- Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）在配置后接受 `cacheRetention` 透传。 - 非 Anthropic 的 Bedrock 模型在运行时会被强制设置为 `cacheRetention: "none"`。 -- 当未设置显式值时，Anthropic API 密钥的智能默认值也会为 Claude-on-Bedrock 模型引用填充 `cacheRetention: "short"`。 +- 当未设置显式值时，Anthropic API 密钥的智能默认值也会为 Claude-on-Bedrock 模型引用注入 `cacheRetention: "short"`。 -## 1M 上下文窗口（Anthropic beta） +## 100 万上下文窗口（Anthropic beta） -Anthropic 的 1M 上下文窗口仍处于 beta 限制阶段。在 OpenClaw 中， -请通过 `params.context1m: true` 为受支持的 Opus/Sonnet 模型逐个启用。 +Anthropic 的 100 万上下文窗口受 beta 限制。在 OpenClaw 中，可通过 +`params.context1m: true` 为受支持的 Opus/Sonnet 模型按模型启用。 ```json5 { @@ -203,74 +185,54 @@ Anthropic 的 1M 上下文窗口仍处于 beta 限制阶段。在 OpenClaw 中 } ``` -OpenClaw 会将其映射为 Anthropic 请求上的 +OpenClaw 会将其映射为 Anthropic 请求中的 `anthropic-beta: context-1m-2025-08-07`。 -只有在该模型的 `params.context1m` 被显式设置为 `true` 时， -此功能才会激活。 +只有当该模型的 `params.context1m` 被显式设置为 `true` 时，才会启用此功能。 -要求：Anthropic 必须允许该凭证使用长上下文 -（通常是 API 密钥计费，或启用了 Extra Usage 的 OpenClaw Claude 登录路径 / 旧版 token 凭证）。 -否则 Anthropic 会返回： -`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。 +要求：Anthropic 必须允许该凭证使用长上下文。 -注意：Anthropic 当前会在使用 -旧版 Anthropic token 凭证（`sk-ant-oat-*`）时拒绝 `context-1m-*` beta 请求。如果你在该旧版凭证模式下配置了 -`context1m: true`，OpenClaw 会记录一条警告，并通过跳过 context1m beta -header 回退到标准上下文窗口，同时保留必需的 OAuth beta。 +注意：Anthropic 目前在使用旧版 Anthropic 令牌凭证（`sk-ant-oat-*`）时会拒绝 `context-1m-*` beta 请求。如果你在该旧版凭证模式下配置 +`context1m: true`，OpenClaw 会记录警告，并通过跳过 context1m beta +请求头、同时保留必需的 OAuth beta，请求回退到标准上下文窗口。 -## 已移除：Claude CLI 后端 +## Claude CLI 后端 -内置 Anthropic `claude-cli` 后端已被移除。 +内置的 Anthropic `claude-cli` 后端在 OpenClaw 中受支持。 -- Anthropic 在 2026 年 4 月 4 日的通知中表示，由 OpenClaw 驱动的 Claude 登录流量属于 - 第三方 harness 使用，并需要 **Extra Usage**。 -- 我们的本地复现也表明，直接执行 - `claude -p --append-system-prompt ...` 在附加的提示词标识出 OpenClaw 时， - 也可能触发相同保护。 -- 在 Anthropic SDK + `ANTHROPIC_API_KEY` 路径上，相同的类 OpenClaw 提示词 - 不会触发该保护。 -- 在 OpenClaw 中处理 Anthropic 流量时，请使用 Anthropic API 密钥。 -- 如果你需要本地 CLI 回退运行时，请使用其他受支持的 CLI 后端， - 例如 Codex CLI。请参阅 [/gateway/cli-backends](/gateway/cli-backends)。 +- Anthropic 员工告诉我们这种用法再次被允许。 +- 因此，只要 Anthropic 没有发布新的政策，OpenClaw 就会将 Claude CLI 复用和 `claude -p` 用法视为此集成下被认可的方式。 +- 对于始终在线的 Gateway 网关主机，Anthropic API 密钥仍然是最清晰的生产路径，也更便于进行显式服务端计费控制。 +- 设置和运行时详情请参见 [/gateway/cli-backends](/zh-CN/gateway/cli-backends)。 ## 说明 -- Anthropic 的公开 Claude Code 文档仍然记录了诸如 - `claude -p` 之类的直接 CLI 用法，但 Anthropic 单独发给 OpenClaw 用户的通知指出， - **OpenClaw** 的 Claude 登录路径属于第三方 harness 使用，并要求 - **Extra Usage**（按量计费，与订阅分开计费）。 - 我们的本地复现也表明，直接执行 - `claude -p --append-system-prompt ...` 在附加提示词标识出 OpenClaw 时 - 也可能触发相同保护，而相同的提示词形式在 Anthropic SDK + `ANTHROPIC_API_KEY` - 路径上不会复现该问题。对于生产环境，我们 - 改为推荐使用 Anthropic API 密钥。 -- Anthropic setup-token 现已在 OpenClaw 中重新提供，作为旧版 / 手动路径。Anthropic 针对 OpenClaw 的专用计费通知仍然适用，因此请在预期 Anthropic 会对此路径要求 **Extra Usage** 的前提下使用它。 -- 凭证详情和复用规则请参阅 [/concepts/oauth](/zh-CN/concepts/oauth)。 +- Anthropic 的公开 Claude Code 文档仍然记录了类似 + `claude -p` 的直接 CLI 用法，而 Anthropic 员工也告诉我们 OpenClaw 风格的 Claude CLI 用法再次被允许。除非 Anthropic 发布新的政策变更，否则我们将这一指导视为已确定。 +- Anthropic setup-token 仍在 OpenClaw 中作为受支持的令牌凭证路径保留，但 OpenClaw 现在在可用时优先使用 Claude CLI 复用和 `claude -p`。 +- 凭证详情和复用规则请参见 [/concepts/oauth](/zh-CN/concepts/oauth)。 ## 故障排除 -**401 错误 / token 突然失效** +**401 错误 / 令牌突然失效** -- 旧版 Anthropic token 凭证可能会过期或被撤销。 +- Anthropic 令牌凭证可能会过期或被撤销。 - 对于新的设置，请迁移到 Anthropic API 密钥。 -**提供商 “anthropic” 未找到 API 密钥** +**未找到提供商 “anthropic” 的 API 密钥** -- 凭证是**按智能体**区分的。新智能体不会继承主智能体的密钥。 -- 请重新为该智能体运行新手引导，或在 gateway host 上配置 API 密钥， - 然后使用 `openclaw models status` 进行验证。 +- 凭证是**按智能体**管理的。新智能体不会继承主智能体的密钥。 +- 请为该智能体重新运行新手引导，或者在 Gateway 网关主机上配置 API 密钥，然后使用 `openclaw models status` 验证。 **未找到配置文件 `anthropic:default` 的凭证** -- 运行 `openclaw models status` 以查看当前激活的是哪个凭证配置文件。 -- 重新运行新手引导，或为该配置文件路径配置 API 密钥。 +- 运行 `openclaw models status` 查看当前启用的是哪个凭证配置文件。 +- 重新运行新手引导，或者为该配置文件路径配置一个 API 密钥。 -**没有可用的凭证配置文件（全部处于冷却 / 不可用）** +**没有可用的凭证配置文件（全部处于冷却中/不可用）** - 检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。 -- Anthropic 的速率限制冷却可能是按模型生效的，因此即使当前模型正在冷却， - 同级的其他 Anthropic 模型仍可能可用。 +- Anthropic 速率限制冷却可能是按模型划分的，因此即使当前模型处于冷却中，兄弟 Anthropic 模型仍可能可用。 - 添加另一个 Anthropic 配置文件，或等待冷却结束。 更多内容：[/gateway/troubleshooting](/zh-CN/gateway/troubleshooting) 和 [/help/faq](/zh-CN/help/faq)。 diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index d01c9b348..4b2f8bafa 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -1,25 +1,31 @@ --- read_when: - - 你想在 OpenClaw 中使用 OpenAI 模型 - - 你想使用 Codex 订阅凭证而不是 API 密钥 + - 你希望在 OpenClaw 中使用 OpenAI 模型 + - 你希望使用 Codex 订阅认证而不是 API 密钥 summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI title: OpenAI x-i18n: - generated_at: "2026-04-06T00:33:49Z" + generated_at: "2026-04-06T15:31:36Z" model: gpt-5.4 provider: openai - source_hash: 9e04db5787f6ed7b1eda04d965c10febae10809fc82ae4d9769e7163234471f5 + source_hash: 736ad34671584665674515aee76e2670b14b22bb3cc0bf0ab3ae2388ac136598 source_path: providers/openai.md workflow: 15 --- # OpenAI -OpenAI 为 GPT 模型提供开发者 API。Codex 支持通过 **ChatGPT 登录** 使用订阅访问，或通过 **API 密钥** 登录使用按量计费访问。Codex cloud 需要 ChatGPT 登录。OpenAI 明确支持在 OpenClaw 这类外部工具/工作流中使用订阅 OAuth。 +OpenAI 为 GPT 模型提供开发者 API。Codex 支持**ChatGPT 登录**用于订阅访问，或支持**API 密钥**登录用于按量计费访问。Codex cloud 需要 ChatGPT 登录。 +OpenAI 明确支持在 OpenClaw 这样的外部工具/工作流中使用订阅 OAuth。 ## 默认交互风格 -OpenClaw 可以为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI 专用提示词叠加层。默认情况下，这个叠加层会让助手保持更温暖、协作、简洁、直接，并带有一点更丰富的情感表达，同时不会替换 OpenClaw 的基础系统提示词。这个友好叠加层也允许在自然合适时偶尔使用 emoji，同时保持整体输出简洁。 +OpenClaw 可以为 `openai/*` 和 +`openai-codex/*` 运行添加一个小型 OpenAI 专属提示叠加层。默认情况下，该叠加层会让 assistant 保持温和、 +协作、简洁、直接，并带有一点更丰富的情感表达， +同时不会替换 OpenClaw 的基础系统提示。这个友好的叠加层还 +允许在自然合适时偶尔使用 emoji，同时保持整体 +输出简洁。 配置键： @@ -27,8 +33,8 @@ OpenClaw 可以为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 Open 允许的值： -- `"friendly"`：默认；启用 OpenAI 专用叠加层。 -- `"off"`：禁用叠加层，仅使用基础 OpenClaw 提示词。 +- `"friendly"`：默认；启用 OpenAI 专属叠加层。 +- `"off"`：禁用叠加层，仅使用基础 OpenClaw 提示。 作用范围： @@ -36,7 +42,8 @@ OpenClaw 可以为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 Open - 适用于 `openai-codex/*` 模型。 - 不影响其他提供商。 -此行为默认开启。如果你希望它在未来本地配置变动后仍然保留，请显式保留 `"friendly"`： +此行为默认开启。如果你希望它 +在未来本地配置变动中仍然保留，请显式保留 `"friendly"`： ```json5 { @@ -52,9 +59,9 @@ OpenClaw 可以为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 Open } ``` -### 禁用 OpenAI 提示词叠加层 +### 禁用 OpenAI 提示叠加层 -如果你想使用未修改的基础 OpenClaw 提示词，请将叠加层设置为 `"off"`： +如果你希望使用未修改的基础 OpenClaw 提示，请将叠加层设置为 `"off"`： ```json5 { @@ -70,7 +77,7 @@ OpenClaw 可以为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 Open } ``` -你也可以直接使用配置 CLI 设置： +你也可以直接使用配置 CLI 设置它： ```bash openclaw config set plugins.entries.openai.config.personality off @@ -79,13 +86,19 @@ openclaw config set plugins.entries.openai.config.personality off ## 选项 A：OpenAI API 密钥（OpenAI Platform） **最适合：** 直接 API 访问和按量计费。 -从 OpenAI 控制台获取你的 API 密钥。 +请从 OpenAI 控制台获取你的 API 密钥。 + +路由摘要： + +- `openai/gpt-5.4` = 直接 OpenAI Platform API 路由 +- 需要 `OPENAI_API_KEY`（或等效的 OpenAI 提供商配置） +- 在 OpenClaw 中，ChatGPT/Codex 登录通过 `openai-codex/*` 路由，而不是 `openai/*` ### CLI 设置 ```bash openclaw onboard --auth-choice openai-api-key -# 或非交互式 +# 或非交互方式 openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` @@ -98,21 +111,28 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY" } ``` -OpenAI 当前的 API 模型文档列出了可直接通过 OpenAI API 使用的 `gpt-5.4` 和 `gpt-5.4-pro`。OpenClaw 通过 `openai/*` Responses 路径转发这两个模型。OpenClaw 会有意隐藏过时的 `openai/gpt-5.3-codex-spark` 条目，因为直接 OpenAI API 调用在真实流量中会拒绝它。 +OpenAI 当前的 API 模型文档将 `gpt-5.4` 和 `gpt-5.4-pro` 列为可直接 +通过 OpenAI API 使用的模型。OpenClaw 会通过 `openai/*` Responses 路径转发这两个模型。 +OpenClaw 会有意隐藏过时的 `openai/gpt-5.3-codex-spark` 条目， +因为直接 OpenAI API 调用在真实流量中会拒绝它。 -OpenClaw **不会** 在直接 OpenAI API 路径上暴露 `openai/gpt-5.3-codex-spark`。`pi-ai` 仍然为该模型内置了一个条目，但当前真实的 OpenAI API 请求会拒绝它。在 OpenClaw 中，Spark 被视为仅限 Codex。 +OpenClaw **不会**在直接 OpenAI +API 路径上公开 `openai/gpt-5.3-codex-spark`。`pi-ai` 仍然内置该模型的一条记录，但当前真实 OpenAI API +请求会拒绝它。在 OpenClaw 中，Spark 被视为仅限 Codex。 ## 图像生成 -内置的 `openai` 插件还会通过共享的 `image_generate` 工具注册图像生成功能。 +内置的 `openai` 插件也会通过共享的 +`image_generate` 工具注册图像生成功能。 - 默认图像模型：`openai/gpt-image-1` - 生成：每次请求最多 4 张图像 - 编辑模式：已启用，最多支持 5 张参考图像 - 支持 `size` -- 当前 OpenAI 专属注意事项：OpenClaw 目前不会将 `aspectRatio` 或 `resolution` 覆盖值转发到 OpenAI Images API +- 当前 OpenAI 特定限制：OpenClaw 目前不会将 `aspectRatio` 或 + `resolution` 覆盖值转发到 OpenAI Images API -要将 OpenAI 用作默认图像提供商： +如需将 OpenAI 用作默认图像提供商： ```json5 { @@ -126,18 +146,21 @@ OpenClaw **不会** 在直接 OpenAI API 路径上暴露 `openai/gpt-5.3-codex-s } ``` -有关共享工具参数、提供商选择和故障切换行为，请参见 [图像生成](/zh-CN/tools/image-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。 ## 视频生成 -内置的 `openai` 插件还会通过共享的 `video_generate` 工具注册视频生成功能。 +内置的 `openai` 插件也会通过共享的 +`video_generate` 工具注册视频生成功能。 - 默认视频模型：`openai/sora-2` - 模式：文生视频、图生视频，以及单视频参考/编辑流程 -- 当前限制：仅支持 1 张图像或 1 个视频参考输入 -- 当前 OpenAI 专属注意事项：OpenClaw 当前仅会为原生 OpenAI 视频生成转发 `size` 覆盖值。不支持的可选覆盖值，如 `aspectRatio`、`resolution`、`audio` 和 `watermark` 会被忽略，并作为工具警告返回。 +- 当前限制：1 张图像或 1 个视频参考输入 +- 当前 OpenAI 特定限制：OpenClaw 目前只会为原生 OpenAI 视频生成转发 `size` + 覆盖值。不支持的可选覆盖值，例如 `aspectRatio`、`resolution`、`audio` 和 `watermark`，会被忽略， + 并作为工具警告返回。 -要将 OpenAI 用作默认视频提供商： +如需将 OpenAI 用作默认视频提供商： ```json5 { @@ -151,13 +174,19 @@ OpenClaw **不会** 在直接 OpenAI API 路径上暴露 `openai/gpt-5.3-codex-s } ``` -有关共享工具参数、提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。 ## 选项 B：OpenAI Code（Codex）订阅 **最适合：** 使用 ChatGPT/Codex 订阅访问，而不是 API 密钥。 Codex cloud 需要 ChatGPT 登录，而 Codex CLI 支持 ChatGPT 或 API 密钥登录。 +路由摘要： + +- `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth 路由 +- 使用 ChatGPT/Codex 登录，而不是直接 OpenAI Platform API 密钥 +- `openai-codex/*` 的提供商侧限制可能与 ChatGPT 网页版/应用版体验不同 + ### CLI 设置（Codex OAuth） ```bash @@ -176,30 +205,43 @@ openclaw models auth login --provider openai-codex } ``` -OpenAI 当前的 Codex 文档将 `gpt-5.4` 列为当前 Codex 模型。OpenClaw 将其映射为 `openai-codex/gpt-5.4`，用于 ChatGPT/Codex OAuth 访问。 +OpenAI 当前的 Codex 文档将 `gpt-5.4` 列为当前 Codex 模型。OpenClaw +会将其映射为 `openai-codex/gpt-5.4`，用于 ChatGPT/Codex OAuth。 -如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期时，OpenClaw 会先重新读取外部 Codex 来源；当提供商可以刷新它时，会将刷新后的凭证写回 Codex 存储，而不是在单独的 OpenClaw 专用副本中接管管理。 +这一路由与 `openai/gpt-5.4` 是有意分开的。如果你想使用 +直接 OpenAI Platform API 路径，请使用带 API 密钥的 `openai/*`。如果你想使用 +ChatGPT/Codex 登录，请使用 `openai-codex/*`。 -如果你的 Codex 账户具有 Codex Spark 权限，OpenClaw 还支持： +如果新手引导复用了现有的 Codex CLI 登录，这些凭证 +仍由 Codex CLI 管理。过期时，OpenClaw 会先重新读取外部 Codex 来源， +并且当提供商可以刷新它时，会将刷新后的凭证写回 Codex 存储， +而不是通过单独的 OpenClaw 专用副本接管它。 + +如果你的 Codex 账户拥有 Codex Spark 权限，OpenClaw 还支持： - `openai-codex/gpt-5.3-codex-spark` -OpenClaw 将 Codex Spark 视为仅限 Codex。它不会暴露直接的 `openai/gpt-5.3-codex-spark` API 密钥路径。 +OpenClaw 将 Codex Spark 视为仅限 Codex。它不会公开直接的 +`openai/gpt-5.3-codex-spark` API 密钥路径。 -当 `pi-ai` 发现 `openai-codex/gpt-5.3-codex-spark` 时，OpenClaw 也会保留它。请将其视为依赖权限且带有实验性质：Codex Spark 独立于 GPT-5.4 `/fast`，其可用性取决于已登录的 Codex / ChatGPT 账户。 +当 `pi-ai` +发现 `openai-codex/gpt-5.3-codex-spark` 时，OpenClaw 也会保留它。请将其视为依赖权限且具有实验性：Codex Spark 与 GPT-5.4 `/fast` 是 +分开的，其可用性取决于已登录的 Codex / ChatGPT 账户。 ### Codex 上下文窗口上限 -OpenClaw 将 Codex 模型元数据和运行时上下文上限视为两个独立的值。 +OpenClaw 将 Codex 模型元数据和运行时上下文上限视为彼此独立的 +值。 对于 `openai-codex/gpt-5.4`： - 原生 `contextWindow`：`1050000` - 默认运行时 `contextTokens` 上限：`272000` -这样既能保持模型元数据真实准确，又能保留在实践中具有更好延迟和质量特性的较小默认运行时窗口。 +这样既保证模型元数据真实，又保留了在实践中具有更好延迟和质量特征的较小默认运行时 +窗口。 -如果你想使用不同的实际上限，请设置 `models.providers..models[].contextTokens`： +如果你想要不同的实际上限，请设置 `models.providers..models[].contextTokens`： ```json5 { @@ -218,19 +260,33 @@ OpenClaw 将 Codex 模型元数据和运行时上下文上限视为两个独立 } ``` -仅当你要声明或覆盖原生模型元数据时，才使用 `contextWindow`。当你想限制运行时上下文预算时，请使用 `contextTokens`。 +只有当你在声明或覆盖原生模型 +元数据时才使用 `contextWindow`。当你希望限制运行时上下文预算时，请使用 `contextTokens`。 -### 默认传输方式 +### 传输默认值 -OpenClaw 使用 `pi-ai` 进行模型流式传输。对于 `openai/*` 和 `openai-codex/*`，默认传输方式是 `"auto"`（优先 WebSocket，然后回退到 SSE）。 +OpenClaw 使用 `pi-ai` 进行模型流式传输。对于 `openai/*` 和 +`openai-codex/*`，默认传输方式都是 `"auto"`（WebSocket 优先，然后回退到 SSE）。 -在 `"auto"` 模式下，OpenClaw 还会在回退到 SSE 之前，对一次早期且可重试的 WebSocket 失败进行重试。强制使用 `"websocket"` 模式时，传输错误会直接显示，而不会被回退逻辑掩盖。 +在 `"auto"` 模式下，OpenClaw 还会在回退到 SSE 之前 +对一次早期、可重试的 WebSocket 失败进行重试。 +强制 `"websocket"` 模式仍会直接暴露传输错误，而不是用回退隐藏它们。 -在 `"auto"` 模式下，如果连接或会话早期轮次发生 WebSocket 失败，OpenClaw 会将该会话的 WebSocket 路径标记为降级状态，持续大约 60 秒，并在冷却期间通过 SSE 发送后续轮次，而不是在不同传输方式之间来回抖动。 +在 `"auto"` 模式下，如果发生连接失败或回合早期 WebSocket 失败，OpenClaw 会将 +该会话的 WebSocket 路径标记为降级状态约 60 秒，并在冷却期间通过 SSE 发送 +后续回合，而不是在多种传输方式之间来回抖动。 -对于原生 OpenAI 系列端点（`openai/*`、`openai-codex/*` 以及 Azure OpenAI Responses），OpenClaw 还会为请求附加稳定的会话和轮次身份状态，以便重试、重连和 SSE 回退都能与同一会话身份保持一致。在原生 OpenAI 系列路由上，这包括稳定的会话/轮次请求身份标头以及匹配的传输元数据。 +对于原生 OpenAI 系列端点（`openai/*`、`openai-codex/*` 和 Azure +OpenAI Responses），OpenClaw 还会将稳定的会话和回合身份状态附加到请求中， +以便重试、重连和 SSE 回退都保持与同一个 +对话身份一致。在原生 OpenAI 系列路由上，这包括稳定的 +会话/回合请求身份头以及匹配的传输元数据。 -OpenClaw 还会在 OpenAI 使用量计数器到达会话/状态界面之前，先跨不同传输变体对它们进行归一化。原生 OpenAI/Codex Responses 流量可能会将使用量报告为 `input_tokens` / `output_tokens`，也可能报告为 `prompt_tokens` / `completion_tokens`；OpenClaw 会将它们视为相同的输入和输出计数器，用于 `/status`、`/usage` 和会话日志。当原生 WebSocket 流量省略 `total_tokens`（或报告为 `0`）时，OpenClaw 会回退为归一化后的输入 + 输出总数，以确保会话/状态显示仍然有值。 +OpenClaw 还会在 OpenAI 使用量计数器到达会话/状态界面之前，跨不同传输变体对其进行标准化。原生 OpenAI/Codex Responses 流量可能会将使用量报告为 `input_tokens` / `output_tokens` 或 +`prompt_tokens` / `completion_tokens`；OpenClaw 会在 `/status`、`/usage` 和会话日志中将它们视为相同的输入 +和输出计数器。当原生 +WebSocket 流量省略 `total_tokens`（或报告为 `0`）时，OpenClaw 会回退为 +标准化后的输入 + 输出总和，以便会话/状态显示保持有值。 你可以设置 `agents.defaults.models..params.transport`： @@ -238,7 +294,8 @@ OpenClaw 还会在 OpenAI 使用量计数器到达会话/状态界面之前， - `"websocket"`：强制使用 WebSocket - `"auto"`：先尝试 WebSocket，然后回退到 SSE -对于 `openai/*`（Responses API），当使用 WebSocket 传输时，OpenClaw 还会默认启用 WebSocket 预热（`openaiWsWarmup: true`）。 +对于 `openai/*`（Responses API），当使用 WebSocket 传输时，OpenClaw 还会默认启用 +WebSocket 预热（`openaiWsWarmup: true`）。 相关 OpenAI 文档： @@ -264,7 +321,8 @@ OpenClaw 还会在 OpenAI 使用量计数器到达会话/状态界面之前， ### OpenAI WebSocket 预热 -OpenAI 文档将预热描述为可选功能。OpenClaw 默认会为 `openai/*` 启用它，以减少使用 WebSocket 传输时首轮请求的延迟。 +OpenAI 文档将预热描述为可选。对于 +`openai/*`，OpenClaw 默认启用它，以便在使用 WebSocket 传输时降低首轮延迟。 ### 禁用预热 @@ -304,7 +362,9 @@ OpenAI 文档将预热描述为可选功能。OpenClaw 默认会为 `openai/*` ### OpenAI 和 Codex 优先级处理 -OpenAI 的 API 通过 `service_tier=priority` 提供优先级处理。在 OpenClaw 中，设置 `agents.defaults.models["/"].params.serviceTier` 即可在原生 OpenAI/Codex Responses 端点上透传该字段。 +OpenAI 的 API 通过 `service_tier=priority` 暴露优先级处理能力。在 +OpenClaw 中，设置 `agents.defaults.models["/"].params.serviceTier` +即可在原生 OpenAI/Codex Responses 端点上传递该字段。 ```json5 { @@ -327,35 +387,37 @@ OpenAI 的 API 通过 `service_tier=priority` 提供优先级处理。在 OpenCl } ``` -支持的值有 `auto`、`default`、`flex` 和 `priority`。 +支持的值为 `auto`、`default`、`flex` 和 `priority`。 -当这些模型指向原生 OpenAI/Codex 端点时，OpenClaw 会将 `params.serviceTier` 同时转发到直接的 `openai/*` Responses 请求和 `openai-codex/*` Codex Responses 请求。 +当这些模型指向原生 OpenAI/Codex 端点时，OpenClaw 会将 `params.serviceTier` 同时转发到直接 `openai/*` Responses +请求和 `openai-codex/*` Codex Responses 请求。 重要行为： - 直接 `openai/*` 必须指向 `api.openai.com` - `openai-codex/*` 必须指向 `chatgpt.com/backend-api` -- 如果你通过其他 base URL 或代理转发任一提供商，OpenClaw 会保持 `service_tier` 不变 +- 如果你通过其他 base URL 或代理路由其中任一提供商，OpenClaw 会保持 `service_tier` 原样不动 ### OpenAI 快速模式 -OpenClaw 为 `openai/*` 和 `openai-codex/*` 会话提供了共享的快速模式开关： +OpenClaw 为 `openai/*` 和 +`openai-codex/*` 会话都提供了共享的快速模式开关： - 聊天/UI：`/fast status|on|off` - 配置：`agents.defaults.models["/"].params.fastMode` -启用快速模式后，OpenClaw 会将其映射为 OpenAI 优先级处理： +启用快速模式后，OpenClaw 会将其映射到 OpenAI 优先级处理： -- 发往 `api.openai.com` 的直接 `openai/*` Responses 调用会发送 `service_tier = "priority"` -- 发往 `chatgpt.com/backend-api` 的 `openai-codex/*` Responses 调用也会发送 `service_tier = "priority"` +- 指向 `api.openai.com` 的直接 `openai/*` Responses 调用会发送 `service_tier = "priority"` +- 指向 `chatgpt.com/backend-api` 的 `openai-codex/*` Responses 调用也会发送 `service_tier = "priority"` - 现有负载中的 `service_tier` 值会被保留 -- 快速模式不会改写 `reasoning` 或 `text.verbosity` +- 快速模式不会重写 `reasoning` 或 `text.verbosity` -对于 GPT 5.4，最常见的配置是： +对于 GPT 5.4，最常见的设置是： - 在使用 `openai/gpt-5.4` 或 `openai-codex/gpt-5.4` 的会话中发送 `/fast on` - 或设置 `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true` -- 如果你也使用 Codex OAuth，请同时设置 `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true` +- 如果你也使用 Codex OAuth，也要设置 `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true` 示例： @@ -380,34 +442,48 @@ OpenClaw 为 `openai/*` 和 `openai-codex/*` 会话提供了共享的快速模 } ``` -会话级覆盖优先于配置。在 Sessions UI 中清除此会话覆盖后，会话将恢复为配置的默认值。 +会话覆盖优先于配置。在 Sessions UI +中清除会话覆盖会让该会话恢复为配置的默认值。 -### 原生 OpenAI 与 OpenAI-compatible 路由的区别 +### 原生 OpenAI 与 OpenAI 兼容路由 -OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理方式，与通用的 OpenAI-compatible `/v1` 代理不同： +OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理方式 +与通用 OpenAI 兼容 `/v1` 代理不同： -- 原生 `openai/*`、`openai-codex/*` 和 Azure OpenAI 路由会在你显式禁用推理时，保留 `reasoning: { effort: "none" }` -- 原生 OpenAI 系列路由默认将工具 schema 设为严格模式 -- 隐藏的 OpenClaw 归因标头（`originator`、`version` 和 `User-Agent`）只会附加到已验证的原生 OpenAI 主机（`api.openai.com`）和原生 Codex 主机（`chatgpt.com/backend-api`）上 -- 原生 OpenAI/Codex 路由会保留 OpenAI 专属请求整形能力，例如 `service_tier`、Responses `store`、OpenAI 推理兼容负载以及提示词缓存提示 -- 代理风格的 OpenAI-compatible 路由会保留更宽松的兼容行为，不会强制严格工具 schema、原生专属请求整形或隐藏的 OpenAI/Codex 归因标头 +- 原生 `openai/*`、`openai-codex/*` 和 Azure OpenAI 路由会在你显式禁用 reasoning 时保留 + `reasoning: { effort: "none" }` +- 原生 OpenAI 系列路由默认将工具 schema 设为 strict 模式 +- 隐藏的 OpenClaw 标识头（`originator`、`version` 和 + `User-Agent`）只会附加到经过验证的原生 OpenAI 主机 + （`api.openai.com`）和原生 Codex 主机（`chatgpt.com/backend-api`）上 +- 原生 OpenAI/Codex 路由会保留 OpenAI 专属请求整形，例如 + `service_tier`、Responses `store`、OpenAI reasoning 兼容负载以及 + prompt-cache 提示 +- 代理式 OpenAI 兼容路由会保留更宽松的兼容行为，并且 + 不会强制 strict 工具 schema、原生专属请求整形或隐藏的 + OpenAI/Codex 标识头 -Azure OpenAI 在传输和兼容行为方面仍属于原生路由类别，但不会收到隐藏的 OpenAI/Codex 归因标头。 +Azure OpenAI 在传输和兼容行为上仍属于原生路由类别， +但不会接收隐藏的 OpenAI/Codex 标识头。 -这样可以保留当前原生 OpenAI Responses 行为，同时不会把较旧的 OpenAI-compatible 适配逻辑强加到第三方 `/v1` 后端上。 +这样可以保留当前原生 OpenAI Responses 行为，而不会将旧式 +OpenAI 兼容 shim 强加给第三方 `/v1` 后端。 ### OpenAI Responses 服务端压缩 -对于直接 OpenAI Responses 模型（`openai/*` 使用 `api: "openai-responses"` 且 `baseUrl` 为 `api.openai.com`），OpenClaw 现在会自动启用 OpenAI 服务端压缩负载提示： +对于直接 OpenAI Responses 模型（`openai/*` 使用 `api: "openai-responses"`，且 +`baseUrl` 为 `api.openai.com`），OpenClaw 现在会自动启用 OpenAI 服务端 +压缩负载提示： -- 强制设置 `store: true`（除非模型兼容性设置 `supportsStore: false`） +- 强制 `store: true`（除非模型兼容层将 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` 默认情况下，`compact_threshold` 为模型 `contextWindow` 的 `70%`（如果不可用，则为 `80000`）。 ### 显式启用服务端压缩 -当你想在兼容的 Responses 模型上强制注入 `context_management` 时使用此项（例如 Azure OpenAI Responses）： +当你希望在兼容的 +Responses 模型（例如 Azure OpenAI Responses）上强制注入 `context_management` 时，请使用此设置： ```json5 { @@ -462,9 +538,11 @@ Azure OpenAI 在传输和兼容行为方面仍属于原生路由类别，但不 } ``` -`responsesServerCompaction` 只控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 +`responsesServerCompaction` 只控制 `context_management` 注入。 +直接 OpenAI Responses 模型仍会强制 `store: true`，除非兼容层设置 +`supportsStore: false`。 -## 备注 +## 说明 -- 模型引用始终使用 `provider/model`（见 [/concepts/models](/zh-CN/concepts/models)）。 -- 凭证详情和复用规则见 [/concepts/oauth](/zh-CN/concepts/oauth)。 +- 模型引用始终使用 `provider/model`（参见 [/concepts/models](/zh-CN/concepts/models)）。 +- 认证详情和复用规则见 [/concepts/oauth](/zh-CN/concepts/oauth)。 diff --git a/docs/zh-CN/reference/api-usage-costs.md b/docs/zh-CN/reference/api-usage-costs.md index c437bf4e6..7e574ab7d 100644 --- a/docs/zh-CN/reference/api-usage-costs.md +++ b/docs/zh-CN/reference/api-usage-costs.md @@ -2,64 +2,61 @@ read_when: - 你想了解哪些功能可能会调用付费 API - 你需要审计密钥、成本和用量可见性 - - 你在解释 /status 或 /usage 成本报告 -summary: 审计哪些功能会花钱、使用了哪些密钥，以及如何查看用量 -title: API 用量与成本 + - 你正在解释 /status 或 /usage 成本报告 +summary: 审计哪些功能会花钱、使用哪些密钥，以及如何查看用量 +title: API 使用与成本 x-i18n: - generated_at: "2026-04-05T10:07:46Z" + generated_at: "2026-04-06T15:31:12Z" model: gpt-5.4 provider: openai - source_hash: 71789950fe54dcdcd3e34c8ad6e3143f749cdfff5bbc2f14be4b85aaa467b14c + source_hash: ab6eefcde9ac014df6cdda7aaa77ef48f16936ab12eaa883d9fe69425a31a2dd source_path: reference/api-usage-costs.md workflow: 15 --- -# API 用量与成本 +# API 使用与成本 -本文档列出了**可能调用 API 密钥的功能**以及它们的成本会显示在哪里。它重点说明 -OpenClaw 中可能产生提供商用量或付费 API 调用的功能。 +本文档列出了**可能调用 API 密钥的功能**以及它们的成本会显示在哪里。重点关注 +可能产生提供商用量或付费 API 调用的 OpenClaw 功能。 ## 成本显示位置（聊天 + CLI） **按会话的成本快照** -- `/status` 会显示当前会话模型、上下文用量以及上一次响应的 token 数。 -- 如果模型使用**API 密钥认证**，`/status` 还会显示上一次回复的**估算成本**。 -- 如果实时会话元数据较少，`/status` 可以从最新转录中的用量 - 条目恢复 token/缓存计数器和当前活动运行时模型标签。 - 现有的非零实时值仍然优先，如果存储的总量缺失或更小， - 按提示大小统计的转录总量也可以优先生效。 +- `/status` 会显示当前会话模型、上下文用量和上一条回复的 token 数。 +- 如果模型使用的是 **API 密钥认证**，`/status` 还会显示上一条回复的**估算成本**。 +- 如果 live 会话元数据较少，`/status` 可以从最新的转录用量条目中恢复 token/缓存 + 计数器以及当前活动运行时模型标签。现有的非零 live 值仍然优先， + 当已存储总量缺失或更小时，按提示词大小计算的转录总量可以胜出。 **按消息的成本页脚** -- `/usage full` 会在每条回复后附加一个用量页脚，其中包括**估算成本**（仅限 API 密钥）。 -- `/usage tokens` 仅显示 token；基于订阅的 OAuth/token 和 CLI 流程会隐藏美元成本。 +- `/usage full` 会在每条回复后追加用量页脚，其中包括**估算成本**（仅 API 密钥）。 +- `/usage tokens` 仅显示 token；订阅式 OAuth/token 和 CLI 流程会隐藏美元成本。 - Gemini CLI 说明：当 CLI 返回 JSON 输出时，OpenClaw 会从 - `stats` 读取用量，将 `stats.cached` 规范化为 `cacheRead`，并在需要时从 + `stats` 中读取用量，将 `stats.cached` 标准化为 `cacheRead`，并在需要时从 `stats.input_tokens - stats.cached` 推导输入 token。 -Anthropic 说明：Anthropic 公开的 Claude Code 文档仍将直接 Claude -Code 终端用量计入 Claude 套餐限制。另一方面，Anthropic 已告知 OpenClaw -用户，从 **2026 年 4 月 4 日太平洋时间下午 12:00 / 英国夏令时晚上 8:00** 起， -**OpenClaw** 的 Claude 登录路径将被视为第三方 harness 用法， -并且需要单独于订阅计费的 **Extra Usage**。Anthropic -并未提供 OpenClaw 可在 -`/usage full` 中显示的逐条消息美元估算值。 +Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用量 +现在再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法 +视为此集成的许可方式，除非 Anthropic 发布新的政策。 +Anthropic 仍然没有提供 OpenClaw 可以在 `/usage full` 中 +显示的逐消息美元估算。 **CLI 用量窗口（提供商配额）** -- `openclaw status --usage` 和 `openclaw channels list` 会显示提供商**用量窗口** - （配额快照，而不是逐条消息成本）。 -- 人类可读输出会在各提供商之间统一规范为 `X% left`。 +- `openclaw status --usage` 和 `openclaw channels list` 会显示提供商的**用量窗口** + （配额快照，而不是逐消息成本）。 +- 面向人的输出会在各提供商之间标准化为 `X% left`。 - 当前支持用量窗口的提供商：Anthropic、GitHub Copilot、Gemini CLI、 OpenAI Codex、MiniMax、Xiaomi 和 z.ai。 -- MiniMax 说明：其原始 `usage_percent` / `usagePercent` 字段表示剩余 - 配额，因此 OpenClaw 会在显示前将其取反。如果存在基于计数的字段， - 这些字段仍然优先生效。如果提供商返回 `model_remains`，OpenClaw 会优先选择 - 聊天模型条目，必要时从时间戳推导窗口标签， - 并在套餐标签中包含模型名称。 -- 这些配额窗口的用量认证会在可用时优先来自提供商特定 hooks； - 否则 OpenClaw 会回退到从认证配置文件、环境变量或配置中匹配 OAuth/API 密钥 +- MiniMax 说明：其原始 `usage_percent` / `usagePercent` 字段表示的是剩余 + 配额，因此 OpenClaw 会在显示前将其反转。如果存在基于计数的字段， + 仍然优先使用计数字段。如果提供商返回 `model_remains`，OpenClaw 会优先使用 + 聊天模型条目，必要时从时间戳推导窗口标签，并在套餐标签中 + 包含模型名称。 +- 这些配额窗口的用量认证会在可用时来自提供商特定钩子；否则 OpenClaw 会回退到从 + 认证 profile、环境变量或配置中匹配 OAuth/API 密钥 凭证。 详情和示例参见 [Token 使用与成本](/zh-CN/reference/token-use)。 @@ -68,94 +65,94 @@ Code 终端用量计入 Claude 套餐限制。另一方面，Anthropic 已告知 OpenClaw 可以从以下位置获取凭证： -- **认证配置文件**（按智能体划分，存储在 `auth-profiles.json` 中）。 +- **认证 profile**（每个智能体单独存储在 `auth-profiles.json` 中）。 - **环境变量**（例如 `OPENAI_API_KEY`、`BRAVE_API_KEY`、`FIRECRAWL_API_KEY`）。 - **配置**（`models.providers.*.apiKey`、`plugins.entries.*.config.webSearch.apiKey`、 `plugins.entries.firecrawl.config.webFetch.apiKey`、`memorySearch.*`、 `talk.providers.*.apiKey`）。 -- **Skills**（`skills.entries..apiKey`），它们可能会将密钥导出到 Skill 进程环境中。 +- **Skills**（`skills.entries..apiKey`），它们可能会将密钥导出到 Skill 进程环境变量中。 ## 会消耗密钥的功能 -### 1) 核心模型响应（聊天 + 工具） +### 1）核心模型回复（聊天 + 工具） -每次回复或工具调用都会使用**当前模型提供商**（OpenAI、Anthropic 等）。这是 +每条回复或工具调用都会使用**当前模型提供商**（OpenAI、Anthropic 等）。这是 用量和成本的主要来源。 -这也包括那些仍在 OpenClaw 本地 UI 之外计费的订阅式托管提供商， +这也包括仍在 OpenClaw 本地 UI 之外计费的订阅式托管提供商， 例如 **OpenAI Codex**、**Alibaba Cloud Model Studio Coding Plan**、**MiniMax Coding Plan**、**Z.AI / GLM Coding Plan**，以及 启用了 **Extra Usage** 的 Anthropic OpenClaw Claude 登录路径。 -关于定价配置参见 [模型](/zh-CN/providers/models)，关于显示方式参见 [Token 使用与成本](/zh-CN/reference/token-use)。 +定价配置参见 [模型](/zh-CN/providers/models)，显示方式参见 [Token 使用与成本](/zh-CN/reference/token-use)。 -### 2) 媒体理解（音频/图像/视频） +### 2）媒体理解（音频/图像/视频） -在运行回复之前，可以先对输入媒体进行摘要或转录。这会使用模型/提供商 API。 +在执行回复之前，入站媒体可能会先被摘要/转录。这会使用模型/提供商 API。 - 音频：OpenAI / Groq / Deepgram / Google / Mistral。 -- 图像：OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI。 -- 视频：Google / Qwen / Moonshot。 +- 图像：OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot AI / Qwen / Z.AI。 +- 视频：Google / Qwen / Moonshot AI。 参见 [媒体理解](/zh-CN/nodes/media-understanding)。 -### 3) 图像和视频生成 +### 3）图像和视频生成 -共享生成能力也可能消耗提供商密钥： +共享的生成能力也可能消耗提供商密钥： - 图像生成：OpenAI / Google / fal / MiniMax - 视频生成：Qwen 当 -`agents.defaults.imageGenerationModel` 未设置时，图像生成可以推断一个基于认证的提供商默认值。视频生成目前 -需要显式设置 `agents.defaults.videoGenerationModel`，例如 +`agents.defaults.imageGenerationModel` 未设置时，图像生成可以推断出一个基于认证的默认提供商。视频生成当前 +要求显式设置 `agents.defaults.videoGenerationModel`，例如 `qwen/wan2.6-t2v`。 -参见 [图像生成](/tools/image-generation)、[Qwen Cloud](/zh-CN/providers/qwen) +参见 [图像生成](/zh-CN/tools/image-generation)、[Qwen Cloud](/zh-CN/providers/qwen) 和 [模型](/zh-CN/concepts/models)。 -### 4) 记忆嵌入 + 语义搜索 +### 4）记忆嵌入 + 语义搜索 -语义记忆搜索在配置为远程提供商时会使用**嵌入 API**： +配置为远程提供商时，语义记忆搜索会使用**嵌入 API**： -- `memorySearch.provider = "openai"` → OpenAI 嵌入 -- `memorySearch.provider = "gemini"` → Gemini 嵌入 -- `memorySearch.provider = "voyage"` → Voyage 嵌入 -- `memorySearch.provider = "mistral"` → Mistral 嵌入 -- `memorySearch.provider = "ollama"` → Ollama 嵌入（本地/自托管；通常没有托管 API 计费） -- 如果本地嵌入失败，可选择回退到远程提供商 +- `memorySearch.provider = "openai"` → OpenAI embeddings +- `memorySearch.provider = "gemini"` → Gemini embeddings +- `memorySearch.provider = "voyage"` → Voyage embeddings +- `memorySearch.provider = "mistral"` → Mistral embeddings +- `memorySearch.provider = "ollama"` → Ollama embeddings（本地/自托管；通常不会产生托管 API 计费） +- 如果本地 embeddings 失败，可选择回退到远程提供商 -你可以通过设置 `memorySearch.provider = "local"` 保持本地运行（不使用 API）。 +你可以通过 `memorySearch.provider = "local"` 保持本地运行（不使用 API）。 -参见 [记忆](/zh-CN/concepts/memory)。 +参见 [Memory](/zh-CN/concepts/memory)。 -### 5) Web 搜索工具 +### 5）Web 搜索工具 `web_search` 可能会根据你的提供商产生用量费用： - **Brave Search API**：`BRAVE_API_KEY` 或 `plugins.entries.brave.config.webSearch.apiKey` - **Exa**：`EXA_API_KEY` 或 `plugins.entries.exa.config.webSearch.apiKey` - **Firecrawl**：`FIRECRAWL_API_KEY` 或 `plugins.entries.firecrawl.config.webSearch.apiKey` -- **Gemini（Google Search）**：`GEMINI_API_KEY` 或 `plugins.entries.google.config.webSearch.apiKey` +- **Gemini（Google 搜索）**：`GEMINI_API_KEY` 或 `plugins.entries.google.config.webSearch.apiKey` - **Grok（xAI）**：`XAI_API_KEY` 或 `plugins.entries.xai.config.webSearch.apiKey` -- **Kimi（Moonshot）**：`KIMI_API_KEY`、`MOONSHOT_API_KEY` 或 `plugins.entries.moonshot.config.webSearch.apiKey` +- **Kimi（Moonshot AI）**：`KIMI_API_KEY`、`MOONSHOT_API_KEY` 或 `plugins.entries.moonshot.config.webSearch.apiKey` - **MiniMax Search**：`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`、`MINIMAX_API_KEY` 或 `plugins.entries.minimax.config.webSearch.apiKey` -- **Ollama Web 搜索**：默认不需要密钥，但需要可访问的 Ollama 主机以及 `ollama signin`；当主机要求认证时，也可以复用普通 Ollama 提供商 bearer 认证 +- **Ollama Web 搜索**：默认不需要密钥，但要求可访问的 Ollama 主机以及 `ollama signin`；当主机要求时，也可以复用普通的 Ollama 提供商 bearer 认证 - **Perplexity Search API**：`PERPLEXITY_API_KEY`、`OPENROUTER_API_KEY` 或 `plugins.entries.perplexity.config.webSearch.apiKey` - **Tavily**：`TAVILY_API_KEY` 或 `plugins.entries.tavily.config.webSearch.apiKey` -- **DuckDuckGo**：无密钥回退（不产生 API 计费，但属于非官方且基于 HTML） -- **SearXNG**：`SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`（无密钥/自托管；无托管 API 计费） +- **DuckDuckGo**：无密钥回退方案（不产生 API 计费，但属于非官方且基于 HTML） +- **SearXNG**：`SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`（无密钥/自托管；不产生托管 API 计费） -旧版 `tools.web.search.*` 提供商路径仍会通过临时兼容层加载，但它们已不再是推荐的配置入口。 +旧版 `tools.web.search.*` 提供商路径仍会通过临时兼容层加载，但它们已不再是推荐的配置接口。 **Brave Search 免费额度：** 每个 Brave 套餐都包含每月 \$5 的可续期 -免费额度。Search 套餐费用为每 1,000 次请求 \$5，因此该额度可覆盖 -每月 1,000 次请求且无需付费。请在 Brave 控制台中设置用量上限， -以避免意外收费。 +免费额度。Search 套餐价格为每 1,000 次请求 \$5，因此该额度可覆盖 +每月 1,000 次免费请求。请在 Brave 控制台中设置用量上限， +以避免意外费用。 参见 [Web 工具](/zh-CN/tools/web)。 -### 5) Web 抓取工具（Firecrawl） +### 5）Web 抓取工具（Firecrawl） 当存在 API 密钥时，`web_fetch` 可以调用 **Firecrawl**： @@ -165,40 +162,40 @@ Coding Plan**、**MiniMax Coding Plan**、**Z.AI / GLM Coding Plan**，以及 参见 [Web 工具](/zh-CN/tools/web)。 -### 6) 提供商用量快照（status/health） +### 6）提供商用量快照（状态/健康） -某些状态命令会调用**提供商用量端点**来显示配额窗口或认证健康状态。 -这些通常是低频调用，但仍会访问提供商 API： +某些状态命令会调用**提供商用量端点**以显示配额窗口或认证健康状态。 +这些通常是低频调用，但仍会命中提供商 API： - `openclaw status --usage` - `openclaw models status --json` 参见 [Models CLI](/cli/models)。 -### 7) 压缩保护摘要 +### 7）压缩保护摘要 -压缩保护可以使用**当前模型**对会话历史进行摘要， -因此运行时会调用提供商 API。 +压缩保护机制可以使用**当前模型**对会话历史进行摘要， +运行时会调用提供商 API。 参见 [会话管理 + 压缩](/zh-CN/reference/session-management-compaction)。 -### 8) 模型扫描 / 探测 +### 8）模型扫描 / 探测 -`openclaw models scan` 在启用探测时可以探测 OpenRouter 模型，并使用 `OPENROUTER_API_KEY`。 +在启用探测时，`openclaw models scan` 可以探测 OpenRouter 模型，并使用 `OPENROUTER_API_KEY`。 参见 [Models CLI](/cli/models)。 -### 9) Talk（语音） +### 9）Talk（语音） -Talk 模式在配置后可以调用 **ElevenLabs**： +配置后，Talk 模式可以调用 **ElevenLabs**： - `ELEVENLABS_API_KEY` 或 `talk.providers.elevenlabs.apiKey` 参见 [Talk 模式](/zh-CN/nodes/talk)。 -### 10) Skills（第三方 API） +### 10）Skills（第三方 API） -Skills 可以将 `apiKey` 存储在 `skills.entries..apiKey` 中。如果某个 Skill 使用该密钥访问外部 -API，则可能根据该 Skill 的提供商产生费用。 +Skills 可以在 `skills.entries..apiKey` 中存储 `apiKey`。如果某个 Skill 使用该密钥访问外部 +API，它就可能按该 Skill 提供商的规则产生费用。 参见 [Skills](/zh-CN/tools/skills)。 diff --git a/docs/zh-CN/reference/test.md b/docs/zh-CN/reference/test.md index 4fdcd8744..ebb07858d 100644 --- a/docs/zh-CN/reference/test.md +++ b/docs/zh-CN/reference/test.md @@ -1,13 +1,13 @@ --- read_when: - - 运行或修复测试 -summary: 如何在本地运行测试（vitest），以及何时使用 force/coverage 模式 + - 运行或修复测试时 +summary: 如何在本地运行测试（Vitest），以及何时使用 force/coverage 模式 title: 测试 x-i18n: - generated_at: "2026-04-05T10:09:00Z" + generated_at: "2026-04-06T15:31:19Z" model: gpt-5.4 provider: openai - source_hash: 78390107a9ac2bdc4294d4d0204467c5efdd98faebaf308f3a4597ab966a6d26 + source_hash: f47eef441b9dc700b0f7182ebf1b494303cd1dab85aefdea414a0fae12f51963 source_path: reference/test.md workflow: 15 --- @@ -16,40 +16,42 @@ x-i18n: - 完整测试套件（测试集、live、Docker）：[测试](/zh-CN/help/testing) -- `pnpm test:force`：终止所有仍占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，避免服务端测试与正在运行的实例冲突。当先前的 Gateway 网关运行导致端口 `18789` 仍被占用时，请使用此命令。 -- `pnpm test:coverage`：使用 V8 覆盖率运行单元测试集（通过 `vitest.unit.config.ts`）。全局阈值为 70% 的行数/分支/函数/语句覆盖率。覆盖率会排除集成较重的入口点（CLI 接线、gateway/telegram 桥接、webchat 静态服务器），以便将目标聚焦于适合单元测试的逻辑。 -- `pnpm test:coverage:changed`：仅对自 `origin/main` 以来变更的文件运行单元覆盖率。 -- `pnpm test:changed`：使用 `--changed origin/main` 运行原生 Vitest projects 配置。基础配置将 projects/config 文件视为 `forceRerunTriggers`，因此当这些接线发生变化时，仍会在需要时更广泛地重新运行测试。 -- `pnpm test`：直接运行原生 Vitest 根 projects 配置。文件过滤器可在已配置的 projects 间原生生效。 -- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用共享的非隔离运行器。 +- `pnpm test:force`：终止任何仍占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，以避免服务端测试与正在运行的实例发生冲突。如果之前某次 Gateway 网关运行导致端口 `18789` 仍被占用，请使用此命令。 +- `pnpm test:coverage`：使用 V8 覆盖率运行单元测试套件（通过 `vitest.unit.config.ts`）。全局阈值为 70% 的 lines/branches/functions/statements。覆盖率会排除集成程度较高的入口点（CLI 接线、gateway/telegram 桥接、webchat 静态服务器），以便将目标聚焦在适合单元测试的逻辑上。 +- `pnpm test:coverage:changed`：仅对自 `origin/main` 以来变更的文件运行单元测试覆盖率。 +- `pnpm test:changed`：当差异只涉及可路由的源码/测试文件时，会将变更的 git 路径展开为有范围的 Vitest 测试 lane。配置/设置变更仍会回退为原生根项目运行，以便在需要时让接线改动触发更广泛的重跑。 +- `pnpm test`：会将显式的文件/目录目标路由到有范围的 Vitest 测试 lane，但在你执行完整、无目标限制的扫描时，仍会回退为原生根项目运行。 +- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会通过专用的轻量 lane 路由，这些 lane 只保留 `test/setup.ts`，而运行时负担较重的用例仍保留在原有 lane 上。 +- 选定的 `plugin-sdk` 和 `commands` 辅助源码文件也会将 `pnpm test:changed` 映射到这些轻量 lane 中对应的同级测试，因此对小型辅助函数的修改无需重跑那些依赖重量级运行时的测试套件。 +- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用了共享的非隔离运行器。 - `pnpm test:channels` 运行 `vitest.channels.config.ts`。 - `pnpm test:extensions` 运行 `vitest.extensions.config.ts`。 -- `pnpm test:extensions`：运行扩展/插件测试集。 -- `pnpm test:perf:imports`：为原生根 projects 运行启用 Vitest 导入耗时 + 导入明细报告。 -- `pnpm test:perf:imports:changed`：同样的导入性能分析，但仅针对自 `origin/main` 以来变更的文件。 +- `pnpm test:extensions`：运行扩展/插件测试套件。 +- `pnpm test:perf:imports`：启用 Vitest 导入耗时 + 导入明细报告，同时对显式文件/目录目标仍使用有范围的 lane 路由。 +- `pnpm test:perf:imports:changed`：与上面相同的导入分析，但只针对自 `origin/main` 以来变更的文件。 - `pnpm test:perf:profile:main`：为 Vitest 主线程写入 CPU profile（`.artifacts/vitest-main-profile`）。 -- `pnpm test:perf:profile:runner`：为单元测试运行器写入 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。 +- `pnpm test:perf:profile:runner`：为单元测试运行器写入 CPU + heap profiles（`.artifacts/vitest-runner-profile`）。 - Gateway 网关集成测试：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 选择启用。 -- `pnpm test:e2e`：运行 Gateway 网关端到端 smoke 测试（多实例 WS/HTTP/节点配对）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false` 和自适应 worker；可通过 `OPENCLAW_E2E_WORKERS=` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。 -- `pnpm test:live`：运行 provider live 测试（minimax/zai）。需要 API 密钥和 `LIVE=1`（或 provider 专用的 `*_LIVE_TEST=1`）才能取消跳过。 -- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要一个可用的 live 模型密钥（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，且不像常规单元/e2e 测试集那样预期具备 CI 稳定性。 -- `pnpm test:docker:mcp-channels`：启动一个带种子数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后通过真实的 stdio 桥接验证路由对话发现、转录读取、附件元数据、live 事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该 smoke 测试反映的就是桥接实际发出的内容。 +- `pnpm test:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS/HTTP/节点配对）。默认在 `vitest.e2e.config.ts` 中使用 `threads` + `isolate: false` 和自适应 worker；可通过 `OPENCLAW_E2E_WORKERS=` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以获得详细日志。 +- `pnpm test:live`：运行提供商 live 测试（minimax/zai）。需要 API keys，并设置 `LIVE=1`（或特定提供商的 `*_LIVE_TEST=1`）以取消跳过。 +- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行真实的代理聊天。需要可用的 live 模型 key（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并不期望像常规单元/e2e 测试套件那样具有 CI 稳定性。 +- `pnpm test:docker:mcp-channels`：启动一个预置数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后通过真实的 stdio bridge 验证路由会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP frames，因此该冒烟测试能反映桥接实际发出的内容。 -## 本地 PR 门禁 +## 本地 PR gate -对于本地 PR 落地/门禁检查，请运行： +对于本地 PR 落地/gate 检查，请运行： - `pnpm check` - `pnpm build` - `pnpm test` - `pnpm check:docs` -如果 `pnpm test` 在负载较高的主机上偶发失败，请先重新运行一次，再将其视为回归问题；然后使用 `pnpm test ` 进行定位。对于内存受限的主机，请使用： +如果 `pnpm test` 在高负载主机上出现偶发失败，请先重跑一次，再判断是否是回归问题；然后用 `pnpm test ` 进行隔离。对于内存受限的主机，请使用： - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` -## 模型延迟基准（本地密钥） +## 模型延迟基准测试（本地 keys） 脚本：[`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) @@ -57,14 +59,14 @@ x-i18n: - `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10` - 可选环境变量：`MINIMAX_API_KEY`、`MINIMAX_BASE_URL`、`MINIMAX_MODEL`、`ANTHROPIC_API_KEY` -- 默认提示词：“Reply with a single word: ok. No punctuation or extra text.” +- 默认提示词：“用一个单词回复：ok。不要标点，也不要额外文本。” -最近一次运行（2025-12-31，20 次运行）： +最近一次运行（2025-12-31，20 次）： - minimax 中位数 1279ms（最小 1114，最大 2431） - opus 中位数 2454ms（最小 1224，最大 3170） -## CLI 启动基准 +## CLI 启动基准测试 脚本：[`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts) @@ -89,37 +91,37 @@ x-i18n: - `startup`：`--version`、`--help`、`health`、`health --json`、`status --json`、`status` - `real`：`health`、`status`、`status --json`、`sessions`、`sessions --json`、`agents list --json`、`gateway status`、`gateway status --json`、`gateway health --json`、`config get gateway.port` -- `all`：同时包含这两个预设 +- `all`：两个预设都包含 -输出包括每个命令的 `sampleCount`、平均值、p50、p95、最小/最大值、退出码/信号分布，以及最大 RSS 摘要。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，从而让计时与 profile 采集使用相同的测试框架。 +输出包括每个命令的 `sampleCount`、avg、p50、p95、min/max、exit-code/signal 分布，以及最大 RSS 摘要。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，因此计时和 profile 捕获使用同一个测试 harness。 -已保存输出约定： +保存输出约定： -- `pnpm test:startup:bench:smoke` 会将目标 smoke 产物写入 `.artifacts/cli-startup-bench-smoke.json` -- `pnpm test:startup:bench:save` 会使用 `runs=5` 和 `warmup=1` 将完整测试集产物写入 `.artifacts/cli-startup-bench-all.json` -- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1` 刷新已纳入版本控制的基线夹具 `test/fixtures/cli-startup-bench.json` +- `pnpm test:startup:bench:smoke` 会将目标冒烟产物写入 `.artifacts/cli-startup-bench-smoke.json` +- `pnpm test:startup:bench:save` 会使用 `runs=5` 和 `warmup=1` 将完整测试套件产物写入 `.artifacts/cli-startup-bench-all.json` +- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1` 刷新已提交的基线 fixture：`test/fixtures/cli-startup-bench.json` -已纳入版本控制的夹具： +已提交的 fixture： - `test/fixtures/cli-startup-bench.json` - 使用 `pnpm test:startup:bench:update` 刷新 -- 使用 `pnpm test:startup:bench:check` 将当前结果与该夹具进行比较 +- 使用 `pnpm test:startup:bench:check` 将当前结果与该 fixture 进行比较 ## 新手引导 E2E（Docker） -Docker 是可选的；只有在进行容器化新手引导 smoke 测试时才需要。 +Docker 是可选的；只有在进行容器化新手引导冒烟测试时才需要它。 -在干净的 Linux 容器中的完整冷启动流程： +在干净的 Linux 容器中执行完整冷启动流程： ```bash scripts/e2e/onboard-docker.sh ``` -该脚本通过伪 TTY 驱动交互式向导，验证配置/工作区/会话文件，然后启动 Gateway 网关并运行 `openclaw health`。 +此脚本会通过伪终端驱动交互式向导，验证 config/workspace/session 文件，然后启动 Gateway 网关并运行 `openclaw health`。 -## 二维码导入 smoke 测试（Docker） +## 二维码导入冒烟测试（Docker） -确保 `qrcode-terminal` 可在受支持的 Docker Node 运行时中加载（默认 Node 24，兼容 Node 22）： +确保 `qrcode-terminal` 能在受支持的 Docker Node 运行时下加载（默认 Node 24，兼容 Node 22）： ```bash pnpm test:docker:qr diff --git a/docs/zh-CN/reference/token-use.md b/docs/zh-CN/reference/token-use.md index 4c77caa03..ad945d17a 100644 --- a/docs/zh-CN/reference/token-use.md +++ b/docs/zh-CN/reference/token-use.md @@ -1,121 +1,109 @@ --- read_when: - - 解释 token 使用量、成本或上下文窗口时 - - 调试上下文增长或压缩行为时 -summary: OpenClaw 如何构建提示词上下文，以及如何报告 token 使用量和成本 -title: Token 使用量和成本 + - 解释 token 用量、成本或上下文窗口 + - 调试上下文增长或压缩行为 +summary: OpenClaw 如何构建提示词上下文并报告 token 用量与成本 +title: Token 用量与成本 x-i18n: - generated_at: "2026-04-05T10:09:10Z" + generated_at: "2026-04-06T15:31:22Z" model: gpt-5.4 provider: openai - source_hash: 14e7a0ac0311298cf1484d663799a3f5a9687dd5afc9702233e983aba1979f1d + source_hash: 0683693d6c6fcde7d5fba236064ba97dd4b317ae6bea3069db969fcd178119d9 source_path: reference/token-use.md workflow: 15 --- -# Token 使用量和成本 +# Token 用量与成本 -OpenClaw 跟踪的是 **token**，而不是字符。token 因模型而异，但大多数 -OpenAI 风格模型对英文文本的平均值约为每个 token 4 个字符。 +OpenClaw 跟踪的是 **token**，而不是字符。Token 是模型特定的，但大多数 OpenAI 风格模型对英文文本的平均值约为每个 token 4 个字符。 ## 系统提示词是如何构建的 -OpenClaw 会在每次运行时组装自己的系统提示词。其中包括： +OpenClaw 会在每次运行时组装自己的系统提示词。它包括： -- 工具列表 + 简短说明 +- 工具列表 + 简短描述 - Skills 列表（仅元数据；说明会按需通过 `read` 加载） -- 自更新说明 -- 工作区 + bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、新建时的 `BOOTSTRAP.md`，以及存在时的 `MEMORY.md` 或作为小写回退的 `memory.md`）。大文件会被 `agents.defaults.bootstrapMaxChars` 截断（默认值：20000），而 bootstrap 注入总量受 `agents.defaults.bootstrapTotalMaxChars` 限制（默认值：150000）。`memory/*.md` 文件通过 memory 工具按需加载，不会自动注入。 +- 自我更新说明 +- 工作区 + bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、新建时的 `BOOTSTRAP.md`，以及在存在时的 `MEMORY.md` 或作为小写回退的 `memory.md`）。大文件会被 `agents.defaults.bootstrapMaxChars` 截断（默认：20000），bootstrap 注入总量受 `agents.defaults.bootstrapTotalMaxChars` 限制（默认：150000）。`memory/*.md` 文件通过 memory 工具按需加载，不会自动注入。 - 时间（UTC + 用户时区） - 回复标签 + heartbeat 行为 -- 运行时元数据（主机/操作系统/模型/thinking） +- 运行时元数据（主机/OS/模型/thinking） -完整拆解请参见 [System Prompt](/zh-CN/concepts/system-prompt)。 +完整拆分请参见 [System Prompt](/zh-CN/concepts/system-prompt)。 ## 什么会计入上下文窗口 模型接收到的所有内容都会计入上下文限制： - 系统提示词（上面列出的所有部分） -- 对话历史（用户 + 助手消息） +- 对话历史（用户 + assistant 消息） - 工具调用和工具结果 -- 附件/transcript（图像、音频、文件） -- 压缩摘要和剪枝产物 -- 提供商包装层或安全标头（不可见，但仍会计入） +- 附件/转录内容（图片、音频、文件） +- 压缩摘要和裁剪产物 +- provider 包装器或安全标头（不可见，但仍会计入） -对于图像，OpenClaw 会在调用提供商之前下采样 transcript/工具图像载荷。 -请使用 `agents.defaults.imageMaxDimensionPx`（默认值：`1200`）进行调节： +对于图片，OpenClaw 会在调用 provider 之前对转录/工具图片负载进行缩放。使用 `agents.defaults.imageMaxDimensionPx`（默认：`1200`）来调整： -- 较低的值通常会减少视觉 token 用量和载荷大小。 -- 较高的值会保留更多视觉细节，适用于 OCR/UI 密集型截图。 +- 较低的值通常会减少视觉 token 用量和负载大小。 +- 较高的值会为 OCR/UI 密集型截图保留更多视觉细节。 -如需查看实用拆解（按每个注入文件、工具、Skills 和系统提示词大小），请使用 `/context list` 或 `/context detail`。参见 [Context](/zh-CN/concepts/context)。 +如需查看实用拆分（按注入文件、工具、Skills 和系统提示词大小），请使用 `/context list` 或 `/context detail`。参见 [Context](/zh-CN/concepts/context)。 -## 如何查看当前 token 使用量 +## 如何查看当前 token 用量 -在聊天中使用以下命令： +在聊天中使用这些命令： -- `/status` → **富含 emoji 的状态卡片**，显示会话模型、上下文使用量、 - 上次响应的输入/输出 token，以及**估算成本**（仅 API 密钥）。 -- `/usage off|tokens|full` → 在每条回复后附加一个**按响应统计的使用量页脚**。 +- `/status` → 显示**富含 emoji 的状态卡片**，包含会话模型、上下文用量、上次响应的输入/输出 token，以及**估算成本**（仅 API 密钥）。 +- `/usage off|tokens|full` → 在每条回复后附加**按响应统计的用量页脚**。 - 按会话持久化（存储为 `responseUsage`）。 - - OAuth 认证**会隐藏成本**（仅显示 token）。 -- `/usage cost` → 从 OpenClaw 会话日志中显示本地成本汇总。 + - OAuth 身份验证**隐藏成本**（仅显示 token）。 +- `/usage cost` → 显示基于 OpenClaw 会话日志的本地成本摘要。 其他界面： - **TUI/Web TUI：** 支持 `/status` + `/usage`。 -- **CLI：** `openclaw status --usage` 和 `openclaw channels list` 会显示 - 规范化后的提供商配额窗口（`X% left`，而不是按响应成本）。 - 当前支持使用量窗口的提供商有：Anthropic、GitHub Copilot、Gemini CLI、 +- **CLI：** `openclaw status --usage` 和 `openclaw channels list` 显示 + 标准化后的 provider 配额窗口（`X% left`，而不是按响应成本）。 + 当前支持用量窗口的 provider：Anthropic、GitHub Copilot、Gemini CLI、 OpenAI Codex、MiniMax、Xiaomi 和 z.ai。 -使用量界面在显示前会规范化常见的提供商原生字段别名。 +用量界面会在显示前标准化常见的 provider 原生字段别名。 对于 OpenAI 系列 Responses 流量，这包括 `input_tokens` / -`output_tokens` 以及 `prompt_tokens` / `completion_tokens`，因此传输层特定的 -字段名不会改变 `/status`、`/usage` 或会话摘要。 -Gemini CLI JSON 使用量也会被规范化：回复文本来自 `response`，而 -`stats.cached` 会映射到 `cacheRead`；当 CLI 省略显式的 `stats.input` -字段时，会使用 `stats.input_tokens - stats.cached`。 -对于原生 OpenAI 系列 Responses 流量，WebSocket/SSE 的使用量别名也会以相同方式规范化，并且当 -`total_tokens` 缺失或为 `0` 时，总量会回退到规范化后的输入 + 输出。 -当当前会话快照较为稀疏时，`/status` 和 `session_status` 还可以 -从最近的 transcript 使用日志中恢复 token/cache 计数器和当前运行时模型标签。现有的非零实时值仍优先于 transcript 回退值，而当存储总量缺失或更小时，较大的面向提示词的 transcript -总量可以胜出。 -提供商配额窗口的使用量认证在可用时来自提供商专用 hook；否则 OpenClaw 会回退到从认证配置文件、环境或配置中匹配 OAuth/API 密钥凭据。 +`output_tokens` 和 `prompt_tokens` / `completion_tokens`，因此特定传输的字段名不会改变 `/status`、`/usage` 或会话摘要。 +Gemini CLI JSON 用量也会被标准化：回复文本来自 `response`，并且 `stats.cached` 会映射为 `cacheRead`，当 CLI 省略显式 `stats.input` 字段时，会使用 `stats.input_tokens - stats.cached`。 +对于原生 OpenAI 系列 Responses 流量，WebSocket/SSE 用量别名也会以相同方式标准化，当 `total_tokens` 缺失或为 `0` 时，总量会回退到标准化后的输入 + 输出。 +当当前会话快照信息较少时，`/status` 和 `session_status` 还可以从最近的转录用量日志中恢复 token/缓存计数器和活动运行时模型标签。现有的非零实时值仍然优先于转录回退值，而当存储总量缺失或更小时，较大的面向提示词的转录总量可以胜出。 +用于 provider 配额窗口的用量身份验证优先来自 provider 特定 hooks；否则 OpenClaw 会回退为使用来自 auth profile、环境变量或配置中匹配的 OAuth/API 密钥凭证。 ## 成本估算（显示时） -成本根据你的模型定价配置进行估算： +成本是根据你的模型定价配置估算的： ``` models.providers..models[].cost ``` 这些值表示 `input`、`output`、`cacheRead` 和 -`cacheWrite` 的**每 100 万 token 美元价格**。如果缺少定价信息，OpenClaw 只显示 token。OAuth token -永远不会显示美元成本。 +`cacheWrite` 的**每 100 万 token 的美元价格**。如果缺少定价，OpenClaw 只显示 token。OAuth token 永远不会显示美元成本。 -## 缓存 TTL 和剪枝影响 +## 缓存 TTL 和裁剪的影响 -提供商提示词缓存仅在缓存 TTL 窗口内生效。OpenClaw 可选运行**cache-ttl 剪枝**：当缓存 TTL 过期后，它会剪枝会话，然后重置缓存窗口，这样后续请求就可以复用刚刚重新缓存的上下文，而不必对完整历史重新缓存。这样在会话空闲超过 TTL 后，可以保持较低的缓存写入成本。 +Provider 提示词缓存只会在缓存 TTL 窗口内生效。OpenClaw 可以选择运行**缓存 TTL 裁剪**：一旦缓存 TTL 过期，它就会裁剪会话，然后重置缓存窗口，这样后续请求就能重用刚刚重新缓存的上下文，而不是重新缓存完整历史。这可以在会话空闲超过 TTL 时降低缓存写入成本。 请在 [Gateway 网关配置](/zh-CN/gateway/configuration) 中进行配置，并在 -[Session pruning](/zh-CN/concepts/session-pruning) 中查看行为细节。 +[会话裁剪](/zh-CN/concepts/session-pruning) 中查看行为细节。 -Heartbeat 可以在空闲间隔之间保持缓存**温热**。如果你的模型缓存 TTL -是 `1h`，将 heartbeat 间隔设置为略低于该值（例如 `55m`）可以避免重新缓存完整提示词，从而降低缓存写入成本。 +Heartbeat 可以在空闲间隔期间保持缓存**预热**。如果你的模型缓存 TTL +是 `1h`，将 heartbeat 间隔设置为略低于该值（例如 `55m`）可以避免重新缓存完整提示词，从而减少缓存写入成本。 -在多智能体设置中，你可以保留一个共享模型配置，并通过 -`agents.list[].params.cacheRetention` 按智能体调节缓存行为。 +在多智能体设置中，你可以保留一个共享模型配置，并通过 `agents.list[].params.cacheRetention` 为每个智能体调整缓存行为。 -如需查看逐项配置指南，请参见 [Prompt Caching](/reference/prompt-caching)。 +如需完整的逐项参数指南，请参见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -对于 Anthropic API 定价，缓存读取显著便宜于输入 -token，而缓存写入则按更高倍数计费。最新费率和 TTL 倍率请参见 Anthropic 的提示词缓存定价： +对于 Anthropic API 定价，缓存读取比输入 token 便宜得多，而缓存写入则按更高倍数计费。最新费率和 TTL 倍数请参见 Anthropic 的提示词缓存定价： [https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching) -### 示例：使用 heartbeat 保持 1 小时缓存温热 +### 示例：使用 heartbeat 保持 1 小时缓存预热 ```yaml agents: @@ -130,7 +118,7 @@ agents: every: "55m" ``` -### 示例：按智能体使用不同缓存策略的混合流量 +### 示例：带有按智能体缓存策略的混合流量 ```yaml agents: @@ -145,19 +133,18 @@ agents: - id: "research" default: true heartbeat: - every: "55m" # 为深度会话保持长期缓存温热 + every: "55m" # 为深度会话保持长缓存预热 - id: "alerts" params: cacheRetention: "none" # 避免为突发通知写入缓存 ``` -`agents.list[].params` 会合并到所选模型的 `params` 之上，因此你可以 -只覆盖 `cacheRetention`，并保持其他模型默认值不变。 +`agents.list[].params` 会在所选模型的 `params` 之上合并，因此你可以只覆盖 `cacheRetention`，而让其他模型默认值保持不变。 ### 示例：启用 Anthropic 1M 上下文 beta 标头 -Anthropic 的 1M 上下文窗口当前受 beta 限制。在受支持的 Opus -或 Sonnet 模型上启用 `context1m` 后，OpenClaw 可以注入所需的 +Anthropic 的 1M 上下文窗口当前仍受 beta 限制。启用受支持的 Opus +或 Sonnet 模型上的 `context1m` 后，OpenClaw 可以注入所需的 `anthropic-beta` 值。 ```yaml @@ -171,23 +158,18 @@ agents: 这会映射到 Anthropic 的 `context-1m-2025-08-07` beta 标头。 -仅当该模型条目上设置了 `context1m: true` 时，这一行为才会生效。 +这仅在该模型条目上设置了 `context1m: true` 时生效。 -要求：该凭据必须有资格使用长上下文（API 密钥 -计费，或启用了 Extra Usage 的 OpenClaw Claude 登录路径）。否则， -Anthropic 会响应 -`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。 +要求：该凭证必须具备长上下文使用资格。否则，Anthropic 会对该请求返回 provider 侧速率限制错误。 -如果你使用 OAuth/订阅 token（`sk-ant-oat-*`）对 Anthropic 进行认证， -OpenClaw 会跳过 `context-1m-*` beta 标头，因为 Anthropic 当前 -会以 HTTP 401 拒绝这种组合。 +如果你使用 OAuth/订阅 token（`sk-ant-oat-*`）对 Anthropic 进行身份验证，OpenClaw 会跳过 `context-1m-*` beta 标头，因为 Anthropic 当前会以 HTTP 401 拒绝这种组合。 -## 减少 token 压力的建议 +## 减少 token 压力的技巧 -- 使用 `/compact` 总结长会话。 -- 在你的工作流中裁剪大型工具输出。 -- 对于截图较多的会话，降低 `agents.defaults.imageMaxDimensionPx`。 +- 使用 `/compact` 总结较长的会话。 +- 在你的工作流中裁剪较大的工具输出。 +- 对截图密集型会话降低 `agents.defaults.imageMaxDimensionPx`。 - 保持 skill 描述简短（skill 列表会被注入到提示词中）。 -- 对于冗长、探索性的工作，优先使用较小模型。 +- 对冗长、探索性工作优先使用更小的模型。 -确切的 skill 列表开销公式请参见 [Skills](/zh-CN/tools/skills)。 +精确的 skill 列表开销公式请参见 [Skills](/zh-CN/tools/skills)。 diff --git a/docs/zh-CN/reference/wizard.md b/docs/zh-CN/reference/wizard.md index 43aae22d7..23246f52f 100644 --- a/docs/zh-CN/reference/wizard.md +++ b/docs/zh-CN/reference/wizard.md @@ -4,13 +4,13 @@ read_when: - 使用非交互模式自动化新手引导 - 调试新手引导行为 sidebarTitle: Onboarding Reference -summary: CLI 新手引导完整参考：每一步、每个标志与每个配置字段 +summary: CLI 新手引导的完整参考：每一步、每个标志和每个配置字段 title: 新手引导参考 x-i18n: - generated_at: "2026-04-05T17:49:36Z" + generated_at: "2026-04-06T15:31:48Z" model: gpt-5.4 provider: openai - source_hash: e02a4da4a39ba335199095723f5d3b423671eb12efc2d9e4f9e48c1e8ee18419 + source_hash: a142b9ec4323fabb9982d05b64375d2b4a4007dffc910acbee3a38ff871a7236 source_path: reference/wizard.md workflow: 15 --- @@ -20,136 +20,136 @@ x-i18n: 这是 `openclaw onboard` 的完整参考。 如需高层概览，请参见 [新手引导（CLI）](/zh-CN/start/wizard)。 -## 流程细节（本地模式） +## 流程详情（本地模式） - - 如果存在 `~/.openclaw/openclaw.json`，请选择 **保留 / 修改 / 重置**。 + - 如果 `~/.openclaw/openclaw.json` 存在，可选择 **保留 / 修改 / 重置**。 - 重新运行新手引导**不会**清除任何内容，除非你明确选择 **重置** （或传入 `--reset`）。 - - CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full` - 可额外移除工作区。 - - 如果配置无效或包含旧版键，向导会停止并要求 - 你先运行 `openclaw doctor`，然后才能继续。 + - CLI `--reset` 默认范围是 `config+creds+sessions`；使用 `--reset-scope full` + 还会删除工作区。 + - 如果配置无效或包含旧版键名，向导会停止并要求 + 你先运行 `openclaw doctor` 再继续。 - 重置使用 `trash`（绝不使用 `rm`），并提供以下范围： - 仅配置 - 配置 + 凭证 + 会话 - - 完全重置（也会移除工作区） + - 完全重置（也会删除工作区） - - - **Anthropic API 密钥**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示输入密钥，然后保存供守护进程使用。 - - **Anthropic API 密钥**：是新手引导 / 配置中推荐的 Anthropic 助手选择。 - - **Anthropic setup-token（旧版 / 手动）**：已重新在新手引导 / 配置中提供，但 Anthropic 已通知 OpenClaw 用户，OpenClaw 的 Claude 登录路径被视为第三方封装工具用法，并且 Claude 账户需要启用 **Extra Usage**。 - - **OpenAI Code（Codex）订阅（Codex CLI）**：如果存在 `~/.codex/auth.json`，新手引导可以复用它。被复用的 Codex CLI 凭证仍由 Codex CLI 管理；过期时，OpenClaw 会优先重新读取该来源，并且当提供商可以刷新它时，会将刷新后的凭证写回 Codex 存储，而不是自行接管。 + + - **Anthropic API 密钥**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示输入密钥，然后保存以供守护进程使用。 + - **Anthropic API 密钥**：在新手引导/配置中是 Anthropic 助手的首选选项。 + - **Anthropic setup-token**：在新手引导/配置中仍然可用，不过 OpenClaw 现在在可用时更倾向于复用 Claude CLI。 + - **OpenAI Code（Codex）订阅（Codex CLI）**：如果 `~/.codex/auth.json` 存在，新手引导可以复用它。被复用的 Codex CLI 凭证仍由 Codex CLI 管理；过期时，OpenClaw 会先重新读取该来源，并在提供商能够刷新时，将刷新后的凭证写回 Codex 存储，而不是自行接管。 - **OpenAI Code（Codex）订阅（OAuth）**：浏览器流程；粘贴 `code#state`。 - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。 - - **OpenAI API 密钥**：如果存在则使用 `OPENAI_API_KEY`，否则提示输入密钥，然后将其存储到认证配置文件中。 + - **OpenAI API 密钥**：如果存在则使用 `OPENAI_API_KEY`，否则提示输入密钥，然后将其存储到凭证配置文件中。 - 当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.4`。 - - **xAI（Grok）API 密钥**：提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。 + - **xAI（Grok）API 密钥**：提示输入 `XAI_API_KEY` 并将 xAI 配置为模型提供商。 - **OpenCode**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，可在 https://opencode.ai/auth 获取），并让你选择 Zen 或 Go 目录。 - - **Ollama**：提示输入 Ollama 基础 URL，提供 **Cloud + Local** 或 **Local** 模式，发现可用模型，并在需要时自动拉取所选本地模型。 + - **Ollama**：提示输入 Ollama base URL，提供 **Cloud + Local** 或 **Local** 模式，发现可用模型，并在需要时自动拉取所选本地模型。 - 更多细节：[Ollama](/zh-CN/providers/ollama) - **API 密钥**：为你存储该密钥。 - **Vercel AI Gateway（多模型代理）**：提示输入 `AI_GATEWAY_API_KEY`。 - 更多细节：[Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway) - **Cloudflare AI Gateway**：提示输入 Account ID、Gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。 - 更多细节：[Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway) - - **MiniMax**：配置会自动写入；托管默认值为 `MiniMax-M2.7`。 + - **MiniMax**：会自动写入配置；托管默认模型是 `MiniMax-M2.7`。 API 密钥设置使用 `minimax/...`，而 OAuth 设置使用 `minimax-portal/...`。 - 更多细节：[MiniMax](/zh-CN/providers/minimax) - - **StepFun**：会为中国区或全球端点的 StepFun 标准版或 Step Plan 自动写入配置。 + - **StepFun**：会为中国或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。 - 标准版当前包含 `step-3.5-flash`，Step Plan 还包含 `step-3.5-flash-2603`。 - 更多细节：[StepFun](/zh-CN/providers/stepfun) - - **Synthetic（兼容 Anthropic）**：提示输入 `SYNTHETIC_API_KEY`。 + - **Synthetic（Anthropic 兼容）**：提示输入 `SYNTHETIC_API_KEY`。 - 更多细节：[Synthetic](/zh-CN/providers/synthetic) - - **Moonshot（Kimi K2）**：配置会自动写入。 - - **Kimi Coding**：配置会自动写入。 + - **Moonshot（Kimi K2）**：会自动写入配置。 + - **Kimi Coding**：会自动写入配置。 - 更多细节：[Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot) - - **跳过**：暂不配置认证。 - - 从检测到的选项中选择一个默认模型（或手动输入 provider/model）。为了获得最佳质量并降低提示词注入风险，请选择你提供商栈中可用的最新一代最强模型。 - - 新手引导会执行模型检查，并在已配置模型未知或缺少认证时发出警告。 + - **跳过**：暂不配置凭证。 + - 从检测到的选项中选择一个默认模型（或手动输入 provider/model）。为了获得最佳质量并降低提示注入风险，请选择你提供商栈中可用的最强最新一代模型。 + - 新手引导会执行模型检查，并在配置的模型未知或缺少凭证时发出警告。 - API 密钥存储模式默认使用明文 auth-profile 值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。 - - 认证配置文件位于 `~/.openclaw/agents//agent/auth-profiles.json`（API 密钥 + OAuth）。`~/.openclaw/credentials/oauth.json` 仅用于旧版导入。 + - 凭证配置文件位于 `~/.openclaw/agents//agent/auth-profiles.json`（API 密钥 + OAuth）。`~/.openclaw/credentials/oauth.json` 仅用于导入旧版数据。 - 更多细节：[/concepts/oauth](/zh-CN/concepts/oauth) - 无头 / 服务器提示：请在有浏览器的机器上完成 OAuth，然后复制 + 无头/服务器提示：可先在有浏览器的机器上完成 OAuth，然后复制 该智能体的 `auth-profiles.json`（例如 `~/.openclaw/agents//agent/auth-profiles.json`，或对应的 `$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机上。`credentials/oauth.json` - 仅是旧版导入来源。 + 只是旧版导入来源。 - - 默认值为 `~/.openclaw/workspace`（可配置）。 - - 会为智能体 bootstrap 仪式预置所需的工作区文件。 - - 完整工作区布局与备份指南：[智能体工作区](/zh-CN/concepts/agent-workspace) + - 默认是 `~/.openclaw/workspace`（可配置）。 + - 会初始化智能体 bootstrap ritual 所需的工作区文件。 + - 完整工作区布局和备份指南：[智能体工作区](/zh-CN/concepts/agent-workspace) - - 端口、绑定、认证模式、Tailscale 暴露。 - - 认证建议：即使在 loopback 模式下也保留 **Token**，这样本地 WS 客户端也必须认证。 + - 端口、绑定、凭证模式、Tailscale 暴露。 + - 凭证建议：即使是 loopback，也请保留 **Token**，这样本地 WS 客户端仍必须进行身份验证。 - 在 token 模式下，交互式设置提供： - - **生成 / 存储明文 token**（默认） + - **生成/存储明文 token**（默认） - **使用 SecretRef**（可选启用） - - 快速开始会在新手引导探测 / 仪表板 bootstrap 期间，复用 `env`、`file` 和 `exec` 提供商中现有的 `gateway.auth.token` SecretRef。 - - 如果该 SecretRef 已配置但无法解析，新手引导会尽早失败并给出明确修复信息，而不是静默降级运行时认证。 - - 在 password 模式下，交互式设置也支持明文或 SecretRef 存储。 - - 非交互式 token SecretRef 路径：`--gateway-token-ref-env `。 + - 快速开始会在新手引导探测/仪表板 bootstrap 过程中复用现有的 `gateway.auth.token` SecretRef，支持 `env`、`file` 和 `exec` 提供商。 + - 如果已配置该 SecretRef 但无法解析，新手引导会尽早失败并给出清晰的修复信息，而不是静默降级运行时凭证。 + - 在密码模式下，交互式设置也支持明文或 SecretRef 存储。 + - 非交互 token SecretRef 路径：`--gateway-token-ref-env `。 - 要求新手引导进程环境中存在非空环境变量。 - - 不能与 `--gateway-token` 同时使用。 - - 仅当你完全信任每个本地进程时才禁用认证。 - - 非 loopback 绑定仍然需要认证。 + - 不能与 `--gateway-token` 一起使用。 + - 仅当你完全信任所有本地进程时才禁用凭证。 + - 非 loopback 绑定仍然需要凭证。 - [WhatsApp](/zh-CN/channels/whatsapp)：可选 QR 登录。 - - [Telegram](/zh-CN/channels/telegram)：机器人 token。 - - [Discord](/zh-CN/channels/discord)：机器人 token。 - - [Google Chat](/zh-CN/channels/googlechat)：服务账户 JSON + webhook audience。 - - [Mattermost](/zh-CN/channels/mattermost)（插件）：机器人 token + 基础 URL。 - - [Signal](/zh-CN/channels/signal)：可选安装 `signal-cli` + 账户配置。 - - [BlueBubbles](/zh-CN/channels/bluebubbles)：**iMessage 的推荐方案**；服务器 URL + 密码 + webhook。 + - [Telegram](/zh-CN/channels/telegram)：机器人令牌。 + - [Discord](/zh-CN/channels/discord)：机器人令牌。 + - [Google Chat](/zh-CN/channels/googlechat)：服务账号 JSON + webhook audience。 + - [Mattermost](/zh-CN/channels/mattermost)（插件）：机器人令牌 + base URL。 + - [Signal](/zh-CN/channels/signal)：可选 `signal-cli` 安装 + 账户配置。 + - [BlueBubbles](/zh-CN/channels/bluebubbles)：**推荐用于 iMessage**；服务器 URL + 密码 + webhook。 - [iMessage](/zh-CN/channels/imessage)：旧版 `imsg` CLI 路径 + DB 访问。 - - 私信安全：默认使用配对。首次私信会发送验证码；通过 `openclaw pairing approve ` 批准，或使用允许列表。 + - 私信安全：默认启用配对。首次私信会发送一个代码；通过 `openclaw pairing approve ` 批准，或使用允许列表。 - - 选择受支持的提供商，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web 搜索、Perplexity、SearXNG 或 Tavily（或跳过）。 - - 基于 API 的提供商可使用环境变量或现有配置进行快速设置；无密钥提供商则使用其提供商特定的前置条件。 + - 选择一个受支持的提供商，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web 搜索、Perplexity、SearXNG 或 Tavily（也可以跳过）。 + - 基于 API 的提供商可以使用环境变量或现有配置快速设置；无需密钥的提供商则使用其各自的前置条件。 - 使用 `--skip-search` 跳过。 - 稍后配置：`openclaw configure --section web`。 - + - macOS：LaunchAgent - - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未内置提供）。 + - 需要已登录的用户会话；对于无头场景，请使用自定义 LaunchDaemon（未内置）。 - Linux（以及通过 WSL2 的 Windows）：systemd 用户单元 - - 新手引导会尝试启用 `loginctl enable-linger `，以便 Gateway 网关在登出后继续运行。 - - 可能会提示输入 sudo（写入 `/var/lib/systemd/linger`）；它会先尝试不使用 sudo。 - - **运行时选择：** Node（推荐；WhatsApp / Telegram 必需）。**不推荐** Bun。 - - 如果 token 认证需要 token 且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将解析后的明文 token 值持久化到 supervisor 服务环境元数据中。 - - 如果 token 认证需要 token 且已配置的 token SecretRef 未解析，守护进程安装会被阻止，并给出可操作的指导。 - - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，而 `gateway.auth.mode` 未设置，则在显式设置模式之前会阻止守护进程安装。 + - 新手引导会尝试通过 `loginctl enable-linger ` 启用 lingering，这样 Gateway 网关在登出后仍能保持运行。 + - 可能会提示 sudo（会写入 `/var/lib/systemd/linger`）；会先尝试不使用 sudo。 + - **运行时选择：** Node（推荐；WhatsApp/Telegram 必需）。**不推荐** Bun。 + - 如果 token 凭证需要 token 且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会把解析后的明文 token 值持久化到 supervisor 服务环境元数据中。 + - 如果 token 凭证需要 token 且配置的 token SecretRef 未解析，守护进程安装会被阻止，并给出可操作的指导。 + - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，而 `gateway.auth.mode` 未设置，则会阻止守护进程安装，直到明确设置 mode。 - 启动 Gateway 网关（如有需要）并运行 `openclaw health`。 - - 提示：`openclaw status --deep` 会将在线 Gateway 网关健康探测添加到状态输出中，包括受支持时的渠道探测（需要可访问的 Gateway 网关）。 + - 提示：`openclaw status --deep` 会将 live Gateway 网关健康探测添加到状态输出中，在支持时也包括渠道探测（需要能访问到 Gateway 网关）。 - - 读取可用 Skills 并检查要求。 - - 让你选择一个节点管理器：**npm / pnpm**（不推荐 bun）。 - - 安装可选依赖（某些在 macOS 上使用 Homebrew）。 + - 读取可用的 Skills 并检查要求。 + - 让你选择一个 node 管理器：**npm / pnpm**（不推荐 bun）。 + - 安装可选依赖（有些会在 macOS 上使用 Homebrew）。 - - 摘要 + 后续步骤，包括 iOS / Android / macOS 应用以启用额外功能。 + - 显示摘要和后续步骤，包括 iOS/Android/macOS 应用以启用更多功能。 -如果未检测到 GUI，新手引导会打印用于访问 Control UI 的 SSH 端口转发说明，而不是打开浏览器。 -如果缺少 Control UI 资源，新手引导会尝试构建它们；回退命令为 `pnpm ui:build`（会自动安装 UI 依赖）。 +如果未检测到 GUI，新手引导会打印用于 Control UI 的 SSH 端口转发说明，而不是打开浏览器。 +如果缺少 Control UI 资源，新手引导会尝试构建它们；回退命令是 `pnpm ui:build`（会自动安装 UI 依赖）。 ## 非交互模式 -使用 `--non-interactive` 可自动化或脚本化新手引导： +使用 `--non-interactive` 来自动化或脚本化新手引导： ```bash openclaw onboard --non-interactive \ @@ -163,7 +163,7 @@ openclaw onboard --non-interactive \ --skip-skills ``` -添加 `--json` 可获得机器可读摘要。 +添加 `--json` 可获得机器可读的摘要。 非交互模式中的 Gateway 网关 token SecretRef： @@ -182,7 +182,7 @@ openclaw onboard --non-interactive \ `--json` **不**意味着非交互模式。脚本中请使用 `--non-interactive`（以及 `--workspace`）。 -提供商特定命令示例位于 [CLI 自动化](/zh-CN/start/wizard-cli-automation#provider-specific-examples)。 +提供商专用命令示例位于 [CLI 自动化](/zh-CN/start/wizard-cli-automation#provider-specific-examples)。 本参考页用于说明标志语义和步骤顺序。 ### 添加智能体（非交互） @@ -196,23 +196,23 @@ openclaw agents add work \ --json ``` -## Gateway 向导 RPC +## Gateway 网关向导 RPC -Gateway 网关通过 RPC 公开新手引导流程（`wizard.start`、`wizard.next`、`wizard.cancel`、`wizard.status`）。 -客户端（macOS 应用、Control UI）可以渲染各步骤，而无需重新实现新手引导逻辑。 +Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.next`、`wizard.cancel`、`wizard.status`）。 +客户端（macOS 应用、Control UI）可以渲染步骤，而无需重新实现新手引导逻辑。 ## Signal 设置（signal-cli） 新手引导可以从 GitHub releases 安装 `signal-cli`： -- 下载适当的发布资源。 -- 将其存储到 `~/.openclaw/tools/signal-cli//` 下。 +- 下载合适的发布资源。 +- 将其存储到 `~/.openclaw/tools/signal-cli//`。 - 将 `channels.signal.cliPath` 写入你的配置。 说明： - JVM 构建需要 **Java 21**。 -- 如可用，则使用原生构建。 +- 在可用时会使用原生构建。 - Windows 使用 WSL2；`signal-cli` 安装会在 WSL 内遵循 Linux 流程。 ## 向导会写入什么 @@ -221,14 +221,14 @@ Gateway 网关通过 RPC 公开新手引导流程（`wizard.start`、`wizard.nex - `agents.defaults.workspace` - `agents.defaults.model` / `models.providers`（如果选择了 Minimax） -- `tools.profile`（本地新手引导在未设置时默认为 `"coding"`；现有显式值会被保留） -- `gateway.*`（模式、绑定、认证、tailscale） +- `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有的显式值会被保留） +- `gateway.*`（mode、bind、auth、tailscale） - `session.dmScope`（行为细节：[CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals)） - `channels.telegram.botToken`、`channels.discord.token`、`channels.matrix.*`、`channels.signal.*`、`channels.imessage.*` -- 当你在提示中选择启用时，写入渠道允许列表（Slack / Discord / Matrix / Microsoft Teams）（名称会在可能时解析为 ID）。 +- 当你在提示中选择启用时，会写入渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）（在可能时会将名称解析为 ID）。 - `skills.install.nodeManager` - `setup --node-manager` 接受 `npm`、`pnpm` 或 `bun`。 - - 手动配置仍可通过直接设置 `skills.install.nodeManager` 来使用 `yarn`。 + - 手动配置仍可通过直接设置 `skills.install.nodeManager` 使用 `yarn`。 - `wizard.lastRunAt` - `wizard.lastRunVersion` - `wizard.lastRunCommit` @@ -237,16 +237,16 @@ Gateway 网关通过 RPC 公开新手引导流程（`wizard.start`、`wizard.nex `openclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。 -WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp//` 下。 +WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp//`。 会话存储在 `~/.openclaw/agents//sessions/` 下。 -某些渠道以插件形式提供。当你在设置期间选择其中之一时，新手引导 -会先提示安装它（npm 或本地路径），然后才能配置。 +某些渠道以插件形式交付。当你在设置期间选择其中一个时，新手引导 +会先提示安装它（npm 或本地路径），然后才能进行配置。 ## 相关文档 - 新手引导概览：[新手引导（CLI）](/zh-CN/start/wizard) - macOS 应用新手引导：[新手引导](/zh-CN/start/onboarding) -- 配置参考：[Gateway 配置](/zh-CN/gateway/configuration) +- 配置参考：[Gateway 网关配置](/zh-CN/gateway/configuration) - 提供商：[WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord)、[Google Chat](/zh-CN/channels/googlechat)、[Signal](/zh-CN/channels/signal)、[BlueBubbles](/zh-CN/channels/bluebubbles)（iMessage）、[iMessage](/zh-CN/channels/imessage)（旧版） - Skills：[Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) diff --git a/docs/zh-CN/start/wizard-cli-automation.md b/docs/zh-CN/start/wizard-cli-automation.md index a60419ccd..68d25e093 100644 --- a/docs/zh-CN/start/wizard-cli-automation.md +++ b/docs/zh-CN/start/wizard-cli-automation.md @@ -1,15 +1,15 @@ --- read_when: - 你正在脚本或 CI 中自动化新手引导 - - 你需要特定提供商的非交互式示例 + - 你需要针对特定提供商的非交互式示例 sidebarTitle: CLI automation summary: 用于 OpenClaw CLI 的脚本化新手引导和智能体设置 title: CLI 自动化 x-i18n: - generated_at: "2026-04-05T17:49:19Z" + generated_at: "2026-04-06T15:31:32Z" model: gpt-5.4 provider: openai - source_hash: 878ea3fa9f2a75cff9f1a803ccb8a52a1219102e2970883ad18e3aaec5967fd2 + source_hash: bca2dd6e482a16b27284fc76319e936e8df0ff5558134827c19f6875436cc652 source_path: start/wizard-cli-automation.md workflow: 15 --- @@ -37,13 +37,13 @@ openclaw onboard --non-interactive \ --skip-skills ``` -添加 `--json` 可获得机器可读的摘要。 +添加 `--json` 以获得机器可读的摘要。 -使用 `--secret-input-mode ref` 可在认证配置文件中存储由环境变量支持的引用，而不是明文值。 +使用 `--secret-input-mode ref` 可将基于环境变量的引用存储到认证 profile 中，而不是存储明文值。 在新手引导流程中，支持在环境变量引用和已配置的提供商引用（`file` 或 `exec`）之间进行交互式选择。 在非交互式 `ref` 模式下，提供商环境变量必须在进程环境中设置。 -如果传入内联密钥 flag，但没有对应的环境变量，现在会快速失败。 +传入内联密钥标志但未设置对应环境变量时，现在会快速失败。 示例： @@ -55,10 +55,10 @@ openclaw onboard --non-interactive \ --accept-risk ``` -## 特定提供商示例 +## 提供商特定示例 - + ```bash openclaw onboard --non-interactive \ --mode local \ @@ -149,7 +149,7 @@ openclaw onboard --non-interactive \ --gateway-port 18789 \ --gateway-bind loopback ``` - 如需使用 Go 目录，请改为 `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"`。 + 如果要使用 Go catalog，请改为 `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"`。 ```bash @@ -176,7 +176,7 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - `--custom-api-key` 是可选的。如果省略，新手引导会检查 `CUSTOM_API_KEY`。 + `--custom-api-key` 是可选项。如果省略，新手引导会检查 `CUSTOM_API_KEY`。 ref 模式变体： @@ -194,17 +194,18 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - 在此模式下，新手引导会将 `apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。 + 在该模式下，新手引导会将 `apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。 -Anthropic setup-token 再次作为一种旧版 / 手动新手引导路径可用。 -使用它时，请预期 Anthropic 已告知 OpenClaw 用户，OpenClaw 的 Claude 登录路径需要 **Extra Usage**。在生产环境中，优先使用 Anthropic API key。 +Anthropic setup-token 仍然可作为受支持的新手引导令牌路径使用，但 OpenClaw 现在在可用时更优先使用 Claude CLI 复用。 +在生产环境中，优先使用 Anthropic API 密钥。 ## 添加另一个智能体 -使用 `openclaw agents add ` 创建一个具有独立工作区、会话和认证配置文件的单独智能体。不带 `--workspace` 运行会启动向导。 +使用 `openclaw agents add ` 创建一个单独的智能体，它拥有自己的工作区、 +会话和认证 profile。不带 `--workspace` 运行会启动向导。 ```bash openclaw agents add work \ @@ -224,8 +225,8 @@ openclaw agents add work \ 说明： - 默认工作区遵循 `~/.openclaw/workspace-`。 -- 添加 `bindings` 可路由入站消息（向导可以处理这个）。 -- 非交互式 flag：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。 +- 添加 `bindings` 以路由入站消息（向导可以完成此操作）。 +- 非交互式标志：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。 ## 相关文档 diff --git a/docs/zh-CN/start/wizard.md b/docs/zh-CN/start/wizard.md index 86df036e2..9d98f8b5a 100644 --- a/docs/zh-CN/start/wizard.md +++ b/docs/zh-CN/start/wizard.md @@ -1,15 +1,15 @@ --- read_when: - 运行或配置 CLI 新手引导时 - - 设置新机器时 + - 设置一台新机器时 sidebarTitle: 'Onboarding: CLI' -summary: CLI 新手引导：为 Gateway 网关、工作区、渠道和 Skills 提供引导式设置 +summary: CLI 新手引导：用于 Gateway 网关、工作区、渠道和 Skills 的引导式设置 title: 设置向导（CLI） x-i18n: - generated_at: "2026-04-05T10:10:16Z" + generated_at: "2026-04-06T15:31:42Z" model: gpt-5.4 provider: openai - source_hash: 81e33fb4f8be30e7c2c6e0024bf9bdcf48583ca58eaf5fff5afd37a1cd628523 + source_hash: 6773b07afa8babf1b5ac94d857063d08094a962ee21ec96ca966e99ad57d107d source_path: start/wizard.md workflow: 15 --- @@ -17,8 +17,8 @@ x-i18n: # 设置向导（CLI） CLI 新手引导是在 macOS、 -Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的**推荐**方式。 -它会在一个引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、Skills +Linux 或 Windows（通过 WSL2，强烈推荐）上设置 OpenClaw 的**推荐**方式。 +它会通过一个引导式流程一次性配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、Skills 和工作区默认值。 ```bash @@ -26,11 +26,11 @@ openclaw onboard ``` -最快开始首次聊天的方式：打开控制 UI（无需设置任何渠道）。运行 -`openclaw dashboard` 并在浏览器中聊天。文档：[Dashboard](/web/dashboard)。 +最快开始第一次聊天的方法：打开 Control UI（无需设置任何渠道）。运行 +`openclaw dashboard` 并在浏览器中聊天。文档： [Dashboard](/web/dashboard)。 -稍后若要重新配置： +如果之后要重新配置： ```bash openclaw configure @@ -38,34 +38,34 @@ openclaw agents add ``` -`--json` 不意味着非交互模式。对于脚本，请使用 `--non-interactive`。 +`--json` 不代表非交互模式。对于脚本，请使用 `--non-interactive`。 CLI 新手引导包含一个 Web 搜索步骤，你可以在其中选择提供商， 例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、 -Ollama Web 搜索、Perplexity、SearXNG 或 Tavily。某些提供商需要 -API 密钥，而另一些不需要密钥。你也可以稍后使用 -`openclaw configure --section web` 进行配置。文档：[Web 工具](/zh-CN/tools/web)。 +Ollama Web 搜索、Perplexity、SearXNG 或 Tavily。有些提供商需要 +API key，而另一些不需要。你也可以之后再用 +`openclaw configure --section web` 进行配置。文档： [Web 工具](/zh-CN/tools/web)。 ## 快速开始 vs 高级 -新手引导会先从**快速开始**（默认值）和**高级**（完全控制）之间开始选择。 +新手引导一开始会让你选择**快速开始**（默认值）还是**高级**（完全控制）。 - 本地 Gateway 网关（loopback） - 默认工作区（或现有工作区） - Gateway 网关端口 **18789** - - Gateway 网关认证 **Token**（自动生成，即使在 loopback 上也是如此） - - 新本地设置的默认工具策略：`tools.profile: "coding"`（现有显式 profile 会被保留） - - 私信隔离默认值：本地新手引导在未设置时写入 `session.dmScope: "per-channel-peer"`。详情参见：[CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals) + - Gateway 网关认证 **Token**（即使在 loopback 上也会自动生成） + - 新本地设置的默认工具策略：`tools.profile: "coding"`（已有的显式 profile 会被保留） + - 私信隔离默认值：本地新手引导会在未设置时写入 `session.dmScope: "per-channel-peer"`。详情： [CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals) - Tailscale 暴露 **关闭** - - Telegram 和 WhatsApp 私信默认使用 **allowlist**（会提示你输入你的电话号码） + - Telegram + WhatsApp 私信默认使用 **allowlist**（系统会提示你输入手机号） - - 暴露每一个步骤（mode、workspace、gateway、channels、daemon、skills）。 + - 显示所有步骤（模式、工作区、Gateway 网关、渠道、守护进程、Skills）。 @@ -73,38 +73,38 @@ API 密钥，而另一些不需要密钥。你也可以稍后使用 **本地模式（默认）**会引导你完成以下步骤： -1. **模型/认证** —— 选择任意受支持的提供商/认证流程（API 密钥、OAuth 或提供商特定的手动认证），包括 Custom Provider - （OpenAI 兼容、Anthropic 兼容或 Unknown 自动检测）。选择一个默认模型。 - 安全说明：如果该智能体将运行工具或处理 webhook/hooks 内容，请优先选择可用的最新一代最强模型，并保持严格的工具策略。较弱/较旧的层级更容易受到 prompt injection 影响。 - 对于非交互式运行，`--secret-input-mode ref` 会在认证配置文件中存储由环境变量支持的引用，而不是明文 API 密钥值。 - 在非交互 `ref` 模式下，必须设置提供商环境变量；如果未设置该环境变量却传入内联密钥标志，则会快速失败。 - 在交互式运行中，选择密钥引用模式后，你可以选择指向环境变量或已配置的提供商引用（`file` 或 `exec`），并在保存前执行快速预检验证。 - 对于 Anthropic，交互式新手引导/配置会提供 **Anthropic Claude CLI** 作为本地回退方案，并将 **Anthropic API 密钥** 作为推荐的生产路径。Anthropic setup-token 也再次作为旧版/手动 OpenClaw 路径提供，并遵循 Anthropic 针对 OpenClaw 的 **Extra Usage** 计费预期。 -2. **工作区** —— 智能体文件的位置（默认 `~/.openclaw/workspace`）。会初始化 bootstrap 文件。 -3. **Gateway 网关** —— 端口、绑定地址、认证模式、Tailscale 暴露。 - 在交互式 token 模式下，可以选择默认的明文 token 存储，或选择使用 SecretRef。 +1. **模型/认证** — 选择任意受支持的提供商/认证流程（API key、OAuth 或提供商专用手动认证），包括 Custom Provider + （兼容 OpenAI、兼容 Anthropic，或 Unknown 自动检测）。选择一个默认模型。 + 安全说明：如果此智能体将运行工具或处理 webhook/hooks 内容，请优先选择当前最强的新一代模型，并保持严格的工具策略。较弱/较旧的层级更容易受到提示注入攻击。 + 对于非交互式运行，`--secret-input-mode ref` 会在认证 profile 中存储基于环境变量的引用，而不是明文 API key 值。 + 在非交互式 `ref` 模式下，必须设置提供商环境变量；如果传入内联 key flags 但未设置相应环境变量，将会快速失败。 + 在交互式运行中，选择 secret 引用模式后，你可以指向环境变量或已配置的提供商引用（`file` 或 `exec`），并在保存前进行快速预检验证。 + 对于 Anthropic，交互式新手引导/配置会将 **Anthropic Claude CLI** 作为首选本地路径，并将 **Anthropic API key** 作为推荐的生产路径。Anthropic setup-token 也仍然可作为受支持的 token 认证路径。 +2. **工作区** — 智能体文件的位置（默认 `~/.openclaw/workspace`）。会植入引导文件。 +3. **Gateway 网关** — 端口、绑定地址、认证模式、Tailscale 暴露。 + 在交互式 token 模式中，你可以选择默认的明文 token 存储，或改用 SecretRef。 非交互式 token SecretRef 路径：`--gateway-token-ref-env `。 -4. **渠道** —— 内置和内置打包的聊天渠道，例如 BlueBubbles、Discord、Feishu、Google Chat、Mattermost、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp 等。 -5. **守护进程** —— 安装 LaunchAgent（macOS）、systemd 用户单元（Linux/WSL2），或原生 Windows Scheduled Task，并提供按用户 Startup-folder 回退方案。 - 如果 token 认证需要 token 且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将解析出的 token 持久化到 supervisor 服务环境元数据中。 - 如果 token 认证需要 token 且已配置的 token SecretRef 未解析，守护进程安装会被阻止，并给出可操作的指导。 - 如果 `gateway.auth.token` 和 `gateway.auth.password` 都已配置，而 `gateway.auth.mode` 未设置，守护进程安装会被阻止，直到显式设置 mode。 -6. **健康检查** —— 启动 Gateway 网关并验证其正在运行。 -7. **Skills** —— 安装推荐的 Skills 和可选依赖。 +4. **渠道** — 内置和内置打包的聊天渠道，例如 BlueBubbles、Discord、Feishu、Google Chat、Mattermost、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp 等。 +5. **守护进程** — 安装 LaunchAgent（macOS）、systemd 用户单元（Linux/WSL2），或原生 Windows 计划任务，并提供按用户 Startup 文件夹回退方案。 + 如果 token 认证需要 token 且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将解析后的 token 持久化到 supervisor 服务环境元数据中。 + 如果 token 认证需要 token 且已配置的 token SecretRef 无法解析，守护进程安装将被阻止，并给出可执行的指引。 + 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但 `gateway.auth.mode` 未设置，守护进程安装将被阻止，直到显式设置 mode。 +6. **健康检查** — 启动 Gateway 网关并验证它是否正在运行。 +7. **Skills** — 安装推荐的 Skills 和可选依赖。 -重新运行新手引导**不会**清除任何内容，除非你明确选择**重置**（或传入 `--reset`）。 -CLI `--reset` 默认重置配置、凭证和会话；使用 `--reset-scope full` 可将工作区也包含在内。 -如果配置无效或包含旧版键，新手引导会要求你先运行 `openclaw doctor`。 +重新运行新手引导**不会**清除任何内容，除非你明确选择 **Reset**（或传入 `--reset`）。 +CLI `--reset` 默认会重置 config、credentials 和 sessions；使用 `--reset-scope full` 可将 workspace 也包括进去。 +如果配置无效或包含旧版键名，新手引导会要求你先运行 `openclaw doctor`。 -**远程模式**只会配置本地客户端去连接其他地方的 Gateway 网关。 +**远程模式**只会配置本地客户端去连接另一处的 Gateway 网关。 它**不会**在远程主机上安装或更改任何内容。 ## 添加另一个智能体 -使用 `openclaw agents add ` 可创建一个独立的智能体，拥有自己的工作区、 -会话和认证配置文件。运行时不带 `--workspace` 会启动新手引导。 +使用 `openclaw agents add ` 创建一个拥有独立工作区、 +会话和认证 profile 的单独智能体。不带 `--workspace` 运行时会启动新手引导。 它会设置： @@ -115,15 +115,15 @@ CLI `--reset` 默认重置配置、凭证和会话；使用 `--reset-scope full` 说明： - 默认工作区遵循 `~/.openclaw/workspace-`。 -- 可添加 `bindings` 来路由入站消息（新手引导可以执行此操作）。 -- 非交互式标志：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。 +- 添加 `bindings` 可路由入站消息（新手引导可以完成此操作）。 +- 非交互式 flags：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。 ## 完整参考 -如需详细的逐步拆解和配置输出，请参见 +有关详细的分步骤说明和配置输出，请参见 [CLI 设置参考](/zh-CN/start/wizard-cli-reference)。 -如需非交互示例，请参见 [CLI 自动化](/zh-CN/start/wizard-cli-automation)。 -如需更深入的技术参考（包括 RPC 详情），请参见 +有关非交互式示例，请参见 [CLI 自动化](/zh-CN/start/wizard-cli-automation)。 +有关更深入的技术参考（包括 RPC 细节），请参见 [新手引导参考](/zh-CN/reference/wizard)。 ## 相关文档 @@ -131,4 +131,4 @@ CLI `--reset` 默认重置配置、凭证和会话；使用 `--reset-scope full` - CLI 命令参考：[`openclaw onboard`](/cli/onboard) - 新手引导概览：[新手引导概览](/zh-CN/start/onboarding-overview) - macOS 应用新手引导：[新手引导](/zh-CN/start/onboarding) -- 智能体首次运行流程：[智能体引导初始化](/zh-CN/start/bootstrapping) +- 智能体首次运行仪式：[智能体引导](/zh-CN/start/bootstrapping) diff --git a/docs/zh-CN/tools/media-overview.md b/docs/zh-CN/tools/media-overview.md new file mode 100644 index 000000000..9d88b7e97 --- /dev/null +++ b/docs/zh-CN/tools/media-overview.md @@ -0,0 +1,67 @@ +--- +read_when: + - 正在查找媒体能力概览 + - 正在决定应配置哪个媒体 provider + - 想了解异步媒体生成是如何工作的 +summary: 媒体生成、理解和语音能力的统一落地页 +title: 媒体概览 +x-i18n: + generated_at: "2026-04-06T15:31:36Z" + model: gpt-5.4 + provider: openai + source_hash: cfee08eb91ec3e827724c8fa99bff7465356f6f1ac1b146562f35651798e3fd6 + source_path: tools/media-overview.md + workflow: 15 +--- + +# 媒体生成与理解 + +OpenClaw 可以生成图像、视频和音乐，理解传入媒体（图像、音频、视频），并通过文本转语音将回复朗读出来。所有媒体能力都由工具驱动：智能体会根据对话决定何时使用它们，并且只有在至少配置了一个对应 provider 时，相应工具才会出现。 + +## 能力一览 + +| 能力 | 工具 | Providers | 功能说明 | +| -------------------- | ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------- | +| 图像生成 | `image_generate` | ComfyUI、fal、Google、MiniMax、OpenAI、Vydra | 根据文本提示词或参考内容创建或编辑图像 | +| 视频生成 | `video_generate` | Alibaba、BytePlus（国际版）、ComfyUI、fal、Google、MiniMax、OpenAI、Qwen、Runway、Together、Vydra、xAI | 根据文本、图像或现有视频创建视频 | +| 音乐生成 | `music_generate` | ComfyUI、Google、MiniMax | 根据文本提示词创建音乐或音轨 | +| 文本转语音（TTS） | `tts` | ElevenLabs、Microsoft、MiniMax、OpenAI | 将输出回复转换为语音音频 | +| 媒体理解 | （自动） | 任何具备视觉/音频能力的模型 provider，以及 CLI 回退 | 总结传入的图像、音频和视频 | + +## Provider 能力矩阵 + +此表展示了各 provider 在整个平台上支持哪些媒体能力。 + +| Provider | 图像 | 视频 | 音乐 | TTS | STT / 转录 | 媒体理解 | +| ---------- | ----- | ----- | ----- | --- | ------------------- | ------------------- | +| Alibaba | | Yes | | | | | +| BytePlus | | Yes | | | | | +| ComfyUI | Yes | Yes | Yes | | | | +| Deepgram | | | | | Yes | | +| ElevenLabs | | | | Yes | | | +| fal | Yes | Yes | | | | | +| Google | Yes | Yes | Yes | | | Yes | +| Microsoft | | | | Yes | | | +| MiniMax | Yes | Yes | Yes | Yes | | | +| OpenAI | Yes | Yes | | Yes | Yes | Yes | +| Qwen | | Yes | | | | | +| Runway | | Yes | | | | | +| Together | | Yes | | | | | +| Vydra | Yes | Yes | | | | | +| xAI | | Yes | | | | | + + +媒体理解会使用你在 provider 配置中注册的任何具备视觉能力或音频能力的模型。上表重点标出了具备专用媒体理解支持的 provider；大多数带有多模态模型的 LLM provider（Anthropic、Google、OpenAI 等）在被配置为当前活动回复模型时，也能够理解传入媒体。 + + +## 异步生成如何工作 + +视频和音乐生成会作为后台任务运行，因为 provider 处理通常需要 30 秒到数分钟。当智能体调用 `video_generate` 或 `music_generate` 时，OpenClaw 会将请求提交给 provider，立即返回任务 ID，并在任务账本中跟踪该作业。作业运行期间，智能体会继续响应其他消息。当 provider 完成后，OpenClaw 会唤醒智能体，使其能够将完成的媒体发布回原始渠道。图像生成和 TTS 是同步的，会在回复过程中内联完成。 + +## 快速链接 + +- [图像生成](/zh-CN/tools/image-generation) -- 生成和编辑图像 +- [视频生成](/zh-CN/tools/video-generation) -- text-to-video、image-to-video 和 video-to-video +- [音乐生成](/zh-CN/tools/music-generation) -- 创建音乐和音轨 +- [文本转语音](/zh-CN/tools/tts) -- 将回复转换为语音音频 +- [媒体理解](/zh-CN/nodes/media-understanding) -- 理解传入的图像、音频和视频 diff --git a/docs/zh-CN/tools/music-generation.md b/docs/zh-CN/tools/music-generation.md index 2d7acd706..0724772e9 100644 --- a/docs/zh-CN/tools/music-generation.md +++ b/docs/zh-CN/tools/music-generation.md @@ -1,35 +1,40 @@ --- read_when: - - 通过智能体生成音乐或音频 - - 配置音乐生成提供商和模型 - - 理解 `music_generate` 工具参数 + - 通过智能体生成音乐或音频时 + - 配置音乐生成提供商和模型时 + - 了解 `music_generate` 工具参数时 summary: 使用共享提供商生成音乐，包括基于工作流的插件 title: 音乐生成 x-i18n: - generated_at: "2026-04-06T01:46:14Z" + generated_at: "2026-04-06T15:32:12Z" model: gpt-5.4 provider: openai - source_hash: a03de8aa75cfb7248eb0c1d969fb2a6da06117967d097e6f6e95771d0f017ae1 + source_hash: 5a2c95d087d6d0b5f4aaaae2fc1f98d683cbb4991d08ed6cabae45c90519ec0c source_path: tools/music-generation.md workflow: 15 --- # 音乐生成 -`music_generate` 工具让智能体能够通过共享音乐生成能力，使用已配置的提供商来创建音乐或音频，例如 Google、MiniMax 和通过工作流配置的 ComfyUI。 +`music_generate` 工具允许智能体通过共享的音乐生成能力来创建音乐或音频， +可使用已配置的提供商，例如 Google、 +MiniMax，以及通过工作流配置的 ComfyUI。 -对于由共享提供商支持的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务账本中跟踪它，然后在音轨准备就绪时再次唤醒智能体，以便智能体将完成的音频发布回原始渠道。 +对于基于共享提供商的智能体会话，OpenClaw 会将音乐生成启动为后台任务， +在任务账本中跟踪它，然后在音轨准备好后再次唤醒智能体， +这样智能体就可以把最终音频发回原始渠道。 -仅当至少有一个音乐生成提供商可用时，内置共享工具才会显示。如果你在智能体工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。 +只有在至少有一个音乐生成提供商可用时，内置共享工具才会出现。如果你在智能体工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。 ## 快速开始 -### 由共享提供商支持的生成 +### 基于共享提供商的生成 -1. 为至少一个提供商设置 API 密钥，例如 `GEMINI_API_KEY` 或 `MINIMAX_API_KEY`。 -2. 你也可以选择设置首选模型： +1. 为至少一个提供商设置 API 密钥，例如 `GEMINI_API_KEY` 或 + `MINIMAX_API_KEY`。 +2. 可选地设置你的首选模型： ```json5 { @@ -43,11 +48,12 @@ x-i18n: } ``` -3. 向智能体发出请求：_“生成一首关于夜间驾车穿越霓虹城市的欢快 synthpop 音轨。”_ +3. 向智能体提问：_“生成一段关于夜晚驾车穿过霓虹都市的轻快 synthpop 音轨。”_ -智能体会自动调用 `music_generate`。无需配置工具允许列表。 +智能体会自动调用 `music_generate`。不需要工具允许列表。 -对于没有会话支持智能体运行的直接同步上下文，内置工具仍会回退到内联生成，并在工具结果中返回最终媒体路径。 +对于没有基于会话的智能体运行的直接同步上下文，内置 +工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。 示例提示词： @@ -59,11 +65,13 @@ Generate a cinematic piano track with soft strings and no vocals. Generate an energetic chiptune loop about launching a rocket at sunrise. ``` -### 由工作流驱动的 Comfy 生成 +### 基于工作流的 Comfy 生成 -内置的 `comfy` 插件通过音乐生成提供商注册表接入共享 `music_generate` 工具。 +内置的 `comfy` 插件通过 +音乐生成提供商注册表接入共享的 `music_generate` 工具。 -1. 使用工作流 JSON 以及提示词/输出节点配置 `models.providers.comfy.music`。 +1. 配置 `models.providers.comfy.music`，包含工作流 JSON 以及 + prompt/output 节点。 2. 如果你使用 Comfy Cloud，请设置 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。 3. 请求智能体生成音乐，或直接调用该工具。 @@ -75,19 +83,30 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. ## 共享内置提供商支持 -| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 | -| ------ | ---------------------- | -------------- | --------------------------------------------------------- | -------------------------------------- | -| ComfyUI | `workflow` | 最多 1 张图像 | 由工作流定义的音乐或音频 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | -| Google | `lyria-3-clip-preview` | 最多 10 张图像 | `lyrics`、`instrumental`、`format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | +| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 | +| -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- | +| ComfyUI | `workflow` | 最多 1 张图像 | 由工作流定义的音乐或音频 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | +| Google | `lyria-3-clip-preview` | 最多 10 张图像 | `lyrics`、`instrumental`、`format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | | MiniMax | `music-2.5+` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` | +### 已声明的能力矩阵 + +这是 `music_generate`、契约测试 +和共享 live 扫描使用的显式模式契约。 + +| 提供商 | `generate` | `edit` | 编辑上限 | 共享 live lane | +| -------- | ---------- | ------ | ---------- | ------------------------------------------------------------------------- | +| ComfyUI | 是 | 是 | 1 张图像 | 不在共享扫描中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 | +| Google | 是 | 是 | 10 张图像 | `generate`、`edit` | +| MiniMax | 是 | 否 | 无 | `generate` | + 使用 `action: "list"` 可在运行时查看可用的共享提供商和模型： ```text /tool music_generate action=list ``` -使用 `action: "status"` 可查看当前由会话支持的活动音乐任务： +使用 `action: "status"` 可查看当前基于会话的音乐任务： ```text /tool music_generate action=status @@ -101,30 +120,50 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. ## 内置工具参数 -| 参数 | 类型 | 说明 | +| 参数 | 类型 | 描述 | | ----------------- | -------- | ------------------------------------------------------------------------------------------------- | -| `prompt` | string | 音乐生成提示词（`action: "generate"` 时必填） | -| `action` | string | `"generate"`（默认）、用于当前会话任务的 `"status"`，或用于查看提供商的 `"list"` | -| `model` | string | 提供商/模型覆盖值，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` | -| `lyrics` | string | 当提供商支持显式歌词输入时，可选的歌词内容 | -| `instrumental` | boolean | 当提供商支持时，请求仅器乐输出 | -| `image` | string | 单个参考图像路径或 URL | -| `images` | string[] | 多个参考图像（最多 10 张） | -| `durationSeconds` | number | 当提供商支持时，目标时长（秒）提示 | -| `format` | string | 当提供商支持时，输出格式提示（`mp3` 或 `wav`） | -| `filename` | string | 输出文件名提示 | +| `prompt` | string | 音乐生成提示词（`action: "generate"` 时必填） | +| `action` | string | `"generate"`（默认）、`"status"`（当前会话任务）或 `"list"`（查看提供商） | +| `model` | string | 提供商/模型覆盖，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` | +| `lyrics` | string | 当提供商支持显式歌词输入时使用的可选歌词 | +| `instrumental` | boolean | 当提供商支持时，请求仅器乐输出 | +| `image` | string | 单张参考图像路径或 URL | +| `images` | string[] | 多张参考图像（最多 10 张） | +| `durationSeconds` | number | 当提供商支持时长提示时，目标时长（秒） | +| `format` | string | 当提供商支持时的输出格式提示（`mp3` 或 `wav`） | +| `filename` | string | 输出文件名提示 | -并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证硬性限制，例如输入数量，但对于所选提供商或模型无法满足的不受支持可选提示，会在发出警告后忽略。 +并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证诸如输入数量之类的硬性限制， +但如果所选提供商或模型无法满足某些可选提示，这些提示会被忽略，并给出警告。 -## 共享提供商支持路径的异步行为 +## 共享提供商路径的异步行为 -- 由会话支持的智能体运行：`music_generate` 会创建一个后台任务，立即返回 started/task 响应，并在稍后的智能体跟进消息中发布完成的音轨。 -- 防止重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中后续的 `music_generate` 调用会返回任务状态，而不是启动新的生成。 -- 状态查询：使用 `action: "status"` 可在不启动新任务的情况下查看当前由会话支持的活动音乐任务。 -- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show ` 可查看该生成任务的排队中、运行中和终态状态。 -- 完成唤醒：OpenClaw 会将一个内部完成事件注入回同一会话，以便模型自行编写面向用户的跟进内容。 -- 提示词提示：当音乐任务已在进行中时，同一会话中的后续用户/手动轮次会收到一个较小的运行时提示，这样模型就不会盲目再次调用 `music_generate`。 -- 无会话回退：没有真实智能体会话的直接/本地上下文仍会以内联方式运行，并在同一轮中返回最终音频结果。 +- 基于会话的智能体运行：`music_generate` 会创建后台任务，立即返回已启动/任务响应，并在稍后的后续智能体消息中发送完成的音轨。 +- 重复防护：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中的后续 `music_generate` 调用会返回任务状态，而不是再次启动生成。 +- 状态查询：使用 `action: "status"` 可在不启动新生成的情况下查看当前基于会话的音乐任务。 +- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show ` 查看生成任务的排队、运行和终态状态。 +- 完成唤醒：OpenClaw 会将内部完成事件注入回同一会话，以便模型自行编写面向用户的后续消息。 +- 提示词提示：如果同一会话中已有音乐任务在进行，后续用户/手动回合会收到一个小型运行时提示，避免模型再次盲目调用 `music_generate`。 +- 无会话回退：没有真实智能体会话的直接/本地上下文仍会以内联方式运行，并在同一回合返回最终音频结果。 + +### 任务生命周期 + +每个 `music_generate` 请求会经历四个状态： + +1. **queued** —— 任务已创建，等待提供商接受。 +2. **running** —— 提供商正在处理（通常为 30 秒到 3 分钟，取决于提供商和时长）。 +3. **succeeded** —— 音轨已就绪；智能体被唤醒并将其发布到会话中。 +4. **failed** —— 提供商错误或超时；智能体会带着错误详情被唤醒。 + +从 CLI 检查状态： + +```bash +openclaw tasks list +openclaw tasks show +openclaw tasks cancel +``` + +重复防护：如果当前会话已有音乐任务处于 `queued` 或 `running` 状态，`music_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可显式检查，而不会触发新生成。 ## 配置 @@ -147,42 +186,87 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. 生成音乐时，OpenClaw 会按以下顺序尝试提供商： -1. 工具调用中的 `model` 参数（如果智能体指定了） +1. 工具调用中的 `model` 参数（如果智能体显式指定） 2. 配置中的 `musicGenerationModel.primary` 3. 按顺序使用 `musicGenerationModel.fallbacks` -4. 仅使用基于凭证的提供商默认值进行自动检测： - - 先使用当前默认提供商 - - 再按提供商 ID 顺序使用其余已注册的音乐生成提供商 +4. 仅使用基于认证的提供商默认值进行自动检测： + - 先尝试当前默认提供商 + - 再按提供商 id 顺序尝试其余已注册的音乐生成提供商 -如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。 +如果某个提供商失败，会自动尝试下一个候选项。如果全部失败， +错误中会包含每次尝试的详细信息。 ## 提供商说明 -- Google 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本和可选参考图像。 -- MiniMax 使用批量 `music_generation` 端点。当前内置流程支持提示词、可选歌词、器乐模式、时长控制和 mp3 输出。 -- ComfyUI 支持由工作流驱动，并取决于已配置的图以及提示词/输出字段的节点映射。 +- Google 使用 Lyria 3 批量生成。当前内置流程支持 + prompt、可选歌词文本和可选参考图像。 +- MiniMax 使用批量 `music_generation` 端点。当前内置流程 + 支持 prompt、可选歌词、器乐模式、时长引导以及 + mp3 输出。 +- ComfyUI 支持基于工作流驱动，并取决于所配置的图以及 + prompt/output 字段的节点映射。 -## 选择合适的路径 +## 提供商能力模式 -- 当你需要模型选择、提供商故障转移以及内置异步任务/状态流程时，请使用共享提供商支持路径。 -- 当你需要自定义工作流图，或需要不属于共享内置音乐能力的提供商时，请使用插件路径，例如 ComfyUI。 -- 如果你正在调试 ComfyUI 特定行为，请参阅 [ComfyUI](/zh-CN/providers/comfy)。如果你正在调试共享提供商行为，请先查看 [Google（Gemini）](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax)。 +共享音乐生成契约现在支持显式模式声明： -## 实时测试 +- `generate` 用于仅基于提示词的生成 +- 当请求包含一张或多张参考图像时，使用 `edit` -共享内置提供商的选择加入式实时覆盖： +新的提供商实现应优先使用显式模式块： + +```typescript +capabilities: { + generate: { + maxTracks: 1, + supportsLyrics: true, + supportsFormat: true, + }, + edit: { + enabled: true, + maxTracks: 1, + maxInputImages: 1, + supportsFormat: true, + }, +} +``` + +旧版平铺字段，例如 `maxInputImages`、`supportsLyrics` 和 +`supportsFormat`，不足以宣告编辑支持。提供商应 +显式声明 `generate` 和 `edit`，这样 live 测试、契约测试以及 +共享的 `music_generate` 工具才能以确定性的方式验证模式支持。 + +## 选择正确的路径 + +- 当你需要模型选择、提供商故障切换和内置异步任务/状态流时，请使用共享提供商路径。 +- 当你需要自定义工作流图，或需要使用不属于共享内置音乐能力的提供商时，请使用插件路径，例如 ComfyUI。 +- 如果你正在调试 ComfyUI 特定行为，请参见 [ComfyUI](/zh-CN/providers/comfy)。如果你正在调试共享提供商行为，请先从 [Google（Gemini）](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax) 开始。 + +## Live 测试 + +针对共享内置提供商的按需启用 live 覆盖： ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts ``` -内置 ComfyUI 音乐路径的选择加入式实时覆盖： +该 live 文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用 +live/env API 密钥而不是已存储的认证 profile，并在提供商启用编辑模式时同时运行 +`generate` 和已声明的 `edit` 覆盖。 + +当前这意味着： + +- `google`：`generate` 加 `edit` +- `minimax`：仅 `generate` +- `comfy`：单独的 Comfy live 覆盖，不属于共享提供商扫描 + +针对内置 ComfyUI 音乐路径的按需启用 live 覆盖： ```bash OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts ``` -当这些部分已配置时，Comfy 实时文件还会覆盖 comfy 图像和视频工作流。 +当这些部分已配置时，Comfy live 文件也会覆盖 comfy 图像和视频工作流。 ## 相关内容 @@ -191,5 +275,5 @@ OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy. - [ComfyUI](/zh-CN/providers/comfy) - [Google（Gemini）](/zh-CN/providers/google) - [MiniMax](/zh-CN/providers/minimax) -- [模型](/zh-CN/concepts/models) - 模型配置和故障转移 +- [模型](/zh-CN/concepts/models) - 模型配置和故障切换 - [工具概览](/zh-CN/tools) diff --git a/docs/zh-CN/tools/video-generation.md b/docs/zh-CN/tools/video-generation.md index fce76d02c..c2562cef3 100644 --- a/docs/zh-CN/tools/video-generation.md +++ b/docs/zh-CN/tools/video-generation.md @@ -1,152 +1,192 @@ --- read_when: - - 通过智能体生成视频时 - - 配置视频生成提供商和模型时 - - 了解 `video_generate` 工具参数时 -summary: 使用 12 个提供商后端，从文本、图像或现有视频生成视频 + - 通过智能体生成视频 + - 配置视频生成 provider 和模型 + - 了解 `video_generate` 工具参数 +summary: 使用 12 个 provider 后端根据文本、图像或现有视频生成视频 title: 视频生成 x-i18n: - generated_at: "2026-04-06T12:28:04Z" + generated_at: "2026-04-06T15:32:14Z" model: gpt-5.4 provider: openai - source_hash: a224c0a1bd6fe61592ac22ad9a65f0ae25a378a12b79c1210f2e7101886798bb + source_hash: 7d995d91f86f863f5a69c6945043dc430eb186830348a09eeaaad94620767f7d source_path: tools/video-generation.md workflow: 15 --- # 视频生成 -OpenClaw 智能体可以根据文本提示、参考图像或现有视频生成视频。支持 12 个提供商后端，每个后端具有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。 +OpenClaw 智能体可以根据文本提示词、参考图像或现有视频生成视频。支持 12 个 provider 后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的 provider。 -只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会出现。如果你没有在智能体工具中看到它，请设置提供商 API 密钥，或配置 `agents.defaults.videoGenerationModel`。 +只有在至少有一个视频生成 provider 可用时，`video_generate` 工具才会出现。如果你没有在智能体工具中看到它，请设置 provider API 密钥或配置 `agents.defaults.videoGenerationModel`。 OpenClaw 将视频生成视为三种运行时模式： -- `generate`：用于没有参考媒体的文生视频请求 +- `generate`：用于没有参考媒体的 text-to-video 请求 - `imageToVideo`：当请求包含一个或多个参考图像时使用 - `videoToVideo`：当请求包含一个或多个参考视频时使用 -提供商可以支持这些模式中的任意子集。工具会在提交前验证当前模式，并在 `action=list` 中报告支持的模式。 +Providers 可以支持这些模式中的任意子集。工具会在提交前验证当前 +模式，并在 `action=list` 中报告支持的模式。 ## 快速开始 -1. 为任一受支持的提供商设置 API 密钥： +1. 为任意受支持的 provider 设置 API 密钥： ```bash export GEMINI_API_KEY="your-key" ``` -2. 可选：固定一个默认模型： +2. 可选地固定一个默认模型： ```bash openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" ``` -3. 向智能体提出请求： +3. 向智能体发出请求： -> 生成一个 5 秒长、具有电影感的友善龙虾在日落时冲浪的视频。 +> 生成一个 5 秒钟的电影感视频：一只友好的龙虾在日落时冲浪。 -智能体会自动调用 `video_generate`。无需对工具进行 allowlist 配置。 +智能体会自动调用 `video_generate`。不需要工具 allowlist。 ## 生成视频时会发生什么 -视频生成是异步的。当智能体在一个会话中调用 `video_generate` 时： +视频生成是异步的。当智能体在会话中调用 `video_generate` 时： -1. OpenClaw 会将请求提交给提供商，并立即返回一个任务 ID。 -2. 提供商会在后台处理该任务（通常需要 30 秒到 5 分钟，具体取决于提供商和分辨率）。 -3. 当视频准备就绪时，OpenClaw 会通过内部完成事件唤醒同一个会话。 -4. 智能体会将完成的视频发布回原始对话中。 +1. OpenClaw 将请求提交给 provider，并立即返回一个任务 ID。 +2. Provider 在后台处理该任务（通常需要 30 秒到 5 分钟，取决于 provider 和分辨率）。 +3. 当视频准备就绪后，OpenClaw 会通过内部完成事件唤醒同一个会话。 +4. 智能体会将生成完成的视频发布回原始对话中。 -当同一会话中已有任务正在进行时，重复调用 `video_generate` 不会启动新的生成，而是返回当前任务状态。使用 `openclaw tasks list` 或 `openclaw tasks show ` 可在 CLI 中检查进度。 +当同一会话中已有任务正在进行时，重复调用 `video_generate` 不会启动新的生成，而是返回当前任务状态。使用 `openclaw tasks list` 或 `openclaw tasks show ` 可以在 CLI 中检查进度。 -在不依赖会话支持的智能体运行场景之外（例如直接调用工具），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。 +在没有会话支持的智能体运行之外（例如直接工具调用），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。 -## 支持的提供商 +### 任务生命周期 -| 提供商 | 默认模型 | 文本 | 图像参考 | 视频参考 | API 密钥 | -| ------ | ------------------------------- | ---- | ----------------- | ---------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `MODELSTUDIO_API_KEY` | -| BytePlus | `seedance-1-0-lite-t2v-250428` | 是 | 1 张图像 | 否 | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | 是 | 1 张图像 | 否 | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | 是 | 1 张图像 | 否 | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | 是 | 1 张图像 | 1 个视频 | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | 是 | 1 张图像 | 否 | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | 是 | 1 张图像 | 1 个视频 | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `QWEN_API_KEY` | -| Runway | `gen4.5` | 是 | 1 张图像 | 1 个视频 | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | 是 | 1 张图像 | 否 | `TOGETHER_API_KEY` | -| Vydra | `veo3` | 是 | 1 张图像（`kling`） | 否 | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | 是 | 1 张图像 | 1 个视频 | `XAI_API_KEY` | +每个 `video_generate` 请求都会经历四种状态： -某些提供商接受额外或替代的 API 密钥环境变量。详见各个[提供商页面](#related)。 +1. **queued** -- 任务已创建，等待 provider 接受。 +2. **running** -- provider 正在处理（通常需要 30 秒到 5 分钟，取决于 provider 和分辨率）。 +3. **succeeded** -- 视频已准备好；智能体会被唤醒并将其发布到对话中。 +4. **failed** -- provider 错误或超时；智能体会带着错误详情被唤醒。 -运行 `video_generate action=list` 可在运行时检查可用的提供商、模型和运行时模式。 +从 CLI 检查状态： + +```bash +openclaw tasks list +openclaw tasks show +openclaw tasks cancel +``` + +防止重复：如果当前会话已有视频任务处于 `queued` 或 `running` 状态，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可以显式检查状态，而不触发新的生成。 + +## 支持的 providers + +| Provider | 默认模型 | 文本 | 图像参考 | 视频参考 | API 密钥 | +| -------- | ------------------------------- | ---- | ----------------- | ---------------- | ---------------------------------------- | +| Alibaba | `wan2.6-t2v` | Yes | Yes（远程 URL） | Yes（远程 URL） | `MODELSTUDIO_API_KEY` | +| BytePlus（国际版） | `seedance-1-0-lite-t2v-250428` | Yes | 1 张图像 | No | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | Yes | 1 张图像 | No | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | Yes | 1 张图像 | No | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | Yes | 1 张图像 | 1 个视频 | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | Yes | 1 张图像 | No | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | Yes | 1 张图像 | 1 个视频 | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | Yes | Yes（远程 URL） | Yes（远程 URL） | `QWEN_API_KEY` | +| Runway | `gen4.5` | Yes | 1 张图像 | 1 个视频 | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | Yes | 1 张图像 | No | `TOGETHER_API_KEY` | +| Vydra | `veo3` | Yes | 1 张图像（`kling`） | No | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | Yes | 1 张图像 | 1 个视频 | `XAI_API_KEY` | + +某些 provider 接受额外的或替代的 API 密钥环境变量。详情请参见各个[provider 页面](#related)。 + +运行 `video_generate action=list` 可在运行时检查可用的 provider、模型和 +运行时模式。 + +### 声明的能力矩阵 + +这是 `video_generate`、合约测试和共享 live sweep 所使用的显式模式合约。 + +| Provider | `generate` | `imageToVideo` | `videoToVideo` | 当前共享 live lanes | +| -------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------- | +| Alibaba | Yes | Yes | Yes | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此 provider 需要远程 `http(s)` 视频 URL | +| BytePlus（国际版） | Yes | Yes | No | `generate`、`imageToVideo` | +| ComfyUI | Yes | Yes | No | 不在共享 sweep 中；特定 workflow 的覆盖由 Comfy 测试负责 | +| fal | Yes | Yes | No | `generate`、`imageToVideo` | +| Google | Yes | Yes | Yes | `generate`、`imageToVideo`、`videoToVideo` | +| MiniMax | Yes | Yes | No | `generate`、`imageToVideo` | +| OpenAI | Yes | Yes | Yes | `generate`、`imageToVideo`、`videoToVideo` | +| Qwen | Yes | Yes | Yes | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此 provider 需要远程 `http(s)` 视频 URL | +| Runway | Yes | Yes | Yes | `generate`、`imageToVideo`；仅当所选模型为 `runway/gen4_aleph` 时运行 `videoToVideo` | +| Together | Yes | Yes | No | `generate`、`imageToVideo` | +| Vydra | Yes | Yes | No | `generate`、`imageToVideo` | +| xAI | Yes | Yes | Yes | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此 provider 当前需要远程 MP4 URL | ## 工具参数 ### 必填 -| 参数 | 类型 | 说明 | -| -------- | ------ | --------------------------------------------------------------------------- | -| `prompt` | string | 要生成视频的文本描述（对于 `action: "generate"` 为必填） | +| 参数 | 类型 | 描述 | +| --------- | ------ | ----------------------------------------------------------------------------- | +| `prompt` | string | 要生成的视频文本描述（`action: "generate"` 时必填） | ### 内容输入 -| 参数 | 类型 | 说明 | -| -------- | -------- | ---------------------------- | -| `image` | string | 单个参考图像（路径或 URL） | -| `images` | string[] | 多个参考图像（最多 5 个） | -| `video` | string | 单个参考视频（路径或 URL） | -| `videos` | string[] | 多个参考视频（最多 4 个） | +| 参数 | 类型 | 描述 | +| --------- | -------- | ------------------------------------ | +| `image` | string | 单个参考图像（路径或 URL） | +| `images` | string[] | 多个参考图像（最多 5 个） | +| `video` | string | 单个参考视频（路径或 URL） | +| `videos` | string[] | 多个参考视频（最多 4 个） | ### 风格控制 -| 参数 | 类型 | 说明 | +| 参数 | 类型 | 描述 | | ----------------- | ------- | ------------------------------------------------------------------------ | | `aspectRatio` | string | `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` | -| `resolution` | string | `480P`、`720P` 或 `1080P` | -| `durationSeconds` | number | 目标时长（秒，四舍五入到提供商支持的最接近值） | -| `size` | string | 当提供商支持时的尺寸提示 | -| `audio` | boolean | 在支持时启用生成音频 | -| `watermark` | boolean | 在支持时切换提供商水印 | +| `resolution` | string | `480P`、`720P` 或 `1080P` | +| `durationSeconds` | number | 目标时长（秒，会四舍五入到 provider 支持的最近值） | +| `size` | string | 当 provider 支持时使用的尺寸提示 | +| `audio` | boolean | 在支持时启用生成音频 | +| `watermark` | boolean | 在支持时切换 provider 水印 | ### 高级 -| 参数 | 类型 | 说明 | -| ---------- | ------ | ------------------------------------------------- | -| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` | -| `model` | string | 提供商/模型覆盖（例如 `runway/gen4.5`） | -| `filename` | string | 输出文件名提示 | +| 参数 | 类型 | 描述 | +| ---------- | ------ | ----------------------------------------------- | +| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` | +| `model` | string | provider/model 覆盖（例如 `runway/gen4.5`） | +| `filename` | string | 输出文件名提示 | -并非所有提供商都支持全部参数。不支持的覆盖项会以尽力而为的方式被忽略，并在工具结果中报告为警告。硬性能力限制（例如参考输入过多）会在提交前直接失败。 +并非所有 provider 都支持所有参数。不支持的覆盖会尽力忽略，并在工具结果中报告为警告。硬性能力限制（例如参考输入过多）会在提交前直接失败。 -参考输入也会决定运行时模式： +参考输入还会决定运行时模式： - 无参考媒体：`generate` - 任意图像参考：`imageToVideo` - 任意视频参考：`videoToVideo` -混合使用图像和视频参考并不是稳定的共享能力接口。 -建议每次请求只使用一种参考类型。 +混合图像与视频参考不是稳定的共享能力表面。 +每个请求优先只使用一种参考类型。 ## 操作 -- **generate**（默认）-- 根据给定提示和可选参考输入创建视频。 +- **generate**（默认）-- 根据给定提示词和可选参考输入创建视频。 - **status** -- 检查当前会话中正在进行的视频任务状态，而不启动新的生成。 -- **list** -- 显示可用的提供商、模型及其能力。 +- **list** -- 显示可用的 provider、模型及其能力。 ## 模型选择 -生成视频时，OpenClaw 会按以下顺序解析模型： +生成视频时，OpenClaw 按以下顺序解析模型： -1. **`model` 工具参数** -- 如果智能体在调用中指定了该参数。 +1. **`model` 工具参数** -- 如果智能体在调用中指定了它。 2. **`videoGenerationModel.primary`** -- 来自配置。 3. **`videoGenerationModel.fallbacks`** -- 按顺序尝试。 -4. **自动检测** -- 使用具有有效认证的提供商，先从当前默认提供商开始，然后按字母顺序尝试其余提供商。 +4. **自动检测** -- 使用具有有效身份验证的 providers，先从当前默认 provider 开始，然后按字母顺序尝试其余 providers。 -如果某个提供商失败，会自动尝试下一个候选项。如果所有候选项都失败，错误中会包含每次尝试的详细信息。 +如果某个 provider 失败，会自动尝试下一个候选项。如果所有候选项都失败，错误中会包含每次尝试的详情。 ```json5 { @@ -161,26 +201,28 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 } ``` -## 提供商说明 +## Provider 说明 -| 提供商 | 说明 | -| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图像和视频必须是远程 `http(s)` URL。 | -| BytePlus | 仅支持单张参考图像。 | -| ComfyUI | 由工作流驱动的本地或云端执行。通过已配置图形支持文生视频和图生视频。 | -| fal | 对长时间运行任务使用基于队列的流程。仅支持单张参考图像。 | -| Google | 使用 Gemini/Veo。支持一个图像参考或一个视频参考。 | -| MiniMax | 仅支持单张参考图像。 | -| OpenAI | 仅转发 `size` 覆盖项。其他风格覆盖项（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略，并附带警告。 | -| Qwen | 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会在前期直接被拒绝。 | -| Runway | 支持通过数据 URI 使用本地文件。视频转视频需要 `runway/gen4_aleph`。纯文本运行提供 `16:9` 和 `9:16` 宽高比。 | -| Together | 仅支持单张参考图像。 | -| Vydra | 直接使用 `https://www.vydra.ai/api/v1`，以避免认证在重定向中丢失。`veo3` 内置为仅文生视频；`kling` 需要远程图像 URL。 | -| xAI | 支持文生视频、图生视频，以及远程视频编辑/扩展流程。 | +| Provider | 说明 | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图像和视频必须是远程 `http(s)` URL。 | +| BytePlus（国际版） | 仅支持单张参考图像。 | +| ComfyUI | 由 workflow 驱动的本地或云端执行。通过已配置图支持 text-to-video 和 image-to-video。 | +| fal | 对长时间运行任务使用基于队列的流程。仅支持单张参考图像。 | +| Google | 使用 Gemini/Veo。支持一张参考图像或一个参考视频。 | +| MiniMax | 仅支持单张参考图像。 | +| OpenAI | 只会转发 `size` 覆盖。其他风格覆盖（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略并附带警告。 | +| Qwen | 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会在一开始就被拒绝。 | +| Runway | 通过 data URI 支持本地文件。video-to-video 需要 `runway/gen4_aleph`。纯文本运行暴露 `16:9` 和 `9:16` 宽高比。 | +| Together | 仅支持单张参考图像。 | +| Vydra | 直接使用 `https://www.vydra.ai/api/v1` 以避免丢失身份验证的重定向。`veo3` 内置为仅 text-to-video；`kling` 需要远程图像 URL。 | +| xAI | 支持 text-to-video、image-to-video，以及远程视频编辑/扩展流程。 | -## 提供商能力模式 +## Provider 能力模式 -共享的视频生成契约现在允许提供商声明按模式划分的能力，而不只是扁平的聚合限制。新的提供商实现应优先使用显式模式块： +共享视频生成合约现在允许 providers 声明特定模式的 +能力，而不是只声明扁平的聚合限制。新的 provider +实现应优先使用显式模式块： ```typescript capabilities: { @@ -204,7 +246,31 @@ capabilities: { } ``` -旧的扁平字段，如 `maxInputImages` 和 `maxInputVideos`，仍可作为向后兼容的聚合上限使用，但它们无法同样精确地表达按模式划分的限制。 +像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段，不足以表达变换模式支持。Providers 应显式声明 +`generate`、`imageToVideo` 和 `videoToVideo`，这样 live tests、 +合约测试和共享 `video_generate` 工具才能以确定性的方式验证模式支持。 + +## Live tests + +针对共享内置 providers 的选择接入 live 覆盖： + +```bash +OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts +``` + +该 live 文件会从 `~/.profile` 加载缺失的 provider 环境变量，默认优先使用 +live/env API 密钥而不是已存储的 auth profiles，并运行它能够用本地媒体安全执行的已声明模式： + +- 对 sweep 中每个 provider 执行 `generate` +- 当 `capabilities.imageToVideo.enabled` 时执行 `imageToVideo` +- 当 `capabilities.videoToVideo.enabled` 且 provider/model + 在共享 sweep 中接受基于缓冲区的本地视频输入时执行 `videoToVideo` + +目前共享 `videoToVideo` live lane 覆盖： + +- `google` +- `openai` +- `runway`，仅当你选择 `runway/gen4_aleph` ## 配置 @@ -223,7 +289,7 @@ capabilities: { } ``` -或通过 CLI： +或者通过 CLI： ```bash openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v" diff --git a/docs/zh-CN/tts.md b/docs/zh-CN/tts.md index 601ec433b..fa57f4df5 100644 --- a/docs/zh-CN/tts.md +++ b/docs/zh-CN/tts.md @@ -1,456 +1,13 @@ --- -read_when: - - 启用回复文本转语音 - - 配置 TTS 提供商或限制 - - 使用 `/tts` 命令 -summary: 用于出站回复的文本转语音（TTS） -title: 文本转语音（TTS）（旧版路径） +redirect: /tools/tts +title: 文本转语音 x-i18n: - generated_at: "2026-04-05T10:13:31Z" + generated_at: "2026-04-06T15:31:37Z" model: gpt-5.4 provider: openai - source_hash: acca61773996299a582ab88e5a5db12d8f22ce8a28292ce97cc5dd5fdc2d3b83 + source_hash: 0c9ace272aa9adff93c946ee6275f6eb314dc1fa5043e0a26ecb164c990c0c59 source_path: tts.md workflow: 15 --- -# 文本转语音（TTS） - -OpenClaw 可以使用 ElevenLabs、Microsoft、MiniMax 或 OpenAI 将出站回复转换为音频。 -凡是 OpenClaw 能发送音频的地方，它都可以工作。 - -## 支持的服务 - -- **ElevenLabs**（主提供商或回退提供商） -- **Microsoft**（主提供商或回退提供商；当前内置实现使用 `node-edge-tts`） -- **MiniMax**（主提供商或回退提供商；使用 T2A v2 API） -- **OpenAI**（主提供商或回退提供商；也用于摘要） - -### Microsoft speech 说明 - -当前内置的 Microsoft speech 提供商通过 `node-edge-tts` 库使用 Microsoft Edge 的在线 -神经 TTS 服务。这是一项托管服务（不是本地服务），使用 Microsoft 端点，并且不需要 API 密钥。 -`node-edge-tts` 暴露了语音配置选项和输出格式，但并非所有选项都受到该服务支持。使用 `edge` 的旧版配置和指令输入 -仍然有效，并会被规范化为 `microsoft`。 - -由于这一路径是公开 Web 服务，没有已发布的 SLA 或配额， -请将其视为尽力而为。如果你需要有保障的限制和支持，请使用 OpenAI -或 ElevenLabs。 - -## 可选密钥 - -如果你想使用 OpenAI、ElevenLabs 或 MiniMax： - -- `ELEVENLABS_API_KEY`（或 `XI_API_KEY`） -- `MINIMAX_API_KEY` -- `OPENAI_API_KEY` - -Microsoft speech **不**需要 API 密钥。 - -如果配置了多个提供商，则会先使用已选提供商，其他提供商会作为回退选项。 -自动摘要会使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`）， -因此如果你启用了摘要，该提供商也必须已完成认证。 - -## 服务链接 - -- [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech) -- [OpenAI Audio API 参考](https://platform.openai.com/docs/api-reference/audio) -- [ElevenLabs 文本转语音](https://elevenlabs.io/docs/api-reference/text-to-speech) -- [ElevenLabs 认证](https://elevenlabs.io/docs/api-reference/authentication) -- [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2) -- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) -- [Microsoft Speech 输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) - -## 默认启用吗？ - -不是。自动 TTS 默认**关闭**。可在配置中通过 -`messages.tts.auto` 启用，或按会话使用 `/tts always`（别名：`/tts on`）启用。 - -当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序选取第一个已配置的 -speech 提供商。 - -## 配置 - -TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 -完整 schema 见 [Gateway 网关配置](/zh-CN/gateway/configuration)。 - -### 最小配置（启用 + 提供商） - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "elevenlabs", - }, - }, -} -``` - -### OpenAI 主提供商，ElevenLabs 回退 - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "openai", - summaryModel: "openai/gpt-4.1-mini", - modelOverrides: { - enabled: true, - }, - providers: { - openai: { - apiKey: "openai_api_key", - baseUrl: "https://api.openai.com/v1", - model: "gpt-4o-mini-tts", - voice: "alloy", - }, - elevenlabs: { - apiKey: "elevenlabs_api_key", - baseUrl: "https://api.elevenlabs.io", - voiceId: "voice_id", - modelId: "eleven_multilingual_v2", - seed: 42, - applyTextNormalization: "auto", - languageCode: "en", - voiceSettings: { - stability: 0.5, - similarityBoost: 0.75, - style: 0.0, - useSpeakerBoost: true, - speed: 1.0, - }, - }, - }, - }, - }, -} -``` - -### Microsoft 主提供商（无 API 密钥） - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "microsoft", - providers: { - microsoft: { - enabled: true, - voice: "en-US-MichelleNeural", - lang: "en-US", - outputFormat: "audio-24khz-48kbitrate-mono-mp3", - rate: "+10%", - pitch: "-5%", - }, - }, - }, - }, -} -``` - -### MiniMax 主提供商 - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "minimax", - providers: { - minimax: { - apiKey: "minimax_api_key", - baseUrl: "https://api.minimax.io", - model: "speech-2.8-hd", - voiceId: "English_expressive_narrator", - speed: 1.0, - vol: 1.0, - pitch: 0, - }, - }, - }, - }, -} -``` - -### 禁用 Microsoft speech - -```json5 -{ - messages: { - tts: { - providers: { - microsoft: { - enabled: false, - }, - }, - }, - }, -} -``` - -### 自定义限制 + prefs 路径 - -```json5 -{ - messages: { - tts: { - auto: "always", - maxTextLength: 4000, - timeoutMs: 30000, - prefsPath: "~/.openclaw/settings/tts.json", - }, - }, -} -``` - -### 仅在收到入站语音消息后以音频回复 - -```json5 -{ - messages: { - tts: { - auto: "inbound", - }, - }, -} -``` - -### 为长回复禁用自动摘要 - -```json5 -{ - messages: { - tts: { - auto: "always", - }, - }, -} -``` - -然后运行： - -``` -/tts summary off -``` - -### 字段说明 - -- `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。 - - `inbound` 仅在收到入站语音消息后发送音频。 - - `tagged` 仅在回复包含 `[[tts]]` 标签时发送音频。 -- `enabled`：旧版开关（Doctor 会将其迁移到 `auto`）。 -- `mode`：`"final"`（默认）或 `"all"`（包括工具/块回复）。 -- `provider`：speech 提供商 id，例如 `"elevenlabs"`、`"microsoft"`、`"minimax"` 或 `"openai"`（回退自动处理）。 -- 如果**未设置** `provider`，OpenClaw 会按注册表自动选择顺序使用第一个已配置的 speech 提供商。 -- 旧版 `provider: "edge"` 仍然有效，并会被规范化为 `microsoft`。 -- `summaryModel`：用于自动摘要的可选低成本模型；默认使用 `agents.defaults.model.primary`。 - - 接受 `provider/model` 或已配置的模型别名。 -- `modelOverrides`：允许模型发出 TTS 指令（默认开启）。 - - `allowProvider` 默认为 `false`（提供商切换需显式启用）。 -- `providers.`：由提供商拥有的设置，以 speech 提供商 id 作为键。 -- 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）会在加载时自动迁移到 `messages.tts.providers.`。 -- `maxTextLength`：TTS 输入的硬上限（字符数）。超出时 `/tts audio` 会失败。 -- `timeoutMs`：请求超时（毫秒）。 -- `prefsPath`：覆盖本地 prefs JSON 路径（提供商/限制/摘要）。 -- `apiKey` 值会回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`）。 -- `providers.elevenlabs.baseUrl`：覆盖 ElevenLabs API base URL。 -- `providers.openai.baseUrl`：覆盖 OpenAI TTS 端点。 - - 解析顺序：`messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - 非默认值会被视为 OpenAI-compatible TTS 端点，因此接受自定义模型名和语音名。 -- `providers.elevenlabs.voiceSettings`： - - `stability`、`similarityBoost`、`style`：`0..1` - - `useSpeakerBoost`：`true|false` - - `speed`：`0.5..2.0`（1.0 = 正常） -- `providers.elevenlabs.applyTextNormalization`：`auto|on|off` -- `providers.elevenlabs.languageCode`：双字母 ISO 639-1（例如 `en`、`de`） -- `providers.elevenlabs.seed`：整数 `0..4294967295`（尽力保证确定性） -- `providers.minimax.baseUrl`：覆盖 MiniMax API base 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）。 -- `providers.microsoft.enabled`：允许使用 Microsoft speech（默认 `true`；无 API 密钥）。 -- `providers.microsoft.voice`：Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。 -- `providers.microsoft.lang`：语言代码（例如 `en-US`）。 -- `providers.microsoft.outputFormat`：Microsoft 输出格式（例如 `audio-24khz-48kbitrate-mono-mp3`）。 - - 有效值请参见 Microsoft Speech 输出格式；并非所有格式都受内置的 Edge 支持传输支持。 -- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`：百分比字符串（例如 `+10%`、`-5%`）。 -- `providers.microsoft.saveSubtitles`：在音频文件旁边写入 JSON 字幕。 -- `providers.microsoft.proxy`：Microsoft speech 请求的代理 URL。 -- `providers.microsoft.timeoutMs`：请求超时覆盖（毫秒）。 -- `edge.*`：同一组 Microsoft 设置的旧版别名。 - -## 模型驱动覆盖（默认开启） - -默认情况下，模型**可以**为单条回复发出 TTS 指令。 -当 `messages.tts.auto` 为 `tagged` 时，这些指令是触发音频所必需的。 - -启用后，模型可以发出 `[[tts:...]]` 指令来覆盖单条回复的语音， -还可以附加一个可选的 `[[tts:text]]...[[/tts:text]]` 块， -用于提供表达性标签（笑声、歌唱提示等），这些内容应仅出现在 -音频中。 - -除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 - -回复载荷示例： - -``` -Here you go. - -[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] -[[tts:text]](laughs) Read the song once more.[[/tts:text]] -``` - -可用指令键（启用时）： - -- `provider`（已注册的 speech 提供商 id，例如 `openai`、`elevenlabs`、`minimax` 或 `microsoft`；需要 `allowProvider: true`） -- `voice`（OpenAI 语音）或 `voiceId`（ElevenLabs / MiniMax） -- `model`（OpenAI TTS 模型、ElevenLabs model id 或 MiniMax 模型） -- `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost` -- `vol` / `volume`（MiniMax 音量，0-10） -- `pitch`（MiniMax 音高，-12 到 12） -- `applyTextNormalization`（`auto|on|off`） -- `languageCode`（ISO 639-1） -- `seed` - -禁用所有模型覆盖： - -```json5 -{ - messages: { - tts: { - modelOverrides: { - enabled: false, - }, - }, - }, -} -``` - -可选允许列表（启用提供商切换，同时保持其他参数可配置）： - -```json5 -{ - messages: { - tts: { - modelOverrides: { - enabled: true, - allowProvider: true, - allowSeed: false, - }, - }, - }, -} -``` - -## 按用户偏好 - -Slash Commands 会将本地覆盖写入 `prefsPath`（默认： -`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 -`messages.tts.prefsPath` 覆盖）。 - -存储字段： - -- `enabled` -- `provider` -- `maxLength`（摘要阈值；默认 1500 字符） -- `summarize`（默认 `true`） - -这些值会覆盖该主机上的 `messages.tts.*`。 - -## 输出格式（固定） - -- **Feishu / Matrix / Telegram / WhatsApp**：Opus 语音消息（ElevenLabs 使用 `opus_48000_64`，OpenAI 使用 `opus`）。 - - 48 kHz / 64 kbps 是语音消息的良好折中。 -- **其他渠道**：MP3（ElevenLabs 使用 `mp3_44100_128`，OpenAI 使用 `mp3`）。 - - 44.1 kHz / 128 kbps 是语音清晰度的默认平衡点。 -- **MiniMax**：MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。原生不支持语音便笺格式；如果你需要有保障的 Opus 语音消息，请使用 OpenAI 或 ElevenLabs。 -- **Microsoft**：使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。 - - 内置传输接受 `outputFormat`，但该服务并不提供所有格式。 - - 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。 - - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要 - 有保障的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 - - 如果已配置的 Microsoft 输出格式失败，OpenClaw 会重试 MP3。 - -OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 - -## 自动 TTS 行为 - -启用后，OpenClaw 会： - -- 如果回复已经包含媒体或 `MEDIA:` 指令，则跳过 TTS。 -- 跳过过短回复（少于 10 个字符）。 -- 在启用时使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复进行摘要。 -- 将生成的音频附加到回复上。 - -如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频， -发送普通文本回复。 - -## 流程图 - -``` -Reply -> TTS enabled? - no -> send text - yes -> has media / MEDIA: / short? - yes -> send text - no -> length > limit? - no -> TTS -> attach audio - yes -> summary enabled? - no -> send text - yes -> summarize (summaryModel or agents.defaults.model.primary) - -> TTS -> attach audio -``` - -## Slash Commands 用法 - -只有一个命令：`/tts`。 -启用细节见 [Slash Commands](/zh-CN/tools/slash-commands)。 - -Discord 说明：`/tts` 是 Discord 内置命令，因此 OpenClaw 会在那里注册 -`/voice` 作为原生命令。文本形式的 `/tts ...` 仍然有效。 - -``` -/tts off -/tts always -/tts inbound -/tts tagged -/tts status -/tts provider openai -/tts limit 2000 -/tts summary off -/tts audio Hello from OpenClaw -``` - -说明： - -- 这些命令需要授权发送者（允许列表/所有者规则仍然适用）。 -- 必须启用 `commands.text` 或原生命令注册。 -- `off|always|inbound|tagged` 是按会话切换（`/tts on` 是 `/tts always` 的别名）。 -- `limit` 和 `summary` 存储在本地 prefs 中，而不是主配置中。 -- `/tts audio` 会生成一次性音频回复（不会开启 TTS）。 -- `/tts status` 包含最近一次尝试的回退可见性： - - 成功回退：`Fallback: -> ` 加 `Attempts: ...` - - 失败：`Error: ...` 加 `Attempts: ...` - - 详细诊断：`Attempt details: provider:outcome(reasonCode) latency` -- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（当提供商返回时），这些信息会体现在 TTS 错误/日志中。 - -## 智能体工具 - -`tts` 工具会将文本转换为语音，并返回一个用于 -回复投递的音频附件。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时， -音频会作为语音消息而不是文件附件进行投递。 - -## Gateway 网关 RPC - -Gateway 网关方法： - -- `tts.status` -- `tts.enable` -- `tts.disable` -- `tts.convert` -- `tts.setProvider` -- `tts.providers` +此页面已迁移至 [文本转语音](/zh-CN/tools/tts)。