From 4e55962aaebda7730f93c1b7c9932736c2b868e4 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 22:11:58 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/gateway.md | 228 +++--- docs/zh-CN/cli/hooks.md | 78 +- docs/zh-CN/gateway/security/index.md | 1003 +++++++++++++------------- 3 files changed, 663 insertions(+), 646 deletions(-) diff --git a/docs/zh-CN/cli/gateway.md b/docs/zh-CN/cli/gateway.md index 9f9c65362..b671081df 100644 --- a/docs/zh-CN/cli/gateway.md +++ b/docs/zh-CN/cli/gateway.md @@ -1,24 +1,24 @@ --- read_when: - - 从 CLI 运行 Gateway 网关（开发或服务器环境） + - 从 CLI 运行 Gateway 网关（开发或服务器） - 调试 Gateway 网关认证、绑定模式和连接性 - - 通过 Bonjour 发现 Gateway 网关（本地 + 广域 DNS-SD） -summary: OpenClaw Gateway 网关 CLI（`openclaw gateway`）——运行、查询和发现 Gateway 网关 + - 通过 Bonjour 发现网关（本地 + 广域 DNS-SD） +summary: OpenClaw Gateway 网关 CLI（`openclaw gateway`）——运行、查询和发现网关 title: Gateway 网关 x-i18n: - generated_at: "2026-04-24T04:01:10Z" + generated_at: "2026-04-25T22:08:07Z" model: gpt-5.4 provider: openai - source_hash: 011b8c8f86de6ecafbf17357a458956357ebe8285fe86e2bf875a4e2d87b5126 + source_hash: ce8f72ad74fc2956520c1c3af2252a5b22b3bda0f2023c5ca76cf8cddb1c0edb source_path: cli/gateway.md workflow: 15 --- # Gateway 网关 CLI -Gateway 网关是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、hooks）。 +Gateway 网关是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、钩子）。 -本页中的子命令位于 `openclaw gateway …` 之下。 +本页中的子命令位于 `openclaw gateway …` 下。 相关文档： @@ -40,27 +40,27 @@ openclaw gateway openclaw gateway run ``` -注意事项： +说明： -- 默认情况下，除非在 `~/.openclaw/openclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway 网关会拒绝启动。临时/开发运行可使用 `--allow-unconfigured`。 -- `openclaw onboard --mode local` 和 `openclaw setup` 预期会写入 `gateway.mode=local`。如果文件存在但缺少 `gateway.mode`，应将其视为损坏或被覆盖的配置，并修复它，而不是隐式假定为本地模式。 -- 如果文件存在且缺少 `gateway.mode`，Gateway 网关会将其视为可疑的配置损坏，并拒绝替你“猜测为本地模式”。 -- 在无认证的情况下绑定到 loopback 之外会被阻止（安全护栏）。 -- 当获得授权时，`SIGUSR1` 会触发进程内重启（默认启用 `commands.restart`；设置 `commands.restart: false` 可阻止手动重启，而 gateway 工具/配置 apply/update 仍然允许）。 -- `SIGINT`/`SIGTERM` 处理器会停止 gateway 进程，但不会恢复任何自定义终端状态。如果你用 TUI 或 raw mode 输入包装 CLI，请在退出前恢复终端。 +- 默认情况下，除非在 `~/.openclaw/openclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway 网关会拒绝启动。对于临时/开发运行，请使用 `--allow-unconfigured`。 +- 预期 `openclaw onboard --mode local` 和 `openclaw setup` 会写入 `gateway.mode=local`。如果该文件存在但缺少 `gateway.mode`，应将其视为损坏或被覆盖的配置，并修复它，而不是隐式假定为本地模式。 +- 如果该文件存在且缺少 `gateway.mode`，Gateway 网关会将其视为可疑的配置损坏，并拒绝为你“猜测本地”。 +- 未启用认证时，禁止绑定到 loopback 之外的地址（安全护栏）。 +- 当已获授权时，`SIGUSR1` 会触发进程内重启（默认启用 `commands.restart`；设置 `commands.restart: false` 可阻止手动重启，但 gateway 工具/config apply/update 仍然允许）。 +- `SIGINT`/`SIGTERM` 处理程序会停止 gateway 进程，但不会恢复任何自定义终端状态。如果你用 TUI 或 raw-mode 输入封装 CLI，请在退出前恢复终端。 ### 选项 -- `--port `：WebSocket 端口（默认来自配置/环境；通常为 `18789`）。 +- `--port `：WebSocket 端口（默认值来自配置/环境变量；通常为 `18789`）。 - `--bind `：监听器绑定模式。 - `--auth `：认证模式覆盖。 -- `--token `：令牌覆盖（同时为该进程设置 `OPENCLAW_GATEWAY_TOKEN`）。 +- `--token `：token 覆盖（也会为该进程设置 `OPENCLAW_GATEWAY_TOKEN`）。 - `--password `：密码覆盖。警告：内联密码可能会暴露在本地进程列表中。 - `--password-file `：从文件读取 gateway 密码。 - `--tailscale `：通过 Tailscale 暴露 Gateway 网关。 - `--tailscale-reset-on-exit`：关闭时重置 Tailscale serve/funnel 配置。 -- `--allow-unconfigured`：允许在配置中没有 `gateway.mode=local` 时启动 gateway。它只会绕过临时/开发引导的启动保护，不会写入或修复配置文件。 -- `--dev`：如果缺失，则创建开发配置和工作区（跳过 `BOOTSTRAP.md`）。 +- `--allow-unconfigured`：允许在配置中没有 `gateway.mode=local` 的情况下启动 gateway。此选项仅绕过临时/开发引导的启动保护；不会写入或修复配置文件。 +- `--dev`：如果缺失则创建开发配置 + 工作区（跳过 `BOOTSTRAP.md`）。 - `--reset`：重置开发配置 + 凭证 + 会话 + 工作区（需要 `--dev`）。 - `--force`：启动前终止所选端口上的任何现有监听器。 - `--verbose`：详细日志。 @@ -73,7 +73,7 @@ openclaw gateway run 启动分析： - 设置 `OPENCLAW_GATEWAY_STARTUP_TRACE=1` 以在 Gateway 网关启动期间记录各阶段耗时。 -- 运行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 以对 Gateway 网关启动进行基准测试。该基准会记录首个进程输出、`/healthz`、`/readyz` 以及启动跟踪耗时。 +- 运行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 以对 Gateway 网关启动进行基准测试。该基准会记录首个进程输出、`/healthz`、`/readyz` 和启动跟踪耗时。 ## 查询正在运行的 Gateway 网关 @@ -82,19 +82,19 @@ openclaw gateway run 输出模式： - 默认：人类可读（在 TTY 中带颜色）。 -- `--json`：机器可读 JSON（无样式/无 spinner）。 +- `--json`：机器可读 JSON（无样式/旋转指示器）。 - `--no-color`（或 `NO_COLOR=1`）：禁用 ANSI，同时保留人类可读布局。 -共享选项（在支持的命令中）： +共享选项（在支持的地方）： - `--url `：Gateway 网关 WebSocket URL。 -- `--token `：Gateway 网关令牌。 +- `--token `：Gateway 网关 token。 - `--password `：Gateway 网关密码。 -- `--timeout `：超时/预算（随命令而异）。 +- `--timeout `：超时/预算（因命令而异）。 - `--expect-final`：等待“final”响应（智能体调用）。 -注意：设置 `--url` 时，CLI 不会回退到配置或环境凭证。 -请显式传入 `--token` 或 `--password`。缺少显式凭证会报错。 +注意：当你设置 `--url` 时，CLI 不会回退到配置或环境变量凭证。 +请显式传递 `--token` 或 `--password`。缺少显式凭证会报错。 ### `gateway health` @@ -102,11 +102,11 @@ openclaw gateway run openclaw gateway health --url ws://127.0.0.1:18789 ``` -HTTP `/healthz` 端点是存活探针：只要服务器能够响应 HTTP，它就会返回。HTTP `/readyz` 端点更严格；在启动 sidecar、渠道或已配置 hooks 仍在稳定期间，它会保持未就绪状态。 +HTTP `/healthz` 端点是存活探针：一旦服务器可以响应 HTTP，它就会返回。HTTP `/readyz` 端点更严格，在启动 sidecar、渠道或已配置钩子仍在稳定期间，它会持续显示未就绪。 ### `gateway usage-cost` -从会话日志获取 usage-cost 汇总。 +从会话日志中获取 usage-cost 汇总。 ```bash openclaw gateway usage-cost @@ -120,7 +120,7 @@ openclaw gateway usage-cost --json ### `gateway stability` -从正在运行的 Gateway 网关获取最近的诊断稳定性记录器内容。 +从正在运行的 Gateway 网关中获取最近的诊断稳定性记录器。 ```bash openclaw gateway stability @@ -132,22 +132,22 @@ openclaw gateway stability --json 选项： -- `--limit `：包含的最近事件最大数量（默认 `25`，最大 `1000`）。 +- `--limit `：要包含的最近事件最大数量（默认 `25`，最大 `1000`）。 - `--type `：按诊断事件类型过滤，例如 `payload.large` 或 `diagnostic.memory.pressure`。 - `--since-seq `：仅包含某个诊断序列号之后的事件。 -- `--bundle [path]`：读取持久化的稳定性 bundle，而不是调用正在运行的 Gateway 网关。使用 `--bundle latest`（或仅 `--bundle`）可读取状态目录下最新的 bundle，或直接传入 bundle JSON 路径。 +- `--bundle [path]`：读取持久化的稳定性 bundle，而不是调用正在运行的 Gateway 网关。使用 `--bundle latest`（或仅 `--bundle`）读取状态目录下最新的 bundle，或直接传入 bundle JSON 路径。 - `--export`：写出可共享的支持诊断 zip，而不是打印稳定性详情。 - `--output `：`--export` 的输出路径。 -注意事项： +说明： -- 记录会保留运行元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、cookies、密钥值、主机名或原始会话 ID。设置 `diagnostics.enabled: false` 可完全禁用该记录器。 -- 当 Gateway 网关发生致命退出、关闭超时和重启启动失败时，只要记录器中存在事件，OpenClaw 就会将相同的诊断快照写入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。可使用 `openclaw gateway stability --bundle latest` 检查最新 bundle；`--limit`、`--type` 和 `--since-seq` 同样适用于 bundle 输出。 +- 记录会保留运维元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称，以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、token、cookie、密钥值、主机名或原始会话 id。设置 `diagnostics.enabled: false` 可完全禁用记录器。 +- 在 Gateway 网关致命退出、关闭超时和重启启动失败时，只要记录器中有事件，OpenClaw 就会将相同的诊断快照写入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。使用 `openclaw gateway stability --bundle latest` 可检查最新 bundle；`--limit`、`--type` 和 `--since-seq` 也适用于 bundle 输出。 ### `gateway diagnostics export` -写出一个本地诊断 zip，设计用于附加到错误报告中。 -关于隐私模型和 bundle 内容，参见 [Diagnostics Export](/zh-CN/gateway/diagnostics)。 +写出一个本地诊断 zip，用于附加到缺陷报告。 +有关隐私模型和 bundle 内容，请参见 [Diagnostics Export](/zh-CN/gateway/diagnostics)。 ```bash openclaw gateway diagnostics export @@ -158,22 +158,22 @@ openclaw gateway diagnostics export --json 选项： - `--output `：输出 zip 路径。默认为状态目录下的支持导出文件。 -- `--log-lines `：要包含的已脱敏日志行最大数量（默认 `5000`）。 +- `--log-lines `：要包含的最大脱敏日志行数（默认 `5000`）。 - `--log-bytes `：要检查的最大日志字节数（默认 `1000000`）。 -- `--url `：用于健康快照的 Gateway 网关 WebSocket URL。 -- `--token `：用于健康快照的 Gateway 网关令牌。 -- `--password `：用于健康快照的 Gateway 网关密码。 -- `--timeout `：状态/健康快照超时（默认 `3000`）。 +- `--url `：用于健康状态快照的 Gateway 网关 WebSocket URL。 +- `--token `：用于健康状态快照的 Gateway 网关 token。 +- `--password `：用于健康状态快照的 Gateway 网关密码。 +- `--timeout `：status/health 快照超时（默认 `3000`）。 - `--no-stability-bundle`：跳过持久化稳定性 bundle 查找。 -- `--json`：以 JSON 形式打印已写入路径、大小和 manifest。 +- `--json`：以 JSON 格式打印写出的路径、大小和清单。 -导出内容包含一个 manifest、一个 Markdown 摘要、配置形状、已脱敏的配置详情、已脱敏的日志摘要、已脱敏的 Gateway 网关状态/健康快照，以及存在时的最新稳定性 bundle。 +该导出包含清单、Markdown 摘要、配置形状、脱敏配置详情、脱敏日志摘要、脱敏后的 Gateway 网关 status/health 快照，以及存在时的最新稳定性 bundle。 -它旨在被共享。它会保留有助于调试的运行细节，例如安全的 OpenClaw 日志字段、子系统名称、状态码、耗时、已配置模式、端口、插件 ID、提供商 ID、非密钥功能设置以及已脱敏的运行日志消息。它会省略或脱敏聊天文本、webhook 正文、工具输出、凭证、cookies、账户/消息标识符、提示词/指令文本、主机名和密钥值。当某条 LogTape 风格消息看起来像用户/聊天/工具有效负载文本时，导出只会保留“某条消息已省略”以及其字节数。 +它 предназначено 用于共享。它会保留有助于调试的运维细节，例如安全的 OpenClaw 日志字段、子系统名称、状态码、持续时间、已配置模式、端口、插件 id、provider id、非敏感功能设置，以及已脱敏的运维日志消息。它会省略或脱敏聊天文本、webhook 正文、工具输出、凭证、cookie、账户/消息标识符、提示词/指令文本、主机名和密钥值。当某条 LogTape 风格消息看起来像用户/聊天/工具负载文本时，导出只会保留“某条消息已被省略”及其字节计数。 ### `gateway status` -`gateway status` 会显示 Gateway 网关服务（launchd/systemd/schtasks），以及可选的连接性/认证能力探测。 +`gateway status` 显示 Gateway 网关服务（launchd/systemd/schtasks），以及可选的连接性/认证能力探测。 ```bash openclaw gateway status @@ -183,43 +183,44 @@ openclaw gateway status --require-rpc 选项： -- `--url `：添加一个显式探测目标。仍会探测已配置的远程目标和 localhost。 -- `--token `：用于探测的令牌认证。 +- `--url `：添加一个显式探测目标。仍会探测已配置的远程目标 + localhost。 +- `--token `：用于探测的 token 认证。 - `--password `：用于探测的密码认证。 - `--timeout `：探测超时（默认 `10000`）。 - `--no-probe`：跳过连接性探测（仅服务视图）。 -- `--deep`：同时扫描系统级服务。 -- `--require-rpc`：将默认连接性探测升级为读取探测，并在读取探测失败时以非零状态退出。不能与 `--no-probe` 组合使用。 +- `--deep`：也扫描系统级服务。 +- `--require-rpc`：将默认的连接性探测升级为读探测，并在该读探测失败时以非零状态退出。不能与 `--no-probe` 结合使用。 -注意事项： +说明： - 即使本地 CLI 配置缺失或无效，`gateway status` 仍可用于诊断。 -- 默认的 `gateway status` 可证明服务状态、WebSocket 连接以及握手时可见的认证能力。它不能证明读/写/管理操作可用。 -- `gateway status` 会在可能的情况下解析已配置的认证 SecretRef，以用于探测认证。 -- 如果此命令路径中某个必需的认证 SecretRef 无法解析，并且探测连接/认证失败，`gateway status --json` 会报告 `rpc.authWarning`；请显式传入 `--token`/`--password`，或先解析对应的密钥来源。 -- 如果探测成功，则会抑制未解析的 auth-ref 警告，以避免误报。 -- 当脚本和自动化场景中仅有监听中的服务还不够、你还需要读取范围的 RPC 调用也保持健康时，请使用 `--require-rpc`。 -- `--deep` 会添加尽力而为的额外 launchd/systemd/schtasks 安装扫描。当检测到多个类似 Gateway 网关的服务时，人类可读输出会打印清理提示，并警告大多数设置应在每台机器上运行一个 Gateway 网关。 -- 人类可读输出会包含解析后的文件日志路径，以及 CLI 与服务的配置路径/有效性快照，以帮助诊断配置文件或状态目录漂移。 -- 在 Linux 的 systemd 安装中，服务认证漂移检查会同时读取单元中的 `Environment=` 和 `EnvironmentFile=` 值（包括 `%h`、带引号路径、多个文件以及可选的 `-` 文件）。 -- 漂移检查会使用合并后的运行时环境解析 `gateway.auth.token` SecretRef（优先使用服务命令环境，其次回退到进程环境）。 -- 如果令牌认证实际上未启用（`gateway.auth.mode` 明确为 `password`/`none`/`trusted-proxy`，或在未设置 mode 且 password 可能生效并且不存在可生效的 token 候选值时），令牌漂移检查会跳过配置令牌解析。 +- 默认的 `gateway status` 可证明服务状态、WebSocket 连接，以及握手时可见的认证能力。它不能证明读/写/管理操作。 +- 对于首次设备认证，诊断探测是非变更性的：如果已有缓存的设备 token，它们会复用该 token，但不会仅为检查状态而创建新的 CLI 设备身份或只读设备配对记录。 +- 在可能的情况下，`gateway status` 会解析已配置的认证 SecretRef 以用于探测认证。 +- 如果在此命令路径中未解析某个必需的认证 SecretRef，且探测连接/认证失败，`gateway status --json` 会报告 `rpc.authWarning`；请显式传递 `--token`/`--password`，或先解析密钥来源。 +- 如果探测成功，则会抑制未解析 auth-ref 的警告，以避免误报。 +- 在脚本和自动化中，当仅有监听服务还不够、且你还需要读作用域 RPC 调用健康时，请使用 `--require-rpc`。 +- `--deep` 会尽力扫描额外的 launchd/systemd/schtasks 安装。当检测到多个类似 gateway 的服务时，人类可读输出会打印清理提示，并警告大多数设置应在每台机器上只运行一个 gateway。 +- 人类可读输出包含已解析的文件日志路径，以及 CLI 与服务的配置路径/有效性快照，以帮助诊断 profile 或状态目录漂移。 +- 在 Linux systemd 安装中，服务认证漂移检查会同时读取单元中的 `Environment=` 和 `EnvironmentFile=` 值（包括 `%h`、带引号的路径、多个文件以及可选的 `-` 文件）。 +- 漂移检查会使用合并后的运行时环境变量解析 `gateway.auth.token` SecretRef（优先使用服务命令环境变量，其次回退到进程环境变量）。 +- 如果 token 认证实际上未激活（显式 `gateway.auth.mode` 为 `password`/`none`/`trusted-proxy`，或模式未设置且密码可能获胜，同时没有任何 token 候选可能获胜），则 token 漂移检查会跳过配置 token 解析。 ### `gateway probe` -`gateway probe` 是“全量调试”命令。它始终会探测： +`gateway probe` 是“调试一切”的命令。它始终会探测： - 你已配置的远程 gateway（如果已设置），以及 -- localhost（local loopback）**即使已配置远程目标也是如此**。 +- localhost（loopback），**即使已配置远程目标**。 -如果你传入 `--url`，该显式目标会被添加到两者之前。人类可读输出会将这些 -目标标记为： +如果你传递 `--url`，该显式目标会添加在这两者之前。人类可读输出会将 +这些目标标记为： - `URL (explicit)` - `Remote (configured)` 或 `Remote (configured, inactive)` - `Local loopback` -如果有多个 Gateway 网关可达，它会全部打印出来。当你使用隔离的配置文件/端口（例如救援 bot）时，支持多个 Gateway 网关，但大多数安装通常仍只运行一个 Gateway 网关。 +如果可访问多个网关，它会打印全部结果。当你使用隔离的 profile/端口时，支持多个网关（例如 rescue bot），但大多数安装仍只运行单个 gateway。 ```bash openclaw gateway probe @@ -229,42 +230,43 @@ openclaw gateway probe --json 解释： - `Reachable: yes` 表示至少有一个目标接受了 WebSocket 连接。 -- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 报告探测所能证明的认证能力。它与可达性是分开的。 -- `Read probe: ok` 表示读取范围的详细 RPC 调用（`health`/`status`/`system-presence`/`config.get`）也成功了。 -- `Read probe: limited - missing scope: operator.read` 表示连接成功，但读取范围 RPC 受限。这会被报告为**降级**可达性，而不是完全失败。 -- 只有在所有被探测目标都不可达时，退出码才为非零。 +- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 表示探测能够证明的认证能力。它与可达性是分开的。 +- `Read probe: ok` 表示读作用域的详情 RPC 调用（`health`/`status`/`system-presence`/`config.get`）也成功了。 +- `Read probe: limited - missing scope: operator.read` 表示连接成功，但读作用域 RPC 受限。这会被报告为**降级的**可达性，而不是完全失败。 +- 与 `gateway status` 一样，probe 会复用现有缓存的设备认证，但不会创建首次设备身份或配对状态。 +- 仅当所有已探测目标都不可达时，退出码才为非零。 JSON 说明（`--json`）： - 顶层： - `ok`：至少有一个目标可达。 - - `degraded`：至少有一个目标的详细 RPC 受到作用域限制。 - - `capability`：在所有可达目标中观察到的最佳能力（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope` 或 `unknown`）。 - - `primaryTargetId`：按以下顺序视为当前活动优胜目标的最佳目标：显式 URL、SSH 隧道、已配置的远程目标，然后是 local loopback。 - - `warnings[]`：尽力而为的警告记录，包含 `code`、`message` 以及可选的 `targetIds`。 - - `network`：根据当前配置和主机网络推导出的 local loopback/tailnet URL 提示。 - - `discovery.timeoutMs` 和 `discovery.count`：本次探测实际使用的发现预算/结果数量。 + - `degraded`：至少有一个目标的详情 RPC 受到作用域限制。 + - `capability`：在可达目标中观察到的最佳能力（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope` 或 `unknown`）。 + - `primaryTargetId`：按以下顺序视为当前活动优胜目标的最佳目标：显式 URL、SSH 隧道、已配置的远程目标，然后是本地 local loopback。 + - `warnings[]`：尽力提供的警告记录，包含 `code`、`message` 和可选的 `targetIds`。 + - `network`：根据当前配置和主机网络推导出的本地 local loopback/tailnet URL 提示。 + - `discovery.timeoutMs` 和 `discovery.count`：本次探测实际使用的设备发现预算/结果数量。 - 每个目标（`targets[].connect`）： - - `ok`：连接建立后以及降级分类后的可达性。 - - `rpcOk`：完整详细 RPC 成功。 - - `scopeLimited`：由于缺少 operator 作用域，详细 RPC 失败。 + - `ok`：连接 + 降级分类后的可达性。 + - `rpcOk`：完整详情 RPC 成功。 + - `scopeLimited`：由于缺少 operator 作用域而导致详情 RPC 失败。 - 每个目标（`targets[].auth`）： - - `role`：可用时，在 `hello-ok` 中报告的认证角色。 - - `scopes`：可用时，在 `hello-ok` 中报告的已授予作用域。 - - `capability`：该目标呈现出的认证能力分类。 + - `role`：在可用时，由 `hello-ok` 报告的认证角色。 + - `scopes`：在可用时，由 `hello-ok` 报告的已授予作用域。 + - `capability`：该目标暴露出的认证能力分类。 常见警告代码： -- `ssh_tunnel_failed`：SSH 隧道建立失败；命令已回退为直接探测。 -- `multiple_gateways`：可达目标超过一个；除非你有意运行隔离的配置文件（例如救援 bot），否则这并不常见。 +- `ssh_tunnel_failed`：SSH 隧道建立失败；该命令回退为直接探测。 +- `multiple_gateways`：有多个目标可达；除非你有意运行隔离的 profile（例如 rescue bot），否则这通常不常见。 - `auth_secretref_unresolved`：某个已配置的认证 SecretRef 无法为失败目标解析。 -- `probe_scope_limited`：WebSocket 连接成功，但读取探测因缺少 `operator.read` 而受限。 +- `probe_scope_limited`：WebSocket 连接成功，但读探测因缺少 `operator.read` 而受限。 #### 通过 SSH 连接远程目标（与 Mac 应用一致） -macOS 应用的“Remote over SSH”模式使用本地端口转发，使远程 gateway（它可能只绑定到 loopback）能够通过 `ws://127.0.0.1:` 访问。 +macOS 应用的“Remote over SSH”模式使用本地端口转发，使远程 gateway（可能仅绑定到 loopback）可以通过 `ws://127.0.0.1:` 访问。 -对应的 CLI： +等效的 CLI： ```bash openclaw gateway probe --ssh user@gateway-host @@ -272,11 +274,9 @@ openclaw gateway probe --ssh user@gateway-host 选项： -- `--ssh `：`user@host` 或 `user@host:port`（端口默认 `22`）。 +- `--ssh `：`user@host` 或 `user@host:port`（端口默认为 `22`）。 - `--ssh-identity `：身份文件。 -- `--ssh-auto`：从解析后的 - 发现端点（`local.` 加上已配置的广域域名（如果有））中，选择第一个发现的 gateway 主机作为 SSH 目标。仅 TXT 的 - 提示会被忽略。 +- `--ssh-auto`：从已解析的设备发现端点中，选择第一个已发现的 gateway 主机作为 SSH 目标（`local.` 加上已配置的广域域名（如果有））。仅 TXT 的提示会被忽略。 配置（可选，用作默认值）： @@ -285,7 +285,7 @@ openclaw gateway probe --ssh user@gateway-host ### `gateway call ` -底层 RPC 辅助命令。 +底层 RPC 辅助工具。 ```bash openclaw gateway call status @@ -294,7 +294,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' 选项： -- `--params `：用于 params 的 JSON 对象字符串（默认 `{}`） +- `--params `：params 的 JSON 对象字符串（默认 `{}`） - `--url ` - `--token ` - `--password ` @@ -302,10 +302,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' - `--expect-final` - `--json` -注意事项： +说明： - `--params` 必须是有效的 JSON。 -- `--expect-final` 主要用于那些在最终有效负载之前会流式输出中间事件的智能体风格 RPC。 +- `--expect-final` 主要用于智能体风格的 RPC，这类 RPC 会在最终负载之前流式传输中间事件。 ## 管理 Gateway 网关服务 @@ -323,33 +323,33 @@ openclaw gateway uninstall - `gateway install`：`--port`、`--runtime `、`--token`、`--force`、`--json` - `gateway uninstall|start|stop|restart`：`--json` -注意事项： +说明： - `gateway install` 支持 `--port`、`--runtime`、`--token`、`--force`、`--json`。 -- 当令牌认证需要令牌且 `gateway.auth.token` 由 SecretRef 管理时，`gateway install` 会验证该 SecretRef 可被解析，但不会将解析后的令牌持久化到服务环境元数据中。 -- 如果令牌认证需要令牌且配置的令牌 SecretRef 无法解析，安装会以安全关闭方式失败，而不是持久化后备明文值。 +- 当 token 认证需要 token 且 `gateway.auth.token` 由 SecretRef 管理时，`gateway install` 会验证该 SecretRef 可被解析，但不会将解析出的 token 持久化到服务环境元数据中。 +- 如果 token 认证需要 token，而已配置的 token SecretRef 无法解析，则安装会以安全关闭方式失败，而不是持久化回退的明文。 - 对于 `gateway run` 的密码认证，优先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file` 或由 SecretRef 支持的 `gateway.auth.password`，而不是内联 `--password`。 -- 在推断认证模式下，仅 shell 中的 `OPENCLAW_GATEWAY_PASSWORD` 不会放宽安装时的令牌要求；安装受管服务时，请使用持久配置（`gateway.auth.password` 或配置 `env`）。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，则安装会被阻止，直到显式设置 mode。 -- 生命周期命令接受 `--json`，便于脚本使用。 +- 在推断认证模式下，仅 shell 中的 `OPENCLAW_GATEWAY_PASSWORD` 不会放宽安装 token 要求；安装受管服务时，请使用持久配置（`gateway.auth.password` 或配置中的 `env`）。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，则安装会被阻止，直到显式设置模式。 +- 生命周期命令接受 `--json` 以用于脚本编写。 -## 发现 Gateway 网关（Bonjour） +## 发现网关（Bonjour） `gateway discover` 会扫描 Gateway 网关信标（`_openclaw-gw._tcp`）。 -- 多播 DNS-SD：`local.` -- 单播 DNS-SD（广域 Bonjour）：选择一个域名（例如：`openclaw.internal.`），并设置 split DNS + DNS 服务器；参见 [/gateway/bonjour](/zh-CN/gateway/bonjour) +- 组播 DNS-SD：`local.` +- 单播 DNS-SD（广域 Bonjour）：选择一个域名（例如：`openclaw.internal.`）并设置 split DNS + DNS 服务器；参见 [/gateway/bonjour](/zh-CN/gateway/bonjour) -只有启用了 Bonjour 发现功能的 Gateway 网关（默认开启）才会广播信标。 +只有启用了 Bonjour 设备发现的网关（默认启用）才会广播该信标。 -广域发现记录包括（TXT）： +广域设备发现记录包含（TXT）： -- `role`（gateway 角色提示） +- `role`（网关角色提示） - `transport`（传输提示，例如 `gateway`） - `gatewayPort`（WebSocket 端口，通常为 `18789`） -- `sshPort`（可选；缺失时客户端默认 SSH 目标为 `22`） +- `sshPort`（可选；缺失时客户端默认 SSH 目标端口为 `22`） - `tailnetDns`（可用时的 MagicDNS 主机名） -- `gatewayTls` / `gatewayTlsSha256`（是否启用 TLS + 证书指纹） +- `gatewayTls` / `gatewayTlsSha256`（TLS 已启用 + 证书指纹） - `cliPath`（写入广域区域的远程安装提示） ### `gateway discover` @@ -361,7 +361,7 @@ openclaw gateway discover 选项： - `--timeout `：每个命令的超时时间（browse/resolve）；默认 `2000`。 -- `--json`：机器可读输出（同时禁用样式/spinner）。 +- `--json`：机器可读输出（也会禁用样式/旋转指示器）。 示例： @@ -370,16 +370,16 @@ openclaw gateway discover --timeout 4000 openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -注意事项： +说明： -- CLI 会扫描 `local.` 以及已配置的广域域名（如果已启用）。 -- JSON 输出中的 `wsUrl` 是根据解析后的服务端点推导出来的，而不是来自仅 TXT 的 +- CLI 会扫描 `local.`，以及启用时已配置的广域域名。 +- JSON 输出中的 `wsUrl` 来自已解析的服务端点，而不是仅 TXT 的 提示，例如 `lanHost` 或 `tailnetDns`。 - 在 `local.` mDNS 上，只有当 `discovery.mdns.mode` 为 `full` 时，才会广播 `sshPort` 和 `cliPath`。广域 DNS-SD 仍会写入 `cliPath`；`sshPort` - 在那里同样保持可选。 + 在那里也仍然是可选的。 -## 相关内容 +## 相关 - [CLI 参考](/zh-CN/cli) -- [Gateway 网关操作手册](/zh-CN/gateway) +- [Gateway 网关运行手册](/zh-CN/gateway) diff --git a/docs/zh-CN/cli/hooks.md b/docs/zh-CN/cli/hooks.md index 0a946eb54..786207ca5 100644 --- a/docs/zh-CN/cli/hooks.md +++ b/docs/zh-CN/cli/hooks.md @@ -1,28 +1,28 @@ --- read_when: - - 你想要管理智能体钩子 - - 你想要检查钩子的可用性，或启用工作区钩子 + - 你想管理智能体钩子 + - 你想检查钩子的可用性，或启用工作区钩子 summary: '`openclaw hooks` 的 CLI 参考（智能体钩子）' title: 钩子 x-i18n: - generated_at: "2026-04-24T17:31:12Z" + generated_at: "2026-04-25T22:08:04Z" model: gpt-5.4 provider: openai - source_hash: dd84cc984b24996c5509ce6b69f9bb76c61c4fa65b002809fdf5776abe67b48b + source_hash: 874c3c7e7b603066209857e8b8b39bbe23eb8d1eda148025c74907c05bacd8f2 source_path: cli/hooks.md workflow: 15 --- # `openclaw hooks` -管理智能体钩子（针对 `/new`、`/reset` 和 Gateway 网关启动等命令的事件驱动自动化）。 +管理智能体钩子（用于 `/new`、`/reset` 和 Gateway 网关启动等命令的事件驱动自动化）。 -在不带子命令的情况下运行 `openclaw hooks`，等同于 `openclaw hooks list`。 +在不带任何子命令的情况下运行 `openclaw hooks`，等同于 `openclaw hooks list`。 相关内容： -- 钩子：[Hooks](/zh-CN/automation/hooks) -- 插件钩子：[插件钩子](/zh-CN/plugins/hooks) +- 钩子：[钩子](/zh-CN/automation/hooks) +- 插件钩子：[Plugin hooks](/zh-CN/plugins/hooks) ## 列出所有钩子 @@ -30,12 +30,12 @@ x-i18n: openclaw hooks list ``` -列出从工作区、托管目录、额外目录和内置目录中发现的所有钩子。 +列出从工作区、托管、额外和内置目录中发现的所有钩子。 在至少配置了一个内部钩子之前，Gateway 网关启动时不会加载内部钩子处理程序。 **选项：** -- `--eligible`：仅显示符合条件的钩子（满足要求） +- `--eligible`：仅显示符合条件的钩子（已满足要求） - `--json`：以 JSON 格式输出 - `-v, --verbose`：显示详细信息，包括缺失的要求 @@ -57,7 +57,7 @@ Ready: openclaw hooks list --verbose ``` -显示不符合条件的钩子缺失了哪些要求。 +显示不符合条件的钩子所缺失的要求。 **示例（JSON）：** @@ -107,13 +107,13 @@ Requirements: Config: ✓ workspace.dir ``` -## 检查钩子适用性 +## 检查钩子是否符合条件 ```bash openclaw hooks check ``` -显示钩子适用状态的摘要（有多少已就绪，多少未就绪）。 +显示钩子符合条件状态的摘要（有多少已就绪，多少未就绪）。 **选项：** @@ -137,7 +137,7 @@ openclaw hooks enable 通过将特定钩子添加到你的配置中来启用它（默认是 `~/.openclaw/openclaw.json`）。 -**注意：** 工作区钩子默认禁用，必须在此处或配置中启用。由插件管理的钩子会在 `openclaw hooks list` 中显示为 `plugin:`，不能在这里启用或禁用。请改为启用或禁用对应插件。 +**注意：** 工作区钩子默认处于禁用状态，必须先在这里或在配置中启用。由插件管理的钩子会在 `openclaw hooks list` 中显示为 `plugin:`，不能在这里启用或禁用。请改为启用或禁用对应插件。 **参数：** @@ -155,17 +155,18 @@ openclaw hooks enable session-memory ✓ Enabled hook: 💾 session-memory ``` -**它的作用：** +**它会执行以下操作：** - 检查钩子是否存在且符合条件 - 在你的配置中更新 `hooks.internal.entries..enabled = true` - 将配置保存到磁盘 -如果钩子来自 `/hooks/`，则 Gateway 网关加载它之前必须完成此显式启用步骤。 +如果该钩子来自 `/hooks/`，则必须完成这一步显式启用， +Gateway 网关才会加载它。 **启用后：** -- 重启 Gateway 网关以重新加载钩子（在 macOS 上重启菜单栏应用，或在开发环境中重启你的 Gateway 网关进程）。 +- 重启 gateway，使钩子重新加载（在 macOS 上重启菜单栏应用，或在开发环境中重启你的 gateway 进程）。 ## 禁用钩子 @@ -193,39 +194,45 @@ openclaw hooks disable command-logger **禁用后：** -- 重启 Gateway 网关以重新加载钩子 +- 重启 gateway，使钩子重新加载 ## 说明 - `openclaw hooks list --json`、`info --json` 和 `check --json` 会将结构化 JSON 直接写入 stdout。 -- 由插件管理的钩子不能在这里启用或禁用；请改为启用或禁用所属插件。 +- 由插件管理的钩子不能在这里启用或禁用；请改为启用或禁用其所属插件。 ## 安装钩子包 ```bash -openclaw plugins install # 优先从 ClawHub，其次 npm +openclaw plugins install # 优先 ClawHub，然后是 npm openclaw plugins install --pin # 固定版本 openclaw plugins install # 本地路径 ``` 通过统一的插件安装器安装钩子包。 -`openclaw hooks install` 仍可用作兼容性别名，但它会打印弃用警告，并转发到 `openclaw plugins install`。 +`openclaw hooks install` 仍然可用，作为兼容性别名，但它会打印弃用警告， +并转发到 `openclaw plugins install`。 -Npm 规格仅支持 **registry-only**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file 规格和 semver 范围会被拒绝。出于安全考虑，依赖安装会使用 `--ignore-scripts` 运行。 +Npm 规格必须是**仅注册表**形式（包名 + 可选的**精确版本**或 +**dist-tag**）。Git/URL/file 规格和 semver 范围会被拒绝。出于安全考虑， +依赖安装会以项目本地方式运行，并使用 `--ignore-scripts`，即使你的 +shell 配置了全局 npm 安装设置也是如此。 -不带后缀的规格和 `@latest` 会保持在稳定版本轨道上。如果 npm 将其中任意一种解析为预发布版本，OpenClaw 会停止并要求你显式选择加入，例如使用 `@beta`/`@rc` 这样的预发布标签，或精确的预发布版本号。 +裸规格和 `@latest` 会保持在稳定通道上。如果 npm 将其中任一解析为预发布版本， +OpenClaw 会停止并要求你显式选择加入，例如使用 `@beta`/`@rc` 这样的 +预发布标签，或精确的预发布版本。 -**它的作用：** +**它会执行以下操作：** - 将钩子包复制到 `~/.openclaw/hooks/` - 在 `hooks.internal.entries.*` 中启用已安装的钩子 -- 在 `hooks.internal.installs` 中记录安装信息 +- 在 `hooks.internal.installs` 下记录安装信息 **选项：** - `-l, --link`：链接本地目录而不是复制（将其添加到 `hooks.internal.load.extraDirs`） -- `--pin`：将 npm 安装以精确解析后的 `name@version` 记录到 `hooks.internal.installs` +- `--pin`：将 npm 安装记录为 `hooks.internal.installs` 中精确解析后的 `name@version` **支持的归档格式：** `.zip`、`.tgz`、`.tar.gz`、`.tar` @@ -245,7 +252,7 @@ openclaw plugins install @openclaw/my-hook-pack openclaw plugins install -l ./my-hook-pack ``` -链接的钩子包会被视为来自运维人员配置目录的托管钩子，而不是工作区钩子。 +已链接的钩子包会被视为来自操作员配置目录的托管钩子，而不是工作区钩子。 ## 更新钩子包 @@ -254,22 +261,25 @@ openclaw plugins update openclaw plugins update --all ``` -通过统一的插件更新器更新已跟踪的基于 npm 的钩子包。 +通过统一的插件更新器更新被跟踪的基于 npm 的钩子包。 -`openclaw hooks update` 仍可用作兼容性别名，但它会打印弃用警告，并转发到 `openclaw plugins update`。 +`openclaw hooks update` 仍然可用，作为兼容性别名，但它会打印弃用警告， +并转发到 `openclaw plugins update`。 **选项：** -- `--all`：更新所有已跟踪的钩子包 -- `--dry-run`：显示将会发生的变更，但不写入 +- `--all`：更新所有被跟踪的钩子包 +- `--dry-run`：显示将会发生的更改，但不实际写入 -当存在已存储的完整性哈希且获取到的制品哈希发生变化时，OpenClaw 会打印警告并在继续前请求确认。在 CI 或非交互运行中，可使用全局 `--yes` 跳过提示。 +当存在已存储的完整性哈希且获取到的制品哈希发生变化时， +OpenClaw 会打印警告，并在继续前请求确认。在 CI/非交互式运行中， +可使用全局 `--yes` 跳过提示。 ## 内置钩子 ### session-memory -当你发出 `/new` 或 `/reset` 时，将会话上下文保存到 memory。 +当你发出 `/new` 或 `/reset` 时，将会话上下文保存到 memory 中。 **启用：** @@ -322,7 +332,7 @@ grep '"action":"new"' ~/.openclaw/logs/commands.log | jq . ### boot-md -在 Gateway 网关启动时（渠道启动后）运行 `BOOT.md`。 +在 gateway 启动时运行 `BOOT.md`（在渠道启动之后）。 **事件**：`gateway:startup` diff --git a/docs/zh-CN/gateway/security/index.md b/docs/zh-CN/gateway/security/index.md index fa4c752b4..fde717b69 100644 --- a/docs/zh-CN/gateway/security/index.md +++ b/docs/zh-CN/gateway/security/index.md @@ -1,37 +1,37 @@ --- read_when: - 添加会扩大访问范围或自动化能力的功能 -summary: 运行具有 shell 访问权限的 AI Gateway 网关时的安全注意事项和威胁模型 -title: Security +summary: 运行具有 shell 访问权限的 AI Gateway 网关的安全注意事项和威胁模型 +title: 安全性 x-i18n: - generated_at: "2026-04-25T05:54:28Z" + generated_at: "2026-04-25T22:08:03Z" model: gpt-5.4 provider: openai - source_hash: a63386bac5db060ff1edc2260aae4a192ac666fc82956c8538915a970205215c + source_hash: cee231e4cfef7919296e45657a50291021c53488e537cb691306ec5dca95e44b source_path: gateway/security/index.md workflow: 15 --- - **个人智能体信任模型。** 本指南假定每个 Gateway 网关只有一个受信任的操作员边界（单用户、个人智能体模型）。OpenClaw **不是** 适用于多个对抗性用户共享同一个智能体或 Gateway 网关的敌对多租户安全边界。如果你需要混合信任或对抗性用户场景，请拆分信任边界（独立的 Gateway 网关 + 凭证，最好再配合独立的 OS 用户或主机）。 + **个人助手信任模型。** 本指南假设每个 Gateway 网关对应一个受信任的操作员边界（单用户、个人助手模型）。OpenClaw **并不是** 适用于多个敌对用户共享同一个智能体或 Gateway 网关的恶意多租户安全边界。如果你需要混合信任或敌对用户场景，请拆分信任边界（独立的 Gateway 网关 + 凭证，最好再配合独立的操作系统用户或主机）。 -## 先明确范围：个人智能体安全模型 +## 先明确范围：个人助手安全模型 -OpenClaw 的安全指南假定你采用的是**个人智能体**部署：一个受信任的操作员边界，可能包含多个智能体。 +OpenClaw 的安全指南基于**个人助手**部署：一个受信任的操作员边界，可能包含多个智能体。 -- 支持的安全姿态：每个 Gateway 网关对应一个用户/信任边界（最好每个边界对应一个 OS 用户/主机/VPS）。 -- 不受支持的安全边界：多个彼此不受信任或具有对抗关系的用户共享同一个 Gateway 网关/智能体。 -- 如果需要对抗性用户隔离，请按信任边界拆分（独立的 Gateway 网关 + 凭证，最好再配合独立的 OS 用户/主机）。 -- 如果多个不受信任的用户都可以向同一个启用了工具的智能体发送消息，请将其视为共享了该智能体同一组被委派的工具权限。 +- 支持的安全姿态：每个 Gateway 网关对应一个用户/信任边界（最好每个边界使用一个操作系统用户/主机/VPS）。 +- 不受支持的安全边界：多个彼此不信任或具有对抗关系的用户共享同一个 Gateway 网关/智能体。 +- 如果需要敌对用户隔离，请按信任边界拆分（独立的 Gateway 网关 + 凭证，最好再配合独立的操作系统用户/主机）。 +- 如果多个不受信任的用户都可以给同一个启用了工具的智能体发消息，请将其视为共享该智能体相同的委派工具权限。 -本页说明的是**在该模型之内**如何加固。它并不声称在单个共享 Gateway 网关上提供敌对多租户隔离。 +本页解释的是**在该模型内**如何加固。它不声称在单个共享 Gateway 网关上提供对抗性的多租户隔离。 ## 快速检查：`openclaw security audit` -另请参见： [Formal Verification (Security Models)](/zh-CN/security/formal-verification) +另见：[Formal Verification（安全模型）](/zh-CN/security/formal-verification) -请定期运行此命令（尤其是在更改配置或暴露网络接口之后）： +请定期运行此命令（尤其是在更改配置或暴露网络入口之后）： ```bash openclaw security audit @@ -40,98 +40,98 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` 的范围被有意保持得很窄：它会将常见的开放群组策略切换为允许列表，恢复 `logging.redactSensitive: "tools"`，收紧状态/配置/include 文件权限，并且在 Windows 上运行时使用 Windows ACL 重置，而不是 POSIX `chmod`。 +`security audit --fix` 故意保持在较小范围内：它会把常见的开放群组策略切换为 allowlist，恢复 `logging.redactSensitive: "tools"`，收紧状态/配置/包含文件的权限，并且在 Windows 上运行时使用 Windows ACL 重置，而不是 POSIX `chmod`。 -它会标记常见的易错配置（Gateway 网关认证暴露、浏览器控制暴露、提升权限的允许列表、文件系统权限、宽松的 exec 批准策略，以及开放渠道工具暴露）。 +它会标记常见的易错配置（Gateway 网关身份验证暴露、浏览器控制暴露、高权限 allowlist、文件系统权限、宽松的 exec 审批，以及开放渠道的工具暴露）。 -OpenClaw 既是一个产品，也是一个实验：你正在把前沿模型的行为接入真实的消息渠道和真实工具。**不存在“绝对安全”的配置。** 目标是有意识地明确： +OpenClaw 既是一个产品，也是一项实验：你正在把前沿模型行为连接到真实的消息渠道和真实工具上。**不存在“绝对安全”的配置。** 目标是有意识地明确以下几点： -- 谁可以和你的机器人对话 +- 谁可以与你的机器人对话 - 机器人被允许在哪些地方执行操作 -- 机器人可以接触哪些内容 +- 机器人可以接触什么 -从仍能满足需求的最小访问范围开始，然后随着信心增加再逐步放宽。 +从仍能正常工作的最小访问范围开始，随着信心增加再逐步放宽。 ### 部署与主机信任 -OpenClaw 假定主机和配置边界是受信任的： +OpenClaw 假设主机和配置边界是受信任的： -- 如果某人可以修改 Gateway 网关主机状态/配置（`~/.openclaw`，包括 `openclaw.json`），请将其视为受信任操作员。 -- 为多个彼此不受信任/具有对抗关系的操作员运行一个 Gateway 网关，**不是推荐配置**。 -- 对于混合信任团队，请使用独立 Gateway 网关（或至少独立 OS 用户/主机）拆分信任边界。 -- 推荐的默认方式：每台机器/主机（或 VPS）一个用户，该用户一个 Gateway 网关，该 Gateway 网关内有一个或多个智能体。 -- 在单个 Gateway 网关实例内，经过认证的 operator 访问属于受信任的控制平面角色，而不是按用户划分的租户角色。 +- 如果某人可以修改 Gateway 网关主机状态/配置（`~/.openclaw`，包括 `openclaw.json`），应将其视为受信任的操作员。 +- 使用一个 Gateway 网关服务多个彼此不信任/具有对抗关系的操作员，**不是推荐配置**。 +- 对于混合信任团队，请使用独立的 Gateway 网关 来拆分信任边界（或者至少使用独立的操作系统用户/主机）。 +- 推荐默认做法：每台机器/主机（或 VPS）一个用户，该用户一个 Gateway 网关，该 Gateway 网关中有一个或多个智能体。 +- 在单个 Gateway 网关实例内部，经过身份验证的操作员访问属于受信任的控制平面角色，而不是按用户划分的租户角色。 - 会话标识符（`sessionKey`、会话 ID、标签）是路由选择器，不是授权令牌。 -- 如果多个人都可以向同一个启用了工具的智能体发送消息，那么他们每个人都可以驱动同一套权限。按用户隔离会话/记忆有助于隐私，但不会把共享智能体转换成按用户划分的主机授权。 +- 如果多个人都可以给同一个启用了工具的智能体发消息，那么他们每个人都可以驱动同一组权限。按用户进行会话/记忆隔离有助于隐私，但不会把一个共享智能体变成按用户划分的主机授权边界。 ### 共享 Slack 工作区：真实风险 如果“Slack 里的所有人都可以给机器人发消息”，核心风险是委派工具权限： -- 任何被允许的发送者都可以在智能体策略范围内诱发工具调用（`exec`、浏览器、网络/文件工具）； -- 某个发送者的提示词/内容注入可能导致影响共享状态、设备或输出的操作； -- 如果一个共享智能体拥有敏感凭证/文件，任何被允许的发送者都可能通过工具使用驱动数据外泄。 +- 任何被允许的发送者都可以在该智能体的策略范围内诱导工具调用（`exec`、浏览器、网络/文件工具）； +- 来自某个发送者的提示/内容注入可能导致影响共享状态、设备或输出的操作； +- 如果一个共享智能体拥有敏感凭证/文件，任何被允许的发送者都可能通过工具使用来驱动数据外泄。 -对于团队工作流，请使用工具最少化的独立智能体/Gateway 网关；涉及个人数据的智能体请保持私有。 +对于团队工作流，请使用具有最小工具集的独立智能体/Gateway 网关；涉及个人数据的智能体应保持私有。 ### 公司共享智能体：可接受模式 -当使用该智能体的所有人都属于同一个信任边界（例如同一个公司团队），并且该智能体严格限定在业务范围内时，这是可接受的。 +当使用该智能体的所有人都处于同一个信任边界内（例如同一个公司团队），并且该智能体严格限定在业务范围内时，这是可接受的。 - 在专用机器/VM/容器上运行它； -- 为该运行时使用专用 OS 用户 + 专用浏览器/配置文件/账户； -- 不要让该运行时登录个人 Apple/Google 账户，也不要使用个人密码管理器/浏览器配置文件。 +- 为该运行时使用专用操作系统用户 + 专用浏览器/配置文件/账号； +- 不要让该运行时登录个人 Apple/Google 账号，或个人密码管理器/浏览器配置文件。 -如果你在同一个运行时里混用个人身份和公司身份，就会打破这种隔离，并增加个人数据暴露风险。 +如果你在同一运行时中混用个人身份和公司身份，就会打破这种隔离，并增加个人数据暴露风险。 -## Gateway 网关和节点信任概念 +## Gateway 网关与节点的信任概念 -请将 Gateway 网关和节点视为同一个操作员信任域，只是角色不同： +应将 Gateway 网关和节点视为同一个操作员信任域中的不同角色： -- **Gateway 网关**是控制平面和策略界面（`gateway.auth`、工具策略、路由）。 -- **节点**是与该 Gateway 网关配对的远程执行界面（命令、设备操作、主机本地能力）。 -- 认证到 Gateway 网关的调用方，在 Gateway 网关作用域内是受信任的。配对后，节点操作就是该节点上的受信任操作员操作。 -- `sessionKey` 是路由/上下文选择，不是按用户划分的认证。 -- Exec 批准策略（允许列表 + 询问）是保护操作员意图的护栏，不是敌对多租户隔离。 -- 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 网关。 +如果你需要敌对用户隔离，请按操作系统用户/主机拆分信任边界，并运行独立的 Gateway 网关。 ## 信任边界矩阵 -在进行风险判断时，请把它作为快速模型使用： +在评估风险时，可将下表作为快速模型： -| 边界或控制 | 含义 | 常见误解 | -| --------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | -| `gateway.auth`（token/password/trusted-proxy/device auth） | 将调用方认证到 gateway API | “要安全，就必须对每一帧消息都做按消息签名” | -| `sessionKey` | 用于上下文/会话选择的路由键 | “会话键是用户认证边界” | -| 提示词/内容护栏 | 降低模型滥用风险 | “仅凭提示注入就足以证明认证绕过” | -| `canvas.eval` / 浏览器 evaluate | 启用时的有意操作员能力 | “任何 JS eval 原语在这个信任模型里都自动算漏洞” | -| 本地 TUI `!` shell | 显式由操作员触发的本地执行 | “本地 shell 便捷命令就是远程注入” | -| 节点配对和节点命令 | 已配对设备上的操作员级远程执行 | “远程设备控制默认应被视为不受信任用户访问” | -| `gateway.nodes.pairing.autoApproveCidrs` | 可选启用的受信任网络节点注册策略 | “默认关闭的允许列表也会自动造成配对漏洞” | +| 边界或控制项 | 它的含义 | 常见误解 | +| --------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | +| `gateway.auth`（token/password/trusted-proxy/device auth） | 对 Gateway 网关 API 的调用方进行身份验证 | “要安全，就必须对每一帧消息都做按消息签名” | +| `sessionKey` | 用于上下文/会话选择的路由键 | “会话 key 是用户身份验证边界” | +| 提示/内容护栏 | 降低模型滥用风险 | “仅凭提示注入就能证明身份验证绕过” | +| `canvas.eval` / 浏览器 evaluate | 启用后属于有意提供给操作员的能力 | “在这种信任模型里，任何 JS eval 原语都自动算漏洞” | +| 本地 TUI `!` shell | 由操作员显式触发的本地执行 | “本地 shell 便捷命令属于远程注入” | +| 节点配对和节点命令 | 对已配对设备进行操作员级别的远程执行 | “远程设备控制默认应被视为不受信任用户访问” | +| `gateway.nodes.pairing.autoApproveCidrs` | 可选启用的受信任网络节点注册策略 | “默认关闭的 allowlist 也是自动配对漏洞” | -## 按设计不算漏洞的情况 +## 按设计不属于漏洞的情况 -这些模式经常被报告，但除非能证明存在真实边界绕过，否则通常会被关闭为无需处理： +以下模式经常被报告，但除非证明存在真实的边界绕过，否则通常会按无需处理关闭： -- 仅有提示注入链，而没有策略、认证或沙箱绕过。 -- 假设在一台共享主机或共享配置上运行敌对多租户。 -- 将共享 Gateway 网关配置中的正常 operator 读取路径（例如 `sessions.list` / `sessions.preview` / `chat.history`）归类为 IDOR。 -- 仅限 localhost 部署的发现（例如只绑定 loopback 的 Gateway 网关上缺少 HSTS）。 -- 针对本仓库中并不存在的入站路径，报告 Discord 入站 webhook 签名问题。 -- 将节点配对元数据视为 `system.run` 的隐藏“每条命令二次批准层”，而真实执行边界其实仍是 gateway 的全局节点命令策略加上节点自身的 exec 批准。 -- 将已配置的 `gateway.nodes.pairing.autoApproveCidrs` 本身视为漏洞。该设置默认禁用，需要显式填写 CIDR/IP，仅适用于首次且未请求任何作用域的 `role: node` 配对，不会自动批准 operator/浏览器/Control UI、WebChat、角色升级、作用域升级、元数据更改、公钥更改，或同主机 loopback 的 trusted-proxy header 路径。 -- 将 `sessionKey` 当成认证令牌来报告“缺少按用户授权”的发现。 +- 仅有提示注入链条，但没有策略、身份验证或沙箱隔离绕过。 +- 基于“单个共享主机或配置上存在敌对多租户运行”的假设提出的指控。 +- 将正常的操作员读取路径访问（例如 `sessions.list` / `sessions.preview` / `chat.history`）在共享 Gateway 网关 配置中归类为 IDOR 的指控。 +- 仅限 localhost 部署的发现（例如仅 loopback Gateway 网关上的 HSTS）。 +- 针对本仓库中不存在的入站路径提出的 Discord 入站 webhook 签名问题。 +- 将节点配对元数据视为 `system.run` 的隐藏第二层“逐命令审批”的报告，而真实执行边界仍然是 Gateway 网关的全局节点命令策略加上节点自身的 exec 审批。 +- 将已配置的 `gateway.nodes.pairing.autoApproveCidrs` 本身视为漏洞的报告。该设置默认关闭，需要显式填写 CIDR/IP 条目，仅适用于首次 `role: node` 配对且未请求任何作用域的情况，并且不会自动批准 operator/browser/Control UI、WebChat、角色升级、作用域升级、元数据变更、公钥变更，或同主机 loopback trusted-proxy header 路径。 +- 把 `sessionKey` 当作身份验证令牌，并据此报告“缺少按用户授权”的问题。 -## 六十秒内的加固基线 +## 60 秒内完成的加固基线 -请先使用这个基线，然后再按受信任智能体选择性重新启用工具： +先使用这个基线配置，然后再为受信任的智能体有选择地重新启用工具： ```json5 { @@ -156,117 +156,120 @@ OpenClaw 假定主机和配置边界是受信任的： } ``` -这会将 Gateway 网关限制为仅本地访问、隔离私信，并默认禁用控制平面/运行时工具。 +这会让 Gateway 网关仅限本地访问、隔离私信，并默认禁用控制平面/运行时工具。 ## 共享收件箱快速规则 -如果有不止一个人可以给你的机器人发送私信： +如果不止一个人可以给你的机器人发私信： -- 设置 `session.dmScope: "per-channel-peer"`（对于多账户渠道则使用 `"per-account-channel-peer"`）。 -- 保持 `dmPolicy: "pairing"` 或使用严格允许列表。 -- 绝不要将共享私信和广泛的工具访问组合使用。 -- 这可以加强协作型/共享收件箱，但在用户共享主机/配置写权限时，并不是为敌对共同租户隔离而设计的。 +- 将 `session.dmScope` 设为 `"per-channel-peer"`（多账号渠道则使用 `"per-account-channel-peer"`）。 +- 保持 `dmPolicy: "pairing"` 或使用严格的 allowlist。 +- 绝不要把共享私信和广泛工具访问组合在一起。 +- 这能加固协作式/共享式收件箱，但在用户共享主机/配置写权限时，并不是为敌对共租户隔离而设计的。 ## 上下文可见性模型 OpenClaw 区分两个概念： -- **触发授权**：谁可以触发智能体（`dmPolicy`、`groupPolicy`、允许列表、提及门槛）。 +- **触发授权**：谁可以触发智能体（`dmPolicy`、`groupPolicy`、allowlist、提及门槛）。 - **上下文可见性**：哪些补充上下文会被注入到模型输入中（回复正文、引用文本、线程历史、转发元数据）。 -允许列表控制触发和命令授权。`contextVisibility` 设置控制补充上下文（引用回复、线程根消息、已获取历史）如何被过滤： +Allowlist 用于限制触发和命令授权。`contextVisibility` 设置控制如何过滤补充上下文（引用回复、线程根消息、拉取的历史记录）： -- `contextVisibility: "all"`（默认）会保留接收到的全部补充上下文。 -- `contextVisibility: "allowlist"` 会将补充上下文过滤为仅包含通过当前允许列表检查的发送者内容。 -- `contextVisibility: "allowlist_quote"` 的行为与 `allowlist` 相同，但仍会保留一条显式引用回复。 +- `contextVisibility: "all"`（默认）保留接收到的全部补充上下文。 +- `contextVisibility: "allowlist"` 按当前生效的 allowlist 检查，仅保留被允许发送者的补充上下文。 +- `contextVisibility: "allowlist_quote"` 的行为与 `allowlist` 相同，但仍保留一条显式引用回复。 -可按渠道或按房间/会话设置 `contextVisibility`。配置细节请参见 [Group Chats](/zh-CN/channels/groups#context-visibility-and-allowlists)。 +可以按渠道或按房间/对话设置 `contextVisibility`。配置细节参见 [群聊](/zh-CN/channels/groups#context-visibility-and-allowlists)。 -安全通告分诊指导： +安全通告分级建议： -- 仅证明“模型可以看到来自未列入允许列表发送者的引用或历史文本”的报告，属于可通过 `contextVisibility` 处理的加固发现，本身不构成认证或沙箱边界绕过。 -- 若要构成真正的安全影响，报告仍需证明存在信任边界绕过（认证、策略、沙箱、批准或其他已记录边界）。 +- 仅能证明“模型可以看到来自未列入 allowlist 的发送者的引用文本或历史文本”的问题，应视为可通过 `contextVisibility` 进行加固的发现，而不是身份验证或沙箱隔离边界绕过。 +- 若要被认定为具有安全影响，报告仍需证明存在信任边界绕过（身份验证、策略、沙箱隔离、审批，或其他已记录的边界）。 -## 审计检查的内容（高层概述） +## 审计检查的内容（高层概览） -- **入站访问**（私信策略、群组策略、允许列表）：陌生人能否触发机器人？ -- **工具爆炸半径**（提升权限工具 + 开放房间）：提示注入是否可能演变成 shell/文件/网络操作？ -- **Exec 批准漂移**（`security=full`、`autoAllowSkills`、未启用 `strictInlineEval` 的解释器允许列表）：主机 exec 护栏是否仍按你的预期工作？ - - `security="full"` 是广泛姿态警告，不是漏洞证明。它是受信任个人智能体配置中的默认选择；只有当你的威胁模型需要批准或允许列表护栏时，才应收紧它。 -- **网络暴露**（Gateway 网关 bind/auth、Tailscale Serve/Funnel、弱或过短的认证令牌）。 -- **浏览器控制暴露**（远程节点、中继端口、远程 CDP 端点）。 +- **入站访问**（私信策略、群组策略、allowlist）：陌生人能否触发机器人？ +- **工具影响半径**（高权限工具 + 开放房间）：提示注入是否可能演变为 shell/文件/网络操作？ +- **Exec 审批漂移**（`security=full`、`autoAllowSkills`、未启用 `strictInlineEval` 的解释器 allowlist）：主机 exec 护栏是否仍按你的预期工作？ + - `security="full"` 是广泛姿态警告，不代表一定存在 bug。它是受信任个人助手场景下的默认选择；只有当你的威胁模型需要审批或 allowlist 护栏时，才应收紧它。 +- **网络暴露**（Gateway 网关 bind/auth、Tailscale Serve/Funnel、弱或过短的身份验证 token）。 +- **浏览器控制暴露**（远程节点、relay 端口、远程 CDP 端点）。 - **本地磁盘卫生**（权限、符号链接、配置 include、“同步文件夹”路径）。 -- **插件**（插件在没有显式允许列表的情况下加载）。 -- **策略漂移/错误配置**（已配置 sandbox docker 设置但沙箱模式关闭；无效的 `gateway.nodes.denyCommands` 模式，因为匹配仅基于精确命令名，例如 `system.run`，不会检查 shell 文本；危险的 `gateway.nodes.allowCommands` 条目；全局 `tools.profile="minimal"` 被按智能体配置覆盖；插件拥有的工具在宽松工具策略下可访问）。 -- **运行时期望漂移**（例如，原以为隐式 exec 仍表示 `sandbox`，但现在 `tools.exec.host` 默认是 `auto`；或者显式设置 `tools.exec.host="sandbox"`，而沙箱模式其实已关闭）。 -- **模型卫生**（当配置的模型看起来像旧版模型时发出警告；不是硬性阻止）。 +- **插件**（插件在没有显式 allowlist 的情况下加载）。 +- **策略漂移/配置错误**（已配置沙箱 Docker 设置但沙箱模式关闭；无效的 `gateway.nodes.denyCommands` 模式，因为匹配仅针对精确命令名生效，例如 `system.run`，不会检查 shell 文本；危险的 `gateway.nodes.allowCommands` 条目；全局 `tools.profile="minimal"` 被按智能体配置覆盖；在宽松工具策略下可访问的插件自有工具）。 +- **运行时预期漂移**（例如误以为隐式 exec 仍然表示 `sandbox`，但 `tools.exec.host` 现在默认是 `auto`；或者在沙箱模式关闭时显式设置 `tools.exec.host="sandbox"`）。 +- **模型卫生**（当已配置模型看起来较旧时发出警告；不是硬性阻止）。 -如果你运行 `--deep`，OpenClaw 还会尽力尝试实时 Gateway 网关探测。 +如果你运行 `--deep`，OpenClaw 还会尽力尝试对在线 Gateway 网关进行探测。 ## 凭证存储映射 -在审计访问权限或决定备份哪些内容时可参考此节： +在审计访问权限或决定需要备份什么时，可参考以下内容： - **WhatsApp**：`~/.openclaw/credentials/whatsapp//creds.json` -- **Telegram 机器人令牌**：config/env 或 `channels.telegram.tokenFile`（仅允许普通文件；拒绝符号链接） -- **Discord 机器人令牌**：config/env 或 SecretRef（env/file/exec 提供商） -- **Slack 令牌**：config/env（`channels.slack.*`） -- **配对允许列表**： - - `~/.openclaw/credentials/-allowFrom.json`（默认账户） - - `~/.openclaw/credentials/--allowFrom.json`（非默认账户） -- **模型认证配置文件**：`~/.openclaw/agents//agent/auth-profiles.json` -- **基于文件的密钥负载（可选）**：`~/.openclaw/secrets.json` +- **Telegram bot token**：config/env 或 `channels.telegram.tokenFile`（仅接受常规文件；拒绝符号链接） +- **Discord bot token**：config/env 或 SecretRef（env/file/exec provider） +- **Slack token**：config/env（`channels.slack.*`） +- **配对 allowlist**： + - `~/.openclaw/credentials/-allowFrom.json`（默认账号） + - `~/.openclaw/credentials/--allowFrom.json`（非默认账号） +- **模型身份验证配置文件**：`~/.openclaw/agents//agent/auth-profiles.json` +- **基于文件的 secrets 负载（可选）**：`~/.openclaw/secrets.json` - **旧版 OAuth 导入**：`~/.openclaw/credentials/oauth.json` ## 安全审计检查清单 -当审计打印出发现项时，请按以下优先级处理： +当审计输出发现项时，请按以下优先级处理： -1. **任何“开放”+ 启用工具**：先锁定私信/群组（配对/允许列表），再收紧工具策略/沙箱隔离。 -2. **公共网络暴露**（LAN 绑定、Funnel、缺少认证）：立即修复。 -3. **浏览器控制远程暴露**：将其视为 operator 访问（仅 tailnet、谨慎配对节点、避免公开暴露）。 -4. **权限**：确保状态/配置/凭证/认证信息不是组可读或全局可读。 +1. **任何“开放”状态 + 已启用工具**：先锁定私信/群组（配对/allowlist），然后收紧工具策略/沙箱隔离。 +2. **公共网络暴露**（LAN bind、Funnel、缺少 auth）：立即修复。 +3. **浏览器控制远程暴露**：将其视为操作员访问权限（仅限 tailnet，谨慎配对节点，避免公开暴露）。 +4. **权限**：确保状态/配置/凭证/身份验证内容对 group/world 不可读。 5. **插件**：只加载你明确信任的内容。 -6. **模型选择**：对于任何启用了工具的机器人，优先使用现代、具备指令加固能力的模型。 +6. **模型选择**：对任何带工具的机器人，都优先使用现代、具备更强指令防护能力的模型。 ## 安全审计术语表 -每条审计发现都会带有结构化的 `checkId`（例如 -`gateway.bind_no_auth` 或 `tools.exec.security_full_configured`）。常见的严重级别类别包括： +每个审计发现都会使用结构化的 `checkId` 作为键（例如 +`gateway.bind_no_auth` 或 `tools.exec.security_full_configured`）。常见的关键严重级别类别包括： -- `fs.*` — 状态、配置、凭证、认证配置文件的文件系统权限。 -- `gateway.*` — bind 模式、认证、Tailscale、Control UI、trusted-proxy 设置。 -- `hooks.*`、`browser.*`、`sandbox.*`、`tools.exec.*` — 各界面的加固检查。 -- `plugins.*`、`skills.*` — 插件/Skills 供应链和扫描发现。 -- `security.exposure.*` — 访问策略与工具爆炸半径相交的跨领域检查。 +- `fs.*` — 状态、配置、凭证、身份验证配置文件的文件系统权限。 +- `gateway.*` — bind 模式、auth、Tailscale、Control UI、trusted-proxy 配置。 +- `hooks.*`、`browser.*`、`sandbox.*`、`tools.exec.*` — 各入口面的加固项。 +- `plugins.*`、`skills.*` — 插件/技能供应链和扫描发现。 +- `security.exposure.*` — 访问策略与工具影响半径交汇处的跨领域检查。 -完整目录（包括严重级别、修复键名和自动修复支持）请参见 +完整目录（包括严重级别、修复键和自动修复支持）见 [Security audit checks](/zh-CN/gateway/security/audit-checks)。 ## 通过 HTTP 使用 Control UI -Control UI 需要一个**安全上下文**（HTTPS 或 localhost）来生成设备身份。 +Control UI 需要**安全上下文**（HTTPS 或 localhost）来生成设备身份。 `gateway.controlUi.allowInsecureAuth` 是一个本地兼容性开关： -- 在 localhost 上，当页面通过非安全 HTTP 加载时，它允许 Control UI 在没有设备身份的情况下进行认证。 +- 在 localhost 上，当页面通过非安全 HTTP 加载时，它允许 Control UI 在没有设备身份的情况下进行身份验证。 - 它不会绕过配对检查。 - 它不会放宽远程（非 localhost）设备身份要求。 优先使用 HTTPS（Tailscale Serve），或在 `127.0.0.1` 上打开 UI。 -仅用于紧急破窗场景，`gateway.controlUi.dangerouslyDisableDeviceAuth` -会完全禁用设备身份检查。这是严重的安全降级；除非你正在主动调试且能够快速恢复，否则请保持关闭。 +仅用于紧急破窗场景时，`gateway.controlUi.dangerouslyDisableDeviceAuth` +会完全禁用设备身份检查。这会严重降低安全性； +除非你正在积极调试且能够快速恢复，否则请保持关闭。 与这些危险标志分开的是，成功的 `gateway.auth.mode: "trusted-proxy"` -可以在没有设备身份的情况下接纳 **operator** Control UI 会话。这是 -有意设计的认证模式行为，而不是 `allowInsecureAuth` 的捷径，并且它仍然 -不会扩展到 node 角色的 Control UI 会话。 +可以在没有设备身份的情况下接纳**操作员** Control UI 会话。这是 +有意设计的 auth 模式行为，并不是 `allowInsecureAuth` 的捷径，而且它 +仍然不适用于 node 角色的 Control UI 会话。 -启用该设置时，`openclaw security audit` 会发出警告。 +当此设置启用时，`openclaw security audit` 会发出警告。 ## 不安全或危险标志摘要 -当已知的不安全/危险调试开关被启用时，`openclaw security audit` 会报告 `config.insecure_or_dangerous_flags`。在生产环境中请保持这些设置未启用。 +当已知不安全/危险的调试开关被启用时， +`openclaw security audit` 会触发 `config.insecure_or_dangerous_flags`。 +在生产环境中请保持这些设置未启用。 @@ -286,8 +289,8 @@ Control UI 需要一个**安全上下文**（HTTPS 或 localhost）来生成设 - `gateway.controlUi.dangerouslyDisableDeviceAuth` - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - 渠道名称匹配（内置和插件渠道；在适用情况下，也可按 - `accounts.` 单独配置）： + 渠道名称匹配（内置渠道和插件渠道；适用时也可在 + `accounts.` 下单独设置）： - `channels.discord.dangerouslyAllowNameMatching` - `channels.slack.dangerouslyAllowNameMatching` @@ -301,9 +304,9 @@ Control UI 需要一个**安全上下文**（HTTPS 或 localhost）来生成设 网络暴露： - - `channels.telegram.network.dangerouslyAllowPrivateNetwork`（也支持按账户配置） + - `channels.telegram.network.dangerouslyAllowPrivateNetwork`（也可按账号设置） - 沙箱 Docker（默认值 + 按智能体配置）： + 沙箱 Docker（默认值 + 按智能体设置）： - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` - `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources` @@ -314,35 +317,35 @@ Control UI 需要一个**安全上下文**（HTTPS 或 localhost）来生成设 ## 反向代理配置 -如果你在反向代理（nginx、Caddy、Traefik 等）之后运行 Gateway 网关，请配置 -`gateway.trustedProxies`，以正确处理转发客户端 IP。 +如果你在反向代理（nginx、Caddy、Traefik 等）后面运行 Gateway 网关，请配置 +`gateway.trustedProxies`，以正确处理转发的客户端 IP。 -当 Gateway 网关检测到来自**不在** `trustedProxies` 中地址的代理头时，它**不会**将这些连接视为本地客户端。如果 gateway 认证被禁用，这些连接会被拒绝。这可以防止认证绕过：否则，被代理的连接可能看起来像来自 localhost，从而自动获得信任。 +当 Gateway 网关检测到来自**不在** `trustedProxies` 中地址的代理头时，它将**不会**把连接视为本地客户端。如果 gateway auth 被禁用，这些连接将被拒绝。这样可以防止身份验证绕过：否则，被代理的连接可能看起来像是来自 localhost，从而自动获得信任。 -`gateway.trustedProxies` 也会用于 `gateway.auth.mode: "trusted-proxy"`，但该认证模式更严格： +`gateway.trustedProxies` 也用于 `gateway.auth.mode: "trusted-proxy"`，但该 auth 模式更加严格： -- trusted-proxy 认证对 loopback 来源代理**默认失败关闭** -- 同主机 loopback 反向代理仍可使用 `gateway.trustedProxies` 进行本地客户端检测和转发 IP 处理 -- 对于同主机 loopback 反向代理，请使用 token/password 认证，而不是 `gateway.auth.mode: "trusted-proxy"` +- trusted-proxy auth **对来自 loopback 源的代理默认拒绝** +- 同主机 loopback 反向代理仍然可以使用 `gateway.trustedProxies` 进行本地客户端检测和转发 IP 处理 +- 对于同主机 loopback 反向代理，请使用 token/password auth，而不是 `gateway.auth.mode: "trusted-proxy"` ```yaml gateway: trustedProxies: - "10.0.0.1" # 反向代理 IP # 可选。默认 false。 - # 仅在你的代理无法提供 X-Forwarded-For 时启用。 + # 仅当你的代理无法提供 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`。 -受信任代理头不会让节点设备配对自动变得可信。 -`gateway.nodes.pairing.autoApproveCidrs` 是一个单独的、默认禁用的 +受信任代理头不会让节点设备配对自动变为受信任。 +`gateway.nodes.pairing.autoApproveCidrs` 是一个独立的、默认关闭的 操作员策略。即使启用，来自 loopback 源的 trusted-proxy header 路径 -也会被排除在节点自动批准之外，因为本地调用方可以伪造这些头。 +也不会被节点自动批准，因为本地调用方可以伪造这些 header。 良好的反向代理行为（覆盖传入的转发头）： @@ -357,104 +360,106 @@ 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 头。 +- 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 头的来源回退模式；请将其视为操作员主动选择的危险策略。 -- 请将 DNS rebinding 和代理 Host 头行为视为部署加固问题；保持 `trustedProxies` 范围严格，并避免将 gateway 直接暴露到公共互联网。 +- `gateway.controlUi.allowedOrigins: ["*"]` 是显式的允许所有浏览器来源策略，不是加固后的默认值。除非是在严格受控的本地测试中，否则应避免使用。 +- 即使启用了通用 loopback 豁免，loopback 上的浏览器来源身份验证失败仍然会受到速率限制，但锁定键会按规范化后的 `Origin` 值划分，而不是使用一个共享的 localhost 桶。 +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host-header origin fallback 模式；应将其视为操作员主动选择的危险策略。 +- 将 DNS rebinding 和代理 Host header 行为视为部署加固问题；保持 `trustedProxies` 严格，并避免将 gateway 直接暴露到公共互联网。 ## 本地会话日志存储在磁盘上 -OpenClaw 会将会话转录存储在磁盘上的 `~/.openclaw/agents//sessions/*.jsonl`。 -这对于会话连续性以及（可选的）会话记忆索引是必需的，但这也意味着 +OpenClaw 会将会话记录存储在磁盘上的 `~/.openclaw/agents//sessions/*.jsonl`。 +这是实现会话连续性和（可选）会话记忆索引所必需的，但这也意味着 **任何具有文件系统访问权限的进程/用户都可以读取这些日志**。请将磁盘访问视为信任 -边界，并锁定 `~/.openclaw` 的权限（参见下文审计部分）。如果你需要 -在智能体之间提供更强隔离，请将它们运行在不同的 OS 用户下，或使用不同主机。 +边界，并锁定 `~/.openclaw` 的权限（参见下方审计部分）。如果你需要 +在不同智能体之间实现更强隔离，请让它们运行在独立的操作系统用户或独立主机下。 -## 节点执行（system.run） +## 节点执行（`system.run`） -如果某个 macOS 节点已配对，Gateway 网关就可以在该节点上调用 `system.run`。这属于该 Mac 上的**远程代码执行**： +如果已配对一个 macOS 节点，Gateway 网关就可以在该节点上调用 `system.run`。这属于该 Mac 上的**远程代码执行**： -- 需要节点配对（批准 + 令牌）。 -- Gateway 网关节点配对不是逐条命令的批准界面。它建立的是节点身份/信任和令牌签发。 +- 需要节点配对（审批 + token）。 +- Gateway 网关节点配对不是逐命令审批入口。它建立的是节点身份/信任以及 token 签发。 - Gateway 网关通过 `gateway.nodes.allowCommands` / `denyCommands` 应用粗粒度的全局节点命令策略。 -- 在 Mac 上通过 **Settings → Exec approvals** 控制（security + ask + allowlist）。 -- 每个节点的 `system.run` 策略由该节点自己的 exec 批准文件（`exec.approvals.node.*`）控制，它可以比 gateway 的全局命令 ID 策略更严格，也可以更宽松。 -- 以 `security="full"` 和 `ask="off"` 运行的节点，是在遵循默认的受信任操作员模型。除非你的部署明确要求更严格的批准或允许列表策略，否则应将其视为预期行为。 -- 批准模式会绑定精确的请求上下文，并在可能时绑定一个具体的本地脚本/文件操作数。如果 OpenClaw 无法为解释器/运行时命令精确识别唯一的直接本地文件，则会拒绝基于批准的执行，而不是承诺提供完整的语义覆盖。 -- 对于 `host=node`，基于批准的运行还会存储一个规范化的已准备 `systemRunPlan`；后续已批准的转发会复用该已存储计划，并且 gateway 验证会拒绝调用方在批准请求创建后对命令/cwd/会话上下文所做的编辑。 -- 如果你不希望远程执行，请将 security 设为 **deny**，并移除该 Mac 的节点配对。 +- 在 Mac 上通过**设置 → Exec 审批**进行控制（security + ask + allowlist）。 +- 每个节点的 `system.run` 策略由节点自身的 exec 审批文件（`exec.approvals.node.*`）控制，它可以比 gateway 的全局命令 ID 策略更严格，也可以更宽松。 +- 以 `security="full"` 和 `ask="off"` 运行的节点是在遵循默认的受信任操作员模型。除非你的部署明确要求更严格的审批或 allowlist 姿态，否则应将其视为预期行为。 +- 审批模式会绑定精确的请求上下文，并在可能时绑定一个具体的本地脚本/文件操作数。如果 OpenClaw 无法为某个解释器/运行时命令准确识别出唯一的直接本地文件，那么基于审批的执行将被拒绝，而不会声称提供完整的语义覆盖。 +- 对于 `host=node`，基于审批的运行还会存储规范化的预备 + `systemRunPlan`；后续已批准的转发会复用该已存储计划，并且 gateway + 校验会拒绝调用方在审批请求创建后对命令/cwd/会话上下文所做的修改。 +- 如果你不希望远程执行，请将 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 变为可用（基于二进制探测）。 -请将 skill 文件夹视为**受信任代码**，并限制谁可以修改它们。 +应将 skill 文件夹视为**受信任代码**，并限制谁可以修改它们。 ## 威胁模型 你的 AI 助手可以： - 执行任意 shell 命令 -- 读取/写入文件 +- 读写文件 - 访问网络服务 -- 向任何人发送消息（如果你赋予它 WhatsApp 访问权限） +- 向任何人发送消息（如果你给了它 WhatsApp 访问权限） -给你发送消息的人可以： +给你发消息的人可以： -- 试图诱骗你的 AI 去做坏事 -- 通过社会工程方式获取你的数据访问权 -- 探测基础设施细节 +- 试图诱骗你的 AI 做坏事 +- 通过社会工程学获取你的数据访问权限 +- 探测你的基础设施细节 ## 核心概念：先做访问控制，再谈智能 -这里的大多数失败都不是复杂利用——而是“有人给机器人发了消息，而机器人照做了”。 +这里的大多数失败并不是什么高级利用，而是“有人给机器人发了消息，而机器人照做了”。 -OpenClaw 的立场： +OpenClaw 的立场是： -- **先身份：** 决定谁可以和机器人对话（私信配对 / 允许列表 / 显式 “open”）。 -- **再范围：** 决定机器人被允许在哪些地方执行操作（群组允许列表 + 提及门槛、工具、沙箱隔离、设备权限）。 -- **最后才是模型：** 假定模型可以被操纵；要把系统设计成即使被操纵，影响范围也有限。 +- **先确认身份：** 决定谁可以与机器人对话（私信配对 / allowlist / 显式 “open”）。 +- **再限定范围：** 决定机器人被允许在哪些地方执行操作（群组 allowlist + 提及门槛、工具、沙箱隔离、设备权限）。 +- **最后才是模型：** 假设模型可能被操纵；设计时要让这种操纵的影响半径有限。 ## 命令授权模型 -斜杠命令和指令只会对**已授权发送者**生效。授权来源于 -渠道允许列表/配对，加上 `commands.useAccessGroups`（参见 [Configuration](/zh-CN/gateway/configuration) -和 [Slash commands](/zh-CN/tools/slash-commands)）。如果某个渠道允许列表为空，或包含 `"*"`， -则该渠道上的命令实际上就是开放的。 +斜杠命令和指令仅对**已授权发送者**生效。授权来源于 +渠道 allowlist/配对以及 `commands.useAccessGroups`（参见[配置](/zh-CN/gateway/configuration) +和[斜杠命令](/zh-CN/tools/slash-commands)）。如果某个渠道的 allowlist 为空或包含 `"*"`， +那么该渠道上的命令实际上就是开放的。 -`/exec` 是面向已授权操作员的仅会话便捷命令。它**不会**写入配置，也 -不会更改其他会话。 +`/exec` 是仅面向已授权操作员的会话内便捷功能。它**不会**写入配置，也**不会** +更改其他会话。 ## 控制平面工具风险 -两个内置工具可以进行持久化的控制平面变更： +两个内置工具可以进行持久性的控制平面更改： -- `gateway` 可以通过 `config.schema.lookup` / `config.get` 检查配置，也可以通过 `config.apply`、`config.patch` 和 `update.run` 进行持久化更改。 -- `cron` 可以创建在原始聊天/任务结束后仍持续运行的定时任务。 +- `gateway` 可以通过 `config.schema.lookup` / `config.get` 检查配置，并可通过 `config.apply`、`config.patch` 和 `update.run` 进行持久化更改。 +- `cron` 可以创建定时任务，使其在原始聊天/任务结束后继续运行。 -仅限所有者的 `gateway` 运行时工具仍会拒绝重写 -`tools.exec.ask` 或 `tools.exec.security`；旧版 `tools.bash.*` 别名 -会先被规范化到相同的受保护 exec 路径，再进行写入。 +仅限所有者的 `gateway` 运行时工具仍然拒绝重写 +`tools.exec.ask` 或 `tools.exec.security`；旧版 `tools.bash.*` 别名会 +在写入前被规范化为相同的受保护 exec 路径。 由智能体驱动的 `gateway config.apply` 和 `gateway config.patch` 编辑 -默认是失败关闭的：只有一小部分 prompt、model 和提及门槛 -路径允许由智能体调整。因此，新的敏感配置树会默认受到保护， -除非它们被刻意加入允许列表。 +默认是失败关闭的：只有一小部分 prompt、model 和 mention-gating +路径允许由智能体调整。因此，新的敏感配置树默认会受到保护， +除非它们被有意加入 allowlist。 -对于任何处理不受信任内容的智能体/界面，默认都应拒绝这些工具： +对于任何处理不受信任内容的智能体/入口面，默认都应拒绝这些工具： ```json5 { @@ -464,33 +469,33 @@ OpenClaw 的立场： } ``` -`commands.restart=false` 只会阻止重启动作。它不会禁用 `gateway` 配置/更新操作。 +`commands.restart=false` 只会阻止重启动作。它不会禁用 `gateway` 的配置/更新操作。 ## 插件 -插件**在进程内**与 Gateway 网关一起运行。请将它们视为受信任代码： +插件与 Gateway 网关**在同一进程内**运行。应将其视为受信任代码： - 只安装来自你信任来源的插件。 -- 优先使用显式 `plugins.allow` 允许列表。 +- 优先使用显式的 `plugins.allow` allowlist。 - 启用前审查插件配置。 -- 修改插件后重启 Gateway 网关。 -- 如果你安装或更新插件（`openclaw plugins install `、`openclaw plugins update `），请将其视为运行不受信任代码： +- 插件更改后重启 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` 钩子策略阻止，也不会绕过扫描失败。 - - 基于 Gateway 网关的 skill 依赖安装遵循相同的危险/可疑划分：内置 `critical` 发现会阻止安装，除非调用方显式设置 `dangerouslyForceUnsafeInstall`，而可疑发现仍然只会发出警告。`openclaw skills install` 仍然是独立的 ClawHub skill 下载/安装流程。 + - OpenClaw 使用 `npm pack`，然后在该目录中运行项目本地的 `npm install --omit=dev --ignore-scripts`。继承的全局 npm 安装设置会被忽略，以确保依赖始终保留在插件安装路径下。 + - 优先使用固定且精确的版本（`@scope/pkg@1.2.3`），并在启用前检查磁盘上解包后的代码。 + - `--dangerously-force-unsafe-install` 仅用于在插件安装/更新流程中处理内置扫描误报的紧急破窗场景。它不会绕过插件 `before_install` 钩子策略阻止，也不会绕过扫描失败。 + - 基于 Gateway 网关的 skill 依赖安装遵循同样的危险/可疑分类：内置 `critical` 发现会默认阻止，除非调用方显式设置 `dangerouslyForceUnsafeInstall`；而可疑发现仍然只会发出警告。`openclaw skills install` 仍然是独立的 ClawHub skill 下载/安装流程。 -详情： [Plugins](/zh-CN/tools/plugin) +详情见：[插件](/zh-CN/tools/plugin) -## 私信访问模型：pairing、allowlist、open、disabled +## 私信访问模型：配对、allowlist、开放、禁用 -所有当前支持私信的渠道都支持一个私信策略（`dmPolicy` 或 `*.dm.policy`），用于在处理消息**之前**控制入站私信： +所有当前支持私信的渠道都支持 DM 策略（`dmPolicy` 或 `*.dm.policy`），它会在消息处理**之前**限制入站私信： -- `pairing`（默认）：未知发送者会收到一个简短配对代码，在获批前机器人会忽略其消息。代码 1 小时后过期；重复发送私信不会重复发送代码，除非创建了新请求。待处理请求默认每个渠道最多 **3 个**。 +- `pairing`（默认）：未知发送者会收到一个简短的配对码，而机器人会忽略其消息，直到获得批准。配对码在 1 小时后过期；在新请求创建之前，重复私信不会重复发送配对码。默认情况下，每个渠道待处理请求最多为 **3 个**。 - `allowlist`：未知发送者会被阻止（没有配对握手）。 -- `open`：允许任何人发送私信（公开）。**要求**该渠道允许列表包含 `"*"`（显式选择启用）。 +- `open`：允许任何人发送私信（公开）。**要求** 该渠道的 allowlist 包含 `"*"`（显式选择启用）。 - `disabled`：完全忽略入站私信。 通过 CLI 批准： @@ -500,11 +505,11 @@ openclaw pairing list openclaw pairing approve ``` -详情和磁盘文件位置： [Pairing](/zh-CN/channels/pairing) +详情及磁盘文件位置见：[配对](/zh-CN/channels/pairing) ## 私信会话隔离（多用户模式） -默认情况下，OpenClaw 会将**所有私信都路由到主会话**，这样你的助手可以跨设备和渠道保持连续性。如果**多个人**都可以给机器人发送私信（开放私信或多人允许列表），请考虑隔离私信会话： +默认情况下，OpenClaw 会将**所有私信路由到主会话**，以便你的助手在不同设备和渠道之间保持连续性。如果**多个人**可以给机器人发送私信（开放私信或多人 allowlist），请考虑隔离私信会话： ```json5 { @@ -512,212 +517,217 @@ openclaw pairing approve } ``` -这可以防止跨用户上下文泄漏，同时保持群聊隔离。 +这样可以防止跨用户上下文泄露，同时保持群聊彼此隔离。 -这是消息上下文边界，不是主机管理员边界。如果用户彼此具有对抗关系，并共享同一个 Gateway 网关主机/配置，请按信任边界运行独立 Gateway 网关。 +这是消息上下文边界，不是主机管理员边界。如果用户彼此具有对抗关系，并且共享同一个 Gateway 网关主机/配置，请按信任边界运行独立的 Gateway 网关。 ### 安全私信模式（推荐） -请将上面的片段视为**安全私信模式**： +将上面的代码片段视为**安全私信模式**： -- 默认值：`session.dmScope: "main"`（所有私信共享一个会话，以保持连续性）。 +- 默认：`session.dmScope: "main"`（所有私信共享一个会话，以保持连续性）。 - 本地 CLI 新手引导默认：当未设置时写入 `session.dmScope: "per-channel-peer"`（保留现有显式值）。 -- 安全私信模式：`session.dmScope: "per-channel-peer"`（每个渠道 + 发送者组合都有独立的私信上下文）。 -- 跨渠道联系人隔离：`session.dmScope: "per-peer"`（同一发送者在同类型所有渠道中共享一个会话）。 +- 安全私信模式：`session.dmScope: "per-channel-peer"`（每个渠道 + 发送者组合都获得隔离的私信上下文）。 +- 跨渠道联系人隔离：`session.dmScope: "per-peer"`（同类型所有渠道中的每个发送者共享一个会话）。 -如果你在同一渠道上运行多个账户，请改用 `per-account-channel-peer`。如果同一个人通过多个渠道联系你，请使用 `session.identityLinks` 将这些私信会话合并为一个规范身份。参见 [Session Management](/zh-CN/concepts/session) 和 [Configuration](/zh-CN/gateway/configuration)。 +如果你在同一个渠道上运行多个账号，请改用 `per-account-channel-peer`。如果同一个人通过多个渠道联系你，请使用 `session.identityLinks` 将这些私信会话合并为一个规范身份。参见[会话管理](/zh-CN/concepts/session)和[配置](/zh-CN/gateway/configuration)。 -## 私信和群组的允许列表 +## 私信和群组的 allowlist OpenClaw 有两个彼此独立的“谁可以触发我？”层级： -- **私信允许列表**（`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`；旧版：`channels.discord.dm.allowFrom`、`channels.slack.dm.allowFrom`）：谁被允许在私信中与机器人对话。 - - 当 `dmPolicy="pairing"` 时，批准结果会写入 `~/.openclaw/credentials/` 下按账户划分的配对允许列表存储（默认账户为 `-allowFrom.json`，非默认账户为 `--allowFrom.json`），并与配置允许列表合并。 -- **群组允许列表**（按渠道区分）：机器人会接受哪些群组/频道/guild 的消息。 +- **私信 allowlist**（`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`；旧版：`channels.discord.dm.allowFrom`、`channels.slack.dm.allowFrom`）：谁可以在私信中与机器人对话。 + - 当 `dmPolicy="pairing"` 时，批准结果会写入 `~/.openclaw/credentials/` 下按账号划分的配对 allowlist 存储中（默认账号为 `-allowFrom.json`，非默认账号为 `--allowFrom.json`），并与配置中的 allowlist 合并。 +- **群组 allowlist**（按渠道定义）：机器人到底会接受哪些群组/频道/guild 的消息。 - 常见模式： - - `channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups`：按群组配置默认值，如 `requireMention`；设置后，它也会充当群组允许列表（包含 `"*"` 可保持允许全部行为）。 - - `groupPolicy="allowlist"` + `groupAllowFrom`：限制在群组会话内部谁可以触发机器人（WhatsApp/Telegram/Signal/iMessage/Microsoft Teams）。 - - `channels.discord.guilds` / `channels.slack.channels`：按界面划分的允许列表 + 提及默认值。 - - 群组检查按以下顺序运行：先 `groupPolicy`/群组允许列表，再提及/回复激活。 - - 回复机器人消息（隐式提及）**不会**绕过像 `groupAllowFrom` 这样的发送者允许列表。 - - **安全说明：** 请将 `dmPolicy="open"` 和 `groupPolicy="open"` 视为最后手段。应尽量少用；除非你完全信任房间中的每一个成员，否则应优先使用配对 + 允许列表。 + - `channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups`：每个群组的默认值，如 `requireMention`；设置后它也会充当群组 allowlist（包含 `"*"` 以保持允许所有群组的行为）。 + - `groupPolicy="allowlist"` + `groupAllowFrom`：限制在某个群组会话**内部**谁可以触发机器人（WhatsApp/Telegram/Signal/iMessage/Microsoft Teams）。 + - `channels.discord.guilds` / `channels.slack.channels`：按入口面设置的 allowlist + 提及默认值。 + - 群组检查的顺序是：先检查 `groupPolicy`/群组 allowlist，再检查提及/回复激活。 + - 回复机器人消息（隐式提及）**不会**绕过诸如 `groupAllowFrom` 之类的发送者 allowlist。 + - **安全提示：** 应将 `dmPolicy="open"` 和 `groupPolicy="open"` 视为最后手段。它们应尽量少用；除非你完全信任房间中的每个成员，否则优先使用配对 + allowlist。 -详情： [Configuration](/zh-CN/gateway/configuration) 和 [Groups](/zh-CN/channels/groups) +详情见：[配置](/zh-CN/gateway/configuration) 和 [群组](/zh-CN/channels/groups) ## 提示注入（它是什么，为什么重要） -提示注入是指攻击者精心构造一条消息，操纵模型去执行不安全的事情（“忽略你的指令”、“导出你的文件系统”、“打开这个链接并运行命令”等）。 +提示注入是指攻击者精心构造一条消息，操纵模型执行不安全行为（“忽略你的指令”、“导出你的文件系统”、“访问这个链接并运行命令”等）。 -即使有很强的系统提示词，**提示注入也没有被解决**。系统提示词护栏只是软性指导；真正的强制执行来自工具策略、exec 批准、沙箱隔离和渠道允许列表（并且操作员可以按设计禁用这些机制）。在实践中真正有帮助的是： +即使有很强的系统提示，**提示注入问题也没有被解决**。系统提示护栏只是软性指导；真正的强制约束来自工具策略、exec 审批、沙箱隔离和渠道 allowlist（而且操作员可以按设计关闭它们）。实践中真正有帮助的是： -- 保持入站私信处于锁定状态（配对/允许列表）。 -- 在群组中优先使用提及门槛；避免在公共房间中使用“始终在线”机器人。 -- 默认将链接、附件和粘贴的指令视为不可信内容。 -- 在沙箱中运行敏感工具执行；不要把密钥放在智能体可访问的文件系统里。 -- 注意：沙箱隔离是可选启用的。如果沙箱模式关闭，隐式 `host=auto` 会解析为 gateway 主机。显式 `host=sandbox` 仍会失败关闭，因为没有可用的沙箱运行时。如果你希望这种行为在配置中明确表达，请设置 `host=gateway`。 -- 将高风险工具（`exec`、`browser`、`web_fetch`、`web_search`）限制给受信任智能体或显式允许列表。 -- 如果你将解释器（`python`、`node`、`ruby`、`perl`、`php`、`lua`、`osascript`）加入允许列表，请启用 `tools.exec.strictInlineEval`，这样内联求值形式仍然需要显式批准。 -- Shell 批准分析还会拒绝**未加引号的 heredoc** 中的 POSIX 参数展开形式（`$VAR`、`$?`、`$$`、`$1`、`$@`、`${…}`），这样加入允许列表的 heredoc 正文就不能把 shell 展开伪装成纯文本绕过允许列表审查。给 heredoc 终止符加引号（例如 `<<'EOF'`）可启用字面量正文语义；会展开变量的未加引号 heredoc 会被拒绝。 -- **模型选择很重要：** 较旧/较小/旧版模型对提示注入和工具滥用的抵抗能力明显更弱。对于启用了工具的智能体，请使用当前可用的最强、最新一代、经过指令加固的模型。 +- 保持入站私信处于锁定状态（配对/allowlist）。 +- 在群组中优先使用提及门槛；避免在公共房间中使用“始终在线”的机器人。 +- 默认将链接、附件和粘贴的指令视为不受信任内容。 +- 在沙箱中运行敏感工具执行；让 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 形式仍然需要显式审批。 +- Shell 审批分析还会拒绝 **未加引号的 heredoc** 中的 POSIX 参数展开形式（`$VAR`、`$?`、`$$`、`$1`、`$@`、`${…}`），这样 allowlist 中的 heredoc 内容就不能在 allowlist 审查时伪装成纯文本，从而偷偷进行 shell 展开。给 heredoc 终止符加引号（例如 `<<'EOF'`）即可选择字面量正文语义；未加引号且会发生变量展开的 heredoc 会被拒绝。 +- **模型选择很重要：** 较旧/较小/旧版的模型在面对提示注入和工具滥用时明显更脆弱。对于启用了工具的智能体，请使用当前可用的最强最新一代、经过指令防护强化的模型。 -应视为不可信的危险信号： +应视为不受信任的危险信号： -- “读取这个文件/URL，并完全照它说的做。” -- “忽略你的系统提示词或安全规则。” +- “读取这个文件/URL，然后严格按它说的做。” +- “忽略你的系统提示或安全规则。” - “泄露你的隐藏指令或工具输出。” -- “贴出 `~/.openclaw` 或你的日志的全部内容。” +- “贴出 `~/.openclaw` 或你的日志的完整内容。” -## 外部内容特殊令牌清洗 +## 外部内容特殊 token 清洗 -OpenClaw 会在包装外部内容和元数据时，先移除常见的自托管 LLM 聊天模板特殊令牌字面量，然后再将其发送给模型。覆盖的标记家族包括 Qwen/ChatML、Llama、Gemma、Mistral、Phi 和 GPT-OSS 的角色/轮次令牌。 +OpenClaw 会在包装外部内容和元数据时，先移除常见的自托管 LLM chat-template 特殊 token 字面量，然后再将它们送入模型。覆盖的标记家族包括 Qwen/ChatML、Llama、Gemma、Mistral、Phi 和 GPT-OSS 的角色/回合 token。 原因： -- 一些以前置自托管模型的 OpenAI 兼容后端，在用户文本中出现特殊令牌时可能会原样保留，而不是进行屏蔽。攻击者如果能够写入入站外部内容（例如抓取到的页面、邮件正文、文件内容工具输出），就可能注入一个伪造的 `assistant` 或 `system` 角色边界，从而逃逸已包装内容的护栏。 -- 清洗发生在外部内容包装层，因此它会统一应用于抓取/读取工具和入站渠道内容，而不是按提供商单独处理。 -- 出站模型响应已经有单独的清洗器，会从用户可见回复中移除泄漏的 ``、`` 等脚手架。外部内容清洗器则是它的入站对应物。 +- 一些以前置自托管模型的 OpenAI-compatible 后端，有时会保留出现在用户文本中的特殊 token，而不是将其屏蔽。攻击者如果能够写入入站外部内容（抓取的页面、邮件正文、文件内容工具输出），否则就可能注入一个伪造的 `assistant` 或 `system` 角色边界，从而绕过包装内容的护栏。 +- 清洗发生在外部内容包装层，因此会统一适用于抓取/读取工具以及入站渠道内容，而不是按 provider 分别处理。 +- 出站模型响应已经有独立的清洗器，会从用户可见回复中移除泄露的 ``、`` 等类似脚手架。外部内容清洗则是它的入站对应项。 -这不能替代本页中的其他加固措施——`dmPolicy`、允许列表、exec 批准、沙箱隔离和 `contextVisibility` 仍然承担主要作用。它封堵的是一种特定的分词器层绕过：针对会把带特殊令牌的用户文本原样转发的自托管堆栈。 +这并不能替代本页中的其他加固措施——`dmPolicy`、allowlist、exec 审批、沙箱隔离和 `contextVisibility` 仍然承担主要作用。它所解决的是一个特定的 tokenizer 层绕过问题，针对的是那些会在转发用户文本时保留特殊 token 不变的自托管技术栈。 ## 不安全外部内容绕过标志 -OpenClaw 包含一些显式绕过标志，用于禁用外部内容安全包装： +OpenClaw 包含显式绕过标志，可禁用外部内容安全包装： - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` - Cron 负载字段 `allowUnsafeExternalContent` -指导建议： +建议： - 在生产环境中保持这些设置未启用/为 false。 -- 仅在严格限定的调试场景下临时启用。 -- 如果启用，请隔离该智能体（沙箱隔离 + 最小化工具 + 专用会话命名空间）。 +- 仅在严格限定范围的调试场景中临时启用。 +- 如果启用，请隔离该智能体（沙箱隔离 + 最小工具集 + 专用会话命名空间）。 Hooks 风险说明： -- Hook 负载是不可信内容，即使它们来自你可控的系统（邮件/文档/网页内容仍可能携带提示注入）。 -- 较弱的模型层级会增加这一风险。对于 hook 驱动自动化，请优先使用强大的现代模型层级，并保持严格的工具策略（`tools.profile: "messaging"` 或更严格），并在可能时启用沙箱隔离。 +- Hook 负载属于不受信任内容，即使投递来自你控制的系统也是如此（邮件/文档/网页内容都可能携带提示注入）。 +- 较弱的模型层级会放大这种风险。对于由 hook 驱动的自动化，优先使用强力的现代模型层级，并保持严格的工具策略（`tools.profile: "messaging"` 或更严格），并尽可能启用沙箱隔离。 ### 提示注入并不需要公开私信 -即使**只有你自己**可以给机器人发送消息，提示注入仍然可能通过 -机器人读取的任何**不可信内容**发生（web 搜索/抓取结果、浏览器页面、 -电子邮件、文档、附件、粘贴的日志/代码）。换句话说：发送者并不是 +即使**只有你**可以给机器人发消息，提示注入仍然可能通过 +机器人读取的任何**不受信任内容**发生（网页搜索/抓取结果、浏览器页面、 +邮件、文档、附件、粘贴的日志/代码）。换句话说：发送者并不是 唯一的威胁面；**内容本身**也可能携带对抗性指令。 -启用工具后，典型风险是外泄上下文或触发工具调用。可通过以下方式降低影响范围： +当工具启用时，典型风险是外泄上下文或触发 +工具调用。降低影响半径的方法包括： -- 使用只读或禁用工具的**阅读智能体**来总结不可信内容， +- 使用只读或禁用工具的**阅读智能体**来总结不受信任内容， 然后再把摘要传给你的主智能体。 - 除非确有需要，否则对启用了工具的智能体关闭 `web_search` / `web_fetch` / `browser`。 - 对于 OpenResponses URL 输入（`input_file` / `input_image`），设置严格的 `gateway.http.endpoints.responses.files.urlAllowlist` 和 `gateway.http.endpoints.responses.images.urlAllowlist`，并保持 `maxUrlParts` 较低。 - 空允许列表会被视为未设置；如果你想完全禁用 URL 抓取，请使用 `files.allowUrl: false` / `images.allowUrl: false`。 + 空 allowlist 会被视为未设置；如果你想完全禁用 URL 抓取，请使用 `files.allowUrl: false` / `images.allowUrl: false`。 - 对于 OpenResponses 文件输入，解码后的 `input_file` 文本仍会作为 - **不可信外部内容**注入。不要因为 Gateway 网关是在本地解码文件文本， - 就把它当作可信内容。注入块仍会携带显式的 + **不受信任的外部内容**注入。不要因为文件文本是由 Gateway 网关本地解码， + 就假定它是可信的。注入块仍然会携带显式的 `<<>>` 边界标记以及 `Source: External` 元数据，尽管这一路径省略了更长的 `SECURITY NOTICE:` 横幅。 -- 当媒体理解在把文本附加到媒体提示词之前，从附件文档中提取文本时，也会应用同样基于标记的包装。 -- 对任何接触不可信输入的智能体启用沙箱隔离和严格工具允许列表。 -- 不要把密钥放进提示词中；改为通过 gateway 主机上的 env/config 传递。 +- 当媒体理解在将文本附加到媒体提示前从附件文档中提取文本时， + 也会应用同样基于标记的包装。 +- 对任何接触不受信任输入的智能体启用沙箱隔离和严格的工具 allowlist。 +- 不要把 secrets 放进提示中；应通过 gateway 主机上的 env/config 传递它们。 ### 自托管 LLM 后端 -OpenAI 兼容的自托管后端，例如 vLLM、SGLang、TGI、LM Studio， -或自定义 Hugging Face tokenizer 堆栈，在处理聊天模板特殊令牌时， -可能与托管提供商有所不同。如果某个后端会把字面量字符串 -如 `<|im_start|>`、`<|start_header_id|>` 或 `` 作为 -用户内容中的结构化聊天模板令牌进行分词，那么不可信文本就可能尝试 -在分词器层伪造角色边界。 +OpenAI-compatible 的自托管后端，如 vLLM、SGLang、TGI、LM Studio， +或自定义 Hugging Face tokenizer 技术栈，在处理 +chat-template 特殊 token 时，可能与托管 provider 有所不同。如果某个后端会把 +`<|im_start|>`、`<|start_header_id|>` 或 `` 这样的字面字符串 +在用户内容中分词为结构化的 chat-template token， +那么不受信任文本就可能尝试在 tokenizer 层伪造角色边界。 -OpenClaw 会在分发给模型之前，从包装的外部内容中移除常见模型家族的特殊令牌字面量。请保持外部内容包装启用，并在可用时优先使用能对用户提供内容中的特殊令牌进行拆分或转义的后端设置。像 OpenAI -和 Anthropic 这样的托管提供商已经在请求侧应用了自己的清洗。 +OpenClaw 会在分发给模型之前，从包装过的 +外部内容中移除常见模型家族的特殊 token 字面量。请保持外部内容 +包装处于启用状态，并在可用时优先使用会拆分或转义 +用户提供内容中特殊 token 的后端设置。像 OpenAI +和 Anthropic 这样的托管 provider 已经在请求侧应用了自己的清洗措施。 ### 模型强度（安全说明） -不同模型层级对提示注入的抵抗能力**并不相同**。更小/更便宜的模型通常更容易被诱导滥用工具和劫持指令，尤其是在对抗性提示词下。 +不同模型层级的提示注入抵抗能力**并不一致**。更小/更便宜的模型通常更容易受到工具滥用和指令劫持的影响，尤其是在对抗性提示下。 -对于启用了工具的智能体或会读取不可信内容的智能体，较旧/较小模型的提示注入风险通常过高。不要在弱模型层级上运行这些工作负载。 +对于启用了工具的智能体，或会读取不受信任内容的智能体，较旧/较小模型带来的提示注入风险通常过高。不要在弱模型层级上运行这些工作负载。 建议： -- 对任何可以运行工具或接触文件/网络的机器人，**使用最新一代、最高档位的模型**。 -- **不要对启用了工具的智能体或不可信收件箱使用较旧/较弱/较小的模型层级**；提示注入风险过高。 -- 如果你必须使用较小模型，请**缩小影响范围**（只读工具、强沙箱隔离、最小文件系统访问、严格允许列表）。 -- 运行小模型时，请**为所有会话启用沙箱隔离**，并**禁用 web_search/web_fetch/browser**，除非输入受到严格控制。 -- 对于只有聊天功能、输入可信且不启用工具的个人助手，较小模型通常没问题。 +- 对任何能够运行工具或接触文件/网络的机器人，**使用最新一代、最高等级的模型**。 +- **不要为启用了工具的智能体或不受信任收件箱使用较旧/较弱/较小的层级**；提示注入风险过高。 +- 如果你必须使用较小的模型，请**缩小影响半径**（只读工具、强沙箱隔离、最小文件系统访问、严格 allowlist）。 +- 运行小模型时，**为所有会话启用沙箱隔离**，并且除非输入受到严格控制，否则**禁用 `web_search`/`web_fetch`/`browser`**。 +- 对于仅聊天的个人助手、输入可信且不启用工具的场景，较小模型通常是可以的。 -## 群组中的推理与详细输出 +## 群组中的推理和详细输出 `/reasoning`、`/verbose` 和 `/trace` 可能会暴露内部推理、工具 输出或插件诊断信息，而这些内容 -原本并不适合出现在公共渠道中。在群组环境下，请将它们视为**仅用于调试** -的功能，除非你确实明确需要，否则请保持关闭。 +本来并不打算出现在公共渠道中。在群组场景下，应将它们视为**仅调试用途**， +除非你明确需要，否则保持关闭。 -指导建议： +建议： - 在公共房间中保持 `/reasoning`、`/verbose` 和 `/trace` 关闭。 -- 如果你要启用它们，请只在受信任私信或严格受控的房间中启用。 -- 请记住：详细和 trace 输出可能包含工具参数、URL、插件诊断以及模型看到的数据。 +- 如果要启用，只应在受信任的私信或严格受控的房间中启用。 +- 请记住：verbose 和 trace 输出可能包含工具参数、URL、插件诊断信息以及模型看到的数据。 ## 配置加固示例 ### 文件权限 -请在 gateway 主机上保持配置和状态为私有： +在 gateway 主机上保持配置和状态私有： - `~/.openclaw/openclaw.json`：`600`（仅用户可读写） - `~/.openclaw`：`700`（仅用户可访问） -`openclaw doctor` 可以发出警告，并提供收紧这些权限的选项。 +`openclaw doctor` 可以发出警告并提供收紧这些权限的选项。 -### 网络暴露（bind、port、防火墙） +### 网络暴露（bind、端口、防火墙） -Gateway 网关会在一个端口上复用 **WebSocket + HTTP**： +Gateway 网关会在单个端口上复用 **WebSocket + HTTP**： -- 默认值：`18789` -- config/flags/env：`gateway.port`、`--port`、`OPENCLAW_GATEWAY_PORT` +- 默认：`18789` +- 配置/flags/env：`gateway.port`、`--port`、`OPENCLAW_GATEWAY_PORT` -这个 HTTP 界面包括 Control UI 和 canvas host： +这个 HTTP 入口面包括 Control UI 和 canvas host： -- Control UI（SPA 静态资源）（默认基础路径 `/`） -- canvas host：`/__openclaw__/canvas/` 和 `/__openclaw__/a2ui/`（任意 HTML/JS；请将其视为不可信内容） +- Control 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 绑定（`"lan"`、`"tailnet"`、`"custom"`）会扩大攻击面。只有在启用 gateway 认证（共享 token/password 或正确配置的非 loopback trusted proxy）并配合真实防火墙时才应使用。 +- 非 loopback bind（`"lan"`、`"tailnet"`、`"custom"`）会扩大攻击面。只有在启用 gateway auth（共享 token/password，或正确配置的非 loopback trusted proxy）并配合真实防火墙时才应使用。 -经验规则： +经验法则： -- 优先使用 Tailscale Serve，而不是 LAN 绑定（Serve 会让 Gateway 网关保持在 loopback 上，由 Tailscale 处理访问）。 -- 如果你必须绑定到 LAN，请用防火墙把端口限制为严格的源 IP 允许列表；不要广泛做端口转发。 -- 绝不要在 `0.0.0.0` 上以未认证方式暴露 Gateway 网关。 +- 优先选择 Tailscale Serve，而不是 LAN bind（Serve 会让 Gateway 网关保持在 loopback 上，由 Tailscale 处理访问）。 +- 如果必须绑定到 LAN，请用防火墙将端口限制为严格的源 IP allowlist；不要广泛做端口转发。 +- 绝不要在 `0.0.0.0` 上无认证暴露 Gateway 网关。 ### 使用 UFW 的 Docker 端口发布 -如果你在 VPS 上使用 Docker 运行 OpenClaw，请记住，容器发布的端口 -（`-p HOST:CONTAINER` 或 Compose `ports:`）会通过 Docker 的转发 -链路进行路由，而不仅仅经过主机的 `INPUT` 规则。 +如果你在 VPS 上使用 Docker 运行 OpenClaw，请记住，已发布的容器端口 +（`-p HOST:CONTAINER` 或 Compose `ports:`）会通过 Docker 的转发链路路由， +而不仅仅经过主机的 `INPUT` 规则。 -为了让 Docker 流量与你的防火墙策略保持一致，请在 -`DOCKER-USER` 中强制执行规则（该链会在 Docker 自己的接受规则之前被评估）。 +为了让 Docker 流量与防火墙策略保持一致，请在 +`DOCKER-USER` 中强制规则（该链会在 Docker 自身的 accept 规则之前被评估）。 在许多现代发行版上，`iptables`/`ip6tables` 使用的是 `iptables-nft` 前端， -但这些规则仍会应用到 nftables 后端。 +但这些规则仍然会应用到 nftables 后端。 -最小允许列表示例（IPv4）： +最小 allowlist 示例（IPv4）： ```bash -# /etc/ufw/after.rules（作为独立的 *filter 区段追加） +# /etc/ufw/after.rules（作为独立的 *filter section 追加） *filter :DOCKER-USER - [0:0] -A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN @@ -733,14 +743,14 @@ bind 模式控制 Gateway 网关监听的位置： COMMIT ``` -IPv6 使用独立的表。如果启用了 Docker IPv6，请在 `/etc/ufw/after6.rules` 中 -添加对应策略。 +IPv6 使用独立的表。如果 +启用了 Docker IPv6，请在 `/etc/ufw/after6.rules` 中添加匹配的策略。 -避免在文档片段中硬编码接口名，例如 `eth0`。不同 VPS 镜像中的接口名 -可能不同（`ens3`、`enp*` 等），不匹配会意外导致你的拒绝规则 -被跳过。 +避免在文档示例中硬编码像 `eth0` 这样的接口名。不同 VPS 镜像上的接口名 +各不相同（`ens3`、`enp*` 等），不匹配可能会意外 +跳过你的拒绝规则。 -重新加载后的快速验证： +重载后的快速验证： ```bash ufw reload @@ -749,22 +759,22 @@ ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` -预期的外部端口应该只包括你有意暴露的那些（对于大多数 -配置：SSH + 你的反向代理端口）。 +预期的外部开放端口应只包括你有意暴露的那些（对大多数 +配置来说：SSH + 你的反向代理端口）。 ### mDNS/Bonjour 发现 -Gateway 网关会通过 mDNS（端口 5353 上的 `_openclaw-gw._tcp`）广播自身存在，以便本地设备发现。在 full 模式下，这会包含可能暴露运行细节的 TXT 记录： +Gateway 网关会通过 mDNS（`_openclaw-gw._tcp`，端口 5353）广播其存在，用于本地设备发现。在 full 模式下，这还包括可能暴露运行细节的 TXT 记录： -- `cliPath`：CLI 二进制的完整文件系统路径（会泄露用户名和安装位置） +- `cliPath`：CLI 二进制文件的完整文件系统路径（会泄露用户名和安装位置） - `sshPort`：广播主机上的 SSH 可用性 - `displayName`、`lanHost`：主机名信息 -**运维安全考量：** 广播基础设施细节会让同一本地网络中的任何人更容易进行侦察。即使是文件系统路径和 SSH 可用性这类“看似无害”的信息，也会帮助攻击者描绘你的环境。 +**操作安全注意事项：** 广播基础设施细节会让本地网络中的任何人更容易进行侦察。即使是文件系统路径、SSH 可用性这类“看似无害”的信息，也能帮助攻击者绘制你的环境图谱。 **建议：** -1. **最小模式**（默认值，推荐用于暴露的 Gateway 网关）：从 mDNS 广播中省略敏感字段： +1. **最小模式**（默认，推荐用于暴露的 Gateway 网关）：从 mDNS 广播中省略敏感字段： ```json5 { @@ -784,7 +794,7 @@ Gateway 网关会通过 mDNS（端口 5353 上的 `_openclaw-gw._tcp`）广播 } ``` -3. **完整模式**（显式启用）：在 TXT 记录中包含 `cliPath` + `sshPort`： +3. **完整模式**（选择启用）：在 TXT 记录中包含 `cliPath` + `sshPort`： ```json5 { @@ -796,17 +806,17 @@ Gateway 网关会通过 mDNS（端口 5353 上的 `_openclaw-gw._tcp`）广播 4. **环境变量**（替代方式）：设置 `OPENCLAW_DISABLE_BONJOUR=1`，无需修改配置即可禁用 mDNS。 -在最小模式下，Gateway 网关仍会广播足够用于设备发现的信息（`role`、`gatewayPort`、`transport`），但会省略 `cliPath` 和 `sshPort`。需要 CLI 路径信息的应用可通过已认证的 WebSocket 连接来获取。 +在最小模式下，Gateway 网关仍会广播足够用于设备发现的信息（`role`、`gatewayPort`、`transport`），但会省略 `cliPath` 和 `sshPort`。需要 CLI 路径信息的应用可以稍后通过已认证的 WebSocket 连接获取。 -### 锁定 Gateway 网关 WebSocket（本地认证） +### 锁定 Gateway 网关 WebSocket（本地身份验证） -默认情况下**必须启用** Gateway 网关认证。如果没有配置有效的 gateway 认证路径， +Gateway 网关身份验证默认**必须启用**。如果没有配置有效的 gateway auth 路径， Gateway 网关会拒绝 WebSocket 连接（失败关闭）。 -新手引导默认会生成一个令牌（即使是 loopback），因此 -本地客户端也必须进行认证。 +新手引导默认会生成一个 token（即使是 loopback），因此 +本地客户端也必须进行身份验证。 -设置一个令牌，让**所有** WS 客户端都必须认证： +设置一个 token，让**所有** WS 客户端都必须身份验证： ```json5 { @@ -816,154 +826,152 @@ Gateway 网关会拒绝 WebSocket 连接（失败关闭）。 } ``` -Doctor 可以为你生成一个：`openclaw doctor --generate-gateway-token`。 +Doctor 可以帮你生成：`openclaw doctor --generate-gateway-token`。 注意：`gateway.remote.token` / `.password` 是客户端凭证来源。它们 本身**不会**保护本地 WS 访问。 -只有在 `gateway.auth.*` -未设置时，本地调用路径才可以把 `gateway.remote.*` 用作回退。 -如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析， -解析会失败关闭（不会被远程回退所掩盖）。 -可选：当使用 `wss://` 时，可通过 `gateway.remote.tlsFingerprint` 固定远程 TLS。 -默认情况下，明文 `ws://` 仅限 loopback。对于受信任的私有网络 +仅当 `gateway.auth.*` +未设置时，本地调用路径才可以把 `gateway.remote.*` 作为回退。 +如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` +但未能解析，则解析会失败关闭（不会用 remote 回退来掩盖）。 +可选：使用 `wss://` 时，通过 `gateway.remote.tlsFingerprint` 固定远程 TLS。 +明文 `ws://` 默认仅限 loopback。对于受信任的私有网络 路径，可在客户端进程上设置 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` -作为破窗手段。这一设置有意仅限进程环境变量，而不是 +作为紧急破窗手段。这故意只支持进程环境变量，而不是 `openclaw.json` 配置键。 -移动端配对以及 Android 手动或扫码的 gateway 路由更严格： -明文可用于 loopback，但私有 LAN、链路本地、`.local` 和 +移动端配对以及 Android 手动或扫描的 gateway 路由更加严格： +明文仅对 loopback 可接受，但私有 LAN、link-local、`.local` 和 无点主机名必须使用 TLS，除非你显式选择启用受信任私有网络明文路径。 本地设备配对： -- 为了让同主机客户端使用更顺畅，直接本地 loopback 连接的设备配对会被自动批准。 -- OpenClaw 还为受信任的共享密钥辅助流程提供了一个狭窄的后端/容器本地自连接路径。 -- Tailnet 和 LAN 连接（包括同主机 tailnet bind）在配对时都视为远程连接，仍然需要批准。 -- loopback 请求中的转发头证据会使其失去 loopback - 本地性资格。元数据升级自动批准的范围也很窄。两者的规则请参见 - [Gateway pairing](/zh-CN/gateway/pairing)。 +- 为了让同主机客户端流程更顺畅，直连本地 loopback 的设备配对会自动批准。 +- OpenClaw 还提供了一条狭义的后端/容器本地自连接路径，用于受信任共享密钥辅助流程。 +- tailnet 和 LAN 连接，包括同主机 tailnet bind，都会被视为远程连接，配对时仍需审批。 +- loopback 请求中的转发 header 证据会使其失去 loopback + 本地属性。元数据升级自动批准的范围也非常有限。详见 + [Gateway 配对](/zh-CN/gateway/pairing) 中这两类规则。 -认证模式： +身份验证模式： -- `gateway.auth.mode: "token"`：共享 bearer 令牌（推荐用于大多数配置）。 -- `gateway.auth.mode: "password"`：密码认证（推荐通过 env 设置：`OPENCLAW_GATEWAY_PASSWORD`）。 -- `gateway.auth.mode: "trusted-proxy"`：信任具备身份感知能力的反向代理为用户完成认证，并通过头传递身份信息（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。 +- `gateway.auth.mode: "token"`：共享 bearer token（大多数场景推荐）。 +- `gateway.auth.mode: "password"`：密码身份验证（建议通过环境变量设置：`OPENCLAW_GATEWAY_PASSWORD`）。 +- `gateway.auth.mode: "trusted-proxy"`：信任具备身份感知能力的反向代理来验证用户身份，并通过 header 传递身份（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。 轮换检查清单（token/password）： -1. 生成/设置新的密钥（`gateway.auth.token` 或 `OPENCLAW_GATEWAY_PASSWORD`）。 -2. 重启 Gateway 网关（或如果由 macOS 应用托管 Gateway 网关，则重启该应用）。 -3. 更新任何远程客户端（在调用 Gateway 网关的机器上更新 `gateway.remote.token` / `.password`）。 -4. 验证旧凭证已无法再建立连接。 +1. 生成/设置新的 secret（`gateway.auth.token` 或 `OPENCLAW_GATEWAY_PASSWORD`）。 +2. 重启 Gateway 网关（如果由 macOS 应用监管 Gateway 网关，也要重启该应用）。 +3. 更新所有远程客户端（调用该 Gateway 网关的机器上的 `gateway.remote.token` / `.password`）。 +4. 验证旧凭证已无法连接。 -### Tailscale Serve 身份头 +### Tailscale Serve 身份 header -当 `gateway.auth.allowTailscale` 为 `true`（Serve 的默认值）时，OpenClaw -会接受 Tailscale Serve 身份头（`tailscale-user-login`）用于 Control -UI/WebSocket 认证。OpenClaw 会通过本地 Tailscale 守护进程（`tailscale whois`） -解析 `x-forwarded-for` 地址，并将其与头中的身份进行匹配，以验证该身份。此流程仅在请求命中 loopback -并包含由 Tailscale 注入的 `x-forwarded-for`、`x-forwarded-proto` 和 `x-forwarded-host` +当 `gateway.auth.allowTailscale` 为 `true` 时（Serve 默认如此），OpenClaw +会接受 Tailscale Serve 身份 header（`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 客户端发起的并发错误重试，可能会导致第二次尝试立刻被锁定， -而不会像两个普通不匹配请求那样并发竞态通过。 - +在这条异步身份检查路径上，同一 `{scope, ip}` +的失败尝试会在限流器记录失败前按顺序串行处理。因此，来自同一个 Serve 客户端的并发错误重试 +可能会立即锁死第二次尝试，而不是像两个普通不匹配那样并发穿过。 HTTP API 端点（例如 `/v1/*`、`/tools/invoke` 和 `/api/channels/*`） -**不会**使用 Tailscale 身份头认证。它们仍然遵循 gateway -已配置的 HTTP 认证模式。 +**不会**使用 Tailscale 身份 header 身份验证。它们仍然遵循 gateway +已配置的 HTTP auth 模式。 重要边界说明： -- Gateway 网关 HTTP bearer 认证实际上是全有或全无的 operator 访问。 -- 能调用 `/v1/chat/completions`、`/v1/responses` 或 `/api/channels/*` 的凭证，应被视为该 gateway 的完全访问 operator 密钥。 -- 在 OpenAI 兼容 HTTP 界面上，共享密钥 bearer 认证会恢复完整的默认 operator 作用域（`operator.admin`、`operator.approvals`、`operator.pairing`、`operator.read`、`operator.talk.secrets`、`operator.write`）以及智能体轮次的所有者语义；更窄的 `x-openclaw-scopes` 值不会缩减这条共享密钥路径。 -- HTTP 上按请求作用域语义仅适用于带身份的模式，例如 trusted proxy auth 或私有入口上的 `gateway.auth.mode="none"`。 -- 在这些带身份模式下，如果省略 `x-openclaw-scopes`，会回退到普通 operator 默认作用域集；如果你想使用更窄的作用域集，请显式发送该头。 -- `/tools/invoke` 遵循同样的共享密钥规则：token/password bearer auth 在那里也被视为完整 operator 访问，而带身份的模式仍会尊重声明的作用域。 -- 不要将这些凭证分享给不受信任的调用方；请按信任边界使用独立 Gateway 网关。 +- Gateway 网关 HTTP bearer auth 实际上等同于全有或全无的操作员访问权限。 +- 能够调用 `/v1/chat/completions`、`/v1/responses` 或 `/api/channels/*` 的凭证，应视为该 gateway 的全访问操作员 secret。 +- 在 OpenAI-compatible HTTP 入口面上，共享密钥 bearer auth 会恢复完整的默认操作员 scope（`operator.admin`、`operator.approvals`、`operator.pairing`、`operator.read`、`operator.talk.secrets`、`operator.write`）以及智能体回合的所有者语义；更窄的 `x-openclaw-scopes` 值不会削弱这条共享密钥路径。 +- HTTP 上的按请求 scope 语义，仅在请求来自带身份的模式时才适用，例如 trusted proxy auth 或私有入口上的 `gateway.auth.mode="none"`。 +- 在这些带身份的模式下，如果省略 `x-openclaw-scopes`，会回退到正常的默认操作员 scope 集；如果你想要更窄的 scope 集，请显式发送该 header。 +- `/tools/invoke` 也遵循相同的共享密钥规则：token/password bearer auth 在这里同样被视为完整操作员访问，而带身份的模式仍会尊重声明的 scope。 +- 不要与不受信任的调用方共享这些凭证；应按信任边界使用独立的 Gateway 网关。 -**信任假设：** 无令牌 Serve 认证假定 gateway 主机是受信任的。 -不要把它当作防御同主机恶意进程的保护机制。如果不受信任的 +**信任假设：** 无 token 的 Serve auth 假设 gateway 主机本身是受信任的。 +不要把它视为防御同主机恶意进程的保护手段。如果不受信任的 本地代码可能在 gateway 主机上运行，请禁用 `gateway.auth.allowTailscale`， -并要求显式共享密钥认证，使用 `gateway.auth.mode: "token"` 或 +并要求使用显式共享密钥身份验证，即 `gateway.auth.mode: "token"` 或 `"password"`。 -**安全规则：** 不要从你自己的反向代理转发这些头。如果 -你在 gateway 前终止 TLS 或做代理，请禁用 -`gateway.auth.allowTailscale`，改用共享密钥认证（`gateway.auth.mode: +**安全规则：** 不要通过你自己的反向代理转发这些 header。如果 +你在 gateway 前面终止 TLS 或做代理，请禁用 +`gateway.auth.allowTailscale`，并改用共享密钥身份验证（`gateway.auth.mode: "token"` 或 `"password"`）或 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)。 受信任代理： - 如果你在 Gateway 网关前终止 TLS，请将 `gateway.trustedProxies` 设置为你的代理 IP。 -- OpenClaw 会信任来自这些 IP 的 `x-forwarded-for`（或 `x-real-ip`），以确定客户端 IP，用于本地配对检查以及 HTTP 认证/本地性检查。 -- 确保你的代理会**覆盖** `x-forwarded-for`，并阻止直接访问 Gateway 网关端口。 +- OpenClaw 会信任来自这些 IP 的 `x-forwarded-for`（或 `x-real-ip`），以确定客户端 IP，用于本地配对检查和 HTTP 身份验证/本地检查。 +- 确保你的代理会**覆盖** `x-forwarded-for`，并阻止对 Gateway 网关端口的直接访问。 -参见 [Tailscale](/zh-CN/gateway/tailscale) 和 [Web overview](/zh-CN/web)。 +参见 [Tailscale](/zh-CN/gateway/tailscale) 和 [Web 概览](/zh-CN/web)。 ### 通过节点主机进行浏览器控制（推荐） -如果你的 Gateway 网关是远程的，但浏览器运行在另一台机器上，请在浏览器机器上运行一个**节点主机**， -让 Gateway 网关代理浏览器操作（参见 [Browser tool](/zh-CN/tools/browser)）。 -请将节点配对视为管理员访问。 +如果你的 Gateway 网关是远程的，但浏览器运行在另一台机器上，请在浏览器所在机器上运行一个**节点主机**， +并让 Gateway 网关代理浏览器操作（参见[浏览器工具](/zh-CN/tools/browser)）。 +应将节点配对视为管理员访问权限。 推荐模式： -- 让 Gateway 网关和节点主机位于同一个 tailnet（Tailscale）中。 -- 有意地完成节点配对；如果你不需要浏览器代理路由，请禁用它。 +- 让 Gateway 网关和节点主机处于同一个 tailnet（Tailscale）中。 +- 有意识地进行节点配对；如果不需要浏览器代理路由，就禁用它。 避免： - 通过 LAN 或公共互联网暴露 relay/control 端口。 -- 将 Tailscale Funnel 用于浏览器控制端点（公共暴露）。 +- 对浏览器控制端点使用 Tailscale Funnel（公开暴露）。 -### 磁盘上的密钥 +### 磁盘上的 secrets -应假定 `~/.openclaw/`（或 `$OPENCLAW_STATE_DIR/`）下的任何内容都可能包含密钥或私有数据： +应假设 `~/.openclaw/`（或 `$OPENCLAW_STATE_DIR/`）下的任何内容都可能包含 secret 或私有数据： -- `openclaw.json`：配置中可能包含令牌（gateway、remote gateway）、提供商设置和允许列表。 -- `credentials/**`：渠道凭证（例如 WhatsApp 凭证）、配对允许列表、旧版 OAuth 导入。 -- `agents//agent/auth-profiles.json`：API 密钥、令牌配置文件、OAuth 令牌，以及可选的 `keyRef`/`tokenRef`。 -- `secrets.json`（可选）：由 `file` SecretRef 提供商（`secrets.providers`）使用的基于文件的密钥负载。 +- `openclaw.json`：配置中可能包含 token（gateway、remote gateway）、provider 设置和 allowlist。 +- `credentials/**`：渠道凭证（例如 WhatsApp 凭证）、配对 allowlist、旧版 OAuth 导入。 +- `agents//agent/auth-profiles.json`：API key、token 配置文件、OAuth token，以及可选的 `keyRef`/`tokenRef`。 +- `secrets.json`（可选）：供 `file` SecretRef provider（`secrets.providers`）使用的文件型 secret 负载。 - `agents//agent/auth.json`：旧版兼容文件。发现静态 `api_key` 条目时会进行清理。 -- `agents//sessions/**`：会话转录（`*.jsonl`）+ 路由元数据（`sessions.json`），其中可能包含私信、工具输出和链接。 -- 内置插件包：已安装插件（以及它们的 `node_modules/`）。 -- `sandboxes/**`：工具沙箱工作区；可能会累积你在沙箱中读取/写入文件的副本。 +- `agents//sessions/**`：会话记录（`*.jsonl`）+ 路由元数据（`sessions.json`），其中可能包含私信、工具输出和链接。 +- 内置插件包：已安装的插件（及其 `node_modules/`）。 +- `sandboxes/**`：工具沙箱工作区；可能会累积你在沙箱内读写的文件副本。 加固建议： -- 保持权限严格（目录 `700`，文件 `600`）。 +- 保持严格权限（目录 `700`，文件 `600`）。 - 在 gateway 主机上使用全盘加密。 -- 如果主机是共享的，优先为 Gateway 网关使用专用 OS 用户账户。 +- 如果主机是共享的，优先为 Gateway 网关使用专用操作系统用户账号。 ### 工作区 `.env` 文件 OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不会让这些文件悄悄覆盖 gateway 运行时控制。 -- 任何以 `OPENCLAW_*` 开头的键都会被不可信工作区 `.env` 文件拦截。 -- Matrix、Mattermost、IRC 和 Synology Chat 的渠道端点设置也会被阻止通过工作区 `.env` 覆盖，因此克隆的工作区无法通过本地端点配置重定向内置连接器流量。端点环境变量键（例如 `MATRIX_HOMESERVER`、`MATTERMOST_URL`、`IRC_HOST`、`SYNOLOGY_CHAT_INCOMING_URL`）必须来自 gateway 进程环境或 `env.shellEnv`，而不能来自工作区加载的 `.env`。 -- 这种拦截是失败关闭的：未来版本中新增的运行时控制变量，无法从已提交或攻击者提供的 `.env` 中继承；该键会被忽略，gateway 会保留自己的值。 -- 受信任的进程/OS 环境变量（gateway 自己的 shell、launchd/systemd 单元、应用包）仍然有效——这里限制的只是 `.env` 文件加载。 +- 任何以 `OPENCLAW_*` 开头的键，都会被来自不受信任工作区 `.env` 文件的值阻止覆盖。 +- Matrix、Mattermost、IRC 和 Synology Chat 的渠道端点设置也会被阻止通过工作区 `.env` 覆盖，因此克隆出来的工作区无法通过本地端点配置重定向内置连接器流量。端点环境变量键（例如 `MATRIX_HOMESERVER`、`MATTERMOST_URL`、`IRC_HOST`、`SYNOLOGY_CHAT_INCOMING_URL`）必须来自 gateway 进程环境或 `env.shellEnv`，而不是工作区加载的 `.env`。 +- 该阻止机制是失败关闭的：将来版本新增的运行时控制变量，不能从已提交到仓库或由攻击者提供的 `.env` 中继承；该键会被忽略，gateway 会保留自己的值。 +- 受信任的进程/操作系统环境变量（gateway 自身的 shell、launchd/systemd 单元、应用 bundle）仍然有效——这个限制只作用于 `.env` 文件加载。 -原因：工作区 `.env` 文件经常与智能体代码放在一起、被意外提交，或被工具写入。拦截整个 `OPENCLAW_*` 前缀意味着未来新增任何 `OPENCLAW_*` 标志，都不会退化为从工作区状态中静默继承。 +原因：工作区 `.env` 文件经常与智能体代码放在一起、被意外提交，或由工具写入。阻止整个 `OPENCLAW_*` 前缀意味着，即使以后新增某个 `OPENCLAW_*` 标志，也绝不会退化成从工作区状态中静默继承。 -### 日志与转录（脱敏与保留） +### 日志和记录（脱敏与保留） -即使访问控制正确，日志和转录也可能泄露敏感信息： +即使访问控制正确，日志和记录也可能泄露敏感信息： - Gateway 网关日志可能包含工具摘要、错误和 URL。 -- 会话转录可能包含粘贴的密钥、文件内容、命令输出和链接。 +- 会话记录可能包含粘贴的 secret、文件内容、命令输出和链接。 建议： - 保持工具摘要脱敏开启（`logging.redactSensitive: "tools"`；默认值）。 -- 通过 `logging.redactPatterns` 为你的环境添加自定义模式（令牌、主机名、内部 URL）。 -- 在共享诊断信息时，优先使用 `openclaw status --all`（可直接粘贴，密钥已脱敏），而不是原始日志。 -- 如果你不需要长期保留，请清理旧的会话转录和日志文件。 +- 通过 `logging.redactPatterns` 为你的环境添加自定义模式（token、主机名、内部 URL）。 +- 分享诊断信息时，优先使用 `openclaw status --all`（可直接粘贴，secrets 已脱敏），而不是原始日志。 +- 如果不需要长期保留，请清理旧的会话记录和日志文件。 -详情： [Logging](/zh-CN/gateway/logging) +详情见：[日志](/zh-CN/gateway/logging) -### 私信：默认启用 pairing +### 私信：默认使用配对 ```json5 { @@ -971,7 +979,7 @@ OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不 } ``` -### 群组：所有地方都要求提及 +### 群组：始终要求提及 ```json { @@ -993,31 +1001,31 @@ OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不 } ``` -在群聊中，只有在被明确提及时才响应。 +在群聊中，仅在被明确提及时才回复。 -### 使用独立号码（WhatsApp、Signal、Telegram） +### 分离号码（WhatsApp、Signal、Telegram） -对于基于手机号的渠道，可以考虑让你的 AI 使用与个人号码分开的号码运行： +对于基于电话号码的渠道，可以考虑让你的 AI 使用与个人号码不同的独立号码： - 个人号码：你的对话保持私密 - 机器人号码：由 AI 处理，并设置适当边界 -### 只读模式（通过沙箱和工具）构建 +### 只读模式（通过沙箱和工具） 你可以通过以下组合构建只读配置： -- `agents.defaults.sandbox.workspaceAccess: "ro"`（或 `"none"` 表示完全不访问工作区） +- `agents.defaults.sandbox.workspaceAccess: "ro"`（或使用 `"none"` 来完全禁止工作区访问） - 使用工具 allow/deny 列表来阻止 `write`、`edit`、`apply_patch`、`exec`、`process` 等。 其他加固选项： -- `tools.exec.applyPatch.workspaceOnly: true`（默认）：确保即使关闭沙箱隔离，`apply_patch` 也不能在工作区目录之外写入/删除。只有在你明确希望 `apply_patch` 操作工作区外文件时，才设置为 `false`。 -- `tools.fs.workspaceOnly: true`（可选）：将 `read`/`write`/`edit`/`apply_patch` 路径以及原生提示词图片自动加载路径限制到工作区目录（如果你当前允许绝对路径，并希望有一个统一护栏，这会很有用）。 -- 保持文件系统根目录范围狭窄：避免把用户主目录这类宽泛根目录用作智能体工作区/沙箱工作区。宽泛根目录可能会把敏感本地文件（例如 `~/.openclaw` 下的状态/配置）暴露给文件系统工具。 +- `tools.exec.applyPatch.workspaceOnly: true`（默认）：确保 `apply_patch` 即使在未启用沙箱隔离时，也不能在工作区目录之外写入/删除文件。只有当你明确希望 `apply_patch` 操作工作区外文件时，才设置为 `false`。 +- `tools.fs.workspaceOnly: true`（可选）：将 `read`/`write`/`edit`/`apply_patch` 路径以及原生提示图片自动加载路径限制在工作区目录中（如果你当前允许绝对路径，而又想加一道统一护栏，这会很有用）。 +- 保持文件系统根目录范围狭窄：避免把你的主目录这类宽泛根目录用作智能体工作区/沙箱工作区。宽泛根目录可能会让文件系统工具接触到敏感本地文件（例如 `~/.openclaw` 下的状态/配置）。 ### 安全基线（可直接复制粘贴） -一个“默认安全”的配置：保持 Gateway 网关私有、要求私信配对，并避免在群组中使用始终在线的机器人： +一个“安全默认”配置示例：保持 Gateway 网关私有、要求私信配对，并避免在群组中部署始终在线的机器人： ```json5 { @@ -1036,69 +1044,69 @@ OpenClaw 会为智能体和工具加载工作区本地 `.env` 文件，但绝不 } ``` -如果你还希望工具执行也“默认更安全”，请为任何非所有者智能体添加沙箱，并拒绝危险工具（示例见下文“按智能体访问配置”）。 +如果你还希望工具执行也“默认更安全”，可为任何非所有者智能体添加沙箱隔离 + 拒绝危险工具（示例见下方“按智能体划分的访问配置”）。 -内置的聊天驱动智能体轮次基线规则：非所有者发送者不能使用 `cron` 或 `gateway` 工具。 +针对由聊天驱动的智能体回合，内置基线策略是：非所有者发送者不能使用 `cron` 或 `gateway` 工具。 ## 沙箱隔离（推荐） -专门文档： [沙箱隔离](/zh-CN/gateway/sandboxing) +专门文档：[沙箱隔离](/zh-CN/gateway/sandboxing) 两种互补方式： -- **在 Docker 中运行完整 Gateway 网关**（容器边界）： [Docker](/zh-CN/install/docker) -- **工具沙箱**（`agents.defaults.sandbox`，gateway 主机 + 沙箱隔离工具；Docker 是默认后端）： [沙箱隔离](/zh-CN/gateway/sandboxing) +- **在 Docker 中运行完整 Gateway 网关**（容器边界）：[Docker](/zh-CN/install/docker) +- **工具沙箱**（`agents.defaults.sandbox`，主机上运行 gateway + 经过沙箱隔离的工具；Docker 是默认后端）：[沙箱隔离](/zh-CN/gateway/sandboxing) 注意：为防止跨智能体访问，请将 `agents.defaults.sandbox.scope` 保持为 `"agent"`（默认） -或使用 `"session"` 以获得更严格的按会话隔离。`scope: "shared"` 会使用单个 -容器/工作区。 +或使用 `"session"` 以实现更严格的按会话隔离。`scope: "shared"` 会使用 +单一容器/工作区。 -另外也要考虑沙箱内的智能体工作区访问： +同时也要考虑沙箱中的智能体工作区访问： -- `agents.defaults.sandbox.workspaceAccess: "none"`（默认）会阻止访问智能体工作区；工具会针对 `~/.openclaw/sandboxes` 下的沙箱工作区运行 +- `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` 会根据规范化和规范路径后的源路径进行校验。如果父目录符号链接技巧或规范化后的 home 别名最终解析到诸如 `/etc`、`/var/run` 或操作系统主目录下凭证目录等受阻止根目录，仍会失败关闭。 -重要：`tools.elevated` 是全局基线逃逸口，用于在沙箱外运行 exec。默认情况下其有效主机是 `gateway`，或者当 exec 目标配置为 `node` 时则为 `node`。请保持 `tools.elevated.allowFrom` 范围严格，不要为陌生人启用它。你还可以通过 `agents.list[].tools.elevated` 按智能体进一步限制提升权限模式。参见 [Elevated Mode](/zh-CN/tools/elevated)。 +重要：`tools.elevated` 是全局基线逃逸通道，会在沙箱之外运行 exec。默认的有效主机是 `gateway`，或者当 exec 目标配置为 `node` 时为 `node`。请保持 `tools.elevated.allowFrom` 严格，不要对陌生人启用。你还可以通过 `agents.list[].tools.elevated` 进一步按智能体限制 elevated。参见[高权限模式](/zh-CN/tools/elevated)。 ### 子智能体委派护栏 -如果你允许会话工具，请将委派给子智能体运行视为另一项边界决策： +如果你允许使用会话工具，请将委派给子智能体运行视为另一个边界决策： -- 除非智能体确实需要委派，否则拒绝 `sessions_spawn`。 +- 除非智能体确实需要委派，否则应拒绝 `sessions_spawn`。 - 保持 `agents.defaults.subagents.allowAgents` 以及任何按智能体覆盖的 `agents.list[].subagents.allowAgents` 仅限已知安全的目标智能体。 -- 对任何必须保持沙箱隔离的工作流，请在调用 `sessions_spawn` 时使用 `sandbox: "require"`（默认值是 `inherit`）。 -- `sandbox: "require"` 会在目标子运行时未启用沙箱时快速失败。 +- 对于任何必须保持沙箱隔离的工作流，请在调用 `sessions_spawn` 时使用 `sandbox: "require"`（默认值是 `inherit`）。 +- `sandbox: "require"` 会在目标子运行时未启用沙箱隔离时快速失败。 ## 浏览器控制风险 -启用浏览器控制会赋予模型驱动真实浏览器的能力。 -如果该浏览器配置文件中已登录某些会话，模型就可能 -访问这些账户和数据。请将浏览器配置文件视为**敏感状态**： +启用浏览器控制意味着模型可以驱动一个真实浏览器。 +如果该浏览器配置文件中已经存在已登录会话，模型就可以 +访问这些账号和数据。应将浏览器配置文件视为**敏感状态**： - 优先为智能体使用专用配置文件（默认的 `openclaw` 配置文件）。 - 避免让智能体使用你的个人日常浏览器配置文件。 - 对于沙箱隔离的智能体，除非你信任它们，否则请保持主机浏览器控制关闭。 -- 独立的 loopback 浏览器控制 API 只接受共享密钥认证 +- 独立的 loopback 浏览器控制 API 仅接受共享密钥身份验证 （gateway token bearer auth 或 gateway password）。它不会使用 - trusted-proxy 或 Tailscale Serve 身份头。 -- 将浏览器下载视为不可信输入；优先使用隔离的下载目录。 -- 如有可能，请在智能体配置文件中禁用浏览器同步/密码管理器（可降低影响范围）。 -- 对于远程 Gateway 网关，应将“浏览器控制”等同视为对该配置文件可访问内容的“operator 访问”。 -- 让 Gateway 网关和节点主机仅暴露在 tailnet 中；避免将浏览器控制端口暴露到 LAN 或公共互联网。 -- 在不需要时禁用浏览器代理路由（`gateway.nodes.browser.mode="off"`）。 -- Chrome MCP 现有会话模式**并不**“更安全”；它可以以你的身份操作该主机 Chrome 配置文件能访问的任何内容。 + trusted-proxy 或 Tailscale Serve 身份 header。 +- 将浏览器下载内容视为不受信任输入；优先使用隔离的下载目录。 +- 如果可能，请在智能体浏览器配置文件中禁用浏览器同步/密码管理器（可减少影响半径）。 +- 对于远程 gateway，应将“浏览器控制”等同看待为对该浏览器配置文件可访问内容的“操作员访问”。 +- 让 Gateway 网关和节点主机仅处于 tailnet 内；避免将浏览器控制端口暴露到 LAN 或公共互联网。 +- 不需要浏览器代理路由时，请关闭它（`gateway.nodes.browser.mode="off"`）。 +- Chrome MCP 的现有会话模式**并不**“更安全”；它能够以你的身份操作该主机上对应 Chrome 配置文件所能访问的一切。 ### 浏览器 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 上再次尽力检查。 严格策略示例： @@ -1114,17 +1122,17 @@ OpenClaw 的浏览器导航策略默认是严格的：私有/内部目标会被 } ``` -## 按智能体访问配置（多智能体） +## 按智能体划分的访问配置（多智能体） -使用多智能体路由时，每个智能体都可以有自己的沙箱 + 工具策略： -利用这一点，你可以按智能体分配**完全访问**、**只读**或**无访问权限**。 -完整细节和优先级规则请参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +在多智能体路由中，每个智能体都可以拥有自己的沙箱隔离 + 工具策略： +可利用这一点为不同智能体配置**完全访问**、**只读**或**无访问**。 +完整细节和优先级规则见[多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 -常见使用场景： +常见用例： - 个人智能体：完全访问，不使用沙箱 - 家庭/工作智能体：沙箱隔离 + 只读工具 -- 公开智能体：沙箱隔离 + 无文件系统/shell 工具 +- 公共智能体：沙箱隔离 + 无文件系统/shell 工具 ### 示例：完全访问（无沙箱） @@ -1166,7 +1174,7 @@ OpenClaw 的浏览器导航策略默认是严格的：私有/内部目标会被 } ``` -### 示例：无文件系统/shell 访问（允许提供商消息工具） +### 示例：无文件系统/shell 访问（允许 provider 消息工具） ```json5 { @@ -1180,8 +1188,8 @@ OpenClaw 的浏览器导航策略默认是严格的：私有/内部目标会被 scope: "agent", workspaceAccess: "none", }, - // 会话工具可能泄露转录中的敏感数据。默认情况下 OpenClaw 将这些工具限制为 - // 当前会话 + 生成的子智能体会话，但如有需要你可以进一步收紧。 + // 会话工具可能泄露记录中的敏感数据。默认情况下，OpenClaw 将这些工具限制为 + // 当前会话 + 由其生成的子智能体会话，但如果需要，你可以进一步收紧。 // 参见配置参考中的 `tools.sessions.visibility`。 tools: { sessions: { visibility: "tree" }, // self | tree | agent | all @@ -1221,38 +1229,37 @@ OpenClaw 的浏览器导航策略默认是严格的：私有/内部目标会被 如果你的 AI 做了不该做的事： -### 遏制 +### 控制局势 -1. **停止它：** 停止 macOS 应用（如果它负责托管 Gateway 网关），或终止你的 `openclaw gateway` 进程。 -2. **关闭暴露面：** 将 `gateway.bind` 设为 `"loopback"`（或禁用 Tailscale Funnel/Serve），直到你弄清楚发生了什么。 -3. **冻结访问：** 将高风险私信/群组切换为 `dmPolicy: "disabled"` / 要求提及，并移除你之前设置的 `"*"` 全部允许条目。 +1. **停止它：** 停止 macOS 应用（如果它在监管 Gateway 网关），或终止你的 `openclaw gateway` 进程。 +2. **关闭暴露面：** 将 `gateway.bind` 设为 `"loopback"`（或禁用 Tailscale Funnel/Serve），直到你弄清发生了什么。 +3. **冻结访问：** 将高风险私信/群组切换为 `dmPolicy: "disabled"` / 要求提及，并移除你之前可能设置的 `"*"` 全开放条目。 -### 轮换（如果密钥泄露，则假定已被攻破） +### 轮换（如果 secrets 泄露，则按已泄露处理） -1. 轮换 Gateway 网关认证（`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`）并重启。 -2. 在任何可以调用 Gateway 网关的机器上轮换远程客户端密钥（`gateway.remote.token` / `.password`）。 -3. 轮换提供商/API 凭证（WhatsApp 凭证、Slack/Discord 令牌、`auth-profiles.json` 中的模型/API 密钥，以及使用时的加密 secrets 负载值）。 +1. 轮换 Gateway 网关身份验证（`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`）并重启。 +2. 轮换所有可调用 Gateway 网关机器上的远程客户端 secret（`gateway.remote.token` / `.password`）。 +3. 轮换 provider/API 凭证（WhatsApp 凭证、Slack/Discord token、`auth-profiles.json` 中的模型/API key，以及启用时的加密 secrets 负载值）。 ### 审计 1. 检查 Gateway 网关日志：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`（或 `logging.file`）。 -2. 审查相关转录：`~/.openclaw/agents//sessions/*.jsonl`。 -3. 审查近期配置变更（任何可能扩大访问范围的内容：`gateway.bind`、`gateway.auth`、私信/群组策略、`tools.elevated`、插件变更）。 +2. 查看相关记录：`~/.openclaw/agents//sessions/*.jsonl`。 +3. 查看最近的配置变更（任何可能扩大访问范围的内容：`gateway.bind`、`gateway.auth`、私信/群组策略、`tools.elevated`、插件变更）。 4. 重新运行 `openclaw security audit --deep`，并确认关键发现已解决。 -### 收集报告所需信息 +### 为报告收集材料 -- 时间戳、gateway 主机 OS + OpenClaw 版本 -- 会话转录 + 一小段日志尾部（脱敏后） -- 攻击者发送了什么 + 智能体做了什么 -- Gateway 网关是否暴露到了 loopback 之外（LAN/Tailscale Funnel/Serve） +- 时间戳、gateway 主机操作系统 + OpenClaw 版本 +- 会话记录 + 简短日志尾部（脱敏后） +- 攻击者发送了什么 + 智能体执行了什么 +- Gateway 网关是否暴露到 loopback 之外（LAN/Tailscale Funnel/Serve） -## 使用 detect-secrets 进行密钥扫描 +## 使用 detect-secrets 进行 secret 扫描 -CI 会在 `secrets` job 中运行 `detect-secrets` pre-commit hook。 -推送到 `main` 时始终会扫描所有文件。Pull request 会在有基准提交时使用仅扫描变更文件的 -快速路径，否则回退为全文件扫描。 -如果失败，说明有新的候选项尚未加入 baseline。 +CI 会在 `secrets` 作业中运行 `detect-secrets` pre-commit hook。 +推送到 `main` 时总是执行全文件扫描。Pull request 在有基线提交可用时会走已变更文件 +快速路径，否则回退为全文件扫描。如果失败，说明出现了尚未纳入 baseline 的新候选项。 ### 如果 CI 失败 @@ -1264,25 +1271,25 @@ CI 会在 `secrets` job 中运行 `detect-secrets` pre-commit hook。 2. 了解这些工具： - pre-commit 中的 `detect-secrets` 会使用仓库的 - baseline 和排除规则运行 `detect-secrets-hook`。 - - `detect-secrets audit` 会打开交互式审查界面，用于将 baseline - 中的每一项标记为真实密钥或误报。 -3. 对于真实密钥：轮换/移除它们，然后重新运行扫描以更新 baseline。 -4. 对于误报：运行交互式审查，并将其标记为误报： + baseline 和排除项运行 `detect-secrets-hook`。 + - `detect-secrets audit` 会打开交互式审核界面，将 baseline + 中的每一项标记为真实 secret 或误报。 +3. 对于真实 secret：轮换/删除它们，然后重新运行扫描以更新 baseline。 +4. 对于误报：运行交互式审计并将其标记为误报： ```bash detect-secrets audit .secrets.baseline ``` -5. 如果你需要新增排除规则，请把它们添加到 `.detect-secrets.cfg`，并使用匹配的 `--exclude-files` / `--exclude-lines` 标志重新生成 - baseline（该配置文件仅供参考；detect-secrets 不会自动读取它）。 +5. 如果你需要新增排除规则，请将其添加到 `.detect-secrets.cfg`，并使用匹配的 `--exclude-files` / `--exclude-lines` 标志重新生成 + baseline（该配置文件仅作参考；detect-secrets 不会自动读取它）。 -当 `.secrets.baseline` 反映出预期状态后，再提交更新。 +当更新后的 `.secrets.baseline` 反映了预期状态后，再提交它。 ## 报告安全问题 -在 OpenClaw 中发现了漏洞？请负责任地报告： +在 OpenClaw 中发现漏洞？请负责任地报告： -1. 邮件： [security@openclaw.ai](mailto:security@openclaw.ai) +1. 发送邮件至：[security@openclaw.ai](mailto:security@openclaw.ai) 2. 在修复前不要公开发布 -3. 我们会注明你的贡献（除非你希望匿名） +3. 我们会署名致谢你（除非你希望匿名）