diff --git a/docs/zh-CN/channels/irc.md b/docs/zh-CN/channels/irc.md index f42e3e22e..54a5699bb 100644 --- a/docs/zh-CN/channels/irc.md +++ b/docs/zh-CN/channels/irc.md @@ -1,25 +1,25 @@ --- read_when: - - 你希望将 OpenClaw 连接到 IRC 渠道或私信 + - 你想将 OpenClaw 连接到 IRC 频道或私信 - 你正在配置 IRC 允许列表、群组策略或提及门控 -summary: IRC 插件设置、访问控制与故障排除 +summary: IRC 插件设置、访问控制和故障排除 title: IRC x-i18n: - generated_at: "2026-04-23T20:41:19Z" - model: gpt-5.4 + generated_at: "2026-05-04T00:57:17Z" + model: gpt-5.5 provider: openai - source_hash: 76f316c0f026d0387a97dc5dcb6d8967f6e4841d94b95b36e42f6f6284882a69 + source_hash: 43c3098fe49a5e7405443df73e1bf752a579460dc0b2070c3d07f43b512bb555 source_path: channels/irc.md - workflow: 15 + workflow: 16 --- -当你希望 OpenClaw 进入经典 IRC 渠道（`#room`）和私信时，请使用 IRC。 -IRC 作为内置插件提供，但需要在主配置的 `channels.irc` 下进行配置。 +当你想在经典渠道（`#room`）和私信中使用 OpenClaw 时，请使用 IRC。 +IRC 作为内置插件提供，但它在主配置的 `channels.irc` 下配置。 ## 快速开始 1. 在 `~/.openclaw/openclaw.json` 中启用 IRC 配置。 -2. 至少设置以下内容： +2. 至少设置： ```json5 { @@ -36,7 +36,7 @@ IRC 作为内置插件提供，但需要在主配置的 `channels.irc` 下进行 } ``` -建议使用私有 IRC 服务器进行机器人协作。如果你有意使用公共 IRC 网络，常见选择包括 Libera.Chat、OFTC 和 Snoonet。避免将可预测的公共频道用于机器人或 swarm 的回传流量。 +建议使用私有 IRC 服务器进行机器人协调。如果你有意使用公共 IRC 网络，常见选择包括 Libera.Chat、OFTC 和 Snoonet。避免将可预测的公共频道用于机器人或集群的后向通道流量。 3. 启动/重启 Gateway 网关： @@ -44,42 +44,43 @@ IRC 作为内置插件提供，但需要在主配置的 `channels.irc` 下进行 openclaw gateway run ``` -## 默认安全设置 +## 安全默认值 -- `channels.irc.dmPolicy` 默认为 `"pairing"`。 -- `channels.irc.groupPolicy` 默认为 `"allowlist"`。 -- 当 `groupPolicy="allowlist"` 时，设置 `channels.irc.groups` 以定义允许的渠道。 +- IRC 使用 OpenClaw 操作者管理的转发代理路由之外的原始 TCP/TLS 套接字。在要求所有出口流量都经过该转发代理的部署中，除非直接 IRC 出口已明确获批，否则请设置 `channels.irc.enabled=false`。 +- `channels.irc.dmPolicy` 默认值为 `"pairing"`。 +- `channels.irc.groupPolicy` 默认值为 `"allowlist"`。 +- 使用 `groupPolicy="allowlist"` 时，设置 `channels.irc.groups` 来定义允许的渠道。 - 除非你有意接受明文传输，否则请使用 TLS（`channels.irc.tls=true`）。 ## 访问控制 -IRC 渠道有两个独立的“门”： +IRC 渠道有两个独立的“门禁”： -1. **渠道访问**（`groupPolicy` + `groups`）：机器人是否完全接受来自某个渠道的消息。 -2. **发送者访问**（`groupAllowFrom` / 每渠道 `groups["#channel"].allowFrom`）：谁有权在该渠道内触发机器人。 +1. **渠道访问**（`groupPolicy` + `groups`）：机器人是否接受来自某个渠道的消息。 +2. **发送者访问**（`groupAllowFrom` / 每渠道 `groups["#channel"].allowFrom`）：谁被允许在该渠道内触发机器人。 配置键： - 私信允许列表（私信发送者访问）：`channels.irc.allowFrom` - 群组发送者允许列表（渠道发送者访问）：`channels.irc.groupAllowFrom` - 每渠道控制（渠道 + 发送者 + 提及规则）：`channels.irc.groups["#channel"]` -- `channels.irc.groupPolicy="open"` 允许未配置的渠道（**默认仍然受提及门控限制**） +- `channels.irc.groupPolicy="open"` 允许未配置的渠道（**默认仍受提及门控限制**） -允许列表项应使用稳定的发送者身份（`nick!user@host`）。 -仅使用裸 `nick` 匹配是可变的，并且只有在 `channels.irc.dangerouslyAllowNameMatching: true` 时才会启用。 +允许列表条目应使用稳定的发送者身份（`nick!user@host`）。 +裸昵称匹配是可变的，并且仅在 `channels.irc.dangerouslyAllowNameMatching: true` 时启用。 ### 常见陷阱：`allowFrom` 用于私信，不用于渠道 -如果你看到这样的日志： +如果你看到类似日志： - `irc: drop group sender alice!ident@host (policy=allowlist)` -……这意味着该发送者未被允许发送**群组/渠道**消息。你可以通过以下方式修复： +……这表示该发送者未被允许发送**群组/渠道**消息。可通过以下任一方式修复： - 设置 `channels.irc.groupAllowFrom`（对所有渠道全局生效），或 - 设置每渠道发送者允许列表：`channels.irc.groups["#channel"].allowFrom` -示例（允许 `#tuirc-dev` 中的任何人与机器人对话）： +示例（允许 `#tuirc-dev` 中任何人与机器人对话）： ```json5 { @@ -96,11 +97,11 @@ IRC 渠道有两个独立的“门”： ## 回复触发（提及） -即使某个渠道已被允许（通过 `groupPolicy` + `groups`），并且发送者也被允许，OpenClaw 在群组场景下默认仍启用**提及门控**。 +即使某个渠道已被允许（通过 `groupPolicy` + `groups`），并且发送者也已被允许，OpenClaw 在群组上下文中默认仍会使用**提及门控**。 -这意味着，除非消息中包含与机器人匹配的提及模式，否则你可能会看到类似 `drop channel … (missing-mention)` 的日志。 +这意味着你可能会看到类似 `drop channel … (missing-mention)` 的日志，除非消息包含与机器人匹配的提及模式。 -如果你希望机器人在 IRC 渠道中**无需提及即可回复**，请为该渠道禁用提及门控： +要让机器人在 IRC 渠道中**无需提及也能回复**，请为该渠道禁用提及门控： ```json5 { @@ -118,7 +119,7 @@ IRC 渠道有两个独立的“门”： } ``` -或者，如果你希望允许**所有** IRC 渠道（不使用每渠道允许列表），并且仍然无需提及即可回复： +或者，允许**所有** IRC 渠道（无每渠道允许列表），同时仍无需提及即可回复： ```json5 { @@ -133,12 +134,12 @@ IRC 渠道有两个独立的“门”： } ``` -## 安全说明（推荐用于公共渠道） +## 安全说明（公共渠道推荐） -如果你在公共渠道中设置 `allowFrom: ["*"]`，任何人都可以提示机器人。 -为降低风险，建议限制该渠道可用的工具。 +如果你在公共渠道中允许 `allowFrom: ["*"]`，任何人都可以提示机器人。 +为降低风险，请限制该渠道的工具。 -### 渠道内所有人使用相同的工具权限 +### 渠道中每个人使用相同工具 ```json5 { @@ -157,9 +158,9 @@ IRC 渠道有两个独立的“门”： } ``` -### 按发送者区分工具权限（所有者权限更大） +### 按发送者使用不同工具（所有者获得更多权限） -使用 `toolsBySender`，对 `"*"` 应用更严格的策略，对你的 nick 应用更宽松的策略： +使用 `toolsBySender` 对 `"*"` 应用更严格的策略，并对你的昵称应用更宽松的策略： ```json5 { @@ -186,15 +187,15 @@ IRC 渠道有两个独立的“门”： 说明： - `toolsBySender` 键应对 IRC 发送者身份值使用 `id:`： - 使用 `id:eigen`，或使用 `id:eigen!~eigen@174.127.248.171` 进行更强匹配。 -- 旧版无前缀键仍然受支持，但只会按 `id:` 进行匹配。 -- 首个匹配到的发送者策略优先生效；`"*"` 是通配回退。 + `id:eigen`，或使用 `id:eigen!~eigen@174.127.248.171` 进行更强匹配。 +- 旧版无前缀键仍会被接受，并且仅按 `id:` 匹配。 +- 第一个匹配的发送者策略生效；`"*"` 是通配回退。 -有关群组访问与提及门控（以及它们如何交互）的更多信息，请参阅：[/channels/groups](/zh-CN/channels/groups)。 +要进一步了解群组访问与提及门控（以及它们如何交互），请参阅：[/channels/groups](/zh-CN/channels/groups)。 ## NickServ -连接后若要通过 NickServ 进行身份验证： +连接后要向 NickServ 进行身份验证： ```json5 { @@ -210,7 +211,7 @@ IRC 渠道有两个独立的“门”： } ``` -连接时可选执行一次性注册： +连接时可选的一次性注册： ```json5 { @@ -225,7 +226,7 @@ IRC 渠道有两个独立的“门”： } ``` -在 nick 完成注册后禁用 `register`，以避免重复尝试执行 REGISTER。 +昵称注册完成后，请禁用 `register`，以避免重复尝试 REGISTER。 ## 环境变量 @@ -242,18 +243,18 @@ IRC 渠道有两个独立的“门”： - `IRC_NICKSERV_PASSWORD` - `IRC_NICKSERV_REGISTER_EMAIL` -`IRC_HOST` 不能通过工作区 `.env` 设置；请参阅[工作区 `.env` 文件](/zh-CN/gateway/security)。 +不能从工作区 `.env` 设置 `IRC_HOST`；请参阅[工作区 `.env` 文件](/zh-CN/gateway/security)。 ## 故障排除 -- 如果机器人已连接但从不在渠道中回复，请检查 `channels.irc.groups`，**以及**是否因为提及门控而丢弃了消息（`missing-mention`）。如果你希望它无需 ping 就能回复，请为该渠道设置 `requireMention:false`。 -- 如果登录失败，请检查 nick 是否可用以及服务器密码是否正确。 -- 如果在自定义网络上 TLS 失败，请检查 host/port 和证书配置。 +- 如果机器人已连接但在渠道中从不回复，请验证 `channels.irc.groups`，**并**检查提及门控是否正在丢弃消息（`missing-mention`）。如果你希望它无需 ping 即可回复，请为该渠道设置 `requireMention:false`。 +- 如果登录失败，请验证昵称可用性和服务器密码。 +- 如果 TLS 在自定义网络上失败，请验证主机/端口和证书设置。 ## 相关内容 -- [渠道概览](/zh-CN/channels)——所有支持的渠道 -- [配对](/zh-CN/channels/pairing)——私信认证与配对流程 -- [群组](/zh-CN/channels/groups)——群聊行为与提及门控 -- [渠道路由](/zh-CN/channels/channel-routing)——消息的会话路由 -- [安全](/zh-CN/gateway/security)——访问模型与加固措施 +- [渠道概览](/zh-CN/channels) — 所有支持的渠道 +- [配对](/zh-CN/channels/pairing) — 私信认证和配对流程 +- [群组](/zh-CN/channels/groups) — 群组聊天行为和提及门控 +- [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由 +- [安全](/zh-CN/gateway/security) — 访问模型和加固 diff --git a/docs/zh-CN/concepts/mantis.md b/docs/zh-CN/concepts/mantis.md index fe3898548..c9238c3d2 100644 --- a/docs/zh-CN/concepts/mantis.md +++ b/docs/zh-CN/concepts/mantis.md @@ -1,65 +1,65 @@ --- read_when: - - 为 OpenClaw 缺陷构建或运行实时视觉 QA + - 为 OpenClaw 缺陷构建或运行实时可视化 QA - 为拉取请求添加前后验证 - - 添加 Discord、Slack、WhatsApp 或其他实时传输场景 + - 添加 Discord、Slack、WhatsApp 或其他实时传输协议场景 - 调试需要截图、浏览器自动化或 VNC 访问的 QA 运行 -summary: Mantis 是用于在实时传输协议上复现 OpenClaw 缺陷、捕获修复前后证据，并将构件附加到拉取请求的可视化端到端验证系统。 +summary: Mantis 是一个可视化端到端验证系统，用于在实时传输协议上复现 OpenClaw 缺陷、捕获前后证据，并将产物附加到 PR。 title: Mantis x-i18n: - generated_at: "2026-05-04T00:35:07Z" + generated_at: "2026-05-04T00:57:25Z" model: gpt-5.5 provider: openai - source_hash: 7d1fe1e6cb57406fab351892b43c7057a0d08e26455d76a50157f958474e363e + source_hash: 42161d802c8601e58af1abef69277b5b3eac37750480326e1f56b2898a6af3fb source_path: concepts/mantis.md workflow: 16 --- -Mantis 是 OpenClaw 的端到端验证系统，适用于需要真实运行时、真实传输协议和可见证据的 bug。它会针对已知有问题的 ref 运行一个场景、捕获证据，然后针对候选 ref 运行同一场景，并将对比结果发布为制品，维护者可以从 PR 或本地命令中检查这些制品。 +Mantis 是 OpenClaw 的端到端验证系统，适用于需要真实运行时、真实传输协议和可见证明的错误。它会针对一个已知有问题的 ref 运行场景，捕获证据，再针对一个候选 ref 运行相同场景，并将对比结果发布为 artifact，维护者可以从 PR 或本地命令中检查。 -Mantis 从 Discord 开始，因为 Discord 为我们提供了一条高价值的首条验证线：真实 bot 凭证、真实公会频道、回应、话题串、原生命令，以及一个浏览器 UI，人类可以在其中直观确认传输协议展示了什么。 +Mantis 从 Discord 开始，因为 Discord 提供了一个高价值的首个通道：真实机器人凭证、真实公会频道、回应、线程、原生命令，以及一个人类可以直观看到传输协议所展示内容的浏览器 UI。 ## 目标 -- 使用用户看到的相同传输协议形态，从 GitHub issue 或 PR 复现 bug。 -- 在应用修复前，在基线 ref 上捕获一个**之前**制品。 -- 在应用修复后，在候选 ref 上捕获一个**之后**制品。 -- 尽可能使用确定性的判定器，例如 Discord REST 回应读取或频道转录检查。 -- 当 bug 有可见 UI 表面时捕获截图。 +- 使用用户看到的相同传输协议形态，从 GitHub issue 或 PR 中复现错误。 +- 在应用修复前，在基线 ref 上捕获一个 **before** artifact。 +- 在应用修复后，在候选 ref 上捕获一个 **after** artifact。 +- 尽可能使用确定性 oracle，例如 Discord REST 回应读取或频道 transcript 检查。 +- 当错误具有可见 UI 表面时捕获截图。 - 从智能体控制的 CLI 在本地运行，并从 GitHub 远程运行。 - 保留足够的机器状态，以便在登录、浏览器自动化或提供商凭证卡住时进行 VNC 救援。 -- 当运行被阻塞、需要手动 VNC 帮助或完成时，向操作员 Discord 频道发布简洁状态。 +- 当运行被阻塞、需要手动 VNC 帮助或完成时，向操作员 Discord 频道发布简洁 Status。 ## 非目标 -- Mantis 不是单元测试的替代品。理解修复后，Mantis 运行通常应该转化为更小的回归测试。 -- Mantis 不是常规的快速 CI 门禁。它更慢，会使用实时凭证，并且只保留给实时环境很重要的 bug。 -- Mantis 正常运行不应需要人工参与。手动 VNC 是救援路径，不是理想路径。 -- Mantis 不会在制品、日志、截图、Markdown 报告或 PR 评论中存储原始密钥。 +- Mantis 不是单元测试的替代品。理解修复后，Mantis 运行通常应转化为更小的回归测试。 +- Mantis 不是常规的快速 CI 门禁。它更慢，使用实时凭证，并且保留给实时环境很重要的错误。 +- Mantis 不应要求人类参与正常操作。手动 VNC 是救援路径，不是正常路径。 +- Mantis 不会在 artifact、日志、截图、Markdown 报告或 PR 评论中存储原始密钥。 ## 所有权 -Mantis 位于 OpenClaw 质量保障栈中。 +Mantis 位于 OpenClaw QA 栈中。 - OpenClaw 拥有场景运行时、传输协议适配器、证据 schema，以及 `pnpm openclaw qa mantis` 下的本地 CLI。 -- QA Lab 拥有实时传输协议 harness 组件、浏览器捕获帮助器和制品写入器。 -- 当需要远程 VM 时，Crabbox 拥有预热的 Linux 机器。 -- GitHub Actions 拥有远程 workflow 入口点和制品保留。 -- ClawSweeper 拥有 GitHub 评论路由：解析维护者命令、派发 workflow，并发布最终 PR 评论。 +- QA Lab 拥有实时传输协议 harness 组件、浏览器捕获辅助工具和 artifact 写入器。 +- 需要远程 VM 时，Crabbox 拥有预热的 Linux 机器。 +- GitHub Actions 拥有远程 workflow 入口点和 artifact 保留。 +- ClawSweeper 拥有 GitHub 评论路由：解析维护者命令、分派 workflow，以及发布最终 PR 评论。 - 当场景需要智能体式设置、调试或卡住状态报告时，OpenClaw 智能体通过 Codex 驱动 Mantis。 这个边界将传输协议知识保留在 OpenClaw 中，将机器调度保留在 Crabbox 中，并将维护者 workflow 胶水保留在 ClawSweeper 中。 ## 命令形式 -第一个本地命令会验证 Discord bot、公会、频道、消息发送、回应发送和制品路径： +第一个本地命令会验证 Discord 机器人、公会、频道、消息发送、回应发送和 artifact 路径： ```bash pnpm openclaw qa mantis discord-smoke \ --output-dir .artifacts/qa-e2e/mantis/discord-smoke ``` -本地之前和之后运行器接受这种形式： +本地 before 和 after runner 接受以下形式： ```bash pnpm openclaw qa mantis run \ @@ -70,7 +70,7 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -运行器会在输出目录下创建分离的基线和候选 worktree，安装依赖，构建每个 ref，使用 `--allow-failures` 运行场景，然后写入 `baseline/`、`candidate/`、`comparison.json` 和 `mantis-report.md`。对于第一个 Discord 场景，成功验证意味着基线状态为 `fail`，候选状态为 `pass`。 +runner 会在输出目录下创建分离的基线和候选 worktree，安装依赖，构建每个 ref，使用 `--allow-failures` 运行场景，然后写入 `baseline/`、`candidate/`、`comparison.json` 和 `mantis-report.md`。对于第一个 Discord 场景，验证成功意味着基线 Status 为 `fail`，候选 Status 为 `pass`。 第一个 VM/浏览器原语是桌面冒烟测试： @@ -79,21 +79,22 @@ pnpm openclaw qa mantis desktop-browser-smoke \ --output-dir .artifacts/qa-e2e/mantis/desktop-browser ``` -它会租用或复用一台 Crabbox 桌面机器，在 VNC 会话内启动可见浏览器，捕获桌面，将制品拉回本地输出目录，并把重新连接命令写入报告。该命令默认使用 Hetzner 提供商，因为它是 Mantis 验证线中第一个具备可用桌面/VNC 覆盖的提供商。针对另一个 Crabbox 机器池运行时，可以用 `--provider`、`--crabbox-bin` 或 `OPENCLAW_MANTIS_CRABBOX_PROVIDER` 覆盖它。 +它会租用或复用一台 Crabbox 桌面机器，在 VNC 会话内启动可见浏览器，捕获桌面，将 artifact 拉回本地输出目录，并将重新连接命令写入报告。该命令默认使用 Hetzner 提供商，因为它是 Mantis 通道中第一个具备可用桌面/VNC 覆盖的提供商。针对另一个 Crabbox fleet 运行时，可使用 `--provider`、`--crabbox-bin` 或 `OPENCLAW_MANTIS_CRABBOX_PROVIDER` 覆盖。 有用的桌面冒烟测试标志： - `--lease-id ` 或 `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` 会复用预热的桌面。 -- `--browser-url ` 会更改可见浏览器中打开的页面。 -- `--keep-lease` 或 `OPENCLAW_MANTIS_KEEP_VM=1` 会让新创建且通过的租约保持打开，以便 VNC 检查。失败的运行默认会在创建了租约时保留租约，以便操作员重新连接。 -- `--class`、`--idle-timeout` 和 `--ttl` 会调整机器大小和租约生命周期。 +- `--browser-url ` 会更改在可见浏览器中打开的页面。 +- `--html-file ` 会在可见浏览器中渲染仓库本地 HTML artifact。Mantis 使用它通过真实 Crabbox 桌面捕获生成的 Discord 状态回应时间线。 +- `--keep-lease` 或 `OPENCLAW_MANTIS_KEEP_VM=1` 会让新创建且通过的 lease 保持打开，以供 VNC 检查。失败运行默认会保留创建的 lease，以便操作员重新连接。 +- `--class`、`--idle-timeout` 和 `--ttl` 用于调整机器规格和 lease 生命周期。 -GitHub 冒烟测试 workflow 是 `Mantis Discord Smoke`。第一个真实场景的之前和之后 GitHub workflow 是 `Mantis Discord Status Reactions`。它接受： +GitHub 冒烟测试 workflow 是 `Mantis Discord Smoke`。第一个真实场景的 before 和 after GitHub workflow 是 `Mantis Discord Status Reactions`。它接受： - `baseline_ref`：预期会复现仅排队行为的 ref。 - `candidate_ref`：预期会显示 `queued -> thinking -> done` 的 ref。 -它会检出 workflow harness ref，构建单独的基线和候选 worktree，针对每个 worktree 运行 `discord-status-reactions-tool-only`，并将 `baseline/`、`candidate/`、`comparison.json` 和 `mantis-report.md` 作为 Actions 制品上传。 +它会 checkout workflow harness ref，构建独立的基线和候选 worktree，针对每个 worktree 运行 `discord-status-reactions-tool-only`，并将 `baseline/`、`candidate/`、`comparison.json` 和 `mantis-report.md` 作为 Actions artifact 上传。它还会在 Crabbox 桌面浏览器中渲染每个通道的时间线 HTML，并在 PR 评论中将这些 VNC 截图发布到确定性时间线 PNG 旁边。 你也可以直接从 PR 评论触发状态回应运行： @@ -101,7 +102,7 @@ GitHub 冒烟测试 workflow 是 `Mantis Discord Smoke`。第一个真实场景 @Mantis discord status reactions ``` -评论触发器有意保持狭窄。它只会在来自拥有写入、维护或管理员访问权限的用户的拉取请求评论上运行，并且只识别 Discord 状态回应请求。默认情况下，它使用已知有问题的基线 ref，并使用当前 PR head SHA 作为候选。维护者可以覆盖任一 ref： +评论触发器有意保持窄范围。它只会在具有写入、维护或管理员权限的用户发表的 pull request 评论上运行，并且只识别 Discord 状态回应请求。默认情况下，它使用已知有问题的基线 ref，并将当前 PR head SHA 作为候选。维护者可以覆盖任一 ref： ```text @Mantis discord status reactions baseline=origin/main candidate=HEAD @@ -114,45 +115,45 @@ ClawSweeper 命令示例： @clawsweeper verify e2e discord ``` -第一个命令是显式且聚焦场景的。第二个命令稍后可以根据标签、变更文件和 ClawSweeper 审查发现，将 PR 或 issue 映射到推荐的 Mantis 场景。 +第一个命令是显式且聚焦场景的。第二个之后可以基于标签、变更文件和 ClawSweeper review 发现，将 PR 或 issue 映射到推荐的 Mantis 场景。 ## 运行生命周期 1. 获取凭证。 2. 分配或复用 VM。 -3. 当场景需要 UI 证据时，准备桌面/浏览器配置文件。 -4. 为基线 ref 准备干净检出。 +3. 当场景需要 UI 证据时，准备桌面/浏览器 profile。 +4. 为基线 ref 准备干净 checkout。 5. 安装依赖，并只构建场景需要的内容。 -6. 使用隔离的状态目录启动子 OpenClaw Gateway 网关。 -7. 配置实时传输协议、提供商、模型和浏览器配置文件。 +6. 使用隔离状态目录启动子 OpenClaw Gateway 网关。 +7. 配置实时传输协议、提供商、模型和浏览器 profile。 8. 运行场景并捕获基线证据。 9. 停止 Gateway 网关并保留日志。 10. 在同一 VM 中准备候选 ref。 -11. 运行同一场景并捕获候选证据。 -12. 对比判定器结果和视觉证据。 -13. 写入 Markdown、JSON、日志、截图和可选 trace 制品。 -14. 上传 GitHub Actions 制品。 -15. 发布简洁的 PR 或 Discord 状态消息。 +11. 运行相同场景并捕获候选证据。 +12. 对比 oracle 结果和视觉证据。 +13. 写入 Markdown、JSON、日志、截图和可选 trace artifact。 +14. 上传 GitHub Actions artifact。 +15. 发布简洁的 PR 或 Discord Status 消息。 -场景应该能够以两种不同方式失败： +场景应能以两种不同方式失败： -- **Bug 已复现**：基线以预期方式失败。 -- **Harness 失败**：在 bug 判定器有意义之前，环境设置、凭证、Discord API、浏览器或提供商失败。 +- **错误已复现**：基线按预期方式失败。 +- **Harness 失败**：在错误 oracle 有意义之前，环境设置、凭证、Discord API、浏览器或提供商失败。 -最终报告必须区分这些情况，避免维护者把不稳定环境与产品行为混淆。 +最终报告必须区分这些情况，以免维护者将不稳定环境与产品行为混淆。 ## Discord 最小可行版本 -第一个场景应该针对公会频道中的 Discord 状态回应，其中源回复投递模式为 `message_tool_only`。 +第一个场景应针对公会频道中的 Discord 状态回应，其中源回复投递模式为 `message_tool_only`。 -它是一个很好的 Mantis 起点，原因如下： +它是一个好的 Mantis 种子，原因如下： -- 它在 Discord 中以触发消息上的回应形式可见。 -- 它通过 Discord 消息回应状态提供强 REST 判定器。 -- 它会执行真实的 OpenClaw Gateway 网关、Discord bot 凭证、消息分发、源回复投递模式、状态回应状态和模型轮次生命周期。 -- 它足够狭窄，可以让第一个实现保持诚实。 +- 它在 Discord 中表现为触发消息上的回应，可见。 +- 它通过 Discord 消息回应状态提供强 REST oracle。 +- 它会覆盖真实 OpenClaw Gateway 网关、Discord 机器人凭证、消息分发、源回复投递模式、状态回应状态以及模型轮次生命周期。 +- 它足够窄，可以让第一个实现保持诚实。 -预期场景形式： +预期场景形态： ```yaml id: discord-status-reactions-tool-only @@ -183,9 +184,9 @@ evidence: screenshotMessageRow: true ``` -基线证据应显示已排队的确认回应，但在仅工具模式下没有生命周期转换。候选证据应显示当 `messages.statusReactions.enabled` 被显式设置为 true 时，生命周期状态回应会运行。 +基线证据应显示已排队的确认回应，但在仅工具模式下没有生命周期转换。候选证据应显示当 `messages.statusReactions.enabled` 被显式设置为 true 时生命周期状态回应正在运行。 -第一个可执行切片是选择启用的 Discord 实时 QA 场景： +可执行的第一个切片是选择启用的 Discord 实时 QA 场景： ```bash pnpm openclaw qa discord \ @@ -197,24 +198,23 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -它会为被测系统配置始终开启的公会处理、`visibleReplies: -"message_tool"`、`ackReaction: "👀"` 和显式状态回应。判定器会轮询真实的 Discord 触发消息，并期望观察到序列 `👀 -> 🤔 -> 👍`。制品包括 `discord-qa-reaction-timelines.json`、`discord-status-reactions-tool-only-timeline.html` 和 `discord-status-reactions-tool-only-timeline.png`。 +它会为被测系统配置始终开启的公会处理、`visibleReplies: "message_tool"`、`ackReaction: "👀"` 和显式状态回应。oracle 会轮询真实 Discord 触发消息，并期望观察到序列 `👀 -> 🤔 -> 👍`。Artifact 包括 `discord-qa-reaction-timelines.json`、`discord-status-reactions-tool-only-timeline.html` 和 `discord-status-reactions-tool-only-timeline.png`。 -## 现有质量保障组件 +## 现有 QA 组件 -Mantis 应该基于现有私有质量保障栈构建，而不是从零开始： +Mantis 应基于现有私有 QA 栈构建，而不是从零开始： -- `pnpm openclaw qa discord` 已经运行带有 driver 和 SUT bot 的实时 Discord 验证线。 -- 实时传输协议运行器已经会在 `.artifacts/qa-e2e/` 下写入报告和已观察消息制品。 -- Convex 凭证租约已经为共享实时传输协议凭证提供独占访问。 -- 浏览器控制服务已经支持截图、快照、无头托管配置文件和远程 CDP 配置文件。 +- `pnpm openclaw qa discord` 已经会使用 driver 和被测系统机器人运行实时 Discord 通道。 +- 实时传输协议 runner 已经会在 `.artifacts/qa-e2e/` 下写入报告和观察到的消息 artifact。 +- Convex 凭证 lease 已经为共享实时传输协议凭证提供独占访问。 +- 浏览器控制服务已经支持截图、快照、无头托管 profile 和远程 CDP profile。 - QA Lab 已经有用于传输协议形态测试的调试器 UI 和总线。 -第一个 Mantis 实现可以是在这些组件之上的薄层之前/之后运行器，再加上一层视觉证据。 +第一个 Mantis 实现可以是在这些组件之上的轻量 before/after runner，再加一个视觉证据层。 ## 证据模型 -每次运行都会写入一个稳定的制品目录： +每次运行都会写入一个稳定的 artifact 目录： ```text .artifacts/qa-e2e/mantis// @@ -234,63 +234,63 @@ Mantis 应该基于现有私有质量保障栈构建，而不是从零开始： run.log ``` -`mantis-summary.json` 应该是机器可读的事实来源。Markdown 报告用于 PR 评论和人工审查。 +`mantis-summary.json` 应是机器可读的事实来源。Markdown 报告用于 PR 评论和人工 review。 摘要必须包含： -- 测试过的 ref 和 SHA -- 传输协议和场景 id -- 机器提供商和机器 id 或租约 id +- 已测试的 ref 和 SHA +- 传输协议和场景 ID +- 机器提供商以及机器 ID 或 lease ID - 不含密钥值的凭证来源 - 基线结果 - 候选结果 -- bug 是否在基线上复现 +- 错误是否在基线上复现 - 候选是否修复了它 -- 制品路径 +- artifact 路径 - 已清理的设置或清理问题 -截图是证据，不是密钥。它们仍然需要遵守遮盖纪律：私有频道名称、用户名或消息内容可能会出现。对于公共 PR，在遮盖方案更成熟之前，优先使用 GitHub Actions 制品链接，而不是内联图片。 +截图是证据，不是密钥。它们仍然需要遵守脱敏纪律：私有频道名称、用户名或消息内容可能会出现。对于公开 PR，在脱敏方案更强之前，优先使用 GitHub Actions artifact 链接，而不是内联图片。 ## 浏览器和 VNC -浏览器验证线有两种模式： +浏览器通道有两种模式： - **无头自动化**：CI 的默认模式。Chrome 启用 CDP 运行，Playwright 或 OpenClaw 浏览器控制会捕获截图。 -- **VNC 救援**：当登录、MFA、Discord 反自动化或视觉调试需要人工时，在同一 VM 上启用。 +- **VNC 救援**：当登录、MFA、Discord 反自动化或视觉调试需要人类时，在同一 VM 上启用。 -Discord 观察者浏览器配置文件应足够持久，以避免每次运行都登录，但应与个人浏览器状态隔离。配置文件属于 Mantis 机器池，而不是开发者笔记本电脑。 +Discord 观察者浏览器配置文件应足够持久，避免每次运行都登录，但要与个人浏览器状态隔离。配置文件属于 Mantis 机器池，而不是开发者笔记本电脑。 -当 Mantis 卡住时，它会发布一条 Discord 状态消息，包含： +当 Mantis 卡住时，它会发布一条 Discord 状态消息，其中包含： -- 运行 id -- 场景 id +- 运行 ID +- 场景 ID - 机器提供商 -- 制品目录 -- VNC 或 noVNC 连接说明（如果可用） -- 简短阻塞原因文本 +- 工件目录 +- VNC 或 noVNC 连接说明（如可用） +- 简短的阻塞原因文本 -首个私有部署可以先将这些消息发布到现有的操作员渠道，之后再迁移到专用的 Mantis 渠道。 +首次私有部署可以将这些消息发布到现有操作员渠道，之后再迁移到专用的 Mantis 渠道。 ## 机器 -Mantis 的首个远程实现应优先通过 Crabbox 使用 AWS。Crabbox 为我们提供预热机器、租约跟踪、水合、日志、结果和清理。如果 AWS 容量太慢或不可用，请在同一个机器接口后添加 Hetzner 提供商。 +Mantis 的首个远程实现应优先通过 Crabbox 使用 AWS。Crabbox 为我们提供预热机器、租约跟踪、补水、日志、结果和清理。如果 AWS 容量太慢或不可用，则在同一机器接口后添加 Hetzner 提供商。 最低 VM 要求： -- Linux，并安装可运行桌面的 Chrome 或 Chromium +- 安装了可用于桌面的 Chrome 或 Chromium 的 Linux - 用于浏览器自动化的 CDP 访问 - 用于救援的 VNC 或 noVNC - Node 22 和 pnpm - OpenClaw 检出和依赖缓存 - 使用 Playwright 时的 Playwright Chromium 浏览器缓存 -- 足够的 CPU 和内存，可运行一个 OpenClaw Gateway 网关、一个浏览器和一次模型运行 +- 足够运行一个 OpenClaw Gateway 网关、一个浏览器和一次模型运行的 CPU 和内存 - 可出站访问 Discord、GitHub、模型提供商和凭证代理 -VM 不应在预期的凭证或浏览器配置文件存储之外保留长期存在的原始密钥。 +VM 不应在预期的凭证或浏览器配置文件存储之外保留长期有效的原始密钥。 ## 密钥 -远程运行的密钥存放在 GitHub 组织或仓库密钥中，本地运行的密钥存放在由本地操作员控制的密钥文件中。 +远程运行的密钥存储在 GitHub 组织或仓库密钥中，本地运行的密钥存储在本地操作员控制的密钥文件中。 推荐的密钥名称： @@ -300,32 +300,32 @@ VM 不应在预期的凭证或浏览器配置文件存储之外保留长期存 - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID` -- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` 用于公开 GitHub 构件上传 +- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`，用于公开 GitHub 工件上传 - `OPENCLAW_QA_CONVEX_SITE_URL` - `OPENCLAW_QA_CONVEX_SECRET_CI` 长期来看，Convex 凭证池应继续作为实时传输凭证的常规来源。GitHub 密钥用于引导代理和备用通道。 -Mantis runner 绝不能打印： +Mantis 运行器绝不能打印： - Discord 机器人令牌 - 提供商 API key -- 浏览器 cookie +- 浏览器 Cookie - 认证配置文件内容 - VNC 密码 - 原始凭证载荷 -公开构件上传还应遮盖 Discord 目标元数据，例如机器人、服务器、频道和消息 ID。GitHub smoke workflow 因此启用了 `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`。 +公开工件上传还应脱敏 Discord 目标元数据，例如机器人、公会、渠道和消息 ID。因此，GitHub 冒烟工作流会启用 `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`。 -如果令牌被意外粘贴到 issue、PR、聊天或日志中，请在新密钥存储后轮换该令牌。 +如果令牌被意外粘贴到 issue、PR、聊天或日志中，请在新密钥已存储后轮换该令牌。 -## GitHub 构件和 PR 评论 +## GitHub 工件和 PR 评论 -Mantis workflow 应将完整证据包上传为短期 Actions 构件。当 workflow 针对 bug 报告或修复 PR 运行时，还应将已遮盖的 PNG 截图发布到 `qa-artifacts` 分支，并在该 bug 或修复 PR 上更新插入一条评论，内联展示修复前/后的截图。不要只把主要证明发布到通用 QA 自动化 PR 上。原始日志、观察到的消息和其他体积较大的证据保留在 Actions 构件中。 +Mantis 工作流应将完整证据包上传为短期 Actions 工件。当工作流针对缺陷报告或修复 PR 运行时，它还应将脱敏后的 PNG 截图发布到 `qa-artifacts` 分支，并在该缺陷或修复 PR 上更新或插入一条评论，包含内联的修复前/修复后截图。不要只在通用 QA 自动化 PR 上发布主要证明。原始日志、观察到的消息和其他大体积证据保留在 Actions 工件中。 -生产 workflow 应使用 Mantis GitHub App 发布这些评论，而不是使用 `github-actions[bot]`。将 app id 和私钥作为 `MANTIS_GITHUB_APP_ID` 与 `MANTIS_GITHUB_APP_PRIVATE_KEY` GitHub Actions 密钥存储。workflow 使用隐藏标记作为更新插入键；当令牌可以编辑该评论时就更新该评论；当较旧的 bot 所有标记无法编辑时，就创建新的 Mantis 所有评论。 +生产工作流应使用 Mantis GitHub App 发布这些评论，而不是使用 `github-actions[bot]`。将应用 ID 和私钥作为 `MANTIS_GITHUB_APP_ID` 和 `MANTIS_GITHUB_APP_PRIVATE_KEY` GitHub Actions 密钥存储。工作流使用隐藏标记作为更新或插入键；当令牌可以编辑评论时更新该评论；当较旧的机器人所有标记无法编辑时，创建一条由 Mantis 拥有的新评论。 -PR 评论应简短且以视觉为主： +PR 评论应简短且可视化： ```md Mantis Discord Status Reactions QA @@ -345,15 +345,15 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -当运行失败是因为 harness 失败时，评论必须说明这一点，而不是暗示候选修复失败。 +当运行因 harness 失败而失败时，评论必须说明这一点，而不是暗示候选修复失败。 ## 私有部署说明 -私有部署可能已经有一个 Mantis Discord 应用。如果该应用具备正确的机器人权限并且可以安全轮换，请复用该应用，而不是创建另一个 app。 +私有部署可能已经有一个 Mantis Discord 应用。如果该应用具备正确的机器人权限并且可以安全轮换，请复用该应用，而不是创建另一个应用。 -通过密钥或部署配置设置初始操作员通知渠道。它可以先指向现有的维护者或运维渠道，等专用 Mantis 渠道存在后再迁移过去。 +通过密钥或部署配置设置初始操作员通知渠道。它可以先指向现有的维护者或运维渠道，然后在专用 Mantis 渠道存在后再迁移过去。 -不要把服务器 ID、频道 ID、机器人令牌、浏览器 cookie 或 VNC 密码放进本文档。将它们存储在 GitHub 密钥、凭证代理或操作员的本地密钥存储中。 +不要将公会 ID、渠道 ID、机器人令牌、浏览器 Cookie 或 VNC 密码放入本文档。请将它们存储在 GitHub 密钥、凭证代理或操作员的本地密钥存储中。 ## 添加场景 @@ -366,39 +366,39 @@ Mantis 场景应声明： - 候选 ref 策略 - OpenClaw 配置补丁 - 设置步骤 -- 激励 +- 刺激输入 - 预期基线判定器 - 预期候选判定器 -- 视觉捕获目标 +- 可视化捕获目标 - 超时预算 - 清理步骤 场景应优先使用小型、带类型的判定器： -- 用于 reaction bug 的 Discord reaction 状态 -- 用于 threading bug 的 Discord 消息引用 -- 用于 Slack bug 的 Slack thread ts 和 reaction API 状态 -- 用于 email bug 的 email 消息 ID 和标头 -- 当 UI 是唯一可靠可观测项时使用浏览器截图 +- 用于 reaction 缺陷的 Discord reaction 状态 +- 用于串线缺陷的 Discord 消息引用 +- 用于 Slack 缺陷的 Slack 线程 ts 和 reaction API 状态 +- 用于电子邮件缺陷的电子邮件消息 ID 和标头 +- 当 UI 是唯一可靠可观察项时的浏览器截图 -视觉检查应作为补充。如果平台 API 能证明 bug，请使用 API 作为通过/失败判定器，并保留截图用于增强人工信心。 +视觉检查应作为增量补充。如果平台 API 可以证明该缺陷，请使用 API 作为通过/失败判定器，并保留截图供人工建立信心。 ## 提供商扩展 -在 Discord 之后，同一个 runner 可以添加： +在 Discord 之后，同一运行器可以添加： -- Slack：reactions、threads、app mentions、modals、file uploads。 -- Email：Gmail 认证，以及在 connectors 不足时使用 `gog` 进行消息 threading。 -- WhatsApp：QR 登录、重新识别、消息投递、媒体、reactions。 -- Telegram：群组 mention gating、commands、可用时的 reactions。 -- Matrix：加密房间、thread 或 reply relations、重启恢复。 +- Slack：reaction、线程、应用提及、模态框、文件上传。 +- 电子邮件：在连接器不足时使用 `gog` 进行 Gmail 认证和消息串线。 +- WhatsApp：二维码登录、重新识别、消息投递、媒体、reaction。 +- Telegram：群组提及门控、命令、可用时的 reaction。 +- Matrix：加密房间、线程或回复关系、重启恢复。 -每种传输协议都应有一个低成本 smoke 场景，以及一个或多个 bug 类别场景。昂贵的视觉场景应保持为选择启用。 +每个传输协议都应有一个低成本冒烟场景，以及一个或多个缺陷类别场景。昂贵的视觉场景应保持为可选启用。 -## 待解决问题 +## 未决问题 -- 复用现有 Mantis bot 时，哪个 Discord bot 应作为 driver，哪个应作为 SUT？ -- 第一阶段的观察者浏览器登录应使用真人 Discord 账号、测试账号，还是只使用 bot 可读取的 REST 证据？ -- GitHub 应为 PR 保留 Mantis 构件多长时间？ -- ClawSweeper 应在什么时候自动推荐 Mantis，而不是等待维护者命令？ -- 公开 PR 上传前是否应遮盖或裁剪截图？ +- 复用现有 Mantis 机器人时，哪个 Discord 机器人应作为驱动方，哪个应作为 SUT？ +- 第一阶段的观察者浏览器登录应使用真人 Discord 账号、测试账号，还是只使用机器人可读的 REST 证据？ +- GitHub 应为 PR 保留 Mantis 工件多久？ +- ClawSweeper 何时应自动推荐 Mantis，而不是等待维护者命令？ +- 对于公开 PR，截图上传前是否应脱敏或裁剪？ diff --git a/docs/zh-CN/security/network-proxy.md b/docs/zh-CN/security/network-proxy.md index 7beb789bd..0cffd533c 100644 --- a/docs/zh-CN/security/network-proxy.md +++ b/docs/zh-CN/security/network-proxy.md @@ -5,36 +5,36 @@ read_when: summary: 如何通过运维方管理的过滤代理路由 OpenClaw 运行时 HTTP 和 WebSocket 流量 title: 网络代理 x-i18n: - generated_at: "2026-05-01T05:23:54Z" + generated_at: "2026-05-04T00:57:17Z" model: gpt-5.5 provider: openai - source_hash: 9207d349e4410e38631ae7665be19b536e4a4128a4e80dd095e802804dfd66a3 + source_hash: cd5594324e8c6b7da51d903e98fda0feacb8970e0b15d980f7a249d6641461c9 source_path: security/network-proxy.md workflow: 16 --- # 网络代理 -OpenClaw 可以通过由运维人员管理的正向代理路由运行时 HTTP 和 WebSocket 流量。对于需要集中式出站控制、更强 SSRF 防护和更好网络可审计性的部署，这是可选的纵深防御措施。 +OpenClaw 可以通过由运维方管理的正向代理来路由运行时 HTTP 和 WebSocket 流量。对于希望集中控制出站流量、增强 SSRF 防护并提升网络可审计性的部署，这是可选的纵深防御措施。 -OpenClaw 不随附、下载、启动、配置或认证代理。你运行适合自己环境的代理技术，OpenClaw 会通过它路由普通的进程本地 HTTP 和 WebSocket 客户端。 +OpenClaw 不会随附、下载、启动、配置或认证代理。你运行适合自己环境的代理技术，OpenClaw 会通过它路由普通的进程内 HTTP 和 WebSocket 客户端流量。 ## 为什么使用代理？ -代理为运维人员提供一个用于出站 HTTP 和 WebSocket 流量的网络控制点。即使在 SSRF 加固之外，这也可能很有用： +代理为运维方提供一个用于出站 HTTP 和 WebSocket 流量的网络控制点。即使不考虑 SSRF 加固，这也可能很有用： -- 集中式策略：维护一个出站策略，而不是依赖每个应用程序 HTTP 调用点都正确处理网络规则。 -- 连接时检查：在 DNS 解析之后、代理打开上游连接之前立即评估目标。 -- DNS 重绑定防护：缩小应用程序级 DNS 检查与实际出站连接之间的间隙。 -- 更广泛的 JavaScript 覆盖范围：通过同一路径路由普通的 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch 以及类似客户端。 -- 可审计性：在出站边界记录允许和拒绝的目标。 -- 运维控制：无需重新构建 OpenClaw 即可强制执行目标规则、网络分段、速率限制或出站 allowlist。 +- 集中策略：维护一套出站策略，而不是依赖每个应用 HTTP 调用点都正确处理网络规则。 +- 连接时检查：在 DNS 解析后、代理打开上游连接之前立即评估目标地址。 +- DNS 重绑定防御：缩小应用级 DNS 检查与实际出站连接之间的空隙。 +- 更广的 JavaScript 覆盖范围：将普通的 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch 以及类似客户端通过同一路径路由。 +- 可审计性：在出站边界记录允许和拒绝的目标地址。 +- 运维控制：无需重新构建 OpenClaw，即可强制执行目标地址规则、网络分段、速率限制或出站允许列表。 -代理路由是针对普通 HTTP 和 WebSocket 出站流量的进程级护栏。它为运维人员提供了一个 fail-closed 路径，用于通过他们自己的过滤代理路由受支持的 JavaScript HTTP 客户端，但它不是操作系统级网络沙箱，也不会让 OpenClaw 认证该代理的目标策略。 +代理路由是针对普通 HTTP 和 WebSocket 出站流量的进程级防护栏。它为运维方提供了一条失败即关闭的路径，用于将受支持的 JavaScript HTTP 客户端通过自己的过滤代理路由，但它不是操作系统级网络沙箱，也不会让 OpenClaw 认证该代理的目标地址策略。 ## OpenClaw 如何路由流量 -当 `proxy.enabled=true` 且已配置代理 URL 时，受保护的运行时进程（例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`）会通过配置的代理路由普通 HTTP 和 WebSocket 出站流量： +当 `proxy.enabled=true` 且配置了代理 URL 时，受保护的运行时进程（例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`）会通过配置的代理路由普通 HTTP 和 WebSocket 出站流量： ```text OpenClaw process @@ -43,27 +43,27 @@ OpenClaw process WebSocket clients -> operator-managed filtering proxy -> public internet ``` -公开契约是路由行为，而不是用于实现它的内部 Node 钩子。当 Gateway 网关 URL 使用 `localhost` 或字面量 loopback IP（例如 `127.0.0.1` 或 `[::1]`）时，OpenClaw Gateway 网关控制平面 WebSocket 客户端会对 local loopback Gateway RPC 流量使用一条狭窄的直连路径。即使运维人员代理阻止 loopback 目标，该控制平面路径也必须能够到达 loopback Gateway 网关。普通运行时 HTTP 和 WebSocket 请求仍会使用已配置的代理。 +公开契约是路由行为，而不是用于实现它的内部 Node 钩子。OpenClaw Gateway 网关控制平面 WebSocket 客户端在 Gateway 网关 URL 使用 `localhost` 或字面量回环 IP（例如 `127.0.0.1` 或 `[::1]`）时，会使用一条狭窄的直连路径处理 local loopback Gateway 网关 RPC 流量。即使运维方代理阻止回环目标地址，该控制平面路径也必须能够访问回环 Gateway 网关。普通运行时 HTTP 和 WebSocket 请求仍会使用配置的代理。 在内部，OpenClaw 为此功能使用两个进程级路由钩子： -- Undici dispatcher 路由覆盖 `fetch`、基于 undici 的客户端，以及提供自有 undici dispatcher 的传输协议。 -- `global-agent` 路由覆盖 Node 核心 `node:http` 和 `node:https` 调用方，包括许多构建在 `http.request`、`https.request`、`http.get` 和 `https.get` 之上的库。托管代理模式会强制使用该全局 agent，因此显式 Node HTTP agent 不会意外绕过运维人员代理。 +- Undici 调度器路由覆盖 `fetch`、基于 undici 的客户端，以及提供自身 undici 调度器的传输协议。 +- `global-agent` 路由覆盖 Node 核心 `node:http` 和 `node:https` 调用方，包括许多基于 `http.request`、`https.request`、`http.get` 和 `https.get` 的库。托管代理模式会强制使用该全局 agent，避免显式 Node HTTP agent 意外绕过运维方代理。 -某些插件拥有自定义传输协议，即使存在进程级路由，也需要显式代理接线。例如，Telegram 的 Bot API 传输协议使用自己的 HTTP/1 undici dispatcher，因此会在该所有者特定的传输路径中遵循进程代理环境以及托管的 `OPENCLAW_PROXY_URL` 回退。 +某些插件拥有自定义传输协议，即使存在进程级路由，也需要显式接入代理。例如，Telegram 的 Bot API 传输使用自己的 HTTP/1 undici 调度器，因此会在该所有者专属传输路径中遵循进程代理环境以及托管的 `OPENCLAW_PROXY_URL` 兜底配置。 -代理 URL 本身必须使用 `http://`。通过代理访问 HTTPS 目标仍受支持，使用 HTTP `CONNECT`；这只表示 OpenClaw 期望一个纯 HTTP 正向代理监听器，例如 `http://127.0.0.1:3128`。 +代理 URL 本身必须使用 `http://`。HTTPS 目标地址仍通过 HTTP `CONNECT` 经由代理受支持；这只表示 OpenClaw 期望一个纯 HTTP 正向代理监听器，例如 `http://127.0.0.1:3128`。 -代理处于活动状态时，OpenClaw 会清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。这些绕过列表基于目标，因此如果把 `localhost` 或 `127.0.0.1` 留在那里，高风险 SSRF 目标就会跳过过滤代理。 +代理处于活动状态时，OpenClaw 会清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。这些绕过列表基于目标地址，因此如果把 `localhost` 或 `127.0.0.1` 留在那里，高风险 SSRF 目标就可以跳过过滤代理。 关闭时，OpenClaw 会恢复先前的代理环境，并重置缓存的进程路由状态。 ## 相关代理术语 - `proxy.enabled` / `proxy.proxyUrl`：用于 OpenClaw 运行时出站流量的出站正向代理路由。本页记录该功能。 -- `gateway.auth.mode: "trusted-proxy"`：用于 Gateway 网关访问的入站身份感知反向代理认证。参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)。 -- `openclaw proxy`：用于开发和支持的本地调试代理与捕获检查器。参见 [openclaw proxy](/zh-CN/cli/proxy)。 -- 渠道或提供商特定的代理设置：针对特定传输协议的所有者特定覆盖。当目标是跨运行时的集中式出站控制时，优先使用托管网络代理。 +- `gateway.auth.mode: "trusted-proxy"`：用于 Gateway 网关访问的入站、身份感知反向代理认证。请参阅[可信代理认证](/zh-CN/gateway/trusted-proxy-auth)。 +- `openclaw proxy`：用于开发和支持的本地调试代理与捕获检查器。请参阅 [openclaw proxy](/zh-CN/cli/proxy)。 +- 渠道或提供商专属代理设置：特定传输协议的所有者专属覆盖项。当目标是在整个运行时集中控制出站流量时，优先使用托管网络代理。 ## 配置 @@ -73,7 +73,7 @@ proxy: proxyUrl: http://127.0.0.1:3128 ``` -你也可以通过环境提供该 URL，同时在配置中保持 `proxy.enabled=true`： +你也可以通过环境提供 URL，同时在配置中保留 `proxy.enabled=true`： ```bash OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run @@ -81,9 +81,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run `proxy.proxyUrl` 优先于 `OPENCLAW_PROXY_URL`。 -如果 `enabled=true` 但没有配置有效的代理 URL，受保护命令会启动失败，而不是回退到直接网络访问。 +如果 `enabled=true` 但未配置有效的代理 URL，受保护命令会启动失败，而不是回退到直接网络访问。 -对于使用 `openclaw gateway start` 启动的托管 Gateway 网关服务，建议将 URL 存储在配置中： +对于通过 `openclaw gateway start` 启动的托管 Gateway 网关服务，建议将 URL 存储在配置中： ```bash openclaw config set proxy.enabled true @@ -92,63 +92,63 @@ openclaw gateway install --force openclaw gateway start ``` -环境回退最适合前台运行。如果你将它用于已安装的服务，请将 `OPENCLAW_PROXY_URL` 放入服务的持久环境中，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然后重新安装该服务，使 launchd、systemd 或 Scheduled Tasks 使用该值启动 gateway。 +环境兜底最适合前台运行。如果你将它用于已安装的服务，请把 `OPENCLAW_PROXY_URL` 放入服务的持久环境中，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然后重新安装该服务，使 launchd、systemd 或计划任务使用该值启动 Gateway 网关。 -对于 `openclaw --container ...` 命令，OpenClaw 会在设置了 `OPENCLAW_PROXY_URL` 时将其转发到面向容器的子 CLI。该 URL 必须能从容器内部访问；`127.0.0.1` 指的是容器本身，而不是宿主机。对于面向容器的命令，OpenClaw 会拒绝 loopback 代理 URL，除非你显式覆盖该安全检查。 +对于 `openclaw --container ...` 命令，当设置了 `OPENCLAW_PROXY_URL` 时，OpenClaw 会将它转发给面向容器的子 CLI。该 URL 必须能从容器内部访问；`127.0.0.1` 指向容器自身，而不是宿主机。除非你显式覆盖该安全检查，否则 OpenClaw 会拒绝面向容器命令中的回环代理 URL。 ## 代理要求 -代理策略是安全边界。OpenClaw 无法验证代理是否阻止了正确的目标。 +代理策略是安全边界。OpenClaw 无法验证该代理是否阻止了正确的目标地址。 -配置代理以： +请将代理配置为： -- 仅绑定到 loopback 或专用受信任接口。 -- 限制访问，使只有 OpenClaw 进程、宿主机、容器或服务账户可以使用它。 -- 自行解析目标，并在 DNS 解析后阻止目标 IP。 -- 对纯 HTTP 请求和 HTTPS `CONNECT` 隧道都在连接时应用策略。 -- 拒绝对 loopback、私有、链路本地、元数据、多播、保留或文档范围的基于目标的绕过。 -- 避免使用主机名 allowlist，除非你完全信任 DNS 解析路径。 -- 记录目标、决策、状态和原因，但不记录请求正文、授权标头、cookie 或其他机密。 -- 将代理策略置于版本控制下，并像审查安全敏感配置一样审查变更。 +- 仅绑定到回环地址或受信任的私有接口。 +- 限制访问，使只有 OpenClaw 进程、主机、容器或服务账号可以使用它。 +- 自行解析目标地址，并在 DNS 解析后阻止目标 IP。 +- 对普通 HTTP 请求和 HTTPS `CONNECT` 隧道都在连接时应用策略。 +- 拒绝针对回环、私有、链路本地、元数据、多播、保留或文档地址范围的基于目标地址绕过。 +- 除非你完全信任 DNS 解析路径，否则避免使用主机名允许列表。 +- 记录目标地址、决策、状态和原因，但不要记录请求体、授权头、Cookie 或其他机密。 +- 将代理策略纳入版本控制，并像审查安全敏感配置一样审查变更。 -## 建议阻止的目标 +## 建议阻止的目标地址 -将此 denylist 用作任何正向代理、防火墙或出站策略的起点。 +将此拒绝列表作为任何正向代理、防火墙或出站策略的起点。 -OpenClaw 应用程序级分类器逻辑位于 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相关的等价钩子是 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及针对 NAT64、6to4、Teredo、ISATAP 和 IPv4-mapped 形式的嵌入式 IPv4 sentinel 处理。维护外部代理策略时，这些文件是有用的参考，但 OpenClaw 不会在你的代理中自动导出或强制执行这些规则。 +OpenClaw 应用级分类器逻辑位于 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相关的等价钩子包括 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及针对 NAT64、6to4、Teredo、ISATAP 和 IPv4 映射形式的嵌入式 IPv4 哨兵处理。维护外部代理策略时，这些文件是有用参考，但 OpenClaw 不会自动导出或在你的代理中强制执行这些规则。 | 范围或主机 | 阻止原因 | | ------------------------------------------------------------------------------------ | ---------------------------------------------------- | -| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback | -| `::1/128` | IPv6 loopback | +| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 回环 | +| `::1/128` | IPv6 回环 | | `0.0.0.0/8`, `::/128` | 未指定地址和本网地址 | | `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC1918 私有网络 | | `169.254.0.0/16`, `fe80::/10` | 链路本地地址和常见云元数据路径 | | `169.254.169.254`, `metadata.google.internal` | 云元数据服务 | | `100.64.0.0/10` | 运营商级 NAT 共享地址空间 | -| `198.18.0.0/15`, `2001:2::/48` | 基准测试范围 | -| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途和文档范围 | +| `198.18.0.0/15`, `2001:2::/48` | 基准测试地址范围 | +| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途和文档地址范围 | | `224.0.0.0/4`, `ff00::/8` | 多播 | | `240.0.0.0/4` | 保留 IPv4 | -| `fc00::/7`, `fec0::/10` | IPv6 本地/私有范围 | -| `100::/64`, `2001:20::/28` | IPv6 discard 和 ORCHIDv2 范围 | +| `fc00::/7`, `fec0::/10` | IPv6 本地/私有地址范围 | +| `100::/64`, `2001:20::/28` | IPv6 丢弃和 ORCHIDv2 地址范围 | | `64:ff9b::/96`, `64:ff9b:1::/48` | 带嵌入式 IPv4 的 NAT64 前缀 | | `2002::/16`, `2001::/32` | 带嵌入式 IPv4 的 6to4 和 Teredo | -| `::/96`, `::ffff:0:0/96` | IPv4-compatible 和 IPv4-mapped IPv6 | +| `::/96`, `::ffff:0:0/96` | IPv4 兼容和 IPv4 映射 IPv6 | -如果你的云提供商或网络平台记录了其他元数据主机或保留范围，也请添加它们。 +如果你的云提供商或网络平台记录了其他元数据主机或保留地址范围，也请一并添加。 ## 验证 -从运行 OpenClaw 的同一宿主机、容器或服务账户验证代理： +从运行 OpenClaw 的同一主机、容器或服务账号验证代理： ```bash openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` -默认情况下，如果未提供自定义目标，该命令会检查 `https://example.com/` 是否成功，并启动一个临时 loopback canary，代理不得访问它。当代理返回非 2xx 拒绝响应，或通过传输失败阻止 canary 时，默认拒绝检查通过；如果成功响应到达 canary，则检查失败。如果未启用并配置代理，验证会报告配置问题；在更改配置前，可使用 `--proxy-url` 进行一次性预检。使用 `--allowed-url` 和 `--denied-url` 测试部署特定的预期。自定义拒绝目标采用 fail-closed：任何 HTTP 响应都表示该目标可通过代理访问，而任何传输错误都会报告为无法确定，因为 OpenClaw 无法证明代理阻止了一个可达来源。验证失败时，该命令以代码 1 退出。 +默认情况下，当没有提供自定义目标地址时，该命令会检查 `https://example.com/` 是否成功，并启动一个临时回环金丝雀，代理不得访问它。当代理返回非 2xx 拒绝响应，或通过传输失败阻止该金丝雀时，默认拒绝检查会通过；如果成功响应到达金丝雀，则检查失败。如果没有启用并配置代理，验证会报告配置问题；在更改配置前，可使用 `--proxy-url` 进行一次性预检。使用 `--allowed-url` 和 `--denied-url` 测试部署专属预期。自定义拒绝目标地址采用失败即关闭语义：任何 HTTP 响应都表示该目标地址可通过代理访问，而任何传输错误都会报告为无法确定，因为 OpenClaw 无法证明代理阻止了一个可访问的源站。验证失败时，该命令以代码 1 退出。 -使用 `--json` 进行自动化。JSON 输出包含总体结果、有效代理配置来源、任何配置错误以及每个目标检查。代理 URL 凭据会在文本和 JSON 输出中被遮蔽： +使用 `--json` 进行自动化。JSON 输出包含总体结果、有效代理配置来源、任何配置错误以及每个目标地址检查。代理 URL 凭证会在文本和 JSON 输出中被遮蔽： ```json { @@ -170,7 +170,7 @@ openclaw proxy validate --proxy-url http://127.0.0.1:3128 } ``` -你也可以用 `curl` 手动验证： +你也可以使用 `curl` 手动验证： ```bash curl -x http://127.0.0.1:3128 https://example.com/ @@ -178,7 +178,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/ curl -x http://127.0.0.1:3128 http://169.254.169.254/ ``` -公共请求应该成功。local loopback 和元数据请求应该被代理阻止。对于 `openclaw proxy validate`，内置的 local loopback 金丝雀可以区分代理拒绝和可访问的源站。自定义 `--denied-url` 检查没有这个金丝雀，因此除非你的代理暴露了可单独验证的部署专用拒绝信号，否则请将 HTTP 响应和模糊的传输失败都视为验证失败。 +公共请求应该成功。回环和元数据请求应该被代理阻止。对于 `openclaw proxy validate`，内置的回环 canary 可以区分代理拒绝和可访问的源站。自定义 `--denied-url` 检查没有这个 canary，因此除非你的代理公开了可单独验证的部署特定拒绝信号，否则应将 HTTP 响应和不明确的传输失败都视为验证失败。 然后启用 OpenClaw 代理路由： @@ -198,9 +198,10 @@ proxy: ## 限制 -- 代理提升了进程本地 JavaScript HTTP 和 WebSocket 客户端的覆盖范围，但它不是操作系统级网络沙箱。 -- 原始 `net`、`tls` 和 `http2` 套接字、原生插件以及子进程可能绕过 Node 级代理路由，除非它们继承并遵循代理环境变量。 -- 需要时，用户本地 WebUI 和本地模型服务器应在操作员代理策略中加入允许列表；OpenClaw 不会为它们暴露通用的本地网络绕过能力。 -- Gateway 网关控制平面的代理绕过被有意限制为 `localhost` 和字面量回环 IP URL。对于本地直连 Gateway 网关控制平面连接，请使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789`；其他主机名会像普通的基于主机名的流量一样路由。 +- 代理提高了进程本地 JavaScript HTTP 和 WebSocket 客户端的覆盖范围，但它不是操作系统级网络沙箱。 +- 原始 `net`、`tls` 和 `http2` 套接字、原生插件以及子进程可能会绕过 Node 级代理路由，除非它们继承并遵守代理环境变量。 +- IRC 是一个原始 TCP/TLS 渠道，位于操作员管理的正向代理路由之外。在要求所有出口流量都通过该正向代理的部署中，除非已明确批准直接 IRC 出口流量，否则请设置 `channels.irc.enabled=false`。 +- 需要时，应在操作员代理策略中将用户本地 WebUI 和本地模型服务器加入允许列表；OpenClaw 不会为它们公开通用的本地网络绕过机制。 +- Gateway 网关控制平面代理绕过被有意限制为 `localhost` 和字面量回环 IP URL。对于本地直接 Gateway 网关控制平面连接，请使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789`；其他主机名会像普通基于主机名的流量一样路由。 - OpenClaw 不会检查、测试或认证你的代理策略。 -- 请将代理策略变更视为安全敏感的运维变更。 +- 将代理策略变更视为安全敏感的操作变更。