diff --git a/docs/zh-CN/gateway/bonjour.md b/docs/zh-CN/gateway/bonjour.md index ced362c60..0cf73c0cf 100644 --- a/docs/zh-CN/gateway/bonjour.md +++ b/docs/zh-CN/gateway/bonjour.md @@ -1,42 +1,42 @@ --- read_when: - - 在 macOS/iOS 上调试 Bonjour 发现问题 - - 更改 mDNS 服务类型、TXT 记录或发现 UX -summary: Bonjour/mDNS 发现 + 调试（Gateway 网关信标、客户端以及常见故障模式） -title: Bonjour 发现 + - 在 macOS/iOS 上调试 Bonjour 设备发现问题 + - 更改 mDNS 服务类型、TXT 记录或设备发现 UX +summary: Bonjour/mDNS 设备发现 + 调试（Gateway 网关信标、客户端和常见故障模式） +title: Bonjour 设备发现 x-i18n: - generated_at: "2026-04-26T00:16:08Z" + generated_at: "2026-04-26T04:54:50Z" model: gpt-5.4 provider: openai - source_hash: ced3a4a81ab6a4e8c32a33c967ff3e173485c3e644885192012eaca8b81a065f + source_hash: 625d4fbf8fe46938ee42f267d2bdabe6ab9c2766d6b2debc30de3c43f0de724c source_path: gateway/bonjour.md workflow: 15 --- -# Bonjour / mDNS 发现 +# Bonjour / mDNS 设备发现 -OpenClaw 使用 Bonjour（mDNS / DNS-SD）来发现处于活动状态的 Gateway 网关（WebSocket 端点）。 -多播 `local.` 浏览是一种**仅限 LAN 的便利机制**。内置的 `bonjour` -插件负责 LAN 广播，并且默认启用。对于跨网络发现， +OpenClaw 使用 Bonjour（mDNS / DNS‑SD）来发现活跃的 Gateway 网关（WebSocket 端点）。 +多播 `local.` 浏览是一种**仅限局域网的便利机制**。内置的 `bonjour` +插件负责局域网广播，并且默认启用。对于跨网络设备发现， 同一个信标也可以通过已配置的广域 DNS-SD 域发布。 -发现机制仍然是尽力而为，**不能**替代 SSH 或基于 Tailnet 的连接。 +设备发现仍然是尽力而为的机制，**不能**替代 SSH 或基于 Tailnet 的连接能力。 ## 通过 Tailscale 实现广域 Bonjour（单播 DNS-SD） -如果节点和网关位于不同网络，多播 mDNS 将无法跨越该 -边界。你可以通过在 Tailscale 上切换到**单播 DNS-SD** -（“广域 Bonjour”）来保留相同的发现 UX。 +如果节点和网关位于不同网络，多播 mDNS 无法跨越该 +边界。你可以通过在 Tailscale 上切换到**单播 DNS‑SD** +（“广域 Bonjour”）来保留相同的设备发现 UX。 高层步骤： 1. 在网关主机上运行一个 DNS 服务器（可通过 Tailnet 访问）。 -2. 在专用区域下发布 `_openclaw-gw._tcp` 的 DNS-SD 记录 +2. 在专用区域下为 `_openclaw-gw._tcp` 发布 DNS‑SD 记录 （示例：`openclaw.internal.`）。 -3. 配置 Tailscale 的**拆分 DNS**，使客户端（包括 iOS）通过该 - DNS 服务器解析你选择的域。 +3. 配置 Tailscale 的**split DNS**，使客户端（包括 iOS）对你所选域名的解析 + 通过该 DNS 服务器完成。 -OpenClaw 支持任何发现域；`openclaw.internal.` 只是一个示例。 -iOS/Android 节点会同时浏览 `local.` 和你配置的广域域。 +OpenClaw 支持任何设备发现域；`openclaw.internal.` 只是一个示例。 +iOS/Android 节点会同时浏览 `local.` 和你配置的广域域名。 ### Gateway 网关配置（推荐） @@ -56,9 +56,9 @@ openclaw dns setup --apply 这会安装 CoreDNS 并将其配置为： - 仅在网关的 Tailscale 接口上的 53 端口监听 -- 从 `~/.openclaw/dns/.db` 为你选择的域（示例：`openclaw.internal.`）提供服务 +- 从 `~/.openclaw/dns/.db` 为你选择的域提供服务（示例：`openclaw.internal.`） -在连接到 tailnet 的机器上验证： +在已连接 tailnet 的机器上验证： ```bash dns-sd -B _openclaw-gw._tcp openclaw.internal. @@ -70,25 +70,25 @@ dig @ -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short 在 Tailscale 管理控制台中： - 添加一个指向网关 tailnet IP 的名称服务器（UDP/TCP 53）。 -- 添加拆分 DNS，使你的发现域使用该名称服务器。 +- 添加 split DNS，使你的设备发现域使用该名称服务器。 -一旦客户端接受 tailnet DNS，iOS 节点和 CLI 发现功能就可以在你的发现域中浏览 -`_openclaw-gw._tcp`，而无需多播。 +一旦客户端接受 tailnet DNS，iOS 节点和 CLI 设备发现就可以在你的设备发现域中 +浏览 `_openclaw-gw._tcp`，而无需多播。 ### Gateway 网关监听器安全性（推荐） -Gateway 网关 WS 端口（默认 `18789`）默认绑定到 loopback。对于 LAN/tailnet -访问，请显式绑定并保持启用身份验证。 +Gateway 网关 WS 端口（默认 `18789`）默认绑定到 loopback。对于局域网 / tailnet +访问，请显式绑定并保持认证启用。 对于仅 tailnet 的设置： - 在 `~/.openclaw/openclaw.json` 中设置 `gateway.bind: "tailnet"`。 - 重启 Gateway 网关（或重启 macOS 菜单栏应用）。 -## 谁会广播 +## 广播内容 -只有 Gateway 网关会广播 `_openclaw-gw._tcp`。LAN 多播广播由 -内置的 `bonjour` 插件提供；广域 DNS-SD 发布仍由 +只有 Gateway 网关会广播 `_openclaw-gw._tcp`。局域网多播广播 +由内置的 `bonjour` 插件提供；广域 DNS-SD 发布仍由 Gateway 网关负责。 ## 服务类型 @@ -97,7 +97,7 @@ Gateway 网关负责。 ## TXT 键（非机密提示） -Gateway 网关会广播一些小型的非机密提示，以便让 UI 流程更方便： +Gateway 网关会广播一些小型的非机密提示，以便让 UI 流程更加方便： - `role=gateway` - `displayName=` @@ -107,17 +107,17 @@ Gateway 网关会广播一些小型的非机密提示，以便让 UI 流程更 - `gatewayTlsSha256=`（仅当启用 TLS 且指纹可用时） - `canvasPort=`（仅当启用 canvas host 时；当前与 `gatewayPort` 相同） - `transport=gateway` -- `tailnetDns=`（仅限 mDNS 完整模式；当 Tailnet 可用时的可选提示） -- `sshPort=`（仅限 mDNS 完整模式；广域 DNS-SD 可能会省略它） -- `cliPath=`（仅限 mDNS 完整模式；广域 DNS-SD 仍会将其写入作为远程安装提示） +- `tailnetDns=`（仅在 mDNS full mode 下；当 Tailnet 可用时的可选提示） +- `sshPort=`（仅在 mDNS full mode 下；广域 DNS-SD 可能省略它） +- `cliPath=`（仅在 mDNS full mode 下；广域 DNS-SD 仍会将其写入作为远程安装提示） 安全说明： -- Bonjour/mDNS TXT 记录是**未经身份验证的**。客户端不得将 TXT 视为权威路由信息。 +- Bonjour/mDNS TXT 记录是**未经认证的**。客户端不得将 TXT 视为权威路由信息。 - 客户端应使用已解析的服务端点（SRV + A/AAAA）进行路由。仅将 `lanHost`、`tailnetDns`、`gatewayPort` 和 `gatewayTlsSha256` 视为提示。 - SSH 自动目标选择同样应使用已解析的服务主机，而不是仅依赖 TXT 提示。 -- TLS pinning 绝不能允许已广播的 `gatewayTlsSha256` 覆盖先前存储的 pin。 -- iOS/Android 节点应将基于发现的直接连接视为**仅限 TLS**，并在首次信任指纹前要求用户明确确认。 +- TLS pinning 绝不能允许广播的 `gatewayTlsSha256` 覆盖先前已存储的 pin。 +- iOS/Android 节点应将基于设备发现的直接连接视为**仅限 TLS**，并且在首次信任指纹之前要求用户明确确认。 ## 在 macOS 上调试 @@ -129,19 +129,19 @@ Gateway 网关会广播一些小型的非机密提示，以便让 UI 流程更 dns-sd -B _openclaw-gw._tcp local. ``` -- 解析单个实例（替换 ``）： +- 解析一个实例（替换 ``）： ```bash dns-sd -L "" _openclaw-gw._tcp local. ``` -如果浏览可用但解析失败，通常意味着你遇到了 LAN 策略或 +如果浏览正常但解析失败，通常说明你遇到了局域网策略或 mDNS 解析器问题。 ## 在 Gateway 网关日志中调试 -Gateway 网关会写入一个滚动日志文件（启动时会打印为 -`gateway log file: ...`）。请查找 `bonjour:` 行，特别是： +Gateway 网关会写入滚动日志文件（启动时会打印为 +`gateway log file: ...`）。查找 `bonjour:` 行，尤其是： - `bonjour: advertise failed ...` - `bonjour: ... name conflict resolved` / `hostname conflict resolved` @@ -154,43 +154,47 @@ iOS 节点使用 `NWBrowser` 来发现 `_openclaw-gw._tcp`。 要捕获日志： -- 设置 → Gateway 网关 → 高级 → **Discovery Debug Logs** -- 设置 → Gateway 网关 → 高级 → **Discovery Logs** → 复现问题 → **Copy** +- 设置 → Gateway 网关 → 高级 → **Discovery 调试日志** +- 设置 → Gateway 网关 → 高级 → **Discovery 日志** → 复现问题 → **复制** -日志包含浏览器状态转换和结果集变化。 +日志包含浏览器状态转换以及结果集变更。 ## 常见故障模式 -- **Bonjour 无法跨网络工作**：请使用 Tailnet 或 SSH。 +- **Bonjour 无法跨越网络**：请使用 Tailnet 或 SSH。 - **多播被阻止**：某些 Wi‑Fi 网络会禁用 mDNS。 -- **广播器卡在 probing/announcing**：在多播被阻止、 - 容器网桥、WSL 或接口频繁变化的主机上，`ciao` 广播器可能会停留在 +- **广播器卡在 probing/announcing**：存在多播被阻止、 + 容器网桥、WSL 或接口频繁变化的主机时，`ciao` 广播器可能会停留在 未广播状态。OpenClaw 会重试几次，然后为当前 Gateway 网关进程禁用 Bonjour， 而不是无限重启广播器。 -- **睡眠 / 接口变化**：macOS 可能会暂时丢失 mDNS 结果；请重试。 -- **浏览可用但解析失败**：请保持机器名称简洁（避免使用表情符号或 +- **Docker bridge networking**：内置的 Docker Compose 默认通过 + `OPENCLAW_DISABLE_BONJOUR=1` 禁用 Bonjour。仅在 host、 + macvlan 或其他支持 mDNS 的网络中，将其设置为 `0`。 +- **睡眠 / 接口频繁变化**：macOS 可能会临时丢失 mDNS 结果；请重试。 +- **浏览正常但解析失败**：保持机器名称简洁（避免使用表情符号或 标点符号），然后重启 Gateway 网关。服务实例名称派生自 - 主机名，因此过于复杂的名称可能会让某些解析器产生混淆。 + 主机名，因此过于复杂的名称可能会让某些解析器混淆。 -## 转义后的实例名称（`\032`） +## 转义的实例名（`\032`） -Bonjour/DNS-SD 通常会将服务实例名称中的字节转义为十进制 `\DDD` +Bonjour/DNS‑SD 通常会将服务实例名中的字节转义为十进制 `\DDD` 序列（例如空格会变成 `\032`）。 -- 这在协议层面是正常的。 +- 这在协议层面是正常现象。 - UI 应为显示目的进行解码（iOS 使用 `BonjourEscapes.decode`）。 ## 禁用 / 配置 -- `openclaw plugins disable bonjour` 通过禁用内置插件来禁用 LAN 多播广播。 -- `openclaw plugins enable bonjour` 恢复默认的 LAN 发现插件。 -- `OPENCLAW_DISABLE_BONJOUR=1` 在不更改插件配置的情况下禁用 LAN 多播广播；可接受的真值包括 `1`、`true`、`yes` 和 `on`（旧版：`OPENCLAW_DISABLE_BONJOUR`）。 -- `gateway.bind` 位于 `~/.openclaw/openclaw.json` 中，用于控制 Gateway 网关绑定模式。 +- `openclaw plugins disable bonjour` 通过禁用内置插件来禁用局域网多播广播。 +- `openclaw plugins enable bonjour` 恢复默认的局域网设备发现插件。 +- `OPENCLAW_DISABLE_BONJOUR=1` 在不更改插件配置的情况下禁用局域网多播广播；可接受的真值包括 `1`、`true`、`yes` 和 `on`（旧版：`OPENCLAW_DISABLE_BONJOUR`）。 +- 对于 bridge networking，Docker Compose 默认设置 `OPENCLAW_DISABLE_BONJOUR=1`；仅当 mDNS 多播可用时，才使用 `OPENCLAW_DISABLE_BONJOUR=0` 覆盖。 +- `gateway.bind` 在 `~/.openclaw/openclaw.json` 中控制 Gateway 网关绑定模式。 - `OPENCLAW_SSH_PORT` 会在广播 `sshPort` 时覆盖 SSH 端口（旧版：`OPENCLAW_SSH_PORT`）。 -- `OPENCLAW_TAILNET_DNS` 会在启用 mDNS 完整模式时在 TXT 中发布 MagicDNS 提示（旧版：`OPENCLAW_TAILNET_DNS`）。 +- `OPENCLAW_TAILNET_DNS` 会在启用 mDNS full mode 时于 TXT 中发布一个 MagicDNS 提示（旧版：`OPENCLAW_TAILNET_DNS`）。 - `OPENCLAW_CLI_PATH` 会覆盖广播的 CLI 路径（旧版：`OPENCLAW_CLI_PATH`）。 ## 相关文档 - 设备发现策略与传输选择：[设备发现](/zh-CN/gateway/discovery) -- 节点配对 + 批准：[Gateway 网关配对](/zh-CN/gateway/pairing) +- 节点配对 + 审批：[Gateway 网关配对](/zh-CN/gateway/pairing) diff --git a/docs/zh-CN/gateway/discovery.md b/docs/zh-CN/gateway/discovery.md index fe38c6780..2e827102f 100644 --- a/docs/zh-CN/gateway/discovery.md +++ b/docs/zh-CN/gateway/discovery.md @@ -1,66 +1,66 @@ --- read_when: - - 实现或更改 Bonjour 发现/广播 - - 调整远程连接模式（direct 与 SSH） - - 为远程节点设计节点发现 + 配对机制 -summary: 用于查找 Gateway 网关的节点发现与传输协议（Bonjour、Tailscale、SSH） + - 实现或更改 Bonjour 设备发现/通告 + - 调整远程连接模式（直连与 SSH） + - 为远程节点设计设备发现 + 配对机制 +summary: 用于查找 Gateway 网关的节点发现和传输协议（Bonjour、Tailscale、SSH） title: 设备发现 + 传输协议 x-i18n: - generated_at: "2026-04-24T03:15:35Z" + generated_at: "2026-04-26T04:54:49Z" model: gpt-5.4 provider: openai - source_hash: 684e5aeb1f74a90bf8689f8b25830be2c9e497fcdeda390d98f204d7cb4134b8 + source_hash: 615be0f501470772c257beb8e798c522c108b09081a603f44218404277fdf269 source_path: gateway/discovery.md workflow: 15 --- # 设备发现 + 传输协议 -OpenClaw 有两个表面上看起来相似、但实际上彼此独立的问题： +OpenClaw 有两个表面看起来相似、但本质上不同的问题： -1. **操作员远程控制**：macOS 菜单栏应用控制运行在其他地方的 Gateway 网关。 +1. **操作端远程控制**：macOS 菜单栏应用控制运行在其他地方的 Gateway 网关。 2. **节点配对**：iOS/Android（以及未来的节点）查找 Gateway 网关并进行安全配对。 -设计目标是将所有网络发现/广播都保留在 **Node Gateway**（`openclaw gateway`）中，并让客户端（mac 应用、iOS）作为消费者。 +设计目标是将所有网络设备发现/通告都保留在 **Node Gateway**（`openclaw gateway`）中，并让客户端（mac 应用、iOS）作为使用方。 ## 术语 -- **Gateway 网关**：一个单独的长时间运行的 Gateway 网关进程，负责持有状态（会话、配对、节点注册表）并运行渠道。大多数部署在每台主机上使用一个；也支持隔离的多 Gateway 网关部署。 -- **Gateway WS（控制平面）**：默认位于 `127.0.0.1:18789` 的 WebSocket 端点；可通过 `gateway.bind` 绑定到 LAN/tailnet。 -- **Direct WS transport**：面向 LAN/tailnet 的 Gateway WS 端点（无 SSH）。 -- **SSH transport（回退）**：通过 SSH 转发 `127.0.0.1:18789` 来实现远程控制。 -- **Legacy TCP bridge（已移除）**：较旧的节点传输方式（参见 - [Bridge protocol（旧版节点，历史参考）](/zh-CN/gateway/bridge-protocol)）；已不再用于设备发现广播，也不再属于当前构建的一部分。 +- **Gateway 网关**：单个长期运行的 Gateway 网关进程，负责状态（会话、配对、节点注册表）并运行渠道。大多数部署在每台主机上使用一个；也支持隔离的多 Gateway 网关部署。 +- **Gateway WS（控制平面）**：默认位于 `127.0.0.1:18789` 的 WebSocket 端点；可通过 `gateway.bind` 绑定到局域网 / tailnet。 +- **直连 WS 传输**：面向局域网 / tailnet 的 Gateway WS 端点（不使用 SSH）。 +- **SSH 传输（回退方案）**：通过 SSH 转发 `127.0.0.1:18789` 来实现远程控制。 +- **旧版 TCP 桥接（已移除）**：较早的节点传输方式（参见 + [Bridge protocol](/zh-CN/gateway/bridge-protocol)）；不再用于设备发现通告，也不再属于当前构建的一部分。 协议详情： - [Gateway protocol](/zh-CN/gateway/protocol) -- [Bridge protocol（旧版节点，历史参考）](/zh-CN/gateway/bridge-protocol) +- [Bridge protocol（旧版）](/zh-CN/gateway/bridge-protocol) -## 为什么我们同时保留 “direct” 和 SSH +## 为什么我们同时保留“直连”和 SSH -- **Direct WS** 在同一网络和 tailnet 内拥有最佳用户体验： - - 通过 Bonjour 在 LAN 上自动发现 - - 配对令牌 + ACL 由 Gateway 网关持有 - - 不需要 shell 访问；协议暴露面可以保持紧凑且可审计 -- **SSH** 仍然是通用回退方案： - - 只要你有 SSH 访问权限，就能在任何地方工作（即使跨越无关网络） - - 能应对多播/mDNS 问题 - - 除 SSH 外不需要新增入站端口 +- **直连 WS** 在同一网络以及 tailnet 内提供最佳体验： + - 通过 Bonjour 在局域网内自动发现 + - 配对令牌和 ACL 由 Gateway 网关管理 + - 无需 shell 访问；协议暴露面可以保持精简且可审计 +- **SSH** 仍然是通用的回退方案： + - 只要你有 SSH 访问权限，就几乎可以在任何地方使用（即使跨越互不相关的网络） + - 能避开多播 / mDNS 问题 + - 除 SSH 外无需开放新的入站端口 -## 发现输入（客户端如何得知 Gateway 网关的位置） +## 设备发现输入（客户端如何获知 Gateway 网关位置） -### 1）Bonjour / DNS-SD 发现 +### 1) Bonjour / DNS-SD 设备发现 -多播 Bonjour 是尽力而为的，并且不会跨网络工作。OpenClaw 也可以通过已配置的广域 DNS-SD 域浏览同一个 Gateway 网关信标，因此设备发现可覆盖： +多播 Bonjour 是尽力而为的，并且不会跨网络。OpenClaw 也可以通过已配置的广域 DNS-SD 域浏览同一个 Gateway 网关信标，因此设备发现范围可以覆盖： -- 同一 LAN 上的 `local.` -- 用于跨网络发现的已配置单播 DNS-SD 域 +- 同一局域网中的 `local.` +- 用于跨网络设备发现的已配置单播 DNS-SD 域 目标方向： -- **Gateway 网关** 通过 Bonjour 广播其 WS 端点。 -- 客户端浏览并显示“选择一个 Gateway 网关”的列表，然后存储所选端点。 +- **Gateway 网关** 通过 Bonjour 通告它的 WS 端点。 +- 客户端负责浏览并显示“选择一个 Gateway 网关”的列表，然后保存所选端点。 故障排除和信标详情： [Bonjour](/zh-CN/gateway/bonjour)。 @@ -68,54 +68,55 @@ OpenClaw 有两个表面上看起来相似、但实际上彼此独立的问题 - 服务类型： - `_openclaw-gw._tcp`（Gateway 网关传输信标） -- TXT 键（非机密）： +- TXT 键名（非机密）： - `role=gateway` - `transport=gateway` - - `displayName=`（由操作员配置的显示名称） + - `displayName=`（操作端配置的显示名称） - `lanHost=.local` - `gatewayPort=18789`（Gateway WS + HTTP） - - `gatewayTls=1`（仅当启用 TLS 时） - - `gatewayTlsSha256=`（仅当启用 TLS 且指纹可用时） - - `canvasPort=`（canvas 主机端口；当前在启用 canvas 主机时与 `gatewayPort` 相同） - - `tailnetDns=`（可选提示；在 Tailscale 可用时自动检测） - - `sshPort=`（仅 mDNS 完整模式；广域 DNS-SD 可能省略它，此时 SSH 默认仍为 `22`） - - `cliPath=`（仅 mDNS 完整模式；广域 DNS-SD 仍会将其写入为远程安装提示） + - `gatewayTls=1`（仅在启用 TLS 时） + - `gatewayTlsSha256=`（仅在启用 TLS 且指纹可用时） + - `canvasPort=`（canvas host 端口；当前在启用 canvas host 时与 `gatewayPort` 相同） + - `tailnetDns=`（可选提示；当 Tailscale 可用时自动检测） + - `sshPort=`（仅 mDNS 完整模式；广域 DNS-SD 可能省略该项，此时 SSH 默认端口保持为 `22`） + - `cliPath=`（仅 mDNS 完整模式；广域 DNS-SD 仍会将其写入，作为远程安装提示） 安全说明： -- Bonjour/mDNS TXT 记录**未经认证**。客户端必须仅将 TXT 值视为用户体验提示。 -- 路由（主机/端口）应优先使用**解析后的服务端点**（SRV + A/AAAA），而不是 TXT 提供的 `lanHost`、`tailnetDns` 或 `gatewayPort`。 -- TLS pinning 绝不能允许已广播的 `gatewayTlsSha256` 覆盖先前存储的 pin。 -- iOS/Android 节点在所选路由为安全/TLS 路由时，首次存储 pin 前应要求明确的“信任此指纹”确认（带外验证）。 +- Bonjour/mDNS TXT 记录是**未经认证的**。客户端必须仅将 TXT 值视为用户体验提示。 +- 路由（主机 / 端口）应优先使用**已解析的服务端点**（SRV + A/AAAA），而不是 TXT 中提供的 `lanHost`、`tailnetDns` 或 `gatewayPort`。 +- TLS 固定必须绝不允许通告的 `gatewayTlsSha256` 覆盖先前存储的 pin。 +- iOS/Android 节点在所选路由为安全 / 基于 TLS 的情况下，在存储首次 pin 之前，应要求显式确认“信任此指纹”（带外验证）。 -禁用/覆盖： +禁用 / 覆盖： -- `OPENCLAW_DISABLE_BONJOUR=1` 会禁用广播。 +- `OPENCLAW_DISABLE_BONJOUR=1` 禁用通告。 +- Docker Compose 默认使用 `OPENCLAW_DISABLE_BONJOUR=1`，因为 bridge 网络通常无法可靠承载 mDNS 多播；仅在 host、macvlan 或其他支持 mDNS 的网络上使用 `0`。 - `~/.openclaw/openclaw.json` 中的 `gateway.bind` 控制 Gateway 网关绑定模式。 -- `OPENCLAW_SSH_PORT` 会覆盖发出 `sshPort` 时广播的 SSH 端口。 -- `OPENCLAW_TAILNET_DNS` 会发布 `tailnetDns` 提示（MagicDNS）。 -- `OPENCLAW_CLI_PATH` 会覆盖广播的 CLI 路径。 +- `OPENCLAW_SSH_PORT` 会在发出 `sshPort` 时覆盖所通告的 SSH 端口。 +- `OPENCLAW_TAILNET_DNS` 发布 `tailnetDns` 提示（MagicDNS）。 +- `OPENCLAW_CLI_PATH` 覆盖所通告的 CLI 路径。 -### 2）Tailnet（跨网络） +### 2) Tailnet（跨网络） -对于 London/Vienna 这类部署，Bonjour 不会有帮助。推荐的 “direct” 目标是： +对于 London/Vienna 这类部署，Bonjour 不会有帮助。推荐的“直连”目标是： -- Tailscale MagicDNS 名称（首选）或稳定的 tailnet IP。 +- Tailscale MagicDNS 名称（优先），或稳定的 tailnet IP。 -如果 Gateway 网关能够检测到自己运行在 Tailscale 下，它会发布 `tailnetDns` 作为客户端的可选提示（包括广域信标）。 +如果 Gateway 网关能够检测到自己运行在 Tailscale 环境下，它会将 `tailnetDns` 作为客户端的可选提示发布（包括广域信标）。 -macOS 应用现在在 Gateway 网关发现中优先使用 MagicDNS 名称，而不是原始 Tailscale IP。这会在 tailnet IP 发生变化时提升可靠性（例如节点重启后或 CGNAT 重新分配后），因为 MagicDNS 名称会自动解析到当前 IP。 +macOS 应用现在在 Gateway 网关设备发现中优先使用 MagicDNS 名称，而不是原始 Tailscale IP。这样在 tailnet IP 发生变化时（例如节点重启后或 CGNAT 重新分配后）可靠性更高，因为 MagicDNS 名称会自动解析到当前 IP。 -对于移动节点配对，发现提示不会放宽 tailnet/公共路由上的传输安全要求： +对于移动节点配对，设备发现提示不会放宽 tailnet / 公网路由上的传输安全要求： -- iOS/Android 仍然要求安全的首次 tailnet/公共连接路径（`wss://` 或 Tailscale Serve/Funnel）。 -- 发现到的原始 tailnet IP 只是路由提示，并不代表允许使用明文远程 `ws://`。 -- 私有 LAN 直连 `ws://` 仍然受支持。 -- 如果你希望为移动节点使用最简单的 Tailscale 路径，请使用 Tailscale Serve，这样设备发现和设置代码都会解析到同一个安全的 MagicDNS 端点。 +- iOS/Android 仍然要求首次通过安全的 tailnet / 公网连接路径进行连接（`wss://` 或 Tailscale Serve/Funnel）。 +- 发现到的原始 tailnet IP 只是路由提示，并不意味着允许使用明文远程 `ws://`。 +- 私有局域网直连 `ws://` 仍然受支持。 +- 如果你希望为移动节点提供最简单的 Tailscale 路径，请使用 Tailscale Serve，这样设备发现和设置代码都会解析到同一个安全的 MagicDNS 端点。 -### 3）手动 / SSH 目标 +### 3) 手动 / SSH 目标 -当没有 direct 路径（或 direct 已禁用）时，客户端始终可以通过 SSH 转发 loopback Gateway 网关端口来连接。 +当没有直连路径（或直连被禁用）时，客户端始终可以通过转发 loopback Gateway 网关端口来使用 SSH 连接。 参见 [Remote access](/zh-CN/gateway/remote)。 @@ -123,26 +124,26 @@ macOS 应用现在在 Gateway 网关发现中优先使用 MagicDNS 名称，而 推荐的客户端行为： -1. 如果已配置并且可访问某个已配对的 direct 端点，就使用它。 -2. 否则，如果设备发现能在 `local.` 或已配置的广域域名中找到 Gateway 网关，则提供一个一键“Use this gateway”选项，并将其保存为 direct 端点。 -3. 否则，如果配置了 tailnet DNS/IP，则尝试 direct。 - 对于位于 tailnet/公共路由上的移动节点，direct 指的是安全端点，而不是明文远程 `ws://`。 +1. 如果已配置并且可达的已配对直连端点存在，则使用它。 +2. 否则，如果设备发现在 `local.` 或已配置的广域域名中找到 Gateway 网关，则提供一键“使用此 Gateway 网关”的选项，并将其保存为直连端点。 +3. 否则，如果已配置 tailnet DNS / IP，则尝试直连。 + 对于位于 tailnet / 公网路由上的移动节点，直连意味着安全端点，而不是明文远程 `ws://`。 4. 否则，回退到 SSH。 -## 配对 + 凭证（direct transport） +## 配对 + 认证（直连传输） -Gateway 网关是节点/客户端接入的事实来源。 +Gateway 网关是节点 / 客户端接入的唯一真实来源。 -- 配对请求会在 Gateway 网关中创建/批准/拒绝（参见 [Gateway pairing](/zh-CN/gateway/pairing)）。 -- Gateway 网关会强制执行： - - 凭证（token / keypair） - - scopes/ACL（Gateway 网关不是通往所有方法的原始代理） +- 配对请求由 Gateway 网关创建 / 批准 / 拒绝（参见 [Gateway pairing](/zh-CN/gateway/pairing)）。 +- Gateway 网关负责执行： + - 认证（令牌 / 密钥对） + - 作用域 / ACL（Gateway 网关不是通往所有方法的原始代理） - 速率限制 ## 各组件职责 -- **Gateway 网关**：广播发现信标、负责配对决策，并托管 WS 端点。 -- **macOS 应用**：帮助你选择一个 Gateway 网关、显示配对提示，并且仅在回退时使用 SSH。 +- **Gateway 网关**：通告设备发现信标，负责配对决策，并托管 WS 端点。 +- **macOS 应用**：帮助你选择 Gateway 网关，显示配对提示，并仅将 SSH 作为回退方案使用。 - **iOS/Android 节点**：将 Bonjour 浏览作为便利功能，并连接到已配对的 Gateway WS。 ## 相关内容 diff --git a/docs/zh-CN/install/docker.md b/docs/zh-CN/install/docker.md index 5e6f27c35..d884a2ac8 100644 --- a/docs/zh-CN/install/docker.md +++ b/docs/zh-CN/install/docker.md @@ -2,45 +2,45 @@ read_when: - 你想使用容器化的 Gateway 网关，而不是本地安装 - 你正在验证 Docker 流程 -summary: OpenClaw 的可选 Docker 部署与新手引导设置 +summary: OpenClaw 的可选 Docker 安装与新手引导 title: Docker x-i18n: - generated_at: "2026-04-23T22:58:23Z" + generated_at: "2026-04-26T04:54:49Z" model: gpt-5.4 provider: openai - source_hash: ee6bfd2d4ad8b4629c5077d401b8fec36e71b250da3cccdd9ec3cb9c2abbdfc2 + source_hash: 9b2d73da68266946f62feca240bdd94336a3f15e9ca48f0a52209f4ae4a85ffe source_path: install/docker.md workflow: 15 --- -Docker 是**可选**的。只有当你想要一个容器化的 Gateway 网关，或者想验证 Docker 流程时，才需要使用它。 +Docker **是可选的**。只有当你想使用容器化的 Gateway 网关，或验证 Docker 流程时才使用它。 ## Docker 适合我吗？ - **是**：你想要一个隔离的、可随时丢弃的 Gateway 网关环境，或者想在没有本地安装的主机上运行 OpenClaw。 -- **否**：你是在自己的机器上运行，只想获得最快的开发循环。请改用常规安装流程。 -- **沙箱注意事项**：默认沙箱后端在启用沙箱隔离时会使用 Docker，但沙箱隔离默认是关闭的，并且**不需要**让整个 Gateway 网关都运行在 Docker 中。也支持 SSH 和 OpenShell 沙箱后端。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 +- **否**：你正在自己的机器上运行，只想要最快的开发迭代。请改用常规安装流程。 +- **沙箱注意事项**：默认的沙箱后端在启用沙箱隔离时使用 Docker，但沙箱隔离默认是关闭的，且**不**要求整个 Gateway 网关 都在 Docker 中运行。也提供 SSH 和 OpenShell 沙箱后端。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 -## 前置条件 +## 前提条件 - Docker Desktop（或 Docker Engine）+ Docker Compose v2 -- 镜像构建至少需要 2 GB 内存（在 1 GB 主机上，`pnpm install` 可能因 OOM 被杀死并返回退出码 137） +- 镜像构建至少需要 2 GB 内存（在 1 GB 主机上，`pnpm install` 可能因内存不足被终止并返回退出码 137） - 足够的磁盘空间用于镜像和日志 - 如果在 VPS/公网主机上运行，请查看 [网络暴露的安全加固](/zh-CN/gateway/security)， - 特别是 Docker `DOCKER-USER` 防火墙策略。 + 尤其是 Docker `DOCKER-USER` 防火墙策略。 ## 容器化 Gateway 网关 - 在仓库根目录运行设置脚本： + 在仓库根目录运行安装脚本： ```bash ./scripts/docker/setup.sh ``` - 这会在本地构建 Gateway 网关镜像。如果你想改用预构建镜像： + 这会在本地构建 Gateway 网关 镜像。如果要改用预构建镜像： ```bash export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" @@ -54,20 +54,20 @@ Docker 是**可选**的。只有当你想要一个容器化的 Gateway 网关， - 设置脚本会自动运行新手引导。它会： + 安装脚本会自动运行新手引导。它将会： - - 提示输入提供商 API key - - 生成 Gateway 网关 token 并写入 `.env` + - 提示你输入提供商 API 密钥 + - 生成一个 Gateway 网关 令牌并写入 `.env` - 通过 Docker Compose 启动 Gateway 网关 - 在设置过程中，启动前的新手引导和配置写入会直接通过 - `openclaw-gateway` 执行。`openclaw-cli` 用于在 - Gateway 网关容器已经存在之后再运行的命令。 + 在安装过程中，启动前的新手引导和配置写入会直接通过 + `openclaw-gateway` 运行。`openclaw-cli` 用于在 + Gateway 网关 容器已经存在之后执行的命令。 - 在浏览器中打开 `http://127.0.0.1:18789/`，并将已配置的共享密钥粘贴到设置中。设置脚本默认会把 token 写入 `.env`；如果你将容器配置切换为密码凭证，请改用那个密码。 + 在浏览器中打开 `http://127.0.0.1:18789/`，并将已配置的共享密钥粘贴到 Settings 中。安装脚本默认会将令牌写入 `.env`；如果你将容器配置切换为密码认证，请改用该密码。 需要再次查看 URL？ @@ -81,7 +81,7 @@ Docker 是**可选**的。只有当你想要一个容器化的 Gateway 网关， 使用 CLI 容器添加消息渠道： ```bash - # WhatsApp (QR) + # WhatsApp（QR） docker compose run --rm openclaw-cli channels login # Telegram @@ -91,14 +91,14 @@ Docker 是**可选**的。只有当你想要一个容器化的 Gateway 网关， docker compose run --rm openclaw-cli channels add --channel discord --token "" ``` - 文档： [WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord) + 文档：[WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord) ### 手动流程 -如果你希望自行逐步运行，而不是使用设置脚本： +如果你想自己逐步运行，而不是使用安装脚本： ```bash docker build -t openclaw:local -f Dockerfile . @@ -110,44 +110,47 @@ docker compose up -d openclaw-gateway ``` -请在仓库根目录运行 `docker compose`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS` -或 `OPENCLAW_HOME_VOLUME`，设置脚本会写入 `docker-compose.extra.yml`； -请使用 `-f docker-compose.yml -f docker-compose.extra.yml` 将它一并包含。 +请从仓库根目录运行 `docker compose`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS` +或 `OPENCLAW_HOME_VOLUME`，安装脚本会写入 `docker-compose.extra.yml`； +请通过 `-f docker-compose.yml -f docker-compose.extra.yml` 将其包含进来。 -由于 `openclaw-cli` 与 `openclaw-gateway` 共享网络命名空间，它是一个启动后的工具。在执行 `docker compose up -d openclaw-gateway` 之前，请通过带有 -`--no-deps --entrypoint node` 的 `openclaw-gateway` 运行新手引导和设置阶段的配置写入。 +由于 `openclaw-cli` 与 `openclaw-gateway` 共享网络命名空间，它是一个 +启动后工具。在运行 `docker compose up -d openclaw-gateway` 之前，请通过 +`openclaw-gateway` 配合 +`--no-deps --entrypoint node` 来执行新手引导和安装阶段的配置写入。 ### 环境变量 -设置脚本接受以下可选环境变量： +安装脚本接受以下可选环境变量： -| 变量 | 用途 | +| 变量 | 用途 | | ------------------------------ | --------------------------------------------------------------- | -| `OPENCLAW_IMAGE` | 使用远程镜像而不是本地构建 | -| `OPENCLAW_DOCKER_APT_PACKAGES` | 在构建期间安装额外的 apt 软件包（空格分隔） | -| `OPENCLAW_EXTENSIONS` | 在构建时预安装插件依赖（空格分隔名称） | -| `OPENCLAW_EXTRA_MOUNTS` | 额外的主机绑定挂载（逗号分隔，格式为 `source:target[:opts]`） | -| `OPENCLAW_HOME_VOLUME` | 将 `/home/node` 持久化到一个命名 Docker volume 中 | -| `OPENCLAW_SANDBOX` | 选择启用沙箱引导（`1`、`true`、`yes`、`on`） | -| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker socket 路径 | +| `OPENCLAW_IMAGE` | 使用远程镜像，而不是在本地构建 | +| `OPENCLAW_DOCKER_APT_PACKAGES` | 在构建期间安装额外的 apt 软件包（以空格分隔） | +| `OPENCLAW_EXTENSIONS` | 在构建时预安装插件依赖（以空格分隔的名称） | +| `OPENCLAW_EXTRA_MOUNTS` | 额外的主机绑定挂载（以逗号分隔的 `source:target[:opts]`） | +| `OPENCLAW_HOME_VOLUME` | 将 `/home/node` 持久化到一个具名 Docker 卷中 | +| `OPENCLAW_SANDBOX` | 选择启用沙箱引导（`1`、`true`、`yes`、`on`） | +| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker socket 路径 | +| `OPENCLAW_DISABLE_BONJOUR` | 禁用 Bonjour/mDNS 广播（Docker 默认值为 `1`） | ### 健康检查 -容器探针端点（无需凭证）： +容器探针端点（无需认证）： ```bash curl -fsS http://127.0.0.1:18789/healthz # 存活检查 curl -fsS http://127.0.0.1:18789/readyz # 就绪检查 ``` -Docker 镜像内置了一个 `HEALTHCHECK`，会探测 `/healthz`。 +Docker 镜像内置了一个 `HEALTHCHECK`，用于探测 `/healthz`。 如果检查持续失败，Docker 会将容器标记为 `unhealthy`， -编排系统随后可以重启或替换该容器。 +编排系统即可重启或替换该容器。 -带凭证的深度健康快照： +需要认证的深度健康快照： ```bash docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN" @@ -155,51 +158,63 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA ### LAN 与 loopback -`scripts/docker/setup.sh` 默认将 `OPENCLAW_GATEWAY_BIND=lan`，这样通过 Docker 端口发布后，主机可以访问 +`scripts/docker/setup.sh` 默认将 `OPENCLAW_GATEWAY_BIND=lan`，因此借助 Docker 端口发布，主机可访问 `http://127.0.0.1:18789`。 -- `lan`（默认）：主机浏览器和主机 CLI 都可以访问已发布的 Gateway 网关端口。 -- `loopback`：只有容器网络命名空间内部的进程才能直接访问 Gateway 网关。 +- `lan`（默认）：主机浏览器和主机 CLI 都可以访问已发布的 Gateway 网关 端口。 +- `loopback`：只有容器网络命名空间内的进程才能直接访问 + Gateway 网关。 请在 `gateway.bind` 中使用绑定模式值（`lan` / `loopback` / `custom` / -`tailnet` / `auto`），而不要使用诸如 `0.0.0.0` 或 `127.0.0.1` 这样的主机别名。 +`tailnet` / `auto`），不要使用像 `0.0.0.0` 或 `127.0.0.1` 这样的主机别名。 +### Bonjour / mDNS + +Docker bridge 网络通常无法可靠地转发 Bonjour/mDNS 组播 +（`224.0.0.251:5353`）。因此，内置的 Compose 配置默认设置 +`OPENCLAW_DISABLE_BONJOUR=1`，以避免 Gateway 网关 在 bridge 丢失组播流量时崩溃循环或反复重启广播。 + +对于 Docker 主机，请使用已发布的 Gateway 网关 URL、Tailscale 或广域 DNS-SD。 +只有在使用 host 网络、macvlan， +或其他已知支持 mDNS 组播的网络时，才将 `OPENCLAW_DISABLE_BONJOUR=0`。 + ### 存储与持久化 Docker Compose 会将 `OPENCLAW_CONFIG_DIR` 绑定挂载到 `/home/node/.openclaw`，并将 -`OPENCLAW_WORKSPACE_DIR` 绑定挂载到 `/home/node/.openclaw/workspace`，因此这些路径在容器被替换后仍会保留。 +`OPENCLAW_WORKSPACE_DIR` 绑定挂载到 `/home/node/.openclaw/workspace`，因此这些路径 +在容器被替换后仍然会保留。 -这个挂载的配置目录是 OpenClaw 保存以下内容的位置： +这个挂载的配置目录是 OpenClaw 存放以下内容的位置： -- `openclaw.json`：行为配置 -- `agents//agent/auth-profiles.json`：已存储的提供商 OAuth/API-key 凭证 -- `.env`：由环境变量支持的运行时密钥，例如 `OPENCLAW_GATEWAY_TOKEN` +- 用于行为配置的 `openclaw.json` +- 用于已存储提供商 OAuth/API 密钥认证的 `agents//agent/auth-profiles.json` +- 用于基于环境变量的运行时密钥（例如 `OPENCLAW_GATEWAY_TOKEN`）的 `.env` -有关 VM 部署中完整持久化细节，请参见 -[Docker VM 运行时 - 各项内容持久化位置](/zh-CN/install/docker-vm-runtime#what-persists-where)。 +有关 VM 部署的完整持久化细节，请参见 +[Docker VM Runtime - 持久化内容与位置](/zh-CN/install/docker-vm-runtime#what-persists-where)。 -**磁盘增长热点：** 请关注 `media/`、会话 JSONL 文件、`cron/runs/*.jsonl`， +**磁盘增长热点：**请关注 `media/`、会话 JSONL 文件、`cron/runs/*.jsonl`， 以及 `/tmp/openclaw/` 下的滚动文件日志。 -### Shell 助手（可选） +### Shell 辅助工具（可选） -为了更方便地进行日常 Docker 管理，可以安装 `ClawDock`： +为了更方便地进行日常 Docker 管理，请安装 `ClawDock`： ```bash mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ``` -如果你此前是通过旧的 `scripts/shell-helpers/clawdock-helpers.sh` 原始路径安装的 ClawDock，请重新运行上面的安装命令，以便你的本地助手文件跟踪新位置。 +如果你之前是通过旧的原始路径 `scripts/shell-helpers/clawdock-helpers.sh` 安装 ClawDock，请重新运行上面的安装命令，以便让你本地的辅助文件跟踪新位置。 -然后即可使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。运行 -`clawdock-help` 可查看所有命令。 -完整助手指南参见 [ClawDock](/zh-CN/install/clawdock)。 +然后你可以使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。运行 +`clawdock-help` 可查看全部命令。 +完整辅助指南参见 [ClawDock](/zh-CN/install/clawdock)。 - + ```bash export OPENCLAW_SANDBOX=1 ./scripts/docker/setup.sh @@ -213,7 +228,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ./scripts/docker/setup.sh ``` - 脚本只有在沙箱前置条件通过后才会挂载 `docker.sock`。如果 + 只有在沙箱前提条件通过后，脚本才会挂载 `docker.sock`。如果 沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode` 重置为 `off`。 @@ -230,15 +245,15 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - `openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，这样 CLI - 命令就可以通过 `127.0.0.1` 访问 Gateway 网关。请将其视为共享信任边界。compose 配置会为 - `openclaw-cli` 去掉 `NET_RAW`/`NET_ADMIN`，并启用 - `no-new-privileges`。 + `openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，因此 CLI + 命令可以通过 `127.0.0.1` 访问 Gateway 网关。请将此视为共享 + 信任边界。compose 配置会移除 `NET_RAW`/`NET_ADMIN`，并在 + `openclaw-cli` 上启用 `no-new-privileges`。 - + 镜像以 `node`（uid 1000）身份运行。如果你在 - `/home/node/.openclaw` 上看到权限错误，请确保你的主机绑定挂载归属于 uid 1000： + `/home/node/.openclaw` 上看到权限错误，请确保主机绑定挂载归 uid 1000 所有： ```bash sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace @@ -246,8 +261,8 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - - 请按依赖层可缓存的方式组织你的 Dockerfile。这样可以避免在 lockfile 未变化时重复运行 + + 请按顺序组织你的 Dockerfile，使依赖层可以被缓存。这样可以避免在锁文件未变更时重复运行 `pnpm install`： ```dockerfile @@ -270,11 +285,11 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - - 默认镜像以安全优先为原则，并以非 root 的 `node` 身份运行。若想使用功能更完整的容器： + + 默认镜像以安全优先为目标，并以非 root 的 `node` 用户运行。若你需要一个功能更完整的容器： 1. **持久化 `/home/node`**：`export OPENCLAW_HOME_VOLUME="openclaw_home"` - 2. **烘焙系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"` + 2. **预装系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"` 3. **安装 Playwright 浏览器**： ```bash docker compose run --rm openclaw-cli \ @@ -288,34 +303,37 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc 如果你在向导中选择了 OpenAI Codex OAuth，它会打开一个浏览器 URL。在 - Docker 或无头环境中，请复制你最终跳转到的完整重定向 URL，并将其粘贴回向导中以完成凭证配置。 + Docker 或无头环境中，请复制你最终访问到的完整重定向 URL，并将其粘贴回 + 向导中以完成认证。 - 主 Docker 镜像使用 `node:24-bookworm`，并发布 OCI 基础镜像注解， - 包括 `org.opencontainers.image.base.name`、 + 主 Docker 镜像使用 `node:24-bookworm`，并发布 OCI 基础镜像 + 注解，包括 `org.opencontainers.image.base.name`、 `org.opencontainers.image.source` 等。参见 - [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。 + [OCI 镜像注解](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。 ### 在 VPS 上运行？ -请参见 [Hetzner（Docker VPS）](/zh-CN/install/hetzner) 和 -[Docker VM Runtime](/zh-CN/install/docker-vm-runtime)，了解共享 VM 部署步骤， -其中包括二进制预构建、持久化和更新。 +有关共享 VM 部署步骤（包括二进制预构建、持久化和更新），请参见 [Hetzner（Docker VPS）](/zh-CN/install/hetzner) 和 +[Docker VM Runtime](/zh-CN/install/docker-vm-runtime)。 ## 智能体沙箱 -当使用 Docker 后端启用 `agents.defaults.sandbox` 时，Gateway 网关会在隔离的 Docker -容器中运行智能体工具执行（shell、文件读/写等），而 Gateway 网关自身仍运行在主机上。这为不受信任或多租户的智能体会话提供了一道硬隔离墙，而无需将整个 Gateway 网关都容器化。 +当启用 `agents.defaults.sandbox` 并使用 Docker 后端时，Gateway 网关 会在隔离的 Docker +容器内运行智能体工具执行（shell、文件读/写等），而 Gateway 网关 本身仍保留在主机上。这样你就能在不将整个 +Gateway 网关 容器化的情况下，为不受信任或多租户的智能体会话提供一道硬隔离边界。 -沙箱作用域可以是按智能体（默认）、按会话，或共享。每个作用域都会在 `/workspace` 挂载自己的工作区。你还可以配置工具允许/拒绝策略、网络隔离、资源限制和浏览器容器。 +沙箱范围可以按智能体（默认）、按会话，或共享。每种范围 +都会获得一个挂载到 `/workspace` 的独立工作区。你还可以配置 +工具允许/拒绝策略、网络隔离、资源限制和浏览器容器。 -有关完整配置、镜像、安全说明和多智能体配置文件，请参见： +完整配置、镜像、安全说明和多智能体配置文件，请参见： - [沙箱隔离](/zh-CN/gateway/sandboxing) —— 完整的沙箱参考 -- [OpenShell](/zh-CN/gateway/openshell) —— 对沙箱容器的交互式 shell 访问 +- [OpenShell](/zh-CN/gateway/openshell) —— 对沙箱容器进行交互式 shell 访问 - [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools) —— 按智能体覆盖 ### 快速启用 @@ -343,29 +361,29 @@ scripts/sandbox-setup.sh - 请使用 + 使用 [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) 构建沙箱镜像，或将 `agents.defaults.sandbox.docker.image` 设置为你的自定义镜像。 - 容器会按会话按需自动创建。 + 容器会按需为每个会话自动创建。 - 将 `docker.user` 设置为与你挂载工作区所有权匹配的 UID:GID， - 或者对工作区文件夹执行 chown。 + 将 `docker.user` 设置为与挂载工作区所有权匹配的 UID:GID， + 或对工作区文件夹执行 chown。 OpenClaw 使用 `sh -lc`（登录 shell）运行命令，这会加载 - `/etc/profile`，并可能重置 PATH。请设置 `docker.env.PATH` 以预置你的 - 自定义工具路径，或者在你的 Dockerfile 中向 `/etc/profile.d/` 添加脚本。 + `/etc/profile`，并可能重置 PATH。请设置 `docker.env.PATH` 以预先加入你的 + 自定义工具路径，或在你的 Dockerfile 中向 `/etc/profile.d/` 添加脚本。 - + VM 至少需要 2 GB 内存。请使用更大的机器规格后重试。 - 获取一个新的仪表板链接，并批准该浏览器设备： + 获取一个新的 dashboard 链接，并批准浏览器设备： ```bash docker compose run --rm openclaw-cli dashboard --no-open @@ -373,12 +391,12 @@ scripts/sandbox-setup.sh docker compose run --rm openclaw-cli devices approve ``` - 更多详情： [Dashboard](/zh-CN/web/dashboard)、[Devices](/zh-CN/cli/devices)。 + 更多细节： [Dashboard](/zh-CN/web/dashboard)、[Devices](/zh-CN/cli/devices)。 - - 重置 Gateway 网关模式和绑定： + + 重置 Gateway 网关 模式和绑定： ```bash docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]' @@ -392,6 +410,6 @@ scripts/sandbox-setup.sh - [安装概览](/zh-CN/install) — 所有安装方式 - [Podman](/zh-CN/install/podman) — Docker 的 Podman 替代方案 -- [ClawDock](/zh-CN/install/clawdock) — Docker Compose 社区部署方案 -- [更新](/zh-CN/install/updating) — 保持 OpenClaw 为最新版本 -- [配置](/zh-CN/gateway/configuration) — 安装后的 Gateway 网关配置 +- [ClawDock](/zh-CN/install/clawdock) — Docker Compose 社区安装方案 +- [更新](/zh-CN/install/updating) — 让 OpenClaw 保持最新 +- [配置](/zh-CN/gateway/configuration) — 安装后的 Gateway 网关 配置 diff --git a/docs/zh-CN/logging.md b/docs/zh-CN/logging.md index db44fe5bc..1d7c665f8 100644 --- a/docs/zh-CN/logging.md +++ b/docs/zh-CN/logging.md @@ -1,25 +1,25 @@ --- read_when: - - 你需要一份适合初学者的 OpenClaw 日志概览 - - 你想配置日志级别、格式或脱敏处理 + - 你需要一份面向初学者的 OpenClaw 日志概览 + - 你想要配置日志级别、格式或脱敏处理 - 你正在进行故障排除，需要快速找到日志 -summary: 文件日志、控制台输出、CLI 尾部追踪，以及 Control UI 的 Logs 选项卡 +summary: 文件日志、控制台输出、CLI 尾部日志查看，以及 Control UI 的日志标签页 title: 日志 x-i18n: - generated_at: "2026-04-25T23:50:20Z" + generated_at: "2026-04-26T04:54:50Z" model: gpt-5.4 provider: openai - source_hash: 01b139a45937e4a718837ddcf58cfcf6f0230e416942fd6844c27d0c7d71605e + source_hash: 3d4d32e4cdee429221c020fcb9e862e8f7c06f1e7973f36deac2a3476e8c31c8 source_path: logging.md workflow: 15 --- OpenClaw 有两个主要的日志界面： -- 由 Gateway 网关写入的**文件日志**（JSON Lines）。 +- 由 Gateway 网关写入的**文件日志**（JSON 行）。 - 在终端和 Gateway 网关调试 UI 中显示的**控制台输出**。 -Control UI 的 **Logs** 选项卡会尾随 gateway 文件日志。本页会说明日志位于哪里、如何读取，以及如何配置日志级别和格式。 +Control UI 的**日志**标签页会尾随 gateway 文件日志。本页说明日志位于哪里、如何读取，以及如何配置日志级别和格式。 ## 日志位于哪里 @@ -51,9 +51,9 @@ openclaw logs --follow 当前常用选项： -- `--local-time`：以你的本地时区渲染时间戳 +- `--local-time`：以你的本地时区显示时间戳 - `--url ` / `--token ` / `--timeout `：标准 Gateway 网关 RPC 标志 -- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（在这里通过共享客户端层接受） +- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（此处通过共享客户端层接受） 输出模式： @@ -63,18 +63,18 @@ openclaw logs --follow - `--plain`：在 TTY 会话中强制使用纯文本。 - `--no-color`：禁用 ANSI 颜色。 -当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量凭证；如果目标 Gateway 网关需要身份验证，请自行包含 `--token`。 +当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量凭证；如果目标 Gateway 网关需要认证，请自行包含 `--token`。 -在 JSON 模式下，CLI 会输出带有 `type` 标签的对象： +在 JSON 模式下，CLI 会输出带有 `type` 标记的对象： - `meta`：流元数据（文件、游标、大小） - `log`：已解析的日志条目 - `notice`：截断 / 轮转提示 -- `raw`：未解析的原始日志行 +- `raw`：未解析的日志行 -如果 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式 `--url` 目标不会使用此回退。 +如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式 `--url` 目标不会使用此回退。 -如果 Gateway 网关不可达，CLI 会打印一条简短提示，建议运行： +如果 Gateway 网关无法访问，CLI 会打印一条简短提示，建议运行： ```bash openclaw doctor @@ -82,8 +82,7 @@ openclaw doctor ### Control UI（网页） -Control UI 的 **Logs** 选项卡会使用 `logs.tail` 尾随同一个文件。 -有关如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。 +Control UI 的**日志**标签页会使用 `logs.tail` 尾随同一个文件。有关如何打开它，请参阅 [/web/control-ui](/zh-CN/web/control-ui)。 ### 仅渠道日志 @@ -101,7 +100,7 @@ openclaw channels logs --channel whatsapp ### 控制台输出 -控制台日志是**感知 TTY** 的，并针对可读性进行了格式化： +控制台日志会**感知 TTY**，并以便于阅读的方式格式化： - 子系统前缀（例如 `gateway/channels/whatsapp`） - 级别着色（info/warn/error） @@ -113,9 +112,9 @@ openclaw channels logs --channel whatsapp `openclaw gateway` 还提供用于 RPC 流量的 WebSocket 协议日志： -- 普通模式：仅记录重要结果（错误、解析错误、慢调用） -- `--verbose`：记录所有请求 / 响应流量 -- `--ws-log auto|compact|full`：选择详细输出的渲染样式 +- 普通模式：仅记录值得关注的结果（错误、解析错误、慢调用） +- `--verbose`：记录所有请求/响应流量 +- `--ws-log auto|compact|full`：选择详细日志的渲染样式 - `--compact`：`--ws-log compact` 的别名 示例： @@ -128,7 +127,7 @@ openclaw gateway --verbose --ws-log full ## 配置日志 -所有日志配置都位于 `~/.openclaw/openclaw.json` 的 `logging` 下。 +所有日志配置都位于 `~/.openclaw/openclaw.json` 中的 `logging` 下。 ```json { @@ -148,9 +147,9 @@ openclaw gateway --verbose --ws-log full - `logging.level`：**文件日志**（JSONL）级别。 - `logging.consoleLevel`：**控制台**详细程度级别。 -你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两者（例如 `OPENCLAW_LOG_LEVEL=debug`）。该环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅为单次运行提高详细程度。你也可以传递全局 CLI 选项 **`--log-level `**（例如，`openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。 +你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两个设置（例如 `OPENCLAW_LOG_LEVEL=debug`）。该环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅针对单次运行提高详细程度。你也可以传入全局 CLI 选项 **`--log-level `**（例如，`openclaw --log-level debug gateway run`），它会在该命令中覆盖环境变量。 -`--verbose` 仅影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。 +`--verbose` 只影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。 ### 控制台样式 @@ -162,27 +161,25 @@ openclaw gateway --verbose --ws-log full ### 脱敏 -工具摘要可以在输出到控制台之前对敏感令牌进行脱敏： +工具摘要可以在输出到控制台之前，对敏感令牌进行脱敏： - `logging.redactSensitive`：`off` | `tools`（默认：`tools`） - `logging.redactPatterns`：用于覆盖默认集合的正则表达式字符串列表 -脱敏仅影响**控制台输出**，不会修改文件日志。 +脱敏会在日志输出目标处应用于**控制台输出**、**路由到 stderr 的控制台诊断信息**以及**文件日志**。文件日志仍保持为 JSONL，但匹配的秘密值会在写入磁盘前被屏蔽。 -## Diagnostics 和 OpenTelemetry +## 诊断与 OpenTelemetry -Diagnostics 是用于模型运行和消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志——而是为指标、追踪和导出器提供数据。无论你是否导出它们，事件都会在进程内发出。 +诊断是用于模型运行和消息流遥测（webhook、队列、会话状态）的结构化、机器可读事件。它们**不会**替代日志——它们用于提供指标、追踪和导出器。无论你是否导出它们，事件都会在进程内发出。 -两个相邻的界面： +相邻的两个界面： - **OpenTelemetry 导出**——通过 OTLP/HTTP 将指标、追踪和日志发送到任何兼容 OpenTelemetry 的收集器或后端（Grafana、Datadog、Honeycomb、New Relic、Tempo 等）。完整配置、信号目录、指标 / span 名称、环境变量和隐私模型位于专门页面： [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 -- **Diagnostics 标志**——有针对性的调试日志标志，可将额外日志路由到 - `logging.file`，而无需提高 `logging.level`。这些标志不区分大小写，并支持通配符（`telegram.*`、`*`）。可在 `diagnostics.flags` - 下配置，或通过 `OPENCLAW_DIAGNOSTICS=...` 环境变量覆盖。完整指南： - [Diagnostics 标志](/zh-CN/diagnostics/flags)。 +- **诊断标志**——将额外日志定向写入 `logging.file` 的定向调试日志标志，而无需提高 `logging.level`。标志不区分大小写，并支持通配符（`telegram.*`、`*`）。可在 `diagnostics.flags` 下配置，或通过 `OPENCLAW_DIAGNOSTICS=...` 环境变量覆盖。完整指南： + [诊断标志](/zh-CN/diagnostics/flags)。 -若要为插件或自定义接收端启用 diagnostics 事件，而不进行 OTLP 导出： +要在不使用 OTLP 导出的情况下，为插件或自定义输出目标启用诊断事件： ```json5 { @@ -190,17 +187,17 @@ Diagnostics 是用于模型运行和消息流遥测（webhook、排队、会话 } ``` -有关导出到收集器的 OTLP，请参见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 +有关导出到收集器的 OTLP，请参阅 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 ## 故障排除提示 -- **Gateway 网关不可达？** 先运行 `openclaw doctor`。 -- **日志为空？** 检查 Gateway 网关是否正在运行，并且正在写入 `logging.file` 中的文件路径。 -- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace`，然后重试。 +- **Gateway 网关无法访问？** 先运行 `openclaw doctor`。 +- **日志为空？** 检查 Gateway 网关是否正在运行，并正在写入 `logging.file` 中的文件路径。 +- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 后重试。 ## 相关内容 - [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry) — OTLP/HTTP 导出、指标 / span 目录、隐私模型 -- [Diagnostics 标志](/zh-CN/diagnostics/flags) — 有针对性的调试日志标志 +- [诊断标志](/zh-CN/diagnostics/flags) — 定向调试日志标志 - [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获 - [配置参考](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考