diff --git a/docs/zh-CN/concepts/streaming.md b/docs/zh-CN/concepts/streaming.md index feab3415b..e866183c5 100644 --- a/docs/zh-CN/concepts/streaming.md +++ b/docs/zh-CN/concepts/streaming.md @@ -1,15 +1,15 @@ --- read_when: - - 解释渠道上的流式传输或分块处理如何工作 + - 说明流式传输或分块处理在渠道中的工作方式 - 更改分块流式传输或渠道分块处理行为 - - 调试重复/过早的分块回复或渠道预览流式传输 + - 调试重复或过早的分块回复或渠道预览流式传输 summary: 流式传输 + 分块处理行为（分块回复、渠道预览流式传输、模式映射） title: 流式传输与分块处理 x-i18n: - generated_at: "2026-04-21T20:11:34Z" + generated_at: "2026-04-21T20:41:40Z" model: gpt-5.4 provider: openai - source_hash: ca91815fb44c0d0283dcfbcec44fb016e07a841e538b5cb4baab18d441a86730 + source_hash: e550c13ce180bf8f72fced4071926bfe8d24dfb1a419c19c51a64eb9ff216ff1 source_path: concepts/streaming.md workflow: 15 --- @@ -18,14 +18,14 @@ x-i18n: OpenClaw 有两个彼此独立的流式传输层： -- **分块流式传输（渠道）：** 在助手写入时，输出已完成的**块**。这些是普通的渠道消息（不是 token 增量）。 -- **预览流式传输（Telegram/Discord/Slack）：** 在生成过程中更新一条临时的**预览消息**。 +- **分块流式传输（渠道）：** 在助手写作过程中，随着完整的 **块** 生成而发出。这些是普通的渠道消息（不是 token 增量）。 +- **预览流式传输（Telegram/Discord/Slack）：** 在生成过程中更新一条临时的 **预览消息**。 -目前**没有真正的 token 增量流式传输**发送到渠道消息。预览流式传输是基于消息的（发送 + 编辑/追加）。 +目前，渠道消息**不支持真正的 token 增量流式传输**。预览流式传输是基于消息的（发送 + 编辑/追加）。 ## 分块流式传输（渠道消息） -分块流式传输会在助手输出可用时，以较粗粒度的分段发送。 +分块流式传输会在助手输出可用时，以较粗粒度的分块发送内容。 ``` Model output @@ -39,75 +39,76 @@ Model output 图例： -- `text_delta/events`：模型流事件（对于非流式模型，事件可能很稀疏）。 -- `chunker`：`EmbeddedBlockChunker`，应用最小/最大边界 + 断点偏好。 -- `channel send`：实际发出的消息（分块回复）。 +- `text_delta/events`：模型流事件（对于非流式模型，可能较为稀疏）。 +- `chunker`：应用最小/最大边界 + 断点偏好的 `EmbeddedBlockChunker`。 +- `channel send`：实际发出的出站消息（分块回复）。 **控制项：** - `agents.defaults.blockStreamingDefault`：`"on"`/`"off"`（默认关闭）。 -- 渠道覆盖：`*.blockStreaming`（以及按账户划分的变体），可按渠道强制设为 `"on"`/`"off"`。 +- 渠道覆盖：`*.blockStreaming`（以及每账号变体）可为每个渠道强制设为 `"on"`/`"off"`。 - `agents.defaults.blockStreamingBreak`：`"text_end"` 或 `"message_end"`。 - `agents.defaults.blockStreamingChunk`：`{ minChars, maxChars, breakPreference? }`。 -- `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（在发送前合并流式块）。 +- `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（发送前合并流式块）。 - 渠道硬上限：`*.textChunkLimit`（例如 `channels.whatsapp.textChunkLimit`）。 -- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 会先按空行〔段落边界〕拆分，再按长度分块）。 -- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17），会拆分过高的回复以避免 UI 截断。 +- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 会先按空行即段落边界拆分，再按长度分块）。 +- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17），会拆分过高的回复以避免 UI 裁切。 **边界语义：** -- `text_end`：一旦 chunker 输出块就立即流式发送；在每个 `text_end` 时刷新。 +- `text_end`：只要 chunker 发出块就立即流式发送；在每个 `text_end` 时刷新。 - `message_end`：等待助手消息完成后，再刷新缓冲输出。 -即使是 `message_end`，如果缓冲文本超过 `maxChars`，仍然会使用 chunker，因此它可能在结尾输出多个分块。 +即使使用 `message_end`，如果缓冲文本超过 `maxChars`，仍会使用 chunker，因此它可以在结束时发出多个分块。 ## 分块算法（低/高边界） -分块处理由 `EmbeddedBlockChunker` 实现： +分块流式传输由 `EmbeddedBlockChunker` 实现： -- **低边界：** 在缓冲区达到 `minChars` 之前不输出（除非被强制输出）。 -- **高边界：** 优先在 `maxChars` 之前拆分；如果必须强制拆分，就在 `maxChars` 处切分。 +- **低边界：** 在缓冲区达到 `minChars` 之前不发出内容（除非被强制）。 +- **高边界：** 优先在 `maxChars` 之前拆分；如果必须强制拆分，则在 `maxChars` 处切分。 - **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬拆分。 -- **代码围栏：** 绝不在围栏内部拆分；如果必须在 `maxChars` 处强制拆分，会先闭合再重新打开围栏，以保持 Markdown 有效。 +- **代码围栏：** 绝不在围栏内部拆分；如果必须在 `maxChars` 处强制拆分，会关闭并重新打开围栏以保持 Markdown 有效。 -`maxChars` 会被限制在渠道的 `textChunkLimit` 以内，因此你不能超过各渠道的上限。 +`maxChars` 会被限制到渠道的 `textChunkLimit`，因此你不能超过每个渠道的上限。 -## 合并（合并流式块） +## 合并发送（合并流式块） -启用分块流式传输时，OpenClaw 可以在发送前**合并连续的分块**。 -这样既能保留渐进式输出，又能减少“单行刷屏”。 +启用分块流式传输时，OpenClaw 可以在发送前**合并连续的分块内容**。 +这样既能提供渐进式输出，又能减少“单行刷屏”。 - 合并会等待**空闲间隔**（`idleMs`）后再刷新。 - 缓冲区受 `maxChars` 限制，超过时会立即刷新。 -- `minChars` 会阻止过小的片段过早发送，直到累积足够文本 - （最终刷新时始终会发送剩余文本）。 -- 连接符由 `blockStreamingChunk.breakPreference` 推导而来 - （`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。 -- 可通过 `*.blockStreamingCoalesce` 提供渠道级覆盖（包括按账户配置）。 -- 除非另有覆盖，对于 Signal/Slack/Discord，默认合并 `minChars` 会提升到 1500。 +- `minChars` 可防止过小碎片被发送，直到累计了足够文本 + （最终刷新时总会发送剩余文本）。 +- 连接符由 `blockStreamingChunk.breakPreference` + 推导得出（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。 +- 可通过 `*.blockStreamingCoalesce` 提供渠道级覆盖（包括每账号配置）。 +- 对于 Signal/Slack/Discord，默认的合并 `minChars` 会提升到 1500，除非另有覆盖。 -## 块之间的人类式节奏 +## 分块之间更像人类的节奏 -启用分块流式传输时，你可以在各个分块回复之间加入**随机暂停** -（首个分块之后）。这会让多气泡回复显得更自然。 +启用分块流式传输时，你可以在 +分块回复之间（首个分块之后）加入**随机暂停**。这会让多气泡回复感觉 +更自然。 -- 配置：`agents.defaults.humanDelay`（可通过 `agents.list[].humanDelay` 按智能体覆盖）。 +- 配置：`agents.defaults.humanDelay`（可通过 `agents.list[].humanDelay` 为每个智能体覆盖）。 - 模式：`off`（默认）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。 - 仅适用于**分块回复**，不适用于最终回复或工具摘要。 -## “流式输出分块”还是“最后一次性输出” +## “流式发送分块”还是“最后一次性发送” -这对应到： +它映射为： -- **流式输出分块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边输出）。非 Telegram 渠道还需要 `*.blockStreaming: true`。 -- **在结尾一次性输出全部：** `blockStreamingBreak: "message_end"`（只在最后刷新一次；如果内容很长，可能仍会拆成多个分块）。 -- **不使用分块流式传输：** `blockStreamingDefault: "off"`（只发送最终回复）。 +- **流式发送分块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发出）。非 Telegram 渠道还需要设置 `*.blockStreaming: true`。 +- **在结尾一次性流式发送全部内容：** `blockStreamingBreak: "message_end"`（只刷新一次；如果内容很长，可能仍会拆成多个分块）。 +- **不启用分块流式传输：** `blockStreamingDefault: "off"`（只发送最终回复）。 -**渠道说明：** 只有在明确设置 -`*.blockStreaming: true` 时，才会启用分块流式传输。渠道可以在没有分块回复的情况下启用实时预览 -（`channels..streaming`）。 +**渠道说明：** 除非 +显式将 `*.blockStreaming` 设为 `true`，否则分块流式传输**默认关闭**。渠道即使没有分块回复，也可以通过 +`channels..streaming` 流式显示实时预览。 -配置位置提醒：`blockStreaming*` 默认值位于 `agents.defaults` 下，而不是根配置。 +配置位置提醒：`blockStreaming*` 默认项位于 `agents.defaults` 下，而不是根配置。 ## 预览流式传输模式 @@ -116,9 +117,9 @@ Model output 模式： - `off`：禁用预览流式传输。 -- `partial`：使用单个预览，用最新文本替换其内容。 -- `block`：以分块/追加的方式更新预览。 -- `progress`：生成期间显示进度/状态预览，完成时输出最终答案。 +- `partial`：使用单个预览，并用最新文本替换它。 +- `block`：以分块/追加的方式逐步更新预览。 +- `progress`：在生成期间显示进度/状态预览，完成时发送最终答案。 ### 渠道映射 @@ -129,44 +130,54 @@ Model output | Slack | ✅ | ✅ | ✅ | ✅ | | Mattermost | ✅ | ✅ | ✅ | ✅ | -仅限 Slack： +仅 Slack： -- 当 `channels.slack.streaming.mode="partial"` 时，`channels.slack.streaming.nativeTransport` 用于切换 Slack 原生流式 API 调用（默认：`true`）。 -- Slack 原生流式传输以及 Slack 助手线程状态都需要一个回复线程目标；顶层私信不会显示这种线程式预览。 +- `channels.slack.streaming.nativeTransport` 在 `channels.slack.streaming.mode="partial"` 时切换 Slack 原生流式 API 调用（默认：`true`）。 +- Slack 原生流式传输和 Slack 助手线程状态都需要一个回复线程目标；顶级私信不会显示这种线程式预览。 旧键迁移： -- Telegram：`streamMode` + 布尔值 `streaming` 会自动迁移到 `streaming` 枚举。 -- Discord：`streamMode` + 布尔值 `streaming` 会自动迁移到 `streaming` 枚举。 -- Slack：`streamMode` 会自动迁移到 `streaming.mode`；布尔值 `streaming` 会自动迁移到 `streaming.mode` + `streaming.nativeTransport`；旧版 `nativeStreaming` 会自动迁移到 `streaming.nativeTransport`。 +- Telegram：`streamMode` + 布尔型 `streaming` 会自动迁移到 `streaming` 枚举。 +- Discord：`streamMode` + 布尔型 `streaming` 会自动迁移到 `streaming` 枚举。 +- Slack：`streamMode` 会自动迁移到 `streaming.mode`；布尔型 `streaming` 会自动迁移到 `streaming.mode` 加 `streaming.nativeTransport`；旧版 `nativeStreaming` 会自动迁移到 `streaming.nativeTransport`。 ### 运行时行为 Telegram： -- 在私信和群组/话题中，使用 `sendMessage` + `editMessageText` 更新预览。 -- 当明确启用了 Telegram 分块流式传输时，会跳过预览流式传输（以避免双重流式传输）。 +- 在私信和群组/话题中使用 `sendMessage` + `editMessageText` 更新预览。 +- 如果显式启用了 Telegram 分块流式传输，则会跳过预览流式传输（以避免双重流式传输）。 - `/reasoning stream` 可以将推理内容写入预览。 Discord： - 使用发送 + 编辑预览消息。 - `block` 模式使用草稿分块（`draftChunk`）。 -- 当明确启用了 Discord 分块流式传输时，会跳过预览流式传输。 +- 如果显式启用了 Discord 分块流式传输，则会跳过预览流式传输。 Slack： - `partial` 在可用时可使用 Slack 原生流式传输（`chat.startStream`/`append`/`stop`）。 - `block` 使用追加式草稿预览。 -- `progress` 使用状态预览文本，然后输出最终答案。 +- `progress` 使用状态预览文本，然后发送最终答案。 Mattermost： -- 将思考、工具活动和部分回复文本流式写入单条草稿预览帖子，并在最终答案可安全发送时原地完成该帖子。 -- 如果预览帖子已被删除或在最终完成时不可用，则回退为发送一条新的最终帖子。 +- 将 thinking、工具活动和部分回复文本流式写入单个草稿预览帖子，并在最终答案可安全发送时原地完成。 +- 如果在完成时预览帖子已被删除或因其他原因不可用，则回退为发送一条新的最终帖子。 + +### 工具进度预览更新 + +预览流式传输还可以包含**工具进度**更新——例如“正在搜索网络”“正在读取文件”或“正在调用工具”之类的简短状态行——这些内容会在工具运行期间显示在同一条预览消息中，先于最终回复出现。这样，多步骤的工具回合在视觉上会保持活跃，而不是在首次 thinking 预览和最终答案之间显得沉默。 + +支持的界面： + +- **Discord**、**Slack** 和 **Telegram** 会将工具进度流式写入实时预览编辑中。 +- **Mattermost** 已经将工具活动整合进其单一草稿预览帖子中（见上文）。 +- 工具进度编辑遵循当前启用的预览流式传输模式；当预览流式传输为 `off`，或当分块流式传输已接管该消息时，会跳过这些更新。 ## 相关内容 -- [Messages](/zh-CN/concepts/messages) —— 消息生命周期与投递 -- [Retry](/zh-CN/concepts/retry) —— 投递失败时的重试行为 -- [Channels](/zh-CN/channels) —— 各渠道的流式传输支持 +- [消息](/zh-CN/concepts/messages) — 消息生命周期与投递 +- [重试](/zh-CN/concepts/retry) — 投递失败时的重试行为 +- [渠道](/zh-CN/channels) — 每个渠道的流式传输支持 diff --git a/docs/zh-CN/gateway/security/index.md b/docs/zh-CN/gateway/security/index.md index db1354d84..617ce1f48 100644 --- a/docs/zh-CN/gateway/security/index.md +++ b/docs/zh-CN/gateway/security/index.md @@ -1,43 +1,43 @@ --- read_when: - - 添加会扩大访问范围或自动化能力的功能 -summary: 运行具备 shell 访问权限的 AI Gateway 网关时的安全注意事项和威胁模型 -title: 安全 + - 添加会扩大访问范围或自动化程度的功能 +summary: 运行具有 shell 访问权限的 AI Gateway 网关时的安全注意事项和威胁模型 +title: 安全性 x-i18n: - generated_at: "2026-04-21T20:23:16Z" + generated_at: "2026-04-21T20:41:36Z" model: gpt-5.4 provider: openai - source_hash: 5b03edb022fac8b0fb4ba6e98a8a07434e46a51056df828bcf0be3f220b63cfe + source_hash: 1031e4ba0865f4109c92461ff6c4597928f3aeddfa7ac377a968fb1f16a642d9 source_path: gateway/security/index.md workflow: 15 --- -# 安全 +# 安全性 -**个人助手信任模型：**本指南假设每个 Gateway 网关只有一个受信任的操作员边界（单用户/个人助手模型）。 -OpenClaw **不是**一个适用于多个对抗性用户共享同一个智能体/Gateway 网关的敌对多租户安全边界。 -如果你需要混合信任或对抗性用户场景，请拆分信任边界（单独的 Gateway 网关 + 凭证，最好再配合单独的 OS 用户/主机）。 +**个人助理信任模型：**本指南假设每个 Gateway 网关对应一个受信任的操作员边界（单用户/个人助理模型）。 +OpenClaw **不是**为多个对抗性用户共享同一个智能体/Gateway 网关而设计的恶意多租户安全边界。 +如果你需要混合信任或对抗性用户运行方式，请拆分信任边界（单独的 Gateway 网关 + 凭证，理想情况下再配合单独的 OS 用户/主机）。 **本页内容：**[信任模型](#scope-first-personal-assistant-security-model) | [快速审计](#quick-check-openclaw-security-audit) | [强化基线](#hardened-baseline-in-60-seconds) | [私信访问模型](#dm-access-model-pairing-allowlist-open-disabled) | [配置加固](#configuration-hardening-examples) | [事件响应](#incident-response) -## 首先明确范围：个人助手安全模型 +## 先明确范围：个人助理安全模型 -OpenClaw 的安全指南假设的是一种**个人助手**部署：一个受信任的操作员边界，可能有多个智能体。 +OpenClaw 的安全指南假设采用**个人助理**部署方式：一个受信任的操作员边界，可能对应多个智能体。 - 支持的安全姿态：每个 Gateway 网关对应一个用户/信任边界（最好每个边界使用一个 OS 用户/主机/VPS）。 -- 不受支持的安全边界：多个彼此不受信任或具有对抗关系的用户共享一个 Gateway 网关/智能体。 -- 如果需要对抗性用户隔离，请按信任边界拆分（单独的 Gateway 网关 + 凭证，最好再配合单独的 OS 用户/主机）。 -- 如果多个不受信任的用户都可以向同一个启用了工具的智能体发消息，应视为他们共享该智能体的同一组委派工具权限。 +- 不支持作为安全边界的场景：多个彼此不信任或具有对抗性的用户共享同一个 Gateway 网关/智能体。 +- 如果需要对抗性用户隔离，请按信任边界拆分（单独的 Gateway 网关 + 凭证，理想情况下再配合单独的 OS 用户/主机）。 +- 如果多个不受信任的用户都能给同一个启用了工具的智能体发消息，应将他们视为共享该智能体相同委托工具权限的用户。 -本页说明的是**在该模型内**如何进行加固。它并不声称在单个共享 Gateway 网关上提供敌对多租户隔离。 +本页解释的是**在这一模型之内**如何进行加固。它并不声称单个共享 Gateway 网关能够提供恶意多租户隔离。 ## 快速检查：`openclaw security audit` -另请参阅：[Formal Verification（安全模型）](/zh-CN/security/formal-verification) +另请参阅：[形式化验证（安全模型）](/zh-CN/security/formal-verification) -请定期运行此命令（尤其是在修改配置或暴露网络接口之后）： +请定期运行这个命令（尤其是在修改配置或暴露网络接口后）： ```bash openclaw security audit @@ -46,103 +46,103 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` 的修复范围有意保持较窄：它会把常见的开放群组策略切换为 allowlist，恢复 `logging.redactSensitive: "tools"`，收紧 state/config/include-file 的权限，并且在 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 网关（或至少单独的 OS 用户/主机）拆分信任边界。 -- 推荐默认方式：每台机器/主机（或 VPS）一个用户，该用户一个 Gateway 网关，该 Gateway 网关内可包含一个或多个智能体。 -- 在同一个 Gateway 网关实例内，经过认证的操作员访问属于受信任的控制平面角色，而不是按用户划分的租户角色。 -- 会话标识符（`sessionKey`、会话 ID、标签）是路由选择器，不是授权令牌。 -- 如果多个人都可以向同一个启用了工具的智能体发消息，那么他们每个人都能驱动同一组权限。按用户划分的会话/记忆隔离有助于保护隐私，但不会把一个共享智能体变成按用户划分的主机授权边界。 +- 让多个彼此不信任/具有对抗性的操作员运行同一个 Gateway 网关，**不是推荐配置**。 +- 对于混合信任团队，请使用单独的 Gateway 网关 来拆分信任边界（或者至少使用单独的 OS 用户/主机）。 +- 推荐默认方式：每台机器/主机（或 VPS）一个用户，该用户对应一个 Gateway 网关，该 Gateway 网关中运行一个或多个智能体。 +- 在同一个 Gateway 网关实例内，已认证的操作员访问属于受信任的控制平面角色，而不是按用户划分的租户角色。 +- 会话标识符（`sessionKey`、session ID、标签）是路由选择器，不是授权令牌。 +- 如果多人都能给同一个启用了工具的智能体发消息，那么他们每个人都能驱动同一套权限。按用户隔离 session / memory 有助于保护隐私，但并不能把共享智能体变成按用户划分的主机授权边界。 ### 共享 Slack 工作区：真实风险 -如果“Slack 里的所有人都能给机器人发消息”，核心风险是委派工具权限： +如果“Slack 里的任何人都能给机器人发消息”，核心风险是委托工具权限： -- 任何被允许的发送者都可以在该智能体策略范围内诱发工具调用（`exec`、浏览器、网络/文件工具）； -- 来自某个发送者的提示词/内容注入，可能导致影响共享状态、设备或输出的操作； -- 如果某个共享智能体持有敏感凭证/文件，任何被允许的发送者都可能通过工具使用驱动数据外泄。 +- 任何被允许的发送者都可以在该智能体的策略范围内诱发工具调用（`exec`、浏览器、网络/文件工具）； +- 某个发送者的提示词/内容注入可能引发影响共享状态、设备或输出的操作； +- 如果一个共享智能体持有敏感凭证/文件，任何被允许的发送者都可能通过工具使用来驱动数据外泄。 -对于团队工作流，请使用工具最少、彼此分离的智能体/Gateway 网关；将处理个人数据的智能体保持为私有。 +对于团队工作流，请使用单独的、工具最少化的智能体/Gateway 网关；把涉及个人数据的智能体保持为私有。 -### 公司共享智能体：可接受的模式 +### 公司共享智能体：可接受模式 当使用该智能体的所有人都处于同一个信任边界内（例如同一个公司团队），并且该智能体严格限定在业务范围内时，这种模式是可接受的。 - 在专用机器/VM/容器上运行它； -- 为该运行时使用专用 OS 用户 + 专用浏览器/配置文件/账号； -- 不要让该运行时登录个人 Apple/Google 账号，也不要使用个人密码管理器/浏览器配置文件。 +- 为该运行时使用专用的 OS 用户 + 专用浏览器/配置文件/账号； +- 不要让该运行时登录你的个人 Apple/Google 账号，或个人密码管理器/浏览器配置文件。 -如果你在同一个运行时中混用个人身份和公司身份，就会破坏这种隔离，并增加个人数据暴露风险。 +如果你在同一个运行时中混用个人身份和公司身份，就会打破这种隔离，并增加个人数据暴露的风险。 -## Gateway 网关与节点的信任概念 +## Gateway 网关与节点信任概念 应将 Gateway 网关和节点视为同一个操作员信任域中的不同角色： -- **Gateway 网关**是控制平面和策略界面（`gateway.auth`、工具策略、路由）。 -- **节点**是与该 Gateway 网关配对的远程执行界面（命令、设备操作、主机本地能力）。 -- 通过 Gateway 网关认证的调用方，在 Gateway 网关范围内被视为受信任。完成配对后，节点操作被视为该节点上的受信任操作员行为。 -- `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"`，除非你手动收紧）。这个默认值是有意设计的用户体验，不应被单独视为漏洞。 +- Exec 审批会绑定精确的请求上下文以及尽力识别的直接本地文件操作数；它不会对每一种运行时/解释器加载路径做语义建模。如果你需要更强边界，请使用沙箱隔离和主机隔离。 -如果你需要敌对用户隔离，请按 OS 用户/主机拆分信任边界，并运行单独的 Gateway 网关。 +如果你需要恶意用户隔离，请按 OS 用户/主机拆分信任边界，并运行单独的 Gateway 网关。 ## 信任边界矩阵 -在进行风险研判时，可将其作为快速模型： +在评估风险时，可将下表作为快速模型： | 边界或控制项 | 含义 | 常见误解 | | --- | --- | --- | -| `gateway.auth`（token/password/trusted-proxy/device auth） | 对 Gateway 网关 API 的调用方进行认证 | “要安全就必须对每一帧消息都做逐条签名” | -| `sessionKey` | 用于上下文/会话选择的路由键 | “会话键本身就是用户认证边界” | -| 提示词/内容护栏 | 降低模型被滥用的风险 | “只要有提示词注入就等于认证绕过” | -| `canvas.eval` / 浏览器 evaluate | 启用后属于有意开放给操作员的能力 | “任何 JS eval 原语在这个信任模型下都会自动成为漏洞” | +| `gateway.auth`（token/password/trusted-proxy/device auth） | 对调用方访问 Gateway 网关 API 进行认证 | “要想安全，每一帧消息都必须做逐消息签名” | +| `sessionKey` | 用于上下文/session 选择的路由键 | “Session key 就是用户认证边界” | +| 提示词/内容防护 | 降低模型被滥用的风险 | “只要有提示词注入，就等于认证绕过” | +| `canvas.eval` / 浏览器 evaluate | 启用后属于有意提供给操作员的能力 | “任何 JS eval 原语在这个信任模型里都自动算漏洞” | | 本地 TUI `!` shell | 由操作员显式触发的本地执行 | “本地 shell 便捷命令就是远程注入” | -| 节点配对与节点命令 | 在已配对设备上的操作员级远程执行 | “默认就应该把远程设备控制视为不受信任的用户访问” | +| 节点配对和节点命令 | 对已配对设备的操作员级远程执行 | “远程设备控制默认就应被视为不受信任用户访问” | ## 按设计不属于漏洞的情况 -以下模式经常被报告，但通常会被判定为无需处理，除非能够证明存在真实的边界绕过： +这些模式经常被报告，但如果没有展示真实边界绕过，通常会被关闭且不采取措施： -- 仅包含提示词注入链，但没有策略/认证/沙箱隔离绕过。 -- 假定在一个共享主机/配置上运行敌对多租户的相关说法。 -- 在共享 Gateway 网关配置中，把正常的操作员读取路径访问（例如 `sessions.list`/`sessions.preview`/`chat.history`）归类为 IDOR 的说法。 -- 仅限 localhost 的部署问题（例如仅 loopback Gateway 网关上的 HSTS）。 +- 仅依赖提示词注入链，但没有策略/认证/沙箱绕过。 +- 假设在同一共享主机/配置上存在恶意多租户运行的说法。 +- 在共享 Gateway 网关配置中，把正常的操作员读取路径（例如 `sessions.list` / `sessions.preview` / `chat.history`）归类为 IDOR 的说法。 +- 仅限 localhost 的部署问题（例如只绑定 loopback 的 Gateway 网关缺少 HSTS）。 - 针对本仓库中并不存在的入站路径而提出的 Discord 入站 webhook 签名问题。 -- 将节点配对元数据视为 `system.run` 的隐藏第二层逐命令审批机制的报告，而实际执行边界仍然是 Gateway 网关的全局节点命令策略加上节点自身的 exec 审批。 -- 把 `sessionKey` 当作认证令牌，从而得出“缺少按用户授权”的结论。 +- 将节点配对元数据误认为 `system.run` 的隐藏第二层逐命令审批机制，而真实执行边界实际上仍然是 Gateway 网关的全局节点命令策略加上节点自身的 exec 审批。 +- 把 `sessionKey` 当作认证令牌来报告“缺少按用户授权”的问题。 ## 研究人员预检清单 -在创建 GHSA 之前，请确认以下各项： +在提交 GHSA 之前，请确认以下各项： -1. 在最新的 `main` 或最新发布版本上，复现仍然成立。 -2. 报告包含精确的代码路径（`file`、函数、行范围）以及测试所用版本/commit。 -3. 影响跨越了已记录的信任边界，而不只是提示词注入。 -4. 该问题不在 [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope) 列表中。 -5. 已检查现有 advisory 是否重复（适用时复用规范的 GHSA）。 -6. 已明确部署假设（loopback/本地 vs 对外暴露，受信任 vs 不受信任操作员）。 +1. 在最新 `main` 或最新发布版本上，复现仍然有效。 +2. 报告中包含精确的代码路径（`file`、函数、行范围）以及测试版本/commit。 +3. 影响跨越了某个文档化的信任边界（而不仅仅是提示词注入）。 +4. 该问题不在 [超出范围](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope) 列表中。 +5. 已检查现有 advisory 是否重复（适用时请复用规范 GHSA）。 +6. 已明确部署假设（loopback / 本地，还是对外暴露；受信任操作员，还是不受信任操作员）。 -## 60 秒内完成的强化基线 +## 60 秒建立强化基线 -先使用此基线，然后再按受信任智能体逐项重新启用所需工具： +先使用这个基线，再按受信任智能体选择性重新启用工具： ```json5 { @@ -167,61 +167,61 @@ OpenClaw 假定主机和配置边界是受信任的： } ``` -这样可以让 Gateway 网关仅限本地访问、隔离私信，并默认禁用控制平面/运行时工具。 +这样会让 Gateway 网关仅限本地访问、隔离私信，并默认禁用控制平面/运行时工具。 ## 共享收件箱快速规则 -如果有不止一个人可以给你的机器人发私信： +如果不止一个人可以给你的机器人发私信： -- 设置 `session.dmScope: "per-channel-peer"`（对于多账号渠道则使用 `"per-account-channel-peer"`）。 -- 保持 `dmPolicy: "pairing"` 或使用严格的 allowlist。 -- 绝不要把共享私信和宽泛的工具访问权限组合在一起。 -- 这有助于加固协作式/共享收件箱，但在多个用户共享主机/配置写权限时，它并不是为敌对共租户隔离而设计的。 +- 设置 `session.dmScope: "per-channel-peer"`（多账号渠道则使用 `"per-account-channel-peer"`）。 +- 保持 `dmPolicy: "pairing"` 或严格的 allowlist。 +- 绝不要把共享私信与广泛的工具访问权限结合起来。 +- 这可以加固协作式/共享收件箱，但当用户共享主机/配置写权限时，它并不是为恶意协同租户隔离而设计的。 ## 上下文可见性模型 OpenClaw 区分两个概念： -- **触发授权**：谁可以触发该智能体（`dmPolicy`、`groupPolicy`、allowlist、提及门控）。 +- **触发授权**：谁可以触发智能体（`dmPolicy`、`groupPolicy`、allowlist、mention 门槛）。 - **上下文可见性**：哪些补充上下文会被注入到模型输入中（回复正文、引用文本、线程历史、转发元数据）。 -Allowlists 用于控制触发和命令授权。`contextVisibility` 设置则控制补充上下文（引用回复、线程根消息、拉取的历史记录）如何被过滤： +Allowlist 控制触发和命令授权。`contextVisibility` 设置控制如何过滤补充上下文（引用回复、线程根消息、拉取的历史记录）： -- `contextVisibility: "all"`（默认）会按接收到的原样保留补充上下文。 -- `contextVisibility: "allowlist"` 会将补充上下文过滤为仅包含通过当前 allowlist 检查的发送者内容。 -- `contextVisibility: "allowlist_quote"` 的行为与 `allowlist` 类似，但仍会保留一条明确引用的回复。 +- `contextVisibility: "all"`（默认）保留收到的全部补充上下文。 +- `contextVisibility: "allowlist"` 会根据当前生效的 allowlist 检查结果，过滤补充上下文，仅保留被允许发送者的内容。 +- `contextVisibility: "allowlist_quote"` 的行为类似 `allowlist`，但仍会保留一个显式引用的回复。 -你可以按渠道或按房间/会话设置 `contextVisibility`。具体配置方法请参阅[群聊](/zh-CN/channels/groups#context-visibility-and-allowlists)。 +你可以按渠道或按房间/会话设置 `contextVisibility`。配置细节请参阅[群聊](/zh-CN/channels/groups#context-visibility-and-allowlists)。 -Advisory 分诊指引： +Advisory 分流指南： -- 如果报告仅证明“模型能够看到来自未列入 allowlist 的发送者的引用文本或历史文本”，这属于可通过 `contextVisibility` 解决的加固问题，而不是认证或沙箱边界绕过本身。 -- 若要构成真正的安全影响，报告仍需证明存在信任边界绕过（认证、策略、沙箱隔离、审批，或其他已记录的边界）。 +- 如果报告只展示了“模型可以看到来自未列入 allowlist 的发送者的引用文本或历史文本”，这属于可通过 `contextVisibility` 解决的加固发现，本身不构成认证或沙箱边界绕过。 +- 要构成真正的安全影响，报告仍需证明存在信任边界绕过（认证、策略、沙箱、审批，或其他文档化边界）。 -## 审计会检查什么（高层概述） +## 审计会检查什么（高级概览） - **入站访问**（私信策略、群组策略、allowlist）：陌生人能否触发机器人？ -- **工具影响半径**（高权限工具 + 开放房间）：提示词注入是否可能演变为 shell/文件/网络操作？ -- **Exec 审批漂移**（`security=full`、`autoAllowSkills`、未启用 `strictInlineEval` 的解释器 allowlist）：主机 exec 护栏是否仍然按你的预期发挥作用？ - - `security="full"` 是一个宽泛姿态警告，不代表存在 bug。它是受信任个人助手配置的默认选择；只有当你的威胁模型需要审批或 allowlist 护栏时，才应收紧它。 -- **网络暴露**（Gateway 网关 bind/auth、Tailscale Serve/Funnel、弱或过短的认证 token）。 +- **工具影响半径**（提升权限的工具 + 开放房间）：提示词注入是否可能演变为 shell / 文件 / 网络操作？ +- **Exec 审批漂移**（`security=full`、`autoAllowSkills`、未启用 `strictInlineEval` 的解释器 allowlist）：主机 exec 防护措施是否仍按你的预期工作？ + - `security="full"` 是一种宽泛姿态警告，不是 bug 的证明。它是受信任个人助理配置下有意选择的默认值；只有当你的威胁模型需要审批或 allowlist 防护时，才应收紧它。 +- **网络暴露**（Gateway 网关 bind / auth、Tailscale Serve / Funnel、弱或过短的认证 token）。 - **浏览器控制暴露**（远程节点、中继端口、远程 CDP 端点）。 - **本地磁盘卫生**（权限、符号链接、配置 includes、“同步文件夹”路径）。 -- **插件**（存在扩展但没有显式 allowlist）。 -- **策略漂移/配置错误**（配置了 sandbox docker 设置但未开启沙箱模式；无效的 `gateway.nodes.denyCommands` 模式，因为匹配仅针对精确命令名，例如 `system.run`，不会检查 shell 文本；危险的 `gateway.nodes.allowCommands` 条目；全局 `tools.profile="minimal"` 被按智能体配置的 profile 覆盖；扩展插件工具在宽松工具策略下可达）。 -- **运行时预期漂移**（例如假设隐式 exec 仍表示 `sandbox`，但现在 `tools.exec.host` 默认值是 `auto`；或者显式设置 `tools.exec.host="sandbox"`，但沙箱模式实际上处于关闭状态）。 -- **模型卫生**（当配置的模型看起来较旧时发出警告；这不是硬性阻断）。 +- **插件**（存在 extension，但没有显式 allowlist）。 +- **策略漂移/配置错误**（配置了沙箱 docker 设置但沙箱模式关闭；无效的 `gateway.nodes.denyCommands` 模式，因为匹配仅针对精确命令名生效，例如 `system.run`，不会检查 shell 文本；危险的 `gateway.nodes.allowCommands` 条目；全局 `tools.profile="minimal"` 被按智能体配置的 profile 覆盖；在宽松工具策略下可访问 extension plugin 工具）。 +- **运行时预期漂移**（例如误以为隐式 exec 仍表示 `sandbox`，而 `tools.exec.host` 现在默认是 `auto`；或显式设置 `tools.exec.host="sandbox"`，但沙箱模式实际上已关闭）。 +- **模型卫生**（当配置的模型看起来较旧时发出警告；不是硬性阻止）。 -如果你运行 `--deep`，OpenClaw 还会尽力尝试一次在线 Gateway 网关探测。 +如果你运行 `--deep`，OpenClaw 还会尽力尝试进行一次实时 Gateway 网关探测。 ## 凭证存储映射 -在审计访问权限或决定要备份哪些内容时，可使用此列表： +在审计访问权限或决定要备份什么时，可使用此表： - **WhatsApp**：`~/.openclaw/credentials/whatsapp//creds.json` -- **Telegram 机器人 token**：config/env 或 `channels.telegram.tokenFile`（仅允许普通文件；拒绝符号链接） -- **Discord 机器人 token**：config/env 或 SecretRef（env/file/exec providers） -- **Slack tokens**：config/env（`channels.slack.*`） +- **Telegram bot token**：配置/环境变量，或 `channels.telegram.tokenFile`（仅接受常规文件；拒绝符号链接） +- **Discord bot token**：配置/环境变量，或 SecretRef（env / file / exec 提供商） +- **Slack tokens**：配置/环境变量（`channels.slack.*`） - **配对 allowlist**： - `~/.openclaw/credentials/-allowFrom.json`（默认账号） - `~/.openclaw/credentials/--allowFrom.json`（非默认账号） @@ -233,12 +233,12 @@ Advisory 分诊指引： 当审计输出发现项时，请按以下优先级处理： -1. **任何“开放”+ 已启用工具的组合**：先锁定私信/群组（pairing/allowlist），再收紧工具策略/沙箱隔离。 +1. **任何“开放”且启用了工具的配置**：先锁定私信/群组（配对/allowlist），再收紧工具策略/沙箱隔离。 2. **公共网络暴露**（LAN bind、Funnel、缺少认证）：立即修复。 -3. **浏览器控制的远程暴露**：将其视为操作员级访问（仅 tailnet，谨慎配对节点，避免公开暴露）。 -4. **权限**：确保 state/config/credentials/auth 不是组可读或全局可读。 -5. **插件/扩展**：只加载你明确信任的内容。 -6. **模型选择**：对于任何启用了工具的机器人，优先使用现代、具备更强指令加固能力的模型。 +3. **浏览器控制的远程暴露**：应将其视为操作员访问（仅 tailnet、谨慎配对节点、避免公开暴露）。 +4. **权限**：确保状态/配置/凭证/认证文件不对组用户或所有人可读。 +5. **插件/extensions**：只加载你明确信任的内容。 +6. **模型选择**：对于任何带工具的机器人，优先使用现代、具备更强指令防护能力的模型。 ## 安全审计术语表 @@ -246,130 +246,130 @@ Advisory 分诊指引： | `checkId` | 严重级别 | 原因 | 主要修复键/路径 | 自动修复 | | --- | --- | --- | --- | --- | -| `fs.state_dir.perms_world_writable` | critical | 其他用户/进程可以修改整个 OpenClaw 状态 | `~/.openclaw` 的文件系统权限 | 是 | -| `fs.state_dir.perms_group_writable` | warn | 同组用户可以修改整个 OpenClaw 状态 | `~/.openclaw` 的文件系统权限 | 是 | +| `fs.state_dir.perms_world_writable` | critical | 其他用户/进程可以修改完整的 OpenClaw 状态 | `~/.openclaw` 的文件系统权限 | 是 | +| `fs.state_dir.perms_group_writable` | warn | 同组用户可以修改完整的 OpenClaw 状态 | `~/.openclaw` 的文件系统权限 | 是 | | `fs.state_dir.perms_readable` | warn | 状态目录可被其他人读取 | `~/.openclaw` 的文件系统权限 | 是 | | `fs.state_dir.symlink` | warn | 状态目录目标变成了另一个信任边界 | 状态目录的文件系统布局 | 否 | | `fs.config.perms_writable` | critical | 其他人可以更改认证/工具策略/配置 | `~/.openclaw/openclaw.json` 的文件系统权限 | 是 | | `fs.config.symlink` | warn | 配置目标变成了另一个信任边界 | 配置文件的文件系统布局 | 否 | -| `fs.config.perms_group_readable` | warn | 同组用户可以读取配置 token/设置 | 配置文件的文件系统权限 | 是 | -| `fs.config.perms_world_readable` | critical | 配置可能暴露 token/设置 | 配置文件的文件系统权限 | 是 | +| `fs.config.perms_group_readable` | warn | 同组用户可以读取配置 token / 设置 | 配置文件的文件系统权限 | 是 | +| `fs.config.perms_world_readable` | critical | 配置可能暴露 token / 设置 | 配置文件的文件系统权限 | 是 | | `fs.config_include.perms_writable` | critical | 配置 include 文件可被其他人修改 | `openclaw.json` 引用的 include 文件权限 | 是 | -| `fs.config_include.perms_group_readable` | warn | 同组用户可以读取被包含的 secrets/设置 | `openclaw.json` 引用的 include 文件权限 | 是 | -| `fs.config_include.perms_world_readable` | critical | 被包含的 secrets/设置对所有人可读 | `openclaw.json` 引用的 include 文件权限 | 是 | +| `fs.config_include.perms_group_readable` | warn | 同组用户可以读取被 include 的 secrets / 设置 | `openclaw.json` 引用的 include 文件权限 | 是 | +| `fs.config_include.perms_world_readable` | critical | 被 include 的 secrets / 设置对所有人可读 | `openclaw.json` 引用的 include 文件权限 | 是 | | `fs.auth_profiles.perms_writable` | critical | 其他人可以注入或替换已存储的模型凭证 | `agents//agent/auth-profiles.json` 权限 | 是 | -| `fs.auth_profiles.perms_readable` | warn | 其他人可以读取 API keys 和 OAuth tokens | `agents//agent/auth-profiles.json` 权限 | 是 | +| `fs.auth_profiles.perms_readable` | warn | 其他人可以读取 API 密钥和 OAuth token | `agents//agent/auth-profiles.json` 权限 | 是 | | `fs.credentials_dir.perms_writable` | critical | 其他人可以修改渠道配对/凭证状态 | `~/.openclaw/credentials` 的文件系统权限 | 是 | | `fs.credentials_dir.perms_readable` | warn | 其他人可以读取渠道凭证状态 | `~/.openclaw/credentials` 的文件系统权限 | 是 | -| `fs.sessions_store.perms_readable` | warn | 其他人可以读取会话转录/元数据 | 会话存储权限 | 是 | -| `fs.log_file.perms_readable` | warn | 其他人可以读取已脱敏但仍可能敏感的日志 | Gateway 网关日志文件权限 | 是 | -| `fs.synced_dir` | warn | 将状态/配置放在 iCloud/Dropbox/Drive 中会扩大 token/转录暴露面 | 将配置/状态移出同步文件夹 | 否 | -| `gateway.bind_no_auth` | critical | 在没有共享密钥的情况下进行远程 bind | `gateway.bind`、`gateway.auth.*` | 否 | -| `gateway.loopback_no_auth` | critical | 反向代理的 loopback 可能变成未认证访问 | `gateway.auth.*`、代理设置 | 否 | -| `gateway.trusted_proxies_missing` | warn | 存在反向代理头，但未将代理标记为受信任 | `gateway.trustedProxies` | 否 | -| `gateway.http.no_auth` | warn/critical | 使用 `auth.mode="none"` 时 Gateway 网关 HTTP API 可访问 | `gateway.auth.mode`、`gateway.http.endpoints.*` | 否 | -| `gateway.http.session_key_override_enabled` | info | HTTP API 调用方可以覆盖 `sessionKey` | `gateway.http.allowSessionKeyOverride` | 否 | +| `fs.sessions_store.perms_readable` | warn | 其他人可以读取会话转录/元数据 | session 存储权限 | 是 | +| `fs.log_file.perms_readable` | warn | 其他人可以读取已脱敏但仍然敏感的日志 | Gateway 网关日志文件权限 | 是 | +| `fs.synced_dir` | warn | iCloud / Dropbox / Drive 中的状态/配置会扩大 token / 转录内容暴露面 | 将配置/状态移出同步文件夹 | 否 | +| `gateway.bind_no_auth` | critical | 远程 bind 且没有共享密钥 | `gateway.bind`、`gateway.auth.*` | 否 | +| `gateway.loopback_no_auth` | critical | 反向代理后的 loopback 可能变成未认证访问 | `gateway.auth.*`、代理设置 | 否 | +| `gateway.trusted_proxies_missing` | warn | 存在反向代理头，但这些代理未被信任 | `gateway.trustedProxies` | 否 | +| `gateway.http.no_auth` | warn/critical | 使用 `auth.mode="none"` 时 Gateway 网关 HTTP API 可被访问 | `gateway.auth.mode`、`gateway.http.endpoints.*` | 否 | +| `gateway.http.session_key_override_enabled` | info | HTTP API 调用者可以覆盖 `sessionKey` | `gateway.http.allowSessionKeyOverride` | 否 | | `gateway.tools_invoke_http.dangerous_allow` | warn/critical | 通过 HTTP API 重新启用了危险工具 | `gateway.tools.allow` | 否 | -| `gateway.nodes.allow_commands_dangerous` | warn/critical | 启用了高影响节点命令（camera/screen/contacts/calendar/SMS） | `gateway.nodes.allowCommands` | 否 | -| `gateway.nodes.deny_commands_ineffective` | warn | 类似模式的 deny 条目不会匹配 shell 文本或分组 | `gateway.nodes.denyCommands` | 否 | -| `gateway.tailscale_funnel` | critical | 暴露到公共互联网 | `gateway.tailscale.mode` | 否 | +| `gateway.nodes.allow_commands_dangerous` | warn/critical | 启用了高影响节点命令（摄像头/屏幕/联系人/日历/SMS） | `gateway.nodes.allowCommands` | 否 | +| `gateway.nodes.deny_commands_ineffective` | warn | 类似模式的 deny 条目不会匹配 shell 文本或命令组 | `gateway.nodes.denyCommands` | 否 | +| `gateway.tailscale_funnel` | critical | 公开互联网暴露 | `gateway.tailscale.mode` | 否 | | `gateway.tailscale_serve` | info | 已通过 Serve 启用 tailnet 暴露 | `gateway.tailscale.mode` | 否 | -| `gateway.control_ui.allowed_origins_required` | critical | 非 loopback 的 Control UI 缺少显式浏览器来源 allowlist | `gateway.controlUi.allowedOrigins` | 否 | -| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` 会禁用浏览器来源 allowlist | `gateway.controlUi.allowedOrigins` | 否 | -| `gateway.control_ui.host_header_origin_fallback` | warn/critical | 启用了基于 Host header 的来源回退（降低 DNS rebinding 加固强度） | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | 否 | -| `gateway.control_ui.insecure_auth` | warn | 启用了不安全认证兼容开关 | `gateway.controlUi.allowInsecureAuth` | 否 | -| `gateway.control_ui.device_auth_disabled` | critical | 禁用了设备身份校验 | `gateway.controlUi.dangerouslyDisableDeviceAuth` | 否 | +| `gateway.control_ui.allowed_origins_required` | critical | 非 loopback 的控制 UI 未显式设置浏览器 origin allowlist | `gateway.controlUi.allowedOrigins` | 否 | +| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` 会禁用浏览器 origin allowlist | `gateway.controlUi.allowedOrigins` | 否 | +| `gateway.control_ui.host_header_origin_fallback` | warn/critical | 启用了 Host 头 origin 回退（降低 DNS rebinding 加固强度） | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | 否 | +| `gateway.control_ui.insecure_auth` | warn | 已启用不安全认证兼容开关 | `gateway.controlUi.allowInsecureAuth` | 否 | +| `gateway.control_ui.device_auth_disabled` | critical | 禁用了设备身份检查 | `gateway.controlUi.dangerouslyDisableDeviceAuth` | 否 | | `gateway.real_ip_fallback_enabled` | warn/critical | 信任 `X-Real-IP` 回退可能因代理配置错误而导致源 IP 欺骗 | `gateway.allowRealIpFallback`、`gateway.trustedProxies` | 否 | -| `gateway.token_too_short` | warn | 过短的共享 token 更容易被暴力破解 | `gateway.auth.token` | 否 | -| `gateway.auth_no_rate_limit` | warn | 暴露的认证接口若没有速率限制，会增加暴力破解风险 | `gateway.auth.rateLimit` | 否 | +| `gateway.token_too_short` | warn | 共享 token 过短，更容易被暴力破解 | `gateway.auth.token` | 否 | +| `gateway.auth_no_rate_limit` | warn | 暴露的认证接口没有速率限制会增加暴力破解风险 | `gateway.auth.rateLimit` | 否 | | `gateway.trusted_proxy_auth` | critical | 代理身份现在成为认证边界 | `gateway.auth.mode="trusted-proxy"` | 否 | -| `gateway.trusted_proxy_no_proxies` | critical | 使用 trusted-proxy 认证但未配置受信任代理 IP，不安全 | `gateway.trustedProxies` | 否 | +| `gateway.trusted_proxy_no_proxies` | critical | trusted-proxy 认证未配置受信任代理 IP，存在安全风险 | `gateway.trustedProxies` | 否 | | `gateway.trusted_proxy_no_user_header` | critical | trusted-proxy 认证无法安全解析用户身份 | `gateway.auth.trustedProxy.userHeader` | 否 | -| `gateway.trusted_proxy_no_allowlist` | warn | trusted-proxy 认证会接受任意已认证的上游用户 | `gateway.auth.trustedProxy.allowUsers` | 否 | +| `gateway.trusted_proxy_no_allowlist` | warn | trusted-proxy 认证会接受任何已通过上游认证的用户 | `gateway.auth.trustedProxy.allowUsers` | 否 | | `checkId` | 严重级别 | 原因 | 主要修复键/路径 | 自动修复 | | --- | --- | --- | --- | --- | -| `gateway.probe_auth_secretref_unavailable` | warn | 深度探测无法在当前命令路径中解析认证 SecretRef | 深度探测认证来源 / SecretRef 可用性 | 否 | -| `gateway.probe_failed` | warn/critical | 在线 Gateway 网关探测失败 | Gateway 网关可达性/认证 | 否 | -| `discovery.mdns_full_mode` | warn/critical | mDNS 完整模式会在本地网络广播 `cliPath`/`sshPort` 元数据 | `discovery.mdns.mode`、`gateway.bind` | 否 | -| `config.insecure_or_dangerous_flags` | warn | 启用了任意不安全/危险的调试标志 | 多个键（参见发现详情） | 否 | +| `gateway.probe_auth_secretref_unavailable` | warn | 深度探测无法在当前命令路径中解析认证 SecretRef | 深度探测认证源 / SecretRef 可用性 | 否 | +| `gateway.probe_failed` | warn/critical | 实时 Gateway 网关探测失败 | Gateway 网关可达性/认证 | 否 | +| `discovery.mdns_full_mode` | warn/critical | mDNS 完整模式会在本地网络上广播 `cliPath` / `sshPort` 元数据 | `discovery.mdns.mode`、`gateway.bind` | 否 | +| `config.insecure_or_dangerous_flags` | warn | 启用了不安全/危险的调试标志 | 多个键（见发现详情） | 否 | | `config.secrets.gateway_password_in_config` | warn | Gateway 网关密码直接存储在配置中 | `gateway.auth.password` | 否 | | `config.secrets.hooks_token_in_config` | warn | Hook bearer token 直接存储在配置中 | `hooks.token` | 否 | -| `hooks.token_reuse_gateway_token` | critical | Hook 入站 token 同时也可用于通过 Gateway 网关认证 | `hooks.token`、`gateway.auth.token` | 否 | +| `hooks.token_reuse_gateway_token` | critical | Hook 入站 token 同时也可用于 Gateway 网关认证 | `hooks.token`、`gateway.auth.token` | 否 | | `hooks.token_too_short` | warn | Hook 入站更容易被暴力破解 | `hooks.token` | 否 | -| `hooks.default_session_key_unset` | warn | Hook 智能体运行时会分散到每请求生成的会话中 | `hooks.defaultSessionKey` | 否 | -| `hooks.allowed_agent_ids_unrestricted` | warn/critical | 已认证的 Hook 调用方可以路由到任意已配置智能体 | `hooks.allowedAgentIds` | 否 | +| `hooks.default_session_key_unset` | warn | Hook 智能体运行会扇出到按请求生成的 session | `hooks.defaultSessionKey` | 否 | +| `hooks.allowed_agent_ids_unrestricted` | warn/critical | 已认证的 Hook 调用方可以路由到任意已配置的智能体 | `hooks.allowedAgentIds` | 否 | | `hooks.request_session_key_enabled` | warn/critical | 外部调用方可以选择 `sessionKey` | `hooks.allowRequestSessionKey` | 否 | -| `hooks.request_session_key_prefixes_missing` | warn/critical | 外部会话键格式没有任何边界限制 | `hooks.allowedSessionKeyPrefixes` | 否 | -| `hooks.path_root` | critical | Hook 路径是 `/`，使入站更容易冲突或误路由 | `hooks.path` | 否 | -| `hooks.installs_unpinned_npm_specs` | warn | Hook 安装记录未固定到不可变的 npm specs | Hook 安装元数据 | 否 | +| `hooks.request_session_key_prefixes_missing` | warn/critical | 未限制外部 session key 的形态 | `hooks.allowedSessionKeyPrefixes` | 否 | +| `hooks.path_root` | critical | Hook 路径为 `/`，更容易发生入站冲突或误路由 | `hooks.path` | 否 | +| `hooks.installs_unpinned_npm_specs` | warn | Hook 安装记录未固定到不可变的 npm 规格 | Hook 安装元数据 | 否 | | `hooks.installs_missing_integrity` | warn | Hook 安装记录缺少完整性元数据 | Hook 安装元数据 | 否 | -| `hooks.installs_version_drift` | warn | Hook 安装记录与已安装包发生漂移 | Hook 安装元数据 | 否 | -| `logging.redact_off` | warn | 敏感值会泄漏到日志/状态输出中 | `logging.redactSensitive` | 是 | +| `hooks.installs_version_drift` | warn | Hook 安装记录与已安装包存在版本漂移 | Hook 安装元数据 | 否 | +| `logging.redact_off` | warn | 敏感值会泄露到日志/状态输出 | `logging.redactSensitive` | 是 | | `browser.control_invalid_config` | warn | 浏览器控制配置在运行前即无效 | `browser.*` | 否 | -| `browser.control_no_auth` | critical | 浏览器控制在没有 token/password 认证的情况下暴露 | `gateway.auth.*` | 否 | -| `browser.remote_cdp_http` | warn | 通过明文 HTTP 使用远程 CDP，缺少传输加密 | 浏览器 profile `cdpUrl` | 否 | -| `browser.remote_cdp_private_host` | warn | 远程 CDP 指向私有/内部主机 | 浏览器 profile `cdpUrl`、`browser.ssrfPolicy.*` | 否 | -| `sandbox.docker_config_mode_off` | warn | 已存在 sandbox Docker 配置，但当前未启用 | `agents.*.sandbox.mode` | 否 | -| `sandbox.bind_mount_non_absolute` | warn | 相对 bind mount 可能解析为不可预测的位置 | `agents.*.sandbox.docker.binds[]` | 否 | -| `sandbox.dangerous_bind_mount` | critical | sandbox bind mount 指向受阻止的系统、凭证或 Docker socket 路径 | `agents.*.sandbox.docker.binds[]` | 否 | -| `sandbox.dangerous_network_mode` | critical | sandbox Docker 网络使用 `host` 或 `container:*` 这类命名空间加入模式 | `agents.*.sandbox.docker.network` | 否 | -| `sandbox.dangerous_seccomp_profile` | critical | sandbox seccomp profile 削弱了容器隔离 | `agents.*.sandbox.docker.securityOpt` | 否 | -| `sandbox.dangerous_apparmor_profile` | critical | sandbox AppArmor profile 削弱了容器隔离 | `agents.*.sandbox.docker.securityOpt` | 否 | -| `sandbox.browser_cdp_bridge_unrestricted` | warn | sandbox 浏览器桥未限制来源地址范围即对外暴露 | `sandbox.browser.cdpSourceRange` | 否 | -| `sandbox.browser_container.non_loopback_publish` | critical | 现有浏览器容器在非 loopback 接口上发布 CDP | 浏览器 sandbox 容器发布配置 | 否 | -| `sandbox.browser_container.hash_label_missing` | warn | 现有浏览器容器早于当前 config-hash labels 机制 | `openclaw sandbox recreate --browser --all` | 否 | -| `sandbox.browser_container.hash_epoch_stale` | warn | 现有浏览器容器早于当前浏览器配置 epoch | `openclaw sandbox recreate --browser --all` | 否 | +| `browser.control_no_auth` | critical | 浏览器控制在没有 token / password 认证的情况下暴露 | `gateway.auth.*` | 否 | +| `browser.remote_cdp_http` | warn | 通过纯 HTTP 访问远程 CDP，缺少传输加密 | 浏览器配置文件 `cdpUrl` | 否 | +| `browser.remote_cdp_private_host` | warn | 远程 CDP 指向私有/内网主机 | 浏览器配置文件 `cdpUrl`、`browser.ssrfPolicy.*` | 否 | +| `sandbox.docker_config_mode_off` | warn | 已配置沙箱 Docker 设置，但当前未启用 | `agents.*.sandbox.mode` | 否 | +| `sandbox.bind_mount_non_absolute` | warn | 相对 bind mount 的解析结果可能不可预测 | `agents.*.sandbox.docker.binds[]` | 否 | +| `sandbox.dangerous_bind_mount` | critical | 沙箱 bind mount 指向了被阻止的系统、凭证或 Docker socket 路径 | `agents.*.sandbox.docker.binds[]` | 否 | +| `sandbox.dangerous_network_mode` | critical | 沙箱 Docker 网络使用 `host` 或 `container:*` 命名空间共享模式 | `agents.*.sandbox.docker.network` | 否 | +| `sandbox.dangerous_seccomp_profile` | critical | 沙箱 seccomp 配置文件削弱了容器隔离 | `agents.*.sandbox.docker.securityOpt` | 否 | +| `sandbox.dangerous_apparmor_profile` | critical | 沙箱 AppArmor 配置文件削弱了容器隔离 | `agents.*.sandbox.docker.securityOpt` | 否 | +| `sandbox.browser_cdp_bridge_unrestricted` | warn | 沙箱浏览器桥未限制源地址范围即对外暴露 | `sandbox.browser.cdpSourceRange` | 否 | +| `sandbox.browser_container.non_loopback_publish` | critical | 现有浏览器容器在非 loopback 接口上发布了 CDP | 浏览器沙箱容器发布配置 | 否 | +| `sandbox.browser_container.hash_label_missing` | warn | 现有浏览器容器早于当前配置哈希标签机制创建 | `openclaw sandbox recreate --browser --all` | 否 | +| `sandbox.browser_container.hash_epoch_stale` | warn | 现有浏览器容器早于当前浏览器配置 epoch 创建 | `openclaw sandbox recreate --browser --all` | 否 | | `tools.exec.host_sandbox_no_sandbox_defaults` | warn | 当沙箱关闭时，`exec host=sandbox` 会以失败关闭方式运行 | `tools.exec.host`、`agents.defaults.sandbox.mode` | 否 | | `tools.exec.host_sandbox_no_sandbox_agents` | warn | 当沙箱关闭时，按智能体配置的 `exec host=sandbox` 会以失败关闭方式运行 | `agents.list[].tools.exec.host`、`agents.list[].sandbox.mode` | 否 | -| `tools.exec.security_full_configured` | warn/critical | 主机 exec 正以 `security="full"` 运行 | `tools.exec.security`、`agents.list[].tools.exec.security` | 否 | -| `tools.exec.auto_allow_skills_enabled` | warn | Exec 审批会隐式信任 Skills 二进制文件 | `~/.openclaw/exec-approvals.json` | 否 | -| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | 解释器 allowlist 允许内联 eval，但不会强制重新审批 | `tools.exec.strictInlineEval`、`agents.list[].tools.exec.strictInlineEval`、exec approvals allowlist | 否 | -| `tools.exec.safe_bins_interpreter_unprofiled` | warn | `safeBins` 中的解释器/运行时二进制文件若没有显式 profile，会扩大 exec 风险 | `tools.exec.safeBins`、`tools.exec.safeBinProfiles`、`agents.list[].tools.exec.*` | 否 | -| `tools.exec.safe_bins_broad_behavior` | warn | `safeBins` 中具备宽泛行为的工具会削弱低风险 stdin 过滤信任模型 | `tools.exec.safeBins`、`agents.list[].tools.exec.safeBins` | 否 | +| `tools.exec.security_full_configured` | warn/critical | 主机 exec 当前使用 `security="full"` 运行 | `tools.exec.security`、`agents.list[].tools.exec.security` | 否 | +| `tools.exec.auto_allow_skills_enabled` | warn | Exec 审批会隐式信任 skill bin | `~/.openclaw/exec-approvals.json` | 否 | +| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | 解释器 allowlist 允许 inline eval，且不会强制重新审批 | `tools.exec.strictInlineEval`、`agents.list[].tools.exec.strictInlineEval`、exec 审批 allowlist | 否 | +| `tools.exec.safe_bins_interpreter_unprofiled` | warn | `safeBins` 中的解释器/运行时 bin 若没有显式 profile，会扩大 exec 风险 | `tools.exec.safeBins`、`tools.exec.safeBinProfiles`、`agents.list[].tools.exec.*` | 否 | +| `tools.exec.safe_bins_broad_behavior` | warn | `safeBins` 中行为宽泛的工具会削弱基于低风险 stdin 过滤的信任模型 | `tools.exec.safeBins`、`agents.list[].tools.exec.safeBins` | 否 | | `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` 包含可变或高风险目录 | `tools.exec.safeBinTrustedDirs`、`agents.list[].tools.exec.safeBinTrustedDirs` | 否 | | `skills.workspace.symlink_escape` | warn | 工作区 `skills/**/SKILL.md` 解析到了工作区根目录之外（符号链接链漂移） | 工作区 `skills/**` 文件系统状态 | 否 | -| `plugins.extensions_no_allowlist` | warn | 已安装扩展，但没有显式插件 allowlist | `plugins.allowlist` | 否 | -| `plugins.installs_unpinned_npm_specs` | warn | 插件安装记录未固定到不可变的 npm specs | 插件安装元数据 | 否 | +| `plugins.extensions_no_allowlist` | warn | 已安装 extensions，但没有显式 plugin allowlist | `plugins.allowlist` | 否 | +| `plugins.installs_unpinned_npm_specs` | warn | Plugin 安装记录未固定到不可变的 npm 规格 | plugin 安装元数据 | 否 | | `checkId` | 严重级别 | 原因 | 主要修复键/路径 | 自动修复 | | --- | --- | --- | --- | --- | -| `plugins.installs_missing_integrity` | warn | 插件安装记录缺少完整性元数据 | 插件安装元数据 | 否 | -| `plugins.installs_version_drift` | warn | 插件安装记录与已安装包发生漂移 | 插件安装元数据 | 否 | -| `plugins.code_safety` | warn/critical | 插件代码扫描发现可疑或危险模式 | 插件代码 / 安装来源 | 否 | -| `plugins.code_safety.entry_path` | warn | 插件入口路径指向隐藏目录或 `node_modules` 位置 | 插件清单中的 `entry` | 否 | -| `plugins.code_safety.entry_escape` | critical | 插件入口逃逸出插件目录 | 插件清单中的 `entry` | 否 | -| `plugins.code_safety.scan_failed` | warn | 插件代码扫描未能完成 | 插件扩展路径 / 扫描环境 | 否 | -| `skills.code_safety` | warn/critical | Skills 安装器元数据/代码包含可疑或危险模式 | skill 安装来源 | 否 | +| `plugins.installs_missing_integrity` | warn | Plugin 安装记录缺少完整性元数据 | plugin 安装元数据 | 否 | +| `plugins.installs_version_drift` | warn | Plugin 安装记录与已安装包存在版本漂移 | plugin 安装元数据 | 否 | +| `plugins.code_safety` | warn/critical | Plugin 代码扫描发现可疑或危险模式 | plugin 代码 / 安装来源 | 否 | +| `plugins.code_safety.entry_path` | warn | Plugin 入口路径指向隐藏目录或 `node_modules` 位置 | plugin manifest `entry` | 否 | +| `plugins.code_safety.entry_escape` | critical | Plugin 入口逃逸出了 plugin 目录 | plugin manifest `entry` | 否 | +| `plugins.code_safety.scan_failed` | warn | Plugin 代码扫描未能完成 | plugin extension 路径 / 扫描环境 | 否 | +| `skills.code_safety` | warn/critical | Skill 安装器元数据/代码包含可疑或危险模式 | skill 安装来源 | 否 | | `skills.code_safety.scan_failed` | warn | Skill 代码扫描未能完成 | skill 扫描环境 | 否 | -| `security.exposure.open_channels_with_exec` | warn/critical | 共享/公开房间可访问启用了 exec 的智能体 | `channels.*.dmPolicy`、`channels.*.groupPolicy`、`tools.exec.*`、`agents.list[].tools.exec.*` | 否 | -| `security.exposure.open_groups_with_elevated` | critical | 开放群组 + 高权限工具会形成高影响的提示词注入路径 | `channels.*.groupPolicy`、`tools.elevated.*` | 否 | -| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | 开放群组可以在没有沙箱/workspace 防护的情况下访问命令/文件工具 | `channels.*.groupPolicy`、`tools.profile/deny`、`tools.fs.workspaceOnly`、`agents.*.sandbox.mode` | 否 | -| `security.trust_model.multi_user_heuristic` | warn | 配置看起来像多用户场景，而 Gateway 网关信任模型是个人助手 | 拆分信任边界，或实施共享用户加固（`sandbox.mode`、工具 deny/workspace 范围限制） | 否 | +| `security.exposure.open_channels_with_exec` | warn/critical | 共享/公开房间可以访问启用了 exec 的智能体 | `channels.*.dmPolicy`、`channels.*.groupPolicy`、`tools.exec.*`、`agents.list[].tools.exec.*` | 否 | +| `security.exposure.open_groups_with_elevated` | critical | 开放群组 + 提权工具会形成高影响的提示词注入路径 | `channels.*.groupPolicy`、`tools.elevated.*` | 否 | +| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | 开放群组可以在没有沙箱/工作区防护的情况下访问命令/文件工具 | `channels.*.groupPolicy`、`tools.profile/deny`、`tools.fs.workspaceOnly`、`agents.*.sandbox.mode` | 否 | +| `security.trust_model.multi_user_heuristic` | warn | 配置看起来是多用户使用，但 Gateway 网关信任模型是个人助理 | 拆分信任边界，或进行共享用户加固（`sandbox.mode`、工具 deny / 工作区作用域限制） | 否 | | `tools.profile_minimal_overridden` | warn | 智能体覆盖配置绕过了全局 minimal profile | `agents.list[].tools.profile` | 否 | -| `plugins.tools_reachable_permissive_policy` | warn | 扩展工具在宽松上下文中可达 | `tools.profile` + 工具 allow/deny | 否 | +| `plugins.tools_reachable_permissive_policy` | warn | 在宽松策略上下文中可以访问 extension 工具 | `tools.profile` + 工具 allow / deny | 否 | | `models.legacy` | warn | 仍配置了旧版模型家族 | 模型选择 | 否 | -| `models.weak_tier` | warn | 已配置模型低于当前推荐档位 | 模型选择 | 否 | -| `models.small_params` | critical/info | 小参数模型 + 不安全工具暴露面会提高注入风险 | 模型选择 + 沙箱/工具策略 | 否 | -| `summary.attack_surface` | info | 对认证、渠道、工具和暴露姿态的汇总摘要 | 多个键（参见发现详情） | 否 | +| `models.weak_tier` | warn | 已配置模型低于当前推荐层级 | 模型选择 | 否 | +| `models.small_params` | critical/info | 小参数模型 + 不安全工具表面会提高注入风险 | 模型选择 + 沙箱/工具策略 | 否 | +| `summary.attack_surface` | info | 对认证、渠道、工具和暴露姿态的汇总摘要 | 多个键（见发现详情） | 否 | -## 通过 HTTP 使用 Control UI +## 通过 HTTP 使用控制 UI -Control UI 需要一个**安全上下文**（HTTPS 或 localhost）来生成设备身份。`gateway.controlUi.allowInsecureAuth` 是一个本地兼容性开关： +控制 UI 需要一个**安全上下文**（HTTPS 或 localhost）来生成设备身份。`gateway.controlUi.allowInsecureAuth` 是一个本地兼容性开关： -- 在 localhost 上，当页面通过非安全的 HTTP 加载时，它允许 Control UI 在没有设备身份的情况下进行认证。 +- 在 localhost 上，当页面通过非安全的 HTTP 加载时，它允许控制 UI 在没有设备身份的情况下进行认证。 - 它不会绕过配对检查。 - 它不会放宽远程（非 localhost）设备身份要求。 优先使用 HTTPS（Tailscale Serve），或在 `127.0.0.1` 上打开 UI。 -仅用于紧急兜底场景时，`gateway.controlUi.dangerouslyDisableDeviceAuth` 会完全禁用设备身份检查。这会严重降低安全性；除非你正在主动调试且能快速恢复，否则应保持关闭。 +仅用于紧急兜底场景时，`gateway.controlUi.dangerouslyDisableDeviceAuth` 会完全禁用设备身份检查。这是严重的安全降级；除非你正在主动调试且能够快速恢复，否则应保持关闭。 -与这些危险标志分开的是，成功启用 `gateway.auth.mode: "trusted-proxy"` 时，可以允许**操作员** Control UI 会话在没有设备身份的情况下接入。这是认证模式的有意行为，不是 `allowInsecureAuth` 的捷径，而且它仍不适用于节点角色的 Control UI 会话。 +与这些危险标志不同，成功的 `gateway.auth.mode: "trusted-proxy"` 可以在没有设备身份的情况下允许**操作员**控制 UI 会话。这是该认证模式的有意行为，不是 `allowInsecureAuth` 的捷径，而且它仍然不适用于 node 角色的控制 UI 会话。 -当此设置启用时，`openclaw security audit` 会发出警告。 +当启用此设置时，`openclaw security audit` 会发出警告。 -## 不安全或危险标志汇总 +## 不安全或危险标志摘要 -当已知的不安全/危险调试开关被启用时，`openclaw security audit` 会包含 `config.insecure_or_dangerous_flags`。该检查当前汇总以下项： +当已知的不安全/危险调试开关被启用时，`openclaw security audit` 会包含 `config.insecure_or_dangerous_flags`。该检查目前汇总以下内容： - `gateway.controlUi.allowInsecureAuth=true` - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` @@ -379,7 +379,7 @@ Control UI 需要一个**安全上下文**（HTTPS 或 localhost）来生成设 - `tools.exec.applyPatch.workspaceOnly=false` - `plugins.entries.acpx.config.permissionMode=approve-all` -OpenClaw 配置 schema 中定义的完整 `dangerous*` / `dangerously*` 配置键列表： +OpenClaw 配置 schema 中定义的完整 `dangerous*` / `dangerously*` 配置键： - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` @@ -391,15 +391,15 @@ OpenClaw 配置 schema 中定义的完整 `dangerous*` / `dangerously*` 配置 - `channels.googlechat.dangerouslyAllowNameMatching` - `channels.googlechat.accounts..dangerouslyAllowNameMatching` - `channels.msteams.dangerouslyAllowNameMatching` -- `channels.synology-chat.dangerouslyAllowNameMatching`（扩展渠道） -- `channels.synology-chat.accounts..dangerouslyAllowNameMatching`（扩展渠道） -- `channels.synology-chat.dangerouslyAllowInheritedWebhookPath`（扩展渠道） -- `channels.zalouser.dangerouslyAllowNameMatching`（扩展渠道） -- `channels.zalouser.accounts..dangerouslyAllowNameMatching`（扩展渠道） -- `channels.irc.dangerouslyAllowNameMatching`（扩展渠道） -- `channels.irc.accounts..dangerouslyAllowNameMatching`（扩展渠道） -- `channels.mattermost.dangerouslyAllowNameMatching`（扩展渠道） -- `channels.mattermost.accounts..dangerouslyAllowNameMatching`（扩展渠道） +- `channels.synology-chat.dangerouslyAllowNameMatching`（extension 渠道） +- `channels.synology-chat.accounts..dangerouslyAllowNameMatching`（extension 渠道） +- `channels.synology-chat.dangerouslyAllowInheritedWebhookPath`（extension 渠道） +- `channels.zalouser.dangerouslyAllowNameMatching`（extension 渠道） +- `channels.zalouser.accounts..dangerouslyAllowNameMatching`（extension 渠道） +- `channels.irc.dangerouslyAllowNameMatching`（extension 渠道） +- `channels.irc.accounts..dangerouslyAllowNameMatching`（extension 渠道） +- `channels.mattermost.dangerouslyAllowNameMatching`（extension 渠道） +- `channels.mattermost.accounts..dangerouslyAllowNameMatching`（extension 渠道） - `channels.telegram.network.dangerouslyAllowPrivateNetwork` - `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` @@ -411,29 +411,29 @@ OpenClaw 配置 schema 中定义的完整 `dangerous*` / `dangerously*` 配置 ## 反向代理配置 -如果你在反向代理（nginx、Caddy、Traefik 等）后运行 Gateway 网关，请配置 `gateway.trustedProxies`，以正确处理转发的客户端 IP。 +如果你在反向代理（nginx、Caddy、Traefik 等）后面运行 Gateway 网关，请配置 `gateway.trustedProxies` 以正确处理转发后的客户端 IP。 -当 Gateway 网关检测到来自**不在** `trustedProxies` 中地址的代理头时，它将**不会**把这些连接视为本地客户端。如果 Gateway 网关认证被禁用，这些连接会被拒绝。这可防止认证绕过：否则，经代理转发的连接可能会看起来像来自 localhost，从而自动获得信任。 +当 Gateway 网关检测到来自**不在** `trustedProxies` 中地址的代理头时，它将**不会**把这些连接视为本地客户端。如果 Gateway 网关认证被禁用，这些连接会被拒绝。这样可以防止认证绕过：否则经代理转发的连接可能会看起来像来自 localhost，并自动获得信任。 -`gateway.trustedProxies` 也会被 `gateway.auth.mode: "trusted-proxy"` 使用，但该认证模式更严格： +`gateway.trustedProxies` 也会用于 `gateway.auth.mode: "trusted-proxy"`，但该认证模式更严格： -- trusted-proxy 认证在 loopback 来源代理场景下会**失败关闭** -- 同主机的 loopback 反向代理仍可使用 `gateway.trustedProxies` 来进行本地客户端识别和转发 IP 处理 -- 对于同主机的 loopback 反向代理，应使用 token/password 认证，而不是 `gateway.auth.mode: "trusted-proxy"` +- trusted-proxy 认证会对 loopback 来源的代理**失败关闭** +- 同主机上的 loopback 反向代理仍然可以使用 `gateway.trustedProxies` 来进行本地客户端识别和转发 IP 处理 +- 对于同主机 loopback 反向代理，请使用 token / password 认证，而不是 `gateway.auth.mode: "trusted-proxy"` ```yaml gateway: trustedProxies: - - "10.0.0.1" # 反向代理 IP - # 可选。默认 false。 - # 仅当你的代理无法提供 X-Forwarded-For 时才启用。 + - "10.0.0.1" # reverse proxy 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`。 良好的反向代理行为（覆盖传入的转发头）： @@ -448,50 +448,49 @@ proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` -## HSTS 和来源说明 +## HSTS 和 origin 说明 -- OpenClaw Gateway 网关首先面向本地/loopback。若你在反向代理处终止 TLS，请在代理前的 HTTPS 域名上设置 HSTS。 -- 如果由 Gateway 网关自身终止 HTTPS，你可以设置 `gateway.http.securityHeaders.strictTransportSecurity`，让 OpenClaw 响应输出 HSTS header。 -- 详细部署指南见[Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)。 -- 对于非 loopback 的 Control UI 部署，默认要求配置 `gateway.controlUi.allowedOrigins`。 -- `gateway.controlUi.allowedOrigins: ["*"]` 表示显式允许所有浏览器来源策略，并不是强化后的默认值。除严格受控的本地测试外，应避免使用。 -- 即使启用了一般性的 loopback 豁免，loopback 上的浏览器来源认证失败仍会受到速率限制，但锁定键是按规范化后的 `Origin` 值分别作用，而不是共用一个 localhost 桶。 -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用基于 Host header 的来源回退模式；应将其视为由操作员主动选择的危险策略。 -- 应将 DNS rebinding 和代理 Host header 行为视为部署加固问题；保持 `trustedProxies` 尽量严格，避免将 Gateway 网关直接暴露到公共互联网。 +- OpenClaw Gateway 网关优先面向本地/local 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 的控制 UI 部署，默认要求设置 `gateway.controlUi.allowedOrigins`。 +- `gateway.controlUi.allowedOrigins: ["*"]` 是显式允许所有浏览器 origin 的策略，不是强化默认值。除非是在严格受控的本地测试环境中，否则应避免使用。 +- 即使启用了通用的 loopback 豁免，loopback 上的浏览器 origin 认证失败仍然会受到速率限制，但锁定键会按归一化后的 `Origin` 值分别作用，而不是共享一个 localhost 桶。 +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 头 origin 回退模式；应将其视为由操作员主动选择的危险策略。 +- 应将 DNS rebinding 和代理 Host 头行为视为部署加固问题；保持 `trustedProxies` 尽可能严格，并避免将 Gateway 网关直接暴露到公共互联网。 ## 本地会话日志存储在磁盘上 -OpenClaw 会将会话转录存储到磁盘中的 `~/.openclaw/agents//sessions/*.jsonl`。 -这对于保持会话连续性以及（可选的）会话记忆索引是必需的，但这也意味着 -**任何拥有文件系统访问权限的进程/用户都可以读取这些日志**。应将磁盘访问视为信任边界， -并锁定 `~/.openclaw` 的权限（见下方审计部分）。如果你需要在不同智能体之间实现更强隔离， -请让它们运行在单独的 OS 用户下，或运行在不同主机上。 +OpenClaw 会将会话转录存储在磁盘上的 `~/.openclaw/agents//sessions/*.jsonl`。 +这是保持会话连续性以及（可选）进行会话 memory 索引所必需的，但这也意味着 +**任何具有文件系统访问权限的进程/用户都可以读取这些日志**。应将磁盘访问视为信任 +边界，并锁定 `~/.openclaw` 的权限（见下方审计部分）。如果你需要在智能体之间实现更强隔离，请将它们运行在不同的 OS 用户下，或部署在不同主机上。 ## 节点执行（`system.run`） -如果 macOS 节点已配对，Gateway 网关可以在该节点上调用 `system.run`。这意味着会在该 Mac 上执行**远程代码执行**： +如果某个 macOS 节点已完成配对，Gateway 网关就可以在该节点上调用 `system.run`。这属于 **Mac 上的远程代码执行**： - 需要节点配对（审批 + token）。 -- Gateway 网关节点配对不是逐命令审批界面。它建立的是节点身份/信任和 token 签发。 -- Gateway 网关通过 `gateway.nodes.allowCommands` / `denyCommands` 应用一个粗粒度的全局节点命令策略。 +- Gateway 网关节点配对不是逐命令审批表面。它建立的是节点身份/信任和 token 签发。 +- Gateway 网关通过 `gateway.nodes.allowCommands` / `denyCommands` 应用粗粒度的全局节点命令策略。 - 在 Mac 上通过**设置 → Exec 审批**进行控制（security + ask + allowlist）。 -- 每个节点的 `system.run` 策略由该节点自己的 exec 审批文件（`exec.approvals.node.*`）控制，它可以比 Gateway 网关的全局命令 ID 策略更严格，也可以更宽松。 +- 每个节点的 `system.run` 策略由节点自己的 exec 审批文件（`exec.approvals.node.*`）决定，它可以比 Gateway 网关的全局命令 ID 策略更严格，也可以更宽松。 - 以 `security="full"` 和 `ask="off"` 运行的节点，遵循的是默认的受信任操作员模型。除非你的部署明确要求更严格的审批或 allowlist 策略，否则应将其视为预期行为。 -- 审批模式会绑定精确的请求上下文，并在可能时绑定一个具体的本地脚本/文件操作数。若 OpenClaw 无法为解释器/运行时命令精确识别出唯一一个直接本地文件，则会拒绝基于审批的执行，而不是声称能够提供完整的语义覆盖。 -- 对于 `host=node`，基于审批的运行还会存储一个规范化的预备 `systemRunPlan`；之后已批准的转发会复用该存储计划，且 Gateway 网关验证会拒绝调用方在审批请求创建后再修改命令/cwd/会话上下文。 -- 如果你不希望发生远程执行，请将 security 设置为 **deny**，并取消该 Mac 的节点配对。 +- 审批模式会绑定精确的请求上下文，并在可能时绑定一个具体的本地脚本/文件操作数。如果 OpenClaw 无法为解释器/运行时命令准确识别唯一的直接本地文件，那么基于审批的执行会被拒绝，而不会承诺提供完整语义覆盖。 +- 对于 `host=node`，基于审批的运行还会存储一个规范化的已准备 `systemRunPlan`；之后经批准的转发会复用该已存储计划，而 Gateway 网关验证会拒绝在审批请求创建后对命令/cwd / session 上下文所做的调用方修改。 +- 如果你不希望出现远程执行，请将 security 设置为 **deny**，并取消该 Mac 的节点配对。 -这一区分对于分诊很重要： +这一区分对于分流判断很重要： -- 一个重新连接的已配对节点如果声明了不同的命令列表，本身**并不**构成漏洞，只要 Gateway 网关全局策略和节点本地 exec 审批仍然执行真实的执行边界。 -- 把节点配对元数据当作第二层隐藏逐命令审批机制的报告，通常属于策略/UX 理解混淆，而不是安全边界绕过。 +- 一个重新连接的已配对节点声明了不同的命令列表，这本身并不构成漏洞，只要 Gateway 网关全局策略和节点本地 exec 审批仍然在执行真正的边界控制。 +- 把节点配对元数据当作第二层隐藏逐命令审批机制的报告，通常属于策略/用户体验理解混淆，而不是安全边界绕过。 ## 动态 Skills（watcher / 远程节点） OpenClaw 可以在会话中途刷新 Skills 列表： -- **Skills watcher**：对 `SKILL.md` 的修改可以在下一次智能体回合时更新 Skills 快照。 -- **远程节点**：连接 macOS 节点后，可能会使仅限 macOS 的 Skills 变为可用（基于二进制探测）。 +- **Skills watcher**：对 `SKILL.md` 的更改可以在智能体下一轮响应时更新 Skills 快照。 +- **远程节点**：连接 macOS 节点后，可能会使仅适用于 macOS 的 Skills 变为可选（基于 bin 探测）。 应将 skill 文件夹视为**受信任代码**，并限制谁可以修改它们。 @@ -500,48 +499,48 @@ OpenClaw 可以在会话中途刷新 Skills 列表： 你的 AI 助手可以： - 执行任意 shell 命令 -- 读取/写入文件 +- 读写文件 - 访问网络服务 -- 向任何人发送消息（如果你赋予它 WhatsApp 访问权限） +- 向任何人发送消息（如果你给了它 WhatsApp 访问权限） 给你发消息的人可以： - 试图诱骗你的 AI 做坏事 -- 通过社会工程方式获取你的数据访问权限 +- 通过社会工程获取你的数据访问权限 - 探测基础设施细节 ## 核心概念：先做访问控制，再谈智能 -这里的大多数失败都不是花哨的漏洞利用——而是“有人给机器人发了消息，而机器人照做了”。 +这里的大多数失败都不是高级漏洞利用——而是“某人给机器人发了消息，机器人就照做了”。 OpenClaw 的立场是： -- **身份优先：**先决定谁可以和机器人对话（私信配对 / allowlist / 显式 `open`）。 -- **范围其次：**再决定机器人被允许在哪里执行操作（群组 allowlist + 提及门控、工具、沙箱隔离、设备权限）。 -- **模型最后：**假设模型可以被操纵；系统设计应让这种操纵的影响半径保持有限。 +- **身份优先：**先决定谁可以和机器人对话（私信配对 / allowlist / 显式 “open”）。 +- **范围其次：**再决定机器人被允许在哪些地方执行操作（群组 allowlist + mention 门槛、工具、沙箱隔离、设备权限）。 +- **模型最后：**假定模型可以被操纵；系统设计应使这种操纵的影响半径受到限制。 ## 命令授权模型 -Slash commands 和 directives 仅对**已授权发送者**生效。授权来自 -渠道 allowlist/配对以及 `commands.useAccessGroups`（参见[配置](/zh-CN/gateway/configuration) -和 [Slash commands](/zh-CN/tools/slash-commands)）。如果某个渠道 allowlist 为空，或包含 `"*"`, -则该渠道中的命令实际上就是开放的。 +斜杠命令和指令仅对**已授权发送者**生效。授权来自 +渠道 allowlist / 配对，以及 `commands.useAccessGroups`（参见[配置](/zh-CN/gateway/configuration) +和[斜杠命令](/zh-CN/tools/slash-commands)）。如果某个渠道的 allowlist 为空或包含 `"*"`， +那么该渠道上的命令实际上就是开放的。 -`/exec` 是面向已授权操作员的仅限会话便捷功能。它**不会**写入配置，也不会 -更改其他会话。 +`/exec` 是仅供已授权操作员使用的 session 内便捷命令。它**不会**写入配置，也**不会** +更改其他 session。 ## 控制平面工具风险 -有两个内置工具可以进行持久性的控制平面更改： +两个内置工具可以进行持久性的控制平面更改： - `gateway` 可以通过 `config.schema.lookup` / `config.get` 检查配置，也可以通过 `config.apply`、`config.patch` 和 `update.run` 进行持久更改。 -- `cron` 可以创建计划任务，使其在原始聊天/任务结束后继续运行。 +- `cron` 可以创建定时任务，使其在原始聊天/任务结束后仍持续运行。 -仅限所有者使用的 `gateway` 运行时工具仍然拒绝重写 +仅限所有者的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` 或 `tools.exec.security`；旧版 `tools.bash.*` 别名会 -先被规范化到相同的受保护 exec 路径后再写入。 +先被规范化到相同的受保护 exec 路径，再执行写入。 -对于任何处理不受信任内容的智能体/界面，默认都应拒绝这些工具： +对于任何会处理不受信任内容的智能体/表面，默认都应拒绝这些工具： ```json5 { @@ -553,33 +552,33 @@ Slash commands 和 directives 仅对**已授权发送者**生效。授权来自 `commands.restart=false` 只会阻止重启动作。它不会禁用 `gateway` 配置/更新操作。 -## 插件/扩展 +## 插件/extensions -插件会**在进程内**与 Gateway 网关一起运行。应将它们视为受信任代码： +Plugins 会**在 Gateway 网关进程内**运行。应将它们视为受信任代码： -- 只从你信任的来源安装插件。 -- 优先使用显式 `plugins.allow` allowlist。 -- 启用前先审查插件配置。 -- 插件变更后重启 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 依赖安装也遵循相同的危险/可疑划分：除非调用方显式设置 `dangerouslyForceUnsafeInstall`，否则内置的 `critical` 发现项会被阻止，而可疑发现项仍然只会发出警告。`openclaw skills install` 仍然是独立的 ClawHub skill 下载/安装流程。 +- 只安装来自你信任来源的 plugins。 +- 优先使用显式的 `plugins.allow` allowlist。 +- 启用前先审查 plugin 配置。 +- 修改 plugin 后重启 Gateway 网关。 +- 如果你安装或更新 plugins（`openclaw plugins install `、`openclaw plugins update `），应将其视为运行不受信任代码： + - 安装路径是当前 plugin 安装根目录下对应 plugin 的专属目录。 + - OpenClaw 会在安装/更新前运行内置危险代码扫描。`critical` 发现默认会阻止继续执行。 + - OpenClaw 会先使用 `npm pack`，然后在该目录中运行 `npm install --omit=dev`（npm 生命周期脚本可能在安装期间执行代码）。 + - 优先使用固定、精确的版本（`@scope/pkg@1.2.3`），并在启用前检查磁盘上解包后的代码。 + - `--dangerously-force-unsafe-install` 仅用于 plugin 安装/更新流程中内置扫描误报时的紧急兜底场景。它不会绕过 plugin `before_install` hook 策略阻止，也不会绕过扫描失败。 + - 依赖 Gateway 网关的 skill 依赖安装遵循相同的危险/可疑区分：内置 `critical` 发现会阻止执行，除非调用方显式设置 `dangerouslyForceUnsafeInstall`；而可疑发现仍然仅发出警告。`openclaw skills install` 仍然是单独的 ClawHub skill 下载/安装流程。 -详情见：[插件](/zh-CN/tools/plugin) +详情见：[Plugins](/zh-CN/tools/plugin) ## 私信访问模型（pairing / allowlist / open / disabled） -当前所有支持私信的渠道都支持一个私信策略（`dmPolicy` 或 `*.dm.policy`），用于在消息被处理**之前**拦截入站私信： +当前所有支持私信的渠道都支持一个私信策略（`dmPolicy` 或 `*.dm.policy`），在消息被处理**之前**拦截入站私信： -- `pairing`（默认）：未知发送者会收到一个简短的配对码，在获得批准前机器人会忽略其消息。配对码 1 小时后过期；重复发送私信不会再次发送配对码，除非创建了新的请求。默认情况下，每个渠道最多保留 **3 个待处理请求**。 +- `pairing`（默认）：未知发送者会收到一个简短的配对码，机器人会忽略其消息直到获得批准。配对码 1 小时后过期；重复发送私信不会重复发送配对码，除非创建了新的请求。默认情况下，每个渠道最多保留 **3 个待处理请求**。 - `allowlist`：未知发送者会被阻止（没有配对握手）。 -- `open`：允许任何人发送私信（公开）。**要求**该渠道的 allowlist 包含 `"*"`（显式选择加入）。 +- `open`：允许任何人发送私信（公开）。**要求**该渠道的 allowlist 包含 `"*"`（显式选择启用）。 - `disabled`：完全忽略入站私信。 通过 CLI 批准： @@ -593,7 +592,7 @@ openclaw pairing approve ## 私信会话隔离（多用户模式） -默认情况下，OpenClaw 会将**所有私信都路由到主会话**，这样你的助手就能在不同设备和渠道之间保持连续性。如果**多个人**都可以给机器人发送私信（开放私信或多人 allowlist），请考虑隔离私信会话： +默认情况下，OpenClaw 会将**所有私信都路由到主 session**，这样你的助手就能在不同设备和渠道之间保持连续性。如果**有多个人**可以给机器人发私信（开放私信或多人 allowlist），建议隔离私信 session： ```json5 { @@ -601,195 +600,210 @@ openclaw pairing approve } ``` -这样可以防止不同用户之间的上下文泄漏，同时仍保持群聊彼此隔离。 +这样可以防止跨用户上下文泄露，同时保持群聊彼此隔离。 -这是消息上下文边界，不是主机管理员边界。如果用户彼此对抗，且共享同一 Gateway 网关主机/配置，请按信任边界分别运行独立的 Gateway 网关。 +这是消息上下文边界，不是主机管理员边界。如果这些用户彼此对抗且共享同一个 Gateway 网关主机/配置，请按信任边界分别运行独立 Gateway 网关。 ### 安全私信模式（推荐） 将上面的配置片段视为**安全私信模式**： -- 默认值：`session.dmScope: "main"`（所有私信共享一个会话，以保持连续性）。 -- 本地 CLI 新手引导默认行为：当未设置时，写入 `session.dmScope: "per-channel-peer"`（会保留现有的显式值）。 -- 安全私信模式：`session.dmScope: "per-channel-peer"`（每个渠道 + 发送者组合都会获得一个隔离的私信上下文）。 -- 跨渠道同一联系人隔离：`session.dmScope: "per-peer"`（同一类型的所有渠道中，每个发送者共用一个会话）。 +- 默认值：`session.dmScope: "main"`（所有私信共享一个 session，以保持连续性）。 +- 本地 CLI 新手引导默认值：当未设置时写入 `session.dmScope: "per-channel-peer"`（保留现有显式值）。 +- 安全私信模式：`session.dmScope: "per-channel-peer"`（每个渠道 + 发送者组合都有独立的私信上下文）。 +- 跨渠道对等方隔离：`session.dmScope: "per-peer"`（同一发送者在同类所有渠道中共享一个 session）。 -如果你在同一渠道上运行多个账号，请改用 `per-account-channel-peer`。如果同一个人在多个渠道上联系你，请使用 `session.identityLinks` 将这些私信会话合并为一个规范身份。参见[会话管理](/zh-CN/concepts/session)和[配置](/zh-CN/gateway/configuration)。 +如果你在同一个渠道上运行多个账号，请改用 `per-account-channel-peer`。如果同一个人会通过多个渠道联系你，请使用 `session.identityLinks` 将这些私信 session 合并为一个规范身份。详见[会话管理](/zh-CN/concepts/session)和[配置](/zh-CN/gateway/configuration)。 -## Allowlists（私信 + 群组）- 术语说明 +## Allowlist（私信 + 群组）- 术语说明 OpenClaw 中有两层独立的“谁可以触发我？”机制： - **私信 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 的消息。 + - 当 `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，再检查提及/回复激活。 - - 回复机器人消息（隐式提及）**不会**绕过类似 `groupAllowFrom` 这样的发送者 allowlist。 - - **安全说明：**应将 `dmPolicy="open"` 和 `groupPolicy="open"` 视为最后手段。应尽量少用；除非你完全信任房间里的每一个成员，否则优先使用 pairing + allowlist。 + - `channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups`：如 `requireMention` 之类的按群组默认值；设置后也会充当群组 allowlist（包含 `"*"` 可保持允许所有群组的行为）。 + - `groupPolicy="allowlist"` + `groupAllowFrom`：限制在某个群组 session **内部**谁可以触发机器人（WhatsApp / Telegram / Signal / iMessage / Microsoft Teams）。 + - `channels.discord.guilds` / `channels.slack.channels`：按表面划分的 allowlist + mention 默认值。 + - 群组检查顺序如下：先 `groupPolicy` / 群组 allowlist，后 mention / reply 激活。 + - 回复机器人消息（隐式 mention）**不会**绕过 `groupAllowFrom` 之类的发送者 allowlist。 + - **安全说明：**应将 `dmPolicy="open"` 和 `groupPolicy="open"` 视为最后手段。应尽量少用；除非你完全信任房间中的每个成员，否则优先使用 pairing + allowlist。 -详情见：[配置](/zh-CN/gateway/configuration)和[群组](/zh-CN/channels/groups) +详见：[配置](/zh-CN/gateway/configuration) 和 [群组](/zh-CN/channels/groups) -## 提示词注入（它是什么，为什么重要） +## 提示词注入（是什么，为什么重要） -提示词注入是指攻击者构造一条消息，诱导模型执行不安全操作（“忽略你的指令”“导出你的文件系统”“访问这个链接并运行命令”等）。 +提示词注入是指攻击者精心构造一条消息，操纵模型执行不安全操作（“忽略你的指令”、“导出你的文件系统”、“访问这个链接并执行命令”等）。 -即使有很强的系统提示词，**提示词注入也没有被彻底解决**。系统提示词护栏只是软性指引；真正的强制约束来自工具策略、exec 审批、沙箱隔离和渠道 allowlist（而且这些机制按设计也可以被操作员关闭）。在实践中真正有帮助的是： +即使使用了强系统提示词，**提示词注入也没有被彻底解决**。系统提示词防护只能算软性指引；真正的硬性约束来自工具策略、exec 审批、沙箱隔离和渠道 allowlist（而且这些防护也可以被操作员有意关闭）。实践中真正有帮助的是： -- 保持入站私信处于锁定状态（pairing/allowlist）。 -- 在群组中优先使用提及门控；避免在公共房间中部署“始终在线”的机器人。 -- 默认将链接、附件和粘贴的指令视为敌对内容。 -- 在沙箱中运行敏感工具执行；不要让 secrets 出现在智能体可访问的文件系统中。 -- 注意：沙箱隔离是选择启用的。如果沙箱模式关闭，隐式 `host=auto` 会解析为 Gateway 网关主机。显式 `host=sandbox` 仍会以失败关闭方式运行，因为没有可用的沙箱运行时。如果你希望在配置中明确表达这种行为，请设置 `host=gateway`。 +- 锁定入站私信（pairing / allowlist）。 +- 在群组中优先使用 mention 门槛；避免在公开房间中使用“始终在线”的机器人。 +- 默认将链接、附件和粘贴的指令视为不受信任内容。 +- 在沙箱中运行敏感工具执行；将 secrets 放在智能体可访问文件系统之外。 +- 注意：沙箱隔离是选择启用的。如果沙箱模式关闭，隐式 `host=auto` 会解析到 Gateway 网关主机。显式 `host=sandbox` 仍会以失败关闭方式处理，因为没有可用的沙箱运行时。如果你希望在配置中显式表达这种行为，请设置 `host=gateway`。 - 将高风险工具（`exec`、`browser`、`web_fetch`、`web_search`）限制给受信任智能体或显式 allowlist。 -- 如果你对解释器使用 allowlist（`python`、`node`、`ruby`、`perl`、`php`、`lua`、`osascript`），请启用 `tools.exec.strictInlineEval`，这样内联 eval 形式仍然需要显式审批。 -- **模型选择很重要：**较旧/较小/旧代模型对提示词注入和工具滥用的抵抗力明显更弱。对于启用了工具的智能体，请使用可获得的最新一代、最强档位、经过指令加固的模型。 +- 如果你对解释器进行 allowlist（`python`、`node`、`ruby`、`perl`、`php`、`lua`、`osascript`），请启用 `tools.exec.strictInlineEval`，这样 inline eval 形式仍需要显式审批。 +- Shell 审批分析还会拒绝出现在**未加引号 heredoc** 中的 POSIX 参数展开形式（`$VAR`、`$?`、`$$`、`$1`、`$@`、`${…}`），因此 allowlist 中的 heredoc 主体无法将 shell 展开伪装成纯文本绕过 allowlist 审查。若要启用字面量主体语义，请给 heredoc 结束符加引号（例如 `<<'EOF'`）；对于本会触发变量展开的未加引号 heredoc，将直接拒绝。 +- **模型选择很重要：**较旧/较小/旧版的模型在应对提示词注入和工具滥用方面通常明显更脆弱。对于启用了工具的智能体，请使用当前可用的最新一代、指令防护更强的最强模型。 -应视为不受信任内容的危险信号包括： +应视为不受信任的危险信号： -- “读取这个文件/URL 并严格照着它说的做。” +- “读取这个文件/URL，并完全照它说的做。” - “忽略你的系统提示词或安全规则。” -- “泄露你的隐藏指令或工具输出。” -- “把 `~/.openclaw` 或你的日志的全部内容贴出来。” +- “透露你的隐藏指令或工具输出。” +- “粘贴 `~/.openclaw` 或你的日志的完整内容。” -## 不安全的外部内容绕过标志 +## 外部内容特殊 token 清洗 -OpenClaw 包含一些显式绕过标志，可用于禁用外部内容安全包装： +OpenClaw 会在包装外部内容和元数据时，剥离常见自托管 LLM 聊天模板中的特殊 token 字面量，避免它们到达模型。覆盖的标记族包括 Qwen / ChatML、Llama、Gemma、Mistral、Phi，以及 GPT-OSS 的角色/轮次 token。 + +原因如下： + +- 某些面向自托管模型的 OpenAI 兼容后端，有时会保留出现在用户文本中的特殊 token，而不是将其屏蔽。攻击者如果能够写入入站外部内容（抓取页面、邮件正文、文件读取工具输出），就可能伪造一个 `assistant` 或 `system` 角色边界，从而绕过包装外部内容时的防护。 +- 清洗发生在外部内容包装层，因此它会统一应用于抓取/读取工具以及入站渠道内容，而不是按提供商分别处理。 +- 发往用户可见回复的出站模型响应已经有单独的清洗器，会剥离泄露的 ``、`` 以及类似脚手架。外部内容清洗器则是它在入站方向上的对应机制。 + +这并不能替代本页中的其他加固措施——`dmPolicy`、allowlist、exec 审批、沙箱隔离和 `contextVisibility` 仍然承担主要防护作用。它只是补上了一个特定的 tokenizer 层绕过问题：针对那些会原样转发带特殊 token 的用户文本的自托管技术栈。 + +## 不安全外部内容绕过标志 + +OpenClaw 包含一些显式绕过标志，可禁用外部内容安全包装： - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` - Cron 载荷字段 `allowUnsafeExternalContent` -建议： +指导建议： -- 在生产环境中保持这些值未设置/为 false。 -- 仅在范围严格受控的临时调试中启用。 -- 如果启用了，应隔离该智能体（沙箱隔离 + 最小工具集 + 专用会话命名空间）。 +- 在生产环境中保持这些设置未启用/为 false。 +- 仅在严格限定范围的调试中临时启用。 +- 如果已启用，应隔离对应智能体（沙箱隔离 + 最少工具 + 专用 session 命名空间）。 Hooks 风险说明： -- Hook 载荷属于不受信任内容，即使投递来自你控制的系统（邮件/文档/网页内容也可能携带提示词注入）。 -- 较弱模型档位会增加这种风险。对于基于 Hook 的自动化，优先使用强力的现代模型档位，并保持严格的工具策略（`tools.profile: "messaging"` 或更严格），同时尽可能启用沙箱隔离。 +- Hook 载荷属于不受信任内容，即使它来自你控制的系统（邮件/文档/网页内容仍可能携带提示词注入）。 +- 较弱层级的模型会放大这种风险。对于 Hook 驱动的自动化，请优先选择强大的现代模型层级，并保持严格的工具策略（`tools.profile: "messaging"` 或更严格），同时尽可能启用沙箱隔离。 -### 提示词注入并不要求公开私信 +### 提示词注入并不需要公开私信 即使**只有你自己**可以给机器人发消息，提示词注入仍然可能通过 机器人读取的任何**不受信任内容**发生（网页搜索/抓取结果、浏览器页面、 -邮件、文档、附件、粘贴的日志/代码）。换句话说：发送者并不是唯一的威胁面； +邮件、文档、附件、粘贴的日志/代码）。换句话说：威胁面不只是发送者； **内容本身**也可能携带对抗性指令。 -启用工具后，典型风险是外泄上下文或触发工具调用。降低影响半径的方法包括： +当启用了工具时，典型风险是外泄上下文或触发工具调用。你可以通过以下方式缩小影响半径： -- 使用一个只读或禁用工具的**读取智能体**来总结不受信任内容， - 然后再把摘要交给你的主智能体。 +- 使用只读或禁用工具的**阅读智能体**来总结不受信任内容， + 然后再把摘要传给你的主智能体。 - 对启用了工具的智能体，除非确有需要，否则关闭 `web_search` / `web_fetch` / `browser`。 -- 对于 OpenResponses URL 输入（`input_file` / `input_image`），应严格设置 +- 对于 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 网关主机上的 env/config 传递。 + 元数据，尽管这一路径不会附带更长的 `SECURITY NOTICE:` 横幅。 +- 当媒体理解从附加文档中提取文本并将其追加到媒体提示词时，也会应用同样基于标记的包装。 +- 对任何会接触不受信任输入的智能体启用沙箱隔离和严格的工具 allowlist。 +- 不要把 secrets 放进提示词；应通过 Gateway 网关主机上的环境变量/配置传递。 ### 自托管 LLM 后端 OpenAI 兼容的自托管后端，例如 vLLM、SGLang、TGI、LM Studio， -或自定义的 Hugging Face tokenizer 栈，在处理聊天模板特殊 token 的方式上， -可能与托管提供商不同。如果某个后端会把用户内容中的字面字符串 -如 `<|im_start|>`、`<|start_header_id|>` 或 `` token 化为 -结构性的聊天模板 token，那么不受信任文本就可能尝试在 tokenizer 层伪造角色边界。 +或自定义 Hugging Face tokenizer 技术栈，在处理聊天模板特殊 token 的方式上， +可能与托管提供商不同。如果某个后端会将用户内容中的字面字符串 +如 `<|im_start|>`、`<|start_header_id|>` 或 `` 解析为 +结构化聊天模板 token，不受信任文本就可能尝试在 tokenizer 层伪造角色边界。 -OpenClaw 在将外部内容发送给模型之前，会从包装后的外部内容中剥离常见模型家族的特殊 token 字面量。请保持外部内容包装处于启用状态，并在可用时优先使用那些会对用户提供内容中的特殊 token 进行拆分或转义的后端设置。OpenAI -和 Anthropic 等托管提供商已经在请求侧应用了各自的清洗机制。 +OpenClaw 会在将包装后的外部内容分发给模型之前， +剥离其中常见模型家族的特殊 token 字面量。请保持外部内容包装处于启用状态， +并在后端支持时，优先选择能够对用户提供内容中的特殊 token 进行拆分或转义的设置。像 OpenAI +和 Anthropic 这样的托管提供商已经在请求侧应用了自己的清洗机制。 ### 模型强度（安全说明） -不同模型档位对提示词注入的抵抗力**并不一致**。更小/更便宜的模型通常更容易被诱导滥用工具和劫持指令，尤其是在对抗性提示词下。 +不同模型层级的提示词注入抵抗能力**并不一致**。更小/更便宜的模型通常更容易被诱导滥用工具和劫持指令，尤其是在对抗性提示词下。 -对于启用了工具的智能体，或会读取不受信任内容的智能体，较旧/较小模型带来的提示词注入风险通常过高。不要在弱模型档位上运行这些工作负载。 +对于启用了工具的智能体，或会读取不受信任内容的智能体，较旧/较小模型带来的提示词注入风险通常过高。不要在较弱模型层级上运行这些工作负载。 建议： -- 对于任何可以运行工具或接触文件/网络的机器人，**使用最新一代、最强档位的模型**。 -- **不要对启用了工具的智能体或不受信任收件箱使用较旧/较弱/较小的档位**；提示词注入风险过高。 -- 如果你必须使用较小模型，**就要缩小影响半径**（只读工具、强沙箱隔离、最小文件系统访问、严格 allowlist）。 -- 运行小模型时，**为所有会话启用沙箱隔离**，并且**禁用 `web_search`/`web_fetch`/`browser`**，除非输入受到严格控制。 -- 对于仅聊天、输入可信且不使用工具的个人助手，较小模型通常是可以接受的。 +- 对于任何可以运行工具或接触文件/网络的机器人，**使用最新一代、最佳层级的模型**。 +- 对于启用了工具的智能体或不受信任收件箱，**不要使用较旧/较弱/较小的层级**；提示词注入风险太高。 +- 如果你必须使用较小模型，请**缩小影响半径**（只读工具、强沙箱隔离、最小文件系统访问、严格 allowlist）。 +- 运行小模型时，应**为所有 session 启用沙箱隔离**，并且**禁用 `web_search` / `web_fetch` / `browser`**，除非输入受到严格控制。 +- 对于仅聊天、输入受信任且没有工具的个人助理，较小模型通常没有问题。 -## 群组中的 Reasoning 与详细输出 +## 群组中的推理与详细输出 -`/reasoning`、`/verbose` 和 `/trace` 可能会暴露内部推理、工具 -输出，或本不应出现在公共频道中的插件诊断信息。 -在群组场景中，应将它们视为**仅供调试** +`/reasoning`、`/verbose` 和 `/trace` 可能暴露内部推理、工具 +输出或 plugin 诊断信息，而这些内容 +原本并不适合出现在公共渠道中。在群组环境下，应将它们视为**仅供调试** 的功能，除非你明确需要，否则保持关闭。 -建议： +指导建议： -- 在公共房间中保持 `/reasoning`、`/verbose` 和 `/trace` 关闭。 -- 如果要启用，只应在受信任的私信或严格受控的房间中启用。 -- 请记住：verbose 和 trace 输出可能包含工具参数、URL、插件诊断信息，以及模型看到的数据。 +- 在公开房间中保持 `/reasoning`、`/verbose` 和 `/trace` 关闭。 +- 如果要启用，也只应在受信任的私信或严格受控的房间中启用。 +- 请记住：verbose 和 trace 输出可能包含工具参数、URL、plugin 诊断信息，以及模型看到的数据。 ## 配置加固（示例） -### 0）文件权限 +### 0) 文件权限 在 Gateway 网关主机上保持配置和状态私有： -- `~/.openclaw/openclaw.json`：`600`（仅用户可读写） -- `~/.openclaw`：`700`（仅用户可访问） +- `~/.openclaw/openclaw.json`：`600`（仅当前用户可读写） +- `~/.openclaw`：`700`（仅当前用户可访问） `openclaw doctor` 可以发出警告，并提供收紧这些权限的选项。 -### 0.4）网络暴露（bind + port + firewall） +### 0.4) 网络暴露（bind + port + firewall） -Gateway 网关在单个端口上复用 **WebSocket + HTTP**： +Gateway 网关会在单个端口上复用 **WebSocket + HTTP**： - 默认值：`18789` -- 配置/flags/env：`gateway.port`、`--port`、`OPENCLAW_GATEWAY_PORT` +- 配置/标志/环境变量：`gateway.port`、`--port`、`OPENCLAW_GATEWAY_PORT` -这个 HTTP 界面包括 Control UI 和 canvas host： +这个 HTTP 表面包括控制 UI 和 canvas host： -- Control UI（SPA 静态资源）（默认基础路径 `/`） -- Canvas host：`/__openclaw__/canvas/` 和 `/__openclaw__/a2ui/`（任意 HTML/JS；应视为不受信任内容） +- 控制 UI（SPA 静态资源）（默认基础路径 `/`） +- Canvas host：`/__openclaw__/canvas/` 和 `/__openclaw__/a2ui/`（任意 HTML / JS；应视为不受信任内容） -如果你在普通浏览器中加载 canvas 内容，应像对待其他不受信任网页一样对待它： +如果你在普通浏览器中加载 canvas 内容，应像对待任何其他不受信任网页一样看待它： - 不要将 canvas host 暴露给不受信任的网络/用户。 -- 除非你完全理解其影响，否则不要让 canvas 内容与高权限 Web 界面共享同一来源。 +- 除非你完全理解其影响，否则不要让 canvas 内容与有特权的 Web 表面共享同一 origin。 -bind 模式决定 Gateway 网关监听的位置： +Bind 模式决定 Gateway 网关监听的位置： - `gateway.bind: "loopback"`（默认）：只有本地客户端可以连接。 -- 非 loopback bind（`"lan"`、`"tailnet"`、`"custom"`）会扩大攻击面。只有在启用了 Gateway 网关认证（共享 token/password 或正确配置的非 loopback trusted proxy）并配有真实防火墙时才应使用。 +- 非 loopback 绑定（`"lan"`、`"tailnet"`、`"custom"`）会扩大攻击面。只有在启用了 Gateway 网关认证（共享 token / password，或配置正确的非 loopback trusted proxy）并配有真正防火墙时才应使用。 -经验法则： +经验规则： -- 优先使用 Tailscale Serve，而不是 LAN bind（Serve 会让 Gateway 网关保持在 loopback 上，由 Tailscale 负责访问控制）。 -- 如果你必须绑定到 LAN，请用防火墙将端口限制为严格的源 IP allowlist；不要广泛做端口转发。 -- 绝不要把未认证的 Gateway 网关暴露在 `0.0.0.0` 上。 +- 优先使用 Tailscale Serve，而不是 LAN 绑定（Serve 会让 Gateway 网关保持在 loopback 上，由 Tailscale 处理访问）。 +- 如果必须绑定到 LAN，请用防火墙将端口限制为严格的源 IP allowlist；不要广泛进行端口转发。 +- 绝不要将未认证的 Gateway 网关暴露在 `0.0.0.0` 上。 -### 0.4.1）Docker 端口发布 + UFW（`DOCKER-USER`） +### 0.4.1) Docker 端口发布 + UFW（`DOCKER-USER`） -如果你在 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` 前端， -但这些规则仍然会应用到 nftables 后端。 +为了让 Docker 流量与你的防火墙策略保持一致，请在 +`DOCKER-USER` 中强制应用规则（这个链会在 Docker 自己的 accept 规则之前被评估）。 +在许多现代发行版上，`iptables` / `ip6tables` 使用 `iptables-nft` 前端， +但这些规则仍会应用到 nftables 后端。 最小 allowlist 示例（IPv4）： @@ -810,11 +824,12 @@ 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*` 等），不匹配可能会意外 +跳过你的拒绝规则。 重载后的快速验证： @@ -825,22 +840,22 @@ ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` -预期对外开放的端口应仅限于你有意暴露的那些（对大多数配置来说： -SSH + 你的反向代理端口）。 +预期对外开放的端口应仅限你有意暴露的端口（对大多数 +配置来说：SSH + 你的反向代理端口）。 -### 0.4.2）mDNS/Bonjour 发现（信息泄露） +### 0.4.2) mDNS / Bonjour 发现（信息泄露） -Gateway 网关会通过 mDNS（端口 5353 上的 `_openclaw-gw._tcp`）广播自身存在，以便本地设备发现。在完整模式下，这些广播包含的 TXT 记录可能会暴露运行细节： +Gateway 网关会通过 mDNS（端口 5353 上的 `_openclaw-gw._tcp`）广播自身存在，以便本地设备发现。在完整模式下，这还会包含可能暴露运行细节的 TXT 记录： - `cliPath`：CLI 二进制文件的完整文件系统路径（会泄露用户名和安装位置） -- `sshPort`：广播主机上 SSH 的可用性 +- `sshPort`：广播主机上 SSH 可用 - `displayName`、`lanHost`：主机名信息 -**运维安全注意事项：**广播基础设施细节会让本地网络中的任何人更容易进行侦察。即使是文件系统路径和 SSH 可用性这类“看似无害”的信息，也能帮助攻击者描绘你的环境。 +**运维安全注意事项：**广播基础设施细节会让本地网络中的任何人更容易进行侦察。即使是文件系统路径、SSH 可用性这样的“无害”信息，也有助于攻击者绘制你的环境结构。 **建议：** -1. **最小模式**（默认，推荐用于对外暴露的 Gateway 网关）：从 mDNS 广播中省略敏感字段： +1. **最小模式**（默认，推荐用于暴露型 Gateway 网关）：从 mDNS 广播中省略敏感字段： ```json5 { @@ -850,7 +865,7 @@ Gateway 网关会通过 mDNS（端口 5353 上的 `_openclaw-gw._tcp`）广播 } ``` -2. **完全禁用**：如果你不需要本地设备发现功能： +2. 如果你不需要本地设备发现，**可完全禁用**： ```json5 { @@ -870,17 +885,17 @@ Gateway 网关会通过 mDNS（端口 5353 上的 `_openclaw-gw._tcp`）广播 } ``` -4. **环境变量**（替代方式）：设置 `OPENCLAW_DISABLE_BONJOUR=1`，无需更改配置即可禁用 mDNS。 +4. **环境变量**（替代方式）：设置 `OPENCLAW_DISABLE_BONJOUR=1`，无需修改配置即可禁用 mDNS。 -在最小模式下，Gateway 网关仍会广播足够用于设备发现的信息（`role`、`gatewayPort`、`transport`），但不会包含 `cliPath` 和 `sshPort`。需要 CLI 路径信息的应用可通过已认证的 WebSocket 连接再获取。 +在最小模式下，Gateway 网关仍会广播足够用于设备发现的信息（`role`、`gatewayPort`、`transport`），但会省略 `cliPath` 和 `sshPort`。需要 CLI 路径信息的应用可以改为通过已认证的 WebSocket 连接获取。 -### 0.5）锁定 Gateway 网关 WebSocket（本地认证） +### 0.5) 锁定 Gateway 网关 WebSocket（本地认证） -Gateway 网关认证默认**必须启用**。如果未配置有效的 Gateway 网关认证路径， +默认情况下**必须启用** Gateway 网关认证。如果没有配置有效的 Gateway 网关认证路径， Gateway 网关会拒绝 WebSocket 连接（失败关闭）。 -新手引导默认会生成一个 token（即使是 loopback 场景也会如此），因此 -本地客户端也必须进行认证。 +新手引导默认会生成一个 token（即使是 loopback），因此 +本地客户端也必须完成认证。 设置一个 token，这样**所有** WS 客户端都必须认证： @@ -892,142 +907,143 @@ Gateway 网关会拒绝 WebSocket 连接（失败关闭）。 } ``` -Doctor 可以为你生成一个：`openclaw doctor --generate-gateway-token`。 +Doctor 可以帮你生成一个：`openclaw doctor --generate-gateway-token`。 注意：`gateway.remote.token` / `.password` 是客户端凭证来源。 -它们本身**不会**单独保护本地 WS 访问。 -只有当 `gateway.auth.*` 未设置时，本地调用路径才会把 `gateway.remote.*` 用作回退。 +它们**本身并不会**保护本地 WS 访问。 +只有在 `gateway.auth.*` 未设置时，本地调用路径才会将 `gateway.remote.*` 用作回退。 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析， -则会以失败关闭方式处理（不会用远程回退来掩盖）。 -可选：在使用 `wss://` 时，可通过 `gateway.remote.tlsFingerprint` 固定远程 TLS。 -明文 `ws://` 默认仅限 loopback。对于受信任的私有网络 +解析会以失败关闭方式处理（不会用远程回退来掩盖问题）。 +可选项：使用 `wss://` 时，可通过 `gateway.remote.tlsFingerprint` 固定远程 TLS。 +默认情况下，明文 `ws://` 仅限 loopback。对于受信任的私有网络 路径，可在客户端进程上设置 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 作为紧急兜底。 本地设备配对： -- 为了让同主机客户端使用更顺畅，直接本地 loopback 连接的设备配对会自动批准。 -- OpenClaw 还提供了一条很窄的后端/容器本地自连接路径，用于受信任的共享密钥辅助流。 -- Tailnet 和 LAN 连接，包括同主机的 tailnet bind，都会被视为远程连接，因此仍然需要审批配对。 +- 为了保持同主机客户端的顺畅体验，直接连接 local loopback 时， + 设备配对会被自动批准。 +- OpenClaw 还提供了一条狭义的后端/容器本地自连接路径，用于 + 受信任共享密钥辅助流程。 +- Tailnet 和 LAN 连接（包括同主机 tailnet 绑定）在配对上都被视为远程连接， + 仍然需要审批。 认证模式： -- `gateway.auth.mode: "token"`：共享 bearer token（大多数场景推荐）。 -- `gateway.auth.mode: "password"`：密码认证（优先通过 env 设置：`OPENCLAW_GATEWAY_PASSWORD`）。 -- `gateway.auth.mode: "trusted-proxy"`：信任具备身份感知能力的反向代理来认证用户，并通过 header 传递身份（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。 +- `gateway.auth.mode: "token"`：共享 bearer token（大多数配置推荐使用）。 +- `gateway.auth.mode: "password"`：密码认证（建议通过环境变量设置：`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`）。 +3. 更新所有远程客户端（在调用 Gateway 网关的机器上更新 `gateway.remote.token` / `.password`）。 4. 验证旧凭证已无法再建立连接。 -### 0.6）Tailscale Serve 身份 headers +### 0.6) Tailscale Serve 身份头 当 `gateway.auth.allowTailscale` 为 `true`（Serve 的默认值）时，OpenClaw -会接受 Tailscale Serve 身份 headers（`tailscale-user-login`）用于 Control -UI/WebSocket 认证。OpenClaw 会通过本地 Tailscale 守护进程（`tailscale whois`） -解析 `x-forwarded-for` 地址并与该 header 匹配，以验证身份。只有当请求命中 loopback， -并且包含由 Tailscale 注入的 `x-forwarded-for`、`x-forwarded-proto` 和 `x-forwarded-host` 时， -才会触发这一机制。 -对于这条异步身份检查路径，同一 `{scope, ip}` 的失败尝试会先被串行化，然后限流器才记录失败。 -因此，来自同一个 Serve 客户端的并发错误重试，第二次尝试可能会立即被锁定， -而不是像两个普通不匹配那样并行冲过去。 +会接受 Tailscale Serve 身份头（`tailscale-user-login`）用于控制 UI / WebSocket 认证。OpenClaw 会通过本地 Tailscale 守护进程 +（`tailscale whois`）解析 `x-forwarded-for` 地址，并将结果与该头部匹配，以验证身份。此路径只会在请求命中 loopback 且包含由 Tailscale 注入的 +`x-forwarded-for`、`x-forwarded-proto` 和 `x-forwarded-host` 时触发。 +对于这条异步身份检查路径，同一个 `{scope, ip}` +的失败尝试会在限流器记录失败之前先被串行化。因此，来自同一个 Serve 客户端的并发错误重试 +可能会让第二次尝试立即被锁定，而不是像两个普通不匹配请求那样并发通过。 HTTP API 端点（例如 `/v1/*`、`/tools/invoke` 和 `/api/channels/*`） -**不会**使用 Tailscale 身份 header 认证。它们仍遵循 Gateway 网关 -配置的 HTTP 认证模式。 +**不会**使用 Tailscale 身份头认证。它们仍然遵循 Gateway 网关 +已配置的 HTTP 认证模式。 重要边界说明： -- Gateway 网关 HTTP bearer 认证实际上等同于全有或全无的操作员访问权限。 -- 应将能够调用 `/v1/chat/completions`、`/v1/responses` 或 `/api/channels/*` 的凭证视为该 Gateway 网关的完全访问级操作员 secrets。 -- 在 OpenAI 兼容 HTTP 界面上，共享密钥 bearer 认证会恢复完整的默认操作员作用域（`operator.admin`、`operator.approvals`、`operator.pairing`、`operator.read`、`operator.talk.secrets`、`operator.write`）以及智能体回合的 owner 语义；更窄的 `x-openclaw-scopes` 值不会缩小这一路共享密钥访问路径。 -- HTTP 上的按请求作用域语义，仅适用于带身份的模式，例如 trusted proxy 认证，或私有入口上的 `gateway.auth.mode="none"`。 -- 在这些带身份的模式中，如果省略 `x-openclaw-scopes`，会回退到普通的默认操作员作用域集合；若你希望使用更窄的作用域，请显式发送该 header。 -- `/tools/invoke` 也遵循同样的共享密钥规则：在那里，token/password bearer 认证同样被视为完整操作员访问，而带身份的模式仍会遵守声明的作用域。 -- 不要与不受信任的调用方共享这些凭证；应按信任边界分别部署独立的 Gateway 网关。 +- Gateway 网关 HTTP bearer 认证实际上等同于全量操作员访问。 +- 任何能够调用 `/v1/chat/completions`、`/v1/responses` 或 `/api/channels/*` 的凭证，都应视为该 Gateway 网关的完整访问操作员 secret。 +- 在 OpenAI 兼容 HTTP 表面上，共享 secret 的 bearer 认证会恢复完整的默认操作员作用域（`operator.admin`、`operator.approvals`、`operator.pairing`、`operator.read`、`operator.talk.secrets`、`operator.write`）以及智能体轮次中的 owner 语义；更窄的 `x-openclaw-scopes` 值不会削弱这条共享 secret 路径。 +- 只有当请求来自带身份的模式时（例如 trusted proxy auth，或私有入口上的 `gateway.auth.mode="none"`），HTTP 上的按请求作用域语义才会生效。 +- 在这些带身份的模式下，如果省略 `x-openclaw-scopes`，会回退到普通的默认操作员作用域集合；如果你希望使用更窄的作用域集合，请显式发送该头。 +- `/tools/invoke` 遵循同样的共享 secret 规则：token / password bearer auth 在这里同样被视为完整操作员访问，而带身份模式仍会遵循声明的作用域。 +- 不要将这些凭证分享给不受信任的调用方；应按信任边界使用单独的 Gateway 网关。 -**信任假设：**无 token 的 Serve 认证假定 Gateway 网关主机是受信任的。 -不要把它视为对抗同主机敌对进程的保护机制。如果不受信任的 -本地代码可能在 Gateway 网关主机上运行，请禁用 `gateway.auth.allowTailscale`， -并要求显式共享密钥认证，例如 `gateway.auth.mode: "token"` 或 +**信任假设：**无 token 的 Serve 认证假定 Gateway 网关主机本身是受信任的。 +不要把它视为对抗同主机恶意进程的保护机制。如果 Gateway 网关主机上可能运行 +不受信任的本地代码，请禁用 `gateway.auth.allowTailscale`， +并要求显式共享 secret 认证，即 `gateway.auth.mode: "token"` 或 `"password"`。 -**安全规则：**不要从你自己的反向代理转发这些 headers。如果 -你在 Gateway 网关前终止 TLS 或做代理，请禁用 -`gateway.auth.allowTailscale`，并改用共享密钥认证（`gateway.auth.mode: -"token"` 或 `"password"`），或使用 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)。 +**安全规则：**不要从你自己的反向代理转发这些头。如果 +你在 Gateway 网关前终止 TLS 或进行代理，请禁用 +`gateway.auth.allowTailscale`，并改用共享 secret 认证（`gateway.auth.mode: +"token"` 或 `"password"`）或 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)。 受信任代理： -- 如果你在 Gateway 网关前终止 TLS，请将你的代理 IP 配置到 `gateway.trustedProxies`。 -- OpenClaw 会信任来自这些 IP 的 `x-forwarded-for`（或 `x-real-ip`），用于确定客户端 IP，以便进行本地配对检查和 HTTP 认证/本地检查。 +- 如果你在 Gateway 网关前终止 TLS，请将 `gateway.trustedProxies` 设置为你的代理 IP。 +- OpenClaw 会信任这些 IP 发来的 `x-forwarded-for`（或 `x-real-ip`），以确定客户端 IP，用于本地配对检查和 HTTP 认证/本地检查。 - 确保你的代理会**覆盖** `x-forwarded-for`，并阻止对 Gateway 网关端口的直接访问。 参见 [Tailscale](/zh-CN/gateway/tailscale) 和 [Web 概览](/web)。 -### 0.6.1）通过节点主机进行浏览器控制（推荐） +### 0.6.1) 通过节点主机进行浏览器控制（推荐） -如果你的 Gateway 网关位于远端，但浏览器运行在另一台机器上，请在浏览器所在机器上运行一个**节点主机**， -并让 Gateway 网关代理浏览器操作（参见[浏览器工具](/zh-CN/tools/browser)）。 -应将节点配对视为管理员级访问。 +如果你的 Gateway 网关是远程的，但浏览器运行在另一台机器上，请在浏览器所在机器上运行一个**节点主机**， +并让 Gateway 网关代理浏览器操作（见 [Browser 工具](/zh-CN/tools/browser)）。 +应将节点配对视为管理员访问。 推荐模式： -- 让 Gateway 网关和节点主机处于同一个 tailnet（Tailscale）中。 -- 有意识地完成节点配对；如果不需要浏览器代理路由，就禁用它。 +- 让 Gateway 网关和节点主机位于同一个 tailnet（Tailscale）中。 +- 有意识地进行节点配对；如果你不需要浏览器代理路由，就将其关闭。 应避免： - 通过 LAN 或公共互联网暴露中继/控制端口。 -- 对浏览器控制端点使用 Tailscale Funnel（公共暴露）。 +- 对浏览器控制端点使用 Tailscale Funnel（公开暴露）。 -### 0.7）磁盘上的 secrets（敏感数据） +### 0.7) 磁盘上的 secrets（敏感数据） -应假定 `~/.openclaw/`（或 `$OPENCLAW_STATE_DIR/`）下的任何内容都可能包含 secrets 或私人数据： +应假定 `~/.openclaw/`（或 `$OPENCLAW_STATE_DIR/`）下的任何内容都可能包含 secret 或私密数据： - `openclaw.json`：配置中可能包含 token（Gateway 网关、远程 Gateway 网关）、提供商设置和 allowlist。 - `credentials/**`：渠道凭证（例如 WhatsApp 凭证）、配对 allowlist、旧版 OAuth 导入。 -- `agents//agent/auth-profiles.json`：API keys、token profiles、OAuth tokens，以及可选的 `keyRef`/`tokenRef`。 -- `secrets.json`（可选）：供 `file` SecretRef providers（`secrets.providers`）使用的基于文件的 secret 载荷。 -- `agents//agent/auth.json`：旧版兼容文件。发现静态 `api_key` 条目时会清除。 -- `agents//sessions/**`：会话转录（`*.jsonl`）+ 路由元数据（`sessions.json`），其中可能包含私人消息和工具输出。 -- 内置插件包：已安装插件（以及它们的 `node_modules/`）。 -- `sandboxes/**`：工具沙箱工作区；可能会积累你在沙箱内读取/写入文件的副本。 +- `agents//agent/auth-profiles.json`：API 密钥、token 配置文件、OAuth token，以及可选的 `keyRef` / `tokenRef`。 +- `secrets.json`（可选）：由 `file` SecretRef 提供商（`secrets.providers`）使用的基于文件的 secret 载荷。 +- `agents//agent/auth.json`：旧版兼容文件。发现后会清除静态 `api_key` 条目。 +- `agents//sessions/**`：会话转录（`*.jsonl`）和路由元数据（`sessions.json`），其中可能包含私密消息和工具输出。 +- 内置 plugin 包：已安装的 plugins（以及它们的 `node_modules/`）。 +- `sandboxes/**`：工具沙箱工作区；可能会累积你在沙箱内读写文件的副本。 加固建议： - 保持严格权限（目录 `700`，文件 `600`）。 -- 在 Gateway 网关主机上使用全盘加密。 -- 如果主机是共享的，优先为 Gateway 网关使用专用 OS 用户账号。 +- 在 Gateway 网关主机上启用全盘加密。 +- 如果主机是共享的，建议为 Gateway 网关使用专用 OS 用户账号。 -### 0.8）工作区 `.env` 文件 +### 0.8) 工作区 `.env` 文件 -OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不会允许这些文件悄悄覆盖 Gateway 网关运行时控制项。 +OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不会让这些文件悄悄覆盖 Gateway 网关运行时控制项。 -- 任何以 `OPENCLAW_*` 开头的键都会在不受信任的工作区 `.env` 文件中被阻止。 -- 这种阻止方式是失败关闭：即使未来版本新增了某个运行时控制变量，也不会从已提交或攻击者提供的 `.env` 中被继承；该键会被忽略，Gateway 网关会保留自己的值。 -- 受信任的进程/OS 环境变量（Gateway 网关自己的 shell、launchd/systemd 单元、app bundle）仍然生效——此规则只限制 `.env` 文件加载。 +- 任何以 `OPENCLAW_*` 开头的键都会从不受信任的工作区 `.env` 文件中被阻止。 +- 这种阻止是失败关闭的：将来版本中新增加的运行时控制变量，不能从已提交或由攻击者提供的 `.env` 中继承；该键会被忽略，Gateway 网关会保留自己的值。 +- 受信任的进程/OS 环境变量（Gateway 网关自身的 shell、launchd / systemd 单元、应用包）仍然有效——这里只限制 `.env` 文件加载。 -原因：工作区 `.env` 文件通常与智能体代码放在一起，容易被误提交，或者被工具写入。阻止整个 `OPENCLAW_*` 前缀，意味着以后即使新增了某个 `OPENCLAW_*` 标志，也绝不会退化为从工作区状态中静默继承。 +原因：工作区 `.env` 文件经常和智能体代码放在一起，容易被意外提交，或由工具写入。阻止整个 `OPENCLAW_*` 前缀意味着，将来即使新增了某个 `OPENCLAW_*` 标志，也绝不会退化为从工作区状态中静默继承。 -### 0.9）日志 + 转录（脱敏 + 保留） +### 0.9) 日志 + 转录内容（脱敏 + 保留） -即使访问控制正确，日志和转录仍可能泄露敏感信息： +即使访问控制是正确的，日志和转录内容也可能泄露敏感信息： - Gateway 网关日志可能包含工具摘要、错误和 URL。 -- 会话转录可能包含粘贴的 secrets、文件内容、命令输出和链接。 +- 会话转录可能包含粘贴的 secret、文件内容、命令输出和链接。 建议： - 保持工具摘要脱敏开启（`logging.redactSensitive: "tools"`；默认值）。 - 通过 `logging.redactPatterns` 为你的环境添加自定义模式（token、主机名、内部 URL）。 -- 分享诊断信息时，优先使用 `openclaw status --all`（可直接粘贴，secrets 已脱敏），而不是原始日志。 -- 如果你不需要长期保留，请清理旧的会话转录和日志文件。 +- 分享诊断信息时，优先使用 `openclaw status --all`（可直接粘贴，secret 已脱敏），而不是原始日志。 +- 如果不需要长期保留，请清理旧的会话转录和日志文件。 -详情见：[日志记录](/zh-CN/gateway/logging) +详见：[日志](/zh-CN/gateway/logging) -### 1）私信：默认使用 pairing +### 1) 私信：默认使用 pairing ```json5 { @@ -1035,7 +1051,7 @@ OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不 } ``` -### 2）群组：全局要求提及 +### 2) 群组：在所有地方都要求 mention ```json { @@ -1057,31 +1073,31 @@ OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不 } ``` -在群聊中，仅在被明确提及时才响应。 +在群聊中，只在被明确提及时才响应。 -### 3）使用独立号码（WhatsApp、Signal、Telegram） +### 3) 分离号码（WhatsApp、Signal、Telegram） -对于基于手机号的渠道，请考虑让你的 AI 使用与个人号码分开的独立号码： +对于基于手机号的渠道，建议考虑让你的 AI 使用与个人号码不同的独立号码： - 个人号码：你的对话保持私密 -- 机器人号码：AI 处理这些消息，并配置适当边界 +- 机器人号码：由 AI 处理，并设置适当边界 -### 4）只读模式（通过沙箱 + 工具） +### 4) 只读模式（通过沙箱 + 工具） -你可以通过以下组合构建只读 profile： +你可以通过组合以下设置构建只读 profile： -- `agents.defaults.sandbox.workspaceAccess: "ro"`（或 `"none"`，表示完全无工作区访问） -- 工具 allow/deny 列表，用于阻止 `write`、`edit`、`apply_patch`、`exec`、`process` 等 +- `agents.defaults.sandbox.workspaceAccess: "ro"`（或者使用 `"none"` 完全不允许工作区访问） +- 阻止 `write`、`edit`、`apply_patch`、`exec`、`process` 等的工具 allow / deny 列表 额外加固选项： -- `tools.exec.applyPatch.workspaceOnly: true`（默认）：确保 `apply_patch` 即使在未启用沙箱隔离时，也不能在工作区目录之外写入/删除。只有在你明确希望 `apply_patch` 操作工作区外文件时，才将其设为 `false`。 -- `tools.fs.workspaceOnly: true`（可选）：将 `read`/`write`/`edit`/`apply_patch` 路径以及原生提示图像自动加载路径限制在工作区目录内（如果你当前允许绝对路径并希望增加一个统一护栏，这会很有用）。 -- 保持文件系统根目录范围狭窄：避免把主目录这类宽泛根目录用作智能体工作区/沙箱工作区。宽泛根目录可能会让文件系统工具暴露敏感本地文件（例如 `~/.openclaw` 下的 state/config）。 +- `tools.exec.applyPatch.workspaceOnly: true`（默认）：确保即使关闭了沙箱隔离，`apply_patch` 也不能在工作区目录之外写入/删除。只有当你明确希望 `apply_patch` 操作工作区之外的文件时，才设置为 `false`。 +- `tools.fs.workspaceOnly: true`（可选）：将 `read` / `write` / `edit` / `apply_patch` 路径，以及原生提示图片自动加载路径限制在工作区目录内（如果你当前允许绝对路径，并希望增加一个统一防护，这会很有用）。 +- 保持文件系统根路径尽可能窄：避免把主目录这样的宽泛根路径用作智能体工作区/沙箱工作区。宽泛根路径可能会把敏感本地文件（例如 `~/.openclaw` 下的状态/配置）暴露给文件系统工具。 -### 5）安全基线（可直接复制） +### 5) 安全基线（可复制粘贴） -一个“默认较安全”的配置，可以保持 Gateway 网关私有、要求私信 pairing，并避免始终在线的群组机器人： +一个“安全默认”的配置示例：让 Gateway 网关保持私有、要求私信 pairing，并避免在群组中使用始终在线的机器人： ```json5 { @@ -1100,9 +1116,9 @@ OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不 } ``` -如果你还希望工具执行也“默认更安全”，可为任何非 owner 智能体添加沙箱隔离 + 拒绝危险工具（下文“按智能体划分的访问 profile”中有示例）。 +如果你还希望工具执行也“默认更安全”，请为任何非所有者智能体添加沙箱并拒绝危险工具（见下文“按智能体划分的访问 profile”示例）。 -针对聊天驱动的智能体回合，内置基线规则是：非 owner 发送者不能使用 `cron` 或 `gateway` 工具。 +对于聊天驱动的智能体轮次，内置基线会阻止非所有者发送者使用 `cron` 或 `gateway` 工具。 ## 沙箱隔离（推荐） @@ -1111,58 +1127,58 @@ OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不 两种互补方式： - **在 Docker 中运行整个 Gateway 网关**（容器边界）：[Docker](/zh-CN/install/docker) -- **工具沙箱**（`agents.defaults.sandbox`，主机上的 Gateway 网关 + 经过沙箱隔离的工具；Docker 是默认后端）：[沙箱隔离](/zh-CN/gateway/sandboxing) +- **工具沙箱**（`agents.defaults.sandbox`，Gateway 网关运行在主机上，工具在沙箱中隔离；Docker 是默认后端）：[沙箱隔离](/zh-CN/gateway/sandboxing) -注意：为防止跨智能体访问，请将 `agents.defaults.sandbox.scope` 保持为 `"agent"`（默认） -或使用 `"session"` 以获得更严格的按会话隔离。`scope: "shared"` 会使用 -单一容器/工作区。 +注意：为了防止跨智能体访问，请将 `agents.defaults.sandbox.scope` 保持为 `"agent"`（默认） +或使用 `"session"` 以获得更严格的按 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` 会根据标准化和规范化后的源路径进行校验。如果父级符号链接技巧或规范化后的主目录别名最终解析到受阻止根目录，例如 `/etc`、`/var/run` 或 OS 主目录下的凭证目录，仍会以失败关闭方式处理。 +- 额外的 `sandbox.docker.binds` 会根据归一化和规范化后的源路径进行验证。如果解析结果落入 `/etc`、`/var/run` 或 OS 主目录下凭证目录等被阻止的根路径，那么父级符号链接技巧和规范化 home 别名仍会以失败关闭方式处理。 -重要说明：`tools.elevated` 是一个全局基线逃逸口，会让 exec 在沙箱外运行。其默认有效 host 是 `gateway`，当 exec 目标配置为 `node` 时则为 `node`。请保持 `tools.elevated.allowFrom` 尽量严格，不要对陌生人启用。你还可以通过 `agents.list[].tools.elevated` 对单个智能体进一步限制 elevated。参见[高权限模式](/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)。 -### 子智能体委派护栏 +### 子智能体委派防护 -如果你允许使用会话工具，应将委派给子智能体的运行视为另一个边界决策： +如果你允许使用 session 工具，应将委派给子智能体的运行视为另一项边界决策： -- 除非智能体确实需要委派，否则拒绝 `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 视为**敏感状态**： +启用浏览器控制意味着模型可以驱动一个真实浏览器。 +如果该浏览器配置文件中已经登录了账号，模型就能 +访问这些账号和数据。应将浏览器配置文件视为**敏感状态**： -- 优先为智能体使用专用 profile（默认的 `openclaw` profile）。 -- 避免让智能体使用你个人日常使用的 profile。 -- 对经过沙箱隔离的智能体，除非你信任它们，否则应保持主机浏览器控制关闭。 -- 独立的 loopback 浏览器控制 API 只接受共享密钥认证 +- 优先为智能体使用专用配置文件（默认的 `openclaw` 配置文件）。 +- 不要让智能体使用你的个人日常浏览器配置文件。 +- 对于沙箱隔离的智能体，除非你信任它们，否则保持主机浏览器控制关闭。 +- 独立的 loopback 浏览器控制 API 只接受共享 secret 认证 （Gateway 网关 token bearer auth 或 Gateway 网关 password）。它不会使用 - trusted-proxy 或 Tailscale Serve 身份 headers。 -- 将浏览器下载内容视为不受信任输入；优先使用隔离的下载目录。 -- 如有可能，在智能体 profile 中禁用浏览器同步/密码管理器（可缩小影响半径）。 -- 对于远程 Gateway 网关，应将“浏览器控制”等同于“对该 profile 可访问内容的操作员级访问”。 -- 保持 Gateway 网关和节点主机仅在 tailnet 内可访问；避免将浏览器控制端口暴露到 LAN 或公共互联网。 -- 不需要浏览器代理路由时，请将其关闭（`gateway.nodes.browser.mode="off"`）。 -- Chrome MCP 现有会话模式**并不**“更安全”；它会以你的身份操作该主机 Chrome profile 可访问的一切内容。 + trusted-proxy 或 Tailscale Serve 身份头。 +- 应将浏览器下载内容视为不受信任输入；优先使用隔离的下载目录。 +- 尽可能在智能体配置文件中禁用浏览器同步/密码管理器（可缩小影响半径）。 +- 对于远程 Gateway 网关，应假定“浏览器控制”等同于对该配置文件可访问内容的“操作员访问”。 +- 让 Gateway 网关和节点主机仅位于 tailnet 中；避免将浏览器控制端口暴露到 LAN 或公共互联网。 +- 如果不需要浏览器代理路由，就关闭它（`gateway.nodes.browser.mode="off"`）。 +- Chrome MCP 现有 session 模式**并不**“更安全”；它可以像你一样操作该主机上 Chrome 配置文件可访问的任何内容。 -### 浏览器 SSRF 策略（默认严格） +### Browser SSRF 策略（默认严格） -OpenClaw 的浏览器导航策略默认非常严格：除非你显式选择加入，否则私有/内部目标会被阻止。 +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 上尽力再次检查，以减少基于重定向的跳转利用。 严格策略示例： @@ -1180,17 +1196,17 @@ OpenClaw 的浏览器导航策略默认非常严格：除非你显式选择加 ## 按智能体划分的访问 profile（多智能体） -在多智能体路由中，每个智能体都可以拥有自己的沙箱隔离 + 工具策略： -利用这一点，你可以按智能体赋予**完全访问**、**只读**或**无访问**权限。 -完整细节和优先级规则见[多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 +在多智能体路由下，每个智能体都可以有自己的沙箱隔离 + 工具策略： +利用这一点，你可以按智能体分别赋予**完全访问**、**只读**或**无访问**。 +完整细节和优先级规则见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 常见用例： -- 个人智能体：完全访问，不启用沙箱 -- 家庭/工作智能体：启用沙箱 + 只读工具 -- 公开智能体：启用沙箱 + 无文件系统/shell 工具 +- 个人智能体：完全访问，不使用沙箱 +- 家庭/工作智能体：沙箱隔离 + 只读工具 +- 公开智能体：沙箱隔离 + 不允许文件系统/shell 工具 -### 示例：完全访问（无沙箱） +### 示例：完全访问（不使用沙箱） ```json5 { @@ -1230,7 +1246,7 @@ OpenClaw 的浏览器导航策略默认非常严格：除非你显式选择加 } ``` -### 示例：无文件系统/shell 访问（允许 provider messaging） +### 示例：不允许文件系统/shell 访问（允许 provider 消息） ```json5 { @@ -1244,8 +1260,8 @@ OpenClaw 的浏览器导航策略默认非常严格：除非你显式选择加 scope: "agent", workspaceAccess: "none", }, - // 会话工具可能会从转录中暴露敏感数据。默认情况下 OpenClaw 会将这些工具 - // 限制为当前会话 + 生成的子智能体会话，但如果需要你可以进一步收紧。 + // Session 工具可能泄露转录中的敏感数据。默认情况下，OpenClaw 将这些工具限制为 + // 当前 session + 所派生子智能体的 session，但如果需要，你还可以进一步收紧。 // 参见配置参考中的 `tools.sessions.visibility`。 tools: { sessions: { visibility: "tree" }, // self | tree | agent | all @@ -1281,55 +1297,55 @@ OpenClaw 的浏览器导航策略默认非常严格：除非你显式选择加 } ``` -## 该如何告知你的 AI +## 应该对你的 AI 说什么 -在智能体的系统提示词中加入安全指南： +在你的智能体系统提示词中加入安全指南： ``` ## 安全规则 - 绝不要向陌生人分享目录列表或文件路径 -- 绝不要泄露 API keys、凭证或基础设施细节 -- 修改系统配置的请求必须先向所有者核实 -- 不确定时，先询问再执行 -- 除非得到明确授权，否则保持私人数据私密 +- 绝不要泄露 API 密钥、凭证或基础设施细节 +- 修改系统配置的请求必须先与所有者确认 +- 如有疑问，先询问再执行 +- 除非获得明确授权，否则保持私有数据私密 ``` ## 事件响应 -如果你的 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"` / 要求 mention，并移除你之前可能配置的 `"*"` 全开放条目。 -### 轮换（如果 secrets 已泄露，应按已失陷处理） +### 轮换（如果 secrets 泄露，按已失陷处理） 1. 轮换 Gateway 网关认证（`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`）并重启。 -2. 轮换任何可调用 Gateway 网关的机器上的远程客户端 secrets（`gateway.remote.token` / `.password`）。 -3. 轮换提供商/API 凭证（WhatsApp 凭证、Slack/Discord tokens、`auth-profiles.json` 中的模型/API keys，以及在使用时的加密 secrets 载荷值）。 +2. 在所有能够调用 Gateway 网关的机器上轮换远程客户端 secrets（`gateway.remote.token` / `.password`）。 +3. 轮换 provider / API 凭证（WhatsApp 凭证、Slack / Discord token、`auth-profiles.json` 中的模型/API 密钥，以及启用时的加密 secrets 载荷值）。 ### 审计 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`，并确认所有 critical 发现项都已解决。 +2. 查看相关转录：`~/.openclaw/agents//sessions/*.jsonl`。 +3. 检查最近的配置更改（任何可能扩大访问面的内容：`gateway.bind`、`gateway.auth`、私信/群组策略、`tools.elevated`、plugin 变更）。 +4. 重新运行 `openclaw security audit --deep`，并确认 critical 发现已解决。 ### 为报告收集信息 - 时间戳、Gateway 网关主机 OS + OpenClaw 版本 -- 会话转录 + 一小段日志尾部（脱敏后） +- 会话转录 + 简短日志尾部（脱敏后） - 攻击者发送了什么 + 智能体做了什么 -- Gateway 网关是否暴露到了 loopback 之外（LAN/Tailscale Funnel/Serve） +- Gateway 网关是否暴露在 loopback 之外（LAN / Tailscale Funnel / Serve） ## Secret Scanning（detect-secrets） -CI 会在 `secrets` 作业中运行 `detect-secrets` pre-commit hook。 -推送到 `main` 时总是执行全文件扫描。Pull request 会在有基准 commit -可用时使用按变更文件的快速路径，否则回退为全文件扫描。如果失败， -说明存在尚未写入 baseline 的新候选项。 +CI 会在 `secrets` job 中运行 `detect-secrets` pre-commit hook。 +推送到 `main` 时总是执行全文件扫描。Pull request 在存在基准 commit 时 +会走已更改文件的快速路径，否则回退到全文件扫描。 +如果失败，说明出现了尚未写入 baseline 的新候选项。 ### 如果 CI 失败 @@ -1341,25 +1357,25 @@ CI 会在 `secrets` 作业中运行 `detect-secrets` pre-commit hook。 2. 了解这些工具： - pre-commit 中的 `detect-secrets` 会结合仓库的 - baseline 和 excludes 运行 `detect-secrets-hook`。 - - `detect-secrets audit` 会打开一个交互式审查界面，用于将 baseline + baseline 和排除规则运行 `detect-secrets-hook`。 + - `detect-secrets audit` 会打开交互式审查，将 baseline 中的每一项标记为真实 secret 或误报。 -3. 对于真实 secrets：轮换/删除它们，然后重新运行扫描以更新 baseline。 +3. 对于真实 secret：轮换/移除它们，然后重新运行扫描以更新 baseline。 4. 对于误报：运行交互式审查并将其标记为误报： ```bash detect-secrets audit .secrets.baseline ``` -5. 如果你需要新增 excludes，请将它们添加到 `.detect-secrets.cfg`，并使用匹配的 `--exclude-files` / `--exclude-lines` 参数重新生成 +5. 如果你需要新增排除规则，请将其加入 `.detect-secrets.cfg`，并使用匹配的 `--exclude-files` / `--exclude-lines` 标志重新生成 baseline（该配置文件仅供参考；detect-secrets 不会自动读取它）。 -当 `.secrets.baseline` 反映了预期状态后，提交更新后的文件。 +当 `.secrets.baseline` 反映出预期状态后，提交更新后的文件。 ## 报告安全问题 在 OpenClaw 中发现了漏洞？请负责任地报告： -1. 邮件：[security@openclaw.ai](mailto:security@openclaw.ai) -2. 在问题修复前不要公开披露 -3. 我们会注明致谢（除非你希望匿名） +1. 发送邮件至：[security@openclaw.ai](mailto:security@openclaw.ai) +2. 在修复前不要公开发布 +3. 我们会注明你的贡献（除非你希望匿名）