Docs: add zh-CN translations

2026-05-02 20:48:25 +00:00 · 2026-02-01 22:47:44 +01:00
parent e70984745b
commit 149dc7c4e7
298 changed files with 53861 additions and 0 deletions
--- a/docs/zh-CN/web/control-ui.md
+++ b/docs/zh-CN/web/control-ui.md
@@ -0,0 +1,203 @@
+---
+read_when:
+  - 你想通过浏览器操作 Gateway
+  - 你想通过 Tailnet 访问而无需 SSH 隧道
+summary: 基于浏览器的 Gateway 控制界面（聊天、节点、配置）
+title: 控制界面
+x-i18n:
+  generated_at: "2026-02-01T21:44:27Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 91f6d3f297fb87ffb7c98f9d4955ac624a41fd920af54f1f480e4727816a506b
+  source_path: web/control-ui.md
+  workflow: 15
+---
+
+# 控制界面（浏览器）
+
+控制界面是一个由 Gateway 提供服务的小型 **Vite + Lit** 单页应用：
+
+- 默认地址：`http://<host>:18789/`
+- 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`）
+
+它通过同一端口**直接与 Gateway WebSocket** 通信。
+
+## 快速打开（本地）
+
+如果 Gateway 在同一台计算机上运行，请打开：
+
+- http://127.0.0.1:18789/（或 http://localhost:18789/）
+
+如果页面无法加载，请先启动 Gateway：`openclaw gateway`。
+
+认证在 WebSocket 握手期间通过以下方式提供：
+
+- `connect.params.auth.token`
+- `connect.params.auth.password`
+  仪表板设置面板允许你存储令牌；密码不会被持久化。
+  上手引导向导默认会生成一个 Gateway 令牌，首次连接时请在此处粘贴。
+
+## 设备配对（首次连接）
+
+当你从新浏览器或设备连接到控制界面时，Gateway
+需要进行**一次性配对审批** — 即使你在同一个 Tailnet 上且
+设置了 `gateway.auth.allowTailscale: true`。这是一项防止
+未授权访问的安全措施。
+
+**你会看到：**"disconnected (1008): pairing required"
+
+**审批设备：**
+
+```bash
+# 列出待处理的请求
+openclaw devices list
+
+# 通过请求 ID 审批
+openclaw devices approve <requestId>
+```
+
+审批后，设备会被记住，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销，否则不需要重新审批。参见
+[设备 CLI](/cli/devices) 了解令牌轮换和撤销。
+
+**说明：**
+
+- 本地连接（`127.0.0.1`）会自动审批。
+- 远程连接（局域网、Tailnet 等）需要显式审批。
+- 每个浏览器配置文件会生成唯一的设备 ID，因此切换浏览器或
+  清除浏览器数据将需要重新配对。
+
+## 当前功能
+
+- 通过 Gateway WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）
+- 在聊天中流式传输工具调用 + 实时工具输出卡片（智能体事件）
+- 渠道：WhatsApp/Telegram/Discord/Slack + 插件渠道（Mattermost 等）状态 + 二维码登录 + 每渠道配置（`channels.status`、`web.login.*`、`config.patch`）
+- 实例：在线列表 + 刷新（`system-presence`）
+- 会话：列表 + 每会话思考/详细模式覆盖（`sessions.list`、`sessions.patch`）
+- 定时任务：列表/添加/运行/启用/禁用 + 运行历史（`cron.*`）
+- 技能：状态、启用/禁用、安装、API 密钥更新（`skills.*`）
+- 节点：列表 + 能力（`node.list`）
+- 执行审批：编辑 Gateway 或节点允许列表 + `exec host=gateway/node` 的询问策略（`exec.approvals.*`）
+- 配置：查看/编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）
+- 配置：应用 + 带验证的重启（`config.apply`）并唤醒最后活跃的会话
+- 配置写入包含基础哈希保护，防止覆盖并发编辑
+- 配置模式 + 表单渲染（`config.schema`，包括插件 + 渠道模式）；原始 JSON 编辑器仍然可用
+- 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）
+- 日志：实时跟踪 Gateway 文件日志，支持过滤/导出（`logs.tail`）
+- 更新：运行包/git 更新 + 重启（`update.run`）并附带重启报告
+
+## 聊天行为
+
+- `chat.send` 是**非阻塞的**：它会立即确认并返回 `{ runId, status: "started" }`，响应通过 `chat` 事件流式传输。
+- 使用相同的 `idempotencyKey` 重新发送时，运行中返回 `{ status: "in_flight" }`，完成后返回 `{ status: "ok" }`。
+- `chat.inject` 将助手备注追加到会话记录中，并广播 `chat` 事件用于仅 UI 更新（不触发智能体运行，不投递到渠道）。
+- 停止：
+  - 点击**停止**（调用 `chat.abort`）
+  - 输入 `/stop`（或 `stop|esc|abort|wait|exit|interrupt`）进行带外中止
+  - `chat.abort` 支持 `{ sessionKey }`（无需 `runId`）以中止该会话的所有活跃运行
+
+## Tailnet 访问（推荐）
+
+### 集成 Tailscale Serve（首选）
+
+将 Gateway 保持在回环地址上，让 Tailscale Serve 通过 HTTPS 代理：
+
+```bash
+openclaw gateway --tailscale serve
+```
+
+打开：
+
+- `https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）
+
+默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Serve 请求可以通过 Tailscale 身份头
+（`tailscale-user-login`）进行认证。OpenClaw
+通过使用 `tailscale whois` 解析 `x-forwarded-for` 地址并与头信息匹配来验证身份，且仅在请求通过带有 Tailscale `x-forwarded-*` 头的回环地址到达时才接受。如果你希望即使对 Serve 流量也要求令牌/密码，请设置
+`gateway.auth.allowTailscale: false`（或强制 `gateway.auth.mode: "password"`）。
+
+### 绑定到 Tailnet + 令牌
+
+```bash
+openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
+```
+
+然后打开：
+
+- `http://<tailscale-ip>:18789/`（或你配置的 `gateway.controlUi.basePath`）
+
+在 UI 设置中粘贴令牌（作为 `connect.params.auth.token` 发送）。
+
+## 不安全的 HTTP
+
+如果你通过明文 HTTP（`http://<lan-ip>` 或 `http://<tailscale-ip>`）打开仪表板，
+浏览器运行在**非安全上下文**中并会阻止 WebCrypto。默认情况下，
+OpenClaw **会阻止**没有设备身份的控制界面连接。
+
+**推荐修复：**使用 HTTPS（Tailscale Serve）或在本地打开 UI：
+
+- `https://<magicdns>/`（Serve）
+- `http://127.0.0.1:18789/`（在 Gateway 主机上）
+
+**降级示例（仅令牌，通过 HTTP）：**
+
+```json5
+{
+  gateway: {
+    controlUi: { allowInsecureAuth: true },
+    bind: "tailnet",
+    auth: { mode: "token", token: "replace-me" },
+  },
+}
+```
+
+这将为控制界面禁用设备身份 + 配对（即使在 HTTPS 上也是如此）。仅在
+你信任网络时使用。
+
+有关 HTTPS 设置指导，请参阅 [Tailscale](/gateway/tailscale)。
+
+## 构建 UI
+
+Gateway 从 `dist/control-ui` 提供静态文件。使用以下命令构建：
+
+```bash
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+```
+
+可选的绝对基础路径（当你需要固定的资源 URL 时）：
+
+```bash
+OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
+```
+
+本地开发（独立的开发服务器）：
+
+```bash
+pnpm ui:dev # 首次运行时自动安装 UI 依赖
+```
+
+然后将 UI 指向你的 Gateway WS URL（例如 `ws://127.0.0.1:18789`）。
+
+## 调试/测试：开发服务器 + 远程 Gateway
+
+控制界面是静态文件；WebSocket 目标可配置，可以
+与 HTTP 源不同。当你想在本地使用 Vite 开发服务器但 Gateway 运行在其他地方时，这很方便。
+
+1. 启动 UI 开发服务器：`pnpm ui:dev`
+2. 打开类似以下的 URL：
+
+```text
+http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789
+```
+
+可选的一次性认证（如果需要）：
+
+```text
+http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789&token=<gateway-token>
+```
+
+说明：
+
+- `gatewayUrl` 在加载后存储到 localStorage 并从 URL 中移除。
+- `token` 存储在 localStorage 中；`password` 仅保存在内存中。
+- 当 Gateway 在 TLS 之后（Tailscale Serve、HTTPS 代理等）时使用 `wss://`。
+
+远程访问设置详情：[远程访问](/gateway/remote)。
--- a/docs/zh-CN/web/dashboard.md
+++ b/docs/zh-CN/web/dashboard.md
@@ -0,0 +1,49 @@
+---
+read_when:
+  - 更改仪表盘认证或暴露模式
+summary: Gateway 仪表盘（控制 UI）访问与认证
+title: 仪表盘
+x-i18n:
+  generated_at: "2026-02-01T21:44:08Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: e6876d50e17d3dd741471ed78bef6ac175b2fdbdc1c45dd52d9d2bd013e17f31
+  source_path: web/dashboard.md
+  workflow: 15
+---
+
+# 仪表盘（控制 UI）
+
+Gateway 仪表盘是默认在 `/` 路径提供的浏览器控制 UI（可通过 `gateway.controlUi.basePath` 覆盖）。
+
+快速打开（本地 Gateway）：
+
+- http://127.0.0.1:18789/（或 http://localhost:18789/）
+
+关键参考：
+
+- [控制 UI](/web/control-ui) 了解使用方式和 UI 功能。
+- [Tailscale](/gateway/tailscale) 了解 Serve/Funnel 自动化。
+- [Web 界面](/web) 了解绑定模式和安全说明。
+
+认证在 WebSocket 握手时通过 `connect.params.auth`（令牌或密码）强制执行。参见 [Gateway 配置](/gateway/configuration) 中的 `gateway.auth`。
+
+安全说明：控制 UI 是一个**管理界面**（聊天、配置、执行审批）。不要将其公开暴露。UI 在首次加载后将令牌存储在 `localStorage` 中。建议使用 localhost、Tailscale Serve 或 SSH 隧道。
+
+## 快速路径（推荐）
+
+- 完成上手引导后，CLI 会自动打开携带令牌的仪表盘，并打印相同的带令牌链接。
+- 随时重新打开：`openclaw dashboard`（复制链接，如可能则打开浏览器，无头环境下显示 SSH 提示）。
+- 令牌保留在本地（仅作为查询参数）；UI 在首次加载后会移除它并保存到 localStorage 中。
+
+## 令牌基础（本地 vs 远程）
+
+- **Localhost**：打开 `http://127.0.0.1:18789/`。如果看到"unauthorized"，运行 `openclaw dashboard` 并使用带令牌的链接（`?token=...`）。
+- **令牌来源**：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）；UI 在首次加载后存储它。
+- **非 localhost**：使用 Tailscale Serve（当 `gateway.auth.allowTailscale: true` 时无需令牌）、带令牌的 tailnet 绑定，或 SSH 隧道。参见 [Web 界面](/web)。
+
+## 如果看到"unauthorized"/ 1008
+
+- 运行 `openclaw dashboard` 获取新的带令牌链接。
+- 确保 Gateway 可达（本地：`openclaw status`；远程：SSH 隧道 `ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/?token=...`）。
+- 在仪表盘设置中，粘贴你在 `gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）中配置的相同令牌。
--- a/docs/zh-CN/web/index.md
+++ b/docs/zh-CN/web/index.md
@@ -0,0 +1,118 @@
+---
+read_when:
+  - 您想通过 Tailscale 访问 Gateway
+  - 您想使用浏览器控制 UI 和配置编辑
+summary: Gateway Web 界面：控制 UI、绑定模式与安全
+title: Web
+x-i18n:
+  generated_at: "2026-02-01T21:44:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 4da8bc9831018c482ac918a759b9739f75ca130f70993f81911818bc60a685d1
+  source_path: web/index.md
+  workflow: 15
+---
+
+# Web（Gateway）
+
+Gateway 在与 Gateway WebSocket 相同的端口上提供一个小型**浏览器控制 UI**（Vite + Lit）：
+
+- 默认：`http://<host>:18789/`
+- 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`）
+
+功能详情请参阅[控制 UI](/web/control-ui)。
+本页重点介绍绑定模式、安全和面向 Web 的界面。
+
+## Webhook
+
+当 `hooks.enabled=true` 时，Gateway 还会在同一 HTTP 服务器上暴露一个小型 webhook 端点。
+请参阅 [Gateway 配置](/gateway/configuration) → `hooks` 了解认证和负载。
+
+## 配置（默认启用）
+
+当资源文件存在时（`dist/control-ui`），控制 UI **默认启用**。
+您可以通过配置控制它：
+
+```json5
+{
+  gateway: {
+    controlUi: { enabled: true, basePath: "/openclaw" }, // basePath 可选
+  },
+}
+```
+
+## Tailscale 访问
+
+### 集成 Serve（推荐）
+
+将 Gateway 保持在回环地址上，让 Tailscale Serve 代理它：
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "serve" },
+  },
+}
+```
+
+然后启动 Gateway：
+
+```bash
+openclaw gateway
+```
+
+打开：
+
+- `https://<magicdns>/`（或您配置的 `gateway.controlUi.basePath`）
+
+### Tailnet 绑定 + 令牌
+
+```json5
+{
+  gateway: {
+    bind: "tailnet",
+    controlUi: { enabled: true },
+    auth: { mode: "token", token: "your-token" },
+  },
+}
+```
+
+然后启动 Gateway（非回环绑定需要令牌）：
+
+```bash
+openclaw gateway
+```
+
+打开：
+
+- `http://<tailscale-ip>:18789/`（或您配置的 `gateway.controlUi.basePath`）
+
+### 公网访问（Funnel）
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "funnel" },
+    auth: { mode: "password" }, // 或 OPENCLAW_GATEWAY_PASSWORD
+  },
+}
+```
+
+## 安全说明
+
+- Gateway 认证默认必需（令牌/密码或 Tailscale 身份头）。
+- 非回环绑定仍然**需要**共享令牌/密码（`gateway.auth` 或环境变量）。
+- 向导默认生成 Gateway 令牌（即使在回环地址上）。
+- UI 发送 `connect.params.auth.token` 或 `connect.params.auth.password`。
+- 使用 Serve 时，当 `gateway.auth.allowTailscale` 为 `true` 时，Tailscale 身份头可满足认证要求（无需令牌/密码）。设置 `gateway.auth.allowTailscale: false` 以要求显式凭据。请参阅 [Tailscale](/gateway/tailscale) 和[安全](/gateway/security)。
+- `gateway.tailscale.mode: "funnel"` 需要 `gateway.auth.mode: "password"`（共享密码）。
+
+## 构建 UI
+
+Gateway 从 `dist/control-ui` 提供静态文件。使用以下命令构建：
+
+```bash
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+```
--- a/docs/zh-CN/web/webchat.md
+++ b/docs/zh-CN/web/webchat.md
@@ -0,0 +1,56 @@
+---
+read_when:
+  - 调试或配置 WebChat 访问
+summary: 回环 WebChat 静态主机及 Gateway WebSocket 在聊天 UI 中的使用
+title: WebChat
+x-i18n:
+  generated_at: "2026-02-01T21:44:15Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b5ee2b462c8c979ac27f80dea0cf12cf62b3c799cf8fd0a7721901e26efeb1a0
+  source_path: web/webchat.md
+  workflow: 15
+---
+
+# WebChat（Gateway WebSocket UI）
+
+状态：macOS/iOS SwiftUI 聊天 UI 直接连接 Gateway WebSocket。
+
+## 简介
+
+- 一个 Gateway 的原生聊天 UI（无内嵌浏览器，无本地静态服务器）。
+- 使用与其他渠道相同的会话和路由规则。
+- 确定性路由：回复始终返回到 WebChat。
+
+## 快速开始
+
+1. 启动 Gateway。
+2. 打开 WebChat UI（macOS/iOS 应用）或控制台 UI 的聊天标签页。
+3. 确保已配置 Gateway 认证（默认必需，即使在回环地址上也是如此）。
+
+## 工作原理（行为）
+
+- UI 连接到 Gateway WebSocket，使用 `chat.history`、`chat.send` 和 `chat.inject`。
+- `chat.inject` 将助手备注直接追加到对话记录中并广播到 UI（不触发智能体运行）。
+- 历史记录始终从 Gateway 获取（无本地文件监听）。
+- 如果 Gateway 不可达，WebChat 为只读模式。
+
+## 远程使用
+
+- 远程模式通过 SSH/Tailscale 隧道传输 Gateway WebSocket。
+- 无需运行单独的 WebChat 服务器。
+
+## 配置参考（WebChat）
+
+完整配置：[配置](/gateway/configuration)
+
+渠道选项：
+
+- 没有专用的 `webchat.*` 配置块。WebChat 使用下方的 Gateway 端点 + 认证设置。
+
+相关全局选项：
+
+- `gateway.port`、`gateway.bind`：WebSocket 主机/端口。
+- `gateway.auth.mode`、`gateway.auth.token`、`gateway.auth.password`：WebSocket 认证。
+- `gateway.remote.url`、`gateway.remote.token`、`gateway.remote.password`：远程 Gateway 目标。
+- `session.*`：会话存储和主键默认值。