From 04dfff11eca2e1363ebb862e42c3522db22031ff Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 17:02:27 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/index.md | 63 +- docs/zh-CN/gateway/security/index.md | 971 ++++++++++++++------------- docs/zh-CN/help/testing.md | 613 ++++++++--------- docs/zh-CN/install/updating.md | 66 +- docs/zh-CN/providers/openai.md | 357 +++++----- docs/zh-CN/tools/image-generation.md | 155 +++-- docs/zh-CN/tools/plugin.md | 199 +++--- docs/zh-CN/tools/subagents.md | 331 ++++----- 8 files changed, 1400 insertions(+), 1355 deletions(-) diff --git a/docs/zh-CN/channels/index.md b/docs/zh-CN/channels/index.md index 0ab9aaef9..6683f4da9 100644 --- a/docs/zh-CN/channels/index.md +++ b/docs/zh-CN/channels/index.md @@ -1,55 +1,60 @@ --- read_when: - 你想为 OpenClaw 选择一个聊天渠道 - - 你需要一个受支持消息平台的快速概览 + - 你需要快速了解受支持的消息平台概览 summary: OpenClaw 可连接的消息平台 title: 聊天渠道 x-i18n: - generated_at: "2026-04-23T20:41:17Z" + generated_at: "2026-04-24T16:58:30Z" model: gpt-5.4 provider: openai - source_hash: c016b78b16724e73b21946d6bed0009f4cbebd1f887620431b9b4bff70f2b1ff + source_hash: e97818dce89ea06a60f2cccd0cc8a78cba48d66ea39e4769f2b583690a4f75d0 source_path: channels/index.md workflow: 15 --- OpenClaw 可以通过你已经在使用的任何聊天应用与你交流。每个渠道都通过 Gateway 网关连接。 -所有渠道都支持文本；媒体和表情回应支持会因渠道而异。 +所有渠道都支持文本；媒体和回应功能则因渠道而异。 + +## 传递说明 + +- Telegram 回复中包含 Markdown 图片语法（例如 `![alt](url)`）时，在最终出站路径上会尽可能转换为媒体回复。 +- Slack 多人私信会按群聊路由，因此群组策略、提及行为以及群组会话规则同样适用于 MPIM 对话。 +- WhatsApp 采用按需安装的设置方式：新手引导可以在 Baileys 运行时依赖完成准备之前先展示设置流程，而 Gateway 网关仅在该渠道实际启用时才加载 WhatsApp 运行时。 ## 支持的渠道 -- [BlueBubbles](/zh-CN/channels/bluebubbles) — **iMessage 的推荐方案**；使用 BlueBubbles macOS 服务器 REST API，提供完整功能支持（内置插件；编辑、撤回、效果、表情回应、群组管理——编辑功能目前在 macOS 26 Tahoe 上不可用）。 -- [Discord](/zh-CN/channels/discord) — Discord Bot API + Gateway 网关；支持服务器、频道和私信。 -- [Feishu](/zh-CN/channels/feishu) — 通过 WebSocket 的 Feishu/Lark 机器人（内置插件）。 -- [Google Chat](/zh-CN/channels/googlechat) — 通过 HTTP webhook 的 Google Chat API 应用。 -- [iMessage (legacy)](/zh-CN/channels/imessage) — 基于 imsg CLI 的传统 macOS 集成（已弃用，新部署请使用 BlueBubbles）。 -- [IRC](/zh-CN/channels/irc) — 经典 IRC 服务器；支持频道和私信，并带有配对/允许列表控制。 +- [BlueBubbles](/zh-CN/channels/bluebubbles) — **iMessage 的推荐方案**；使用 BlueBubbles macOS 服务器 REST API，并提供完整功能支持（内置插件；编辑、撤回、特效、回应、群组管理——编辑功能目前在 macOS 26 Tahoe 上不可用）。 +- [Discord](/zh-CN/channels/discord) — Discord Bot API + Gateway 网关；支持服务器、渠道和私信。 +- [Feishu](/zh-CN/channels/feishu) — 通过 WebSocket 连接的 Feishu/Lark 机器人（内置插件）。 +- [Google Chat](/zh-CN/channels/googlechat) — 通过 HTTP webhook 接入的 Google Chat API 应用。 +- [iMessage（旧版）](/zh-CN/channels/imessage) — 通过 imsg CLI 提供的旧版 macOS 集成（已弃用，新设置请使用 BlueBubbles）。 +- [IRC](/zh-CN/channels/irc) — 经典 IRC 服务器；支持渠道和私信，并带有配对/允许列表控制。 - [LINE](/zh-CN/channels/line) — LINE Messaging API 机器人（内置插件）。 - [Matrix](/zh-CN/channels/matrix) — Matrix 协议（内置插件）。 -- [Mattermost](/zh-CN/channels/mattermost) — Bot API + WebSocket；支持频道、群组、私信（内置插件）。 +- [Mattermost](/zh-CN/channels/mattermost) — Bot API + WebSocket；支持渠道、群组、私信（内置插件）。 - [Microsoft Teams](/zh-CN/channels/msteams) — Bot Framework；支持企业场景（内置插件）。 - [Nextcloud Talk](/zh-CN/channels/nextcloud-talk) — 通过 Nextcloud Talk 提供的自托管聊天（内置插件）。 -- [Nostr](/zh-CN/channels/nostr) — 通过 NIP-04 的去中心化私信（内置插件）。 +- [Nostr](/zh-CN/channels/nostr) — 通过 NIP-04 实现的去中心化私信（内置插件）。 - [QQ Bot](/zh-CN/channels/qqbot) — QQ Bot API；支持私聊、群聊和富媒体（内置插件）。 -- [Signal](/zh-CN/channels/signal) — `signal-cli`；注重隐私。 -- [Slack](/zh-CN/channels/slack) — Bolt SDK；工作区应用。 -- [Synology Chat](/zh-CN/channels/synology-chat) — 通过出站 + 入站 webhook 的 Synology NAS Chat（内置插件）。 -- [Telegram](/zh-CN/channels/telegram) — 通过 grammY 的 Bot API；支持群组。 -- [Tlon](/zh-CN/channels/tlon) — 基于 Urbit 的消息工具（内置插件）。 -- [Twitch](/zh-CN/channels/twitch) — 通过 IRC 连接接入 Twitch 聊天（内置插件）。 -- [Voice Call](/zh-CN/plugins/voice-call) — 通过 Plivo 或 Twilio 提供电话功能（插件，需单独安装）。 -- [WebChat](/zh-CN/web/webchat) — 通过 WebSocket 的 Gateway 网关 WebChat UI。 -- [WeChat](/zh-CN/channels/wechat) — 通过扫码登录的腾讯 iLink Bot 插件；仅支持私聊（外部插件）。 -- [WhatsApp](/zh-CN/channels/whatsapp) — 最常用；使用 Baileys，并需要扫码配对。 +- [Signal](/zh-CN/channels/signal) — signal-cli；注重隐私。 +- [Slack](/zh-CN/channels/slack) — Bolt SDK；适用于工作区应用。 +- [Synology Chat](/zh-CN/channels/synology-chat) — 通过出站 + 入站 webhook 接入的 Synology NAS Chat（内置插件）。 +- [Telegram](/zh-CN/channels/telegram) — 通过 grammY 接入的 Bot API；支持群组。 +- [Tlon](/zh-CN/channels/tlon) — 基于 Urbit 的消息应用（内置插件）。 +- [Twitch](/zh-CN/channels/twitch) — 通过 IRC 连接接入的 Twitch 聊天（内置插件）。 +- [Voice Call](/zh-CN/plugins/voice-call) — 通过 Plivo 或 Twilio 提供的电话功能（插件，需单独安装）。 +- [WebChat](/zh-CN/web/webchat) — 通过 WebSocket 提供的 Gateway 网关 WebChat UI。 +- [微信](/zh-CN/channels/wechat) — 通过二维码登录的腾讯 iLink Bot 插件；仅支持私聊（外部插件）。 +- [WhatsApp](/zh-CN/channels/whatsapp) — 最常用；使用 Baileys，并需要二维码配对。 - [Zalo](/zh-CN/channels/zalo) — Zalo Bot API；越南流行的消息应用（内置插件）。 -- [Zalo Personal](/zh-CN/channels/zalouser) — 通过扫码登录的 Zalo 个人账户（内置插件）。 +- [Zalo Personal](/zh-CN/channels/zalouser) — 通过二维码登录的 Zalo 个人账号（内置插件）。 -## 注意事项 +## 说明 -- 渠道可以同时运行；配置多个渠道后，OpenClaw 会按聊天进行路由。 -- 通常最快的设置方式是 **Telegram**（只需简单的机器人令牌）。WhatsApp 需要扫码配对， - 并会在磁盘上存储更多状态。 +- 渠道可以同时运行；配置多个渠道后，OpenClaw 会按聊天分别路由。 +- 通常最快的设置方式是 **Telegram**（简单的机器人令牌）。WhatsApp 需要二维码配对，并会在磁盘上存储更多状态。 - 群组行为因渠道而异；参见 [Groups](/zh-CN/channels/groups)。 - 出于安全考虑，会强制执行私信配对和允许列表；参见 [Security](/zh-CN/gateway/security)。 -- 故障排除：[渠道故障排除](/zh-CN/channels/troubleshooting)。 -- 模型提供商文档单独提供；参见 [模型提供商](/zh-CN/providers/models)。 +- 故障排除：参见 [Channel troubleshooting](/zh-CN/channels/troubleshooting)。 +- 模型提供商单独提供文档；参见 [Model Providers](/zh-CN/providers/models)。 diff --git a/docs/zh-CN/gateway/security/index.md b/docs/zh-CN/gateway/security/index.md index ba5384499..6a19b9a9e 100644 --- a/docs/zh-CN/gateway/security/index.md +++ b/docs/zh-CN/gateway/security/index.md @@ -1,37 +1,40 @@ --- read_when: - - 添加会扩大访问范围或自动化能力的功能 + - 添加会扩大访问范围或自动化程度的功能 summary: 运行具有 shell 访问权限的 AI Gateway 网关时的安全注意事项和威胁模型 title: 安全性 x-i18n: - generated_at: "2026-04-24T06:43:46Z" + generated_at: "2026-04-24T16:58:28Z" model: gpt-5.4 provider: openai - source_hash: 9e8cfc2bd0b4519f60d10b10b3496869a1668d57905926607f597aa34e4ce6de + source_hash: fa578cc687e724751b3db724a972470e385b887f7b83f81bfa01f81a5118955e source_path: gateway/security/index.md workflow: 15 --- - **个人助理信任模型。** 本指南假设每个 Gateway 网关对应一个受信任的操作员边界（单用户、个人助理模型）。OpenClaw **并不是** 一个适用于多个对抗性用户共享同一个智能体或 Gateway 网关的敌对多租户安全边界。如果你需要混合信任或对抗性用户运行，请拆分信任边界（独立的 Gateway 网关 + 凭证，最好再配合独立的操作系统用户或主机）。 + **个人助理信任模型。** 本指南假设每个 Gateway 网关对应一个受信任的操作员边界（单用户、个人助理模型）。 + 对于多个对抗性用户共享同一个智能体或 Gateway 网关的场景，OpenClaw **并不是** + 一个可抵御敌对多租户的安全边界。如果你需要混合信任或对抗性用户运行，请拆分信任边界（独立的 Gateway 网关 + + 凭证，理想情况下还应使用独立的 OS 用户或主机）。 ## 先界定范围：个人助理安全模型 -OpenClaw 的安全指南假设采用**个人助理**部署方式：一个受信任的操作员边界，可以包含多个智能体。 +OpenClaw 的安全指南基于**个人助理**部署：一个受信任的操作员边界，可能对应多个智能体。 -- 支持的安全姿态：每个 Gateway 网关对应一个用户/信任边界（最好每个边界使用独立的操作系统用户/主机/VPS）。 -- 不受支持的安全边界：多个互不信任或具有对抗关系的用户共享同一个 Gateway 网关/智能体。 -- 如果需要对抗性用户隔离，请按信任边界拆分（独立的 Gateway 网关 + 凭证，最好再配合独立的操作系统用户/主机）。 -- 如果多个不受信任的用户都可以向同一个启用了工具的智能体发送消息，应视为他们共享该智能体所委托的同一组工具权限。 +- 支持的安全姿态：每个 Gateway 网关对应一个用户/信任边界（最好每个边界对应一个 OS 用户/主机/VPS）。 +- 不支持作为安全边界的场景：一个共享的 Gateway 网关/智能体被彼此不受信任或具有对抗性的用户共同使用。 +- 如果需要对抗性用户隔离，请按信任边界拆分（独立的 Gateway 网关 + 凭证，理想情况下还应使用独立的 OS 用户/主机）。 +- 如果多个不受信任的用户都可以向同一个启用了工具的智能体发送消息，应视为他们共享该智能体的同一套委托工具权限。 -本页说明的是**在这一模型内**如何加固安全性。它并不声称单个共享 Gateway 网关具备敌对多租户隔离能力。 +本页说明的是**在这一模型内**如何加固。它并不声称在单个共享 Gateway 网关上提供敌对多租户隔离。 ## 快速检查：`openclaw security audit` -另请参阅：[Formal Verification（Security Models）](/zh-CN/security/formal-verification) +另请参阅：[Formal Verification (Security Models)](/zh-CN/security/formal-verification) -请定期运行此命令（尤其是在修改配置或暴露网络接口之后）： +请定期运行此检查（尤其是在更改配置或暴露网络接口之后）： ```bash openclaw security audit @@ -40,94 +43,96 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` 的修复范围刻意保持较窄：它会将常见的开放群组策略切换为 allowlist，恢复 `logging.redactSensitive: "tools"`，收紧状态/配置/包含文件的权限，并且在 Windows 上运行时会使用 Windows ACL 重置，而不是 POSIX `chmod`。 +`security audit --fix` 有意保持范围很窄：它会将常见的开放群组策略切换为 allowlist，恢复 `logging.redactSensitive: "tools"`，收紧状态/配置/包含文件的权限，并且在 Windows 上运行时使用 Windows ACL 重置，而不是 POSIX `chmod`。 -它会标记常见的危险配置（Gateway 网关身份验证暴露、浏览器控制暴露、提升权限的 allowlist、文件系统权限、宽松的 exec 审批，以及开放渠道的工具暴露）。 +它会标记常见的易错配置（Gateway 网关认证暴露、浏览器控制暴露、提升权限的 allowlist、文件系统权限、宽松的 exec 批准策略，以及开放渠道的工具暴露）。 -OpenClaw 既是一个产品，也是一个实验：你正在将前沿模型行为接入真实的消息渠道和真实工具。**不存在“绝对安全”的配置。** 目标是有意识地明确： +OpenClaw 既是一个产品，也是一个实验：你正在把前沿模型的行为连接到真实的消息渠道和真实工具上。**不存在“绝对安全”的配置。** 目标是有意识地明确： - 谁可以和你的机器人对话 -- 机器人被允许在哪些地方执行操作 -- 机器人可以接触哪些内容 +- 机器人被允许在哪里执行操作 +- 机器人可以接触什么 -从仍能满足需求的最小访问范围开始，随着你建立信心，再逐步扩大。 +从仍然可用的最小访问权限开始，随着你建立信心再逐步放宽。 -### 部署和主机信任 +### 部署与主机信任 -OpenClaw 假设主机和配置边界是受信任的： +OpenClaw 假定主机和配置边界是受信任的： -- 如果某人可以修改 Gateway 网关主机状态/配置（`~/.openclaw`，包括 `openclaw.json`），就应将其视为受信任的操作员。 -- 让多个互不信任/具有对抗关系的操作员共享同一个 Gateway 网关**不是推荐的配置**。 -- 对于混合信任团队，请使用独立的 Gateway 网关 来拆分信任边界（或至少使用独立的操作系统用户/主机）。 -- 推荐的默认方式：每台机器/主机（或 VPS）一个用户，该用户一个 Gateway 网关，并在该 Gateway 网关中运行一个或多个智能体。 -- 在单个 Gateway 网关实例内部，经过身份验证的操作员访问属于受信任的控制平面角色，而不是按用户划分的租户角色。 -- 会话标识符（`sessionKey`、session ID、labels）是路由选择器，不是授权令牌。 -- 如果多个人都可以向同一个启用了工具的智能体发送消息，那么他们每个人都可以驱动这一组相同的权限。按用户隔离会话/内存有助于隐私，但并不会把共享智能体变成按用户划分的主机授权边界。 +- 如果某人可以修改 Gateway 网关主机状态/配置（`~/.openclaw`，包括 `openclaw.json`），应将其视为受信任的操作员。 +- 为多个彼此不受信任/具有对抗性的操作员运行同一个 Gateway 网关**不是推荐配置**。 +- 对于混合信任团队，请通过独立的 Gateway 网关拆分信任边界（或者至少使用独立的 OS 用户/主机）。 +- 推荐默认方式：每台机器/主机（或 VPS）一个用户，该用户一个 gateway，该 gateway 内可包含一个或多个智能体。 +- 在同一个 Gateway 网关实例内部，经过认证的操作员访问属于受信任的控制平面角色，而不是按用户划分的租户角色。 +- 会话标识符（`sessionKey`、session ID、标签）是路由选择器，不是授权令牌。 +- 如果多个人都可以向同一个启用了工具的智能体发送消息，那么他们每个人都可以驱动这同一套权限。按用户划分的会话/记忆隔离有助于隐私，但不会把共享智能体变成按用户划分的主机授权边界。 ### 共享 Slack 工作区：真实风险 -如果“Slack 中所有人都可以给机器人发消息”，核心风险在于委托出去的工具权限： +如果“Slack 里的每个人都可以给机器人发消息”，核心风险是委托工具权限： -- 任何被允许的发送者都可以在智能体策略允许范围内触发工具调用（`exec`、浏览器、网络/文件工具）； -- 来自某个发送者的提示词/内容注入可能导致影响共享状态、设备或输出的操作； -- 如果某个共享智能体拥有敏感凭证/文件，那么任何被允许的发送者都可能通过工具使用来驱动数据外流。 +- 任何被允许的发送者都可以在该智能体的策略范围内诱发工具调用（`exec`、浏览器、网络/文件工具）； +- 来自某个发送者的提示词/内容注入，可能导致影响共享状态、设备或输出的操作； +- 如果某个共享智能体拥有敏感凭证/文件，任何被允许的发送者都可能通过工具使用来驱动数据外泄。 -对于团队工作流，请使用工具最少化的独立智能体/Gateway 网关；处理个人数据的智能体应保持私有。 +对于团队工作流，应使用拥有最小化工具集的独立智能体/Gateway 网关；涉及个人数据的智能体应保持私有。 ### 公司共享智能体：可接受模式 -当使用该智能体的所有人都处于同一信任边界内（例如同一个公司团队），并且该智能体严格限定在业务范围内时，这是可接受的。 +当使用该智能体的所有人都处于同一个信任边界内（例如同一个公司团队），且该智能体严格限定在业务范围内时，这种模式是可接受的。 - 在专用机器/VM/容器上运行它； -- 为该运行时使用专用的操作系统用户 + 专用浏览器/配置文件/账号； -- 不要让该运行时登录个人 Apple/Google 账号，也不要使用个人密码管理器/浏览器配置文件。 +- 为该运行时使用专用 OS 用户 + 专用浏览器/Profile/账号； +- 不要让该运行时登录个人 Apple/Google 账号或个人密码管理器/浏览器 Profile。 -如果你在同一个运行时中混用个人身份和公司身份，就会打破隔离并提高个人数据暴露风险。 +如果你在同一运行时中混用个人身份和公司身份，就会打破这种隔离，并增加个人数据暴露风险。 -## Gateway 网关与 node 节点的信任概念 +## Gateway 网关与节点信任概念 -应将 Gateway 网关和 node 节点视为同一个操作员信任域中的不同角色： +应将 Gateway 网关和节点视为同一个操作员信任域中的不同角色： -- **Gateway 网关**是控制平面和策略界面（`gateway.auth`、工具策略、路由）。 -- **Node 节点**是与该 Gateway 网关配对的远程执行界面（命令、设备操作、主机本地能力）。 -- 向 Gateway 网关通过身份验证的调用方，在 Gateway 网关作用域内是受信任的。完成配对后，node 节点上的操作就是该节点上的受信任操作员操作。 -- `sessionKey` 是路由/上下文选择器，不是按用户划分的身份验证。 -- Exec 审批（allowlist + 询问）是针对操作员意图的护栏，而不是敌对多租户隔离。 -- OpenClaw 针对受信任的单操作员配置的产品默认行为是：允许在 `gateway`/`node` 上执行主机 exec，且无需审批提示（`security="full"`，`ask="off"`，除非你手动收紧）。这一默认值是有意的 UX 设计，本身并不是漏洞。 -- Exec 审批会绑定精确的请求上下文以及尽力识别的直接本地文件操作数；它不会对每一种运行时/解释器加载路径进行语义建模。若要获得强边界，请使用沙箱隔离和主机隔离。 +- **Gateway 网关**是控制平面和策略表面（`gateway.auth`、工具策略、路由）。 +- **节点**是与该 Gateway 网关配对的远程执行表面（命令、设备操作、主机本地能力）。 +- 通过 Gateway 网关认证的调用者，在 Gateway 网关范围内被视为受信任。完成配对后，节点操作则是在该节点上的受信任操作员操作。 +- `sessionKey` 是路由/上下文选择，不是按用户划分的认证。 +- Exec 批准（allowlist + 询问）是针对操作员意图的防护栏，不是用于敌对多租户隔离。 +- OpenClaw 针对受信任单操作员场景的产品默认行为是，允许在 `gateway`/`node` 上执行主机 exec 且不弹出批准提示（`security="full"`，`ask="off"`，除非你主动收紧）。这一默认值是出于 UX 的有意设计，本身并不是漏洞。 +- Exec 批准会绑定精确的请求上下文以及尽力识别的直接本地文件操作数；它们不会对每一种运行时/解释器加载路径进行语义建模。如果你需要强边界，请使用沙箱隔离和主机隔离。 -如果你需要敌对用户隔离，请按操作系统用户/主机拆分信任边界，并运行独立的 Gateway 网关。 +如果你需要敌对用户隔离，请按 OS 用户/主机拆分信任边界，并运行独立的 Gateway 网关。 ## 信任边界矩阵 -在进行风险研判时，可以把下表当作快速模型： +在进行风险分级时，可将其作为快速模型： -| 边界或控制 | 含义 | 常见误解 | -| --------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | -| `gateway.auth`（token/password/trusted-proxy/device auth） | 对 Gateway 网关 API 的调用方进行身份验证 | “要想安全，就必须对每一帧消息都做逐条签名” | -| `sessionKey` | 用于上下文/会话选择的路由键 | “Session key 是用户身份验证边界” | -| 提示词/内容护栏 | 降低模型被滥用的风险 | “仅凭提示词注入就能证明存在身份验证绕过” | -| `canvas.eval` / 浏览器 evaluate | 启用时属于有意开放给操作员的能力 | “在这个信任模型下，任何 JS eval 原语自动都算漏洞” | -| 本地 TUI `!` shell | 由操作员显式触发的本地执行 | “本地 shell 便捷命令就是远程注入” | -| Node 配对和 node 命令 | 在已配对设备上的操作员级远程执行 | “远程设备控制默认应视为不受信任用户访问” | +| 边界或控制项 | 含义 | 常见误解 | +| --------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | +| `gateway.auth`（token/password/trusted-proxy/device auth） | 对 Gateway 网关 API 的调用者进行认证 | “要想安全，就必须对每一帧消息都进行逐条签名验证” | +| `sessionKey` | 用于上下文/会话选择的路由键 | “Session key 是用户认证边界” | +| 提示词/内容防护栏 | 降低模型被滥用的风险 | “仅凭提示词注入就足以证明认证被绕过” | +| `canvas.eval` / 浏览器 evaluate | 启用时属于有意赋予操作员的能力 | “在这种信任模型下，任何 JS eval 原语自动都算漏洞” | +| 本地 TUI `!` shell | 由操作员显式触发的本地执行 | “本地 shell 便捷命令就是远程注入” | +| 节点配对与节点命令 | 在已配对设备上的操作员级远程执行 | “默认就应该把远程设备控制视为不受信任用户访问” | ## 按设计不视为漏洞的情况 - - 这些模式经常被报告，但通常都会作为无须处理关闭，除非能证明存在真实的边界绕过： + + 这些模式经常被报告，但除非能证明存在真实的边界绕过，否则通常会被关闭且不采取行动： -- 仅包含提示词注入链，但没有策略、身份验证或沙箱绕过。 -- 假设在同一个共享主机或共享配置上进行敌对多租户运行的指控。 -- 将共享 Gateway 网关 配置中的正常操作员读取路径访问（例如 `sessions.list` / `sessions.preview` / `chat.history`）归类为 IDOR 的指控。 -- 仅限 localhost 部署的发现（例如仅 loopback Gateway 网关缺少 HSTS）。 -- 针对本仓库中并不存在的入站路径而提出的 Discord 入站 webhook 签名问题。 -- 将 node 配对元数据视为 `system.run` 的隐藏第二层逐命令审批，而实际上真正的执行边界仍是 Gateway 网关的全局 node 命令策略加上 node 节点自身的 exec 审批。 -- 将 `sessionKey` 当作身份验证令牌，从而得出“缺少按用户授权”的结论。 +- 仅靠提示词注入、但没有策略、认证或沙箱绕过的攻击链。 +- 假设在一个共享主机或配置上存在敌对多租户运行的说法。 +- 将正常的操作员读取路径访问（例如 + `sessions.list` / `sessions.preview` / `chat.history`）在共享 gateway 场景中归类为 IDOR 的说法。 +- 仅限 localhost 部署的发现（例如仅 loopback gateway 上的 HSTS）。 +- 针对本仓库中并不存在的入站路径，报告 Discord 入站 webhook 签名问题。 +- 将节点配对元数据视为 `system.run` 的隐藏的第二层逐命令批准机制的报告，而实际执行边界仍然是 gateway 的全局节点命令策略加上节点自身的 exec + 批准机制。 +- 将 `sessionKey` 当作认证令牌，从而得出“缺少按用户授权”的报告。 ## 60 秒内建立加固基线 -先使用这个基线，然后再按受信任智能体逐项重新启用工具： +先使用下面这套基线，然后再按受信任智能体的需要有选择地重新启用工具： ```json5 { @@ -152,66 +157,66 @@ OpenClaw 假设主机和配置边界是受信任的： } ``` -这样会让 Gateway 网关仅在本地可访问，隔离私信，并默认禁用控制平面/运行时工具。 +这会让 Gateway 网关仅限本地访问、隔离私信，并默认禁用控制平面/运行时工具。 ## 共享收件箱快速规则 -如果不止一个人可以向你的机器人发送私信： +如果不止一个人可以给你的机器人发私信： -- 设置 `session.dmScope: "per-channel-peer"`（多账号渠道则使用 `"per-account-channel-peer"`）。 +- 将 `session.dmScope` 设为 `"per-channel-peer"`（对于多账号渠道则使用 `"per-account-channel-peer"`）。 - 保持 `dmPolicy: "pairing"` 或使用严格的 allowlist。 -- 绝不要把共享私信和广泛的工具访问权限组合在一起。 -- 这有助于加固协作式/共享收件箱，但并不是为在用户共享主机/配置写权限时提供敌对共租户隔离而设计的。 +- 绝不要将共享私信与广泛的工具访问权限结合使用。 +- 这可以加固协作式/共享收件箱场景，但在用户共享主机/配置写权限时，并不是为敌对共租户隔离而设计的。 ## 上下文可见性模型 OpenClaw 将两个概念区分开来： -- **触发授权**：谁可以触发智能体（`dmPolicy`、`groupPolicy`、allowlist、提及门槛）。 +- **触发授权**：谁可以触发智能体（`dmPolicy`、`groupPolicy`、allowlist、提及门控）。 - **上下文可见性**：哪些补充上下文会被注入到模型输入中（回复正文、引用文本、线程历史、转发元数据）。 -Allowlist 控制触发和命令授权。`contextVisibility` 设置控制补充上下文（引用回复、线程根消息、拉取的历史记录）如何被过滤： +Allowlists 用于控制触发和命令授权。`contextVisibility` 设置则控制如何过滤补充上下文（引用回复、线程根消息、拉取的历史记录）： -- `contextVisibility: "all"`（默认）会按接收到的原样保留补充上下文。 +- `contextVisibility: "all"`（默认）会保留收到的全部补充上下文。 - `contextVisibility: "allowlist"` 会将补充上下文过滤为仅包含通过当前 allowlist 检查的发送者内容。 - `contextVisibility: "allowlist_quote"` 的行为类似 `allowlist`，但仍会保留一条显式引用回复。 -你可以按渠道或按房间/会话设置 `contextVisibility`。配置细节见 [Group Chats](/zh-CN/channels/groups#context-visibility-and-allowlists)。 +可按渠道或按房间/会话单独设置 `contextVisibility`。设置细节请参见 [Group Chats](/zh-CN/channels/groups#context-visibility-and-allowlists)。 -安全通告分级处理指南： +安全通告分级指导： -- 如果报告仅表明“模型可以看到来自未列入 allowlist 的发送者的引用文本或历史文本”，这属于可以通过 `contextVisibility` 解决的加固发现，而不是身份验证或沙箱边界本身被绕过。 -- 若要构成真正具有安全影响的问题，报告仍需证明存在信任边界绕过（身份验证、策略、沙箱、审批，或其他文档化边界）。 +- 仅证明“模型可以看到来自未列入 allowlist 的发送者的引用文本或历史文本”的说法，属于可通过 `contextVisibility` 解决的加固发现，本身并不构成认证或沙箱边界绕过。 +- 若要构成真正具有安全影响的问题，报告仍然需要证明存在信任边界绕过（认证、策略、沙箱、批准机制，或其他已记录的边界）。 ## 审计会检查什么（高层概览） -- **入站访问**（私信策略、群组策略、allowlist）：陌生人能否触发这个机器人？ -- **工具爆炸半径**（高权限工具 + 开放房间）：提示词注入是否可能演变为 shell / 文件 / 网络操作？ -- **Exec 审批漂移**（`security=full`、`autoAllowSkills`、未启用 `strictInlineEval` 的解释器 allowlist）：主机 exec 护栏是否仍然按你的预期生效？ - - `security="full"` 是一种宽泛的姿态警告，不代表一定存在 bug。它是受信任个人助理配置的默认选择；只有当你的威胁模型需要审批或 allowlist 护栏时，才需要收紧它。 -- **网络暴露**（Gateway 网关 bind/auth、Tailscale Serve/Funnel、弱或过短的身份验证 token）。 -- **浏览器控制暴露**（远程 node 节点、中继端口、远程 CDP 端点）。 -- **本地磁盘卫生**（权限、符号链接、配置 include、 “synced folder” 路径）。 +- **入站访问**（私信策略、群组策略、allowlist）：陌生人能否触发机器人？ +- **工具爆炸半径**（提升权限工具 + 开放房间）：提示词注入是否会演变成 shell/文件/网络操作？ +- **Exec 批准漂移**（`security=full`、`autoAllowSkills`、未启用 `strictInlineEval` 的解释器 allowlist）：主机 exec 防护栏是否仍按你的预期工作？ + - `security="full"` 是一种广义姿态警告，不代表已经证明存在 bug。对于受信任的个人助理场景，这是刻意选择的默认值；只有当你的威胁模型需要批准或 allowlist 防护栏时，才应将其收紧。 +- **网络暴露**（Gateway 网关 bind/auth、Tailscale Serve/Funnel、弱或过短的认证 token）。 +- **浏览器控制暴露**（远程节点、中继端口、远程 CDP 端点）。 +- **本地磁盘卫生**（权限、符号链接、配置 include、 “同步文件夹” 路径）。 - **插件**（插件在没有显式 allowlist 的情况下加载）。 -- **策略漂移/配置错误**（已配置沙箱 Docker 设置但沙箱模式关闭；无效的 `gateway.nodes.denyCommands` 模式，因为匹配仅针对精确命令名生效——例如 `system.run`——而不会检查 shell 文本；危险的 `gateway.nodes.allowCommands` 条目；全局 `tools.profile="minimal"` 被按智能体配置覆盖；插件拥有的工具在宽松工具策略下可被访问）。 -- **运行时期望漂移**（例如假设隐式 exec 仍然表示 `sandbox`，而 `tools.exec.host` 现在默认是 `auto`；或者显式设置 `tools.exec.host="sandbox"`，但沙箱模式处于关闭状态）。 -- **模型卫生**（当配置的模型看起来过旧时发出警告；不是硬性阻止）。 +- **策略漂移/错误配置**（已配置 sandbox docker 设置但 sandbox 模式关闭；无效的 `gateway.nodes.denyCommands` 模式，因为匹配仅针对精确命令名，例如 `system.run`，而不会检查 shell 文本；危险的 `gateway.nodes.allowCommands` 条目；全局 `tools.profile="minimal"` 被按智能体配置的 profile 覆盖；在宽松工具策略下仍可访问插件自带工具）。 +- **运行时预期漂移**（例如假定隐式 exec 仍意味着 `sandbox`，但现在 `tools.exec.host` 默认是 `auto`；或者在 sandbox 模式关闭时显式设置 `tools.exec.host="sandbox"`）。 +- **模型卫生**（当已配置模型看起来属于旧版时给出警告；不是硬性阻断）。 如果你运行 `--deep`，OpenClaw 还会尽力尝试进行实时 Gateway 网关探测。 ## 凭证存储映射 -在审计访问权限或决定备份内容时，可参考此清单： +在审计访问或决定备份内容时可参考此表： - **WhatsApp**：`~/.openclaw/credentials/whatsapp//creds.json` -- **Telegram bot token**：配置/环境变量，或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接） -- **Discord bot token**：配置/环境变量，或 SecretRef（env/file/exec 提供商） -- **Slack tokens**：配置/环境变量（`channels.slack.*`） +- **Telegram bot token**：config/env 或 `channels.telegram.tokenFile`（仅接受常规文件；拒绝符号链接） +- **Discord bot token**：config/env 或 SecretRef（env/file/exec 提供商） +- **Slack token**：config/env（`channels.slack.*`） - **配对 allowlist**： - `~/.openclaw/credentials/-allowFrom.json`（默认账号） - `~/.openclaw/credentials/--allowFrom.json`（非默认账号） -- **模型 auth 配置文件**：`~/.openclaw/agents//agent/auth-profiles.json` -- **基于文件的 secrets 负载（可选）**：`~/.openclaw/secrets.json` +- **模型认证 Profile**：`~/.openclaw/agents//agent/auth-profiles.json` +- **基于文件的 secret 负载（可选）**：`~/.openclaw/secrets.json` - **旧版 OAuth 导入**：`~/.openclaw/credentials/oauth.json` ## 安全审计检查清单 @@ -219,50 +224,52 @@ Allowlist 控制触发和命令授权。`contextVisibility` 设置控制补充 当审计输出发现项时，请按以下优先级处理： 1. **任何“开放”状态 + 已启用工具**：先锁定私信/群组（配对/allowlist），再收紧工具策略/沙箱隔离。 -2. **公共网络暴露**（LAN 绑定、Funnel、缺少身份验证）：立即修复。 -3. **浏览器控制的远程暴露**：应将其视为操作员访问（仅 tailnet、谨慎配对 node 节点、避免公开暴露）。 -4. **权限**：确保状态/配置/凭证/auth 不可被组用户或所有人读取。 +2. **公网网络暴露**（LAN bind、Funnel、缺少认证）：立即修复。 +3. **浏览器控制的远程暴露**：应将其视为操作员访问（仅限 tailnet、谨慎配对节点、避免公开暴露）。 +4. **权限**：确保状态/配置/凭证/认证信息不是组可读或全局可读。 5. **插件**：只加载你明确信任的内容。 -6. **模型选择**：对于任何启用了工具的机器人，优先使用现代、具备更强指令加固能力的模型。 +6. **模型选择**：对于任何带工具的机器人，优先选择现代、具备更强指令防护能力的模型。 ## 安全审计术语表 每条审计发现都会使用结构化的 `checkId` 作为键（例如 -`gateway.bind_no_auth` 或 `tools.exec.security_full_configured`）。常见的严重等级类别包括： +`gateway.bind_no_auth` 或 `tools.exec.security_full_configured`）。常见的严重级别类别包括： -- `fs.*` —— 状态、配置、凭证、auth 配置文件的文件系统权限。 -- `gateway.*` —— bind 模式、auth、Tailscale、Control UI、trusted-proxy 设置。 -- `hooks.*`、`browser.*`、`sandbox.*`、`tools.exec.*` —— 各个界面的加固检查。 -- `plugins.*`、`skills.*` —— 插件/Skills 供应链和扫描发现。 -- `security.exposure.*` —— 访问策略与工具爆炸半径相交的跨领域检查。 +- `fs.*` — 状态、配置、凭证、认证 Profile 的文件系统权限。 +- `gateway.*` — bind 模式、auth、Tailscale、Control UI、trusted-proxy 设置。 +- `hooks.*`、`browser.*`、`sandbox.*`、`tools.exec.*` — 各表面的加固项。 +- `plugins.*`、`skills.*` — plugin/skill 供应链和扫描发现。 +- `security.exposure.*` — 访问策略与工具爆炸半径相交的跨领域检查。 -完整目录（包括严重等级、修复键和自动修复支持）见 +完整目录包含严重级别、修复键和自动修复支持，见 [Security audit checks](/zh-CN/gateway/security/audit-checks)。 -## 通过 HTTP 使用 Control UI +## 通过 HTTP 访问 Control UI -Control UI 需要一个**安全上下文**（HTTPS 或 localhost）才能生成设备身份。 +Control UI 需要一个**安全上下文**（HTTPS 或 localhost）来生成设备身份。 `gateway.controlUi.allowInsecureAuth` 是一个本地兼容性开关： -- 在 localhost 上，当页面通过非安全 HTTP 加载时，它允许 Control UI 在没有设备身份的情况下进行 auth。 +- 在 localhost 上，它允许页面通过非安全 HTTP 加载时，Control UI 在没有设备身份的情况下完成认证。 - 它不会绕过配对检查。 - 它不会放宽远程（非 localhost）设备身份要求。 -优先使用 HTTPS（Tailscale Serve），或者在 `127.0.0.1` 上打开 UI。 +优先使用 HTTPS（Tailscale Serve）或在 `127.0.0.1` 上打开 UI。 -仅在紧急破窗场景下，`gateway.controlUi.dangerouslyDisableDeviceAuth` -会完全禁用设备身份检查。这会严重降低安全性；除非你正在主动调试并且能很快回滚，否则请保持关闭。 +仅在紧急破玻璃场景下，`gateway.controlUi.dangerouslyDisableDeviceAuth` +会完全禁用设备身份检查。这会严重降低安全性；除非你正在主动调试且可以迅速恢复，否则请保持关闭。 -与这些危险标志分开的是，成功的 `gateway.auth.mode: "trusted-proxy"` -可以在没有设备身份的情况下允许**操作员** Control UI 会话。这是有意设计的 auth 模式行为，不是 `allowInsecureAuth` 的捷径，并且仍然 +与这些危险标志不同，成功配置 `gateway.auth.mode: "trusted-proxy"` +时，可以在没有设备身份的情况下建立**操作员** Control UI 会话。这是有意设计的 +auth 模式行为，不是 `allowInsecureAuth` 的捷径，而且它仍然 不适用于 node 角色的 Control UI 会话。 -当此设置启用时，`openclaw security audit` 会发出警告。 +当启用该设置时，`openclaw security audit` 会发出警告。 ## 不安全或危险标志摘要 -当已知的不安全/危险调试开关被启用时， -`openclaw security audit` 会报告 `config.insecure_or_dangerous_flags`。在生产环境中请保持这些设置未启用。 +当已知不安全/危险的调试开关被启用时， +`openclaw security audit` 会报告 `config.insecure_or_dangerous_flags`。 +在生产环境中请保持这些开关未设置。 @@ -282,8 +289,8 @@ Control UI 需要一个**安全上下文**（HTTPS 或 localhost）才能生成 - `gateway.controlUi.dangerouslyDisableDeviceAuth` - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - 渠道名称匹配（内置渠道和插件渠道；在适用情况下，也可按 - `accounts.` 单独设置）： + 渠道名称匹配（内置和插件渠道；适用时也可在每个 + `accounts.` 下使用）： - `channels.discord.dangerouslyAllowNameMatching` - `channels.slack.dangerouslyAllowNameMatching` @@ -299,7 +306,7 @@ Control UI 需要一个**安全上下文**（HTTPS 或 localhost）才能生成 - `channels.telegram.network.dangerouslyAllowPrivateNetwork`（也支持按账号设置） - 沙箱 Docker（默认值 + 按智能体设置）： + Sandbox Docker（默认值 + 按智能体）： - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` - `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources` @@ -310,30 +317,31 @@ Control UI 需要一个**安全上下文**（HTTPS 或 localhost）才能生成 ## 反向代理配置 -如果你在反向代理（nginx、Caddy、Traefik 等）后面运行 Gateway 网关，请配置 +如果你在反向代理（nginx、Caddy、Traefik 等）后运行 Gateway 网关，请配置 `gateway.trustedProxies`，以正确处理转发的客户端 IP。 -当 Gateway 网关检测到来自**不在** `trustedProxies` 中的地址的代理头时，它将**不会**把连接视为本地客户端。如果 Gateway 网关 auth 被禁用，这些连接会被拒绝。这可以防止身份验证绕过：否则，被代理的连接可能会看起来来自 localhost，从而自动获得信任。 +当 Gateway 网关检测到代理头来自**不在** `trustedProxies` 中的地址时，它将**不会** +把连接视为本地客户端。如果 gateway auth 被禁用，这些连接会被拒绝。这样可以防止认证绕过：否则，被代理的连接可能看起来像是来自 localhost，从而自动获得信任。 -`gateway.trustedProxies` 也会供 `gateway.auth.mode: "trusted-proxy"` 使用，但这种 auth 模式更严格： +`gateway.trustedProxies` 也会用于 `gateway.auth.mode: "trusted-proxy"`，但该认证模式更严格： -- trusted-proxy auth **对来自 loopback 源的代理采用失败即关闭** -- 同主机上的 loopback 反向代理仍然可以使用 `gateway.trustedProxies` 进行本地客户端检测和转发 IP 处理 -- 对于同主机上的 loopback 反向代理，请使用 token/password auth，而不是 `gateway.auth.mode: "trusted-proxy"` +- trusted-proxy auth **会对 loopback 来源的代理执行失败关闭** +- 同主机 loopback 反向代理仍可使用 `gateway.trustedProxies` 进行本地客户端检测和转发 IP 处理 +- 对于同主机 loopback 反向代理，应使用 token/password auth，而不是 `gateway.auth.mode: "trusted-proxy"` ```yaml gateway: trustedProxies: - - "10.0.0.1" # reverse proxy IP - # 可选。默认为 false。 - # 仅当你的代理无法提供 X-Forwarded-For 时才启用。 + - "10.0.0.1" # 反向代理 IP + # 可选。默认 false。 + # 仅在你的代理无法提供 X-Forwarded-For 时启用。 allowRealIpFallback: false auth: mode: password password: ${OPENCLAW_GATEWAY_PASSWORD} ``` -当配置了 `trustedProxies` 时，Gateway 网关会使用 `X-Forwarded-For` 来确定客户端 IP。默认会忽略 `X-Real-IP`，除非明确设置 `gateway.allowRealIpFallback: true`。 +当配置了 `trustedProxies` 时，Gateway 网关会使用 `X-Forwarded-For` 来确定客户端 IP。默认会忽略 `X-Real-IP`，除非显式设置 `gateway.allowRealIpFallback: true`。 良好的反向代理行为（覆盖传入的转发头）： @@ -348,52 +356,54 @@ proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` -## HSTS 和 origin 说明 +## HSTS 和来源说明 -- OpenClaw Gateway 网关优先面向本地/loopback。如果你在反向代理处终止 TLS，请在那里为面向代理的 HTTPS 域设置 HSTS。 -- 如果由 Gateway 网关自身终止 HTTPS，你可以设置 `gateway.http.securityHeaders.strictTransportSecurity`，让 OpenClaw 在响应中发出 HSTS 头。 +- OpenClaw gateway 优先面向本地/loopback。如果你在反向代理处终止 TLS，请在代理所面对的 HTTPS 域名上设置 HSTS。 +- 如果由 gateway 本身终止 HTTPS，你可以设置 `gateway.http.securityHeaders.strictTransportSecurity`，让 OpenClaw 在响应中发送 HSTS 头。 - 详细部署指南见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)。 -- 对于非 loopback 的 Control UI 部署，默认要求设置 `gateway.controlUi.allowedOrigins`。 -- `gateway.controlUi.allowedOrigins: ["*"]` 是显式允许所有浏览器来源的策略，不是加固后的默认值。除非是在严格受控的本地测试中，否则应避免使用。 -- 即使启用了通用的 loopback 豁免，loopback 上的浏览器来源 auth 失败仍会受到速率限制，但锁定键会按规范化后的 `Origin` 值进行范围划分，而不是共享一个 localhost 桶。 -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 头 origin 回退模式；应将其视为由操作员主动选择的危险策略。 -- 应将 DNS 重绑定和代理 Host 头行为视为部署加固问题；保持 `trustedProxies` 严格，并避免将 Gateway 网关直接暴露到公共互联网。 +- 对于非 loopback 的 Control UI 部署，默认要求配置 `gateway.controlUi.allowedOrigins`。 +- `gateway.controlUi.allowedOrigins: ["*"]` 是显式的允许所有浏览器来源策略，不是加固后的默认值。除严格受控的本地测试外，应避免使用。 +- 即使启用了通用 loopback 豁免，loopback 上的浏览器来源认证失败仍会受到速率限制，但锁定键会按规范化后的 `Origin` 值分别作用，而不是共享一个 localhost 桶。 +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 头来源回退模式；应将其视为由操作员主动选择的危险策略。 +- 应将 DNS rebinding 和代理 Host 头行为视为部署加固问题；保持 `trustedProxies` 范围严格，并避免将 gateway 直接暴露到公共互联网。 ## 本地会话日志存储在磁盘上 -OpenClaw 会将会话转录存储到磁盘上的 `~/.openclaw/agents//sessions/*.jsonl`。 +OpenClaw 会将会话记录存储在磁盘上的 `~/.openclaw/agents//sessions/*.jsonl`。 这对于会话连续性以及（可选的）会话记忆索引是必需的，但这也意味着 **任何拥有文件系统访问权限的进程/用户都可以读取这些日志**。应将磁盘访问视为信任 -边界，并锁定 `~/.openclaw` 的权限（参见下方审计部分）。如果你需要在智能体之间实现 -更强隔离，请让它们运行在独立的操作系统用户下，或使用独立主机。 +边界，并锁定 `~/.openclaw` 的权限（见下方审计部分）。如果你需要在不同智能体之间实现 +更强的隔离，请让它们运行在不同的 OS 用户或不同主机下。 -## Node 执行（system.run） +## 节点执行（system.run） -如果已配对 macOS node 节点，Gateway 网关就可以在该节点上调用 `system.run`。这属于 **Mac 上的远程代码执行**： +如果已配对 macOS 节点，Gateway 网关可以在该节点上调用 `system.run`。这属于 **Mac 上的远程代码执行**： -- 需要 node 配对（审批 + token）。 -- Gateway 网关的 node 配对不是逐命令审批界面。它建立的是 node 身份/信任以及 token 签发。 -- Gateway 网关通过 `gateway.nodes.allowCommands` / `denyCommands` 应用粗粒度的全局 node 命令策略。 -- 在 Mac 上通过**设置 → Exec 审批**进行控制（security + ask + allowlist）。 -- 每个 node 的 `system.run` 策略由该 node 自身的 exec 审批文件（`exec.approvals.node.*`）控制，它可以比 Gateway 网关的全局命令 ID 策略更严格，也可以更宽松。 -- 以 `security="full"` 和 `ask="off"` 运行的 node 节点是在遵循默认的受信任操作员模型。除非你的部署明确需要更严格的审批或 allowlist 策略，否则应将其视为预期行为。 -- 审批模式会绑定精确的请求上下文，并在可能时绑定一个具体的本地脚本/文件操作数。如果 OpenClaw 无法为某个解释器/运行时命令精确识别唯一的直接本地文件，则会拒绝基于审批的执行，而不会声称提供完整的语义覆盖。 -- 对于 `host=node`，基于审批的运行还会存储一个规范化的预处理 `systemRunPlan`；之后获得批准的转发会复用该已存储计划，并且 Gateway 网关验证会拒绝在审批请求创建后由调用方修改命令/cwd/session 上下文。 -- 如果你不希望远程执行，请将 security 设为 **deny**，并移除该 Mac 的 node 配对。 +- 需要节点配对（批准 + token）。 +- Gateway 网关节点配对不是逐命令批准表面。它用于建立节点身份/信任并签发 token。 +- Gateway 网关通过 `gateway.nodes.allowCommands` / `denyCommands` 应用粗粒度的全局节点命令策略。 +- 在 Mac 上通过**设置 → Exec 批准**进行控制（security + ask + allowlist）。 +- 每个节点的 `system.run` 策略由节点自身的 exec 批准文件（`exec.approvals.node.*`）控制，它可能比 gateway 的全局命令 ID 策略更严格，也可能更宽松。 +- 以 `security="full"` 和 `ask="off"` 运行的节点，遵循的是默认的受信任操作员模型。除非你的部署明确需要更严格的批准或 allowlist 策略，否则应将其视为预期行为。 +- 批准模式会绑定精确的请求上下文，并在可能时绑定一个具体的本地脚本/文件操作数。如果 OpenClaw 无法为某个解释器/运行时命令精确识别出唯一一个直接本地文件，则会拒绝基于批准的执行，而不会承诺提供完整的语义覆盖。 +- 对于 `host=node`，基于批准的运行还会存储一个规范化的已准备 + `systemRunPlan`；后续已批准的转发会复用该已存储计划，并且 gateway + 验证会拒绝在批准请求创建后由调用方编辑 command/cwd/session 上下文。 +- 如果你不希望进行远程执行，请将 security 设为 **deny**，并移除该 Mac 的节点配对。 -这个区别在分级研判时很重要： +这一区分对于问题分级很重要： -- 一个重新连接的已配对 node 节点通告了不同的命令列表，这本身并不构成漏洞，只要 Gateway 网关全局策略和 node 节点本地 exec 审批仍然强制执行真实的执行边界。 -- 将 node 配对元数据视为隐藏的第二层逐命令审批界面的报告，通常属于策略/UX 理解混淆，而不是安全边界绕过。 +- 一个重新连接的已配对节点通告了不同的命令列表，这本身并不构成漏洞，只要 Gateway 网关的全局策略和节点的本地 exec 批准仍然实际执行着真正的执行边界约束。 +- 把节点配对元数据当作第二层隐藏的逐命令批准层的报告，通常属于策略/UX 误解，而不是安全边界绕过。 -## 动态 Skills（watcher / 远程 node 节点） +## 动态 Skills（watcher / 远程节点） OpenClaw 可以在会话中途刷新 Skills 列表： -- **Skills watcher**：对 `SKILL.md` 的更改可以在智能体下一轮处理时更新 Skills 快照。 -- **远程 node 节点**：连接 macOS node 节点后，可能会使仅限 macOS 的 Skills 变为可用（基于 bin 探测）。 +- **Skills watcher**：对 `SKILL.md` 的更改可在下一个智能体回合更新 Skills 快照。 +- **远程节点**：连接 macOS 节点后，可使仅限 macOS 的 Skills 变为可用（基于二进制探测）。 -应将 skill 文件夹视为**受信任代码**，并限制谁可以修改它们。 +应将 skill 文件夹视为**受信任代码**，并限制可修改它们的人员。 ## 威胁模型 @@ -402,46 +412,50 @@ OpenClaw 可以在会话中途刷新 Skills 列表： - 执行任意 shell 命令 - 读写文件 - 访问网络服务 -- 向任何人发送消息（如果你赋予了它 WhatsApp 访问权限） +- 向任何人发送消息（如果你赋予它 WhatsApp 访问权限） 给你发消息的人可以： -- 试图诱骗你的 AI 执行有害操作 +- 试图诱骗你的 AI 执行不当操作 - 通过社会工程获取你的数据访问权限 -- 探查基础设施细节 +- 探测基础设施细节 ## 核心概念：先做访问控制，再谈智能 -这里的大多数失败并不是什么花哨的漏洞利用——而是“有人给机器人发了消息，然后机器人照做了”。 +这里的大多数失败并不是什么高级攻击——而是“有人给机器人发了条消息，然后机器人照做了”。 -OpenClaw 的立场是： +OpenClaw 的立场： -- **先身份**：决定谁可以和机器人对话（DM 配对 / allowlist / 显式 `open`）。 -- **再范围**：决定机器人被允许在哪里执行操作（群组 allowlist + 提及门槛、工具、沙箱隔离、设备权限）。 -- **最后才是模型**：假设模型可能被操控；要把系统设计成即使被操控，爆炸半径也有限。 +- **身份优先：**先决定谁可以和机器人对话（私信配对 / allowlist / 显式 “open”）。 +- **范围其次：**再决定机器人可以在哪里执行操作（群组 allowlist + 提及门控、工具、沙箱隔离、设备权限）。 +- **模型最后：**假定模型可能被操控；设计时要让这种操控的爆炸半径保持有限。 ## 命令授权模型 -斜杠命令和指令仅对**已授权发送者**生效。授权来源于 +斜杠命令和指令只会对**已授权的发送者**生效。授权来源于 渠道 allowlist/配对以及 `commands.useAccessGroups`（参见 [Configuration](/zh-CN/gateway/configuration) 和 [Slash commands](/zh-CN/tools/slash-commands)）。如果某个渠道的 allowlist 为空或包含 `"*"`， -那么该渠道的命令实际上就是开放的。 +则该渠道上的命令实际上就是开放的。 -`/exec` 是面向已授权操作员的仅会话便捷功能。它**不会**写入配置，也 -不会更改其他会话。 +`/exec` 是供已授权操作员使用的仅限会话的便捷命令。它**不会**写入配置，也**不会** +更改其他会话。 ## 控制平面工具风险 -有两个内置工具可以进行持久化的控制平面更改： +有两个内置工具可以进行持久性的控制平面更改： -- `gateway` 可以通过 `config.schema.lookup` / `config.get` 检查配置，并可以通过 `config.apply`、`config.patch` 和 `update.run` 进行持久化更改。 +- `gateway` 可以通过 `config.schema.lookup` / `config.get` 检查配置，也可以通过 `config.apply`、`config.patch` 和 `update.run` 进行持久性更改。 - `cron` 可以创建定时任务，使其在原始聊天/任务结束后继续运行。 -仅 owner 可用的 `gateway` 运行时工具仍然拒绝重写 -`tools.exec.ask` 或 `tools.exec.security`；旧版 `tools.bash.*` 别名会在写入前 -被规范化到同样受保护的 exec 路径。 +仅限所有者的 `gateway` 运行时工具仍然拒绝重写 +`tools.exec.ask` 或 `tools.exec.security`；旧版 `tools.bash.*` 别名会 +在写入前被规范化为同样受保护的 exec 路径。 +由智能体驱动的 `gateway config.apply` 和 `gateway config.patch` 编辑 +默认采用失败关闭：只有一小部分 prompt、model 和提及门控 +路径可由智能体调整。因此，新的敏感配置树默认会受到保护， +除非它们被有意加入 allowlist。 -对于任何处理不受信任内容的智能体/界面，默认应禁用这些工具： +对于任何处理不受信任内容的智能体/表面，默认应拒绝以下工具： ```json5 { @@ -451,33 +465,33 @@ OpenClaw 的立场是： } ``` -`commands.restart=false` 只会阻止重启操作。它不会禁用 `gateway` 的配置/更新操作。 +`commands.restart=false` 只会阻止重启动作。它不会禁用 `gateway` 配置/更新操作。 ## 插件 -插件会**在进程内**与 Gateway 网关一起运行。应将其视为受信任代码： +插件会在 Gateway 网关**进程内**运行。应将其视为受信任代码： -- 只安装来自你信任来源的插件。 -- 优先使用显式 `plugins.allow` allowlist。 +- 只从你信任的来源安装插件。 +- 优先使用显式的 `plugins.allow` allowlist。 - 启用前先审查插件配置。 -- 修改插件后重启 Gateway 网关。 +- 插件变更后重启 Gateway 网关。 - 如果你安装或更新插件（`openclaw plugins install `、`openclaw plugins update `），应将其视为运行不受信任代码： - - 安装路径是活动插件安装根目录下对应插件的专属目录。 - - OpenClaw 会在安装/更新前运行内置危险代码扫描。`critical` 级发现默认会阻止安装。 - - OpenClaw 会使用 `npm pack`，然后在该目录中运行 `npm install --omit=dev`（npm 生命周期脚本可能会在安装期间执行代码）。 - - 优先使用固定的精确版本（`@scope/pkg@1.2.3`），并在启用前检查磁盘上解包后的代码。 - - `--dangerously-force-unsafe-install` 仅用于破窗场景，适用于插件安装/更新流程中内置扫描的误报。它不会绕过插件 `before_install` hook 策略阻止，也不会绕过扫描失败。 - - 由 Gateway 网关支持的 skill 依赖安装遵循相同的危险/可疑分级：内置 `critical` 级发现默认会阻止，除非调用方显式设置 `dangerouslyForceUnsafeInstall`；而可疑发现仍然只会发出警告。`openclaw skills install` 仍然是独立的 ClawHub skill 下载/安装流程。 + - 安装路径是当前插件安装根目录下对应插件的目录。 + - OpenClaw 会在安装/更新前运行内置危险代码扫描。默认会阻止 `critical` 级别发现。 + - OpenClaw 使用 `npm pack`，然后在该目录中运行 `npm install --omit=dev`（npm 生命周期脚本可能在安装期间执行代码）。 + - 优先使用固定、精确的版本（`@scope/pkg@1.2.3`），并在启用前检查磁盘上解包后的代码。 + - `--dangerously-force-unsafe-install` 仅用于插件安装/更新流程中内置扫描误报时的紧急破玻璃场景。它不会绕过插件 `before_install` hook 策略拦截，也不会绕过扫描失败。 + - 基于 Gateway 网关的 skill 依赖安装遵循相同的 dangerous/suspicious 区分：内置的 `critical` 发现会阻止安装，除非调用方显式设置 `dangerouslyForceUnsafeInstall`，而 suspicious 发现仍然只会警告。`openclaw skills install` 仍是独立的 ClawHub skill 下载/安装流程。 详情见：[Plugins](/zh-CN/tools/plugin) -## DM 访问模型：配对、allowlist、open、disabled +## 私信访问模型：配对、allowlist、open、disabled -当前所有支持 DM 的渠道都支持 DM 策略（`dmPolicy` 或 `*.dm.policy`），用于在消息被处理**之前**限制入站私信： +当前所有支持私信的渠道都支持一个私信策略（`dmPolicy` 或 `*.dm.policy`），用于在消息被处理**之前**对入站私信进行控制： -- `pairing`（默认）：未知发送者会收到一个简短的配对码，机器人会忽略其消息，直到获得批准。配对码 1 小时后过期；重复发送私信不会重复发送配对码，除非创建了新的请求。待处理请求默认每个渠道最多 **3 个**。 -- `allowlist`：未知发送者会被阻止（无配对握手）。 -- `open`：允许任何人发送私信（公开）。**要求**该渠道的 allowlist 包含 `"*"`（显式选择启用）。 +- `pairing`（默认）：未知发送者会收到一个简短的配对码，在获得批准前机器人会忽略其消息。配对码 1 小时后过期；在新的请求创建之前，重复发送私信不会重新发送配对码。默认情况下，每个渠道最多允许 **3 个待处理请求**。 +- `allowlist`：未知发送者会被拦截（没有配对握手）。 +- `open`：允许任何人发送私信（公开）。**要求**该渠道的 allowlist 包含 `"*"`（显式选择加入）。 - `disabled`：完全忽略入站私信。 通过 CLI 批准： @@ -487,11 +501,11 @@ openclaw pairing list openclaw pairing approve ``` -详情和磁盘文件位置见：[Pairing](/zh-CN/channels/pairing) +详情与磁盘文件位置见：[Pairing](/zh-CN/channels/pairing) -## DM 会话隔离（多用户模式） +## 私信会话隔离（多用户模式） -默认情况下，OpenClaw 会将**所有私信都路由到主会话**，这样你的助手就能在不同设备和渠道间保持连续性。如果**有多个人**可以给机器人发送私信（开放私信或多人的 allowlist），请考虑隔离私信会话： +默认情况下，OpenClaw 会将**所有私信路由到主会话**，以便你的助手在设备和渠道之间保持连续性。如果**多个人**都可以给机器人发私信（开放私信或多人的 allowlist），请考虑隔离私信会话： ```json5 { @@ -499,76 +513,76 @@ openclaw pairing approve } ``` -这样可以防止跨用户上下文泄露，同时保持群聊上下文隔离。 +这样可以防止跨用户上下文泄露，同时保持群聊隔离。 -这是消息上下文边界，不是主机管理员边界。如果用户彼此具有对抗性并共享同一 Gateway 网关主机/配置，请按信任边界运行独立的 Gateway 网关。 +这是消息上下文边界，而不是主机管理边界。如果用户彼此具有对抗性，并共享同一个 Gateway 网关主机/配置，请按信任边界运行独立的 Gateway 网关。 -### 安全 DM 模式（推荐） +### 安全私信模式（推荐） -应将上面的片段视为**安全 DM 模式**： +将上面的配置片段视为**安全私信模式**： -- 默认值：`session.dmScope: "main"`（所有私信共享一个会话以保持连续性）。 +- 默认：`session.dmScope: "main"`（所有私信共享一个会话以保持连续性）。 - 本地 CLI 新手引导默认：当未设置时写入 `session.dmScope: "per-channel-peer"`（保留现有显式值）。 -- 安全 DM 模式：`session.dmScope: "per-channel-peer"`（每个渠道 + 发送者组合获得独立的私信上下文）。 -- 跨渠道联系人隔离：`session.dmScope: "per-peer"`（同一类型的所有渠道中，每个发送者共用一个会话）。 +- 安全私信模式：`session.dmScope: "per-channel-peer"`（每个渠道 + 发送者组合获得一个隔离的私信上下文）。 +- 跨渠道对等方隔离：`session.dmScope: "per-peer"`（同类型的所有渠道中，每个发送者共享一个会话）。 -如果你在同一渠道上运行多个账号，请改用 `per-account-channel-peer`。如果同一个人会通过多个渠道联系你，请使用 `session.identityLinks` 将这些私信会话合并为一个规范身份。参见 [Session Management](/zh-CN/concepts/session) 和 [Configuration](/zh-CN/gateway/configuration)。 +如果你在同一渠道上运行多个账号，请改用 `per-account-channel-peer`。如果同一个人通过多个渠道联系你，可使用 `session.identityLinks` 将这些私信会话合并为一个规范身份。参见 [Session Management](/zh-CN/concepts/session) 和 [Configuration](/zh-CN/gateway/configuration)。 ## 私信和群组的 allowlist OpenClaw 有两层彼此独立的“谁可以触发我？”机制： -- **DM allowlist**（`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`；旧版：`channels.discord.dm.allowFrom`、`channels.slack.dm.allowFrom`）：谁被允许在私信中与机器人对话。 - - 当 `dmPolicy="pairing"` 时，批准结果会写入 `~/.openclaw/credentials/` 下按账号划分的配对 allowlist 存储中（默认账号用 `-allowFrom.json`，非默认账号用 `--allowFrom.json`），并与配置中的 allowlist 合并。 -- **群组 allowlist**（按渠道区分）：机器人总体上会接受来自哪些群组/频道/guild 的消息。 +- **私信 allowlist**（`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`；旧版：`channels.discord.dm.allowFrom`、`channels.slack.dm.allowFrom`）：谁被允许在私信中与机器人对话。 + - 当 `dmPolicy="pairing"` 时，批准记录会写入 `~/.openclaw/credentials/` 下按账号划分的配对 allowlist 存储（默认账号为 `-allowFrom.json`，非默认账号为 `--allowFrom.json`），并与配置中的 allowlist 合并。 +- **群组 allowlist**（按渠道区分）：机器人总体上接受哪些群组/频道/guild 的消息。 - 常见模式： - - `channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups`：按群组设置默认值，例如 `requireMention`；设置后，它也会充当群组 allowlist（包含 `"*"` 可保持允许所有的行为）。 - - `groupPolicy="allowlist"` + `groupAllowFrom`：限制在群组会话**内部**谁可以触发机器人（WhatsApp/Telegram/Signal/iMessage/Microsoft Teams）。 - - `channels.discord.guilds` / `channels.slack.channels`：按界面设置 allowlist + 提及默认值。 - - 群组检查顺序如下：先执行 `groupPolicy`/群组 allowlist，再执行提及/回复激活。 + - `channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups`：按群组设置默认值，例如 `requireMention`；设置后它同时也会充当群组 allowlist（包含 `"*"` 可保持允许所有的行为）。 + - `groupPolicy="allowlist"` + `groupAllowFrom`：限制在群组会话中 _谁_ 可以触发机器人（WhatsApp/Telegram/Signal/iMessage/Microsoft Teams）。 + - `channels.discord.guilds` / `channels.slack.channels`：按表面配置 allowlist + 提及默认值。 + - 群组检查按以下顺序运行：先 `groupPolicy`/群组 allowlist，后提及/回复激活。 - 回复机器人消息（隐式提及）**不会**绕过像 `groupAllowFrom` 这样的发送者 allowlist。 - - **安全说明：** 应将 `dmPolicy="open"` 和 `groupPolicy="open"` 视为最后手段。应尽量少用；除非你完全信任房间中的每一位成员，否则优先使用配对 + allowlist。 + - **安全说明：**应将 `dmPolicy="open"` 和 `groupPolicy="open"` 视为最后手段设置。应尽量少用；除非你完全信任房间中的每一位成员，否则优先使用配对 + allowlist。 详情见：[Configuration](/zh-CN/gateway/configuration) 和 [Groups](/zh-CN/channels/groups) -## 提示词注入（是什么，为什么重要） +## 提示词注入（它是什么，为什么重要） -提示词注入是指攻击者构造一条消息，操控模型去执行不安全的操作（“忽略你的指令”、“导出你的文件系统”、“打开这个链接并执行命令”等）。 +提示词注入是指攻击者构造消息，操纵模型去执行不安全的事情（“忽略你的指令”“导出你的文件系统”“打开这个链接并运行命令”等）。 -即使系统提示词很强，**提示词注入也没有被彻底解决**。系统提示词护栏只是软性引导；真正的硬性约束来自工具策略、exec 审批、沙箱隔离和渠道 allowlist（并且操作员也可以按设计将其关闭）。实践中有帮助的做法包括： +即使有很强的系统提示词，**提示词注入也尚未被解决**。系统提示词防护栏只是软性指导；真正的硬性约束来自工具策略、exec 批准、沙箱隔离和渠道 allowlist（并且操作员可以按设计关闭这些约束）。在实践中有帮助的是： -- 锁定入站私信（配对/allowlist）。 -- 在群组中优先使用提及门槛；避免在公共房间部署“始终在线”的机器人。 -- 默认将链接、附件和粘贴的指令视为敌对内容。 -- 在沙箱中运行敏感工具执行；不要让 secrets 出现在智能体可访问的文件系统中。 -- 注意：沙箱隔离是可选启用的。如果沙箱模式关闭，隐式 `host=auto` 会解析为 Gateway 网关主机。显式 `host=sandbox` 仍会以关闭方式失败，因为没有可用的沙箱运行时。如果你希望在配置中显式表达该行为，请设置 `host=gateway`。 -- 将高风险工具（`exec`、`browser`、`web_fetch`、`web_search`）限制给受信任智能体或显式 allowlist。 -- 如果你对解释器（`python`、`node`、`ruby`、`perl`、`php`、`lua`、`osascript`）使用 allowlist，请启用 `tools.exec.strictInlineEval`，这样内联 eval 形式仍然需要显式审批。 -- Shell 审批分析还会拒绝**未加引号 heredoc** 中的 POSIX 参数展开形式（`$VAR`、`$?`、`$$`、`$1`、`$@`、`${…}`），这样 allowlist 中的 heredoc 内容就无法把 shell 展开伪装成普通文本绕过 allowlist 审查。给 heredoc 终止符加引号（例如 `<<'EOF'`）即可选择字面量正文语义；那些本会展开变量的未加引号 heredoc 会被拒绝。 -- **模型选择很重要：** 较旧/较小/旧版模型在抵御提示词注入和工具滥用方面明显更弱。对于启用了工具的智能体，请使用可用范围内最新一代、指令加固能力最强的模型。 +- 保持入站私信处于锁定状态（配对/allowlist）。 +- 在群组中优先使用提及门控；避免在公共房间中使用“始终在线”的机器人。 +- 默认将链接、附件和粘贴的指令视为不受信任内容。 +- 在沙箱中执行敏感工具操作；将 secret 保持在智能体无法访问的文件系统之外。 +- 注意：沙箱隔离是可选启用的。如果 sandbox 模式关闭，隐式 `host=auto` 会解析为 gateway 主机。显式 `host=sandbox` 仍会失败关闭，因为没有可用的 sandbox 运行时。如果你希望在配置中明确表达这种行为，请设置 `host=gateway`。 +- 将高风险工具（`exec`、`browser`、`web_fetch`、`web_search`）限制给受信任的智能体或显式 allowlist。 +- 如果你对解释器进行 allowlist（`python`、`node`、`ruby`、`perl`、`php`、`lua`、`osascript`），请启用 `tools.exec.strictInlineEval`，这样内联 eval 形式仍然需要显式批准。 +- Shell 批准分析还会拒绝**未加引号的 heredoc** 中的 POSIX 参数展开形式（`$VAR`、`$?`、`$$`、`$1`、`$@`、`${…}`），因此被 allowlist 的 heredoc 主体无法将 shell 展开伪装成纯文本绕过 allowlist 审查。对 heredoc 终止符加引号（例如 `<<'EOF'`）即可启用字面量主体语义；未加引号且会触发变量展开的 heredoc 将被拒绝。 +- **模型选择很重要：**较旧/较小/旧式模型在抵御提示词注入和工具滥用方面明显更弱。对于启用了工具的智能体，请使用当前可用的最新一代、指令加固能力最强的模型。 -应视为不受信任内容的危险信号： +应视为不受信任的危险信号： -- “读取这个文件/URL，并严格按照里面说的去做。” +- “读取这个文件/URL，并完全照它说的做。” - “忽略你的系统提示词或安全规则。” -- “泄露你的隐藏指令或工具输出。” -- “把 `~/.openclaw` 或你的日志的完整内容贴出来。” +- “透露你隐藏的指令或工具输出。” +- “把 `~/.openclaw` 或你的日志完整内容贴出来。” ## 外部内容特殊 token 清洗 -OpenClaw 会在封装后的外部内容和元数据到达模型之前，剥离常见的自托管 LLM chat-template 特殊 token 字面量。覆盖的标记族包括 Qwen / ChatML、Llama、Gemma、Mistral、Phi，以及 GPT-OSS 的角色/轮次 token。 +OpenClaw 会在包裹外部内容和元数据后、送达模型之前，去除常见的自托管 LLM chat-template 特殊 token 字面量。覆盖的标记家族包括 Qwen/ChatML、Llama、Gemma、Mistral、Phi 以及 GPT-OSS 的角色/轮次 token。 原因： -- 某些以前置自托管模型的 OpenAI 兼容后端，有时会保留用户文本中出现的特殊 token，而不是将其屏蔽。攻击者如果能够写入入站外部内容（抓取到的页面、邮件正文、文件内容工具输出），原本就可能借此注入伪造的 `assistant` 或 `system` 角色边界，从而逃逸封装外部内容时设置的护栏。 -- 清洗发生在外部内容封装层，因此它会统一适用于 fetch / read 工具以及入站渠道内容，而不是按 provider 分别处理。 -- 出站模型响应已经有独立的清洗器，会从面向用户的回复中剥离泄露的 ``、`` 及类似脚手架。外部内容清洗器则是对应的入站版本。 +- 以前置自托管模型的 OpenAI 兼容后端有时会保留出现在用户文本中的特殊 token，而不是将其屏蔽。攻击者如果能写入入站外部内容（抓取的页面、邮件正文、文件内容工具输出），就可能注入伪造的 `assistant` 或 `system` 角色边界，从而逃逸外部内容包裹防护栏。 +- 清洗发生在外部内容包裹层，因此它统一适用于 fetch/read 工具和入站渠道内容，而不是按 provider 分别处理。 +- 出站模型响应已经有独立的清洗器，用于去除用户可见回复中泄露的 ``、`` 及类似脚手架。外部内容清洗则是对应的入站版本。 -这并不能替代本页中的其他加固措施——`dmPolicy`、allowlist、exec 审批、沙箱隔离和 `contextVisibility` 仍然承担主要作用。它封堵的是一种特定的 tokenizer 层绕过方式，针对的是那些会原样转发带有特殊 token 的用户文本的自托管栈。 +这并不能替代本页中的其他加固措施——`dmPolicy`、allowlist、exec 批准、沙箱隔离和 `contextVisibility` 仍然承担主要防护作用。它修补的是一种特定的 tokenizer 层绕过，适用于那些会原样转发带特殊 token 的用户文本的自托管栈。 ## 不安全外部内容绕过标志 -OpenClaw 包含可显式关闭外部内容安全封装的绕过标志： +OpenClaw 包含一些显式绕过标志，可禁用外部内容安全包裹： - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` @@ -576,138 +590,134 @@ OpenClaw 包含可显式关闭外部内容安全封装的绕过标志： 指导建议： -- 在生产环境中保持这些设置未启用/为 false。 +- 在生产环境中保持这些值未设置/为 false。 - 仅在严格限定范围的调试中临时启用。 -- 如果启用，请隔离该智能体（沙箱隔离 + 最小工具集 + 专用会话命名空间）。 +- 如果启用，请隔离该智能体（沙箱 + 最小工具 + 专用会话命名空间）。 Hooks 风险说明： -- Hook 负载属于不受信任内容，即使其投递来自你控制的系统也是如此（邮件/文档/网页内容都可能携带提示词注入）。 -- 较弱的模型层级会增加这一风险。对于由 hook 驱动的自动化，请优先选择强大的现代模型层级，并保持严格的工具策略（`tools.profile: "messaging"` 或更严格），同时在可能时启用沙箱隔离。 +- Hook 负载属于不受信任内容，即使投递来自你控制的系统也是如此（邮件/文档/网页内容都可能携带提示词注入）。 +- 较弱的模型层级会放大这一风险。对于由 hook 驱动的自动化，请优先选择强大的现代模型层级，并保持严格的工具策略（`tools.profile: "messaging"` 或更严格），在可能时配合沙箱隔离。 -### 提示词注入不需要公开私信 +### 提示词注入并不需要开放私信 即使**只有你自己**可以给机器人发消息，提示词注入仍然可能通过 -机器人读取的任何**不受信任内容**发生（网页搜索/抓取结果、浏览器页面、 -电子邮件、文档、附件、粘贴的日志/代码）。换句话说：威胁面不只是发送者； -**内容本身**也可能携带对抗性指令。 +机器人读取的任何**不受信任内容**发生（web 搜索/抓取结果、浏览器页面、 +电子邮件、文档、附件、粘贴的日志/代码）。换句话说：发送者并不是 +唯一的威胁表面；**内容本身**也可能携带对抗性指令。 -启用工具后，典型风险是泄露上下文或触发 -工具调用。降低爆炸半径的方法包括： +启用工具后，典型风险是泄露上下文或触发工具调用。可通过以下方式缩小爆炸半径： -- 使用只读或禁用工具的**阅读智能体**来总结不受信任内容， - 然后再把摘要传给你的主智能体。 -- 除非确有需要，否则不要为启用了工具的智能体开启 `web_search` / `web_fetch` / `browser`。 -- 对于 OpenResponses URL 输入（`input_file` / `input_image`），设置严格的 +- 使用只读或禁用工具的**reader 智能体**来总结不受信任内容， + 然后再将摘要传给你的主智能体。 +- 对启用了工具的智能体，在非必要情况下关闭 `web_search` / `web_fetch` / `browser`。 +- 对于 OpenResponses URL 输入（`input_file` / `input_image`），请严格设置 `gateway.http.endpoints.responses.files.urlAllowlist` 和 `gateway.http.endpoints.responses.images.urlAllowlist`，并保持 `maxUrlParts` 较低。 空 allowlist 会被视为未设置；如果你想完全禁用 URL 抓取，请使用 `files.allowUrl: false` / `images.allowUrl: false`。 - 对于 OpenResponses 文件输入，解码后的 `input_file` 文本仍会作为 - **不受信任的外部内容**注入。不要因为文本是由 Gateway 网关本地解码的，就认为文件文本是可信的。 - 注入块仍会携带显式的 + **不受信任的外部内容**注入。不要因为 Gateway 网关是在本地解码文件文本，就认为它是可信的。 + 注入块仍然会携带显式的 `<<>>` 边界标记以及 `Source: External` - 元数据，尽管此路径省略了更长的 `SECURITY NOTICE:` 横幅。 -- 当媒体理解在将文档附件中的文本提取后追加到媒体提示词时，也会应用同样基于标记的封装。 -- 对于任何会接触不受信任输入的智能体，启用沙箱隔离和严格的工具 allowlist。 -- 不要把 secrets 放进提示词；应通过 Gateway 网关主机上的环境变量/配置来传递。 + 元数据，尽管此路径省略了较长的 `SECURITY NOTICE:` 横幅。 +- 当媒体理解在将文档文本附加到媒体提示词之前提取附加文档中的文本时，也会应用相同的基于标记的包裹方式。 +- 对任何接触不受信任输入的智能体启用沙箱隔离和严格的工具 allowlist。 +- 不要把 secret 放进提示词；应通过 gateway 主机上的 env/config 传递它们。 ### 自托管 LLM 后端 -诸如 vLLM、SGLang、TGI、LM Studio -或自定义 Hugging Face tokenizer 栈之类的 OpenAI 兼容自托管后端，在 -处理 chat-template 特殊 token 的方式上，可能与托管 provider 不同。如果某个后端会将 -`<|im_start|>`、`<|start_header_id|>` 或 `` 之类的字面字符串 -在用户内容中也 token 化为结构性的 chat-template token， -那么不受信任文本就可能尝试在 tokenizer 层伪造角色边界。 +OpenAI 兼容的自托管后端，例如 vLLM、SGLang、TGI、LM Studio， +或自定义 Hugging Face tokenizer 栈，在处理 +chat-template 特殊 token 时，行为可能与托管 provider 不同。如果某个后端会把 +用户内容中的字面字符串（例如 `<|im_start|>`、`<|start_header_id|>` 或 ``） +tokenize 为结构化 chat-template token，那么不受信任文本就可能尝试在 tokenizer 层伪造角色边界。 -OpenClaw 会在将封装后的外部内容发送给模型之前， -剥离常见模型族的特殊 token 字面量。请保持外部内容封装启用，并在后端支持的情况下， -优先选择会对用户提供内容中的特殊 token 进行拆分或转义的后端设置。像 OpenAI -和 Anthropic 这样的托管 provider 已经在请求侧应用了各自的清洗措施。 +OpenClaw 会在将包裹后的外部内容分发给模型之前，去除常见模型家族的特殊 token 字面量。请保持外部内容包裹启用，并在后端支持时优先使用会拆分或转义用户提供内容中特殊 token 的设置。OpenAI +和 Anthropic 等托管 provider 已经会在请求侧执行自己的清洗。 ### 模型强度（安全说明） -不同模型层级的提示词注入抵抗能力**并不相同**。更小/更便宜的模型通常更容易遭受工具滥用和指令劫持，尤其是在对抗性提示词下。 +不同模型层级对提示词注入的抵抗能力**并不一致**。更小/更便宜的模型通常更容易受到工具滥用和指令劫持，尤其是在对抗性提示词下。 -对于启用了工具的智能体或会读取不受信任内容的智能体，较旧/较小模型带来的提示词注入风险通常过高。不要在弱模型层级上运行这些工作负载。 +对于启用了工具的智能体，或会读取不受信任内容的智能体，较旧/较小模型带来的提示词注入风险通常过高。不要在弱模型层级上运行这些工作负载。 建议： -- 对于任何能够运行工具或接触文件/网络的机器人，**使用最新一代、最强层级的模型**。 -- **不要在启用了工具的智能体或不受信任收件箱上使用较旧/较弱/较小的模型层级**；提示词注入风险过高。 -- 如果你必须使用较小模型，**请缩小爆炸半径**（只读工具、强沙箱隔离、最小文件系统访问、严格 allowlist）。 -- 运行小模型时，**为所有会话启用沙箱隔离**，并且**禁用 `web_search` / `web_fetch` / `browser`**，除非输入受到严格控制。 -- 对于仅聊天、输入受信任且没有工具的个人助理，较小模型通常是可以接受的。 +- 对于任何可以运行工具或接触文件/网络的机器人，**使用最新一代、最佳档位的模型**。 +- 对于启用了工具的智能体或不受信任收件箱，**不要使用较旧/较弱/较小的档位**；提示词注入风险过高。 +- 如果你必须使用较小模型，**缩小爆炸半径**（只读工具、强沙箱隔离、最小化文件系统访问、严格 allowlist）。 +- 运行小模型时，**为所有会话启用沙箱隔离**，并且**禁用 `web_search`/`web_fetch`/`browser`**，除非输入被严格控制。 +- 对于仅聊天、输入可信且不使用工具的个人助理，较小模型通常是可以接受的。 ## 群组中的 reasoning 和详细输出 `/reasoning`、`/verbose` 和 `/trace` 可能会暴露内部推理、工具 -输出或插件诊断信息，而这些内容 -原本并不适合公开渠道。在群组环境中，应将它们视为**仅用于调试** -的功能，除非你明确需要，否则请保持关闭。 +输出或插件诊断信息， +而这些内容原本并不适合出现在公共渠道中。在群组场景下，应将它们视为**仅调试用途** +，并在你明确需要之前保持关闭。 指导建议： -- 在公开房间中保持 `/reasoning`、`/verbose` 和 `/trace` 关闭。 -- 如果启用，也只应在受信任的私信或严格受控的房间中启用。 -- 请记住：verbose 和 trace 输出可能包含工具参数、URL、插件诊断信息以及模型看到的数据。 +- 在公共房间中保持 `/reasoning`、`/verbose` 和 `/trace` 关闭。 +- 如果要启用，只应在受信任的私信或严格受控的房间中启用。 +- 请记住：verbose 和 trace 输出可能包含工具参数、URL、插件诊断以及模型看到的数据。 ## 配置加固示例 ### 文件权限 -在 Gateway 网关主机上保持配置和状态私有： +在 gateway 主机上保持配置和状态私有： - `~/.openclaw/openclaw.json`：`600`（仅用户可读写） - `~/.openclaw`：`700`（仅用户可访问） -`openclaw doctor` 可以发出警告并提供收紧这些权限的建议。 +`openclaw doctor` 可以发出警告，并提示收紧这些权限。 -### 网络暴露（bind、port、防火墙） +### 网络暴露（bind、端口、防火墙） -Gateway 网关在单个端口上复用 **WebSocket + HTTP**： +Gateway 网关会在单个端口上复用 **WebSocket + HTTP**： - 默认值：`18789` -- 配置/flags/环境变量：`gateway.port`、`--port`、`OPENCLAW_GATEWAY_PORT` +- config/flags/env：`gateway.port`、`--port`、`OPENCLAW_GATEWAY_PORT` -这个 HTTP 界面包括 Control UI 和 canvas host： +这个 HTTP 表面包括 Control UI 和 canvas host： - Control UI（SPA 资源）（默认基础路径 `/`） -- Canvas host：`/__openclaw__/canvas/` 和 `/__openclaw__/a2ui/`（任意 HTML / JS；应视为不受信任内容） +- Canvas host：`/__openclaw__/canvas/` 和 `/__openclaw__/a2ui/`（任意 HTML/JS；应视为不受信任内容） -如果你在普通浏览器中加载 canvas 内容，应像对待其他不受信任网页一样对待它： +如果你在普通浏览器中加载 canvas 内容，应像对待任何其他不受信任网页一样处理： - 不要将 canvas host 暴露给不受信任的网络/用户。 -- 除非你完全理解其中影响，否则不要让 canvas 内容与高权限 Web 界面共享同一 origin。 +- 除非你完全理解其影响，否则不要让 canvas 内容与特权 Web 表面共享同一来源。 Bind 模式控制 Gateway 网关监听的位置： - `gateway.bind: "loopback"`（默认）：只有本地客户端可以连接。 -- 非 loopback 绑定（`"lan"`、`"tailnet"`、`"custom"`）会扩大攻击面。只有在启用了 Gateway 网关 auth（共享 token / password，或正确配置的非 loopback trusted proxy）并配合真实防火墙时才应使用。 +- 非 loopback bind（`"lan"`、`"tailnet"`、`"custom"`）会扩大攻击面。只有在启用了 gateway auth（共享 token/password 或正确配置的非 loopback trusted proxy）并配合真实防火墙时才应使用。 经验法则： -- 优先使用 Tailscale Serve，而不是 LAN 绑定（Serve 会让 Gateway 网关保持在 loopback 上，由 Tailscale 处理访问）。 -- 如果必须绑定到 LAN，请用防火墙将端口限制为严格的源 IP allowlist；不要广泛做端口转发。 -- 永远不要将未认证的 Gateway 网关暴露在 `0.0.0.0` 上。 +- 优先使用 Tailscale Serve，而不是 LAN bind（Serve 会让 Gateway 网关保持在 loopback 上，并由 Tailscale 处理访问控制）。 +- 如果你必须绑定到 LAN，请通过防火墙将端口限制为严格的源 IP allowlist；不要广泛地做端口转发。 +- 绝不要在 `0.0.0.0` 上无认证地暴露 Gateway 网关。 ### 使用 UFW 的 Docker 端口发布 -如果你在 VPS 上用 Docker 运行 OpenClaw，请记住，已发布的容器端口 -（`-p HOST:CONTAINER` 或 Compose `ports:`）会通过 Docker 的转发链路由， -而不只是主机的 `INPUT` 规则。 +如果你在 VPS 上通过 Docker 运行 OpenClaw，请记住，已发布的容器端口 +（`-p HOST:CONTAINER` 或 Compose `ports:`）是通过 Docker 的转发链路由的， +而不仅仅是主机的 `INPUT` 规则。 -为了让 Docker 流量与防火墙策略保持一致，请在 -`DOCKER-USER` 中强制执行规则（该链会在 Docker 自身的 accept 规则之前求值）。 -在许多现代发行版上，`iptables` / `ip6tables` 使用的是 `iptables-nft` 前端， +为了让 Docker 流量与你的防火墙策略保持一致，请在 +`DOCKER-USER` 中强制执行规则（这个链会在 Docker 自己的 accept 规则之前被评估）。 +在许多现代发行版上，`iptables`/`ip6tables` 使用的是 `iptables-nft` 前端， 但这些规则仍会应用到 nftables 后端。 最小 allowlist 示例（IPv4）： ```bash -# /etc/ufw/after.rules（作为独立的 *filter section 追加） +# /etc/ufw/after.rules（以独立的 *filter 段追加） *filter :DOCKER-USER - [0:0] -A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN @@ -723,14 +733,14 @@ Bind 模式控制 Gateway 网关监听的位置： COMMIT ``` -IPv6 使用独立的表。如果启用了 Docker IPv6， -请在 `/etc/ufw/after6.rules` 中添加匹配的策略。 +IPv6 有单独的表。如果启用了 +Docker IPv6，请在 `/etc/ufw/after6.rules` 中添加匹配的策略。 -避免在文档示例中硬编码像 `eth0` 这样的接口名。接口名 -会因 VPS 镜像而异（`ens3`、`enp*` 等），不匹配时可能会意外 -跳过你的拒绝规则。 +避免在文档片段中硬编码像 `eth0` 这样的接口名。接口名 +会因 VPS 镜像而异（`ens3`、`enp*` 等），不匹配可能导致 +你的拒绝规则被意外跳过。 -重载后的快速验证： +重新加载后的快速验证： ```bash ufw reload @@ -739,22 +749,22 @@ ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` -预期对外开放的端口应当只包括你有意暴露的内容（对大多数 -配置来说：SSH + 你的反向代理端口）。 +预期的对外开放端口应只包括你有意暴露的那些（对于大多数 +配置：SSH + 你的反向代理端口）。 -### mDNS / Bonjour 发现 +### mDNS/Bonjour 发现 -Gateway 网关会通过 mDNS 广播其存在（`_openclaw-gw._tcp`，端口 5353），用于本地设备发现。在 full 模式下，这还会包含可能暴露运行细节的 TXT 记录： +Gateway 网关会通过 mDNS 广播其存在（`_openclaw-gw._tcp`，端口 5353），用于本地设备发现。在 full 模式下，这还包括可能暴露运行细节的 TXT 记录： -- `cliPath`：CLI 二进制文件的完整文件系统路径（会泄露用户名和安装位置） -- `sshPort`：声明主机上可用的 SSH +- `cliPath`：CLI 二进制文件的完整文件系统路径（会暴露用户名和安装位置） +- `sshPort`：通告主机上可用的 SSH - `displayName`、`lanHost`：主机名信息 -**运行安全注意事项：** 广播基础设施细节会让本地网络中的任何人更容易进行侦察。即使是文件系统路径和 SSH 可用性这类“看似无害”的信息，也会帮助攻击者绘制你的环境图谱。 +**运行安全注意事项：**广播基础设施细节会让本地网络中的任何人更容易进行侦察。即使是文件系统路径和 SSH 可用性这类“看似无害”的信息，也能帮助攻击者绘制你的环境图谱。 **建议：** -1. **Minimal 模式**（默认值，推荐用于暴露的 Gateway 网关）：从 mDNS 广播中省略敏感字段： +1. **最小模式**（默认，推荐用于已暴露的 gateway） ：从 mDNS 广播中省略敏感字段： ```json5 { @@ -764,7 +774,7 @@ Gateway 网关会通过 mDNS 广播其存在（`_openclaw-gw._tcp`，端口 5353 } ``` -2. 如果你不需要本地设备发现，**可完全禁用**： +2. **完全禁用**，如果你不需要本地设备发现： ```json5 { @@ -774,7 +784,7 @@ Gateway 网关会通过 mDNS 广播其存在（`_openclaw-gw._tcp`，端口 5353 } ``` -3. **Full 模式**（显式启用）：在 TXT 记录中包含 `cliPath` + `sshPort`： +3. **完整模式**（选择性启用）：在 TXT 记录中包含 `cliPath` + `sshPort`： ```json5 { @@ -784,19 +794,19 @@ Gateway 网关会通过 mDNS 广播其存在（`_openclaw-gw._tcp`，端口 5353 } ``` -4. **环境变量**（替代方式）：设置 `OPENCLAW_DISABLE_BONJOUR=1`，无需修改配置即可禁用 mDNS。 +4. **环境变量**（替代方案）：设置 `OPENCLAW_DISABLE_BONJOUR=1`，无需更改配置即可禁用 mDNS。 -在 minimal 模式下，Gateway 网关仍会广播足够用于设备发现的信息（`role`、`gatewayPort`、`transport`），但会省略 `cliPath` 和 `sshPort`。需要 CLI 路径信息的应用，仍可通过经过身份验证的 WebSocket 连接获取。 +在最小模式下，Gateway 网关仍会广播足以完成设备发现的信息（`role`、`gatewayPort`、`transport`），但不会包含 `cliPath` 和 `sshPort`。需要 CLI 路径信息的应用可以改为通过经过认证的 WebSocket 连接获取。 -### 锁定 Gateway 网关 WebSocket（本地 auth） +### 锁定 Gateway 网关 WebSocket（本地认证） -Gateway 网关 auth **默认是必需的**。如果没有配置有效的 Gateway 网关 auth 路径， -Gateway 网关会拒绝 WebSocket 连接（失败即关闭）。 +默认情况下，Gateway auth **是必需的**。如果没有配置有效的 gateway auth 路径， +Gateway 网关会拒绝 WebSocket 连接（失败关闭）。 -新手引导默认会生成一个 token（即使是在 loopback 上），因此 -本地客户端也必须进行身份验证。 +新手引导默认会生成一个 token（即使是 loopback），因此 +本地客户端也必须进行认证。 -设置一个 token，使**所有** WS 客户端都必须通过身份验证： +设置一个 token，这样**所有** WS 客户端都必须认证： ```json5 { @@ -806,146 +816,149 @@ Gateway 网关会拒绝 WebSocket 连接（失败即关闭）。 } ``` -Doctor 可以为你生成一个：`openclaw doctor --generate-gateway-token`。 +Doctor 可以帮你生成一个：`openclaw doctor --generate-gateway-token`。 注意：`gateway.remote.token` / `.password` 是客户端凭证来源。 -它们**本身并不会**保护本地 WS 访问。 -只有当 `gateway.auth.*` -未设置时，本地调用路径才可以将 `gateway.remote.*` 作为回退。 -如果 `gateway.auth.token` / `gateway.auth.password` 是通过 -SecretRef 显式配置但未能解析，则解析会失败即关闭（不会被远程回退所掩盖）。 -可选项：使用 `wss://` 时，可通过 `gateway.remote.tlsFingerprint` 固定远程 TLS。 -明文 `ws://` 默认仅限 loopback。对于受信任的私有网络 -路径，可在客户端进程上设置 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` -作为破窗措施。这刻意只支持进程环境变量，而不是 +它们本身**不会**保护本地 WS 访问。 +只有在 `gateway.auth.*` 未设置时， +本地调用路径才会将 `gateway.remote.*` 作为回退使用。 +如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` +但无法解析，则解析会失败关闭（不会被 remote 回退掩盖）。 +可选项：在使用 `wss://` 时，可通过 `gateway.remote.tlsFingerprint` 固定远程 TLS。 +默认情况下，明文 `ws://` 仅限 loopback。对于受信任的私有网络 +路径，可在客户端进程上设置 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 作为 +紧急破玻璃方案。这一设置有意仅限进程环境变量，而不是 `openclaw.json` 配置键。 +移动端配对，以及 Android 手动或扫描得到的 gateway 路由要求更严格： +明文仅对 loopback 可接受；私有 LAN、link-local、`.local` 以及 +无点主机名必须使用 TLS，除非你显式选择启用受信任私有网络明文路径。 本地设备配对： -- 为了让同主机客户端使用顺畅，直接本地 loopback 连接的设备配对会自动批准。 -- OpenClaw 还提供一条严格限定的后端/容器本地自连接路径，用于受信任的共享密钥辅助流程。 -- Tailnet 和 LAN 连接（包括同主机 tailnet 绑定）都被视为远程连接，因此配对仍需要审批。 -- loopback 请求上的转发头证据会使其失去 loopback - 本地性资格。元数据升级自动批准的适用范围也被严格限制。两项规则都见 +- 为了让同主机客户端使用更顺畅，对于直接的本地 loopback 连接，设备配对会自动批准。 +- OpenClaw 还提供一条狭窄的后端/容器本地自连接路径，用于受信任共享 secret 辅助流。 +- Tailnet 和 LAN 连接（包括同主机 tailnet bind）在配对上都被视为远程，仍然需要批准。 +- 如果 loopback 请求中带有转发头证据，就不再视为 loopback + 本地连接。元数据升级自动批准仅限于狭窄范围。两项规则详见 [Gateway pairing](/zh-CN/gateway/pairing)。 -Auth 模式： +认证模式： -- `gateway.auth.mode: "token"`：共享 bearer token（大多数配置推荐）。 -- `gateway.auth.mode: "password"`：password auth（建议通过环境变量设置：`OPENCLAW_GATEWAY_PASSWORD`）。 -- `gateway.auth.mode: "trusted-proxy"`：信任支持身份感知的反向代理对用户进行身份验证，并通过头传递身份（见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。 +- `gateway.auth.mode: "token"`：共享 bearer token（推荐用于大多数配置）。 +- `gateway.auth.mode: "password"`：密码认证（建议通过 env 设置：`OPENCLAW_GATEWAY_PASSWORD`）。 +- `gateway.auth.mode: "trusted-proxy"`：信任具备身份感知能力的反向代理来完成用户认证，并通过头传递身份（见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。 -轮换检查清单（token / password）： +轮换清单（token/password）： 1. 生成/设置新的 secret（`gateway.auth.token` 或 `OPENCLAW_GATEWAY_PASSWORD`）。 2. 重启 Gateway 网关（如果由 macOS 应用监管 Gateway 网关，则重启该应用）。 -3. 更新所有远程客户端（在调用 Gateway 网关的机器上更新 `gateway.remote.token` / `.password`）。 -4. 验证旧凭证已无法再用于连接。 +3. 更新所有远程客户端（调用 Gateway 网关的机器上的 `gateway.remote.token` / `.password`）。 +4. 验证旧凭证已无法再连接。 ### Tailscale Serve 身份头 当 `gateway.auth.allowTailscale` 为 `true`（Serve 的默认值）时，OpenClaw 会接受 Tailscale Serve 身份头（`tailscale-user-login`）用于 Control -UI / WebSocket 身份验证。OpenClaw 会通过本地 Tailscale 守护进程（`tailscale whois`） -解析 `x-forwarded-for` 地址，并将结果与该头进行匹配，以验证身份。此逻辑仅对命中 loopback +UI/WebSocket 认证。OpenClaw 会通过本地 Tailscale 守护进程 +（`tailscale whois`）解析 `x-forwarded-for` 地址并与该头进行匹配，以验证身份。此逻辑只会对命中 loopback 且包含由 Tailscale 注入的 `x-forwarded-for`、`x-forwarded-proto` 和 `x-forwarded-host` -的请求生效。 +的请求触发。 对于这条异步身份检查路径，来自同一 `{scope, ip}` -的失败尝试会先被串行化，然后限流器才记录失败。 -因此，同一个 Serve 客户端的并发错误重试可能会让第二次尝试立即被锁定， -而不是像两个普通不匹配请求那样竞争通过。 +的失败尝试会在限速器记录失败前被串行化。 +因此，来自同一个 Serve 客户端的并发错误重试 +可能会让第二次尝试被立即锁定，而不是像两个普通不匹配请求那样并发穿过。 HTTP API 端点（例如 `/v1/*`、`/tools/invoke` 和 `/api/channels/*`） -**不会**使用 Tailscale 身份头 auth。它们仍然遵循 Gateway 网关 -配置的 HTTP auth 模式。 +**不会**使用 Tailscale 身份头认证。它们仍然遵循 gateway +已配置的 HTTP 认证模式。 重要边界说明： -- Gateway 网关 HTTP bearer auth 实际上等同于全有或全无的操作员访问。 -- 应将能够调用 `/v1/chat/completions`、`/v1/responses` 或 `/api/channels/*` 的凭证视为该 Gateway 网关的完全访问级操作员 secret。 -- 在 OpenAI 兼容 HTTP 界面上，共享密钥 bearer auth 会恢复智能体轮次的完整默认操作员作用域（`operator.admin`、`operator.approvals`、`operator.pairing`、`operator.read`、`operator.talk.secrets`、`operator.write`）和 owner 语义；更窄的 `x-openclaw-scopes` 值不会削减这一共享密钥路径。 -- HTTP 上的按请求 scope 语义仅在请求来自带身份的模式时适用，例如 trusted proxy auth 或私有入口上的 `gateway.auth.mode="none"`。 -- 在这些带身份的模式下，如果省略 `x-openclaw-scopes`，则会回退到正常的默认操作员作用域集；当你希望更窄的作用域集时，请显式发送该头。 -- `/tools/invoke` 遵循同样的共享密钥规则：token / password bearer auth 在这里也被视为完全操作员访问，而带身份的模式仍会尊重声明的作用域。 +- Gateway HTTP bearer auth 实际上等同于全有或全无的操作员访问。 +- 能调用 `/v1/chat/completions`、`/v1/responses` 或 `/api/channels/*` 的凭证，应视为该 gateway 的完全访问操作员 secret。 +- 在 OpenAI 兼容 HTTP 表面上，共享 secret bearer auth 会恢复完整的默认操作员作用域（`operator.admin`、`operator.approvals`、`operator.pairing`、`operator.read`、`operator.talk.secrets`、`operator.write`）以及智能体回合的 owner 语义；更窄的 `x-openclaw-scopes` 值不会缩小这一共享 secret 路径。 +- HTTP 上的按请求作用域语义，仅适用于请求来自具备身份承载能力的模式时，例如 trusted proxy auth 或私有入口上的 `gateway.auth.mode="none"`。 +- 在这些具备身份承载能力的模式下，如果省略 `x-openclaw-scopes`，则会回退到正常的默认操作员作用域集合；如果你想要更窄的作用域集合，请显式发送该头。 +- `/tools/invoke` 遵循相同的共享 secret 规则：在那里 token/password bearer auth 也被视为完整操作员访问，而具备身份承载能力的模式仍会遵守声明的作用域。 - 不要与不受信任的调用方共享这些凭证；应按信任边界使用独立的 Gateway 网关。 -**信任假设：** 无 token 的 Serve auth 假设 Gateway 网关主机是受信任的。 -不要把它当作防护敌对同主机进程的机制。如果不受信任的 -本地代码可能会在 Gateway 网关主机上运行，请禁用 `gateway.auth.allowTailscale`， -并要求使用 `gateway.auth.mode: "token"` 或 -`"password"` 进行显式共享密钥 auth。 +**信任假设：**无 token 的 Serve auth 假定 gateway 主机是受信任的。 +不要把它当作防御同主机敌对进程的保护机制。如果 gateway 主机上 +可能运行不受信任的本地代码，请禁用 `gateway.auth.allowTailscale`， +并要求显式共享 secret 认证：`gateway.auth.mode: "token"` 或 +`"password"`。 -**安全规则：** 不要从你自己的反向代理转发这些头。如果 -你在 Gateway 网关前终止 TLS 或使用代理，请禁用 -`gateway.auth.allowTailscale`，并改用共享密钥 auth（`gateway.auth.mode: +**安全规则：**不要通过你自己的反向代理转发这些头。如果 +你在 gateway 前终止 TLS 或做代理，请禁用 +`gateway.auth.allowTailscale`，并改用共享 secret auth（`gateway.auth.mode: "token"` 或 `"password"`）或 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)。 受信任代理： - 如果你在 Gateway 网关前终止 TLS，请将 `gateway.trustedProxies` 设置为你的代理 IP。 -- OpenClaw 会信任来自这些 IP 的 `x-forwarded-for`（或 `x-real-ip`），以便在本地配对检查和 HTTP auth / 本地检查中确定客户端 IP。 -- 确保你的代理会**覆盖** `x-forwarded-for`，并阻止对 Gateway 网关端口的直接访问。 +- OpenClaw 会信任来自这些 IP 的 `x-forwarded-for`（或 `x-real-ip`），以确定客户端 IP，用于本地配对检查以及 HTTP auth/本地性检查。 +- 确保你的代理**覆盖** `x-forwarded-for`，并阻止对 Gateway 网关端口的直接访问。 参见 [Tailscale](/zh-CN/gateway/tailscale) 和 [Web overview](/zh-CN/web)。 -### 通过 node host 进行浏览器控制（推荐） +### 通过节点主机进行浏览器控制（推荐） -如果你的 Gateway 网关是远程的，但浏览器运行在另一台机器上，请在浏览器所在机器上运行一个 **node host** -，并让 Gateway 网关代理浏览器操作（见 [Browser tool](/zh-CN/tools/browser)）。 -应将 node 配对视为管理员访问。 +如果你的 Gateway 网关是远程的，但浏览器运行在另一台机器上，请在浏览器所在机器上运行一个 **node host**， +并让 Gateway 网关代理浏览器操作（见 [Browser tool](/zh-CN/tools/browser)）。 +应将节点配对视为管理员访问。 推荐模式： -- 让 Gateway 网关和 node host 位于同一个 tailnet（Tailscale）上。 -- 有意识地完成 node 配对；如果你不需要浏览器代理路由，请将其关闭。 +- 让 Gateway 网关和 node host 处于同一个 tailnet（Tailscale）中。 +- 有意地进行节点配对；如果不需要浏览器代理路由，则将其禁用。 避免： -- 通过 LAN 或公共互联网暴露 relay / control 端口。 -- 对浏览器控制端点使用 Tailscale Funnel（公共暴露）。 +- 通过 LAN 或公网暴露 relay/control 端口。 +- 对浏览器控制端点使用 Tailscale Funnel（公开暴露）。 -### 磁盘上的 secrets +### 磁盘上的 secret -应假定 `~/.openclaw/`（或 `$OPENCLAW_STATE_DIR/`）下的任何内容都可能包含 secrets 或私有数据： +应假定 `~/.openclaw/`（或 `$OPENCLAW_STATE_DIR/`）下的任何内容都可能包含 secret 或私有数据： -- `openclaw.json`：配置中可能包含 token（Gateway 网关、远程 Gateway 网关）、provider 设置和 allowlist。 +- `openclaw.json`：配置中可能包含 token（gateway、remote gateway）、provider 设置和 allowlist。 - `credentials/**`：渠道凭证（例如 WhatsApp 凭证）、配对 allowlist、旧版 OAuth 导入。 -- `agents//agent/auth-profiles.json`：API key、token 配置文件、OAuth token，以及可选的 `keyRef` / `tokenRef`。 +- `agents//agent/auth-profiles.json`：API key、token Profile、OAuth token，以及可选的 `keyRef`/`tokenRef`。 - `secrets.json`（可选）：供 `file` SecretRef provider（`secrets.providers`）使用的基于文件的 secret 负载。 -- `agents//agent/auth.json`：旧版兼容性文件。发现静态 `api_key` 条目时会进行清理。 -- `agents//sessions/**`：会话转录（`*.jsonl`）+ 路由元数据（`sessions.json`），其中可能包含私信和工具输出。 -- 内置插件包：已安装插件（以及它们的 `node_modules/`）。 -- `sandboxes/**`：工具沙箱工作区；可能会累积你在沙箱中读写文件的副本。 +- `agents//agent/auth.json`：旧版兼容文件。发现静态 `api_key` 条目时会将其清理。 +- `agents//sessions/**`：会话记录（`*.jsonl`）+ 路由元数据（`sessions.json`），其中可能包含私信、工具输出和链接。 +- 内置 plugin 包：已安装插件（以及它们的 `node_modules/`）。 +- `sandboxes/**`：工具沙箱工作区；可能累积你在沙箱中读写文件的副本。 加固建议： -- 保持严格权限（目录 `700`，文件 `600`）。 -- 在 Gateway 网关主机上使用全盘加密。 -- 如果主机是共享的，优先为 Gateway 网关使用专用操作系统用户账号。 +- 保持权限严格（目录 `700`，文件 `600`）。 +- 在 gateway 主机上使用全盘加密。 +- 如果主机是共享的，优先为 Gateway 网关使用专用 OS 用户账号。 ### 工作区 `.env` 文件 -OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不会让这些文件悄悄覆盖 Gateway 网关运行时控制。 +OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不会让这些文件悄悄覆盖 gateway 运行时控制。 -- 任何以 `OPENCLAW_*` 开头的键都会被不受信任的工作区 `.env` 文件阻止。 -- Matrix、Mattermost、IRC 和 Synology Chat 的渠道端点设置也会被阻止通过工作区 `.env` 覆盖，因此克隆的工作区无法通过本地端点配置重定向内置连接器流量。端点环境变量键（例如 `MATRIX_HOMESERVER`、`MATTERMOST_URL`、`IRC_HOST`、`SYNOLOGY_CHAT_INCOMING_URL`）必须来自 Gateway 网关进程环境或 `env.shellEnv`，而不能来自工作区加载的 `.env`。 -- 这种阻止方式是失败即关闭的：未来版本新增的运行时控制变量，无法从已提交或攻击者提供的 `.env` 中被继承；该键会被忽略，Gateway 网关会保留自己的值。 -- 受信任的进程/操作系统环境变量（Gateway 网关自身的 shell、launchd / systemd 单元、应用包）仍然生效——这里约束的只是 `.env` 文件加载。 +- 任何以 `OPENCLAW_*` 开头的键，都会被来自不受信任工作区 `.env` 文件的值拦截。 +- Matrix、Mattermost、IRC 和 Synology Chat 的渠道端点设置也会被拦截，不允许通过工作区 `.env` 覆盖，因此克隆出来的工作区无法通过本地端点配置来重定向内置连接器流量。端点环境变量键（例如 `MATRIX_HOMESERVER`、`MATTERMOST_URL`、`IRC_HOST`、`SYNOLOGY_CHAT_INCOMING_URL`）必须来自 gateway 进程环境或 `env.shellEnv`，而不能来自工作区加载的 `.env`。 +- 这种拦截机制是失败关闭的：未来版本中新增加的运行时控制变量，也无法从已检入版本库或攻击者提供的 `.env` 中继承；该键会被忽略，而 gateway 会保持自己的值。 +- 受信任的进程/OS 环境变量（gateway 自己的 shell、launchd/systemd 单元、应用 bundle）仍然有效——这项限制只约束 `.env` 文件加载。 -原因：工作区 `.env` 文件经常与智能体代码放在一起、被意外提交，或由工具写入。阻止整个 `OPENCLAW_*` 前缀意味着以后新增任何 `OPENCLAW_*` 标志时，都不可能退化为从工作区状态静默继承。 +原因：工作区 `.env` 文件通常与智能体代码放在一起，经常会被意外提交，或者被工具写入。拦截整个 `OPENCLAW_*` 前缀意味着，今后即使新增了某个 `OPENCLAW_*` 标志，也永远不会退化为从工作区状态中静默继承。 -### 日志和转录（脱敏与保留） +### 日志和会话记录（脱敏与保留） -即使访问控制正确，日志和转录仍然可能泄露敏感信息： +即使访问控制正确，日志和会话记录仍可能泄露敏感信息： - Gateway 网关日志可能包含工具摘要、错误和 URL。 -- 会话转录可能包含粘贴的 secrets、文件内容、命令输出和链接。 +- 会话记录可能包含粘贴的 secret、文件内容、命令输出和链接。 建议： - 保持工具摘要脱敏开启（`logging.redactSensitive: "tools"`；默认值）。 - 通过 `logging.redactPatterns` 为你的环境添加自定义模式（token、主机名、内部 URL）。 -- 分享诊断信息时，优先使用 `openclaw status --all`（可直接粘贴，secrets 已脱敏），而不是原始日志。 -- 如果不需要长期保留，请清理旧的会话转录和日志文件。 +- 共享诊断信息时，优先使用 `openclaw status --all`（可直接粘贴，secret 已脱敏），而不是原始日志。 +- 如果你不需要长期保留，请清理旧的会话记录和日志文件。 详情见：[Logging](/zh-CN/gateway/logging) @@ -957,7 +970,7 @@ OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不 } ``` -### 群组：始终要求提及 +### 群组：在所有地方都要求提及 ```json { @@ -979,31 +992,31 @@ OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不 } ``` -在群聊中，仅在被明确提及时响应。 +在群聊中，只有在被明确提及时才响应。 ### 分离号码（WhatsApp、Signal、Telegram） -对于基于电话号码的渠道，可以考虑让你的 AI 使用一个与你个人号码分开的号码运行： +对于基于电话号码的渠道，可以考虑让你的 AI 使用与个人号码不同的独立号码： - 个人号码：你的对话保持私密 -- 机器人号码：由 AI 处理，并设置适当边界 +- 机器人号码：AI 处理这些对话，并应用适当边界 ### 只读模式（通过沙箱和工具） -你可以通过以下组合构建只读配置： +你可以通过以下组合构建只读 profile： -- `agents.defaults.sandbox.workspaceAccess: "ro"`（或 `"none"` 表示无工作区访问） -- 阻止 `write`、`edit`、`apply_patch`、`exec`、`process` 等的工具 allow / deny 列表 +- `agents.defaults.sandbox.workspaceAccess: "ro"`（或 `"none"`，表示完全不访问工作区） +- 使用工具 allow/deny 列表来阻止 `write`、`edit`、`apply_patch`、`exec`、`process` 等。 其他加固选项： -- `tools.exec.applyPatch.workspaceOnly: true`（默认）：确保 `apply_patch` 即使在未启用沙箱隔离时，也不能在工作区目录之外写入/删除。只有当你明确希望 `apply_patch` 操作工作区外文件时，才设置为 `false`。 -- `tools.fs.workspaceOnly: true`（可选）：将 `read` / `write` / `edit` / `apply_patch` 路径以及原生提示图片自动加载路径限制在工作区目录内（如果你当前允许绝对路径，并希望加一个统一护栏，这会很有用）。 -- 保持文件系统根路径范围狭窄：避免把主目录这类宽泛根路径用作智能体工作区/沙箱工作区。过宽的根路径会让文件系统工具暴露敏感本地文件（例如 `~/.openclaw` 下的状态/配置）。 +- `tools.exec.applyPatch.workspaceOnly: true`（默认）：确保即使关闭了沙箱隔离，`apply_patch` 也不能在工作区目录之外进行写入/删除。只有当你明确希望 `apply_patch` 能修改工作区外的文件时，才将其设为 `false`。 +- `tools.fs.workspaceOnly: true`（可选）：将 `read`/`write`/`edit`/`apply_patch` 路径以及原生 prompt 图像自动加载路径限制在工作区目录内（如果你当前允许绝对路径，并希望添加一条统一防护栏，这会很有用）。 +- 保持文件系统根目录范围狭窄：避免将你的主目录这类过宽的根目录用作智能体工作区/沙箱工作区。过宽的根目录可能会让文件系统工具接触到敏感本地文件（例如 `~/.openclaw` 下的状态/配置）。 ### 安全基线（可直接复制粘贴） -一个“默认安全”的配置，可让 Gateway 网关保持私有、要求 DM 配对，并避免在群组中始终在线： +一套“默认更安全”的配置，可保持 Gateway 网关私有、要求私信配对，并避免群组机器人始终在线： ```json5 { @@ -1022,69 +1035,69 @@ OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不 } ``` -如果你还希望工具执行也“默认更安全”，请为任何非 owner 智能体添加沙箱隔离 + 禁用危险工具（示例见下文“按智能体划分的访问配置”）。 +如果你还希望工具执行也“默认更安全”，可添加沙箱 + 为任何非 owner 智能体拒绝危险工具（示例见下方“按智能体划分的访问 profile”）。 -对于由聊天驱动的智能体轮次，内置基线是：非 owner 发送者不能使用 `cron` 或 `gateway` 工具。 +对于聊天驱动的智能体回合，内置基线行为是：非 owner 发送者不能使用 `cron` 或 `gateway` 工具。 ## 沙箱隔离（推荐） 专门文档：[沙箱隔离](/zh-CN/gateway/sandboxing) -有两种互补的方法： +两种互补方案： -- **在 Docker 中运行完整 Gateway 网关**（容器边界）：[Docker](/zh-CN/install/docker) -- **工具沙箱**（`agents.defaults.sandbox`，主机 Gateway 网关 + 沙箱隔离工具；默认后端为 Docker）：[沙箱隔离](/zh-CN/gateway/sandboxing) +- **在 Docker 中运行完整的 Gateway 网关**（容器边界）：[Docker](/zh-CN/install/docker) +- **工具沙箱**（`agents.defaults.sandbox`，gateway 主机 + 沙箱隔离的工具；Docker 是默认后端）：[沙箱隔离](/zh-CN/gateway/sandboxing) -注意：为防止跨智能体访问，请将 `agents.defaults.sandbox.scope` 保持为 `"agent"`（默认） -或使用更严格的 `"session"` 实现按会话隔离。`scope: "shared"` 会使用 +注意：为了防止跨智能体访问，请将 `agents.defaults.sandbox.scope` 保持为 `"agent"`（默认） +，或者使用 `"session"` 以获得更严格的按会话隔离。`scope: "shared"` 会使用 单一容器/工作区。 -还应考虑沙箱中的智能体工作区访问： +还应考虑智能体在沙箱内对工作区的访问： -- `agents.defaults.sandbox.workspaceAccess: "none"`（默认）会禁止访问智能体工作区；工具会在 `~/.openclaw/sandboxes` 下的沙箱工作区中运行 -- `agents.defaults.sandbox.workspaceAccess: "ro"` 会将智能体工作区以只读方式挂载到 `/agent`（禁用 `write` / `edit` / `apply_patch`） +- `agents.defaults.sandbox.workspaceAccess: "none"`（默认）会禁止访问智能体工作区；工具会针对位于 `~/.openclaw/sandboxes` 下的沙箱工作区运行 +- `agents.defaults.sandbox.workspaceAccess: "ro"` 会将智能体工作区以只读方式挂载到 `/agent`（禁用 `write`/`edit`/`apply_patch`） - `agents.defaults.sandbox.workspaceAccess: "rw"` 会将智能体工作区以读写方式挂载到 `/workspace` -- 额外的 `sandbox.docker.binds` 会根据规范化和 canonicalized 后的源路径进行校验。如果父级符号链接技巧或规范 home 别名最终解析到了被阻止的根路径（如 `/etc`、`/var/run` 或操作系统 home 下的凭证目录），仍会失败即关闭。 +- 额外的 `sandbox.docker.binds` 会针对规范化和 canonicalized 的源路径进行校验。如果这些路径经解析后落入 `/etc`、`/var/run` 或 OS 主目录下的凭证目录等受阻根路径中，则父级符号链接技巧和规范 home 别名仍会失败关闭。 -重要说明：`tools.elevated` 是全局基线逃逸口，可让 exec 在沙箱外运行。默认情况下，其实际主机是 `gateway`；当 exec 目标配置为 `node` 时，则为 `node`。请保持 `tools.elevated.allowFrom` 严格收紧，不要为陌生人启用它。你还可以通过 `agents.list[].tools.elevated` 对单个智能体进一步限制 elevated。参见 [Elevated Mode](/zh-CN/tools/elevated)。 +重要说明：`tools.elevated` 是全局基线逃逸口，可在沙箱外运行 exec。默认的有效主机是 `gateway`，或者当 exec 目标配置为 `node` 时则为 `node`。请保持 `tools.elevated.allowFrom` 范围严格，不要对陌生人启用。你还可以通过 `agents.list[].tools.elevated` 进一步按智能体限制 elevated。见 [Elevated Mode](/zh-CN/tools/elevated)。 -### 子智能体委派护栏 +### 子智能体委派防护栏 -如果你允许会话工具，请将委派给子智能体运行视为另一项边界决策： +如果你允许使用会话工具，应将委派给子智能体运行视为另一项边界决策： -- 除非智能体确实需要委派，否则禁用 `sessions_spawn`。 -- 保持 `agents.defaults.subagents.allowAgents` 以及任何按智能体覆盖的 `agents.list[].subagents.allowAgents` 仅限于已知安全的目标智能体。 -- 对于任何必须保持沙箱隔离的工作流，请在调用 `sessions_spawn` 时使用 `sandbox: "require"`（默认值是 `inherit`）。 +- 除非智能体确实需要委派，否则拒绝 `sessions_spawn`。 +- 将 `agents.defaults.subagents.allowAgents` 以及任何按智能体覆盖的 `agents.list[].subagents.allowAgents` 限制为已知安全的目标智能体。 +- 对于任何必须保持沙箱隔离的工作流，请在调用 `sessions_spawn` 时使用 `sandbox: "require"`（默认是 `inherit`）。 - 当目标子运行时未启用沙箱隔离时，`sandbox: "require"` 会快速失败。 ## 浏览器控制风险 -启用浏览器控制会让模型具备驱动真实浏览器的能力。 -如果该浏览器配置文件中已经包含登录会话，模型就可以 -访问这些账号和数据。应将浏览器配置文件视为**敏感状态**： +启用浏览器控制会赋予模型驱动真实浏览器的能力。 +如果该浏览器 Profile 中已经包含已登录会话，模型就可以 +访问这些账号和数据。应将浏览器 Profile 视为**敏感状态**： -- 优先为智能体使用专用配置文件（默认 `openclaw` 配置文件）。 -- 避免让智能体使用你的个人日常浏览器配置文件。 -- 除非你信任这些智能体，否则应对启用沙箱隔离的智能体保持主机浏览器控制关闭。 -- 独立的 loopback 浏览器控制 API 仅接受共享密钥 auth - （Gateway 网关 token bearer auth 或 Gateway 网关 password）。它不使用 +- 优先为智能体使用专用 Profile（默认 `openclaw` Profile）。 +- 避免将智能体指向你个人日常使用的主 Profile。 +- 对于启用了沙箱隔离的智能体，除非你信任它们，否则请保持主机浏览器控制关闭。 +- 独立的 loopback 浏览器控制 API 只接受共享 secret auth + （gateway token bearer auth 或 gateway password）。它不使用 trusted-proxy 或 Tailscale Serve 身份头。 -- 应将浏览器下载内容视为不受信任输入；优先使用隔离的下载目录。 -- 如果可能，请在智能体配置文件中禁用浏览器同步/密码管理器（降低爆炸半径）。 -- 对于远程 Gateway 网关，应假设“浏览器控制”等同于对该配置文件可访问内容的“操作员访问”。 -- 让 Gateway 网关和 node host 保持仅 tailnet 可访问；避免将浏览器控制端口暴露到 LAN 或公共互联网。 -- 在不需要时关闭浏览器代理路由（`gateway.nodes.browser.mode="off"`）。 -- Chrome MCP 现有会话模式**并不**“更安全”；它可以像你一样操作该主机上 Chrome 配置文件可访问的任何内容。 +- 将浏览器下载内容视为不受信任输入；优先使用隔离的下载目录。 +- 如有可能，请在智能体 Profile 中禁用浏览器同步/密码管理器（可减小爆炸半径）。 +- 对于远程 Gateway 网关，应将“浏览器控制”视为对该 Profile 可访问内容的“操作员访问”等价物。 +- 保持 Gateway 网关和 node host 仅限 tailnet；避免将浏览器控制端口暴露给 LAN 或公共互联网。 +- 在不需要时禁用浏览器代理路由（`gateway.nodes.browser.mode="off"`）。 +- Chrome MCP 现有会话模式**并不**“更安全”；它会以你的身份操作该主机上 Chrome Profile 可访问的一切内容。 ### 浏览器 SSRF 策略（默认严格） OpenClaw 的浏览器导航策略默认是严格的：私有/内部目标会保持阻止状态，除非你显式选择启用。 -- 默认值：`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置，因此浏览器导航会继续阻止私有/内部/特殊用途目标。 -- 旧版别名：为兼容起见，仍接受 `browser.ssrfPolicy.allowPrivateNetwork`。 -- 显式启用模式：将 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` 设为允许私有/内部/特殊用途目标。 -- 在严格模式下，可使用 `hostnameAllowlist`（如 `*.example.com` 之类的模式）和 `allowedHostnames`（精确主机例外，包括 `localhost` 这类被阻止名称）进行显式例外配置。 -- 导航会在请求前检查，并在导航结束后的最终 `http(s)` URL 上尽力重新检查，以减少基于重定向的跳转利用。 +- 默认：`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置，因此浏览器导航会继续阻止私有/内部/特殊用途目标。 +- 旧版别名：出于兼容性，仍接受 `browser.ssrfPolicy.allowPrivateNetwork`。 +- 选择启用模式：将 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` 设为允许私有/内部/特殊用途目标。 +- 在严格模式下，可使用 `hostnameAllowlist`（如 `*.example.com` 这样的模式）和 `allowedHostnames`（精确主机例外，包括 `localhost` 这类原本被阻止的名称）来添加显式例外。 +- 系统会在请求前检查导航，并在导航完成后的最终 `http(s)` URL 上尽力再次检查，以减少基于重定向的跳转攻击。 严格策略示例： @@ -1100,19 +1113,19 @@ OpenClaw 的浏览器导航策略默认是严格的：私有/内部目标会保 } ``` -## 按智能体划分的访问配置（多智能体） +## 按智能体划分的访问 profile（多智能体） -在多智能体路由中，每个智能体都可以拥有自己的沙箱隔离 + 工具策略： -请利用这一点为不同智能体分别配置**完全访问**、**只读**或**无访问权限**。 +在多智能体路由下，每个智能体都可以拥有自己的沙箱 + 工具策略： +使用这一点可为不同智能体赋予**完全访问**、**只读**或**无访问**权限。 完整细节和优先级规则见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 常见用例： -- 个人智能体：完全访问，无沙箱隔离 +- 个人智能体：完全访问，不使用沙箱 - 家庭/工作智能体：沙箱隔离 + 只读工具 -- 公开智能体：沙箱隔离 + 无文件系统/shell 工具 +- 公共智能体：沙箱隔离 + 无文件系统/shell 工具 -### 示例：完全访问（无沙箱隔离） +### 示例：完全访问（无沙箱） ```json5 { @@ -1152,7 +1165,7 @@ OpenClaw 的浏览器导航策略默认是严格的：私有/内部目标会保 } ``` -### 示例：无文件系统/shell 访问（允许 provider 消息） +### 示例：无文件系统/shell 访问（允许 provider 消息功能） ```json5 { @@ -1166,8 +1179,8 @@ OpenClaw 的浏览器导航策略默认是严格的：私有/内部目标会保 scope: "agent", workspaceAccess: "none", }, - // 会话工具可能会从转录中泄露敏感数据。默认情况下 OpenClaw 会将这些工具限制为 - // 当前会话 + 已启动的子智能体会话，但如果需要，你还可以进一步收紧。 + // 会话工具可能会从记录中暴露敏感数据。默认情况下，OpenClaw 将这些工具限制为 + // 当前会话 + 已生成的子智能体会话，但如果需要，你可以进一步收紧。 // 参见配置参考中的 `tools.sessions.visibility`。 tools: { sessions: { visibility: "tree" }, // self | tree | agent | all @@ -1205,39 +1218,39 @@ OpenClaw 的浏览器导航策略默认是严格的：私有/内部目标会保 ## 事件响应 -如果你的 AI 做了不该做的事： +如果你的 AI 做了不当操作： -### 遏制 +### 控制局势 -1. **停止它：** 停止 macOS 应用（如果它负责监管 Gateway 网关），或者终止你的 `openclaw gateway` 进程。 -2. **关闭暴露面：** 将 `gateway.bind` 设为 `"loopback"`（或禁用 Tailscale Funnel / Serve），直到你弄清楚发生了什么。 -3. **冻结访问：** 将高风险私信/群组切换为 `dmPolicy: "disabled"` / 要求提及，并移除你曾设置的 `"*"` 全开放条目。 +1. **停止它：**停止 macOS 应用（如果它负责监管 Gateway 网关）或终止你的 `openclaw gateway` 进程。 +2. **关闭暴露面：**将 `gateway.bind: "loopback"` 设回（或禁用 Tailscale Funnel/Serve），直到你弄清楚发生了什么。 +3. **冻结访问：**将高风险私信/群组切换为 `dmPolicy: "disabled"` / 要求提及，并移除你之前可能设置的 `"*"` 允许所有条目。 -### 轮换（如果 secrets 泄露，则视为已被攻破） +### 轮换（如果 secret 泄露，按已被攻破处理） -1. 轮换 Gateway 网关 auth（`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`）并重启。 -2. 轮换任意可调用 Gateway 网关的机器上的远程客户端 secrets（`gateway.remote.token` / `.password`）。 -3. 轮换 provider / API 凭证（WhatsApp 凭证、Slack / Discord token、`auth-profiles.json` 中的模型 / API key，以及使用时的加密 secrets 负载值）。 +1. 轮换 Gateway auth（`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`）并重启。 +2. 轮换任何可调用 Gateway 网关机器上的远程客户端 secret（`gateway.remote.token` / `.password`）。 +3. 轮换 provider/API 凭证（WhatsApp 凭证、Slack/Discord token、`auth-profiles.json` 中的 model/API key，以及使用时的加密 secret 负载值）。 ### 审计 1. 检查 Gateway 网关日志：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`（或 `logging.file`）。 -2. 查看相关转录：`~/.openclaw/agents//sessions/*.jsonl`。 -3. 查看最近的配置更改（任何可能扩大访问范围的内容：`gateway.bind`、`gateway.auth`、私信/群组策略、`tools.elevated`、插件更改）。 -4. 重新运行 `openclaw security audit --deep` 并确认关键发现已解决。 +2. 审查相关记录：`~/.openclaw/agents//sessions/*.jsonl`。 +3. 审查最近的配置更改（任何可能扩大访问范围的内容：`gateway.bind`、`gateway.auth`、私信/群组策略、`tools.elevated`、插件变更）。 +4. 重新运行 `openclaw security audit --deep`，并确认关键发现已解决。 -### 收集报告所需信息 +### 为报告收集信息 -- 时间戳、Gateway 网关主机操作系统 + OpenClaw 版本 -- 会话转录 + 简短日志尾部（脱敏后） +- 时间戳、gateway 主机 OS + OpenClaw 版本 +- 会话记录 + 一小段日志尾部（脱敏后） - 攻击者发送了什么 + 智能体做了什么 -- Gateway 网关是否暴露到了 loopback 之外（LAN / Tailscale Funnel / Serve） +- Gateway 网关是否暴露在 loopback 之外（LAN/Tailscale Funnel/Serve） ## 使用 detect-secrets 进行 secret 扫描 CI 会在 `secrets` job 中运行 `detect-secrets` pre-commit hook。 -推送到 `main` 时始终执行全文件扫描。Pull request 会在存在基准提交时使用变更文件 -快速路径，否则回退为全文件扫描。如果失败，说明存在尚未加入 baseline 的新候选项。 +推送到 `main` 时总是执行全文件扫描。Pull request 会在有基准提交可用时使用基于变更文件的快速路径， +否则回退为全文件扫描。如果失败，表示出现了尚未写入基线的新候选项。 ### 如果 CI 失败 @@ -1249,25 +1262,25 @@ CI 会在 `secrets` job 中运行 `detect-secrets` pre-commit hook。 2. 了解这些工具： - pre-commit 中的 `detect-secrets` 会使用仓库的 - baseline 和排除规则来运行 `detect-secrets-hook`。 - - `detect-secrets audit` 会打开交互式审查，用于将 baseline - 中的每一项标记为真实或误报。 -3. 对于真实 secrets：轮换/删除它们，然后重新运行扫描以更新 baseline。 -4. 对于误报：运行交互式审查，并将它们标记为误报： + baseline 和 excludes 运行 `detect-secrets-hook`。 + - `detect-secrets audit` 会打开交互式审查界面，以将 baseline + 中的每一项标记为真实 secret 或误报。 +3. 对于真实 secret：轮换/移除它们，然后重新运行扫描以更新 baseline。 +4. 对于误报：运行交互式 audit，并将其标记为 false： ```bash detect-secrets audit .secrets.baseline ``` -5. 如果需要新增排除项，请将其加入 `.detect-secrets.cfg`，并使用匹配的 `--exclude-files` / `--exclude-lines` 参数重新生成 +5. 如果你需要新增 excludes，请将其添加到 `.detect-secrets.cfg`，并使用匹配的 `--exclude-files` / `--exclude-lines` 标志重新生成 baseline（该配置文件仅作参考；detect-secrets 不会自动读取它）。 -当更新后的 `.secrets.baseline` 反映出预期状态后，请将其提交。 +当更新后的 `.secrets.baseline` 反映了预期状态后，再提交它。 ## 报告安全问题 -如果你在 OpenClaw 中发现漏洞，请负责任地报告： +在 OpenClaw 中发现了漏洞？请负责任地进行报告： -1. 邮箱：[security@openclaw.ai](mailto:security@openclaw.ai) +1. 发送邮件至：[security@openclaw.ai](mailto:security@openclaw.ai) 2. 在修复前不要公开发布 -3. 我们会为你署名致谢（如果你更希望匿名，也可以） +3. 我们会致谢你（除非你希望匿名） diff --git a/docs/zh-CN/help/testing.md b/docs/zh-CN/help/testing.md index 53afa84ec..2021c2ab6 100644 --- a/docs/zh-CN/help/testing.md +++ b/docs/zh-CN/help/testing.md @@ -1,116 +1,117 @@ --- read_when: - - 在本地或 CI 中运行测试 - - 为模型/提供商缺陷添加回归测试 + - 在本地或在 CI 中运行测试 + - 为模型 / 提供商缺陷添加回归测试 - 调试 Gateway 网关 + 智能体行为 -summary: 测试工具包：unit/e2e/live 测试套件、Docker 运行器，以及每项测试覆盖的内容 +summary: 测试工具包：单元 / e2e / 实时测试套件、Docker 运行器，以及每项测试覆盖的内容 title: 测试 x-i18n: - generated_at: "2026-04-24T16:11:55Z" + generated_at: "2026-04-24T16:58:30Z" model: gpt-5.4 provider: openai - source_hash: 0d4f837faddc458509702b2a315d71d35740c01810ca76e40d652df54b09f38e + source_hash: ca845ba5856546841706ac9477aae07041f37620ae5eaafc35fd18ead97dcfae source_path: help/testing.md workflow: 15 --- -OpenClaw 有三个 Vitest 测试套件（unit/integration、e2e、live）以及少量 Docker 运行器。本文档是一份“我们如何测试”的指南： +OpenClaw 有三个 Vitest 测试套件（单元 / 集成、e2e、实时），以及一小组 Docker 运行器。本文档是一份“我们如何测试”的指南： -- 每个测试套件覆盖什么（以及它刻意 _不_ 覆盖什么）。 -- 常见工作流（本地、推送前、调试）应运行哪些命令。 -- live 测试如何发现凭证并选择模型/提供商。 -- 如何为真实世界中的模型/提供商问题添加回归测试。 +- 每个测试套件覆盖什么（以及它明确**不**覆盖什么）。 +- 常见工作流应运行哪些命令（本地、推送前、调试）。 +- 实时测试如何发现凭证并选择模型 / 提供商。 +- 如何为真实世界中的模型 / 提供商问题添加回归测试。 ## 快速开始 大多数时候： -- 完整门禁（预期在 push 前执行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- 完整门禁（预期在 push 前运行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test` - 在资源充足的机器上更快地运行本地完整测试套件：`pnpm test:max` - 直接使用 Vitest 观察模式循环：`pnpm test:watch` -- 直接指定文件现在也支持 extension/channel 路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- 当你在迭代单个失败用例时，优先使用定向运行。 -- Docker 支持的 QA 站点：`pnpm qa:lab:up` -- Linux VM 支持的 QA 通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- 直接按文件定位现在也会路由到扩展 / 渠道路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- 当你在迭代单个失败用例时，优先先运行定向测试。 +- 基于 Docker 的 QA 站点：`pnpm qa:lab:up` +- 基于 Linux VM 的 QA 通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -当你修改了测试或想获得更多信心时： +当你修改测试或想要更多信心时： - 覆盖率门禁：`pnpm test:coverage` - E2E 测试套件：`pnpm test:e2e` -在调试真实提供商/模型时（需要真实凭证）： +当调试真实提供商 / 模型时（需要真实凭证）： -- live 测试套件（模型 + Gateway 网关工具/图像探测）：`pnpm test:live` -- 安静地仅运行一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker live 模型扫描：`pnpm test:docker:live-models` - - 现在每个选中的模型都会运行一次文本轮次以及一个类似小型文件读取的探测。元数据声明支持 `image` 输入的模型还会运行一个极小的图像轮次。在隔离提供商故障时，可通过 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 禁用额外探测。 - - CI 覆盖：每日运行的 `OpenClaw Scheduled Live And E2E Checks` 和手动触发的 `OpenClaw Release Checks` 都会调用可复用的 live/E2E 工作流，并设置 `include_live_suites: true`，其中包含按提供商分片的独立 Docker live 模型矩阵作业。 - - 若要进行聚焦的 CI 重跑，可触发 `OpenClaw Live And E2E Checks (Reusable)`，并设置 `include_live_suites: true` 和 `live_models_only: true`。 - - 将新的高信号提供商密钥添加到 `scripts/ci-hydrate-live-auth.sh`、`.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 及其 scheduled/release 调用方中。 +- 实时测试套件（模型 + Gateway 网关工具 / 图像探测）：`pnpm test:live` +- 安静地只运行一个实时测试文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker 实时模型扫描：`pnpm test:docker:live-models` + - 现在每个选定模型都会运行一次文本轮次外加一个小型文件读取风格探测。元数据声明支持 `image` 输入的模型还会运行一次微型图像轮次。隔离提供商故障时，可通过 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 禁用额外探测。 + - CI 覆盖：每日的 `OpenClaw Scheduled Live And E2E Checks` 和手动触发的 `OpenClaw Release Checks` 都会调用可复用的实时 / E2E 工作流，并设置 `include_live_suites: true`，其中包含按提供商分片的独立 Docker 实时模型矩阵作业。 + - 若要进行聚焦的 CI 重跑，可派发 `OpenClaw Live And E2E Checks (Reusable)`，并设置 `include_live_suites: true` 与 `live_models_only: true`。 + - 将新的高信号提供商密钥添加到 `scripts/ci-hydrate-live-auth.sh`，以及 `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 和其 scheduled/release 调用方中。 - 原生 Codex 绑定聊天冒烟测试：`pnpm test:docker:live-codex-bind` - - 在 Docker live 通道中针对 Codex app-server 路径运行，绑定一个带有 `/codex bind` 的合成 Slack 私信，会执行 `/codex fast` 和 `/codex permissions`，然后验证普通回复和图像附件都通过原生 plugin 绑定路由，而不是 ACP。 -- Moonshot/Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行 `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 运行隔离的 `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json`。验证 JSON 报告的是 Moonshot/K2.6，且 assistant transcript 中存储了规范化的 `usage.cost`。 + - 针对 Codex app-server 路径运行一个 Docker 实时通道，绑定一个合成的 Slack 私信并执行 `/codex bind`，测试 `/codex fast` 和 `/codex permissions`，然后验证普通回复与图像附件是通过原生插件绑定而非 ACP 路由的。 +- Moonshot / Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行 `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 运行独立命令 `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` + 。验证 JSON 报告的是 Moonshot / K2.6，并且助手转录中存储了规范化后的 `usage.cost`。 -提示：当你只需要一个失败用例时，优先通过下文描述的 allowlist 环境变量来收窄 live 测试范围。 +提示：当你只需要一个失败用例时，优先使用下面描述的 allowlist 环境变量来缩小实时测试范围。 ## QA 专用运行器 -当你需要 QA-lab 级别的真实环境时，这些命令与主测试套件并列使用： +当你需要 QA-lab 级别的真实环境时，这些命令与主测试套件并列存在： -CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上运行，也可通过手动触发配合 mock 提供商执行。`QA-Lab - All Lanes` 会在 `main` 上每夜运行，也可通过手动触发，并将 mock parity gate、live Matrix 通道以及由 Convex 管理的 live Telegram 通道作为并行作业运行。`OpenClaw Release Checks` 会在发布批准前运行相同的通道。 +CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上运行，也可通过手动派发结合模拟提供商运行。`QA-Lab - All Lanes` 会在 `main` 上每晚运行，也可手动派发，包含模拟 parity gate、实时 Matrix 通道，以及由 Convex 管理的实时 Telegram 通道，作为并行作业运行。`OpenClaw Release Checks` 会在发布审批前运行相同的通道。 - `pnpm openclaw qa suite` - - 直接在主机上运行基于仓库的 QA 场景。 - - 默认会以隔离的 Gateway 网关工作进程并行运行多个选定场景。`qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency ` 调整工作进程数量，或使用 `--concurrency 1` 回退到旧的串行通道。 - - 任一场景失败时以非零状态退出。如果你想保留产物但不希望以失败退出码结束，请使用 `--allow-failures`。 - - 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。`aimock` 会启动一个本地 AIMock 支持的 provider 服务器，用于实验性 fixture 和协议 mock 覆盖，而不会替代具备场景感知的 `mock-openai` 通道。 + - 直接在宿主机上运行基于仓库的 QA 场景。 + - 默认会以隔离的 Gateway 网关工作进程并行运行多个选定场景。`qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency ` 调整工作进程数，或使用 `--concurrency 1` 运行旧的串行通道。 + - 任一场景失败时以非零状态退出。若你希望保留产物但不以失败退出码结束，可使用 `--allow-failures`。 + - 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。`aimock` 会启动一个本地基于 AIMock 的提供商服务器，用于实验性的夹具与协议模拟覆盖，而不会替代具备场景感知能力的 `mock-openai` 通道。 - `pnpm openclaw qa suite --runner multipass` - 在一次性 Multipass Linux VM 中运行相同的 QA 测试套件。 - - 与主机上的 `qa suite` 保持相同的场景选择行为。 - - 复用与 `qa suite` 相同的提供商/模型选择标志。 - - live 运行会转发那些对 guest 来说可行的受支持 QA 凭证输入：基于环境变量的提供商密钥、QA live 提供商配置路径，以及存在时的 `CODEX_HOME`。 - - 输出目录必须保持在仓库根目录下，这样 guest 才能通过挂载的工作区回写文件。 - - 会将常规 QA 报告 + 摘要以及 Multipass 日志写入 `.artifacts/qa-e2e/...`。 + - 保持与宿主机上 `qa suite` 相同的场景选择行为。 + - 复用与 `qa suite` 相同的提供商 / 模型选择标志。 + - 实时运行会转发对来宾机可行的受支持 QA 认证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。 + - 输出目录必须位于仓库根目录下，以便来宾机能通过挂载的工作区回写内容。 + - 将常规 QA 报告、摘要以及 Multipass 日志写入 `.artifacts/qa-e2e/...`。 - `pnpm qa:lab:up` - - 启动 Docker 支持的 QA 站点，用于偏操作员风格的 QA 工作。 + - 启动基于 Docker 的 QA 站点，用于操作员风格的 QA 工作。 - `pnpm test:docker:npm-onboard-channel-agent` - - 基于当前 checkout 构建一个 npm tarball，在 Docker 中全局安装，以非交互方式执行 OpenAI API key 新手引导，默认配置 Telegram，验证启用 plugin 时会按需安装运行时依赖，运行 doctor，并针对一个 mock OpenAI 端点执行一次本地智能体轮次。 - - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行同样的打包安装通道。 + - 从当前检出构建一个 npm tarball，在 Docker 中全局安装，运行非交互式 OpenAI API 密钥新手引导，默认配置 Telegram，验证启用插件时会按需安装运行时依赖，运行 doctor，并针对模拟的 OpenAI 端点执行一次本地智能体轮次。 + - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行相同的打包安装通道。 - `pnpm test:docker:npm-telegram-live` - - 在 Docker 中安装一个已发布的 OpenClaw 包，运行已安装包的新手引导，通过已安装的 CLI 配置 Telegram，然后将该已安装包作为 SUT Gateway 网关复用 live Telegram QA 通道。 - - 默认使用 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`。 - - 使用与 `pnpm openclaw qa telegram` 相同的 Telegram 环境变量凭证或 Convex 凭证来源。对于 CI/发布自动化，设置 `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`，再加上 `OPENCLAW_QA_CONVEX_SITE_URL` 和角色密钥。如果在 CI 中存在 `OPENCLAW_QA_CONVEX_SITE_URL` 以及 Convex 角色密钥，Docker 包装器会自动选择 Convex。 - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 仅覆盖该通道共享的 `OPENCLAW_QA_CREDENTIAL_ROLE`。 - - GitHub Actions 将该通道暴露为手动维护者工作流 `NPM Telegram Beta E2E`。它不会在 merge 时运行。该工作流使用 `qa-live-shared` 环境和 Convex CI 凭证租约。 + - 在 Docker 中安装已发布的 OpenClaw 包，运行已安装包的新手引导，通过已安装的 CLI 配置 Telegram，然后复用实时 Telegram QA 通道，并将该已安装包作为被测 Gateway 网关（SUT）。 + - 默认为 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`。 + - 使用与 `pnpm openclaw qa telegram` 相同的 Telegram 环境变量凭证或 Convex 凭证来源。对于 CI / 发布自动化，设置 `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`，并同时设置 `OPENCLAW_QA_CONVEX_SITE_URL` 和角色密钥。如果在 CI 中存在 `OPENCLAW_QA_CONVEX_SITE_URL` 和 Convex 角色密钥，Docker 包装器会自动选择 Convex。 + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 仅为该通道覆盖共享的 `OPENCLAW_QA_CREDENTIAL_ROLE`。 + - GitHub Actions 将该通道暴露为手动维护者工作流 `NPM Telegram Beta E2E`。它不会在合并时运行。该工作流使用 `qa-live-shared` environment 和 Convex CI 凭证租约。 - `pnpm test:docker:bundled-channel-deps` - - 在 Docker 中打包并安装当前 OpenClaw 构建产物，启动已配置 OpenAI 的 Gateway 网关，然后通过编辑配置启用内置的 channel/plugins。 - - 验证设置发现阶段不会预先安装未配置 plugin 的运行时依赖，首次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置 plugin 的运行时依赖，第二次重启不会重新安装已激活的依赖。 - - 还会安装一个已知较旧的 npm 基线，在运行 `openclaw update --tag ` 之前启用 Telegram，并验证候选版本在更新后的 doctor 中能够修复内置渠道运行时依赖，而无需 harness 侧的 postinstall 修复。 + - 在 Docker 中打包并安装当前 OpenClaw 构建，使用已配置的 OpenAI 启动 Gateway 网关，然后通过配置编辑启用内置渠道 / 插件。 + - 验证设置发现阶段不会预先安装未配置插件的运行时依赖；首次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置插件的运行时依赖；第二次重启不会重复安装已激活的依赖。 + - 还会安装一个已知较旧的 npm 基线，在运行 `openclaw update --tag ` 之前启用 Telegram，并验证候选版本的更新后 doctor 会修复内置渠道运行时依赖，而无需测试框架侧的 postinstall 修复。 - `pnpm openclaw qa aimock` - - 仅启动本地 AIMock provider 服务器，用于直接协议冒烟测试。 + - 仅启动本地 AIMock 提供商服务器，用于直接协议冒烟测试。 - `pnpm openclaw qa matrix` - - 针对一次性 Docker 支持的 Tuwunel homeserver 运行 Matrix live QA 通道。 - - 该 QA 主机目前仅供 repo/dev 使用。打包后的 OpenClaw 安装不包含 `qa-lab`，因此不会暴露 `openclaw qa`。 - - 仓库 checkout 会直接加载内置运行器；不需要单独安装 plugin。 - - 会创建三个临时 Matrix 用户（`driver`、`sut`、`observer`）以及一个私有房间，然后启动一个以真实 Matrix plugin 作为 SUT 传输层的 QA gateway 子进程。 - - 默认使用固定的稳定 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。如需测试其他镜像，可通过 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。 - - Matrix 不暴露共享的 credential-source 标志，因为该通道会在本地创建一次性用户。 - - 会将 Matrix QA 报告、摘要、observed-events 产物以及合并的 stdout/stderr 输出日志写入 `.artifacts/qa-e2e/...`。 + - 针对一次性的、基于 Docker 的 Tuwunel homeserver 运行 Matrix 实时 QA 通道。 + - 该 QA 宿主当前仅用于仓库 / 开发场景。打包后的 OpenClaw 安装不会附带 `qa-lab`，因此不会暴露 `openclaw qa`。 + - 仓库检出会直接加载内置运行器；不需要单独的插件安装步骤。 + - 配置三个临时 Matrix 用户（`driver`、`sut`、`observer`）以及一个私有房间，然后启动一个 QA Gateway 网关子进程，并将真实 Matrix 插件作为 SUT 传输层。 + - 默认使用固定的稳定版 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。需要测试其他镜像时，可通过 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。 + - Matrix 不暴露共享凭证来源标志，因为该通道会在本地配置一次性用户。 + - 将 Matrix QA 报告、摘要、observed-events 产物以及合并的 stdout/stderr 输出日志写入 `.artifacts/qa-e2e/...`。 - `pnpm openclaw qa telegram` - - 使用来自环境变量的 driver 和 SUT bot token，针对真实私有群组运行 Telegram live QA 通道。 - - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是 Telegram chat 的数字 id。 - - 支持 `--credential-source convex` 以使用共享池凭证。默认使用环境变量模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。 - - 任一场景失败时以非零状态退出。如果你想保留产物但不希望以失败退出码结束，请使用 `--allow-failures`。 - - 需要两个位于同一私有群组中的不同 bot，并且 SUT bot 需要暴露 Telegram 用户名。 - - 为了稳定地观察 bot 对 bot 通信，请在 `@BotFather` 中为两个 bot 都启用 Bot-to-Bot Communication Mode，并确保 driver bot 能观察到群组中的 bot 流量。 - - 会将 Telegram QA 报告、摘要和 observed-messages 产物写入 `.artifacts/qa-e2e/...`。回复场景会包含从 driver 发送请求到观察到 SUT 回复的 RTT。 + - 使用环境变量中的 driver 和 SUT bot token，针对真实私有群组运行 Telegram 实时 QA 通道。 + - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是 Telegram 聊天的数字 id。 + - 支持 `--credential-source convex` 以使用共享池化凭证。默认使用环境变量模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。 + - 任一场景失败时以非零状态退出。若你希望保留产物但不以失败退出码结束，可使用 `--allow-failures`。 + - 需要位于同一私有群组中的两个不同 bot，且 SUT bot 必须暴露 Telegram 用户名。 + - 为了稳定观察 bot 与 bot 之间的通信，在 `@BotFather` 中为两个 bot 启用 Bot-to-Bot Communication Mode，并确保 driver bot 可以观察群组中的 bot 流量。 + - 将 Telegram QA 报告、摘要和 observed-messages 产物写入 `.artifacts/qa-e2e/...`。回复类场景包含从 driver 发送请求到观察到 SUT 回复的 RTT。 -live 传输通道共享一套标准契约，以避免新传输方式发生漂移： +实时传输通道共享一个标准契约，以避免新传输层出现漂移： -`qa-channel` 仍然是宽泛的合成 QA 测试套件，不属于 live 传输覆盖矩阵的一部分。 +`qa-channel` 仍然是覆盖面更广的合成 QA 测试套件，不属于实时传输覆盖矩阵的一部分。 -| 通道 | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | 帮助命令 | -| ---- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | -------- | +| 通道 | Canary | 提及门控 | allowlist 阻止 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | Reaction 观察 | 帮助命令 | +| ---- | ------ | -------- | -------------- | -------- | -------- | -------- | -------- | ------------- | -------- | | Matrix | x | x | x | x | x | x | x | x | | | Telegram | x | | | | | | | | x | @@ -118,19 +119,19 @@ live 传输通道共享一套标准契约，以避免新传输方式发生漂移 当为 `openclaw qa telegram` 启用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）时，QA lab 会从 Convex 支持的凭证池中获取一个独占租约，在通道运行期间为该租约发送心跳，并在关闭时释放该租约。 -参考 Convex 项目脚手架： +参考的 Convex 项目脚手架： - `qa/convex-credential-broker/` -必需环境变量： +必需的环境变量： - `OPENCLAW_QA_CONVEX_SITE_URL`（例如 `https://your-deployment.convex.site`） -- 所选角色对应的一个密钥： - - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` 用于 `maintainer` - - `OPENCLAW_QA_CONVEX_SECRET_CI` 用于 `ci` +- 为所选角色配置一个密钥： + - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` 对应 `maintainer` + - `OPENCLAW_QA_CONVEX_SECRET_CI` 对应 `ci` - 凭证角色选择： - CLI：`--credential-role maintainer|ci` - - 默认环境变量：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认为 `ci`，否则默认为 `maintainer`） + - 环境变量默认值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认 `ci`，否则默认 `maintainer`） 可选环境变量： @@ -139,14 +140,14 @@ live 传输通道共享一套标准契约，以避免新传输方式发生漂移 - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（默认 `90000`） - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（默认 `15000`） - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（默认 `/qa-credentials/v1`） -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选跟踪 id） +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选追踪 id） - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允许在仅限本地开发时使用 loopback `http://` Convex URL。 正常运行时，`OPENCLAW_QA_CONVEX_SITE_URL` 应使用 `https://`。 -维护者管理命令（池添加/删除/列出）需要专门使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。 +维护者管理员命令（池添加 / 删除 / 列表）必须专门使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。 -供维护者使用的 CLI 帮助命令： +面向维护者的 CLI 辅助命令： ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -154,14 +155,14 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -在脚本和 CI 工具中使用 `--json` 以获得机器可读的输出。 +在脚本和 CI 工具中使用 `--json` 可获得机器可读输出。 默认端点契约（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）： - `POST /acquire` - 请求：`{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - 成功：`{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - 已耗尽/可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - 耗尽 / 可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - 成功：`{ status: "ok" }`（或空的 `2xx`） @@ -182,59 +183,59 @@ pnpm openclaw qa credentials remove --credential-id Telegram 类型的 payload 结构： - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` 必须是 Telegram chat id 的数字字符串。 -- `admin/add` 会为 `kind: "telegram"` 校验该结构，并拒绝格式错误的 payload。 +- `groupId` 必须是 Telegram 聊天 id 的数字字符串。 +- `admin/add` 会为 `kind: "telegram"` 验证此结构，并拒绝格式错误的 payload。 -### 向 QA 添加一个渠道 +### 向 QA 添加渠道 -向 markdown QA 系统添加一个渠道，严格来说只需要两样东西： +将一个渠道添加到 Markdown QA 系统中，严格只需要两样东西： 1. 该渠道的传输适配器。 2. 一个用于验证该渠道契约的场景包。 -当共享的 `qa-lab` 主机能够承载流程时，不要新增一个顶层 QA 命令根。 +如果共享的 `qa-lab` 宿主能够承载该流程，就不要添加新的顶层 QA 命令根。 -`qa-lab` 负责共享主机机制： +`qa-lab` 负责共享宿主机制： - `openclaw qa` 命令根 -- 测试套件启动和拆除 -- worker 并发控制 +- 测试套件启动与拆除 +- 工作进程并发 - 产物写入 - 报告生成 - 场景执行 -- 对旧版 `qa-channel` 场景的兼容别名 +- 对旧 `qa-channel` 场景的兼容别名 -运行器 plugins 负责传输契约： +运行器插件负责传输契约： -- 如何将 `openclaw qa ` 挂载到共享的 `qa` 根命令下 -- 如何为该传输方式配置 Gateway 网关 +- 如何将 `openclaw qa ` 挂载到共享 `qa` 根下 +- 如何为该传输配置 Gateway 网关 - 如何检查就绪状态 - 如何注入入站事件 - 如何观察出站消息 -- 如何暴露 transcript 和规范化的传输状态 -- 如何执行由传输方式支持的操作 -- 如何处理传输特定的重置或清理 +- 如何暴露转录与规范化后的传输状态 +- 如何执行基于传输的操作 +- 如何处理传输专属的重置或清理 新渠道的最低接入门槛是： -1. 保持由 `qa-lab` 作为共享 `qa` 根命令的拥有者。 -2. 在共享的 `qa-lab` 主机接口上实现传输运行器。 -3. 将传输特定机制保留在运行器 plugin 或渠道 harness 内部。 +1. 保持 `qa-lab` 作为共享 `qa` 根的所有者。 +2. 在共享的 `qa-lab` 宿主接缝上实现传输运行器。 +3. 将传输专属机制保留在运行器插件或渠道测试框架中。 4. 将运行器挂载为 `openclaw qa `，而不是注册一个竞争性的根命令。 - 运行器 plugins 应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。 - 保持 `runtime-api.ts` 足够轻量；惰性 CLI 和运行器执行应置于独立入口点之后。 -5. 在按主题组织的 `qa/scenarios/` 目录下编写或调整 markdown 场景。 -6. 为新场景使用通用场景辅助工具。 + 运行器插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。 + 保持 `runtime-api.ts` 足够轻量；惰性 CLI 和运行器执行应放在单独的入口点之后。 +5. 在带主题的 `qa/scenarios/` 目录下编写或适配 Markdown 场景。 +6. 对新场景使用通用场景辅助函数。 7. 除非仓库正在进行有意迁移，否则保持现有兼容别名继续可用。 -决策规则非常严格： +决策规则是严格的： -- 如果某个行为可以在 `qa-lab` 中统一表达一次，就把它放到 `qa-lab`。 -- 如果某个行为依赖某一种渠道传输方式，就把它保留在对应的运行器 plugin 或 plugin harness 中。 -- 如果某个场景需要一个可被多个渠道复用的新能力，就添加一个通用辅助工具，而不是在 `suite.ts` 中加入渠道特定分支。 -- 如果某个行为只对某一种传输方式有意义，就保持该场景为传输特定，并在场景契约中明确这一点。 +- 如果某个行为可以在 `qa-lab` 中统一表达一次，就把它放进 `qa-lab`。 +- 如果某个行为依赖单一渠道传输，就将它保留在该运行器插件或插件测试框架中。 +- 如果某个场景需要新增一种能力，且不止一个渠道可以使用它，那么应添加通用辅助函数，而不是在 `suite.ts` 中添加渠道专属分支。 +- 如果某个行为只对一种传输有意义，就保持该场景为传输专属，并在场景契约中明确说明。 -新场景推荐使用的通用辅助工具名称： +新场景优先使用的通用辅助函数名称是： - `waitForTransportReady` - `waitForChannelReady` @@ -257,365 +258,365 @@ Telegram 类型的 payload 结构： - `formatConversationTranscript` - `resetBus` -新的渠道开发应使用通用辅助工具名称。 -兼容别名的存在是为了避免一次性强制迁移，而不是作为新场景编写的范式。 +新的渠道开发应使用通用辅助函数名称。 +兼容别名的存在是为了避免一次性迁移日，而不是作为新场景编写的范式。 -## 测试套件（各自运行在哪里） +## 测试套件（各自在哪里运行） -可以把这些测试套件理解为“真实度逐级提高”（同时波动性/成本也逐级增加）： +可以把这些测试套件理解为“真实程度逐步增加”（同时不稳定性 / 成本也逐步增加）： -### Unit / integration（默认） +### 单元 / 集成（默认） - 命令：`pnpm test` -- 配置：未定向运行使用 `vitest.full-*.config.ts` 分片集合，并且可能会将多项目分片展开为按项目拆分的配置，以便并行调度 -- 文件：位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 下的 core/unit 清单，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` node 测试 +- 配置：未定向运行使用 `vitest.full-*.config.ts` 分片集合，并且可能会将多项目分片展开为按项目划分的配置，以便并行调度 +- 文件：核心 / 单元测试清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`，以及由 `vitest.unit.config.ts` 覆盖的白名单 `ui` Node 测试 - 范围： - - 纯 unit 测试 - - 进程内 integration 测试（Gateway 网关认证、路由、工具、解析、配置） - - 已知缺陷的确定性回归测试 + - 纯单元测试 + - 进程内集成测试（Gateway 网关认证、路由、工具、解析、配置） + - 针对已知缺陷的确定性回归测试 - 预期： - 在 CI 中运行 - 不需要真实密钥 - 应该快速且稳定 - - 未定向的 `pnpm test` 会运行 12 个更小的分片配置（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个巨大的原生根项目进程。这样可以降低高负载机器上的 RSS 峰值，并避免 auto-reply/extension 工作拖慢无关测试套件。 - `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片 watch 循环并不现实。 - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会优先通过定向通道来处理显式的文件/目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不必承担完整根项目启动的成本。 - 当变更的 git 路径仅触及可路由的源文件/测试文件时，`pnpm test:changed` 会将这些路径展开到相同的定向通道；而配置/设置改动仍会回退到更宽泛的根项目重跑。 - `pnpm check:changed` 是处理小范围变更时常规的智能本地门禁。它会将 diff 分类为 core、core tests、extensions、extension tests、apps、docs、release metadata 和 tooling，然后运行对应的 typecheck/lint/test 通道。公共 Plugin SDK 和 plugin-contract 的变更会额外包含一次 extension 验证，因为 extensions 依赖这些 core 契约。仅包含发布元数据版本号变更时，会运行定向的版本/config/root-dependency 检查，而不是完整测试套件，并带有一个保护机制，用于拒绝顶层 version 字段之外的 package 变更。 - 来自 agents、commands、plugins、auto-reply 辅助工具、`plugin-sdk` 以及类似纯工具区域的轻导入 unit 测试，会路由到 `unit-fast` 通道，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态/运行时较重的文件则保留在现有通道中。 - 某些 `plugin-sdk` 和 `commands` 辅助源码文件在 changed 模式下也会映射到这些轻量通道中的显式同级测试，因此辅助工具改动无需为该目录重跑完整的重型测试套件。 - `auto-reply` 有三个专用桶：顶层 core 辅助工具、顶层 `reply.*` integration 测试，以及 `src/auto-reply/reply/**` 子树。这样可以让最重的 reply harness 工作不影响廉价的状态/chunk/token 测试。 + - 未定向的 `pnpm test` 会运行十二个更小的分片配置（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个巨大的原生根项目进程。这样可在负载较高的机器上降低峰值 RSS，并避免 auto-reply / 扩展工作拖慢无关的测试套件。 - `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片的 watch 循环并不现实。 - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会优先通过作用域通道来路由显式文件 / 目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 可以避免支付完整根项目启动成本。 - 当变更的 git 路径只涉及可路由的源文件 / 测试文件时，`pnpm test:changed` 会将这些变更路径展开为相同的作用域通道；配置 / setup 编辑仍会回退到更广泛的根项目重跑。 - `pnpm check:changed` 是窄范围开发工作的常规智能本地门禁。它会将差异分类为 core、core tests、extensions、extension tests、apps、docs、release metadata 和 tooling，然后运行匹配的 typecheck / lint / test 通道。公共插件 SDK 和插件契约变更会额外包含一次扩展验证，因为扩展依赖这些核心契约。仅涉及发布元数据的版本号提升会运行定向的版本 / 配置 / 根依赖检查，而不是完整测试套件，并带有一个保护机制，用于拒绝顶层版本字段之外的 package 变更。 - 来自 agents、commands、plugins、auto-reply 辅助函数、`plugin-sdk` 以及类似纯工具区域的轻导入单元测试，会通过 `unit-fast` 通道路由，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时较重的文件仍保留在现有通道中。 - 选定的 `plugin-sdk` 和 `commands` 辅助源文件也会在 changed 模式运行时映射到这些轻量通道中的显式同级测试，因此对辅助函数的修改无需为该目录重跑完整的重型测试套件。 - `auto-reply` 有三个专用桶：顶层核心辅助函数、顶层 `reply.*` 集成测试，以及 `src/auto-reply/reply/**` 子树。这可使最重的 reply 测试框架工作远离轻量的状态 / 分块 / token 测试。 - - 当你修改消息工具发现输入或压缩运行时上下文时，请同时保持两个层级的覆盖。 - - 为纯路由和规范化边界添加聚焦的辅助工具回归测试。 - - 保持嵌入式运行器 integration 测试套件健康： + - 当你修改消息工具发现输入或压缩运行时上下文时，请同时保留两个层级的覆盖。 + - 为纯路由和规范化边界添加聚焦的辅助函数回归测试。 + - 保持嵌入式运行器集成测试套件健康： `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.loop.test.ts`。 - - 这些测试套件会验证带作用域的 id 和压缩行为是否仍然通过真实的 `run.ts` / `compact.ts` 路径流转；仅有辅助工具测试不足以替代这些 integration 路径。 + - 这些测试套件会验证带作用域的 id 和压缩行为仍然流经真实的 `run.ts` / `compact.ts` 路径；仅有辅助函数级别的测试并不足以替代这些集成路径。 - + - 基础 Vitest 配置默认使用 `threads`。 - - 共享 Vitest 配置固定为 `isolate: false`，并在根项目、e2e 和 live 配置中使用非隔离运行器。 - - 根 UI 通道保留其 `jsdom` 设置和优化器，但也在共享的非隔离运行器上运行。 + - 共享 Vitest 配置固定 `isolate: false`，并在根项目、e2e 和实时配置中使用非隔离运行器。 + - 根 UI 通道保留其 `jsdom` setup 和优化器，但也运行在共享的非隔离运行器上。 - 每个 `pnpm test` 分片都从共享 Vitest 配置继承相同的 `threads` + `isolate: false` 默认值。 - - `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大规模本地运行期间的 V8 编译抖动。设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可对比 stock V8 行为。 + - `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可与原生 V8 行为进行对比。 - - `pnpm changed:lanes` 会显示某个 diff 触发了哪些架构通道。 - - pre-commit hook 仅做格式化。它会重新暂存已格式化文件，但不会运行 lint、typecheck 或测试。 - - 当你需要智能本地门禁时，请在交接或 push 前显式运行 `pnpm check:changed`。公共 Plugin SDK 和 plugin-contract 的变更会额外包含一次 extension 验证。 - - 当变更路径可以清晰映射到更小的测试套件时，`pnpm test:changed` 会通过定向通道执行。 - - `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 changed:lanes` 会显示某个差异触发了哪些架构通道。 + - pre-commit hook 只做格式化。它会重新暂存已格式化文件，但不会运行 lint、typecheck 或测试。 + - 当你需要智能本地门禁时，请在交接或 push 前显式运行 `pnpm check:changed`。公共插件 SDK 和插件契约变更会包含一次扩展验证。 + - 当变更路径可以清晰映射到较小测试套件时，`pnpm test:changed` 会通过作用域通道进行路由。 + - `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由行为，只是使用更高的工作进程上限。 + - 本地工作进程自动扩缩容故意采取保守策略，当宿主机负载平均值已经较高时会自动回退，因此默认情况下多个并发 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` 以来变更的文件。 - - 当某个热点测试的大部分时间仍然消耗在启动导入上时，应将重型依赖保留在一个狭窄的本地 `*.runtime.ts` 接口之后，并直接 mock 该接口，而不是为了通过 `vi.mock(...)` 传递它们就深度导入运行时辅助工具。 - - `pnpm test:perf:changed:bench -- --ref ` 会针对该已提交 diff，将定向的 `test:changed` 与原生根项目路径进行对比，并输出总耗时以及 macOS 最大 RSS。 - - `pnpm test:perf:changed:bench -- --worktree` 会通过将变更文件列表分别路由到 `scripts/test-projects.mjs` 和根 Vitest 配置，对当前未提交工作树进行基准测试。 - - `pnpm test:perf:profile:main` 会为 Vitest/Vite 启动和转换开销写入主线程 CPU profile。 - - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为 unit 测试套件写入运行器 CPU + heap profile。 + - `pnpm test:perf:imports:changed` 会将相同的性能分析视图限定为自 `origin/main` 以来变更的文件。 + - 当某个热点测试仍然将大部分时间耗在启动导入上时，应将重型依赖放在狭窄的本地 `*.runtime.ts` 接缝之后，并直接 mock 该接缝，而不是为了通过 `vi.mock(...)` 传递它们就深度导入运行时辅助模块。 + - `pnpm test:perf:changed:bench -- --ref ` 会将路由后的 `test:changed` 与该已提交差异对应的原生根项目路径进行比较，并打印总耗时以及 macOS 最大 RSS。 + - `pnpm test:perf:changed:bench -- --worktree` 会通过将变更文件列表路由到 `scripts/test-projects.mjs` 和根 Vitest 配置，对当前未提交工作树进行基准测试。 + - `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动与转换开销写出主线程 CPU profile。 + - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元测试套件写出运行器 CPU + 堆 profile。 ### 稳定性（Gateway 网关） - 命令：`pnpm test:stability:gateway` -- 配置：`vitest.gateway.config.ts`，强制只使用一个 worker +- 配置：`vitest.gateway.config.ts`，强制使用单个工作进程 - 范围： - 启动一个默认启用诊断功能的真实 loopback Gateway 网关 - - 通过诊断事件路径驱动合成的 gateway message、memory 和大负载 churn + - 通过诊断事件路径驱动合成的 Gateway 网关消息、内存和大负载 churn - 通过 Gateway 网关 WS RPC 查询 `diagnostics.stability` - - 覆盖诊断稳定性 bundle 持久化辅助工具 - - 断言 recorder 保持有界、合成 RSS 样本保持在压力预算之下，并且每个会话的队列深度都会回落到零 + - 覆盖诊断稳定性 bundle 持久化辅助函数 + - 断言记录器保持有界、合成 RSS 采样保持在压力预算之下，并且每个会话的队列深度都会回落到零 - 预期： - - 对 CI 安全且不需要密钥 - - 这是一个用于稳定性回归跟进的窄通道，而不是完整 Gateway 网关测试套件的替代品 + - 对 CI 安全且无需密钥 + - 这是用于稳定性回归后续跟进的窄通道，不可替代完整的 Gateway 网关测试套件 ### E2E（Gateway 网关冒烟） - 命令：`pnpm test:e2e` - 配置：`vitest.e2e.config.ts` -- 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 下的内置 plugin E2E 测试 +- 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 下内置插件的 E2E 测试 - 运行时默认值： - - 使用 Vitest `threads` 且设置 `isolate: false`，与仓库其余部分保持一致。 - - 使用自适应 workers（CI：最多 2 个，本地：默认 1 个）。 + - 使用 Vitest `threads`，并设置 `isolate: false`，与仓库其余部分保持一致。 + - 使用自适应工作进程（CI：最多 2 个，本地：默认 1 个）。 - 默认以 silent 模式运行，以减少控制台 I/O 开销。 - 常用覆盖项： - - `OPENCLAW_E2E_WORKERS=` 用于强制指定 worker 数量（上限为 16）。 - - `OPENCLAW_E2E_VERBOSE=1` 用于重新启用详细控制台输出。 + - `OPENCLAW_E2E_WORKERS=`：强制指定工作进程数（上限为 16）。 + - `OPENCLAW_E2E_VERBOSE=1`：重新启用详细控制台输出。 - 范围： - 多实例 Gateway 网关端到端行为 - - WebSocket/HTTP 表面、节点配对以及更重的网络行为 + - WebSocket / HTTP 接口、节点配对，以及更重的网络路径 - 预期： - 在 CI 中运行（当流水线中启用时） - 不需要真实密钥 - - 比 unit 测试包含更多活动部件（可能更慢） + - 比单元测试包含更多活动部件（可能更慢） ### E2E：OpenShell 后端冒烟 - 命令：`pnpm test:e2e:openshell` - 文件：`extensions/openshell/src/backend.e2e.test.ts` - 范围： - - 通过 Docker 在主机上启动一个隔离的 OpenShell gateway - - 从一个临时本地 Dockerfile 创建一个沙箱 - - 通过真实的 `sandbox ssh-config` + SSH exec 运行 OpenClaw 的 OpenShell 后端 - - 通过沙箱文件系统桥接验证远端规范化的文件系统行为 + - 通过 Docker 在宿主机上启动一个隔离的 OpenShell Gateway 网关 + - 从一个临时本地 Dockerfile 创建沙箱 + - 通过真实的 `sandbox ssh-config` + SSH exec 测试 OpenClaw 的 OpenShell 后端 + - 通过沙箱 fs bridge 验证远端规范文件系统行为 - 预期： - 仅按需启用；不属于默认 `pnpm test:e2e` 运行的一部分 - - 需要本地 `openshell` CLI 和一个可用的 Docker daemon - - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，随后销毁测试 gateway 和沙箱 + - 需要本地 `openshell` CLI 和可用的 Docker daemon + - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 Gateway 网关和沙箱 - 常用覆盖项： - - `OPENCLAW_E2E_OPENSHELL=1` 用于在手动运行更大范围 e2e 测试套件时启用该测试 - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 用于指向非默认 CLI 二进制文件或包装脚本 + - `OPENCLAW_E2E_OPENSHELL=1`：在手动运行更广泛的 e2e 测试套件时启用该测试 + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`：指向非默认 CLI 二进制或包装脚本 -### Live（真实提供商 + 真实模型） +### 实时（真实提供商 + 真实模型） - 命令：`pnpm test:live` - 配置：`vitest.live.config.ts` -- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下的内置 plugin live 测试 -- 默认：由 `pnpm test:live` **启用**（会设置 `OPENCLAW_LIVE_TEST=1`） +- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下内置插件的实时测试 +- 默认：由 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`） - 范围： - - “这个提供商/模型在 _今天_ 配合真实凭证是否真的能工作？” - - 捕获提供商格式变更、工具调用怪异行为、认证问题以及速率限制行为 + - “这个提供商 / 模型今天在真实凭证下是否真的可用？” + - 捕获提供商格式变更、工具调用怪癖、认证问题以及速率限制行为 - 预期： - - 按设计不具备 CI 稳定性（真实网络、真实提供商策略、配额、故障） - - 会花钱 / 消耗速率限制 - - 优先运行收窄后的子集，而不是“全部都跑” -- live 运行会读取 `~/.profile`，以获取缺失的 API key。 -- 默认情况下，live 运行仍会隔离 `HOME`，并将配置/认证材料复制到一个临时测试 home 中，这样 unit fixture 就不会修改你真实的 `~/.openclaw`。 -- 仅当你确实需要 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 -- `pnpm test:live` 现在默认使用更安静的模式：它会保留 `[live] ...` 进度输出，但会抑制额外的 `~/.profile` 提示，并静音 gateway 启动日志/Bonjour 噪音。如果你想恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。 -- API key 轮换（提供商特定）：设置 `*_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 进度行会立即流式输出。 + - 设计上不保证 CI 稳定性（真实网络、真实提供商策略、配额、故障） + - 会花钱 / 消耗速率限制额度 + - 优先运行缩小范围的子集，而不是“全量” +- 实时运行会加载 `~/.profile` 以获取缺失的 API 密钥。 +- 默认情况下，实时运行仍会隔离 `HOME`，并将配置 / 认证材料复制到临时测试 home 中，这样单元测试夹具就不会修改你真实的 `~/.openclaw`。 +- 只有在你明确需要让实时测试使用真实 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` 进行每次实时运行覆盖；测试会在速率限制响应时重试。 +- 进度 / 心跳输出： + - 实时测试套件现在会向 stderr 输出进度行，因此即使 Vitest 控制台捕获较安静，长时间的提供商调用也会显式显示为仍在活动。 + - `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，以便提供商 / Gateway 网关进度行在实时运行期间立即流式输出。 - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型心跳。 - - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 gateway/探测心跳。 + - 使用 `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（触网）测试 +## 实时（触网）测试 -关于 live 模型矩阵、CLI 后端冒烟、ACP 冒烟、Codex app-server -harness，以及所有媒体提供商 live 测试（Deepgram、BytePlus（国际版）、ComfyUI、图像、 -音乐、视频、媒体 harness）——以及 live 运行的凭证处理——请参见 -[测试 — live 测试套件](/zh-CN/help/testing-live)。 +对于实时模型矩阵、CLI 后端冒烟、ACP 冒烟、Codex app-server +测试框架，以及所有媒体提供商实时测试（Deepgram、BytePlus（国际版）、ComfyUI、图像、 +音乐、视频、媒体测试框架）——以及实时运行的凭证处理——请参见 +[测试——实时测试套件](/zh-CN/help/testing-live)。 ## 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` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像中运行各自匹配的 profile-key 实时测试文件（`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 实时运行器默认有较小的冒烟上限，以便完整的 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_MODEL_TIMEOUT_MS=90000`。当你 - 明确想要进行更大范围的穷尽扫描时，可覆盖这些环境变量。 -- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次 live Docker 镜像，然后在两个 live Docker 通道中复用它。它还会通过 `test:docker:e2e-build` 构建一个共享的 `scripts/e2e/Dockerfile` 镜像，并将其复用于那些验证已构建应用的 E2E 容器冒烟运行器。 + `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` 和 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。如果你明确需要更大的穷举扫描，可覆盖这些环境变量。 +- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次实时 Docker 镜像，然后在两个实时 Docker 通道中复用它。它还会通过 `test:docker:e2e-build` 构建一个共享的 `scripts/e2e/Dockerfile` 镜像，并在测试已构建应用的 E2E 容器冒烟运行器中复用它。 - 容器冒烟运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update` 和 `test:docker:config-reload` 会启动一个或多个真实容器，并验证更高层级的集成路径。 -live-model Docker 运行器还会仅 bind-mount 所需的 CLI auth home（如果运行未收窄，则会挂载所有受支持的 auth home），然后在运行前将其复制到容器 home 中，这样外部 CLI OAuth 就能刷新 token，而不会修改主机 auth 存储： +实时模型 Docker 运行器还会只绑定挂载所需的 CLI 认证 home（如果运行未缩小范围，则挂载所有受支持的认证 home），然后在运行前将它们复制到容器 home 中，以便外部 CLI OAuth 可以刷新 token，而不会修改宿主机认证存储： -- 直连模型：`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`） -- Codex app-server harness 冒烟测试：`pnpm test:docker:live-codex-harness`（脚本：`scripts/test-live-codex-harness-docker.sh`） +- 直接模型：`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`） +- Codex app-server 测试框架冒烟：`pnpm test:docker:live-codex-harness`（脚本：`scripts/test-live-codex-harness-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`） -- onboarding 向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`） -- Npm tarball onboarding/渠道/智能体冒烟测试：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装打包好的 OpenClaw tarball，通过 env-ref onboarding 配置 OpenAI，并默认配置 Telegram，验证 doctor 会修复已激活 plugin 的运行时依赖，并运行一次 mock OpenAI 智能体轮次。可使用 `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，使用 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 跳过主机构建，或使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切换渠道。 -- Bun 全局安装冒烟测试：`bash scripts/e2e/bun-global-install-smoke.sh` 会打包当前工作树，在隔离的 home 中使用 `bun install -g` 安装，并验证 `openclaw infer image providers --json` 会返回内置图像提供商而不是卡住。可使用 `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，使用 `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` 跳过主机构建，或通过 `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` 从已构建的 Docker 镜像复制 `dist/`。 -- 安装器 Docker 冒烟测试：`bash scripts/test-install-sh-docker.sh` 会在其 root、update 和 direct-npm 容器之间共享一个 npm 缓存。更新冒烟测试默认以 npm `latest` 作为稳定基线，再升级到候选 tarball。非 root 安装器检查会保持一个隔离的 npm 缓存，以避免 root 所有的缓存条目掩盖用户本地安装行为。设置 `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` 可在本地重跑之间复用 root/update/direct-npm 缓存。 -- Install Smoke CI 会通过 `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` 跳过重复的 direct-npm 全局更新；当需要覆盖直接 `npm install -g` 时，请在本地运行脚本且不要设置该环境变量。 -- Gateway 网关网络（两个容器，WS 认证 + health）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`） -- OpenAI Responses `web_search` 最小推理回归测试：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会通过 Gateway 网关运行一个 mock OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升到 `low`，然后强制 provider schema 拒绝，并检查原始细节是否出现在 Gateway 网关日志中。 -- MCP 渠道桥接（预置 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟测试）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`） -- Pi bundle MCP 工具（真实 stdio MCP 服务器 + 内嵌 Pi profile allow/deny 冒烟测试）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`） -- Cron/subagent MCP 清理（真实 Gateway 网关 + 独立 cron 和一次性 subagent 运行后的 stdio MCP 子进程清理）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`） -- Plugins（安装冒烟测试 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`） -- Plugin 更新无变化冒烟测试：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`） -- 配置热重载元数据冒烟测试：`pnpm test:docker:config-reload`（脚本：`scripts/e2e/config-reload-source-docker.sh`） -- 内置 plugin 运行时依赖：`pnpm test:docker:bundled-channel-deps` 默认会构建一个小型 Docker 运行器镜像，在主机上构建并打包一次 OpenClaw，然后将该 tarball 挂载到每个 Linux 安装场景中。可使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 复用镜像，在完成一次新的本地构建后使用 `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` 跳过主机重建，或通过 `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 指向现有 tarball。完整 Docker 聚合会先预打包一次该 tarball，然后将内置渠道检查分片到独立通道中；直接运行内置通道时，可使用 `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` 收窄渠道矩阵。 -- 在迭代时，可通过禁用无关场景来收窄内置 plugin 运行时依赖检查，例如： +- Open WebUI 实时冒烟：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`） +- 新手引导向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`） +- Npm tarball 新手引导 / 渠道 / 智能体冒烟：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装打包后的 OpenClaw tarball，通过 env-ref 新手引导配置 OpenAI，并默认配置 Telegram，验证 doctor 会修复已激活插件的运行时依赖，然后运行一次模拟的 OpenAI 智能体轮次。通过 `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，通过 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 跳过宿主重建，或通过 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切换渠道。 +- Bun 全局安装冒烟：`bash scripts/e2e/bun-global-install-smoke.sh` 会打包当前工作树，在隔离的 home 中使用 `bun install -g` 安装，并验证 `openclaw infer image providers --json` 会返回内置图像提供商而不是挂起。通过 `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，通过 `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` 跳过宿主构建，或通过 `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` 从已构建的 Docker 镜像复制 `dist/`。 +- 安装器 Docker 冒烟：`bash scripts/test-install-sh-docker.sh` 会在其 root、update 和 direct-npm 容器之间共享同一个 npm 缓存。更新冒烟默认使用 npm `latest` 作为稳定基线，再升级到候选 tarball。非 root 安装器检查会保留隔离的 npm 缓存，这样 root 所有的缓存条目就不会掩盖用户本地安装行为。设置 `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` 可在本地重复运行之间复用 root / update / direct-npm 缓存。 +- Install Smoke CI 会通过 `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` 跳过重复的 direct-npm 全局更新；当你需要直接 `npm install -g` 覆盖时，请在本地运行该脚本且不要设置此环境变量。 +- Gateway 网关网络（两个容器，WS 认证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`） +- OpenAI Responses `web_search` 最小推理回归：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会通过 Gateway 网关运行一个模拟的 OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升为 `low`，然后强制提供商 schema 拒绝，并检查原始细节出现在 Gateway 网关日志中。 +- MCP 渠道桥接（已播种的 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`） +- Pi bundle MCP 工具（真实 stdio MCP 服务器 + 嵌入式 Pi profile allow / deny 冒烟）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`） +- Cron / 子智能体 MCP 清理（真实 Gateway 网关 + 在隔离 cron 和一次性子智能体运行后拆除 stdio MCP 子进程）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`） +- 插件（安装冒烟 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`） +- 插件更新未变更冒烟：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`） +- 配置热重载元数据冒烟：`pnpm test:docker:config-reload`（脚本：`scripts/e2e/config-reload-source-docker.sh`） +- 内置插件运行时依赖：`pnpm test:docker:bundled-channel-deps` 默认会构建一个小型 Docker 运行器镜像，在宿主机上构建并打包 OpenClaw 一次，然后将该 tarball 挂载到每个 Linux 安装场景中。通过 `OPENCLAW_SKIP_DOCKER_BUILD=1` 复用镜像，通过 `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` 在本地新鲜构建后跳过宿主重建，或通过 `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 指向现有 tarball。完整 Docker 聚合会先预打包该 tarball 一次，然后把内置渠道检查分片为独立通道；直接运行内置通道时，可使用 `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` 缩小渠道矩阵。该通道还会验证 `channels..enabled=false` 和 `plugins.entries..enabled=false` 会抑制 doctor / 运行时依赖修复。 +- 在迭代时缩小内置插件运行时依赖范围，可禁用无关场景，例如： `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`。 -如需手动预构建并复用共享的 built-app 镜像： +若要手动预构建并复用共享的 built-app 镜像： ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -设置后，诸如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 之类的测试套件专用镜像覆盖仍然优先生效。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远程共享镜像时，如果该镜像尚未在本地存在，脚本会先拉取它。QR 和安装器 Docker 测试保留各自的 Dockerfile，因为它们验证的是 package/install 行为，而不是共享的 built-app 运行时。 +设置后，诸如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 这类测试套件专属镜像覆盖仍然优先生效。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远程共享镜像时，如果该镜像尚未存在于本地，脚本会先拉取它。QR 和安装器 Docker 测试保留各自独立的 Dockerfile，因为它们验证的是包 / 安装行为，而不是共享的 built-app 运行时。 -live-model Docker 运行器还会以只读方式 bind-mount 当前 checkout，并将其暂存到容器内的临时工作目录中。这样既能保持运行时镜像精简，又仍能让 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 覆盖时，也请一并传入 +实时模型 Docker 运行器还会将当前检出以只读方式绑定挂载，并在容器内部临时工作目录中进行暂存。这样既能保持运行时镜像轻量，又能让 Vitest 基于你精确的本地源码 / 配置运行。 +暂存步骤会跳过大型本地专用缓存和应用构建输出，例如 +`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地 `.build` 或 +Gradle 输出目录，因此 Docker 实时运行不会花费数分钟复制机器专属产物。 +它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 Gateway 网关实时探测就不会在容器内启动 +真实的 Telegram / Discord / 等渠道工作进程。 +`test:docker:live-models` 仍然会运行 `pnpm test:live`，因此当你需要缩小或排除该 Docker 通道中的 Gateway 网关实时覆盖时，也请同时传入 `OPENCLAW_LIVE_GATEWAY_*`。 -`test:docker:openwebui` 是一个更高层级的兼容性冒烟测试：它会启动一个启用了 OpenAI 兼容 HTTP 端点的 -OpenClaw gateway 容器，再针对该 gateway 启动一个固定版本的 Open WebUI 容器，通过 -Open WebUI 登录，验证 `/api/models` 暴露了 `openclaw/default`，然后通过 +`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": +首次运行可能明显更慢，因为 Docker 可能需要拉取 +Open WebUI 镜像，而且 Open WebUI 可能需要完成自己的冷启动 setup。 +该通道需要一个可用的实时模型密钥，而 `OPENCLAW_PROFILE_FILE` +（默认 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。 +成功运行会打印一个小型 JSON payload，例如 `{ "ok": true, "model": "openclaw/default", ... }`。 -`test:docker:mcp-channels` 是刻意设计为确定性的，不需要真实的 -Telegram、Discord 或 iMessage 账户。它会启动一个预置的 Gateway 网关 -容器，再启动第二个容器来运行 `openclaw mcp serve`，然后 -通过真实的 stdio MCP bridge 验证路由后的会话发现、transcript 读取、附件元数据、 -live 事件队列行为、出站发送路由，以及 Claude 风格的渠道 + +`test:docker:mcp-channels` 是刻意保持确定性的，不需要 +真实的 Telegram、Discord 或 iMessage 账号。它会启动一个已播种的 Gateway 网关 +容器，启动第二个容器来拉起 `openclaw mcp serve`，然后 +通过真实的 stdio MCP bridge 验证已路由会话发现、转录读取、附件元数据、 +实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。通知检查会直接检查原始 stdio MCP 帧，因此该冒烟测试验证的是 bridge 实际发出的内容，而不只是某个特定客户端 SDK 恰好暴露的内容。 -`test:docker:pi-bundle-mcp-tools` 是确定性的，不需要 live -模型密钥。它会构建仓库 Docker 镜像，在容器内启动一个真实的 stdio MCP probe 服务器， -通过内嵌 Pi bundle MCP 运行时实例化该服务器，执行该工具，然后验证 `coding` 和 `messaging` 保留 -`bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会将其过滤掉。 -`test:docker:cron-mcp-cleanup` 是确定性的，不需要 live 模型 -密钥。它会启动一个带真实 stdio MCP probe 服务器的预置 Gateway 网关，运行一个 -独立的 cron 轮次和一个 `/subagents spawn` 一次性子智能体轮次，然后验证 +`test:docker:pi-bundle-mcp-tools` 是确定性的，不需要实时 +模型密钥。它会构建仓库 Docker 镜像，在容器中启动一个真实 stdio MCP 探针服务器， +通过嵌入式 Pi bundle MCP 运行时实例化该服务器，执行该工具， +然后验证 `coding` 和 `messaging` 会保留 +`bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会过滤掉它们。 +`test:docker:cron-mcp-cleanup` 是确定性的，不需要实时模型 +密钥。它会启动一个带有真实 stdio MCP 探针服务器的已播种 Gateway 网关，运行一个隔离的 +cron 轮次和一个 `/subagents spawn` 一次性子智能体轮次，然后验证 MCP 子进程会在每次运行后退出。 -手动 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_PROFILE_ENV_ONLY=1` 用于验证仅来自 `OPENCLAW_PROFILE_FILE` 的环境变量，此时会使用临时 config/workspace 目录且不挂载外部 CLI auth -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）会挂载到 `/home/node/.npm-global`，用于 Docker 内缓存 CLI 安装 -- `$HOME` 下的外部 CLI auth 目录/文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...` +- `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_PROFILE_ENV_ONLY=1` 用于仅验证从 `OPENCLAW_PROFILE_FILE` 加载的环境变量，使用临时配置 / 工作区目录，且不挂载外部 CLI 认证 +- `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` - - 收窄后的 provider 运行只会挂载根据 `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_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_SKIP_DOCKER_BUILD=1` 用于复用现有的 `openclaw:local-live` 镜像，以便在无需重建时重跑 +- `OPENCLAW_SKIP_DOCKER_BUILD=1` 用于在不需要重建的重复运行中复用现有 `openclaw:local-live` 镜像 - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于确保凭证来自 profile 存储（而不是环境变量） -- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择 gateway 为 Open WebUI 冒烟测试暴露的模型 -- `OPENCLAW_OPENWEBUI_PROMPT=...` 用于覆盖 Open WebUI 冒烟测试使用的 nonce-check prompt -- `OPENWEBUI_IMAGE=...` 用于覆盖固定版本的 Open WebUI 镜像标签 +- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择在 Open WebUI 冒烟测试中由 Gateway 网关暴露的模型 +- `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 安全） -这些是在没有真实提供商的情况下进行的“真实流水线”回归测试： +这些是“真实流水线”回归测试，但不需要真实提供商： -- Gateway 网关工具调用（mock 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”） +- 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”） ## 智能体可靠性评估（Skills） -我们已经有一些对 CI 安全的测试，它们的行为类似“智能体可靠性评估”： +我们已经有一些对 CI 安全的测试，其行为类似于“智能体可靠性评估”： -- 通过真实 gateway + 智能体循环进行 mock 工具调用（`src/gateway/gateway.test.ts`）。 +- 通过真实 Gateway 网关 + 智能体循环进行模拟工具调用（`src/gateway/gateway.test.ts`）。 - 验证会话接线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。 -对于 Skills（见 [Skills](/zh-CN/tools/skills)），目前仍然缺少的是： +对于 Skills，目前仍缺少的部分（见 [Skills](/zh-CN/tools/skills)）： -- **决策**：当 prompt 中列出 Skills 时，智能体是否会选择正确的 skill（或避免无关的 skill）？ -- **合规性**：智能体在使用前是否会读取 `SKILL.md` 并遵循要求的步骤/参数？ -- **工作流契约**：断言工具调用顺序、会话历史延续以及沙箱边界的多轮场景。 +- **决策：** 当提示词中列出 Skills 时，智能体是否会选择正确的 Skill（或避免选择无关的 Skill）？ +- **合规：** 智能体在使用前是否会读取 `SKILL.md`，并遵循要求的步骤 / 参数？ +- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。 -未来的评估应首先保持确定性： +未来的评估应优先保持确定性： -- 一个使用 mock 提供商的场景运行器，用于断言工具调用 + 顺序、skill 文件读取以及会话接线。 -- 一组小型的 skill 聚焦场景（使用 vs 避免、门控、prompt injection）。 -- 仅在 CI 安全测试套件落地之后，才添加可选的 live 评估（按需启用、受环境变量门控）。 +- 一个使用模拟提供商的场景运行器，用于断言工具调用与顺序、Skill 文件读取以及会话接线。 +- 一小组聚焦 Skill 的场景（使用 vs 避免、门控、提示注入）。 +- 只有在 CI 安全套件就绪之后，才添加可选的实时评估（按需启用、由环境变量门控）。 -## 契约测试（plugin 和 channel 结构） +## 契约测试（插件和渠道形状） -契约测试用于验证每个已注册的 plugin 和 channel 都符合其接口契约。它们会遍历所有已发现的 plugins，并运行一组关于结构和行为的断言。默认的 `pnpm test` unit 通道会有意跳过这些共享接口和冒烟文件；当你修改共享的 channel 或 provider 表面时，请显式运行契约测试命令。 +契约测试用于验证每个已注册插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一组关于形状和行为的断言。默认的 `pnpm test` 单元测试通道会刻意跳过这些共享接缝和冒烟文件；当你修改共享渠道或提供商接口时，请显式运行契约命令。 ### 命令 -- 所有契约测试：`pnpm test:contracts` -- 仅 channel 契约测试：`pnpm test:contracts:channels` -- 仅 provider 契约测试：`pnpm test:contracts:plugins` +- 所有契约：`pnpm test:contracts` +- 仅渠道契约：`pnpm test:contracts:channels` +- 仅提供商契约：`pnpm test:contracts:plugins` -### Channel 契约测试 +### 渠道契约 位于 `src/channels/plugins/contracts/*.contract.test.ts`： -- **plugin** - 基本 plugin 结构（id、name、capabilities） +- **plugin** - 基础插件形状（id、名称、能力） - **setup** - 设置向导契约 - **session-binding** - 会话绑定行为 - **outbound-payload** - 消息 payload 结构 - **inbound** - 入站消息处理 -- **actions** - 渠道 action 处理器 +- **actions** - 渠道操作处理器 - **threading** - 线程 ID 处理 -- **directory** - 目录/成员列表 API -- **group-policy** - 群组策略强制执行 +- **directory** - 目录 / 花名册 API +- **group-policy** - 群组策略执行 -### Provider 状态契约测试 +### 提供商状态契约 位于 `src/plugins/contracts/*.contract.test.ts`。 - **status** - 渠道状态探测 -- **registry** - Plugin 注册表结构 +- **registry** - 插件注册表形状 -### Provider 契约测试 +### 提供商契约 位于 `src/plugins/contracts/*.contract.test.ts`： - **auth** - 认证流程契约 -- **auth-choice** - 认证选择/选择机制 +- **auth-choice** - 认证选项 / 选择 - **catalog** - 模型目录 API -- **discovery** - Plugin 发现 -- **loader** - Plugin 加载 -- **runtime** - Provider 运行时 -- **shape** - Plugin 结构/接口 +- **discovery** - 插件发现 +- **loader** - 插件加载 +- **runtime** - 提供商运行时 +- **shape** - 插件形状 / 接口 - **wizard** - 设置向导 ### 何时运行 -- 修改 `plugin-sdk` 导出或子路径之后 -- 添加或修改 channel 或 provider plugin 之后 -- 重构 plugin 注册或发现逻辑之后 +- 修改 plugin-sdk 导出或子路径之后 +- 添加或修改渠道或提供商插件之后 +- 重构插件注册或发现逻辑之后 -契约测试会在 CI 中运行，且不需要真实 API key。 +契约测试会在 CI 中运行，不需要真实 API 密钥。 -## 添加回归测试（指南） +## 添加回归测试（指导） -当你修复一个在 live 中发现的 provider/model 问题时： +当你修复一个在实时环境中发现的提供商 / 模型问题时： -- 如果可能，请添加一个对 CI 安全的回归测试（mock/stub provider，或捕获精确的请求结构转换） -- 如果问题本质上只能在 live 中复现（速率限制、认证策略），请保持 live 测试足够收窄，并通过环境变量按需启用 -- 优先定位到能够捕获该缺陷的最小层级： - - provider 请求转换/重放缺陷 → 直连模型测试 - - gateway 会话/历史/工具管线缺陷 → gateway live 冒烟测试或对 CI 安全的 gateway mock 测试 -- 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`。该测试会在出现未分类 target id 时故意失败，这样新类别就不会被悄悄跳过。 +- 如果可能，添加一个对 CI 安全的回归测试（模拟 / stub 提供商，或捕获精确的请求形状转换） +- 如果它本质上只能在实时环境中复现（速率限制、认证策略），就让实时测试保持窄范围，并通过环境变量按需启用 +- 优先瞄准能够捕获该缺陷的最小层级： + - 提供商请求转换 / 回放缺陷 → 直接模型测试 + - Gateway 网关会话 / 历史 / 工具流水线缺陷 → Gateway 网关实时冒烟或对 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 时有意失败，这样新类别就无法被静默跳过。 ## 相关内容 -- [Testing live](/zh-CN/help/testing-live) +- [实时测试](/zh-CN/help/testing-live) - [CI](/zh-CN/ci) diff --git a/docs/zh-CN/install/updating.md b/docs/zh-CN/install/updating.md index 313d641d1..b65f441c2 100644 --- a/docs/zh-CN/install/updating.md +++ b/docs/zh-CN/install/updating.md @@ -1,14 +1,14 @@ --- read_when: - 更新 OpenClaw - - 更新后出现问题时 + - 更新后出现问题 summary: 安全更新 OpenClaw（全局安装或源码安装），以及回滚策略 -title: 更新♀♀♀analysis to=final code omitted +title: 更新 x-i18n: - generated_at: "2026-04-23T20:53:22Z" + generated_at: "2026-04-24T16:58:27Z" model: gpt-5.4 provider: openai - source_hash: 04ed583916ce64c9f60639c8145a46ce5b27ebf5a6dfd09924312d7acfefe1ab + source_hash: f57c5f4d4988eabb62a2c836c07f56e329149b1f9290baa0568ef1d86f66e0ad source_path: install/updating.md workflow: 15 --- @@ -17,13 +17,13 @@ x-i18n: ## 推荐：`openclaw update` -这是最快的更新方式。它会检测你的安装类型（npm 或 git）、获取最新版本、运行 `openclaw doctor`，并重启 gateway。 +这是最快的更新方式。它会检测你的安装类型（npm 或 git），获取最新版本，运行 `openclaw doctor`，并重启 Gateway 网关。 ```bash openclaw update ``` -若要切换渠道或指定特定版本： +如需切换渠道或指定特定版本： ```bash openclaw update --channel beta @@ -31,12 +31,11 @@ openclaw update --tag main openclaw update --dry-run # 仅预览，不实际应用 ``` -`--channel beta` 会优先选择 beta，但当 -beta 标签缺失或比最新稳定版更旧时，运行时会回退到 stable/latest。若你想在一次性包更新中使用原始 npm beta dist-tag，请使用 `--tag beta`。 +`--channel beta` 会优先选择 beta，但当 beta 标签不存在或版本比最新 stable 发布更旧时，运行时会回退到 stable/latest。如果你想要一次性按原始 npm beta dist-tag 更新包，请使用 `--tag beta`。 -有关渠道语义，请参见 [Development channels](/zh-CN/install/development-channels)。 +渠道语义请参见 [Development channels](/zh-CN/install/development-channels)。 -## 另一种方式：重新运行安装器 +## 另一种方式：重新运行安装脚本 ```bash curl -fsSL https://openclaw.ai/install.sh | bash @@ -60,25 +59,26 @@ bun add -g openclaw@latest ### 由 root 拥有的全局 npm 安装 -某些 Linux npm 设置会将全局包安装到由 root 拥有的目录中，例如 -`/usr/lib/node_modules/openclaw`。OpenClaw 支持这种布局：已安装的 -包在运行时会被视为只读，而内置插件运行时依赖会被暂存到可写运行时目录中，而不是修改 -包树。 +某些 Linux npm 环境会将全局包安装到由 root 拥有的目录中，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 支持这种布局：已安装的包在运行时会被视为只读，内置插件的运行时依赖会被暂存到可写的运行时目录中，而不是修改包目录树。 -对于加固后的 systemd unit，请设置一个可写暂存目录，并将其包含在 -`ReadWritePaths` 中： +对于加固的 systemd 单元，请设置一个可写的暂存目录，并将其包含在 `ReadWritePaths` 中： ```ini Environment=OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp ``` -如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 -systemd 提供时使用 `$STATE_DIRECTORY`，否则回退到 `~/.openclaw/plugin-runtime-deps`。 +如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 systemd 提供时使用 `$STATE_DIRECTORY`，否则回退到 `~/.openclaw/plugin-runtime-deps`。 + +### 内置插件运行时依赖 + +打包安装会将内置插件运行时依赖保留在只读包目录树之外。在启动期间以及执行 `openclaw doctor --fix` 时，OpenClaw 只会为以下内置插件修复运行时依赖：在配置中处于活动状态、通过旧版渠道配置处于活动状态，或由其内置清单默认启用的插件。 + +显式禁用具有最高优先级。已禁用的插件或渠道不会仅因为存在于安装包中就修复其运行时依赖。外部插件和自定义加载路径仍然使用 `openclaw plugins install` 或 `openclaw plugins update`。 ## 自动更新器 -自动更新器默认关闭。可在 `~/.openclaw/openclaw.json` 中启用： +自动更新器默认关闭。在 `~/.openclaw/openclaw.json` 中启用它： ```json5 { @@ -94,13 +94,13 @@ systemd 提供时使用 `$STATE_DIRECTORY`，否则回退到 `~/.openclaw/plugin } ``` -| 渠道 | 行为 | -| -------- | ------------------------------------------------------------------------------------------------------------- | -| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内以确定性抖动方式应用（分散发布）。 | -| `beta` | 每 `betaCheckIntervalHours` 检查一次（默认：每小时），并立即应用。 | -| `dev` | 不会自动应用。请手动使用 `openclaw update`。 | +| Channel | 行为 | +| -------- | ---- | +| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内按确定性抖动应用（分散发布）。 | +| `beta` | 每隔 `betaCheckIntervalHours` 检查一次（默认：每小时），并立即应用。 | +| `dev` | 不会自动应用。请手动使用 `openclaw update`。 | -gateway 还会在启动时记录更新提示（可通过 `update.checkOnStart: false` 禁用）。 +Gateway 网关还会在启动时记录更新提示（可通过 `update.checkOnStart: false` 禁用）。 ## 更新后 @@ -112,9 +112,9 @@ gateway 还会在启动时记录更新提示（可通过 `update.checkOnStart: f openclaw doctor ``` -迁移配置、审计私信策略并检查 gateway 健康状态。详情请参见：[Doctor](/zh-CN/gateway/doctor) +迁移配置、审核私信策略，并检查 Gateway 网关健康状态。详情： [Doctor](/zh-CN/gateway/doctor) -### 重启 gateway +### 重启 Gateway 网关 ```bash openclaw gateway restart @@ -138,7 +138,7 @@ openclaw doctor openclaw gateway restart ``` -提示：`npm view openclaw version` 会显示当前已发布版本。 +提示：`npm view openclaw version` 会显示当前已发布的版本。 ### 固定提交（源码） @@ -149,14 +149,14 @@ pnpm install && pnpm build openclaw gateway restart ``` -若要恢复到最新版本：`git checkout main && git pull`。 +如需恢复到最新版本：`git checkout main && git pull`。 ## 如果你卡住了 -- 再次运行 `openclaw doctor`，并仔细阅读输出。 -- 对于源码检出上的 `openclaw update --channel dev`，更新器会在需要时自动引导 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`），然后重新运行更新。 -- 请查看：[Troubleshooting](/zh-CN/gateway/troubleshooting) -- 可在 Discord 中提问：[https://discord.gg/clawd](https://discord.gg/clawd) +- 再次运行 `openclaw doctor`，并仔细阅读输出内容。 +- 对于源码检出的 `openclaw update --channel dev`，更新器会在需要时自动引导安装 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`），然后重新运行更新。 +- 查看：[故障排除](/zh-CN/gateway/troubleshooting) +- 在 Discord 中提问：[https://discord.gg/clawd](https://discord.gg/clawd) ## 相关内容 diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index 4c8cc1793..d3bbdd645 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -3,36 +3,45 @@ read_when: - 你想在 OpenClaw 中使用 OpenAI 模型 - 你想使用 Codex 订阅认证，而不是 API 密钥 - 你需要更严格的 GPT-5 智能体执行行为 -summary: 在 OpenClaw 中使用 API 密钥或 Codex 订阅来接入 OpenAI +summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI title: OpenAI x-i18n: - generated_at: "2026-04-24T05:42:15Z" + generated_at: "2026-04-24T16:58:29Z" model: gpt-5.4 provider: openai - source_hash: 3d533338fa15d866bb69584706162ce099bb4a1edc9851183fb5442730ebdd9b + source_hash: bedc8975dae28e13d653494723ca0ee44cefdb63cbd4c6397658bd22fd8c3d80 source_path: providers/openai.md workflow: 15 --- -OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列接入路径。模型前缀决定所使用的路径： +OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列路由。模型前缀决定所使用的路由： -- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型） -- **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录，并通过订阅获得访问权限（`openai-codex/*` 模型） -- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，外加 `agents.defaults.embeddedHarness.runtime: "codex"`） +- **API 密钥** — 通过按量计费直接访问 OpenAI Platform（`openai/*` 模型） +- **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型） +- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，并配合 `agents.defaults.embeddedHarness.runtime: "codex"`） OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用基于订阅的 OAuth。 +## 快速选择 + +| 目标 | 使用方式 | 说明 | +| --------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- | +| 直接使用 API 密钥计费 | `openai/gpt-5.4` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API 密钥新手引导。 | +| 通过 ChatGPT/Codex 订阅认证使用 GPT-5.5 | `openai-codex/gpt-5.5` | 这是 Codex OAuth 的默认 PI 路由。对于订阅配置来说，是最佳的首选方案。 | +| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `embeddedHarness.runtime: "codex"` | 使用 Codex app-server harness，而不是公开的 OpenAI API 路由。 | +| 图像生成或编辑 | `openai/gpt-image-2` | 可搭配 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 使用。 | + -GPT-5.5 当前可通过订阅/OAuth 路径在 OpenClaw 中使用： -`openai-codex/gpt-5.5` 配合 PI runner，或 `openai/gpt-5.5` 配合 -Codex app-server harness。`openai/gpt-5.5` 的直接 API 密钥访问 -会在 OpenAI 为公共 API 启用 GPT-5.5 后受支持；在此之前，请为 -`OPENAI_API_KEY` 配置使用支持 API 的模型，例如 `openai/gpt-5.4`。 +GPT-5.5 当前可在 OpenClaw 中通过订阅 / OAuth 路由使用： +`openai-codex/gpt-5.5` 搭配 PI runner，或 `openai/gpt-5.5` 搭配 +Codex app-server harness。对于 `openai/gpt-5.5` 的直接 API 密钥访问， +会在 OpenAI 为公开 API 启用 GPT-5.5 后受支持；在此之前，对于 +`OPENAI_API_KEY` 配置，请使用已启用 API 的模型，例如 `openai/gpt-5.4`。 启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会启用内置的 -Codex app-server 插件。只有当你显式选择原生 Codex harness，即设置 +Codex app-server 插件。只有当你显式选择原生 Codex harness，并设置 `embeddedHarness.runtime: "codex"`，或使用旧版 `codex/*` 模型引用时， OpenClaw 才会启用该插件。 @@ -42,28 +51,28 @@ OpenClaw 才会启用该插件。 | OpenAI 能力 | OpenClaw 表面 | 状态 | | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | | 聊天 / Responses | `openai/` 模型提供商 | 是 | -| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/` | 是 | -| Codex app-server harness | 使用 `embeddedHarness.runtime: codex` 的 `openai/` | 是 | -| 服务端 web 搜索 | 原生 OpenAI Responses 工具 | 是，当启用 web 搜索且未固定提供商时 | +| Codex 订阅模型 | `openai-codex/` 搭配 `openai-codex` OAuth | 是 | +| Codex app-server harness | `openai/` 搭配 `embeddedHarness.runtime: codex` | 是 | +| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 | | 图像 | `image_generate` | 是 | | 视频 | `video_generate` | 是 | -| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 | +| 文字转语音 | `messages.tts.provider: "openai"` / `tts` | 是 | | 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | | 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 | | 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 | -| Embeddings | memory embedding 提供商 | 是 | +| Embeddings | memory embedding provider | 是 | ## 入门指南 -选择你偏好的认证方式，并按照设置步骤进行操作。 +选择你偏好的认证方式，并按照设置步骤操作。 - **最适合：** 直接访问 API，并按使用量计费。 + **最适合：** 直接 API 访问和按量计费。 - - 在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 中创建或复制 API 密钥。 + + 在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。 ```bash @@ -76,24 +85,24 @@ OpenClaw 才会启用该插件。 openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` - ### 路径摘要 + ### 路由摘要 - | Model ref | 路径 | 认证 | + | 模型引用 | 路由 | 认证 | |-----------|-------|------| | `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | | `openai/gpt-5.4-mini` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | - | `openai/gpt-5.5` | 一旦 OpenAI 在 API 中启用 GPT-5.5 后的未来直接 API 路径 | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | 一旦 OpenAI 在 API 上启用 GPT-5.5 后可用的未来直接 API 路由 | `OPENAI_API_KEY` | - `openai/*` 默认是直接 OpenAI API 密钥路径，除非你显式强制使用 - Codex app-server harness。GPT-5.5 本身当前仅支持订阅/OAuth； + 除非你显式强制使用 Codex app-server harness，否则 `openai/*` + 就是直接使用 OpenAI API 密钥的路由。GPT-5.5 本身当前仅支持订阅 / OAuth； 如需通过默认 PI runner 使用 Codex OAuth，请使用 `openai-codex/*`。 @@ -107,7 +116,7 @@ OpenClaw 才会启用该插件。 ``` - OpenClaw **不**提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也同样未提供它。 + OpenClaw **不**公开提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，而当前 Codex 目录也不会公开它。 @@ -127,7 +136,7 @@ OpenClaw 才会启用该插件。 openclaw models auth login --provider openai-codex ``` - 对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调： + 对于无头环境或不适合回调主机的配置，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调： ```bash openclaw models auth login --provider openai-codex --device-code @@ -138,23 +147,23 @@ OpenClaw 才会启用该插件。 openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` - ### 路径摘要 + ### 路由摘要 - | Model ref | 路径 | 认证 | + | 模型引用 | 路由 | 认证 | |-----------|-------|------| | `openai-codex/gpt-5.5` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 | | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | Codex app-server 认证 | - 对于认证/配置文件命令，请继续使用 `openai-codex` provider id。 - `openai-codex/*` 模型前缀也是 Codex OAuth 通过 PI 的显式路径。 + 继续对认证 / 配置文件命令使用 `openai-codex` 提供商 id。 + `openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路由。 它不会选择或自动启用内置的 Codex app-server harness。 @@ -167,28 +176,29 @@ OpenClaw 才会启用该插件。 ``` - 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录——OpenClaw 会在自己的智能体认证存储中管理生成的凭证。 + 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录 —— OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。 ### 状态指示器 - 聊天中的 `/status` 会显示当前会话正在使用哪个嵌入式 harness。 - 默认的 PI harness 显示为 `Runner: pi (embedded)`，不会额外添加单独标记。 - 当选中内置 Codex app-server harness 时，`/status` 会在 `Fast` 后附加非 PI 的 harness id，例如 - `Fast · codex`。现有会话会保留其已记录的 harness id，因此如果你在更改 + 聊天中的 `/status` 会显示当前 + 会话正在使用哪个嵌入式 harness。默认的 PI harness 会显示为 `Runner: pi (embedded)`， + 不会额外添加单独的徽标。当选择内置的 Codex app-server harness 时， + `/status` 会在 `Fast` 旁附加非 PI harness id，例如 + `Fast · codex`。现有会话会保留其记录的 harness id，因此如果你在更改 `embeddedHarness` 后希望 `/status` 反映新的 PI/Codex 选择，请使用 `/new` 或 `/reset`。 ### 上下文窗口上限 - OpenClaw 将模型元数据与运行时上下文上限视为两个独立的值。 + OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。 对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`： - 原生 `contextWindow`：`1000000` - 默认运行时 `contextTokens` 上限：`272000` - 在实践中，这个更小的默认上限通常具有更好的延迟和质量特性。你可以用 `contextTokens` 覆盖它： + 实践中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它： ```json5 { @@ -203,27 +213,34 @@ OpenClaw 才会启用该插件。 ``` - 使用 `contextWindow` 来声明模型原生元数据。使用 `contextTokens` 来限制运行时上下文预算。 + 使用 `contextWindow` 声明模型原生元数据。使用 `contextTokens` 限制运行时上下文预算。 + ### 目录恢复 + + 当存在时，OpenClaw 会对 `gpt-5.5` 使用上游 Codex 目录元数据。 + 如果实时 Codex 发现结果在账户已认证的情况下遗漏了 `openai-codex/gpt-5.5` 这一行， + OpenClaw 会合成该 OAuth 模型行，以便 cron、子智能体和已配置默认模型的运行 + 不会因 `Unknown model` 而失败。 + ## 图像生成 内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。 -它同时支持通过 OpenAI API 密钥进行图像生成，以及通过 Codex OAuth -使用同一个 `openai/gpt-image-2` 模型引用进行图像生成。 +它通过同一个 `openai/gpt-image-2` 模型引用，同时支持基于 OpenAI API 密钥的图像生成 +和基于 Codex OAuth 的图像生成。 | 能力 | OpenAI API 密钥 | Codex OAuth | | ------------------------- | ---------------------------------- | ------------------------------------ | -| Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` | +| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` | | 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 | | 传输 | OpenAI Images API | Codex Responses 后端 | -| 每次请求最大图像数 | 4 | 4 | -| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） | +| 每次请求的最大图像数 | 4 | 4 | +| 编辑模式 | 已启用（最多 5 张参考图） | 已启用（最多 5 张参考图） | | 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 | -| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射到受支持尺寸 | +| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API | 在安全的情况下映射到受支持的尺寸 | ```json5 { @@ -236,27 +253,27 @@ OpenClaw 才会启用该插件。 ``` -有关共享工具参数、提供商选择和故障切换行为，请参见 [Image Generation](/zh-CN/tools/image-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。 -`gpt-image-2` 是 OpenAI 文本生成图像和图像编辑的默认模型。 -`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流 -应使用 `openai/gpt-image-2`。 +`gpt-image-2` 是 OpenAI 文生图生成和图像编辑的默认模型。 +`gpt-image-1` 仍可作为显式模型覆盖继续使用，但新的 +OpenAI 图像工作流应使用 `openai/gpt-image-2`。 -对于 Codex OAuth 安装，请保持使用相同的 `openai/gpt-image-2` 引用。 -当已配置 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该已存储的 OAuth -访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 -`OPENAI_API_KEY`，也不会为该请求静默回退到 API 密钥。 -当你希望改用直接 OpenAI Images API 路径时，请使用 API 密钥、 -自定义 base URL 或 Azure endpoint 显式配置 `models.providers.openai`。 -如果该自定义图像端点位于受信任的 LAN/私有地址上，还需要设置 -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若未显式启用此项， -OpenClaw 会继续阻止私有/内部的 OpenAI 兼容图像端点。 +对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。当配置了 +`openai-codex` OAuth 配置文件时，OpenClaw 会解析该已存储的 OAuth +访问令牌，并通过 Codex Responses 后端发送图像请求。对于该请求，它不会先尝试 +`OPENAI_API_KEY`，也不会静默回退到 API 密钥。 +当你想改用直接 OpenAI Images API 路由时，请显式配置 +`models.providers.openai`，并提供 API 密钥、自定义 base URL 或 Azure 端点。 +如果该自定义图像端点位于受信任的局域网 / 私有地址上，还需同时设置 +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若未显式选择加入， +OpenClaw 会继续阻止访问私有 / 内部的 OpenAI 兼容图像端点。 生成： ``` -/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精致的发布海报" size=3840x2160 count=1 +/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精美的发布海报" size=3840x2160 count=1 ``` 编辑： @@ -272,10 +289,10 @@ OpenClaw 会继续阻止私有/内部的 OpenAI 兼容图像端点。 | 能力 | 值 | | ---------------- | --------------------------------------------------------------------------------- | | 默认模型 | `openai/sora-2` | -| 模式 | 文本生成视频、图像生成视频、单视频编辑 | -| 参考输入 | 1 张图像或 1 个视频 | +| 模式 | 文生视频、图生视频、单视频编辑 | +| 参考输入 | 1 张图片或 1 个视频 | | 尺寸覆盖 | 支持 | -| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 | +| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 | ```json5 { @@ -288,20 +305,20 @@ OpenClaw 会继续阻止私有/内部的 OpenAI 兼容图像端点。 ``` -有关共享工具参数、提供商选择和故障切换行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。 ## GPT-5 提示词贡献 -OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.4`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会收到相同的叠加层。较旧的 GPT-4.x 模型则不会。 +OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.4`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会接收相同的覆盖层。较旧的 GPT-4.x 模型则不会。 -内置的原生 Codex harness 通过 Codex app-server developer instructions 使用相同的 GPT-5 行为和心跳叠加层，因此，即使 Codex 接管了其余的 harness 提示词，强制通过 `embeddedHarness.runtime: "codex"` 运行的 `openai/gpt-5.x` 会话仍会保留相同的持续跟进和主动心跳指导。 +内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳覆盖层，因此即使 Codex 接管了 harness 提示词的其余部分，强制通过 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.x` 会话仍会保留相同的后续执行和主动心跳指引。 -这个 GPT-5 贡献增加了一个带标签的行为约定，用于规范 persona 持续性、执行安全、工具纪律、输出形态、完成检查和验证。特定于渠道的回复行为和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好的交互风格层则是独立的，并且可配置。 +GPT-5 贡献添加了一个带标签的行为契约，用于定义人设持久性、执行安全、工具纪律、输出形态、完成检查和验证。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指引始终启用。友好交互风格层是独立的，并且可配置。 | 值 | 效果 | | ---------------------- | ------------------------------------------- | -| `"friendly"`（默认） | 启用友好的交互风格层 | +| `"friendly"`（默认） | 启用友好交互风格层 | | `"on"` | `"friendly"` 的别名 | | `"off"` | 仅禁用友好风格层 | @@ -327,14 +344,14 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提 -在运行时，这些值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 +运行时对值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 -当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 配置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。 +当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。 -## 语音与语音识别 +## 语音和语音识别 @@ -343,14 +360,14 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | - | 声音 | `messages.tts.providers.openai.voice` | `coral` | - | 语速 | `messages.tts.providers.openai.speed` | （未设置） | + | 语音 | `messages.tts.providers.openai.voice` | `coral` | + | 速度 | `messages.tts.providers.openai.speed` | （未设置） | | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） | | 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` | | API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` | | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | - 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用声音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 + 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 ```json5 { @@ -365,23 +382,23 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提 ``` - 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 base URL，而不会影响聊天 API endpoint。 + 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS base URL，而不会影响聊天 API 端点。 内置的 `openai` 插件通过 - OpenClaw 的媒体理解转录表面注册了批量语音转文本功能。 + OpenClaw 的媒体理解转写表面注册了批量语音转文本功能。 - 默认模型：`gpt-4o-transcribe` - - Endpoint：OpenAI REST `/v1/audio/transcriptions` + - 端点：OpenAI REST `/v1/audio/transcriptions` - 输入路径：multipart 音频文件上传 - - 在 OpenClaw 中，只要入站音频转录使用 - `tools.media.audio`，就支持该功能，包括 Discord 语音频道片段和渠道 + - 在 OpenClaw 中，凡是入站音频转写使用 + `tools.media.audio` 的地方都受支持，包括 Discord 语音频道片段和渠道 音频附件 - 要强制对入站音频转录使用 OpenAI： + 要强制将 OpenAI 用于入站音频转写： ```json5 { @@ -401,13 +418,13 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提 } ``` - 当共享音频媒体配置或单次转录请求提供了语言和提示信息时， - OpenClaw 会将它们转发给 OpenAI。 + 当共享音频媒体配置或每次调用的转写请求提供了 + 语言和提示词提示时，它们会被转发给 OpenAI。 - - 内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。 + + 内置的 `openai` 插件为 Voice Call 插件注册了实时转写功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| @@ -419,7 +436,7 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提 | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | - 使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。 + 使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，音频格式为 G.711 u-law（`g711_ulaw` / `audio/pcmu`）。这个流式提供商用于 Voice Call 的实时转写路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转写路径。 @@ -430,8 +447,8 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | - | 声音 | `...openai.voice` | `alloy` | - | Temperature | `...openai.temperature` | `0.8` | + | 语音 | `...openai.voice` | `alloy` | + | 温度 | `...openai.temperature` | `0.8` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | | 静音时长 | `...openai.silenceDurationMs` | `500` | | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | @@ -443,26 +460,30 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提 -## Azure OpenAI endpoint +## Azure OpenAI 端点 -内置的 `openai` 提供商可以通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 中的 Azure 主机名，并自动切换到 Azure 的请求格式。 +内置的 `openai` 提供商可以通过覆盖 base URL， +将图像生成请求发送到 Azure OpenAI 资源。在图像生成路径上，OpenClaw +会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到 +Azure 的请求格式。 实时语音使用单独的配置路径 （`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`）， -不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置请参见 -[语音与语音识别](#voice-and-speech) 下 **实时语音** 折叠面板。 +不会受到 `models.providers.openai.baseUrl` 的影响。相关 Azure +设置请参阅 [Voice and speech](#voice-and-speech) 下的 **Realtime +voice** 折叠面板。 在以下情况下使用 Azure OpenAI： - 你已经拥有 Azure OpenAI 订阅、配额或企业协议 - 你需要 Azure 提供的区域数据驻留或合规控制 -- 你希望将流量保留在现有的 Azure tenancy 内部 +- 你希望将流量保留在现有的 Azure 租户内 ### 配置 -对于通过内置 `openai` 提供商进行的 Azure 图像生成，请将 +要通过内置 `openai` 提供商使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： @@ -479,97 +500,99 @@ Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： } ``` -OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成路径： +OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成 +路由： - `*.openai.azure.com` - `*.services.ai.azure.com` - `*.cognitiveservices.azure.com` -对于发送到已识别 Azure 主机的图像生成请求，OpenClaw 会： +对于发往已识别 Azure 主机的图像生成请求，OpenClaw 会： -- 发送 `api-key` header，而不是 `Authorization: Bearer` -- 使用部署作用域路径（`/openai/deployments/{deployment}/...`） -- 为每个请求附加 `?api-version=...` +- 发送 `api-key` 请求头，而不是 `Authorization: Bearer` +- 使用基于 deployment 的路径（`/openai/deployments/{deployment}/...`） +- 在每个请求后附加 `?api-version=...` -其他 base URL（公共 OpenAI、OpenAI 兼容代理）则继续使用标准的 +其他 base URL（公开 OpenAI、OpenAI 兼容代理）将继续使用标准 OpenAI 图像请求格式。 -`openai` 提供商图像生成路径的 Azure 路由功能需要 +`openai` 提供商图像生成路径的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。更早的版本会将任何自定义 -`openai.baseUrl` 都视为公共 OpenAI endpoint，并在对接 Azure -图像部署时失败。 +`openai.baseUrl` 都视为公开 OpenAI 端点，因此在针对 Azure +图像 deployment 时会失败。 ### API 版本 -设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的 -Azure 预览版或正式版版本： +设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本： ```bash export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` -如果未设置该变量，默认值为 `2024-12-01-preview`。 +当该变量未设置时，默认值为 `2024-12-01-preview`。 -### 模型名称就是部署名称 +### 模型名称即 deployment 名称 -Azure OpenAI 将模型绑定到部署。对于通过内置 `openai` 提供商路由的 -Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure portal 中配置的 -**Azure 部署名称**，而不是公共 OpenAI 模型 id。 +Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提供商 +路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段 +必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是 +公开的 OpenAI 模型 id。 -如果你创建了一个名为 `gpt-image-2-prod` 的部署，用于提供 `gpt-image-2`： +如果你创建了一个名为 `gpt-image-2-prod`、提供 `gpt-image-2` 的 deployment： ``` /tool image_generate model=openai/gpt-image-2-prod prompt="一张简洁的海报" size=1024x1024 count=1 ``` -同样的部署名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。 +同样的 deployment 名称规则也适用于通过内置 `openai` 提供商 +路由的图像生成调用。 ### 区域可用性 Azure 图像生成目前仅在部分区域可用 （例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、 -`uaenorth`）。在创建部署之前，请先查看 Microsoft 当前的区域列表， -并确认你的区域提供所需的具体模型。 +`uaenorth`）。在创建 deployment 之前，请先查看 Microsoft 的最新区域列表， +并确认目标模型在你的区域中可用。 ### 参数差异 -Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。 -Azure 可能会拒绝公共 OpenAI 允许的选项（例如在 `gpt-image-2` 上的某些 -`background` 值），或者仅在特定模型版本上提供这些选项。 -这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请检查 Azure portal 中你的具体部署和 API 版本所支持的参数集。 +Azure OpenAI 和公开 OpenAI 并不总是接受相同的图像参数。 +Azure 可能会拒绝公开 OpenAI 允许的某些选项（例如 `gpt-image-2` 上的某些 +`background` 值），或仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型， +而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 +Azure 门户中检查你的具体 deployment 和 API 版本所支持的参数集。 Azure OpenAI 使用原生传输和兼容行为，但不会接收 -OpenClaw 的隐藏 attribution headers——请参见 -[高级配置](#advanced-configuration) 下 **原生与 OpenAI 兼容路径** -折叠面板。 +OpenClaw 的隐藏归因标头 —— 请参阅 [Advanced configuration](#advanced-configuration) 下 +**Native vs OpenAI-compatible routes** 折叠面板。 -对于 Azure 上的聊天或 Responses 流量（图像生成之外），请使用 -新手引导流程或专用的 Azure 提供商配置——仅设置 `openai.baseUrl` -并不会自动采用 Azure 的 API/认证格式。另有一个独立的 -`azure-openai-responses/*` 提供商；请参见下方的 -服务端压缩折叠面板。 +对于 Azure 上的聊天或 Responses 流量（不仅限于图像生成），请使用 +新手引导流程或专用的 Azure 提供商配置 —— 单独设置 `openai.baseUrl` +不会自动采用 Azure 的 API / 认证格式。另有单独的 +`azure-openai-responses/*` 提供商；请参阅下方的 +Server-side compaction 折叠面板。 ## 高级配置 - OpenClaw 对 `openai/*` 和 `openai-codex/*` 都默认使用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。 + 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都会优先使用 WebSocket，并在失败时回退到 SSE（`"auto"`）。 在 `"auto"` 模式下，OpenClaw 会： - 在回退到 SSE 之前，重试一次早期 WebSocket 失败 - - 在发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE - - 为重试和重连附加稳定的会话和轮次身份 header - - 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`） + - 失败后，将 WebSocket 标记为降级状态约 60 秒，并在冷却期间使用 SSE + - 为重试和重连附加稳定的会话和轮次身份标头 + - 在不同传输变体之间统一使用量计数器（`input_tokens` / `prompt_tokens`） | 值 | 行为 | |-------|----------| - | `"auto"`（默认） | WebSocket 优先，SSE 回退 | - | `"sse"` | 强制仅使用 SSE | - | `"websocket"` | 强制仅使用 WebSocket | + | `"auto"`（默认） | 优先使用 WebSocket，失败时回退到 SSE | + | `"sse"` | 仅强制使用 SSE | + | `"websocket"` | 仅强制使用 WebSocket | ```json5 { @@ -589,13 +612,13 @@ OpenClaw 的隐藏 attribution headers——请参见 ``` 相关 OpenAI 文档： - - [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket) - - [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses) + - [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) + - [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses) - OpenClaw 默认对 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首轮延迟。 + OpenClaw 默认会为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首轮延迟。 ```json5 // 禁用预热 @@ -617,10 +640,10 @@ OpenClaw 的隐藏 attribution headers——请参见 OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的 Fast 模式开关： - - **聊天/UI：** `/fast status|on|off` + - **聊天 / UI：** `/fast status|on|off` - **配置：** `agents.defaults.models["/"].params.fastMode` - 启用后，OpenClaw 会将 Fast 模式映射为 OpenAI 优先级处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，Fast 模式不会重写 `reasoning` 或 `text.verbosity`。 + 启用后，OpenClaw 会将 Fast 模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，Fast 模式不会重写 `reasoning` 或 `text.verbosity`。 ```json5 { @@ -635,13 +658,13 @@ OpenClaw 的隐藏 attribution headers——请参见 ``` - 会话覆盖的优先级高于配置。在 Sessions UI 中清除会话覆盖后，会话会恢复为配置中的默认值。 + 会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置中的默认值。 - - OpenAI 的 API 通过 `service_tier` 提供优先级处理能力。你可以在 OpenClaw 中按模型进行设置： + + OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置： ```json5 { @@ -658,23 +681,23 @@ OpenClaw 的隐藏 attribution headers——请参见 支持的值：`auto`、`default`、`flex`、`priority`。 - `serviceTier` 仅会被转发到原生 OpenAI endpoint（`api.openai.com`）和原生 Codex endpoint（`chatgpt.com/backend-api`）。如果你通过代理路由其中任一提供商，OpenClaw 会保持 `service_tier` 不变。 + `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。 - 对于直接的 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩： + 对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩： - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` - - 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用则为 `80000`） + - 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用，则为 `80000`） - 这适用于内置的 Pi harness 路径，也适用于嵌入式运行所使用的 OpenAI 提供商 hook。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。 + 这会应用于内置 Pi harness 路径，以及嵌入式运行所使用的 OpenAI provider hooks。原生 Codex app-server harness 通过 Codex 管理自己的上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。 - 适用于 Azure OpenAI Responses 这类兼容 endpoint： + 对 Azure OpenAI Responses 这样的兼容端点很有用： ```json5 { @@ -726,13 +749,13 @@ OpenClaw 的隐藏 attribution headers——请参见 - `responsesServerCompaction` 仅控制 `context_management` 的注入。直接的 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 + `responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 - - 对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行约定： + + 对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约： ```json5 { @@ -745,10 +768,10 @@ OpenClaw 的隐藏 attribution headers——请参见 ``` 使用 `strict-agentic` 时，OpenClaw 会： - - 当有可用工具操作时，不再将“仅规划”的轮次视为成功进展 - - 通过立即执行引导来重试该轮次 - - 对于实质性工作，自动启用 `update_plan` - - 如果模型持续只规划而不执行，则明确显示阻塞状态 + - 当工具操作可用时，不再将仅计划的轮次视为成功进展 + - 使用“立即行动”的引导重试该轮次 + - 对于重要工作自动启用 `update_plan` + - 如果模型持续只做计划而不行动，则显式显示阻塞状态 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧模型系列保持默认行为。 @@ -756,21 +779,21 @@ OpenClaw 的隐藏 attribution headers——请参见 - - OpenClaw 会将直接 OpenAI、Codex 和 Azure OpenAI endpoint 与通用的 OpenAI 兼容 `/v1` 代理区分对待： + + OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理方式，与通用 OpenAI 兼容 `/v1` 代理不同： - **原生路径**（`openai/*`、Azure OpenAI）： + **原生路由**（`openai/*`、Azure OpenAI）： - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }` - - 对于拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用的 reasoning + - 对拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用的 reasoning - 默认将工具 schema 设为严格模式 - - 仅在已验证的原生主机上附加隐藏 attribution headers - - 保留 OpenAI 专有的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示） + - 仅在已验证的原生主机上附加隐藏归因标头 + - 保留 OpenAI 专属请求整形（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示） - **代理/兼容路径：** + **代理 / 兼容路由：** - 使用更宽松的兼容行为 - - 不强制严格工具 schema，也不附加仅限原生的 headers + - 不会强制严格工具 schema 或原生专属标头 - Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏的 attribution headers。 + Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因标头。 @@ -779,13 +802,13 @@ OpenClaw 的隐藏 attribution headers——请参见 - 选择提供商、模型引用和故障切换行为。 + 选择提供商、模型引用和故障转移行为。 - 共享的图像工具参数和提供商选择。 + 共享图像工具参数和提供商选择。 - 共享的视频工具参数和提供商选择。 + 共享视频工具参数和提供商选择。 认证细节和凭证复用规则。 diff --git a/docs/zh-CN/tools/image-generation.md b/docs/zh-CN/tools/image-generation.md index 461612a0f..917aa00e4 100644 --- a/docs/zh-CN/tools/image-generation.md +++ b/docs/zh-CN/tools/image-generation.md @@ -2,27 +2,27 @@ read_when: - 通过智能体生成图像 - 配置图像生成提供商和模型 - - 理解 `image_generate` 工具参数 -summary: 使用已配置的提供商生成和编辑图像（OpenAI、OpenAI Codex OAuth、Google Gemini、OpenRouter、fal、MiniMax、ComfyUI、Vydra、xAI） + - 了解 `image_generate` 工具参数 +summary: 使用已配置的提供商（OpenAI、OpenAI Codex OAuth、Google Gemini、OpenRouter、fal、MiniMax、ComfyUI、Vydra、xAI）生成和编辑图像 title: 图像生成 x-i18n: - generated_at: "2026-04-24T03:44:00Z" + generated_at: "2026-04-24T16:58:28Z" model: gpt-5.4 provider: openai - source_hash: 51ffc32165c5e25925460f95f3a6e674a004e6640b7a4b9e88d025eb40943b4b + source_hash: 3a8e721918f5d610163894f33fbfd39ade6694be8bf4ad47c7c691d780d49637 source_path: tools/image-generation.md workflow: 15 --- -`image_generate` 工具允许智能体使用你已配置的提供商来创建和编辑图像。生成的图像会作为媒体附件自动随智能体回复一起发送。 +`image_generate` 工具允许智能体使用你已配置的提供商创建和编辑图像。生成的图像会作为媒体附件自动包含在智能体的回复中。 -只有在至少有一个图像生成提供商可用时，这个工具才会出现。如果你在智能体工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API key，或使用 OpenAI Codex OAuth 登录。 +只有在至少有一个图像生成提供商可用时，该工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API 密钥，或使用 OpenAI Codex OAuth 登录。 ## 快速开始 -1. 为至少一个提供商设置 API key（例如 `OPENAI_API_KEY`、`GEMINI_API_KEY` 或 `OPENROUTER_API_KEY`），或使用 OpenAI Codex OAuth 登录。 +1. 为至少一个提供商设置 API 密钥（例如 `OPENAI_API_KEY`、`GEMINI_API_KEY` 或 `OPENROUTER_API_KEY`），或使用 OpenAI Codex OAuth 登录。 2. 可选：设置你偏好的模型： ```json5 @@ -38,21 +38,33 @@ x-i18n: ``` Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 -`openai-codex` OAuth profile 时，OpenClaw 会通过该 OAuth profile 路由图像请求， -而不是优先尝试 `OPENAI_API_KEY`。显式的自定义 `models.providers.openai` -图像配置，例如 API key 或自定义/Azure `baseUrl`，会重新切回直接使用 OpenAI Images API 的路径。 -对于 LocalAI 这类 OpenAI 兼容的 LAN 端点，请保留自定义 +`openai-codex` OAuth 配置文件时，OpenClaw 会通过该相同的 OAuth 配置文件路由图像请求，而不是先尝试 `OPENAI_API_KEY`。 +显式自定义 `models.providers.openai` 图像配置（例如 API 密钥或 +自定义 / Azure 基础 URL）会切换回直接 OpenAI Images API 路由。 +对于 LocalAI 之类兼容 OpenAI 的 LAN 端点，请保留自定义 `models.providers.openai.baseUrl`，并显式启用 -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；默认情况下，私有/内部 -图像端点仍然会被阻止。 +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；默认情况下，私有 / 内部图像端点仍会被阻止。 -3. 向智能体提出请求：_“生成一张友好的机器人吉祥物图片。”_ +3. 向智能体提问：_“生成一张友好机器人吉祥物的图片。”_ -智能体会自动调用 `image_generate`。不需要工具允许列表——只要有可用提供商，它默认就是启用的。 +智能体会自动调用 `image_generate`。不需要工具允许列表——当提供商可用时，它默认启用。 + +## 常见路由 + +| 目标 | 模型引用 | 认证 | +| ---------------------------------------------------- | -------------------------------------------------- | ------------------------------------ | +| 使用 API 计费的 OpenAI 图像生成 | `openai/gpt-image-2` | `OPENAI_API_KEY` | +| 使用 Codex 订阅认证的 OpenAI 图像生成 | `openai/gpt-image-2` | OpenAI Codex OAuth | +| OpenRouter 图像生成 | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY` | +| Google Gemini 图像生成 | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | + +同一个 `image_generate` 工具同时处理文生图和参考图像编辑。 +对单张参考图像使用 `image`，对多张参考图像使用 `images`。 +如 `quality`、`outputFormat` 以及 OpenAI 专属的 `background` 之类由提供商支持的输出提示，会在可用时透传；当提供商不支持时，会在结果中报告为已忽略。 ## 支持的提供商 -| 提供商 | 默认模型 | 编辑支持 | 凭证 | +| 提供商 | 默认模型 | 编辑支持 | 认证 | | ---------- | --------------------------------------- | ---------------------------------- | ----------------------------------------------------- | | OpenAI | `gpt-image-2` | 是（最多 4 张图像） | `OPENAI_API_KEY` 或 OpenAI Codex OAuth | | OpenRouter | `google/gemini-3.1-flash-image-preview` | 是（最多 5 张输入图像） | `OPENROUTER_API_KEY` | @@ -63,24 +75,24 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 | Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` | | xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` | -使用 `action: "list"` 可在运行时检查可用提供商和模型： +使用 `action: "list"` 可在运行时检查可用的提供商和模型： -```text +``` /tool image_generate action=list ``` ## 工具参数 -图像生成提示。`action: "generate"` 时必填。 +图像生成提示词。对于 `action: "generate"` 为必填。 -使用 `"list"` 在运行时检查可用提供商和模型。 +使用 `"list"` 在运行时检查可用的提供商和模型。 -提供商/模型覆盖，例如 `openai/gpt-image-2`。 +提供商 / 模型覆盖，例如 `openai/gpt-image-2`。 @@ -104,11 +116,11 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 -当提供商支持时使用的质量提示。 +当提供商支持时的质量提示。 -当提供商支持时使用的输出格式提示。 +当提供商支持时的输出格式提示。 @@ -116,7 +128,7 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 -可选的提供商请求超时，单位为毫秒。 +可选的提供商请求超时时间（毫秒）。 @@ -124,12 +136,12 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 -仅限 OpenAI 的提示：`background`、`moderation`、`outputCompression` 和 `user`。 +仅适用于 OpenAI 的提示：`background`、`moderation`、`outputCompression` 和 `user`。 -并非所有提供商都支持所有参数。当某个回退提供商支持接近的几何选项而非精确请求值时，OpenClaw 会在提交前重新映射到最接近的受支持尺寸、宽高比或分辨率。像 `quality` 或 `outputFormat` 这样不受支持的输出提示，对于未声明支持的提供商会被丢弃，并在工具结果中报告。 +并非所有提供商都支持所有参数。当回退提供商支持接近的几何选项而非精确请求值时，OpenClaw 会在提交前重新映射到最接近的受支持尺寸、宽高比或分辨率。对于未声明支持的提供商，不受支持的输出提示（如 `quality` 或 `outputFormat`）会被丢弃，并在工具结果中报告。 -工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值反映的是实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。 +工具结果会报告已应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。 ## 配置 @@ -159,26 +171,25 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 1. 工具调用中的 **`model` 参数**（如果智能体指定了） 2. 配置中的 **`imageGenerationModel.primary`** 3. 按顺序使用 **`imageGenerationModel.fallbacks`** -4. **自动检测**——仅使用有凭证支持的提供商默认值： - - 先尝试当前默认提供商 - - 再按提供商 id 顺序尝试其余已注册的图像生成提供商 +4. **自动检测**——仅使用有认证支持的提供商默认值： + - 先使用当前默认提供商 + - 再按提供商 ID 顺序使用其余已注册的图像生成提供商 -如果某个提供商失败（凭证错误、速率限制等），系统会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。 +如果某个提供商失败（认证错误、速率限制等），会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。 -说明： +注意： -- 自动检测具备凭证感知能力。只有当 OpenClaw 实际能够为某个提供商完成认证时，该提供商默认值才会进入候选列表。 -- 默认启用自动检测。如果你希望图像生成仅使用显式的 `model`、`primary` 和 `fallbacks` +- 自动检测具备认证感知能力。只有当 OpenClaw 实际能够对某个提供商进行认证时，该提供商默认值才会进入候选列表。 +- 默认启用自动检测。如果你希望图像生成只使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。 -- 使用 `action: "list"` 可检查当前已注册的提供商、它们的 - 默认模型以及凭证环境变量提示。 +- 使用 `action: "list"` 可检查当前已注册的提供商、它们的默认模型以及认证环境变量提示。 ### 图像编辑 OpenAI、OpenRouter、Google、fal、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。传入参考图像路径或 URL： -```text +``` "Generate a watercolor version of this photo" + image: "/path/to/photo.jpg" ``` @@ -186,7 +197,7 @@ OpenAI、OpenRouter、Google 和 xAI 通过 `images` 参数最多支持 5 张参 ### OpenRouter 图像模型 -OpenRouter 图像生成使用相同的 `OPENROUTER_API_KEY`，并通过 OpenRouter 的聊天补全图像 API 路由。使用 `openrouter/` 前缀选择 OpenRouter 图像模型： +OpenRouter 图像生成使用同一个 `OPENROUTER_API_KEY`，并通过 OpenRouter 的 chat completions 图像 API 路由。使用 `openrouter/` 前缀选择 OpenRouter 图像模型： ```json5 { @@ -200,27 +211,24 @@ OpenRouter 图像生成使用相同的 `OPENROUTER_API_KEY`，并通过 OpenRout } ``` -OpenClaw 会将 `prompt`、`count`、参考图像以及与 Gemini 兼容的 `aspectRatio` / `resolution` 提示转发给 OpenRouter。当前内置的 OpenRouter 图像模型快捷项包括 `google/gemini-3.1-flash-image-preview`、`google/gemini-3-pro-image-preview` 和 `openai/gpt-5.4-image-2`；使用 `action: "list"` 查看你已配置插件暴露了哪些内容。 +OpenClaw 会将 `prompt`、`count`、参考图像以及与 Gemini 兼容的 `aspectRatio` / `resolution` 提示转发到 OpenRouter。当前内置的 OpenRouter 图像模型快捷项包括 `google/gemini-3.1-flash-image-preview`、`google/gemini-3-pro-image-preview` 和 `openai/gpt-5.4-image-2`；使用 `action: "list"` 可查看你配置的插件公开了哪些模型。 ### OpenAI `gpt-image-2` -OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果配置了 -`openai-codex` OAuth profile，OpenClaw 会复用与 Codex 订阅聊天模型相同的 OAuth -profile，并通过 Codex Responses 后端发送图像请求；它不会在该请求中静默回退到 -`OPENAI_API_KEY`。如果你想强制使用直接的 OpenAI Images API 路由， -请显式配置 `models.providers.openai`，并提供 API key、自定义 `baseUrl` -或 Azure 端点。旧版 -`openai/gpt-image-1` 模型仍然可以显式选择，但新的 OpenAI +OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果已配置 +`openai-codex` OAuth 配置文件，OpenClaw 会复用 Codex 订阅聊天模型所使用的相同 OAuth 配置文件，并通过 Codex Responses 后端发送图像请求； +它不会在该请求中静默回退到 `OPENAI_API_KEY`。若要强制使用直接 OpenAI Images API 路由， +请显式配置 `models.providers.openai`，例如设置 API 密钥、自定义基础 URL +或 Azure 端点。较旧的 +`openai/gpt-image-1` 模型仍可显式选择，但新的 OpenAI 图像生成和图像编辑请求应使用 `gpt-image-2`。 -`gpt-image-2` 同时支持文生图生成和通过同一个 `image_generate` 工具进行参考图像 -编辑。OpenClaw 会将 `prompt`、 -`count`、`size`、`quality`、`outputFormat` 和参考图像转发给 OpenAI。 -OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下， -OpenClaw 会将它们映射到受支持的 `size`，否则工具会将其报告为 -被忽略的覆盖项。 +`gpt-image-2` 通过同一个 `image_generate` 工具同时支持文生图和参考图像编辑。OpenClaw 会将 `prompt`、 +`count`、`size`、`quality`、`outputFormat` 以及参考图像转发给 OpenAI。 +OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；如果可能， +OpenClaw 会将它们映射为受支持的 `size`，否则工具会将其报告为已忽略的覆盖项。 -OpenAI 特定选项位于 `openai` 对象下： +OpenAI 专属选项位于 `openai` 对象下： ```json { @@ -237,67 +245,68 @@ OpenAI 特定选项位于 `openai` 对象下： `openai.background` 接受 `transparent`、`opaque` 或 `auto`；透明 输出要求 `outputFormat` 为 `png` 或 `webp`。`openai.outputCompression` -适用于 JPEG/WebP 输出。 +适用于 JPEG / WebP 输出。 生成一张 4K 横向图像： -```text +``` /tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1 ``` 生成两张方形图像： -```text +``` /tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2 ``` 编辑一张本地参考图像： -```text +``` /tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536 ``` 使用多张参考图像进行编辑： -```text +``` /tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 ``` -如果要通过 Azure OpenAI 部署而不是 -`api.openai.com` 路由 OpenAI 图像生成，请参见 OpenAI 提供商文档中的 [Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。 +若要通过 Azure OpenAI 部署而不是 +`api.openai.com` 路由 OpenAI 图像生成，请参阅 OpenAI 提供商文档中的 [Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。 -MiniMax 图像生成可通过两种内置 MiniMax 凭证路径使用： +MiniMax 图像生成可通过两种内置 MiniMax 认证路径使用： -- `minimax/image-01` 用于 API key 设置 -- `minimax-portal/image-01` 用于 OAuth 设置 +- 用于 API 密钥配置的 `minimax/image-01` +- 用于 OAuth 配置的 `minimax-portal/image-01` ## 提供商能力 | 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI | | --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- | -| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（由工作流定义输出） | 是（1 张） | 是（最多 4 张） | -| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） | +| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（工作流定义的输出） | 是（1 张） | 是（最多 4 张） | +| 编辑 / 参考图像 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） | | 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 | | 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 | | 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 | 是（1K/2K） | ### xAI `grok-imagine-image` -内置的 xAI 提供商会对仅提示词请求使用 `/v1/images/generations`， -当存在 `image` 或 `images` 时则使用 `/v1/images/edits`。 +内置 xAI 提供商对仅提示词请求使用 `/v1/images/generations`， +当存在 `image` 或 `images` 时使用 `/v1/images/edits`。 - 模型：`xai/grok-imagine-image`、`xai/grok-imagine-image-pro` - 数量：最多 4 张 -- 参考：一个 `image` 或最多五个 `images` +- 参考图像：一个 `image` 或最多五个 `images` - 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2` - 分辨率：`1K`、`2K` -- 输出：作为由 OpenClaw 管理的图像附件返回 +- 输出：作为 OpenClaw 管理的图像附件返回 -在这些控制项尚未进入共享的跨提供商 `image_generate` 合同之前，OpenClaw 有意不暴露 xAI 原生的 `quality`、`mask`、`user`，或额外的仅原生支持宽高比。 +在这些控制项出现在跨提供商共享的 `image_generate` 合同中之前， +OpenClaw 有意不公开 xAI 原生的 `quality`、`mask`、`user` 或其他仅原生支持的宽高比。 ## 相关内容 -- [工具概览](/zh-CN/tools) — 所有可用的智能体工具 +- [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具 - [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置 - [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置 - [Google (Gemini)](/zh-CN/providers/google) — Gemini 图像提供商设置 @@ -305,5 +314,5 @@ MiniMax 图像生成可通过两种内置 MiniMax 凭证路径使用： - [OpenAI](/zh-CN/providers/openai) — OpenAI Images 提供商设置 - [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置 - [xAI](/zh-CN/providers/xai) — Grok 图像、视频、搜索、代码执行和 TTS 设置 -- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — `imageGenerationModel` 配置 -- [模型](/zh-CN/concepts/models) — 模型配置与故障转移 +- [Configuration Reference](/zh-CN/gateway/config-agents#agent-defaults) — `imageGenerationModel` 配置 +- [Models](/zh-CN/concepts/models) — 模型配置和故障切换 diff --git a/docs/zh-CN/tools/plugin.md b/docs/zh-CN/tools/plugin.md index e058f1038..ca44c2c35 100644 --- a/docs/zh-CN/tools/plugin.md +++ b/docs/zh-CN/tools/plugin.md @@ -7,20 +7,20 @@ sidebarTitle: Install and Configure summary: 安装、配置和管理 OpenClaw 插件 title: 插件 x-i18n: - generated_at: "2026-04-24T16:35:16Z" + generated_at: "2026-04-24T16:58:32Z" model: gpt-5.4 provider: openai - source_hash: d7db42c0c8d7d8b3bddda46a8a42fc19b39b093863b1730b8ca66528a95ecb50 + source_hash: 1f4968e70dc215dc50916f2d180121ce2afbe90e6bb2a85d3fe0bd8d989244fd source_path: tools/plugin.md workflow: 15 --- -插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、技能、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等等。有些插件是 **core**（随 OpenClaw 一起提供），另一些是 **external**（由社区发布到 npm）。 +插件通过新增功能来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起发布），另一些则是**外部**插件（由社区发布到 npm）。 ## 快速开始 - + ```bash openclaw plugins list ``` @@ -28,10 +28,10 @@ x-i18n: ```bash - # 从 npm + # 来自 npm openclaw plugins install @openclaw/voice-call - # 从本地目录或归档文件 + # 来自本地目录或归档文件 openclaw plugins install ./my-plugin openclaw plugins install ./my-plugin.tgz ``` @@ -48,7 +48,7 @@ x-i18n: -如果你更喜欢聊天原生控制，请启用 `commands.plugins: true` 并使用： +如果你更喜欢聊天原生的控制方式，请启用 `commands.plugins: true` 并使用： ```text /plugin install clawhub:@openclaw/voice-call @@ -56,11 +56,11 @@ x-i18n: /plugin enable voice-call ``` -安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:`，或裸包说明符（优先 ClawHub，然后回退到 npm）。 +安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:`，或裸包规范（优先 ClawHub，其次回退到 npm）。 -如果配置无效，安装通常会以关闭失败的方式结束，并提示你运行 `openclaw doctor --fix`。唯一的恢复例外是一个范围很窄的内置插件重装路径，适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 +如果配置无效，安装通常会以安全失败的方式终止，并提示你使用 `openclaw doctor --fix`。唯一的恢复例外是一个较窄的内置插件重装路径，适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 -打包的 OpenClaw 安装不会急切安装每个内置插件的运行时依赖树。当一个由 OpenClaw 拥有的内置插件通过插件配置、旧版渠道配置或默认启用的清单处于活动状态时，启动流程只会在导入该插件之前修复该插件声明的运行时依赖。外部插件和自定义加载路径仍然必须通过 `openclaw plugins install` 安装。 +打包发布的 OpenClaw 安装不会急切安装每个内置插件的全部运行时依赖树。当某个由 OpenClaw 拥有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于活动状态时，启动过程只会在导入该插件前修复该插件声明的运行时依赖。显式禁用仍然优先生效：`plugins.entries..enabled: false`、`plugins.deny`、`plugins.enabled: false` 和 `channels..enabled: false` 会阻止该插件/渠道的自动内置运行时依赖修复。外部插件和自定义加载路径仍然必须通过 `openclaw plugins install` 安装。 ## 插件类型 @@ -69,9 +69,9 @@ OpenClaw 可识别两种插件格式： | 格式 | 工作方式 | 示例 | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | | **Native** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | -| **Bundle** | 兼容 Codex/Claude/Cursor 的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | +| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | -两者都会显示在 `openclaw plugins list` 中。有关 bundle 的详细信息，请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。 +这两种格式都会显示在 `openclaw plugins list` 中。有关 Bundle 的详细信息，请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。 如果你正在编写原生插件，请从 [Building Plugins](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。 @@ -81,14 +81,14 @@ OpenClaw 可识别两种插件格式： | 插件 | 包 | 文档 | | --------------- | ---------------------- | ------------------------------------ | -| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) | -| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) | -| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) | -| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) | -| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) | -| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) | +| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) | +| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) | +| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) | +| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) | +| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) | +| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) | -### Core（随 OpenClaw 一起提供） +### 核心（随 OpenClaw 一起发布） @@ -100,8 +100,8 @@ OpenClaw 可识别两种插件格式： - - `memory-core` — 内置 memory 搜索（默认通过 `plugins.slots.memory`） - - `memory-lancedb` — 按需安装的长期 memory，带自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`） + - `memory-core` — 内置的内存搜索（通过 `plugins.slots.memory` 默认启用） + - `memory-lancedb` — 按需安装的长期记忆，带自动回忆/捕获功能（设置 `plugins.slots.memory = "memory-lancedb"`） @@ -109,8 +109,8 @@ OpenClaw 可识别两种插件格式： - - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换它之前请先禁用） - - `copilot-proxy` — VS Code Copilot Proxy bridge（默认禁用） + - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用） + - `copilot-proxy` — VS Code Copilot Proxy 桥接器（默认禁用） @@ -132,26 +132,26 @@ OpenClaw 可识别两种插件格式： } ``` -| 字段 | 描述 | +| 字段 | 说明 | | ---------------- | --------------------------------------------------------- | -| `enabled` | 主开关（默认：`true`） | -| `allow` | 插件允许列表（可选） | -| `deny` | 插件拒绝列表（可选；拒绝优先） | -| `load.paths` | 额外的插件文件/目录 | -| `slots` | 独占插槽选择器（例如 `memory`、`contextEngine`） | +| `enabled` | 主开关（默认：`true`） | +| `allow` | 插件允许列表（可选） | +| `deny` | 插件拒绝列表（可选；拒绝优先） | +| `load.paths` | 额外的插件文件/目录 | +| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） | | `entries.\` | 每个插件的开关 + 配置 | -配置更改 **需要重启 Gateway 网关**。如果 Gateway 网关在启用了配置监视和进程内重启的情况下运行（默认的 `openclaw gateway` 路径），通常会在配置写入后稍等片刻自动执行该重启。对于原生插件运行时代码或生命周期 hook，不存在受支持的热重载路径；在期待更新后的 `register(api)` 代码、`api.on(...)` hook、工具、服务或提供商/运行时 hook 生效之前，请重启正在服务实时渠道的 Gateway 网关进程。 +配置更改**需要重启 Gateway 网关**。如果 Gateway 网关正在以启用配置监视和进程内重启的方式运行（默认的 `openclaw gateway` 路径），那么在配置写入后不久，这个重启通常会自动执行。对于原生插件运行时代码或生命周期钩子，不存在受支持的热重载路径；在期望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或提供商/运行时钩子生效之前，请重启正在服务实时渠道的 Gateway 网关进程。 -`openclaw plugins list` 是本地 CLI/配置快照。其中显示为 `loaded` 的插件，表示该插件可从该次 CLI 调用所见的配置/文件中被发现并加载。这并不能证明一个已经运行的远程 Gateway 网关子进程已经重启并加载了同样的插件代码。在 VPS/容器部署中，如果使用了包装进程，请向实际的 `openclaw gateway run` 进程发送重启信号，或者对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 +`openclaw plugins list` 是本地 CLI/配置快照。其中某个插件显示为 `loaded`，表示从该次 CLI 调用所看到的配置/文件来看，这个插件可被发现且可被加载。这并不能证明一个已经运行中的远程 Gateway 网关子进程已重启并载入同一份插件代码。在 VPS/容器部署中，如果存在包装进程，请将重启信号发送给实际的 `openclaw gateway run` 进程，或对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 - - - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。 - - **缺失**：配置引用了一个插件 id，但发现流程没有找到它。 - - **无效**：插件存在，但其配置与声明的 schema 不匹配。 + + - **Disabled**：插件存在，但被启用规则关闭。配置会被保留。 + - **Missing**：配置引用了某个插件 id，但设备发现未找到该插件。 + - **Invalid**：插件存在，但其配置与声明的 schema 不匹配。 -## 发现顺序和优先级 +## 设备发现和优先级 OpenClaw 按以下顺序扫描插件（先匹配者优先）： @@ -169,44 +169,37 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： - 随 OpenClaw 一起提供。许多默认启用（模型提供商、语音）。 - 其他则需要显式启用。 + 随 OpenClaw 一起发布。许多插件默认启用（模型提供商、语音）。 + 其他插件则需要显式启用。 ### 启用规则 - `plugins.enabled: false` 会禁用所有插件 -- `plugins.deny` 总是优先于 allow +- `plugins.deny` 始终优先于 allow - `plugins.entries.\.enabled: false` 会禁用该插件 -- 来自工作区的插件 **默认禁用**（必须显式启用） +- 来自工作区的插件**默认禁用**（必须显式启用） - 内置插件遵循内建的默认启用集合，除非被覆盖 -- 独占插槽可以强制启用为该插槽选定的插件 -- 某些选择加入的内置插件会在配置命名了某个插件拥有的表面时自动启用，例如提供商模型引用、渠道配置或 harness 运行时 +- 独占槽位可以为该槽位强制启用所选插件 +- 某些内置的选择加入型插件会在配置命名了某个由插件拥有的表面时自动启用，例如提供商模型引用、渠道配置或 harness 运行时 - OpenAI 系列的 Codex 路由保持独立的插件边界： `openai-codex/*` 属于 OpenAI 插件，而内置的 Codex app-server 插件则通过 `embeddedHarness.runtime: "codex"` 或旧版 `codex/*` 模型引用来选择 -## 运行时 hook 故障排除 +## 运行时钩子故障排除 -如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或 hook 没有在实时聊天流量中运行，请先检查以下内容： +如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子没有在实时聊天流量中运行，请先检查以下内容： -- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动的 - Gateway 网关 URL、profile、配置路径和进程就是你正在编辑的那些。 -- 在插件安装/配置/代码更改后，重启正在运行的 Gateway 网关。在包装容器中， - PID 1 可能只是一个 supervisor；请重启或向子进程 - `openclaw gateway run` 发送信号。 -- 使用 `openclaw plugins inspect --json` 确认 hook 注册和 - 诊断信息。像 `llm_input`、 - `llm_output` 和 `agent_end` 这样的非内置会话 hook，需要 +- 运行 `openclaw gateway status --deep --require-rpc`，并确认当前活动的 Gateway 网关 URL、profile、配置路径和进程，就是你正在编辑的那些。 +- 在插件安装/配置/代码变更后重启实时 Gateway 网关。在包装容器中，PID 1 可能只是一个 supervisor；请重启或向子进程 `openclaw gateway run` 发送信号。 +- 使用 `openclaw plugins inspect --json` 确认钩子注册和诊断信息。像 `llm_input`、`llm_output` 和 `agent_end` 这类非内置的会话钩子，需要 `plugins.entries..hooks.allowConversationAccess=true`。 -- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只会在一次模型尝试生成 assistant 输出之后运行。 -- 如需证明实际生效的会话模型，请使用 `openclaw sessions` 或 - Gateway 网关的会话/状态表面；调试提供商 payload 时，请使用 - `--raw-stream --raw-stream-path ` 启动 Gateway 网关。 +- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 仅会在某次模型尝试产生 assistant 输出之后运行。 +- 若要证明会话实际使用的模型，请使用 `openclaw sessions` 或 Gateway 网关的会话/状态表面；在调试提供商负载时，请使用 `--raw-stream --raw-stream-path ` 启动 Gateway 网关。 -## 插件 slots（独占类别） +## 插件槽位（独占类别） 某些类别是独占的（一次只能激活一个）： @@ -214,39 +207,39 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： { plugins: { slots: { - memory: "memory-core", // 或使用 "none" 来禁用 - contextEngine: "legacy", // 或一个插件 id + memory: "memory-core", // 或 "none" 以禁用 + contextEngine: "legacy", // 或某个插件 id }, }, } ``` -| 插槽 | 控制内容 | 默认值 | +| 槽位 | 控制内容 | 默认值 | | --------------- | --------------------- | ------------------- | -| `memory` | 活动的 memory 插件 | `memory-core` | -| `contextEngine` | 活动的上下文引擎 | `legacy`（内建） | +| `memory` | 当前活动的 Memory 插件 | `memory-core` | +| `contextEngine` | 当前活动的上下文引擎 | `legacy`（内建） | ## CLI 参考 ```bash openclaw plugins list # 精简清单 -openclaw plugins list --enabled # 仅显示已加载的插件 -openclaw plugins list --verbose # 每个插件的详细行 -openclaw plugins list --json # 机器可读的清单 +openclaw plugins list --enabled # 仅显示已加载插件 +openclaw plugins list --verbose # 每个插件的详细信息行 +openclaw plugins list --json # 机器可读清单 openclaw plugins inspect # 深度详情 openclaw plugins inspect --json # 机器可读格式 -openclaw plugins inspect --all # 全量表格 +openclaw plugins inspect --all # 全局表格 openclaw plugins info # inspect 别名 openclaw plugins doctor # 诊断 -openclaw plugins install # 安装（优先 ClawHub，然后 npm） +openclaw plugins install # 安装（优先 ClawHub，其次 npm） openclaw plugins install clawhub: # 仅从 ClawHub 安装 openclaw plugins install --force # 覆盖现有安装 openclaw plugins install # 从本地路径安装 openclaw plugins install -l # 链接（不复制），用于开发 openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # 记录精确解析后的 npm 说明符 +openclaw plugins install --pin # 记录精确解析出的 npm spec openclaw plugins install --dangerously-force-unsafe-install openclaw plugins update # 更新单个插件 openclaw plugins update --dangerously-force-unsafe-install @@ -260,31 +253,31 @@ openclaw plugins enable openclaw plugins disable ``` -内置插件随 OpenClaw 一起提供。许多默认启用（例如内置模型提供商、内置语音提供商，以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable `。 +内置插件随 OpenClaw 一起发布。许多插件默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable `。 -`--force` 会就地覆盖一个已安装的插件或 hook 包。对于已跟踪 npm 插件的常规升级，请使用 `openclaw plugins update `。该选项不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标。 +`--force` 会就地覆盖现有已安装的插件或 hook pack。对于已跟踪的 npm 插件的常规升级，请使用 `openclaw plugins update `。该选项不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标。 -当已经设置了 `plugins.allow` 时，`openclaw plugins install` 会在启用已安装插件之前，将该插件 id 添加到允许列表中，因此重启后安装内容可以立即被加载。 +当已经设置了 `plugins.allow` 时，`openclaw plugins install` 会在启用插件之前，将已安装的插件 id 添加到该允许列表中，因此重启后安装的插件会立即可加载。 -`openclaw plugins update ` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包说明符时，会将包名解析回已跟踪的插件记录，并为后续更新记录新的说明符。传入不带版本的包名时，会将一个精确固定版本的安装切回注册表的默认发布线。如果已安装的 npm 插件已经与解析后的版本以及记录的构件标识一致，OpenClaw 会跳过更新，不会下载、重新安装或重写配置。 +`openclaw plugins update ` 适用于已跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包 spec 时，会将包名解析回已跟踪的插件记录，并记录新的 spec 以供后续更新使用。传入不带版本的包名时，则会将一个精确固定版本的安装切回注册表的默认发布线。如果已安装的 npm 插件已经与解析出的版本和记录的制品标识匹配，OpenClaw 会跳过更新，不会下载、重装或重写配置。 -`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 说明符。 +`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。 -`--dangerously-force-unsafe-install` 是一个用于应对内置危险代码扫描器误报的紧急覆盖开关。它允许插件安装和插件更新在内置 `critical` 级别发现之后继续进行，但仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止。 +`--dangerously-force-unsafe-install` 是一个紧急兜底覆盖项，用于处理内置危险代码扫描器的误报。它允许插件安装和插件更新在遇到内置 `critical` 发现后继续进行，但仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止。 -这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装则改用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。 +这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。 -兼容的 bundle 会参与相同的插件 list/inspect/enable/disable 流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和由清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。 +兼容的 Bundle 会参与相同的插件 list/inspect/enable/disable 流程。当前运行时支持包括 Bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。 -`openclaw plugins inspect ` 还会报告已检测到的 bundle 能力，以及由 bundle 支持的或不支持的 MCP 和 LSP server 条目。 +`openclaw plugins inspect ` 还会报告检测到的 Bundle 能力，以及由 Bundle 支持的或不受支持的 MCP 和 LSP 服务器条目。 -Marketplace 来源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保留在已克隆的 marketplace 仓库内，并且只能使用相对路径来源。 +Marketplace 来源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保持在克隆的 marketplace 仓库内部，并且只能使用相对路径来源。 完整详情请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。 ## 插件 API 概览 -原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。 +原生插件会导出一个入口对象，并暴露 `register(api)`。较旧的插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。 ```typescript export default definePluginEntry({ @@ -304,48 +297,48 @@ export default definePluginEntry({ }); ``` -OpenClaw 会在插件激活期间加载该入口对象并调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件都应将 `register` 视为公共契约。 +OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。对于旧插件，加载器仍会回退到 `activate(api)`，但内置插件和新的外部插件都应将 `register` 视为公共契约。 常见注册方法： | 方法 | 注册内容 | | --------------------------------------- | --------------------------- | -| `registerProvider` | 模型提供商（LLM） | -| `registerChannel` | 聊天渠道 | -| `registerTool` | 智能体工具 | -| `registerHook` / `on(...)` | 生命周期 hook | -| `registerSpeechProvider` | 文本转语音 / STT | +| `registerProvider` | 模型提供商（LLM） | +| `registerChannel` | 聊天渠道 | +| `registerTool` | 智能体工具 | +| `registerHook` / `on(...)` | 生命周期钩子 | +| `registerSpeechProvider` | 文本转语音 / STT | | `registerRealtimeTranscriptionProvider` | 流式 STT | -| `registerRealtimeVoiceProvider` | 双向实时语音 | -| `registerMediaUnderstandingProvider` | 图像/音频分析 | -| `registerImageGenerationProvider` | 图像生成 | -| `registerMusicGenerationProvider` | 音乐生成 | -| `registerVideoGenerationProvider` | 视频生成 | -| `registerWebFetchProvider` | 网页抓取 / 爬取提供商 | -| `registerWebSearchProvider` | 网页搜索 | -| `registerHttpRoute` | HTTP 端点 | -| `registerCommand` / `registerCli` | CLI 命令 | -| `registerContextEngine` | 上下文引擎 | -| `registerService` | 后台服务 | +| `registerRealtimeVoiceProvider` | 双向实时语音 | +| `registerMediaUnderstandingProvider` | 图像/音频分析 | +| `registerImageGenerationProvider` | 图像生成 | +| `registerMusicGenerationProvider` | 音乐生成 | +| `registerVideoGenerationProvider` | 视频生成 | +| `registerWebFetchProvider` | 网页抓取 / 抓取提供商 | +| `registerWebSearchProvider` | 网页搜索 | +| `registerHttpRoute` | HTTP 端点 | +| `registerCommand` / `registerCli` | CLI 命令 | +| `registerContextEngine` | 上下文引擎 | +| `registerService` | 后台服务 | -类型化生命周期 hook 的 hook guard 行为： +类型化生命周期钩子的守卫行为： -- `before_tool_call`：`{ block: true }` 为终止性结果；会跳过更低优先级的处理器。 +- `before_tool_call`：`{ block: true }` 为终结结果；会跳过更低优先级的处理程序。 - `before_tool_call`：`{ block: false }` 为无操作，不会清除更早的阻止。 -- `before_install`：`{ block: true }` 为终止性结果；会跳过更低优先级的处理器。 +- `before_install`：`{ block: true }` 为终结结果；会跳过更低优先级的处理程序。 - `before_install`：`{ block: false }` 为无操作，不会清除更早的阻止。 -- `message_sending`：`{ cancel: true }` 为终止性结果；会跳过更低优先级的处理器。 +- `message_sending`：`{ cancel: true }` 为终结结果；会跳过更低优先级的处理程序。 - `message_sending`：`{ cancel: false }` 为无操作，不会清除更早的取消。 -原生 Codex app-server 会将 bridge 的 Codex 原生工具事件回传到这个 hook 表面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该 bridge 目前还不会重写 Codex 原生工具参数。 +原生 Codex app-server 会将桥接的 Codex 原生工具事件回传到这个 hook 表面中。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 批准流程。该桥接目前还不会重写 Codex 原生工具参数。 有关完整的类型化 hook 行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。 ## 相关内容 - [Building Plugins](/zh-CN/plugins/building-plugins) — 创建你自己的插件 -- [Plugin Bundles](/zh-CN/plugins/bundles) — Codex/Claude/Cursor bundle 兼容性 +- [Plugin Bundles](/zh-CN/plugins/bundles) — 与 Codex/Claude/Cursor 的 Bundle 兼容性 - [Plugin Manifest](/zh-CN/plugins/manifest) — 清单 schema - [Registering Tools](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具 -- [Plugin Internals](/zh-CN/plugins/architecture) — 能力模型和加载流水线 +- [Plugin Internals](/zh-CN/plugins/architecture) — 能力模型和加载管线 - [Community Plugins](/zh-CN/plugins/community) — 第三方列表 diff --git a/docs/zh-CN/tools/subagents.md b/docs/zh-CN/tools/subagents.md index 1c4054a5f..d7dab3065 100644 --- a/docs/zh-CN/tools/subagents.md +++ b/docs/zh-CN/tools/subagents.md @@ -1,24 +1,24 @@ --- read_when: - - 你想通过智能体进行后台 / 并行工作 + - 你希望通过该智能体进行后台/并行工作 - 你正在更改 `sessions_spawn` 或子智能体工具策略 - - 你正在实现或排查线程绑定的子智能体会话问题 -summary: 子智能体：启动隔离的智能体运行，并将结果回传到请求者聊天中 + - 你正在实现或排查线程绑定的子智能体会话 +summary: 子智能体：启动隔离的智能体运行，并将结果回报到请求者聊天中 title: 子智能体 x-i18n: - generated_at: "2026-04-23T23:05:30Z" + generated_at: "2026-04-24T16:58:29Z" model: gpt-5.4 provider: openai - source_hash: 23202b1761e372e547b02183cb68056043aed04b5620db8b222cbfc7e6cd97ab + source_hash: 471b01c1e6bf689f097e67a7037f35348ac7e8a8a334a83778c6593073332274 source_path: tools/subagents.md workflow: 15 --- -子智能体是在现有智能体运行中启动的后台智能体运行。它们会在自己的会话中运行（`agent::subagent:`），并在完成后将结果**回传**到请求者聊天渠道。每次子智能体运行都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。 +子智能体是从现有智能体运行中派生出的后台智能体运行。它们在各自独立的会话中运行（`agent::subagent:`），并在完成后将其结果**回报**到请求者聊天渠道。每次子智能体运行都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。 -## Slash 命令 +## 斜杠命令 -使用 `/subagents` 检查或控制**当前会话**的子智能体运行： +使用 `/subagents` 来查看或控制**当前会话**的子智能体运行： - `/subagents list` - `/subagents kill ` @@ -30,7 +30,7 @@ x-i18n: 线程绑定控制： -这些命令可用于支持持久线程绑定的渠道。请参阅下文的**支持线程的渠道**。 +这些命令适用于支持持久线程绑定的渠道。请参见下方的**支持线程的渠道**。 - `/focus ` - `/unfocus` @@ -38,52 +38,62 @@ x-i18n: - `/session idle ` - `/session max-age ` -`/subagents info` 会显示运行元数据（状态、时间戳、会话 id、transcript 路径、清理信息）。 -如需受限且经过安全过滤的回溯视图，请使用 `sessions_history`；如果你需要原始完整 transcript，请检查磁盘上的 transcript 路径。 +`/subagents info` 会显示运行元数据（状态、时间戳、会话 id、转录路径、清理情况）。 +使用 `sessions_history` 获取有边界且经过安全过滤的回溯视图；当你需要原始完整转录时，请检查磁盘上的转录路径。 ### 启动行为 -`/subagents spawn` 作为用户命令启动一个后台子智能体，而不是内部中继；当运行完成时，它会向请求者聊天发送一条最终完成更新。 +`/subagents spawn` 会以用户命令而非内部转发的方式启动一个后台子智能体，并在运行结束时向请求者聊天回传一次最终完成更新。 - 启动命令是非阻塞的；它会立即返回一个运行 id。 -- 完成时，子智能体会将摘要 / 结果消息回传到请求者聊天渠道。 -- 完成投递基于推送。一旦已启动，就不要为了等待其完成而循环轮询 `/subagents list`、 - `sessions_list` 或 `sessions_history`；仅在调试或干预时按需检查状态。 -- 完成时，OpenClaw 会尽力关闭该子智能体会话打开的已跟踪浏览器标签页 / 进程，然后再继续执行回传清理流程。 -- 对于手动启动，投递具备弹性： - - OpenClaw 会先使用稳定的幂等键尝试直接 `agent` 投递。 - - 如果直接投递失败，则回退到队列路由。 - - 如果队列路由仍不可用，则在最终放弃前，回传会以较短的指数退避策略重试。 +- 完成后，子智能体会向请求者聊天渠道回报一条摘要/结果消息。 +- 完成通知采用推送方式。一旦启动，不要仅仅为了等待其完成而循环轮询 `/subagents list`、`sessions_list` 或 `sessions_history`；只在调试或干预时按需检查状态。 +- 完成时，OpenClaw 会尽最大努力在回报清理流程继续之前，关闭该子智能体会话打开的已跟踪浏览器标签页/进程。 +- 对于手动启动，投递是具备韧性的： + - OpenClaw 会先尝试使用稳定的幂等键进行直接 `agent` 投递。 + - 如果直接投递失败，会回退到队列路由。 + - 如果队列路由仍不可用，则会在最终放弃前通过短时指数退避重试回报。 - 完成投递会保留已解析的请求者路由： - - 在可用时，线程绑定或会话绑定的完成路由优先 - - 如果完成来源仅提供一个渠道，OpenClaw 会从请求者会话的已解析路由（`lastChannel` / `lastTo` / `lastAccountId`）中补全缺失的 target / account，以便直接投递仍然可用 -- 向请求者会话交接的完成内容，是运行时生成的内部上下文（不是用户编写的文本），其中包括： - - `Result`（最新可见的 `assistant` 回复文本；否则为经过清理的最新 tool / toolResult 文本；终态失败运行不会复用捕获到的回复文本） + - 如果可用，线程绑定或会话绑定的完成路由优先生效 + - 如果完成来源只提供渠道，OpenClaw 会从请求者会话已解析的路由（`lastChannel` / `lastTo` / `lastAccountId`）中补齐缺失的目标/账号，以便直接投递仍可工作 +- 向请求者会话交接的完成内容是运行时生成的内部上下文（不是用户撰写的文本），其中包括： + - `Result`（最新可见的 `assistant` 回复文本；否则为已净化的最新 `tool`/`toolResult` 文本；终态失败的运行不会复用已捕获的回复文本） - `Status`（`completed successfully` / `failed` / `timed out` / `unknown`） - - 紧凑的运行时 / token 统计 - - 一条投递说明，告诉请求者智能体要用正常 assistant 语气重写，而不是直接转发原始内部元数据 + - 紧凑的运行时/令牌统计信息 + - 一条投递指令，告知请求者智能体用正常助手语气重写（而不是转发原始内部元数据） - `--model` 和 `--thinking` 会覆盖该次运行的默认值。 -- 使用 `info` / `log` 可在完成后检查详细信息和输出。 -- `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久线程绑定会话，请使用 `sessions_spawn` 并设置 `thread: true` 和 `mode: "session"`。 -- 对于 ACP harness 会话（Codex、Claude Code、Gemini CLI），请使用 `sessions_spawn` 并设置 `runtime: "acp"`，同时参阅 [ACP 智能体](/zh-CN/tools/acp-agents)，尤其是在调试完成投递或智能体到智能体循环时查看 [ACP 投递模型](/zh-CN/tools/acp-agents#delivery-model)。 +- 使用 `info`/`log` 可在完成后查看详细信息和输出。 +- `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久的线程绑定会话，请使用带有 `thread: true` 和 `mode: "session"` 的 `sessions_spawn`。 +- 对于 ACP harness 会话（Codex、Claude Code、Gemini CLI），请使用带有 `runtime: "acp"` 的 `sessions_spawn`，并参见 [ACP Agents](/zh-CN/tools/acp-agents)，尤其是在调试完成通知或智能体到智能体循环时的 [ACP delivery model](/zh-CN/tools/acp-agents#delivery-model)。 主要目标： -- 并行化 “研究 / 长任务 / 慢工具” 类型的工作，而不阻塞主运行。 +- 在不阻塞主运行的情况下并行处理“研究 / 长任务 / 慢工具”工作。 - 默认保持子智能体隔离（会话隔离 + 可选沙箱隔离）。 -- 保持工具接口难以被误用：默认情况下，子智能体**不会**获得会话工具。 -- 支持为编排器模式配置可嵌套深度。 +- 保持工具表面不易被误用：默认情况下，子智能体**不会**获得会话工具。 +- 支持可配置的嵌套深度，以适配编排器模式。 -成本说明：每个子智能体默认都有**自己的**上下文和 token 使用量。对于重型或重复性任务，请为子智能体设置更便宜的模型，并让主智能体继续使用更高质量的模型。你可以通过 `agents.defaults.subagents.model` 或按智能体覆盖来配置。如果子智能体确实需要请求者当前 transcript，智能体可以在该次启动中请求 `context: "fork"`。 +成本说明：默认情况下，每个子智能体都有其**自己的**上下文和令牌消耗。对于重型或重复性任务，请为子智能体设置更便宜的模型，同时让主智能体保留更高质量的模型。你可以通过 `agents.defaults.subagents.model` 或按智能体覆盖项来配置这一点。当子级确实需要请求者当前转录时，智能体可以仅在那一次启动时请求 `context: "fork"`。 + +## 上下文模式 + +原生子智能体默认以隔离方式启动，除非调用方明确要求分叉当前转录。 + +| 模式 | 适用场景 | 行为 | +| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | +| `isolated` | 全新研究、独立实现、慢工具工作，或任何可以在任务文本中简要说明的工作 | 创建一个干净的子级转录。这是默认设置，并能将令牌使用保持在较低水平。 | +| `fork` | 工作依赖于当前对话、之前的工具结果，或请求者转录中已有的细微指令 | 在子级启动前，将请求者转录分支到子级会话中。 | + +谨慎使用 `fork`。它用于对上下文敏感的委派，不是清晰编写任务提示的替代方案。 ## 工具 使用 `sessions_spawn`： -- 启动一个子智能体运行（`deliver: false`，全局 lane：`subagent`） -- 然后执行一次回传步骤，并将回传回复发布到请求者聊天渠道 -- 默认模型：继承调用者，除非你设置了 `agents.defaults.subagents.model`（或按智能体设置 `agents.list[].subagents.model`）；显式的 `sessions_spawn.model` 仍然优先。 -- 默认 thinking：继承调用者，除非你设置了 `agents.defaults.subagents.thinking`（或按智能体设置 `agents.list[].subagents.thinking`）；显式的 `sessions_spawn.thinking` 仍然优先。 +- 启动一个子智能体运行（`deliver: false`，全局队列：`subagent`） +- 然后执行一个回报步骤，并将回报回复发送到请求者聊天渠道 +- 默认模型：继承调用方，除非你设置了 `agents.defaults.subagents.model`（或按智能体设置 `agents.list[].subagents.model`）；显式提供的 `sessions_spawn.model` 仍然优先生效。 +- 默认思考级别：继承调用方，除非你设置了 `agents.defaults.subagents.thinking`（或按智能体设置 `agents.list[].subagents.thinking`）；显式提供的 `sessions_spawn.thinking` 仍然优先生效。 - 默认运行超时：如果省略 `sessions_spawn.runTimeoutSeconds`，OpenClaw 会在已设置时使用 `agents.defaults.subagents.runTimeoutSeconds`；否则回退到 `0`（无超时）。 工具参数： @@ -91,58 +101,58 @@ x-i18n: - `task`（必填） - `label?`（可选） - `agentId?`（可选；如果允许，可在另一个智能体 id 下启动） -- `model?`（可选；覆盖子智能体模型；无效值会被跳过，子智能体将使用默认模型运行，并在工具结果中给出警告） -- `thinking?`（可选；覆盖子智能体运行的 thinking 级别） -- `runTimeoutSeconds?`（已设置时默认取 `agents.defaults.subagents.runTimeoutSeconds`，否则为 `0`；设置后，子智能体运行会在 N 秒后中止） -- `thread?`（默认 `false`；当为 `true` 时，请求为该子智能体会话启用渠道线程绑定） +- `model?`（可选；覆盖子智能体模型；无效值会被跳过，子智能体会在默认模型上运行，并在工具结果中附带警告） +- `thinking?`（可选；覆盖子智能体运行的思考级别） +- `runTimeoutSeconds?`（若已设置，则默认使用 `agents.defaults.subagents.runTimeoutSeconds`，否则为 `0`；设置后，子智能体运行会在 N 秒后中止） +- `thread?`（默认为 `false`；当为 `true` 时，会为该子智能体会话请求渠道线程绑定） - `mode?`（`run|session`） - - 默认是 `run` - - 如果 `thread: true` 且省略 `mode`，默认值会变为 `session` + - 默认为 `run` + - 如果 `thread: true` 且省略 `mode`，默认会变为 `session` - `mode: "session"` 要求 `thread: true` - `cleanup?`（`delete|keep`，默认 `keep`） -- `sandbox?`（`inherit|require`，默认 `inherit`；如果目标子运行时不是沙箱隔离的，`require` 会拒绝启动） -- `context?`（`isolated|fork`，默认 `isolated`；仅限原生子智能体） - - `isolated` 会创建一个干净的子 transcript，并且是默认值。 - - `fork` 会将请求者当前 transcript 分叉到子会话中，因此子会话会以相同的对话上下文开始。 - - 仅在子会话需要当前 transcript 时才使用 `fork`。对于范围明确的工作，请省略 `context`。 -- `sessions_spawn` **不接受**渠道投递参数（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。如需投递，请在已启动的运行中使用 `message` / `sessions_send`。 +- `sandbox?`（`inherit|require`，默认 `inherit`；`require` 会在目标子级运行时未启用沙箱时拒绝启动） +- `context?`（`isolated|fork`，默认 `isolated`；仅适用于原生子智能体） + - `isolated` 会创建一个干净的子级转录，并且是默认值。 + - `fork` 会将请求者当前转录分支到子级会话中，使子级以相同的对话上下文启动。 + - 仅当子级需要当前转录时才使用 `fork`。对于范围明确的工作，请省略 `context`。 +- `sessions_spawn` **不**接受渠道投递参数（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。如需投递，请从已启动的运行中使用 `message`/`sessions_send`。 ## 线程绑定会话 -当某个渠道启用了线程绑定时，子智能体可以保持绑定到一个线程，这样该线程中的后续用户消息就会继续路由到同一个子智能体会话。 +当某个渠道启用线程绑定时，子智能体可以保持绑定到某个线程，这样该线程中的后续用户消息会持续路由到同一个子智能体会话。 ### 支持线程的渠道 -- Discord（当前唯一受支持的渠道）：支持持久线程绑定的子智能体会话（`sessions_spawn` 配合 `thread: true`）、手动线程控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及适配器键 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSubagentSessions`。 +- Discord（当前唯一受支持的渠道）：支持持久的线程绑定子智能体会话（使用带有 `thread: true` 的 `sessions_spawn`）、手动线程控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及适配器键 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSubagentSessions`。 快速流程： -1. 使用 `sessions_spawn` 启动，并设置 `thread: true`（可选地设置 `mode: "session"`）。 -2. OpenClaw 会在当前激活渠道中创建一个线程，或将某个线程绑定到该会话目标。 -3. 该线程中的回复和后续消息会路由到绑定的会话。 -4. 使用 `/session idle` 查看 / 更新无活动自动取消聚焦策略，使用 `/session max-age` 控制硬性上限。 +1. 使用带有 `thread: true` 的 `sessions_spawn` 启动（也可选择 `mode: "session"`）。 +2. OpenClaw 会在当前渠道中创建一个线程，或将线程绑定到该会话目标。 +3. 该线程中的回复和后续消息会路由到已绑定的会话。 +4. 使用 `/session idle` 查看/更新不活动自动取消聚焦设置，并使用 `/session max-age` 控制硬性上限。 5. 使用 `/unfocus` 手动解除绑定。 手动控制： -- `/focus ` 将当前线程（或创建一个线程）绑定到某个子智能体 / 会话目标。 -- `/unfocus` 移除当前已绑定线程的绑定。 -- `/agents` 列出活动运行和绑定状态（`thread:` 或 `unbound`）。 -- `/session idle` 和 `/session max-age` 仅对已聚焦的绑定线程有效。 +- `/focus ` 会将当前线程（或创建一个线程）绑定到某个子智能体/会话目标。 +- `/unfocus` 会移除当前已绑定线程的绑定关系。 +- `/agents` 会列出活跃运行和绑定状态（`thread:` 或 `unbound`）。 +- `/session idle` 和 `/session max-age` 仅适用于已聚焦的绑定线程。 配置开关： - 全局默认值：`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours` -- 渠道覆盖和启动自动绑定键是特定于适配器的。请参阅上文的**支持线程的渠道**。 +- 渠道覆盖和启动时自动绑定键是适配器特定的。请参见上方的**支持线程的渠道**。 -有关当前适配器详情，请参阅[配置参考](/zh-CN/gateway/configuration-reference)和 [Slash commands](/zh-CN/tools/slash-commands)。 +当前适配器详情请参见 [Configuration Reference](/zh-CN/gateway/configuration-reference) 和 [Slash commands](/zh-CN/tools/slash-commands)。 允许列表： -- `agents.list[].subagents.allowAgents`：可通过 `agentId` 作为目标的智能体 id 列表（`["*"]` 表示允许任意目标）。默认：仅允许请求者智能体。 +- `agents.list[].subagents.allowAgents`：可通过 `agentId` 指定的智能体 id 列表（`["*"]` 表示允许任意智能体）。默认值：仅请求者智能体。 - `agents.defaults.subagents.allowAgents`：当请求者智能体未设置自己的 `subagents.allowAgents` 时使用的默认目标智能体允许列表。 -- 沙箱继承保护：如果请求者会话是沙箱隔离的，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。 -- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`：当为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式配置文件选择）。默认：false。 +- 沙箱继承保护：如果请求者会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。 +- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`：当为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置档案）。默认值：false。 发现： @@ -150,17 +160,17 @@ x-i18n: 自动归档： -- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes` 之后自动归档（默认：60）。 -- 归档使用 `sessions.delete`，并将 transcript 重命名为 `*.deleted.`（同一文件夹内）。 -- `cleanup: "delete"` 会在回传后立即归档（仍然通过重命名保留 transcript）。 -- 自动归档是尽力而为的；如果 Gateway 网关重启，待处理计时器会丢失。 -- `runTimeoutSeconds` **不会**自动归档；它只会停止运行。会话会保留到自动归档时。 -- 自动归档同样适用于深度 1 和深度 2 会话。 -- 浏览器清理与归档清理是分开的：在运行结束时，已跟踪的浏览器标签页 / 进程会尽力关闭，即使 transcript / 会话记录被保留。 +- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes` 之后自动归档（默认值：60）。 +- 归档使用 `sessions.delete`，并将转录重命名为 `*.deleted.`（同一文件夹）。 +- `cleanup: "delete"` 会在回报后立即归档（仍会通过重命名保留转录）。 +- 自动归档尽力而为；如果 Gateway 网关重启，待处理计时器会丢失。 +- `runTimeoutSeconds` **不会**自动归档；它只会停止运行。会话会保留，直到自动归档发生。 +- 自动归档同样适用于深度 1 和深度 2 的会话。 +- 浏览器清理与归档清理分离：运行结束时，会尽最大努力关闭已跟踪的浏览器标签页/进程，即使转录/会话记录被保留也是如此。 ## 嵌套子智能体 -默认情况下，子智能体不能再启动自己的子智能体（`maxSpawnDepth: 1`）。你可以将 `maxSpawnDepth: 2` 设为允许一层嵌套，这样就支持**编排器模式**：主智能体 → 编排器子智能体 → 工作型子子智能体。 +默认情况下，子智能体不能再启动自己的子智能体（`maxSpawnDepth: 1`）。你可以通过设置 `maxSpawnDepth: 2` 来启用一层嵌套，这样就允许使用**编排器模式**：主智能体 → 编排器子智能体 → 工作子子智能体。 ### 如何启用 @@ -169,10 +179,10 @@ x-i18n: agents: { defaults: { subagents: { - maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1) - maxChildrenPerAgent: 5, // max active children per agent session (default: 5) - maxConcurrent: 8, // global concurrency lane cap (default: 8) - runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout) + maxSpawnDepth: 2, // 允许子智能体启动子级（默认值：1） + maxChildrenPerAgent: 5, // 每个智能体会话的最大活跃子级数（默认值：5） + maxConcurrent: 8, // 全局并发队列上限（默认值：8） + runTimeoutSeconds: 900, // 省略时 sessions_spawn 的默认超时（0 = 无超时） }, }, }, @@ -181,123 +191,114 @@ x-i18n: ### 深度级别 -| 深度 | 会话键形状 | 角色 | 可否启动子级？ | +| 深度 | 会话键形态 | 角色 | 可以启动子级？ | | ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | -| 0 | `agent::main` | 主智能体 | 始终可以 | -| 1 | `agent::subagent:` | 子智能体（当允许深度 2 时可作为编排器） | 仅当 `maxSpawnDepth >= 2` | -| 2 | `agent::subagent::subagent:` | 子子智能体（叶子工作者） | 永远不可以 | +| 0 | `agent::main` | 主智能体 | 始终可以 | +| 1 | `agent::subagent:` | 子智能体（在允许深度 2 时可作为编排器） | 仅当 `maxSpawnDepth >= 2` | +| 2 | `agent::subagent::subagent:` | 子子智能体（叶子工作节点） | 永不可以 | -### 回传链 +### 回报链 -结果会沿链路向上流动： +结果会沿链路逐级回传： -1. 深度 2 工作者完成 → 回传给其父级（深度 1 编排器） -2. 深度 1 编排器接收回传、综合结果、完成 → 回传给主智能体 -3. 主智能体接收回传并投递给用户 +1. 深度 2 的工作节点完成 → 向其父级（深度 1 编排器）回报 +2. 深度 1 编排器接收回报、综合结果、完成 → 向主智能体回报 +3. 主智能体接收回报并将结果投递给用户 -每一级只会看到来自其直接子级的回传。 +每一层只能看到其直接子级的回报。 -运维指导： +操作指南： -- 只启动一次子任务，并等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 - `exec` sleep 命令构建轮询循环。 -- 如果子任务完成事件在你已经发送最终答案之后才到达， - 正确的后续动作是发送精确的静默 token：`NO_REPLY` / `no_reply`。 +- 子级工作启动一次后，等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` sleep 命令构建轮询循环。 +- 如果子级完成事件在你已经发送最终答案之后才到达，正确的后续处理是精确的静默令牌 `NO_REPLY` / `no_reply`。 ### 按深度划分的工具策略 - 角色和控制范围会在启动时写入会话元数据。这样可以防止扁平化或恢复后的会话键意外重新获得编排器权限。 -- **深度 1（编排器，当 `maxSpawnDepth >= 2` 时）**：会获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子任务。其他会话 / 系统工具仍然被拒绝。 -- **深度 1（叶子节点，当 `maxSpawnDepth == 1` 时）**：不提供任何会话工具（当前默认行为）。 -- **深度 2（叶子工作者）**：不提供任何会话工具——在深度 2 上，`sessions_spawn` 始终被拒绝。不能再继续启动子级。 +- **深度 1（编排器，当 `maxSpawnDepth >= 2` 时）**：获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子级。其他会话/系统工具仍然被拒绝。 +- **深度 1（叶子节点，当 `maxSpawnDepth == 1` 时）**：没有会话工具（当前默认行为）。 +- **深度 2（叶子工作节点）**：没有会话工具——在深度 2 时 `sessions_spawn` 始终被拒绝。无法继续启动更多子级。 -### 按智能体划分的启动数量上限 +### 每个智能体的启动数量限制 -每个智能体会话（任意深度）同时最多只能拥有 `maxChildrenPerAgent`（默认：5）个活动子任务。这可以防止单个编排器出现失控式扇出。 +每个智能体会话（任意深度）同一时间最多只能有 `maxChildrenPerAgent`（默认值：5）个活跃子级。这可以防止单个编排器出现失控扇出。 ### 级联停止 -停止深度 1 编排器会自动停止它的所有深度 2 子任务： +停止一个深度 1 编排器会自动停止其所有深度 2 子级： -- 在主聊天中执行 `/stop` 会停止所有深度 1 智能体，并级联停止它们的深度 2 子任务。 -- `/subagents kill ` 会停止指定的子智能体，并级联停止其子任务。 -- `/subagents kill all` 会停止该请求者的所有子智能体，并执行级联停止。 +- 在主聊天中发送 `/stop` 会停止所有深度 1 智能体，并级联停止它们的深度 2 子级。 +- `/subagents kill ` 会停止指定的某个子智能体，并级联停止其子级。 +- `/subagents kill all` 会停止该请求者的所有子智能体，并进行级联停止。 -## 身份验证 +## 认证 -子智能体的 auth 是按**智能体 id**解析的，而不是按会话类型： +子智能体认证按**智能体 id**解析，而不是按会话类型： -- 子智能体会话键是 `agent::subagent:`。 -- auth 存储会从该智能体的 `agentDir` 加载。 -- 主智能体的 auth 配置文件会作为**回退**合并进来；如有冲突，智能体配置文件优先于主配置文件。 +- 子智能体会话键为 `agent::subagent:`。 +- 认证存储从该智能体的 `agentDir` 加载。 +- 主智能体的认证配置档案会作为**回退项**合并进来；如果发生冲突，智能体配置档案优先于主配置档案。 -注意：这种合并是追加式的，因此主配置文件始终可作为回退使用。目前尚不支持每个智能体完全隔离的 auth。 +注意：这种合并是增量式的，因此主配置档案始终可作为回退项使用。目前尚不支持每个智能体完全隔离的认证。 -## 回传 +## 回报 -子智能体通过回传步骤进行结果汇报： +子智能体通过回报步骤进行结果汇报： -- 回传步骤在子智能体会话内部运行（而不是在请求者会话中运行）。 -- 如果子智能体回复恰好为 `ANNOUNCE_SKIP`，则不会发布任何内容。 -- 如果最新 assistant 文本恰好是静默 token `NO_REPLY` / `no_reply`， - 即使之前存在可见的进度，也会抑制回传输出。 -- 否则，投递行为取决于请求者深度： - - 顶层请求者会话使用后续 `agent` 调用，并开启外部投递（`deliver=true`） - - 嵌套请求者子智能体会话会接收内部后续注入（`deliver=false`），以便编排器在会话内综合子结果 - - 如果某个嵌套请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者 -- 对于顶层请求者会话，完成模式下的直接投递会先解析任何已绑定的会话 / 线程路由和 hook 覆盖项，然后从请求者会话中存储的路由补全缺失的渠道目标字段。即使完成来源只标识了渠道，这也能让完成消息保持在正确的聊天 / 话题中。 -- 在构建嵌套完成结果时，子任务完成聚合会限定在当前请求者运行范围内，以防旧运行中的子任务输出泄漏到当前回传中。 -- 在渠道适配器支持的情况下，回传回复会保留线程 / 话题路由。 -- 回传上下文会被规范化为稳定的内部事件块： +- 回报步骤在子智能体会话内部运行（不是在请求者会话中运行）。 +- 如果子智能体精确回复 `ANNOUNCE_SKIP`，则不会发布任何内容。 +- 如果最新的助手文本是精确的静默令牌 `NO_REPLY` / `no_reply`，即使之前存在可见进度，也会抑制回报输出。 +- 否则，投递取决于请求者深度： + - 顶层请求者会话使用带外部投递的后续 `agent` 调用（`deliver=true`） + - 嵌套的请求者子智能体会话接收内部后续注入（`deliver=false`），以便编排器能够在会话内综合子级结果 + - 如果嵌套的请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者 +- 对于顶层请求者会话，完成模式下的直接投递会先解析任何已绑定的会话/线程路由和 hook 覆盖项，然后从请求者会话存储的路由中补齐缺失的渠道目标字段。这样即使完成来源只标识了渠道，也能确保完成通知发送到正确的聊天/话题中。 +- 在构建嵌套完成结果时，子级完成聚合被限定在当前请求者运行范围内，防止陈旧的先前运行子级输出泄漏到当前回报中。 +- 在渠道适配器可用时，回报回复会保留线程/话题路由。 +- 回报上下文会被标准化为稳定的内部事件块： - 来源（`subagent` 或 `cron`） - - 子会话键 / id - - 回传类型 + 任务标签 - - 基于运行时结果派生的状态行（`success`、`error`、`timeout` 或 `unknown`） - - 从最新可见 assistant 文本中选择结果内容；否则使用经过清理的最新 tool / toolResult 文本；终态失败运行会报告失败状态，而不会重放已捕获的回复文本 - - 一条后续说明，描述何时应回复、何时应保持静默 -- `Status` 不是从模型输出中推断出来的；它来自运行时结果信号。 -- 在超时情况下，如果子任务只执行到了工具调用，回传可以将该历史压缩成简短的部分进展摘要，而不是重放原始工具输出。 + - 子级会话键/id + - 回报类型 + 任务标签 + - 从运行时结果派生的状态行（`success`、`error`、`timeout` 或 `unknown`） + - 从最新可见助手文本中选择的结果内容；否则使用经过净化的最新 `tool`/`toolResult` 文本；终态失败的运行会报告失败状态，而不会重放已捕获的回复文本 + - 一条后续指令，说明何时应回复、何时应保持静默 +- `Status` 不是从模型输出推断的；它来自运行时结果信号。 +- 在超时时，如果子级只执行到了工具调用阶段，回报可以将那段历史折叠为简短的部分进度摘要，而不是重放原始工具输出。 -回传负载末尾会包含一行统计信息（即使被包裹时也会保留）： +回报载荷在末尾都包含一行统计信息（即使被包裹）： -- 运行时长（例如 `runtime 5m12s`） -- Token 使用量（输入 / 输出 / 总量） -- 当配置了模型定价（`models.providers.*.models[].cost`）时，显示估算成本 -- `sessionKey`、`sessionId` 和 transcript 路径（这样主智能体可以通过 `sessions_history` 获取历史，或直接检查磁盘上的文件） -- 内部元数据仅用于编排；面向用户的回复应重写为正常 assistant 语气。 +- 运行时长（例如，`runtime 5m12s`） +- 令牌使用量（输入/输出/总计） +- 配置了模型定价时的预估成本（`models.providers.*.models[].cost`） +- `sessionKey`、`sessionId` 和转录路径（这样主智能体就可以通过 `sessions_history` 获取历史，或直接检查磁盘上的文件） +- 内部元数据仅用于编排；面向用户的回复应使用正常助手语气重写。 `sessions_history` 是更安全的编排路径： -- assistant 回溯会先被规范化： +- 助手回溯会先进行标准化： - 去除 thinking 标签 - 去除 `` / `` 脚手架块 - - 去除纯文本工具调用 XML 负载块，例如 `...`、 - `...`、`...` 和 - `...`，包括那些从未正常闭合的截断 - 负载 - - 去除降级的工具调用 / 结果脚手架和历史上下文标记 - - 去除泄漏的模型控制 token，例如 `<|assistant|>`、其他 ASCII - `<|...|>` token，以及全角变体 `<｜...｜>` + - 去除纯文本工具调用 XML 载荷块，如 `...`、`...`、`...` 和 `...`，包括那些从未正常闭合的截断载荷 + - 去除降级后的工具调用/结果脚手架和历史上下文标记 + - 去除泄漏的模型控制令牌，例如 `<|assistant|>`、其他 ASCII `<|...|>` 令牌，以及全角 `<｜...｜>` 变体 - 去除格式错误的 MiniMax 工具调用 XML -- 类似凭证 / token 的文本会被脱敏 -- 过长的块可能会被截断 -- 对于非常大的历史，可能会丢弃较早的行，或用 - `[sessions_history omitted: message too large]` 替换超大的单行 -- 当你需要完整的逐字节 transcript 时，回退方案是直接检查磁盘上的原始 transcript +- 类似凭证/令牌的文本会被脱敏 +- 长内容块可能会被截断 +- 对于非常大的历史，可能会丢弃较旧的行，或用 `[sessions_history omitted: message too large]` 替换超大的某一行 +- 当你需要完整逐字节转录时，回退方式是直接检查磁盘上的原始转录文件 ## 工具策略（子智能体工具） -默认情况下，子智能体会获得**除会话工具和系统工具之外的所有工具**： +默认情况下，子智能体获得**除会话工具**和系统工具之外的**所有工具**： - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -这里的 `sessions_history` 仍然是有边界、经过清理的回溯视图；它 -不是原始 transcript 转储。 +这里的 `sessions_history` 也仍然是一个有边界、经过净化的回溯视图；它不是原始转录转储。 -当 `maxSpawnDepth >= 2` 时，深度 1 编排器子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便管理它们的子任务。 +当 `maxSpawnDepth >= 2` 时，深度 1 的编排器子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便管理其子级。 可通过配置覆盖： @@ -313,9 +314,9 @@ x-i18n: tools: { subagents: { tools: { - // deny wins + // deny 优先生效 deny: ["gateway", "cron"], - // if allow is set, it becomes allow-only (deny still wins) + // 如果设置了 allow，则变为仅允许 allow 中的工具（deny 仍然优先生效） // allow: ["read", "exec", "process"] }, }, @@ -325,27 +326,27 @@ x-i18n: ## 并发 -子智能体使用专用的进程内队列 lane： +子智能体使用专用的进程内队列： -- Lane 名称：`subagent` -- 并发数：`agents.defaults.subagents.maxConcurrent`（默认 `8`） +- 队列名称：`subagent` +- 并发度：`agents.defaults.subagents.maxConcurrent`（默认值 `8`） ## 停止 -- 在请求者聊天中发送 `/stop` 会中止请求者会话，并停止由其启动的所有活动子智能体运行，同时级联停止嵌套子任务。 -- `/subagents kill ` 会停止指定的子智能体，并级联停止其子任务。 +- 在请求者聊天中发送 `/stop` 会中止请求者会话，并停止所有由其启动的活跃子智能体运行，同时级联停止嵌套子级。 +- `/subagents kill ` 会停止指定的某个子智能体，并级联停止其子级。 ## 限制 -- 子智能体回传是**尽力而为**的。如果 Gateway 网关重启，待处理的“回传结果”工作会丢失。 -- 子智能体仍然共享同一个 Gateway 网关进程资源；请将 `maxConcurrent` 视为安全阀。 +- 子智能体回报是**尽力而为**的。如果 Gateway 网关重启，待处理的“回报结果”工作会丢失。 +- 子智能体仍共享同一个 Gateway 网关进程资源；应将 `maxConcurrent` 视为安全阀。 - `sessions_spawn` 始终是非阻塞的：它会立即返回 `{ status: "accepted", runId, childSessionKey }`。 -- 子智能体上下文只注入 `AGENTS.md` + `TOOLS.md`（不包括 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。 -- 最大嵌套深度为 5（`maxSpawnDepth` 范围：1–5）。对于大多数使用场景，推荐深度 2。 -- `maxChildrenPerAgent` 限制每个会话的活动子任务数量（默认：5，范围：1–20）。 +- 子智能体上下文只注入 `AGENTS.md` + `TOOLS.md`（不注入 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。 +- 最大嵌套深度为 5（`maxSpawnDepth` 范围：1–5）。对于大多数使用场景，推荐使用深度 2。 +- `maxChildrenPerAgent` 会限制每个会话的活跃子级数量（默认值：5，范围：1–20）。 ## 相关内容 -- [ACP 智能体](/zh-CN/tools/acp-agents) -- [多智能体沙箱工具](/zh-CN/tools/multi-agent-sandbox-tools) -- [智能体发送](/zh-CN/tools/agent-send) +- [ACP agents](/zh-CN/tools/acp-agents) +- [Multi-agent sandbox tools](/zh-CN/tools/multi-agent-sandbox-tools) +- [Agent send](/zh-CN/tools/agent-send)