@gguf/claw 2026.2.1 → 2026.2.2

package/docs/zh-CN/tts.md

@@ -0,0 +1,380 @@
+---
+read_when:
+  - 为回复启用文字转语音
+  - 配置 TTS 提供商或限制
+  - 使用 /tts 命令
+summary: 用于出站回复的文字转语音（TTS）
+title: 文字转语音
+x-i18n:
+  generated_at: "2026-02-01T21:44:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 070ff0cc8592f64c6c9e4ddaddc7e8fba82f0692ceded6fe833ec9ba5b61e6fb
+  source_path: tts.md
+  workflow: 15
+---
+
+# 文字转语音（TTS）
+
+OpenClaw 可以使用 ElevenLabs、OpenAI 或 Edge TTS 将出站回复转换为音频。
+它适用于 OpenClaw 能发送音频的任何地方；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 或配额的公共网络服务，请将其视为尽力而为。如果你需要有保障的限额和支持，请使用 OpenAI 或 ElevenLabs。Microsoft 的 Speech REST API 文档记载了每次请求 10 分钟的音频限制；Edge TTS 没有公布限制，因此请假设类似或更低的限制。citeturn0search3
+
+## 可选密钥
+
+如果你需要使用 OpenAI 或 ElevenLabs：
+
+- `ELEVENLABS_API_KEY`（或 `XI_API_KEY`）
+- `OPENAI_API_KEY`
+
+Edge TTS **不**需要 API 密钥。如果未找到任何 API 密钥，OpenClaw 默认使用 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 配置位于 `openclaw.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: "~/.openclaw/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` **未设置**，OpenClaw 优先使用 `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`（默认：`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_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 输出格式失败，OpenClaw 会以 MP3 重试。
+
+OpenAI/ElevenLabs 格式是固定的；Telegram 需要 Opus 以获得语音消息体验。
+
+## 自动 TTS 行为
+
+启用后，OpenClaw：
+
+- 如果回复已包含媒体或 `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 的内置命令，因此 OpenClaw 在该平台注册 `/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 OpenClaw
+```
+
+注意事项：
+
+- 命令需要已授权的发送者（允许列表/所有者规则仍然适用）。
+- 必须启用 `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/tui.md

@@ -0,0 +1,166 @@
+---
+read_when:
+  - 你需要 TUI 的新手友好指南
+  - 你需要 TUI 功能、命令和快捷键的完整列表
+summary: 终端 UI（TUI）：从任何机器连接到 Gateway网关
+title: TUI
+x-i18n:
+  generated_at: "2026-02-01T21:43:58Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 4bf5b0037bbb3a166289f2f0a9399489637d4cf26335ae3577af9ea83eee747e
+  source_path: tui.md
+  workflow: 15
+---
+
+# TUI（终端 UI）
+
+## 快速开始
+
+1. 启动 Gateway网关。
+
+```bash
+openclaw gateway
+```
+
+2. 打开 TUI。
+
+```bash
+openclaw tui
+```
+
+3. 输入消息并按 Enter。
+
+远程 Gateway网关：
+
+```bash
+openclaw tui --url ws://<host>:<port> --token <gateway-token>
+```
+
+如果你的 Gateway网关使用密码认证，请使用 `--password`。
+
+## 界面概览
+
+- 头部：连接 URL、当前智能体、当前会话。
+- 聊天记录：用户消息、助手回复、系统通知、工具卡片。
+- 状态行：连接/运行状态（连接中、运行中、流式传输中、空闲、错误）。
+- 底栏：连接状态 + 智能体 + 会话 + 模型 + 思考/详细/推理 + token 计数 + 投递状态。
+- 输入框：带自动补全的文本编辑器。
+
+## 概念模型：智能体 + 会话
+
+- 智能体是唯一的标识符（例如 `main`、`research`）。Gateway网关提供可用列表。
+- 会话属于当前智能体。
+- 会话键存储为 `agent:<agentId>:<sessionKey>`。
+  - 如果你输入 `/session main`，TUI 会将其展开为 `agent:<currentAgent>:main`。
+  - 如果你输入 `/session agent:other:main`，则显式切换到该智能体会话。
+- 会话范围：
+  - `per-sender`（默认）：每个智能体有多个会话。
+  - `global`：TUI 始终使用 `global` 会话（选择器可能为空）。
+- 当前智能体 + 会话始终显示在底栏。
+
+## 发送与投递
+
+- 消息发送到 Gateway网关；默认不投递给提供商。
+- 开启投递：
+  - `/deliver on`
+  - 或通过设置面板
+  - 或启动时使用 `openclaw tui --deliver`
+
+## 选择器与覆盖层
+
+- 模型选择器：列出可用模型并设置会话覆盖。
+- 智能体选择器：选择不同的智能体。
+- 会话选择器：仅显示当前智能体的会话。
+- 设置：切换投递、工具输出展开和思考可见性。
+
+## 键盘快捷键
+
+- Enter：发送消息
+- Esc：中止活跃运行
+- Ctrl+C：清除输入（按两次退出）
+- Ctrl+D：退出
+- Ctrl+L：模型选择器
+- Ctrl+G：智能体选择器
+- Ctrl+P：会话选择器
+- Ctrl+O：切换工具输出展开
+- Ctrl+T：切换思考可见性（重新加载历史记录）
+
+## 斜杠命令
+
+核心：
+
+- `/help`
+- `/status`
+- `/agent <id>`（或 `/agents`）
+- `/session <key>`（或 `/sessions`）
+- `/model <provider/model>`（或 `/models`）
+
+会话控制：
+
+- `/think <off|minimal|low|medium|high>`
+- `/verbose <on|full|off>`
+- `/reasoning <on|off|stream>`
+- `/usage <off|tokens|full>`
+- `/elevated <on|off|ask|full>`（别名：`/elev`）
+- `/activation <mention|always>`
+- `/deliver <on|off>`
+
+会话生命周期：
+
+- `/new` 或 `/reset`（重置会话）
+- `/abort`（中止活跃运行）
+- `/settings`
+- `/exit`
+
+其他 Gateway网关斜杠命令（例如 `/context`）会转发到 Gateway网关并显示为系统输出。请参阅[斜杠命令](/tools/slash-commands)。
+
+## 本地 shell 命令
+
+- 在行首加 `!` 可在 TUI 主机上运行本地 shell 命令。
+- TUI 每个会话会提示一次以允许本地执行；拒绝后 `!` 在该会话中保持禁用。
+- 命令在 TUI 工作目录中的全新非交互式 shell 中运行（无持久化的 `cd`/env）。
+- 单独的 `!` 作为普通消息发送；前导空格不会触发本地执行。
+
+## 工具输出
+
+- 工具调用以卡片形式显示，包含参数和结果。
+- Ctrl+O 在折叠/展开视图之间切换。
+- 工具运行时，部分更新会流式输出到同一卡片。
+
+## 历史记录与流式传输
+
+- 连接时，TUI 加载最新历史记录（默认 200 条消息）。
+- 流式响应实时更新，直到最终确认。
+- TUI 还会监听智能体工具事件以提供更丰富的工具卡片。
+
+## 连接详情
+
+- TUI 以 `mode: "tui"` 注册到 Gateway网关。
+- 重新连接时显示系统消息；事件间隙会在日志中显示。
+
+## 选项
+
+- `--url <url>`：Gateway网关 WebSocket URL（默认使用配置或 `ws://127.0.0.1:<port>`）
+- `--token <token>`：Gateway网关令牌（如需要）
+- `--password <password>`：Gateway网关密码（如需要）
+- `--session <key>`：会话键（默认：`main`，全局范围时为 `global`）
+- `--deliver`：将助手回复投递给提供商（默认关闭）
+- `--thinking <level>`：覆盖发送时的思考级别
+- `--timeout-ms <ms>`：智能体超时时间（毫秒，默认为 `agents.defaults.timeoutSeconds`）
+
+## 故障排除
+
+发送消息后没有输出：
+
+- 在 TUI 中运行 `/status` 确认 Gateway网关已连接且处于空闲/忙碌状态。
+- 检查 Gateway网关日志：`openclaw logs --follow`。
+- 确认智能体可以运行：`openclaw status` 和 `openclaw models status`。
+- 如果你期望消息出现在聊天渠道中，请启用投递（`/deliver on` 或 `--deliver`）。
+- `--history-limit <n>`：要加载的历史记录条目数（默认 200）
+
+## 故障排除
+
+- `disconnected`：确保 Gateway网关正在运行且你的 `--url/--token/--password` 正确。
+- 选择器中没有智能体：检查 `openclaw agents list` 和你的路由配置。
+- 会话选择器为空：你可能处于全局范围或尚无会话。

package/docs/zh-CN/vps.md

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