farcasclaudiu/openclaw
1
0
Fork 0
mirror of https://github.com/farcasclaudiu/openclaw.git synced 2026-06-29 15:01:48 +03:00
Code Issues Packages Projects Releases Wiki Activity

Docs: normalize zh-CN terminology + tone

Browse Source 
What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording
Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style
Tests: pnpm docs:build
This commit is contained in:
Josh Palmer
2026-02-02 15:46:45 +01:00
parent 2b1f68c928
commit 5676a6b38d
237 changed files with 2322 additions and 2337 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh-CN/gateway/index.md
+40 -40
View File
@@ -1,8 +1,8 @@
---
read_when:
- 运行或调试 Gateway 进程时
summary: Gateway 服务的运维手册、生命周期与操作指南
title: Gateway 运维手册
- 运行或调试 Gateway网关进程时
summary: Gateway网关服务的运维手册、生命周期与操作指南
title: Gateway网关运维手册
x-i18n:
generated_at: "2026-02-01T20:40:09Z"
model: claude-opus-4-5
@@ -12,7 +12,7 @@ x-i18n:
workflow: 14
---
# Gateway 服务运维手册
# Gateway网关服务运维手册
最后更新：2025-12-09
@@ -46,11 +46,11 @@ pnpm gateway:watch
- 默认在 `canvasHost.port`（默认 `18793`）启动 Canvas 文件服务器，从 `~/.openclaw/workspace/canvas` 提供 `http://<gateway-host>:18793/__openclaw__/canvas/` 服务。通过 `canvasHost.enabled=false` 或 `OPENCLAW_SKIP_CANVAS_HOST=1` 禁用。
- 日志输出到标准输出；使用 launchd/systemd 保持进程存活并轮转日志。
- 传入 `--verbose` 可在故障排除时将调试日志（握手、请求/响应、事件）从日志文件镜像到标准输出。
- `--force` 使用 `lsof` 查找所选端口上的监听进程，发送 SIGTERM，记录被终止的进程，然后启动 Gateway（如果缺少 `lsof` 则快速失败）。
- `--force` 使用 `lsof` 查找所选端口上的监听进程，发送 SIGTERM，记录被终止的进程，然后启动 Gateway网关（如果缺少 `lsof` 则快速失败）。
- 如果在 supervisor（launchd/systemd/mac app 子进程模式）下运行，停止/重启通常发送 **SIGTERM**；旧版本可能将其显示为 `pnpm` `ELIFECYCLE` 退出码 **143**（SIGTERM），这是正常关闭，不是崩溃。
- **SIGUSR1** 在授权时触发进程内重启（Gateway 工具/配置应用/更新，或启用 `commands.restart` 以进行手动重启）。
- 默认需要 Gateway 认证：设置 `gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）或 `gateway.auth.password`。客户端必须发送 `connect.params.auth.token/password`，除非使用 Tailscale Serve 身份。
- 向导现在默认生成令牌，即使在回环地址上也是如此。
- **SIGUSR1** 在授权时触发进程内重启（Gateway网关工具/配置应用/更新，或启用 `commands.restart` 以进行手动重启）。
- 默认需要 Gateway网关认证：设置 `gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）或 `gateway.auth.password`。客户端必须发送 `connect.params.auth.token/password`，除非使用 Tailscale Serve 身份。
- 向导现在默认生成令牌，即使在 local loopback 上也是如此。
- 端口优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > 默认 `18789`。
## 远程访问
@@ -62,17 +62,17 @@ pnpm gateway:watch
- 客户端通过隧道连接到 `ws://127.0.0.1:18789`。
- 如果配置了令牌，客户端即使通过隧道也必须在 `connect.params.auth.token` 中包含令牌。
## 多个 Gateway（同一主机）
## 多个 Gateway网关（同一主机）
通常不需要：一个 Gateway 可以服务多个消息渠道和智能体。仅在需要冗余或严格隔离（例如：救援机器人）时使用多个 Gateway。
通常不需要：一个 Gateway网关可以服务多个消息渠道和智能体。仅在需要冗余或严格隔离（例如：救援机器人）时使用多个 Gateway网关。
如果隔离状态 + 配置并使用唯一端口，则支持多实例。完整指南：[多 Gateway](/gateway/multiple-gateways)。
如果隔离状态 + 配置并使用唯一端口，则支持多实例。完整指南：[多 Gateway网关](/gateway/multiple-gateways)。
服务名称是配置文件感知的：
- macOS：`bot.molt.<profile>`（旧版 `com.openclaw.*` 可能仍然存在）
- Linux：`openclaw-gateway-<profile>.service`
- Windows：`OpenClaw Gateway (<profile>)`
- Windows：`OpenClaw Gateway网关 (<profile>)`
安装元数据嵌入在服务配置中：
@@ -80,7 +80,7 @@ pnpm gateway:watch
- `OPENCLAW_SERVICE_KIND=gateway`
- `OPENCLAW_SERVICE_VERSION=<version>`
救援机器人模式：保持第二个 Gateway 隔离，使用独立的配置文件、状态目录、工作区和基础端口间距。完整指南：[救援机器人指南](/gateway/multiple-gateways#rescue-bot-guide)。
救援机器人模式：保持第二个 Gateway网关隔离，使用独立的配置文件、状态目录、工作区和基础端口间距。完整指南：[救援机器人指南](/gateway/multiple-gateways#rescue-bot-guide)。
### 开发配置文件（`--dev`）
@@ -98,15 +98,15 @@ openclaw --dev health
- `OPENCLAW_STATE_DIR=~/.openclaw-dev`
- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
- `OPENCLAW_GATEWAY_PORT=19001`（Gateway WS + HTTP）
- 浏览器控制服务端口 = `19003`（派生：`gateway.port+2`，仅回环地址）
- `OPENCLAW_GATEWAY_PORT=19001`（Gateway网关 WS + HTTP）
- 浏览器控制服务端口 = `19003`（派生：`gateway.port+2`，仅 local loopback）
- `canvasHost.port=19005`（派生：`gateway.port+4`）
- 在 `--dev` 下运行 `setup`/`onboard` 时，`agents.defaults.workspace` 默认变为 `~/.openclaw/workspace-dev`。
派生端口（经验规则）：
- 基础端口 = `gateway.port`（或 `OPENCLAW_GATEWAY_PORT` / `--port`）
- 浏览器控制服务端口 = 基础端口 + 2（仅回环地址）
- 浏览器控制服务端口 = 基础端口 + 2（仅 local loopback）
- `canvasHost.port = 基础端口 + 4`（或 `OPENCLAW_CANVAS_HOST_PORT` / 配置覆盖）
- 浏览器配置文件 CDP 端口从 `browser.controlPort + 9 .. + 108` 自动分配（按配置文件持久化）。
@@ -134,9 +134,9 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b opencla
## 协议（运维视角）
- 完整文档：[Gateway 协议](/gateway/protocol) 和 [Bridge 协议（旧版）](/gateway/bridge-protocol)。
- 完整文档：[Gateway网关协议](/gateway/protocol) 和 [Bridge 协议（旧版）](/gateway/bridge-protocol)。
- 客户端必须发送的第一帧：`req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }`。
- Gateway 回复 `res {type:"res", id, ok:true, payload:hello-ok }`（或 `ok:false` 附带错误信息，然后关闭连接）。
- Gateway网关回复 `res {type:"res", id, ok:true, payload:hello-ok }`（或 `ok:false` 附带错误信息，然后关闭连接）。
- 握手完成后：
- 请求：`{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
- 事件：`{type:"event", event, payload, seq?, stateVersion?}`
@@ -163,12 +163,12 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b opencla
- `agent` — 来自智能体运行的流式工具/输出事件（带 seq 标签）。
- `presence` — 在线状态更新（带 stateVersion 的增量）推送给所有已连接的客户端。
- `tick` — 定期心跳/空操作，确认活跃性。
- `shutdown` — Gateway 正在退出；负载包含 `reason` 和可选的 `restartExpectedMs`。客户端应重新连接。
- `shutdown` — Gateway网关正在退出；负载包含 `reason` 和可选的 `restartExpectedMs`。客户端应重新连接。
## WebChat 集成
- WebChat 是原生 SwiftUI UI，直接通过 Gateway WebSocket 进行历史记录、发送、中止和事件交互。
- 远程使用通过相同的 SSH/Tailscale 隧道；如果配置了 Gateway 令牌，客户端在 `connect` 时包含它。
- WebChat 是原生 SwiftUI UI，直接通过 Gateway网关 WebSocket 进行历史记录、发送、中止和事件交互。
- 远程使用通过相同的 SSH/Tailscale 隧道；如果配置了 Gateway网关令牌，客户端在 `connect` 时包含它。
- macOS 应用通过单个 WS（共享连接）连接；它从初始快照中获取在线状态，并监听 `presence` 事件以更新 UI。
## 类型与验证
@@ -191,11 +191,11 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b opencla
- `NOT_LINKED` — WhatsApp 未认证。
- `AGENT_TIMEOUT` — 智能体未在配置的截止时间内响应。
- `INVALID_REQUEST` — schema/参数验证失败。
- `UNAVAILABLE` — Gateway 正在关闭或依赖不可用。
- `UNAVAILABLE` — Gateway网关正在关闭或依赖不可用。
## 心跳行为
- `tick` 事件（或 WS ping/pong）会定期发出，以便客户端在没有流量时也能知道 Gateway 处于活跃状态。
- `tick` 事件（或 WS ping/pong）会定期发出，以便客户端在没有流量时也能知道 Gateway网关处于活跃状态。
- 发送/智能体确认仍为独立响应；不要将 tick 用于发送。
## 重放/间隙
@@ -215,9 +215,9 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b opencla
（或 `bot.molt.<profile>.plist`；旧版 `com.openclaw.*` 会被清理）。
- `openclaw doctor` 审计 LaunchAgent 配置，并可将其更新为当前推荐的默认值。
## Gateway 服务管理（CLI）
## Gateway网关服务管理（CLI）
使用 Gateway CLI 进行安装/启动/停止/重启/状态查询：
使用 Gateway网关 CLI 进行安装/启动/停止/重启/状态查询：
```bash
openclaw gateway status
@@ -229,22 +229,22 @@ openclaw logs --follow
注意事项：
- `gateway status` 默认使用服务解析的端口/配置探测 Gateway RPC（可通过 `--url` 覆盖）。
- `gateway status` 默认使用服务解析的端口/配置探测 Gateway网关 RPC（可通过 `--url` 覆盖）。
- `gateway status --deep` 添加系统级扫描（LaunchDaemons/系统单元）。
- `gateway status --no-probe` 跳过 RPC 探测（在网络不可用时有用）。
- `gateway status --json` 输出稳定，适用于脚本。
- `gateway status` 将 **supervisor 运行时**（launchd/systemd 运行中）与 **RPC 可达性**（WS 连接 + 状态 RPC）分开报告。
- `gateway status` 打印配置路径 + 探测目标，以避免"localhost vs LAN 绑定"混淆和配置文件不匹配。
- `gateway status` 在服务看起来正在运行但端口已关闭时包含最后一条 Gateway 错误行。
- `logs` 通过 RPC 跟踪 Gateway 文件日志（无需手动 `tail`/`grep`）。
- 如果检测到其他类似 Gateway 的服务，CLI 会发出警告，除非它们是 OpenClaw 配置文件服务。
我们仍建议大多数场景下**每台机器一个 Gateway**；使用隔离的配置文件/端口实现冗余或救援机器人。参见 [多 Gateway](/gateway/multiple-gateways)。
- `gateway status` 在服务看起来正在运行但端口已关闭时包含最后一条 Gateway网关错误行。
- `logs` 通过 RPC 跟踪 Gateway网关文件日志（无需手动 `tail`/`grep`）。
- 如果检测到其他类似 Gateway网关的服务，CLI 会发出警告，除非它们是 OpenClaw 配置文件服务。
我们仍建议大多数场景下**每台机器一个 Gateway网关**；使用隔离的配置文件/端口实现冗余或救援机器人。参见 [多 Gateway网关](/gateway/multiple-gateways)。
- 清理：`openclaw gateway uninstall`（当前服务）和 `openclaw doctor`（旧版迁移）。
- `gateway install` 在已安装时为空操作；使用 `openclaw gateway install --force` 重新安装（配置文件/环境/路径变更）。
捆绑的 Mac 应用：
- OpenClaw.app 可以捆绑一个基于 Node 的 Gateway 中继，并安装按用户的 LaunchAgent，标签为
- OpenClaw.app 可以捆绑一个基于 Node 的 Gateway网关中继，并安装按用户的 LaunchAgent，标签为
`bot.molt.gateway`（或 `bot.molt.<profile>`；旧版 `com.openclaw.*` 标签仍可正常卸载）。
- 要正常停止，使用 `openclaw gateway stop`（或 `launchctl bootout gui/$UID/bot.molt.gateway`）。
- 要重启，使用 `openclaw gateway restart`（或 `launchctl kickstart -k gui/$UID/bot.molt.gateway`）。
@@ -261,7 +261,7 @@ OpenClaw 在 Linux/WSL2 上默认安装 **systemd 用户服务**。我们推荐
```
[Unit]
Description=OpenClaw Gateway (profile: <profile>, v<version>)
Description=OpenClaw Gateway网关 (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target
@@ -282,7 +282,7 @@ WantedBy=default.target
sudo loginctl enable-linger youruser
```
上手引导在 Linux/WSL2 上会运行此命令（可能提示输入 sudo 密码；写入 `/var/lib/systemd/linger`）。
新手引导在 Linux/WSL2 上会运行此命令（可能提示输入 sudo 密码；写入 `/var/lib/systemd/linger`）。
然后启用服务：
```
@@ -304,23 +304,23 @@ Windows 安装应使用 **WSL2** 并遵循上述 Linux systemd 部分。
- 存活性：打开 WS 并发送 `req:connect` → 期望收到带有 `payload.type="hello-ok"`（含快照）的 `res`。
- 就绪性：调用 `health` → 期望 `ok: true` 且 `linkChannel` 中有已连接的渠道（适用时）。
- 调试：订阅 `tick` 和 `presence` 事件；确保 `status` 显示已连接/认证时间；在线状态条目显示 Gateway 主机和已连接的客户端。
- 调试：订阅 `tick` 和 `presence` 事件；确保 `status` 显示已连接/认证时间；在线状态条目显示 Gateway网关主机和已连接的客户端。
## 安全保证
- 默认假设每台主机一个 Gateway；如果运行多个配置文件，请隔离端口/状态并指向正确的实例。
- 不会回退到直接 Baileys 连接；如果 Gateway 不可用，发送会快速失败。
- 默认假设每台主机一个 Gateway网关；如果运行多个配置文件，请隔离端口/状态并指向正确的实例。
- 不会回退到直接 Baileys 连接；如果 Gateway网关不可用，发送会快速失败。
- 非 connect 的首帧或格式错误的 JSON 会被拒绝并关闭 socket。
- 优雅关闭：关闭前发出 `shutdown` 事件；客户端必须处理关闭 + 重新连接。
## CLI 辅助工具
- `openclaw gateway health|status` — 通过 Gateway WS 请求健康/状态信息。
- `openclaw message send --target <num> --message "hi" [--media ...]` — 通过 Gateway 发送（对 WhatsApp 具有幂等性）。
- `openclaw gateway health|status` — 通过 Gateway网关 WS 请求健康/状态信息。
- `openclaw message send --target <num> --message "hi" [--media ...]` — 通过 Gateway网关发送（对 WhatsApp 具有幂等性）。
- `openclaw agent --message "hi" --to <num>` — 运行智能体回合（默认等待最终结果）。
- `openclaw gateway call <method> --params '{"k":"v"}'` — 用于调试的原始方法调用器。
- `openclaw gateway stop|restart` — 停止/重启受监管的 Gateway 服务（launchd/systemd）。
- Gateway 辅助子命令假设 Gateway 已在 `--url` 上运行；它们不再自动启动 Gateway。
- `openclaw gateway stop|restart` — 停止/重启受监管的 Gateway网关服务（launchd/systemd）。
- Gateway网关辅助子命令假设 Gateway网关已在 `--url` 上运行；它们不再自动启动 Gateway网关。
## 迁移指南