From adc110f3cfb221b03d448d46e1c0758258565f6e Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 23:15:09 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/nodes/audio.md | 139 +++++++++--------- docs/zh-CN/web/control-ui.md | 272 ++++++++++++++++++----------------- docs/zh-CN/web/webchat.md | 67 ++++----- 3 files changed, 241 insertions(+), 237 deletions(-) diff --git a/docs/zh-CN/nodes/audio.md b/docs/zh-CN/nodes/audio.md index 7f83387d5..16cd64ff3 100644 --- a/docs/zh-CN/nodes/audio.md +++ b/docs/zh-CN/nodes/audio.md @@ -1,52 +1,53 @@ --- read_when: - - 更改音频转录或媒体处理 -summary: 入站音频/语音消息如何被下载、转录并注入到回复中 -title: 音频和语音消息 + - 更改音频转写或媒体处理 +summary: 如何下载和转写入站音频/语音消息，并将其注入回复 +title: 音频和语音留言 x-i18n: - generated_at: "2026-04-27T14:47:45Z" - model: gpt-5.4 + generated_at: "2026-05-02T23:13:33Z" + model: gpt-5.5 provider: openai - source_hash: 35074d79104f767ee252064462202a8ec21ac26f6db25c39e67f31f6b40edeb7 + source_hash: 91cd6951f80c6137061a7d4e82415b0872bc92c6d6ad136273a2e9ad7ec00ac1 source_path: nodes/audio.md - workflow: 15 + workflow: 16 --- -# 音频 / 语音消息（2026-01-17） +# 音频 / 语音留言（2026-01-17） -## 已支持的功能 +## 可用功能 -- **媒体理解（音频）**：如果启用了音频理解（或自动检测到可用），OpenClaw 会： +- **媒体理解（音频）**：如果启用了音频理解（或自动检测到），OpenClaw 会： 1. 定位第一个音频附件（本地路径或 URL），并在需要时下载它。 - 2. 在发送给每个模型条目前强制执行 `maxBytes` 限制。 - 3. 按顺序运行第一个符合条件的模型条目（provider 或 CLI）。 - 4. 如果失败或跳过（大小 / 超时），则尝试下一个条目。 - 5. 成功后，它会用一个 `[Audio]` 块替换 `Body`，并设置 `{{Transcript}}`。 -- **命令解析**：当转录成功时，`CommandBody`/`RawBody` 会被设置为转录文本，因此斜杠命令仍然可用。 -- **详细日志**：在 `--verbose` 模式下，我们会记录何时运行转录以及何时替换消息正文。 + 2. 在发送到每个模型条目前强制执行 `maxBytes`。 + 3. 按顺序运行第一个符合条件的模型条目（提供商或 CLI）。 + 4. 如果失败或跳过（大小/超时），会尝试下一个条目。 + 5. 成功后，会将 `Body` 替换为 `[Audio]` 块并设置 `{{Transcript}}`。 +- **命令解析**：转写成功后，`CommandBody`/`RawBody` 会被设置为转写文本，因此斜杠命令仍可工作。 +- **详细日志**：在 `--verbose` 下，我们会记录转写运行以及替换正文的时机。 +- **控制 UI 听写**：聊天撰写器可以将浏览器录制的麦克风片段发送到 `chat.transcribeAudio`。该 Gateway 网关 RPC 会将片段写入临时本地文件，运行同一个音频转写流水线，将草稿文本返回给浏览器，并删除临时文件。它本身不会创建智能体运行。 ## 自动检测（默认） -如果你**未配置模型**，并且 `tools.media.audio.enabled` **未**设置为 `false`， -OpenClaw 会按以下顺序自动检测，并在第一个可用选项成功后停止： +如果你**没有配置模型**，并且 `tools.media.audio.enabled` **未**设置为 `false`， +OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项时停止： -1. **当前回复模型**，前提是其提供商支持音频理解。 +1. **当前回复模型**，当其提供商支持音频理解时。 2. **本地 CLI**（如果已安装） - - `sherpa-onnx-offline`（需要设置 `SHERPA_ONNX_MODEL_DIR`，其中包含 encoder/decoder/joiner/tokens） - - `whisper-cli`（来自 `whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置的 tiny 模型） - - `whisper`（Python CLI；会自动下载模型） + - `sherpa-onnx-offline`（需要带有 encoder/decoder/joiner/tokens 的 `SHERPA_ONNX_MODEL_DIR`） + - `whisper-cli`（来自 `whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置 tiny 模型） + - `whisper`（Python CLI；自动下载模型） 3. **Gemini CLI**（`gemini`），使用 `read_many_files` -4. **provider 凭证** - - 优先尝试已配置且支持音频的 `models.providers.*` 条目 +4. **提供商凭证** + - 会优先尝试已配置且支持音频的 `models.providers.*` 条目 - 内置回退顺序：OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral 要禁用自动检测，请设置 `tools.media.audio.enabled: false`。 要自定义，请设置 `tools.media.audio.models`。 -注意：二进制检测在 macOS/Linux/Windows 上尽力而为；请确保 CLI 在 `PATH` 中（我们会展开 `~`），或者设置带有完整命令路径的显式 CLI 模型。 +注意：二进制检测在 macOS/Linux/Windows 上是尽力而为；请确保 CLI 位于 `PATH` 中（我们会展开 `~`），或设置带完整命令路径的显式 CLI 模型。 ## 配置示例 -### provider + CLI 回退（OpenAI + Whisper CLI） +### 提供商 + CLI 回退（OpenAI + Whisper CLI） ```json5 { @@ -70,7 +71,7 @@ OpenClaw 会按以下顺序自动检测，并在第一个可用选项成功后 } ``` -### 仅 provider，并带作用域门控 +### 仅提供商并带范围控制 ```json5 { @@ -89,7 +90,7 @@ OpenClaw 会按以下顺序自动检测，并在第一个可用选项成功后 } ``` -### 仅 provider（Deepgram） +### 仅提供商（Deepgram） ```json5 { @@ -104,7 +105,7 @@ OpenClaw 会按以下顺序自动检测，并在第一个可用选项成功后 } ``` -### 仅 provider（Mistral Voxtral） +### 仅提供商（Mistral Voxtral） ```json5 { @@ -119,7 +120,7 @@ OpenClaw 会按以下顺序自动检测，并在第一个可用选项成功后 } ``` -### 仅 provider（SenseAudio） +### 仅提供商（SenseAudio） ```json5 { @@ -134,7 +135,7 @@ OpenClaw 会按以下顺序自动检测，并在第一个可用选项成功后 } ``` -### 将转录文本回显到聊天中（可选启用） +### 将转写文本回显到聊天（可选启用） ```json5 { @@ -142,8 +143,8 @@ OpenClaw 会按以下顺序自动检测，并在第一个可用选项成功后 media: { audio: { enabled: true, - echoTranscript: true, // 默认是 false - echoFormat: '📝 "{transcript}"', // 可选，支持 {transcript} + echoTranscript: true, // default is false + echoFormat: '📝 "{transcript}"', // optional, supports {transcript} models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }], }, }, @@ -151,30 +152,30 @@ OpenClaw 会按以下顺序自动检测，并在第一个可用选项成功后 } ``` -## 说明与限制 +## 注意事项与限制 -- provider 凭证遵循标准的模型凭证顺序（认证配置文件、环境变量、`models.providers.*.apiKey`）。 +- 提供商凭证遵循标准模型凭证顺序（凭证配置文件、环境变量、`models.providers.*.apiKey`）。 - Groq 设置详情：[Groq](/zh-CN/providers/groq)。 -- 当使用 `provider: "deepgram"` 时，Deepgram 会读取 `DEEPGRAM_API_KEY`。 -- Deepgram 设置详情：[Deepgram（音频转录）](/zh-CN/providers/deepgram)。 +- 使用 `provider: "deepgram"` 时，Deepgram 会读取 `DEEPGRAM_API_KEY`。 +- Deepgram 设置详情：[Deepgram（音频转写）](/zh-CN/providers/deepgram)。 - Mistral 设置详情：[Mistral](/zh-CN/providers/mistral)。 -- 当使用 `provider: "senseaudio"` 时，SenseAudio 会读取 `SENSEAUDIO_API_KEY`。 +- 使用 `provider: "senseaudio"` 时，SenseAudio 会读取 `SENSEAUDIO_API_KEY`。 - SenseAudio 设置详情：[SenseAudio](/zh-CN/providers/senseaudio)。 -- 音频 provider 可以通过 `tools.media.audio` 覆盖 `baseUrl`、`headers` 和 `providerOptions`。 -- 默认大小上限为 20 MB（`tools.media.audio.maxBytes`）。超出大小限制的音频会对该模型跳过，并尝试下一个条目。 -- 小于 1024 字节的超小 / 空音频文件会在 provider/CLI 转录之前被跳过。 -- 音频的默认 `maxChars` **未设置**（完整转录）。可设置 `tools.media.audio.maxChars` 或按条目设置 `maxChars` 以截断输出。 -- OpenAI 的自动默认模型是 `gpt-4o-mini-transcribe`；如需更高准确率，请设置 `model: "gpt-4o-transcribe"`。 -- 使用 `tools.media.audio.attachments` 处理多个语音消息（`mode: "all"` + `maxAttachments`）。 -- 转录文本可通过 `{{Transcript}}` 提供给模板使用。 -- `tools.media.audio.echoTranscript` 默认关闭；启用后会在智能体处理前将转录确认消息发送回原始聊天。 +- 音频提供商可以通过 `tools.media.audio` 覆盖 `baseUrl`、`headers` 和 `providerOptions`。 +- 默认大小上限为 20MB（`tools.media.audio.maxBytes`）。超大音频会针对该模型跳过，并尝试下一个条目。 +- 小于 1024 字节的 tiny/空音频文件会在提供商/CLI 转写前跳过。 +- 音频的默认 `maxChars` **未设置**（完整转写文本）。设置 `tools.media.audio.maxChars` 或每个条目的 `maxChars` 可裁剪输出。 +- OpenAI 自动默认值为 `gpt-4o-mini-transcribe`；设置 `model: "gpt-4o-transcribe"` 可获得更高准确度。 +- 使用 `tools.media.audio.attachments` 处理多条语音留言（`mode: "all"` + `maxAttachments`）。 +- 转写文本可作为 `{{Transcript}}` 提供给模板。 +- `tools.media.audio.echoTranscript` 默认关闭；启用后可在智能体处理前，将转写确认发送回来源聊天。 - `tools.media.audio.echoFormat` 用于自定义回显文本（占位符：`{transcript}`）。 -- CLI stdout 有上限（5 MB）；请保持 CLI 输出简洁。 -- CLI `args` 应使用 `{{MediaPath}}` 表示本地音频文件路径。运行 `openclaw doctor --fix` 可迁移旧版 `audio.transcription.command` 配置中已弃用的 `{input}` 占位符。 +- CLI stdout 有上限（5MB）；保持 CLI 输出简洁。 +- CLI `args` 应使用 `{{MediaPath}}` 作为本地音频文件路径。运行 `openclaw doctor --fix` 可从旧版 `audio.transcription.command` 配置迁移已弃用的 `{input}` 占位符。 ### 代理环境支持 -基于 provider 的音频转录遵循标准的出站代理环境变量： +基于提供商的音频转写遵循标准出站代理环境变量： - `HTTPS_PROXY` - `HTTP_PROXY` @@ -183,42 +184,42 @@ OpenClaw 会按以下顺序自动检测，并在第一个可用选项成功后 - `http_proxy` - `all_proxy` -如果未设置代理环境变量，则使用直连出口。如果代理配置格式错误，OpenClaw 会记录警告并回退到直连抓取。 +如果未设置代理环境变量，则使用直接出站连接。如果代理配置格式错误，OpenClaw 会记录警告并回退到直接获取。 ## 群组中的提及检测 -当群聊设置了 `requireMention: true` 时，OpenClaw 现在会在检查提及之前**先转录音频**。这样即使语音消息中包含提及，也能被处理。 +当群聊设置了 `requireMention: true` 时，OpenClaw 现在会在检查提及**之前**转写音频。这样即使语音留言中包含提及，也可以被处理。 **工作方式：** -1. 如果语音消息没有文本正文，且群组要求提及，OpenClaw 会执行一次“预检”转录。 -2. 系统会检查转录文本中是否包含提及模式（例如 `@BotName`、表情符号触发词）。 -3. 如果检测到提及，消息会进入完整回复流程。 -4. 转录文本会用于提及检测，因此语音消息可以通过提及门槛。 +1. 如果语音消息没有文本正文且群组要求提及，OpenClaw 会执行“预检”转写。 +2. 检查转写文本中的提及模式（例如 `@BotName`、emoji 触发器）。 +3. 如果找到提及，消息会继续进入完整回复流水线。 +4. 转写文本会用于提及检测，因此语音留言可以通过提及门控。 **回退行为：** -- 如果预检阶段的转录失败（超时、API 错误等），消息将根据纯文本提及检测结果进行处理。 -- 这样可以确保混合消息（文本 + 音频）永远不会被错误丢弃。 +- 如果预检期间转写失败（超时、API 错误等），消息会基于纯文本提及检测进行处理。 +- 这确保混合消息（文本 + 音频）永远不会被错误丢弃。 -**按 Telegram 群组 / 话题选择退出：** +**按 Telegram 群组/话题选择退出：** -- 设置 `channels.telegram.groups..disableAudioPreflight: true` 可为该群组跳过预检转录提及检查。 -- 设置 `channels.telegram.groups..topics..disableAudioPreflight` 可按话题覆盖（`true` 为跳过，`false` 为强制启用）。 +- 设置 `channels.telegram.groups..disableAudioPreflight: true` 可跳过该群组的预检转写提及检查。 +- 设置 `channels.telegram.groups..topics..disableAudioPreflight` 可按话题覆盖（`true` 表示跳过，`false` 表示强制启用）。 - 默认值为 `false`（当提及门控条件匹配时启用预检）。 -**示例：** 用户在一个设置了 `requireMention: true` 的 Telegram 群组中发送一条语音消息，说：“Hey @Claude, what's the weather?”。该语音消息会被转录，系统会检测到提及，然后智能体作出回复。 +**示例：** 用户在设置了 `requireMention: true` 的 Telegram 群组中发送一条语音留言，说 “Hey @Claude, what's the weather?”。该语音留言会被转写、检测到提及，然后智能体回复。 -## 注意事项 +## 注意点 -- 作用域规则采用首次匹配优先。`chatType` 会被规范化为 `direct`、`group` 或 `room`。 -- 请确保你的 CLI 以 0 退出并输出纯文本；如果输出是 JSON，需要通过 `jq -r .text` 做处理。 -- 对于 `parakeet-mlx`，如果你传入 `--output-dir`，当 `--output-format` 为 `txt`（或省略）时，OpenClaw 会读取 `/.txt`；非 `txt` 输出格式会回退到解析 stdout。 -- 请保持合理的超时时间（`timeoutSeconds`，默认 60 秒），以避免阻塞回复队列。 -- 预检转录仅处理**第一个**音频附件用于提及检测。其他音频会在主媒体理解阶段处理。 +- 范围规则使用首个匹配胜出。`chatType` 会规范化为 `direct`、`group` 或 `room`。 +- 确保你的 CLI 以 0 退出并打印纯文本；JSON 需要通过 `jq -r .text` 处理。 +- 对于 `parakeet-mlx`，如果传入 `--output-dir`，当 `--output-format` 为 `txt`（或省略）时，OpenClaw 会读取 `/.txt`；非 `txt` 输出格式会回退到 stdout 解析。 +- 保持合理的超时（`timeoutSeconds`，默认 60s），避免阻塞回复队列。 +- 预检转写只处理**第一个**音频附件用于提及检测。其他音频会在主媒体理解阶段处理。 -## 相关内容 +## 相关 - [媒体理解](/zh-CN/nodes/media-understanding) -- [Talk 模式](/zh-CN/nodes/talk) +- [对话模式](/zh-CN/nodes/talk) - [语音唤醒](/zh-CN/nodes/voicewake) diff --git a/docs/zh-CN/web/control-ui.md b/docs/zh-CN/web/control-ui.md index 6135248ec..73750aa45 100644 --- a/docs/zh-CN/web/control-ui.md +++ b/docs/zh-CN/web/control-ui.md @@ -1,25 +1,25 @@ --- read_when: - - 你想从浏览器操作 Gateway 网关 - - 你想要无需 SSH 隧道的 Tailnet 访问 + - 你想通过浏览器操作 Gateway 网关 + - 你需要无需 SSH 隧道即可访问 Tailnet sidebarTitle: Control UI -summary: 基于浏览器的 Gateway 网关控制 UI（聊天、节点、配置） +summary: 基于浏览器的 Gateway 网关控制界面（聊天、节点、配置） title: 控制界面 x-i18n: - generated_at: "2026-05-02T15:33:59Z" + generated_at: "2026-05-02T23:13:45Z" model: gpt-5.5 provider: openai - source_hash: 88959ccf435b31015039bf28c3043023d99f0b953a1489986ab2d0cbd261771c + source_hash: 50bef807915f27406e19f1c6ca7d839a610d79ba79da85d7a78523400cbf9208 source_path: web/control-ui.md workflow: 16 --- -Control UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用： +控制 UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用： - 默认：`http://:18789/` - 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`） -它在同一端口上**直接与 Gateway 网关 WebSocket 通信**。 +它会在同一端口上**直接与 Gateway 网关 WebSocket 通信**。 ## 快速打开（本地） @@ -29,18 +29,18 @@ Control UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单 如果页面加载失败，请先启动 Gateway 网关：`openclaw gateway`。 -认证会在 WebSocket 握手期间通过以下方式提供： +身份验证会在 WebSocket 握手期间通过以下方式提供： - `connect.params.auth.token` - `connect.params.auth.password` - 当 `gateway.auth.allowTailscale: true` 时的 Tailscale Serve 身份标头 -- 当 `gateway.auth.mode: "trusted-proxy"` 时的受信代理身份标头 +- 当 `gateway.auth.mode: "trusted-proxy"` 时的 trusted-proxy 身份标头 -仪表板设置面板会为当前浏览器标签页会话和选定的 Gateway 网关 URL 保存一个令牌；密码不会被持久化。新手引导通常会在首次连接时为共享密钥认证生成 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，密码认证也可使用。 +仪表盘设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保留一个令牌；密码不会被持久保存。新手引导通常会在首次连接时为共享密钥身份验证生成一个 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，也可以使用密码身份验证。 ## 设备配对（首次连接） -当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关通常会要求进行**一次性配对批准**。这是一项安全措施，用于防止未经授权的访问。 +当你从新的浏览器或设备连接到控制 UI 时，Gateway 网关通常需要**一次性配对批准**。这是一项安全措施，用于防止未经授权的访问。 **你会看到：**“disconnected (1008): pairing required” @@ -57,95 +57,96 @@ Control UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单 -如果浏览器使用更改后的认证详细信息（角色/作用域/公钥）重试配对，之前的待处理请求会被取代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。 +如果浏览器使用已更改的身份验证详情（角色/范围/公钥）重试配对，先前的待处理请求会被取代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。 -如果浏览器已配对，而你将其从读取访问改为写入/管理员访问，这会被视为批准升级，而不是静默重新连接。OpenClaw 会保持旧批准有效，阻止权限更广的重新连接，并要求你显式批准新的作用域集合。 +如果浏览器已配对，而你将其从读取访问改为写入/管理员访问，这会被视为批准升级，而不是静默重连。OpenClaw 会保持旧批准有效，阻止更高权限的重连，并要求你显式批准新的范围集合。 -批准后，设备会被记住，除非你使用 `openclaw devices revoke --device --role ` 撤销它，否则无需重新批准。有关令牌轮换和撤销，请参阅 [设备 CLI](/zh-CN/cli/devices)。 +批准后，该设备会被记住，除非你使用 `openclaw devices revoke --device --role ` 撤销它，否则不需要重新批准。关于令牌轮换和撤销，请参阅[设备 CLI](/zh-CN/cli/devices)。 -- 直接的 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动批准。 -- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过，且浏览器提供其设备身份时，Tailscale Serve 可以为 Control UI 操作员会话跳过配对往返。 -- 直接 Tailnet 绑定、LAN 浏览器连接以及没有设备身份的浏览器配置文件仍需要显式批准。 -- 每个浏览器配置文件都会生成唯一设备 ID，因此切换浏览器或清除浏览器数据将需要重新配对。 +- 直接 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动批准。 +- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过且浏览器提供其设备身份时，Tailscale Serve 可以为控制 UI 操作员会话跳过配对往返。 +- 直接 Tailnet 绑定、局域网浏览器连接以及没有设备身份的浏览器配置文件仍需要显式批准。 +- 每个浏览器配置文件都会生成唯一设备 ID，因此切换浏览器或清除浏览器数据都需要重新配对。 ## 个人身份（浏览器本地） -Control UI 支持按浏览器设置的个人身份（显示名称和头像），并将其附加到发出的消息上，以便在共享会话中标识来源。它存放在浏览器存储中，作用域限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务端持久化，除了你实际发送的消息上的正常转录作者元数据之外。清除站点数据或切换浏览器会将其重置为空。 +控制 UI 支持按浏览器保存的个人身份（显示名称和头像），并将其附加到外发消息中，用于共享会话中的归属标识。它存储在浏览器存储中，作用域限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务器端持久保存，但你实际发送的消息仍会保留正常的转录作者元数据。清除站点数据或切换浏览器会将其重置为空。 -同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖 Gateway 网关解析出的身份，并且绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍可供直接写入该字段的非 UI 客户端使用（例如脚本化 Gateway 网关或自定义仪表板）。 +同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器上覆盖 Gateway 网关解析出的身份，并且绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍可供直接写入该字段的非 UI 客户端使用（例如脚本化 Gateway 网关或自定义仪表盘）。 ## 运行时配置端点 -Control UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点受到与 HTTP 其余表面相同的 Gateway 网关认证保护：未认证的浏览器无法获取它，成功获取需要已有有效的 Gateway 网关令牌/密码、Tailscale Serve 身份或受信代理身份。 +控制 UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点与其余 HTTP 表面一样受 Gateway 网关身份验证保护：未认证的浏览器无法获取它，成功获取需要已有有效的 Gateway 网关令牌/密码、Tailscale Serve 身份，或 trusted-proxy 身份。 ## 语言支持 -Control UI 可以在首次加载时根据你的浏览器区域设置进行本地化。若要稍后覆盖它，请打开 **概览 -> Gateway 网关访问 -> 语言**。区域设置选择器位于 Gateway 网关访问卡片中，而不是外观下。 +控制 UI 可以在首次加载时根据你的浏览器区域设置进行本地化。若要之后覆盖它，请打开 **概览 -> Gateway 网关访问 -> 语言**。区域设置选择器位于 Gateway 网关访问卡片中，而不是外观下。 - 支持的区域设置：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`ar`、`it`、`tr`、`uk`、`id`、`pl`、`th`、`vi`、`nl`、`fa` -- 非英语翻译会在浏览器中懒加载。 -- 选定的区域设置会保存在浏览器存储中，并在后续访问时复用。 -- 缺失的翻译键会回退到英语。 +- 非英文翻译会在浏览器中延迟加载。 +- 选中的区域设置会保存在浏览器存储中，并在后续访问时复用。 +- 缺失的翻译键会回退到英文。 -文档翻译会为同一组非英语区域设置生成，但文档站点内置的 Mintlify 语言选择器受限于 Mintlify 接受的区域设置代码。泰语（`th`）和波斯语（`fa`）文档仍会在发布仓库中生成；在 Mintlify 支持这些代码之前，它们可能不会出现在该选择器中。 +文档翻译会为同一组非英文区域设置生成，但文档站点内置的 Mintlify 语言选择器仅限于 Mintlify 接受的区域设置代码。泰语（`th`）和波斯语（`fa`）文档仍会在发布仓库中生成；在 Mintlify 支持这些代码之前，它们可能不会出现在该选择器中。 ## 外观主题 -外观面板保留内置的 Claw、Knot 和 Dash 主题，以及一个浏览器本地 tweakcn 导入槽。若要导入主题，请打开 [tweakcn themes](https://tweakcn.com/themes)，选择或创建一个主题，点击 **分享**，然后将复制的主题链接粘贴到外观中。导入器也接受 `https://tweakcn.com/r/themes/` 注册表 URL、类似 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的编辑器 URL、相对 `/themes/` 路径、原始主题 ID，以及默认主题名称，例如 `amethyst-haze`。 +外观面板保留内置的 Claw、Knot 和 Dash 主题，外加一个浏览器本地的 tweakcn 导入槽。若要导入主题，请打开 [tweakcn themes](https://tweakcn.com/themes)，选择或创建主题，点击**分享**，然后将复制的主题链接粘贴到外观中。导入器还接受 `https://tweakcn.com/r/themes/` 注册表 URL、类似 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的编辑器 URL、相对 `/themes/` 路径、原始主题 ID，以及 `amethyst-haze` 等默认主题名称。 -导入的主题只存储在当前浏览器配置文件中。它们不会写入 Gateway 网关配置，也不会跨设备同步。替换导入的主题会更新这一个本地槽；如果当前选中的是导入主题，清除它会将活动主题切回 Claw。 +导入的主题只会存储在当前浏览器配置文件中。它们不会写入 Gateway 网关配置，也不会跨设备同步。替换导入的主题会更新这一个本地槽；如果已选择导入主题，清除它会将活动主题切回 Claw。 ## 它现在能做什么 - 通过 Gateway 网关 WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）。 - - 通过浏览器实时会话进行语音对话。OpenAI 使用直接 WebRTC，Google Live 使用通过 WebSocket 传递的受限一次性浏览器令牌，而仅后端的实时语音插件使用 Gateway 网关中继传输。中继会将提供商凭证保留在 Gateway 网关上，同时浏览器通过 `talk.realtime.relay*` RPC 流式传输麦克风 PCM，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用发送回配置的更大 OpenClaw 模型。 - - 在聊天中流式传输工具调用和实时工具输出卡片（智能体事件）。 + - 使用服务器端 STT 向聊天输入框听写（`chat.transcribeAudio`）。浏览器会录制一段较短的麦克风片段并发送给 Gateway 网关，Gateway 网关运行已配置的 `tools.media.audio` 转写流水线，并返回草稿文本，而不会向浏览器暴露提供商凭据。 + - 通过浏览器实时会话进行语音对话。OpenAI 使用直接 WebRTC，Google Live 通过 WebSocket 使用受限的一次性浏览器令牌，且仅后端的实时语音插件使用 Gateway 网关中继传输。中继会将提供商凭据保留在 Gateway 网关上，同时浏览器通过 `talk.realtime.relay*` RPC 流式传输麦克风 PCM，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用发回给配置的更大 OpenClaw 模型。 + - 在聊天中流式传输工具调用 + 实时工具输出卡片（智能体事件）。 - - 渠道：内置以及内置/外部插件渠道状态、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。 - - 实例：在线状态列表 + 刷新（`system-presence`）。 - - 会话：列表 + 按会话设置模型/thinking/fast/verbose/trace/reasoning 覆盖（`sessions.list`、`sessions.patch`）。 - - 梦境：Dreaming 状态、启用/禁用开关，以及 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。 + - 渠道：内置以及捆绑/外部插件渠道 Status、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。 + - 实例：在线列表 + 刷新（`system-presence`）。 + - 会话：列表 + 按会话设置模型/思考/快速/详细/跟踪/推理覆盖项（`sessions.list`、`sessions.patch`）。 + - 梦境：Dreaming Status、启用/禁用切换，以及 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。 - Cron 作业：列出/添加/编辑/运行/启用/禁用 + 运行历史（`cron.*`）。 - - Skills：状态、启用/禁用、安装、API key 更新（`skills.*`）。 + - Skills：Status、启用/禁用、安装、API key 更新（`skills.*`）。 - 节点：列表 + 能力（`node.list`）。 - - Exec 批准：编辑 Gateway 网关或节点允许列表 + `exec host=gateway/node` 的询问策略（`exec.approvals.*`）。 + - exec 批准：编辑 Gateway 网关或节点 allowlist + `exec host=gateway/node` 的询问策略（`exec.approvals.*`）。 - 查看/编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。 - - 使用验证进行应用 + 重启（`config.apply`），并唤醒最后一个活动会话。 - - 写入包含 base-hash 保护，以防覆盖并发编辑。 - - 写入（`config.set`/`config.apply`/`config.patch`）会对提交的配置载荷中的引用预检活动 SecretRef 解析；未解析的活动已提交引用会在写入前被拒绝。 - - Schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；仅当快照具有安全的原始往返时，Raw JSON 编辑器才可用。 - - 如果快照无法安全往返原始文本，Control UI 会强制使用表单模式，并为该快照禁用 Raw 模式。 - - Raw JSON 编辑器的“重置为已保存”会保留原始作者编辑的形状（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此当快照可以安全往返时，外部编辑会在重置后保留下来。 - - 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，以防止意外的对象到字符串损坏。 + - 通过验证应用 + 重启（`config.apply`），并唤醒最后一个活动会话。 + - 写入包含 base-hash 防护，防止覆盖并发编辑。 + - 写入（`config.set`/`config.apply`/`config.patch`）会对提交的配置载荷中的引用预先解析活动 SecretRef；未解析的活动提交引用会在写入前被拒绝。 + - schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；仅当快照具有安全的原始往返能力时，Raw JSON 编辑器才可用。 + - 如果快照无法安全地往返原始文本，控制 UI 会强制使用表单模式，并为该快照禁用原始模式。 + - Raw JSON 编辑器的“重置为已保存”会保留原始编辑形状（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此当快照可以安全往返时，外部编辑能在重置后保留下来。 + - 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，防止意外发生对象到字符串的损坏。 - - 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）。 - - 日志：带过滤/导出的 Gateway 网关文件日志实时尾随（`logs.tail`）。 - - 更新：运行包/git 更新 + 重启（`update.run`）并生成重启报告，然后在重新连接后轮询 `update.status`，以验证正在运行的 Gateway 网关版本。 + - 调试：Status/health/models 快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）。 + - 日志：带过滤/导出的 Gateway 网关文件日志实时 tail（`logs.tail`）。 + - 更新：运行包/git 更新 + 重启（`update.run`）并生成重启报告，然后在重连后轮询 `update.status`，以验证正在运行的 Gateway 网关版本。 - - 对于隔离作业，投递默认会发布摘要。如果你只想进行内部运行，可以切换为无。 - - 选择发布时会显示渠道/目标字段。 + - 对于隔离作业，投递默认是发布摘要。如果你想要仅内部运行，可以切换为无。 + - 当选择发布时，会显示渠道/目标字段。 - Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。 - - 对于主会话作业，webhook 和无投递模式均可用。 - - 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/thinking 覆盖，以及尽力投递开关。 - - 表单验证会以内联方式显示字段级错误；无效值会禁用保存按钮，直到修正。 - - 设置 `cron.webhookToken` 可发送专用 bearer token；如果省略，webhook 会在不带认证标头的情况下发送。 + - 对于主会话作业，可以使用 webhook 和无投递模式。 + - 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/思考覆盖项，以及尽力投递切换。 + - 表单验证以内联方式显示字段级错误；无效值会禁用保存按钮，直到修复为止。 + - 设置 `cron.webhookToken` 可发送专用 bearer 令牌；如果省略，webhook 发送时不会附带身份验证标头。 - 已弃用的回退：存储的旧版作业如果带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。 @@ -155,53 +156,54 @@ Control UI 可以在首次加载时根据你的浏览器区域设置进行本地 - - `chat.send` 是**非阻塞**的：它会立即返回确认 `{ runId, status: "started" }`，响应通过 `chat` 事件流式传输。 - - 聊天上传接受图片以及非视频文件。图片保留原生图片路径；其他文件会作为托管媒体存储，并在历史记录中显示为附件链接。 - - 使用相同的 `idempotencyKey` 重新发送时，运行中会返回 `{ status: "in_flight" }`，完成后会返回 `{ status: "ok" }`。 - - 出于 UI 安全考虑，`chat.history` 响应有大小限制。当转录条目过大时，Gateway 网关可能会截断长文本字段、省略较重的元数据块，并用占位符（`[chat.history omitted: message too large]`）替换超大的消息。 - - 助手/生成的图片会持久化为托管媒体引用，并通过经过身份验证的 Gateway 网关媒体 URL 返回，因此重新加载不依赖原始 base64 图片载荷继续保留在聊天历史响应中。 - - `chat.history` 还会从可见的助手文本中移除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 载荷（包括 `...`、`...`、`...`、`...` 以及被截断的工具调用块）、泄漏的 ASCII/全角模型控制 token，并省略整个可见文本仅为精确静默 token `NO_REPLY` / `no_reply` 的助手条目。 - - 在活动发送期间以及最终历史记录刷新时，如果 `chat.history` 短暂返回较旧的快照，聊天视图会继续显示本地乐观用户/助手消息；一旦 Gateway 网关历史记录追上，规范转录就会替换这些本地消息。 - - `chat.inject` 会向会话转录追加一条助手备注，并广播一个 `chat` 事件用于仅 UI 更新（无 Agent 运行，无渠道投递）。 - - 聊天标题中的模型和思考选择器会通过 `sessions.patch` 立即修补活动会话；它们是持久的会话覆盖项，而不是仅限单轮的发送选项。 - - 在 Control UI 中输入 `/new` 会创建并切换到与 New Chat 相同的全新仪表板会话。输入 `/reset` 会保留 Gateway 网关针对当前会话的显式原地重置。 - - 聊天模型选择器会请求 Gateway 网关配置的模型视图。如果存在 `agents.defaults.models`，该允许列表会驱动选择器。否则，选择器会显示显式的 `models.providers.*.models` 条目，以及具有可用认证的提供商。完整目录仍可通过调试 `models.list` RPC 使用 `view: "all"` 访问。 - - 当新的 Gateway 网关会话用量报告显示上下文压力较高时，聊天撰写区域会显示上下文提示，并且在推荐的压缩级别显示一个压缩按钮，用于运行正常的会话压缩路径。过期的 token 快照会被隐藏，直到 Gateway 网关再次报告新的用量。 + - `chat.send` 是**非阻塞**的：它会立即用 `{ runId, status: "started" }` 确认，响应则通过 `chat` 事件流式传输。 + - `chat.transcribeAudio` 是用于 Chat 草稿的一次性听写辅助工具。它接受浏览器录制的 base64 音频，将上传大小控制在 Gateway 网关 WebSocket 帧限制以下，写入临时本地文件，使用当前 Gateway 网关配置运行媒体理解音频转录，返回 `{ text, provider, model }`，并移除临时文件。它不会创建智能体运行，并且与实时 Talk 分离。 + - Chat 上传支持图片和非视频文件。图片保留原生图片路径；其他文件会作为托管媒体存储，并在历史记录中显示为附件链接。 + - 使用相同 `idempotencyKey` 重新发送时，运行中会返回 `{ status: "in_flight" }`，完成后会返回 `{ status: "ok" }`。 + - `chat.history` 响应会限制大小，以保证 UI 安全。当转录条目过大时，Gateway 网关可能会截断长文本字段，省略较重的元数据块，并用占位符（`[chat.history omitted: message too large]`）替换超大消息。 + - 助手/生成的图片会持久化为托管媒体引用，并通过经过身份验证的 Gateway 网关媒体 URL 提供回来，因此重新加载不依赖原始 base64 图片载荷继续保留在聊天历史响应中。 + - `chat.history` 还会从可见助手文本中移除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 载荷（包括 `...`、`...`、`...`、`...` 和被截断的工具调用块），以及泄露的 ASCII/全角模型控制 token，并会省略整个可见文本仅为精确静默 token `NO_REPLY` / `no_reply` 的助手条目。 + - 在一次活动发送和最终历史刷新期间，如果 `chat.history` 短暂返回较旧的快照，聊天视图会继续显示本地乐观用户/助手消息；一旦 Gateway 网关历史记录追上，规范转录会替换这些本地消息。 + - `chat.inject` 会向会话转录追加一条助手备注，并广播一个 `chat` 事件，用于仅 UI 更新（无智能体运行、无渠道投递）。 + - 聊天标题栏中的模型和思考选择器会通过 `sessions.patch` 立即修补活动会话；它们是持久会话覆盖项，不是仅限单轮的发送选项。 + - 在 Control UI 中输入 `/new` 会创建并切换到与 New Chat 相同的新仪表板会话。输入 `/reset` 会保留 Gateway 网关对当前会话的显式原地重置。 + - 聊天模型选择器会请求 Gateway 网关已配置的模型视图。如果存在 `agents.defaults.models`，该允许列表会驱动选择器。否则，选择器会显示显式 `models.providers.*.models` 条目以及具备可用认证的提供商。完整目录仍可通过调试 `models.list` RPC 使用 `view: "all"` 访问。 + - 当新鲜 Gateway 网关会话用量报告显示上下文压力较高时，聊天输入区域会显示上下文提示；在建议压缩级别下，还会显示一个紧凑按钮，用于运行正常的会话压缩路径。陈旧的 token 快照会被隐藏，直到 Gateway 网关再次报告新鲜用量。 - - 通话模式使用已注册的实时语音提供商。配置 OpenAI 时使用 `talk.provider: "openai"` 加 `talk.providers.openai.apiKey`，或配置 Google 时使用 `talk.provider: "google"` 加 `talk.providers.google.apiKey`；Voice Call 实时提供商配置仍可作为后备复用。浏览器绝不会收到标准提供商 API key。OpenAI 会收到用于 WebRTC 的临时 Realtime 客户端密钥。Google Live 会收到用于浏览器 WebSocket 会话的一次性受限 Live API 认证 token，其中指令和工具声明由 Gateway 网关锁定到该 token 中。仅公开后端实时桥接的提供商会通过 Gateway 网关中继传输运行，因此凭证和供应商 socket 保持在服务器端，而浏览器音频通过经过身份验证的 Gateway 网关 RPC 移动。Realtime 会话提示由 Gateway 网关组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。 + + Talk 模式使用已注册的实时语音提供商。使用 `talk.provider: "openai"` 加 `talk.providers.openai.apiKey` 配置 OpenAI，或使用 `talk.provider: "google"` 加 `talk.providers.google.apiKey` 配置 Google；Voice Call 实时提供商配置仍可作为回退复用。浏览器永远不会收到标准提供商 API key。OpenAI 会收到用于 WebRTC 的临时 Realtime 客户端密钥。Google Live 会收到用于浏览器 WebSocket 会话的一次性受限 Live API 认证 token，其中指令和工具声明由 Gateway 网关锁定到该 token 中。仅暴露后端实时桥接的提供商会通过 Gateway 网关中继传输运行，因此凭据和厂商套接字保持在服务端，而浏览器音频通过经过身份验证的 Gateway 网关 RPC 传输。Realtime 会话提示由 Gateway 网关组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。 - 在 Chat 撰写器中，Talk 控件是麦克风听写按钮旁边的波形按钮。Talk 启动时，撰写器状态行先显示 `Connecting Talk...`，音频连接后显示 `Talk live`，或者当实时工具调用正在通过 `chat.send` 咨询配置的更大模型时显示 `Asking OpenClaw...`。 + 在 Chat 输入框中，Talk 控件是麦克风听写按钮旁边的波形按钮。Talk 启动时，输入框状态行会显示 `Connecting Talk...`，随后在音频已连接时显示 `Talk live`，或在实时工具调用通过 `chat.send` 咨询已配置的更大模型时显示 `Asking OpenClaw...`。 - 维护者实时冒烟测试：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 浏览器 WebRTC SDP 交换、Google Live 受限 token 浏览器 WebSocket 设置，以及使用伪麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只打印提供商状态，不记录密钥。 + 维护者实时 smoke：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 浏览器 WebRTC SDP 交换、Google Live 受限 token 浏览器 WebSocket 设置，以及带模拟麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只打印提供商状态，不会记录密钥。 - 点击 **Stop**（调用 `chat.abort`）。 - - 运行处于活动状态时，普通后续消息会进入队列。点击队列消息上的 **Steer**，可将该后续消息注入正在运行的轮次。 - - 输入 `/stop`（或独立的中止短语，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）进行带外中止。 - - `chat.abort` 支持 `{ sessionKey }`（无 `runId`）来中止该会话的所有活动运行。 + - 当运行处于活动状态时，普通后续消息会排队。点击排队消息上的 **Steer**，将该后续消息注入正在运行的轮次。 + - 输入 `/stop`（或独立的中止短语，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）以带外中止。 + - `chat.abort` 支持 `{ sessionKey }`（无 `runId`），用于中止该会话的所有活动运行。 - - - 当运行被中止时，部分助手文本仍可在 UI 中显示。 - - 当存在缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史中。 - - 持久化条目包含中止元数据，以便转录消费者区分中止部分与正常完成输出。 + + - 运行被中止时，部分助手文本仍可显示在 UI 中。 + - 当存在缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史记录中。 + - 持久化条目包含中止元数据，因此转录消费者可以区分中止部分和正常完成输出。 -## PWA 安装和 Web 推送 +## PWA 安装和 Web Push -Control UI 随附一个 `manifest.webmanifest` 和一个 service worker，因此现代浏览器可以将其安装为独立 PWA。即使标签页或浏览器窗口未打开，Web Push 也能让 Gateway 网关通过通知唤醒已安装的 PWA。 +Control UI 随附 `manifest.webmanifest` 和 service worker，因此现代浏览器可以将其安装为独立 PWA。Web Push 让 Gateway 网关即使在标签页或浏览器窗口未打开时，也能通过通知唤醒已安装的 PWA。 | 表面 | 作用 | | ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | PWA manifest。浏览器在可访问后会提供 “Install app”。 | -| `ui/public/sw.js` | 处理 `push` 事件和通知点击的 service worker。 | -| `push/vapid-keys.json`（位于 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于签名 Web Push 载荷。 | -| `push/web-push-subscriptions.json` | 持久化的浏览器订阅端点。 | +| `ui/public/manifest.webmanifest` | PWA 清单。浏览器在可访问后会提供 “Install app”。 | +| `ui/public/sw.js` | 处理 `push` 事件和通知点击的 service worker。 | +| `push/vapid-keys.json`（位于 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于签名 Web Push 载荷。 | +| `push/web-push-subscriptions.json` | 持久化的浏览器订阅端点。 | 当你想固定密钥（用于多主机部署、密钥轮换或测试）时，可通过 Gateway 网关进程上的环境变量覆盖 VAPID 密钥对： @@ -211,28 +213,28 @@ Control UI 随附一个 `manifest.webmanifest` 和一个 service worker，因此 Control UI 使用这些受作用域限制的 Gateway 网关方法来注册和测试浏览器订阅： -- `push.web.vapidPublicKey` — 获取活动的 VAPID 公钥。 +- `push.web.vapidPublicKey` — 获取当前 VAPID 公钥。 - `push.web.subscribe` — 注册一个 `endpoint` 以及 `keys.p256dh`/`keys.auth`。 - `push.web.unsubscribe` — 移除已注册的端点。 - `push.web.test` — 向调用方的订阅发送测试通知。 -Web Push 独立于 iOS APNS 中继路径（参见 [配置](/zh-CN/gateway/configuration) 了解由中继支持的推送）以及现有的 `push.test` 方法，后者面向原生移动端配对。 +Web Push 独立于 iOS APNS 中继路径（参见[配置](/zh-CN/gateway/configuration)了解基于中继的推送）以及现有的 `push.test` 方法，后两者面向原生移动端配对。 ## 托管嵌入 -助手消息可以使用 `[embed ...]` shortcode 内联渲染托管 Web 内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制： +助手消息可以使用 `[embed ...]` 短代码内联渲染托管网页内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制： - + 禁用托管嵌入中的脚本执行。 - - 在保持来源隔离的同时允许交互式嵌入；这是默认值，通常足以用于自包含的浏览器游戏/小组件。 + + 允许交互式嵌入，同时保持来源隔离；这是默认值，通常足以用于自包含的浏览器游戏/小组件。 - - 在 `allow-scripts` 之上为有意需要更强权限的同站文档添加 `allow-same-origin`。 + + 在 `allow-scripts` 之上添加 `allow-same-origin`，用于有意需要更强权限的同站文档。 @@ -249,14 +251,14 @@ Web Push 独立于 iOS APNS 中继路径（参见 [配置](/zh-CN/gateway/config ``` -仅在嵌入文档确实需要同源行为时使用 `trusted`。对于大多数 Agent 生成的游戏和交互式 canvas，`scripts` 是更安全的选择。 +仅在嵌入文档确实需要同源行为时使用 `trusted`。对于大多数智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。 -默认情况下，绝对外部 `http(s)` 嵌入 URL 仍会被阻止。如果你有意让 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。 +默认情况下，绝对外部 `http(s)` 嵌入 URL 仍会被阻止。如果你有意希望 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。 ## 聊天消息宽度 -分组聊天消息使用易读的默认最大宽度。宽屏显示器部署可以通过设置 `gateway.controlUi.chatMessageMaxWidth` 覆盖它，而无需修补内置 CSS： +分组聊天消息使用便于阅读的默认最大宽度。宽屏部署可以通过设置 `gateway.controlUi.chatMessageMaxWidth` 覆盖它，而无需修补内置 CSS： ```json5 { @@ -284,12 +286,12 @@ Web Push 独立于 iOS APNS 中继路径（参见 [配置](/zh-CN/gateway/config - `https:///`（或你配置的 `gateway.controlUi.basePath`） - 默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行身份验证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与该标头匹配来验证身份，并且仅在请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时接受这些身份。对于具有浏览器设备身份的 Control UI 操作者会话，这条已验证的 Serve 路径还会跳过设备配对往返；无设备浏览器和节点角色连接仍会遵循正常的设备检查。如果你想即使对 Serve 流量也要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。 + 默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行身份验证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与标头匹配来验证身份，并且只有当请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时才接受这些身份。对于具有浏览器设备身份的 Control UI 操作员会话，这条经过验证的 Serve 路径还会跳过设备配对往返；无设备浏览器和节点角色连接仍遵循正常设备检查。如果你希望即使对 Serve 流量也要求显式共享密钥凭据，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。 - 对于该异步 Serve 身份路径，同一客户端 IP 和认证作用域的失败认证尝试会在写入速率限制前被串行化。因此，同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配并行竞态。 + 对于该异步 Serve 身份路径，同一客户端 IP 和认证作用域的失败认证尝试会在写入速率限制前串行化。因此，来自同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配并行竞争。 - 无 token 的 Serve 认证假定 gateway 主机可信。如果不受信任的本地代码可能在该主机上运行，请要求 token/password 认证。 + 无 token Serve 认证假定 Gateway 网关主机是可信的。如果该主机上可能运行不受信任的本地代码，请要求 token/password 认证。 @@ -307,20 +309,20 @@ Web Push 独立于 iOS APNS 中继路径（参见 [配置](/zh-CN/gateway/config -## 不安全 HTTP +## 不安全的 HTTP -如果你通过纯 HTTP（`http://` 或 `http://`）打开仪表板，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。 +如果你通过明文 HTTP（`http://` 或 `http://`）打开仪表板，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。 已记录的例外： -- 使用 `gateway.controlUi.allowInsecureAuth=true` 的仅 localhost 不安全 HTTP 兼容性 -- 通过 `gateway.auth.mode: "trusted-proxy"` 成功进行的操作者 Control UI 认证 -- 破窗选项 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- 仅限 localhost 的非安全 HTTP 兼容性，使用 `gateway.controlUi.allowInsecureAuth=true` +- 通过 `gateway.auth.mode: "trusted-proxy"` 成功完成操作员控制界面认证 +- 紧急破窗选项 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` -**推荐修复：** 使用 HTTPS（Tailscale Serve）或在本地打开 UI： +**推荐修复：**使用 HTTPS（Tailscale Serve）或在本地打开 UI： - `https:///`（Serve） -- `http://127.0.0.1:18789/`（在 gateway 主机上） +- `http://127.0.0.1:18789/`（在 Gateway 网关主机上） @@ -336,12 +338,12 @@ Web Push 独立于 iOS APNS 中继路径（参见 [配置](/zh-CN/gateway/config `allowInsecureAuth` 只是本地兼容性开关： - - 它允许 localhost Control UI 会话在非安全 HTTP 上下文中无需设备身份即可继续。 + - 它允许 localhost 控制界面会话在非安全 HTTP 上下文中无需设备身份即可继续。 - 它不会绕过配对检查。 - 它不会放宽远程（非 localhost）设备身份要求。 - + ```json5 { gateway: { @@ -353,42 +355,42 @@ Web Push 独立于 iOS APNS 中继路径（参见 [配置](/zh-CN/gateway/config ``` - `dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，这是严重的安全降级。紧急使用后请尽快恢复。 + `dangerouslyDisableDeviceAuth` 会禁用控制界面设备身份检查，是严重的安全降级。紧急使用后请尽快恢复。 - - - 成功的受信任代理认证可以允许没有设备身份的 **operator** Control UI 会话进入。 - - 这**不**适用于 node-role Control UI 会话。 - - 同主机 local loopback 反向代理仍然不满足受信任代理认证；参见[受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)。 + + - 成功的可信代理认证可以允许**操作员**控制界面会话无需设备身份进入。 + - 这**不**扩展到节点角色控制界面会话。 + - 同主机 loopback 反向代理仍然不满足可信代理认证；参见[可信代理认证](/zh-CN/gateway/trusted-proxy-auth)。 -有关 HTTPS 设置指南，请参见 [Tailscale](/zh-CN/gateway/tailscale)。 +有关 HTTPS 设置指导，请参见 [Tailscale](/zh-CN/gateway/tailscale)。 ## 内容安全策略 -Control UI 附带严格的 `img-src` 策略：只允许**同源**资源、`data:` URL，以及本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络获取。 +控制界面随附严格的 `img-src` 策略：只允许**同源**资产、`data:` URL 和本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络请求。 -这在实践中意味着： +这在实践中的含义： - 通过相对路径提供的头像和图片（例如 `/avatars/`）仍会渲染，包括 UI 获取并转换为本地 `blob:` URL 的已认证头像路由。 - 内联 `data:image/...` URL 仍会渲染（对协议内载荷很有用）。 -- Control UI 创建的本地 `blob:` URL 仍会渲染。 -- 渠道元数据发出的远程头像 URL 会在 Control UI 的头像辅助逻辑中被剥离，并替换为内置 logo/badge，因此被入侵或恶意的渠道无法强制操作员浏览器获取任意远程图片。 +- 控制界面创建的本地 `blob:` URL 仍会渲染。 +- 渠道元数据发出的远程头像 URL 会在控制界面的头像辅助逻辑中被剥离，并替换为内置徽标/徽章，因此被攻陷或恶意的渠道无法强制操作员浏览器发起任意远程图片请求。 -你无需更改任何内容即可获得此行为——它始终启用且不可配置。 +你无需更改任何内容即可获得此行为，它始终启用且不可配置。 ## 头像路由认证 -配置 Gateway 网关认证后，Control UI 头像端点需要与 API 其余部分相同的 Gateway 网关令牌： +配置 Gateway 网关认证后，控制界面头像端点需要与 API 其余部分相同的 Gateway 网关 token： -- `GET /avatar/` 只向已认证调用方返回头像图片。`GET /avatar/?meta=1` 会按同一规则返回头像元数据。 -- 对任一路由的未认证请求都会被拒绝（与同级 assistant-media 路由一致）。这可以防止头像路由在原本受保护的主机上泄露智能体身份。 -- Control UI 本身在获取头像时会将 Gateway 网关令牌作为 bearer 头转发，并使用已认证的 blob URL，因此图片仍会在仪表盘中渲染。 +- `GET /avatar/` 只向已认证调用方返回头像图片。`GET /avatar/?meta=1` 按同样规则返回头像元数据。 +- 对任一路由的未认证请求都会被拒绝（与相邻的 assistant-media 路由一致）。这可以防止头像路由在其他方面受保护的主机上泄露智能体身份。 +- 控制界面本身在获取头像时会将 Gateway 网关 token 作为 bearer 标头转发，并使用已认证的 blob URL，因此图片仍会在仪表板中渲染。 -如果你禁用 Gateway 网关认证（不建议在共享主机上这样做），头像路由也会变为未认证状态，与 Gateway 网关其余部分保持一致。 +如果你禁用 Gateway 网关认证（不建议在共享主机上这样做），头像路由也会与 Gateway 网关其余部分一致变为未认证。 ## 构建 UI @@ -398,7 +400,7 @@ Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构 pnpm ui:build ``` -可选的绝对基路径（当你需要固定资源 URL 时）： +可选的绝对 base（当你需要固定资产 URL 时）： ```bash OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build @@ -414,7 +416,7 @@ pnpm ui:dev ## 调试/测试：开发服务器 + 远程 Gateway 网关 -Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 来源。当你想在本地使用 Vite 开发服务器，而 Gateway 网关在其他位置运行时，这很有用。 +控制界面是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP origin。当你想在本地使用 Vite 开发服务器，而 Gateway 网关在其他地方运行时，这会很方便。 @@ -427,7 +429,7 @@ Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 H http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ``` - 可选的一次性认证（如需要）： + 可选的一次性认证（如果需要）： ```text http://localhost:5173/?gatewayUrl=wss%3A%2F%2F%3A18789#token= @@ -438,17 +440,17 @@ Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 H - - `gatewayUrl` 会在加载后存储在 localStorage 中，并从 URL 中移除。 - - 如果你通过 `gatewayUrl` 传入完整的 `ws://` 或 `wss://` 端点，请对 `gatewayUrl` 值进行 URL 编码，确保浏览器能正确解析查询字符串。 - - 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，这可以避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数仍会为兼容性导入一次，但仅作为兜底，并会在引导后立即剥离。 - - `password` 仅保存在内存中。 - - 设置 `gatewayUrl` 后，UI 不会回退到配置或环境凭据。请显式提供 `token`（或 `password`）。缺少显式凭据是错误。 + - `gatewayUrl` 会在加载后存储到 localStorage 中，并从 URL 中移除。 + - 如果你通过 `gatewayUrl` 传入完整的 `ws://` 或 `wss://` 端点，请对 `gatewayUrl` 值进行 URL 编码，以便浏览器正确解析查询字符串。 + - 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，这可以避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数仍会为兼容性导入一次，但仅作为后备，并会在启动后立即剥离。 + - `password` 只保存在内存中。 + - 设置 `gatewayUrl` 后，UI 不会回退到配置或环境凭据。请显式提供 `token`（或 `password`）。缺少显式凭据会报错。 - 当 Gateway 网关位于 TLS 后面时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。 - - `gatewayUrl` 只会在顶级窗口中被接受（不可嵌入），以防止点击劫持。 - - 非 loopback 的 Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整 origin）。这包括远程开发设置。 - - Gateway 网关启动时可能会基于有效运行时绑定和端口播种本地 origin，例如 `http://localhost:` 和 `http://127.0.0.1:`，但远程浏览器 origin 仍需要显式条目。 - - 除了严格受控的本地测试，不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任何浏览器 origin，而不是“匹配我正在使用的任何主机”。 - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 头 origin 兜底模式，但这是危险的安全模式。 + - `gatewayUrl` 只会在顶层窗口中被接受（不可嵌入），以防止点击劫持。 + - 非 loopback 控制界面部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整 origin）。这包括远程开发设置。 + - Gateway 网关启动时可能会从实际运行时 bind 和端口种入本地 origin，例如 `http://localhost:` 和 `http://127.0.0.1:`，但远程浏览器 origin 仍需要显式条目。 + - 除了严格受控的本地测试外，请勿使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任何浏览器 origin，而不是“匹配我正在使用的任何主机”。 + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头 origin 后备模式，但这是危险的安全模式。 @@ -467,9 +469,9 @@ Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 H 远程访问设置详情：[远程访问](/zh-CN/gateway/remote)。 -## 相关内容 +## 相关 -- [仪表盘](/zh-CN/web/dashboard) — Gateway 网关仪表盘 +- [仪表板](/zh-CN/web/dashboard) — Gateway 网关仪表板 - [健康检查](/zh-CN/gateway/health) — Gateway 网关健康监控 - [TUI](/zh-CN/web/tui) — 终端用户界面 - [WebChat](/zh-CN/web/webchat) — 基于浏览器的聊天界面 diff --git a/docs/zh-CN/web/webchat.md b/docs/zh-CN/web/webchat.md index 198f5a6ec..44d689bf8 100644 --- a/docs/zh-CN/web/webchat.md +++ b/docs/zh-CN/web/webchat.md @@ -1,13 +1,13 @@ --- read_when: - - 调试或配置 WebChat 访问权限 -summary: 用于聊天 UI 的 Loopback WebChat 静态主机和 Gateway 网关 WS 用法 + - 调试或配置 WebChat 访问 +summary: 回环 WebChat 静态托管主机和聊天 UI 的 Gateway 网关 WS 用法 title: WebChat x-i18n: - generated_at: "2026-05-02T05:17:37Z" + generated_at: "2026-05-02T23:13:40Z" model: gpt-5.5 provider: openai - source_hash: fe6d3cb30ed18d651b0d0ca8fd188b47c5f1d186410ee340deb79315f194ed8d + source_hash: ad3a09c8962e3a6dda83716d319df7ba27e18105cee50721278b5cba0a85c52f source_path: web/webchat.md workflow: 16 --- @@ -16,7 +16,7 @@ Status：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway 网关 WebSocket 通信 ## 它是什么 -- 用于 Gateway 网关的原生聊天 UI（没有嵌入式浏览器，也没有本地静态服务器）。 +- 面向 Gateway 网关的原生聊天 UI（没有嵌入式浏览器，也没有本地静态服务器）。 - 使用与其他渠道相同的会话和路由规则。 - 确定性路由：回复始终返回到 WebChat。 @@ -24,48 +24,49 @@ Status：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway 网关 WebSocket 通信 1. 启动 Gateway 网关。 2. 打开 WebChat UI（macOS/iOS 应用）或 Control UI 聊天标签页。 -3. 确保已配置有效的 Gateway 网关身份验证路径（默认使用共享密钥， - 即使在 loopback 上也是如此）。 +3. 确保已配置有效的 Gateway 网关认证路径（默认使用共享密钥， + 即使在回环地址上也是如此）。 ## 工作方式（行为） -- UI 连接到 Gateway 网关 WebSocket，并使用 `chat.history`、`chat.send` 和 `chat.inject`。 -- 为了稳定性，`chat.history` 是有界的：Gateway 网关可能会截断长文本字段、省略体量较大的元数据，并用 `[chat.history omitted: message too large]` 替换过大的条目。 -- 对于现代仅追加会话文件，`chat.history` 会跟随活动转录分支，因此已放弃的重写分支和被取代的提示词副本不会在 WebChat 中渲染。 -- Control UI 会记住 `chat.history` 返回的后端 Gateway 网关 `sessionId`，并在后续 `chat.send` 调用中包含它，因此重新连接和页面刷新会继续同一个已存储对话，除非用户启动或重置会话。 -- Control UI 会在生成新的 `chat.send` 运行 id 之前，合并同一会话、消息和附件的重复进行中提交；Gateway 网关仍会对复用同一幂等键的重复请求进行去重。 -- `chat.history` 也会进行显示归一化：仅运行时的 OpenClaw 上下文、 - 入站信封包装、内联投递指令标签 - 例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`、纯文本工具调用 XML +- UI 连接到 Gateway 网关 WebSocket，并使用 `chat.history`、`chat.send`、`chat.inject` 和 `chat.transcribeAudio`。 +- 为了稳定性，`chat.history` 会受到限制：Gateway 网关可能会截断较长的文本字段，省略较重的元数据，并将超大的条目替换为 `[chat.history omitted: message too large]`。 +- 对于现代追加式会话文件，`chat.history` 会跟随活动的转录分支，因此废弃的重写分支和被取代的提示副本不会在 WebChat 中渲染。 +- Control UI 会记住 `chat.history` 返回的后端 Gateway 网关 `sessionId`，并在后续 `chat.send` 调用中包含它，因此重新连接和页面刷新会继续同一个已存储的对话，除非用户启动或重置会话。 +- Control UI 会在生成新的 `chat.send` 运行 ID 之前，合并同一会话、消息和附件的重复进行中提交；Gateway 网关仍会对复用相同幂等键的重复请求进行去重。 +- `chat.history` 也会进行显示归一化：仅运行时使用的 OpenClaw 上下文、 + 入站信封包装器、内联投递指令标签 + （例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 载荷（包括 `...`、 `...`、`...`、 - `...` 以及被截断的工具调用块），以及 - 泄漏的 ASCII/全角模型控制令牌都会从可见文本中剥离， - 并且如果助手条目的全部可见文本只是精确的静默令牌 - `NO_REPLY` / `no_reply`，该条目会被省略。 -- 标记为推理的回复载荷（`isReasoning: true`）会从 WebChat 助手内容、转录回放文本和音频内容块中排除，因此仅思考载荷不会显示为可见助手消息或可播放音频。 -- `chat.inject` 会将助手备注直接追加到转录中，并广播到 UI（不运行智能体）。 + `...` 和被截断的工具调用块），以及 + 泄漏的 ASCII/全角模型控制 token 都会从可见文本中移除， + 并且如果助手条目的全部可见文本只是精确的静默 + token `NO_REPLY` / `no_reply`，则会省略该条目。 +- 带推理标记的回复载荷（`isReasoning: true`）会从 WebChat 助手内容、转录回放文本和音频内容块中排除，因此仅用于思考的载荷不会以可见助手消息或可播放音频的形式呈现。 +- `chat.transcribeAudio` 支持 Control UI 聊天输入框中的服务器端听写。浏览器录制麦克风音频，将其以 base64 发送到 Gateway 网关，随后 Gateway 网关运行已配置的 `tools.media.audio` 流水线。返回的转录文本会插入草稿；在用户发送之前，不会启动任何智能体运行。 +- `chat.inject` 会将助手注记直接追加到转录中，并广播到 UI（不会启动智能体运行）。 - 已中止的运行可以让部分助手输出在 UI 中保持可见。 -- 当存在缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史中，并用中止元数据标记这些条目。 +- 当存在已缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史中，并用中止元数据标记这些条目。 - 历史始终从 Gateway 网关获取（不进行本地文件监听）。 -- 如果 Gateway 网关无法访问，WebChat 为只读模式。 +- 如果 Gateway 网关不可达，WebChat 将为只读。 ## Control UI 智能体工具面板 - Control UI `/agents` 工具面板有两个独立视图： - - **当前可用** 使用 `tools.effective(sessionKey=...)`，并显示当前 - 会话在运行时实际可用的内容，包括核心、插件和渠道拥有的工具。 + - **当前可用** 使用 `tools.effective(sessionKey=...)`，并展示当前 + 会话在运行时实际可以使用的内容，包括核心、插件和渠道拥有的工具。 - **工具配置** 使用 `tools.catalog`，并专注于配置文件、覆盖项和 目录语义。 -- 运行时可用性按会话限定。在同一智能体上切换会话可能会改变 +- 运行时可用性按会话划分作用域。在同一个智能体上切换会话可能会改变 **当前可用** 列表。 -- 配置编辑器并不意味着运行时可用；有效访问仍遵循策略 - 优先级（`allow`/`deny`，以及按智能体和提供商/渠道设置的覆盖项）。 +- 配置编辑器并不表示运行时可用；有效访问仍遵循策略 + 优先级（`allow`/`deny`，以及按智能体和提供商/渠道的覆盖项）。 ## 远程使用 - 远程模式通过 SSH/Tailscale 隧道传输 Gateway 网关 WebSocket。 -- 你无需运行单独的 WebChat 服务器。 +- 你不需要运行单独的 WebChat 服务器。 ## 配置参考（WebChat） @@ -73,20 +74,20 @@ Status：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway 网关 WebSocket 通信 WebChat 选项： -- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 响应中文本字段的最大字符数。当转录条目超过此限制时，Gateway 网关会截断长文本字段，并可能用占位符替换过大的消息。客户端也可以发送按请求设置的 `maxChars`，以便仅为单次 `chat.history` 调用覆盖此默认值。 +- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 响应中文本字段的最大字符数。当转录条目超过此限制时，Gateway 网关会截断较长的文本字段，并可能将超大的消息替换为占位符。客户端也可以发送每请求级别的 `maxChars`，以便为单次 `chat.history` 调用覆盖此默认值。 相关全局选项： - `gateway.port`、`gateway.bind`：WebSocket 主机/端口。 - `gateway.auth.mode`、`gateway.auth.token`、`gateway.auth.password`： - 共享密钥 WebSocket 身份验证。 + 共享密钥 WebSocket 认证。 - `gateway.auth.allowTailscale`：启用后，浏览器 Control UI 聊天标签页可以使用 Tailscale Serve 身份标头。 -- `gateway.auth.mode: "trusted-proxy"`：面向位于具备身份感知能力的**非 loopback**代理源后方的浏览器客户端的反向代理身份验证（参见 [可信代理身份验证](/zh-CN/gateway/trusted-proxy-auth)）。 +- `gateway.auth.mode: "trusted-proxy"`：面向位于具备身份感知能力的**非回环**代理源之后的浏览器客户端的反向代理认证（参见 [可信代理认证](/zh-CN/gateway/trusted-proxy-auth)）。 - `gateway.remote.url`、`gateway.remote.token`、`gateway.remote.password`：远程 Gateway 网关目标。 - `session.*`：会话存储和主键默认值。 ## 相关 - [Control UI](/zh-CN/web/control-ui) -- [仪表板](/zh-CN/web/dashboard) +- [Dashboard](/zh-CN/web/dashboard)