@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/tts.md

@@ -0,0 +1,375 @@
+---
+read_when:
+  - 为回复启用文本转语音
+  - 配置 TTS 提供商或限制
+  - 使用 /tts 命令
+summary: 出站回复的文本转语音（TTS）
+title: 文本转语音
+x-i18n:
+  generated_at: "2026-02-03T10:13:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 070ff0cc8592f64c6c9e4ddaddc7e8fba82f0692ceded6fe833ec9ba5b61e6fb
+  source_path: tts.md
+  workflow: 15
+---
+
+# 文本转语音（TTS）
+
+QuantumClaw 可以使用 ElevenLabs、OpenAI 或 Edge TTS 将出站回复转换为音频。它可以在任何 QuantumClaw 能发送音频的地方工作；Telegram 会显示圆形语音消息气泡。
+
+## 支持的服务
+
+- **ElevenLabs**（主要或备用提供商）
+- **OpenAI**（主要或备用提供商；也用于摘要）
+- **Edge TTS**（主要或备用提供商；使用 `node-edge-tts`，无 API 密钥时为默认）
+
+### Edge TTS 注意事项
+
+Edge TTS 通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务（非本地），使用 Microsoft 的端点，不需要 API 密钥。`node-edge-tts` 公开了语音配置选项和输出格式，但并非所有选项都被 Edge 服务支持。citeturn2search0
+
+由于 Edge TTS 是一个没有公布 SLA 或配额的公共 Web 服务，请将其视为尽力而为。如果你需要有保证的限制和支持，请使用 OpenAI 或 ElevenLabs。Microsoft 的语音 REST API 记录了每个请求 10 分钟的音频限制；Edge TTS 没有公布限制，所以假设类似或更低的限制。citeturn0search3
+
+## 可选密钥
+
+如果你想使用 OpenAI 或 ElevenLabs：
+
+- `ELEVENLABS_API_KEY`（或 `XI_API_KEY`）
+- `OPENAI_API_KEY`
+
+Edge TTS **不**需要 API 密钥。如果没有找到 API 密钥，QuantumClaw 默认使用 Edge TTS（除非通过 `messages.tts.edge.enabled=false` 禁用）。
+
+如果配置了多个提供商，首先使用选定的提供商，其他作为备用选项。自动摘要使用配置的 `summaryModel`（或 `agents.defaults.model.primary`），所以如果你启用摘要，该提供商也必须经过认证。
+
+## 服务链接
+
+- [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech)
+- [OpenAI 音频 API 参考](https://platform.openai.com/docs/api-reference/audio)
+- [ElevenLabs 文本转语音](https://elevenlabs.io/docs/api-reference/text-to-speech)
+- [ElevenLabs 认证](https://elevenlabs.io/docs/api-reference/authentication)
+- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)
+- [Microsoft 语音输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
+
+## 默认启用吗？
+
+不是。自动 TTS 默认**关闭**。在配置中使用 `messages.tts.auto` 或在每个会话中使用 `/tts always`（别名：`/tts on`）启用它。
+
+一旦 TTS 开启，Edge TTS **是**默认启用的，并在没有 OpenAI 或 ElevenLabs API 密钥时自动使用。
+
+## 配置
+
+TTS 配置位于 `quantumclaw.json` 中的 `messages.tts` 下。完整 schema 在 [Gateway 网关配置](/gateway/configuration)中。
+
+### 最小配置（启用 + 提供商）
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "elevenlabs",
+    },
+  },
+}
+```
+
+### OpenAI 主要，ElevenLabs 备用
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "openai",
+      summaryModel: "openai/gpt-4.1-mini",
+      modelOverrides: {
+        enabled: true,
+      },
+      openai: {
+        apiKey: "openai_api_key",
+        model: "gpt-4o-mini-tts",
+        voice: "alloy",
+      },
+      elevenlabs: {
+        apiKey: "elevenlabs_api_key",
+        baseUrl: "https://api.elevenlabs.io",
+        voiceId: "voice_id",
+        modelId: "eleven_multilingual_v2",
+        seed: 42,
+        applyTextNormalization: "auto",
+        languageCode: "en",
+        voiceSettings: {
+          stability: 0.5,
+          similarityBoost: 0.75,
+          style: 0.0,
+          useSpeakerBoost: true,
+          speed: 1.0,
+        },
+      },
+    },
+  },
+}
+```
+
+### Edge TTS 主要（无 API 密钥）
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "edge",
+      edge: {
+        enabled: true,
+        voice: "en-US-MichelleNeural",
+        lang: "en-US",
+        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
+        rate: "+10%",
+        pitch: "-5%",
+      },
+    },
+  },
+}
+```
+
+### 禁用 Edge TTS
+
+```json5
+{
+  messages: {
+    tts: {
+      edge: {
+        enabled: false,
+      },
+    },
+  },
+}
+```
+
+### 自定义限制 + 偏好路径
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      maxTextLength: 4000,
+      timeoutMs: 30000,
+      prefsPath: "~/.quantumclaw/settings/tts.json",
+    },
+  },
+}
+```
+
+### 仅在收到语音消息后用音频回复
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "inbound",
+    },
+  },
+}
+```
+
+### 禁用长回复的自动摘要
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+    },
+  },
+}
+```
+
+然后运行：
+
+```
+/tts summary off
+```
+
+### 字段说明
+
+- `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。
+  - `inbound` 仅在收到语音消息后发送音频。
+  - `tagged` 仅在回复包含 `[[tts]]` 标签时发送音频。
+- `enabled`：旧版开关（doctor 将其迁移到 `auto`）。
+- `mode`：`"final"`（默认）或 `"all"`（包括工具/分块回复）。
+- `provider`：`"elevenlabs"`、`"openai"` 或 `"edge"`（自动备用）。
+- 如果 `provider` **未设置**，QuantumClaw 优先选择 `openai`（如果有密钥），然后是 `elevenlabs`（如果有密钥），否则是 `edge`。
+- `summaryModel`：用于自动摘要的可选廉价模型；默认为 `agents.defaults.model.primary`。
+  - 接受 `provider/model` 或配置的模型别名。
+- `modelOverrides`：允许模型发出 TTS 指令（默认开启）。
+- `maxTextLength`：TTS 输入的硬性上限（字符）。超出时 `/tts audio` 会失败。
+- `timeoutMs`：请求超时（毫秒）。
+- `prefsPath`：覆盖本地偏好 JSON 路径（提供商/限制/摘要）。
+- `apiKey` 值回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`OPENAI_API_KEY`）。
+- `elevenlabs.baseUrl`：覆盖 ElevenLabs API 基础 URL。
+- `elevenlabs.voiceSettings`：
+  - `stability`、`similarityBoost`、`style`：`0..1`
+  - `useSpeakerBoost`：`true|false`
+  - `speed`：`0.5..2.0`（1.0 = 正常）
+- `elevenlabs.applyTextNormalization`：`auto|on|off`
+- `elevenlabs.languageCode`：2 字母 ISO 639-1（例如 `en`、`de`）
+- `elevenlabs.seed`：整数 `0..4294967295`（尽力确定性）
+- `edge.enabled`：允许 Edge TTS 使用（默认 `true`；无 API 密钥）。
+- `edge.voice`：Edge 神经网络语音名称（例如 `en-US-MichelleNeural`）。
+- `edge.lang`：语言代码（例如 `en-US`）。
+- `edge.outputFormat`：Edge 输出格式（例如 `audio-24khz-48kbitrate-mono-mp3`）。
+  - 有效值参见 Microsoft 语音输出格式；并非所有格式都被 Edge 支持。
+- `edge.rate` / `edge.pitch` / `edge.volume`：百分比字符串（例如 `+10%`、`-5%`）。
+- `edge.saveSubtitles`：在音频文件旁边写入 JSON 字幕。
+- `edge.proxy`：Edge TTS 请求的代理 URL。
+- `edge.timeoutMs`：请求超时覆盖（毫秒）。
+
+## 模型驱动覆盖（默认开启）
+
+默认情况下，模型**可以**为单个回复发出 TTS 指令。当 `messages.tts.auto` 为 `tagged` 时，需要这些指令来触发音频。
+
+启用后，模型可以发出 `[[tts:...]]` 指令来覆盖单个回复的语音，加上可选的 `[[tts:text]]...[[/tts:text]]` 块来提供表达性标签（笑声、唱歌提示等），这些仅应出现在音频中。
+
+示例回复负载：
+
+```
+Here you go.
+
+[[tts:provider=elevenlabs voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
+[[tts:text]](laughs) Read the song once more.[[/tts:text]]
+```
+
+可用指令键（启用时）：
+
+- `provider`（`openai` | `elevenlabs` | `edge`）
+- `voice`（OpenAI 语音）或 `voiceId`（ElevenLabs）
+- `model`（OpenAI TTS 模型或 ElevenLabs 模型 ID）
+- `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost`
+- `applyTextNormalization`（`auto|on|off`）
+- `languageCode`（ISO 639-1）
+- `seed`
+
+禁用所有模型覆盖：
+
+```json5
+{
+  messages: {
+    tts: {
+      modelOverrides: {
+        enabled: false,
+      },
+    },
+  },
+}
+```
+
+可选白名单（禁用特定覆盖同时保持标签启用）：
+
+```json5
+{
+  messages: {
+    tts: {
+      modelOverrides: {
+        enabled: true,
+        allowProvider: false,
+        allowSeed: false,
+      },
+    },
+  },
+}
+```
+
+## 单用户偏好
+
+斜杠命令将本地覆盖写入 `prefsPath`（默认：`~/.quantumclaw/settings/tts.json`，可通过 `QUANTUMCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。
+
+存储的字段：
+
+- `enabled`
+- `provider`
+- `maxLength`（摘要阈值；默认 1500 字符）
+- `summarize`（默认 `true`）
+
+这些为该主机覆盖 `messages.tts.*`。
+
+## 输出格式（固定）
+
+- **Telegram**：Opus 语音消息（ElevenLabs 的 `opus_48000_64`，OpenAI 的 `opus`）。
+  - 48kHz / 64kbps 是语音消息的良好权衡，圆形气泡所必需。
+- **其他渠道**：MP3（ElevenLabs 的 `mp3_44100_128`，OpenAI 的 `mp3`）。
+  - 44.1kHz / 128kbps 是语音清晰度的默认平衡。
+- **Edge TTS**：使用 `edge.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。
+  - `node-edge-tts` 接受 `outputFormat`，但并非所有格式都可从 Edge 服务获得。citeturn2search0
+  - 输出格式值遵循 Microsoft 语音输出格式（包括 Ogg/WebM Opus）。citeturn1search0
+  - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保证的 Opus 语音消息，请使用 OpenAI/ElevenLabs。citeturn1search1
+  - 如果配置的 Edge 输出格式失败，QuantumClaw 会使用 MP3 重试。
+
+OpenAI/ElevenLabs 格式是固定的；Telegram 期望 Opus 以获得语音消息用户体验。
+
+## 自动 TTS 行为
+
+启用后，QuantumClaw：
+
+- 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。
+- 跳过非常短的回复（< 10 字符）。
+- 启用时使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复进行摘要。
+- 将生成的音频附加到回复中。
+
+如果回复超过 `maxLength` 且摘要关闭（或没有摘要模型的 API 密钥），则跳过音频并发送正常的文本回复。
+
+## 流程图
+
+```
+回复 -> TTS 启用？
+  否  -> 发送文本
+  是  -> 有媒体 / MEDIA: / 太短？
+          是 -> 发送文本
+          否 -> 长度 > 限制？
+                   否  -> TTS -> 附加音频
+                   是  -> 摘要启用？
+                            否  -> 发送文本
+                            是  -> 摘要（summaryModel 或 agents.defaults.model.primary）
+                                      -> TTS -> 附加音频
+```
+
+## 斜杠命令用法
+
+只有一个命令：`/tts`。参见[斜杠命令](/tools/slash-commands)了解启用详情。
+
+Discord 注意：`/tts` 是 Discord 的内置命令，所以 QuantumClaw 在那里注册 `/voice` 作为原生命令。文本 `/tts ...` 仍然有效。
+
+```
+/tts off
+/tts always
+/tts inbound
+/tts tagged
+/tts status
+/tts provider openai
+/tts limit 2000
+/tts summary off
+/tts audio Hello from QuantumClaw
+```
+
+注意事项：
+
+- 命令需要授权发送者（白名单/所有者规则仍然适用）。
+- 必须启用 `commands.text` 或原生命令注册。
+- `off|always|inbound|tagged` 是单会话开关（`/tts on` 是 `/tts always` 的别名）。
+- `limit` 和 `summary` 存储在本地偏好中，不在主配置中。
+- `/tts audio` 生成一次性音频回复（不会开启 TTS）。
+
+## 智能体工具
+
+`tts` 工具将文本转换为语音并返回 `MEDIA:` 路径。当结果与 Telegram 兼容时，工具包含 `[[audio_as_voice]]`，以便 Telegram 发送语音气泡。
+
+## Gateway 网关 RPC
+
+Gateway 网关方法：
+
+- `tts.status`
+- `tts.enable`
+- `tts.disable`
+- `tts.convert`
+- `tts.setProvider`
+- `tts.providers`

package/docs/zh-CN/vps.md

@@ -0,0 +1,47 @@
+---
+read_when:
+  - 你想在云端运行 Gateway 网关
+  - 你需要 VPS/托管指南的快速索引
+summary: QuantumClaw 的 VPS 托管中心（Oracle/Fly/Hetzner/GCP/exe.dev）
+title: VPS 托管
+x-i18n:
+  generated_at: "2026-02-03T10:12:57Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 7749b479b333aa5541e7ad8b0ff84e9f8f6bd10d7188285121975cb893acc037
+  source_path: vps.md
+  workflow: 15
+---
+
+# VPS 托管
+
+本中心链接到支持的 VPS/托管指南，并在高层次上解释云部署的工作原理。
+
+## 选择提供商
+
+- **Railway**（一键 + 浏览器设置）：[Railway](/install/railway)
+- **Northflank**（一键 + 浏览器设置）：[Northflank](/install/northflank)
+- **Oracle Cloud（永久免费）**：[Oracle](/platforms/oracle) — $0/月（永久免费，ARM；容量/注册可能不太稳定）
+- **Fly.io**：[Fly.io](/install/fly)
+- **Hetzner（Docker）**：[Hetzner](/install/hetzner)
+- **GCP（Compute Engine）**：[GCP](/install/gcp)
+- **exe.dev**（VM + HTTPS 代理）：[exe.dev](/install/exe-dev)
+- **AWS（EC2/Lightsail/免费套餐）**：也运行良好。视频指南：
+  https://x.com/techfrenAJ/status/2014934471095812547
+
+## 云设置的工作原理
+
+- **Gateway 网关运行在 VPS 上**并拥有状态 + 工作区。
+- 你通过**控制 UI** 或 **Tailscale/SSH** 从笔记本电脑/手机连接。
+- 将 VPS 视为数据源并**备份**状态 + 工作区。
+- 安全默认：将 Gateway 网关保持在 loopback 上，通过 SSH 隧道或 Tailscale Serve 访问。
+  如果你绑定到 `lan`/`tailnet`，需要 `gateway.auth.token` 或 `gateway.auth.password`。
+
+远程访问：[Gateway 网关远程访问](/gateway/remote)
+平台中心：[平台](/platforms)
+
+## 在 VPS 上使用节点
+
+你可以将 Gateway 网关保持在云端，并在本地设备（Mac/iOS/Android/无头）上配对**节点**。节点提供本地屏幕/摄像头/canvas 和 `system.run` 功能，而 Gateway 网关保持在云端。
+
+文档：[节点](/nodes)，[节点 CLI](/cli/nodes)

package/docs/zh-CN/web/control-ui.md

@@ -0,0 +1,191 @@
+---
+read_when:
+  - 你想从浏览器操作 Gateway 网关
+  - 你想要无需 SSH 隧道的 Tailnet 访问
+summary: Gateway 网关的浏览器控制 UI（聊天、节点、配置）
+title: 控制 UI
+x-i18n:
+  generated_at: "2026-02-03T10:13:20Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: bef105a376fc1a1df44e3e4fb625db1cbcafe2f41e718181c36877b8cbc08816
+  source_path: web/control-ui.md
+  workflow: 15
+---
+
+# 控制 UI（浏览器）
+
+控制 UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用：
+
+- 默认：`http://<host>:18789/`
+- 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/quantumclaw`）
+
+它**直接与同一端口上的 Gateway 网关 WebSocket** 通信。
+
+## 快速打开（本地）
+
+如果 Gateway 网关在同一台计算机上运行，打开：
+
+- http://127.0.0.1:18789/（或 http://localhost:18789/）
+
+如果页面加载失败，请先启动 Gateway 网关：`quantumclaw gateway`。
+
+认证在 WebSocket 握手期间通过以下方式提供：
+
+- `connect.params.auth.token`
+- `connect.params.auth.password`
+  仪表板设置面板允许你存储 token；密码不会被持久化。
+  新手引导向导默认生成一个 Gateway 网关 token，所以在首次连接时将其粘贴到这里。
+
+## 设备配对（首次连接）
+
+当你从新浏览器或设备连接到控制 UI 时，Gateway 网关需要**一次性配对批准** — 即使你在同一个 Tailnet 上且 `gateway.auth.allowTailscale: true`。这是防止未授权访问的安全措施。
+
+**你会看到：** "disconnected (1008): pairing required"
+
+**批准设备：**
+
+```bash
+# 列出待处理的请求
+quantumclaw devices list
+
+# 按请求 ID 批准
+quantumclaw devices approve <requestId>
+```
+
+一旦批准，设备会被记住，除非你使用 `quantumclaw devices revoke --device <id> --role <role>` 撤销它，否则不需要重新批准。参见 [Devices CLI](/cli/devices) 了解 token 轮换和撤销。
+
+**注意：**
+
+- 本地连接（`127.0.0.1`）会自动批准。
+- 远程连接（LAN、Tailnet 等）需要显式批准。
+- 每个浏览器配置文件生成唯一的设备 ID，因此切换浏览器或清除浏览器数据将需要重新配对。
+
+## 目前可以做什么
+
+- 通过 Gateway 网关 WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）
+- 在聊天中流式传输工具调用 + 实时工具输出卡片（智能体事件）
+- 渠道：WhatsApp/Telegram/Discord/Slack + 插件渠道（Mattermost 等）状态 + QR 登录 + 每渠道配置（`channels.status`、`web.login.*`、`config.patch`）
+- 实例：在线列表 + 刷新（`system-presence`）
+- 会话：列表 + 每会话思考/详细覆盖（`sessions.list`、`sessions.patch`）
+- 定时任务：列出/添加/运行/启用/禁用 + 运行历史（`cron.*`）
+- Skills：状态、启用/禁用、安装、API 密钥更新（`skills.*`）
+- 节点：列表 + 能力（`node.list`）
+- 执行批准：编辑 Gateway 网关或节点允许列表 + `exec host=gateway/node` 的询问策略（`exec.approvals.*`）
+- 配置：查看/编辑 `~/.quantumclaw/quantumclaw.json`（`config.get`、`config.set`）
+- 配置：应用 + 带验证的重启（`config.apply`）并唤醒上次活动的会话
+- 配置写入包含基础哈希保护，以防止覆盖并发编辑
+- 配置 schema + 表单渲染（`config.schema`，包括插件 + 渠道 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` 将助手备注附加到会话转录，并为仅 UI 更新广播 `chat` 事件（无智能体运行，无渠道投递）。
+- 停止：
+  - 点击**停止**（调用 `chat.abort`）
+  - 输入 `/stop`（或 `stop|esc|abort|wait|exit|interrupt`）以带外中止
+  - `chat.abort` 支持 `{ sessionKey }`（无 `runId`）以中止该会话的所有活动运行
+
+## Tailnet 访问（推荐）
+
+### 集成 Tailscale Serve（首选）
+
+保持 Gateway 网关在 loopback 上，让 Tailscale Serve 用 HTTPS 代理它：
+
+```bash
+quantumclaw gateway --tailscale serve
+```
+
+打开：
+
+- `https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）
+
+默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Serve 请求可以通过 Tailscale 身份头（`tailscale-user-login`）进行认证。QuantumClaw 通过使用 `tailscale whois` 解析 `x-forwarded-for` 地址并与头匹配来验证身份，并且只在请求通过 Tailscale 的 `x-forwarded-*` 头到达 loopback 时接受这些。如果你想即使对于 Serve 流量也要求 token/密码，请设置 `gateway.auth.allowTailscale: false`（或强制 `gateway.auth.mode: "password"`）。
+
+### 绑定到 tailnet + token
+
+```bash
+quantumclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
+```
+
+然后打开：
+
+- `http://<tailscale-ip>:18789/`（或你配置的 `gateway.controlUi.basePath`）
+
+将 token 粘贴到 UI 设置中（作为 `connect.params.auth.token` 发送）。
+
+## 不安全的 HTTP
+
+如果你通过普通 HTTP 打开仪表板（`http://<lan-ip>` 或 `http://<tailscale-ip>`），浏览器在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，QuantumClaw **阻止**没有设备身份的控制 UI 连接。
+
+**推荐修复：** 使用 HTTPS（Tailscale Serve）或在本地打开 UI：
+
+- `https://<magicdns>/`（Serve）
+- `http://127.0.0.1:18789/`（在 Gateway 网关主机上）
+
+**降级示例（仅通过 HTTP 使用 token）：**
+
+```json5
+{
+  gateway: {
+    controlUi: { allowInsecureAuth: true },
+    bind: "tailnet",
+    auth: { mode: "token", token: "replace-me" },
+  },
+}
+```
+
+这会为控制 UI 禁用设备身份 + 配对（即使在 HTTPS 上）。仅在你信任网络时使用。
+
+参见 [Tailscale](/gateway/tailscale) 了解 HTTPS 设置指南。
+
+## 构建 UI
+
+Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建：
+
+```bash
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+```
+
+可选的绝对基础路径（当你想要固定的资源 URL 时）：
+
+```bash
+QUANTUMCLAW_CONTROL_UI_BASE_PATH=/quantumclaw/ pnpm ui:build
+```
+
+用于本地开发（单独的开发服务器）：
+
+```bash
+pnpm ui:dev # 首次运行时自动安装 UI 依赖
+```
+
+然后将 UI 指向你的 Gateway 网关 WS URL（例如 `ws://127.0.0.1:18789`）。
+
+## 调试/测试：开发服务器 + 远程 Gateway 网关
+
+控制 UI 是静态文件；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)。

package/docs/zh-CN/web/dashboard.md

@@ -0,0 +1,53 @@
+---
+read_when:
+  - 更改仪表板认证或暴露模式
+summary: Gateway 网关仪表板（控制 UI）访问和认证
+title: 仪表板
+x-i18n:
+  generated_at: "2026-02-03T10:13:14Z"
+  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) 了解绑定模式和安全注意事项。
+
+认证通过 `connect.params.auth`（token 或密码）在 WebSocket 握手时强制执行。
+参见 [Gateway 网关配置](/gateway/configuration) 中的 `gateway.auth`。
+
+安全注意事项：控制 UI 是一个**管理界面**（聊天、配置、执行审批）。
+不要公开暴露它。UI 在首次加载后将 token 存储在 `localStorage` 中。
+优先使用 localhost、Tailscale Serve 或 SSH 隧道。
+
+## 快速路径（推荐）
+
+- 新手引导后，CLI 现在会自动打开带有你的 token 的仪表板，并打印相同的带 token 链接。
+- 随时重新打开：`quantumclaw dashboard`（复制链接，如果可能则打开浏览器，如果是无头环境则显示 SSH 提示）。
+- token 保持本地（仅查询参数）；UI 在首次加载后移除它并保存到 localStorage。
+
+## Token 基础（本地 vs 远程）
+
+- **Localhost**：打开 `http://127.0.0.1:18789/`。如果你看到"unauthorized"，运行 `quantumclaw dashboard` 并使用带 token 的链接（`?token=...`）。
+- **Token 来源**：`gateway.auth.token`（或 `QUANTUMCLAW_GATEWAY_TOKEN`）；UI 在首次加载后存储它。
+- **非 localhost**：使用 Tailscale Serve（如果 `gateway.auth.allowTailscale: true` 则无需 token）、带 token 的 tailnet 绑定，或 SSH 隧道。参见 [Web 界面](/web)。
+
+## 如果你看到"unauthorized" / 1008
+
+- 运行 `quantumclaw dashboard` 获取新的带 token 链接。
+- 确保 Gateway 网关可达（本地：`quantumclaw status`；远程：SSH 隧道 `ssh -N -L 18789:127.0.0.1:18789 user@host` 然后打开 `http://127.0.0.1:18789/?token=...`）。
+- 在仪表板设置中，粘贴你在 `gateway.auth.token`（或 `QUANTUMCLAW_GATEWAY_TOKEN`）中配置的相同 token。