chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
409d687625
commit
650b2ea20b
@ -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/<domain>.db` 为你选择的域（示例：`openclaw.internal.`）提供服务
|
||||
- 从 `~/.openclaw/dns/<domain>.db` 为你选择的域提供服务（示例：`openclaw.internal.`）
|
||||
|
||||
在连接到 tailnet 的机器上验证：
|
||||
在已连接 tailnet 的机器上验证：
|
||||
|
||||
```bash
|
||||
dns-sd -B _openclaw-gw._tcp openclaw.internal.
|
||||
@ -70,25 +70,25 @@ dig @<TAILNET_IPV4> -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=<friendly name>`
|
||||
@ -107,17 +107,17 @@ Gateway 网关会广播一些小型的非机密提示，以便让 UI 流程更
|
||||
- `gatewayTlsSha256=<sha256>`（仅当启用 TLS 且指纹可用时）
|
||||
- `canvasPort=<port>`（仅当启用 canvas host 时；当前与 `gatewayPort` 相同）
|
||||
- `transport=gateway`
|
||||
- `tailnetDns=<magicdns>`（仅限 mDNS 完整模式；当 Tailnet 可用时的可选提示）
|
||||
- `sshPort=<port>`（仅限 mDNS 完整模式；广域 DNS-SD 可能会省略它）
|
||||
- `cliPath=<path>`（仅限 mDNS 完整模式；广域 DNS-SD 仍会将其写入作为远程安装提示）
|
||||
- `tailnetDns=<magicdns>`（仅在 mDNS full mode 下；当 Tailnet 可用时的可选提示）
|
||||
- `sshPort=<port>`（仅在 mDNS full mode 下；广域 DNS-SD 可能省略它）
|
||||
- `cliPath=<path>`（仅在 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.
|
||||
```
|
||||
|
||||
- 解析单个实例（替换 `<instance>`）：
|
||||
- 解析一个实例（替换 `<instance>`）：
|
||||
|
||||
```bash
|
||||
dns-sd -L "<instance>" _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)
|
||||
|
||||
@ -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=<friendly name>`（由操作员配置的显示名称）
|
||||
- `displayName=<friendly name>`（操作端配置的显示名称）
|
||||
- `lanHost=<hostname>.local`
|
||||
- `gatewayPort=18789`（Gateway WS + HTTP）
|
||||
- `gatewayTls=1`（仅当启用 TLS 时）
|
||||
- `gatewayTlsSha256=<sha256>`（仅当启用 TLS 且指纹可用时）
|
||||
- `canvasPort=<port>`（canvas 主机端口；当前在启用 canvas 主机时与 `gatewayPort` 相同）
|
||||
- `tailnetDns=<magicdns>`（可选提示；在 Tailscale 可用时自动检测）
|
||||
- `sshPort=<port>`（仅 mDNS 完整模式；广域 DNS-SD 可能省略它，此时 SSH 默认仍为 `22`）
|
||||
- `cliPath=<path>`（仅 mDNS 完整模式；广域 DNS-SD 仍会将其写入为远程安装提示）
|
||||
- `gatewayTls=1`（仅在启用 TLS 时）
|
||||
- `gatewayTlsSha256=<sha256>`（仅在启用 TLS 且指纹可用时）
|
||||
- `canvasPort=<port>`（canvas host 端口；当前在启用 canvas host 时与 `gatewayPort` 相同）
|
||||
- `tailnetDns=<magicdns>`（可选提示；当 Tailscale 可用时自动检测）
|
||||
- `sshPort=<port>`（仅 mDNS 完整模式；广域 DNS-SD 可能省略该项，此时 SSH 默认端口保持为 `22`）
|
||||
- `cliPath=<path>`（仅 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。
|
||||
|
||||
## 相关内容
|
||||
|
||||
@ -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 网关
|
||||
|
||||
<Steps>
|
||||
<Step title="构建镜像">
|
||||
在仓库根目录运行设置脚本：
|
||||
在仓库根目录运行安装脚本：
|
||||
|
||||
```bash
|
||||
./scripts/docker/setup.sh
|
||||
```
|
||||
|
||||
这会在本地构建 Gateway 网关镜像。如果你想改用预构建镜像：
|
||||
这会在本地构建 Gateway 网关 镜像。如果要改用预构建镜像：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
|
||||
@ -54,20 +54,20 @@ Docker 是**可选**的。只有当你想要一个容器化的 Gateway 网关，
|
||||
</Step>
|
||||
|
||||
<Step title="完成新手引导">
|
||||
设置脚本会自动运行新手引导。它会：
|
||||
安装脚本会自动运行新手引导。它将会：
|
||||
|
||||
- 提示输入提供商 API key
|
||||
- 生成 Gateway 网关 token 并写入 `.env`
|
||||
- 提示你输入提供商 API 密钥
|
||||
- 生成一个 Gateway 网关 令牌并写入 `.env`
|
||||
- 通过 Docker Compose 启动 Gateway 网关
|
||||
|
||||
在设置过程中，启动前的新手引导和配置写入会直接通过
|
||||
`openclaw-gateway` 执行。`openclaw-cli` 用于在
|
||||
Gateway 网关容器已经存在之后再运行的命令。
|
||||
在安装过程中，启动前的新手引导和配置写入会直接通过
|
||||
`openclaw-gateway` 运行。`openclaw-cli` 用于在
|
||||
Gateway 网关 容器已经存在之后执行的命令。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="打开 Control UI">
|
||||
在浏览器中打开 `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 "<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)
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 手动流程
|
||||
|
||||
如果你希望自行逐步运行，而不是使用设置脚本：
|
||||
如果你想自己逐步运行，而不是使用安装脚本：
|
||||
|
||||
```bash
|
||||
docker build -t openclaw:local -f Dockerfile .
|
||||
@ -110,44 +110,47 @@ docker compose up -d openclaw-gateway
|
||||
```
|
||||
|
||||
<Note>
|
||||
请在仓库根目录运行 `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` 将其包含进来。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
由于 `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` 来执行新手引导和安装阶段的配置写入。
|
||||
</Note>
|
||||
|
||||
### 环境变量
|
||||
|
||||
设置脚本接受以下可选环境变量：
|
||||
安装脚本接受以下可选环境变量：
|
||||
|
||||
| 变量 | 用途 |
|
||||
| 变量 | 用途 |
|
||||
| ------------------------------ | --------------------------------------------------------------- |
|
||||
| `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 网关。
|
||||
|
||||
<Note>
|
||||
请在 `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` 这样的主机别名。
|
||||
</Note>
|
||||
|
||||
### 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/<agentId>/agent/auth-profiles.json`：已存储的提供商 OAuth/API-key 凭证
|
||||
- `.env`：由环境变量支持的运行时密钥，例如 `OPENCLAW_GATEWAY_TOKEN`
|
||||
- 用于行为配置的 `openclaw.json`
|
||||
- 用于已存储提供商 OAuth/API 密钥认证的 `agents/<agentId>/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)。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="为 Docker Gateway 网关启用智能体沙箱">
|
||||
<Accordion title="为 Docker Gateway 网关 启用智能体沙箱">
|
||||
```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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="共享网络安全说明">
|
||||
`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`。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="权限和 EACCES">
|
||||
<Accordion title="权限与 EACCES">
|
||||
镜像以 `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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="更快的重建">
|
||||
请按依赖层可缓存的方式组织你的 Dockerfile。这样可以避免在 lockfile 未变化时重复运行
|
||||
<Accordion title="更快的重新构建">
|
||||
请按顺序组织你的 Dockerfile，使依赖层可以被缓存。这样可以避免在锁文件未变更时重复运行
|
||||
`pnpm install`：
|
||||
|
||||
```dockerfile
|
||||
@ -270,11 +285,11 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="高级用户容器选项">
|
||||
默认镜像以安全优先为原则，并以非 root 的 `node` 身份运行。若想使用功能更完整的容器：
|
||||
<Accordion title="高级容器选项">
|
||||
默认镜像以安全优先为目标，并以非 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
|
||||
|
||||
<Accordion title="OpenAI Codex OAuth（无头 Docker）">
|
||||
如果你在向导中选择了 OpenAI Codex OAuth，它会打开一个浏览器 URL。在
|
||||
Docker 或无头环境中，请复制你最终跳转到的完整重定向 URL，并将其粘贴回向导中以完成凭证配置。
|
||||
Docker 或无头环境中，请复制你最终访问到的完整重定向 URL，并将其粘贴回
|
||||
向导中以完成认证。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="基础镜像元数据">
|
||||
主 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)。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 在 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
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="镜像缺失或沙箱容器无法启动">
|
||||
请使用
|
||||
使用
|
||||
[`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh)
|
||||
构建沙箱镜像，或将 `agents.defaults.sandbox.docker.image` 设置为你的自定义镜像。
|
||||
容器会按会话按需自动创建。
|
||||
容器会按需为每个会话自动创建。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="沙箱中的权限错误">
|
||||
将 `docker.user` 设置为与你挂载工作区所有权匹配的 UID:GID，
|
||||
或者对工作区文件夹执行 chown。
|
||||
将 `docker.user` 设置为与挂载工作区所有权匹配的 UID:GID，
|
||||
或对工作区文件夹执行 chown。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="在沙箱中找不到自定义工具">
|
||||
OpenClaw 使用 `sh -lc`（登录 shell）运行命令，这会加载
|
||||
`/etc/profile`，并可能重置 PATH。请设置 `docker.env.PATH` 以预置你的
|
||||
自定义工具路径，或者在你的 Dockerfile 中向 `/etc/profile.d/` 添加脚本。
|
||||
`/etc/profile`，并可能重置 PATH。请设置 `docker.env.PATH` 以预先加入你的
|
||||
自定义工具路径，或在你的 Dockerfile 中向 `/etc/profile.d/` 添加脚本。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="镜像构建期间被 OOM 杀死（退出码 137）">
|
||||
<Accordion title="镜像构建期间因 OOM 被终止（退出码 137）">
|
||||
VM 至少需要 2 GB 内存。请使用更大的机器规格后重试。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Control UI 中显示 Unauthorized 或需要配对">
|
||||
获取一个新的仪表板链接，并批准该浏览器设备：
|
||||
获取一个新的 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 <requestId>
|
||||
```
|
||||
|
||||
更多详情： [Dashboard](/zh-CN/web/dashboard)、[Devices](/zh-CN/cli/devices)。
|
||||
更多细节： [Dashboard](/zh-CN/web/dashboard)、[Devices](/zh-CN/cli/devices)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gateway 网关目标显示为 ws://172.x.x.x，或从 Docker CLI 出现配对错误">
|
||||
重置 Gateway 网关模式和绑定：
|
||||
<Accordion title="Gateway 网关 目标显示 ws://172.x.x.x，或从 Docker CLI 出现配对错误">
|
||||
重置 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 网关 配置
|
||||
|
||||
@ -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 <url>` / `--token <token>` / `--timeout <ms>`：标准 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 <level>`**（例如，`openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。
|
||||
你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两个设置（例如 `OPENCLAW_LOG_LEVEL=debug`）。该环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅针对单次运行提高详细程度。你也可以传入全局 CLI 选项 **`--log-level <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.*` 字段参考
|
||||
|
||||
Loading…
Reference in New Issue
Block a user