dlinkclaw-openclaw 1.0.0

package/dist/src/utils.d.ts

@@ -0,0 +1,20 @@
+export declare const readlineHandle: (filename: string, callback: (line: string) => void) => Promise<void>;
+export declare const getOpenclawPath: (...paths: string[]) => string;
+/**
+ * 2026-08-10 扩展能力（ext_capabilities）目录定位。
+ * 优先从插件包目录找（开发/本地路径），找不到则退回 ~/.openclaw/ext_capabilities。
+ */
+/**
+ * 2026-08-10 扩展能力（ext_capabilities）目录定位。
+ * 注意：插件是 ESM（"type": "module"），__dirname 未定义，必须用 import.meta.url 定位。
+ * 从当前文件向上查找含 package.json + ext_capabilities 的插件根目录，
+ * 同时保留 cwd / ~/.openclaw 作为兜底，兼容不同启动方式。
+ */
+export declare const getExtCapabilitiesDir: () => string;
+export declare const dtFormat: (dt: Date, fmt: string) => string;
+/**
+ * 生成指定长度的uuid
+ * @param {Object} len
+ * @param {Object} radix 2,10,16进制
+ */
+export declare const uuidStr: (len: number, radix?: number) => string;

package/dist/src/utils.js

@@ -0,0 +1,128 @@
+import fs from 'fs';
+import path, { join } from 'path';
+import os, { tmpdir } from 'os';
+import readline from 'readline';
+import { fileURLToPath } from 'url';
+import { copyFile, unlink } from 'fs/promises';
+export const readlineHandle = async (filename, callback) => {
+    //被免文件被锁导致gateway重启，需要复制一份副本
+    const tmpFile = join(tmpdir(), `traj-${uuidStr(36)}.jsonl`);
+    await copyFile(filename, tmpFile);
+    //直接读取副本内容
+    const rl = readline.createInterface({
+        input: fs.createReadStream(tmpFile),
+        crlfDelay: Infinity,
+    });
+    for await (const line of rl) {
+        if (!line.trim())
+            continue;
+        callback(line);
+    }
+    callback('---end---');
+    //清理副本文件
+    await unlink(tmpFile).catch(() => { });
+};
+export const getOpenclawPath = (...paths) => {
+    return path.join(os.homedir(), '.openclaw', ...paths);
+};
+/**
+ * 2026-08-10 扩展能力（ext_capabilities）目录定位。
+ * 优先从插件包目录找（开发/本地路径），找不到则退回 ~/.openclaw/ext_capabilities。
+ */
+/**
+ * 2026-08-10 扩展能力（ext_capabilities）目录定位。
+ * 注意：插件是 ESM（"type": "module"），__dirname 未定义，必须用 import.meta.url 定位。
+ * 从当前文件向上查找含 package.json + ext_capabilities 的插件根目录，
+ * 同时保留 cwd / ~/.openclaw 作为兜底，兼容不同启动方式。
+ */
+export const getExtCapabilitiesDir = () => {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // 从当前文件（src/ 或 dist/src/）向上查找插件根目录（含 package.json 且含 ext_capabilities）
+    let dir = here;
+    for (let i = 0; i < 6; i++) {
+        try {
+            if (fs.existsSync(path.join(dir, 'package.json')) && fs.existsSync(path.join(dir, 'ext_capabilities'))) {
+                return path.join(dir, 'ext_capabilities');
+            }
+        }
+        catch { /* ignore */ }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // 兜底：cwd / ~/.openclaw
+    const fallbacks = [
+        path.resolve(process.cwd(), 'ext_capabilities'),
+        getOpenclawPath('ext_capabilities'),
+    ];
+    for (const dir2 of fallbacks) {
+        try {
+            if (fs.existsSync(dir2))
+                return dir2;
+        }
+        catch { /* ignore */ }
+    }
+    return fallbacks[0];
+};
+export const dtFormat = (dt, fmt) => {
+    const o = {
+        "M+": dt.getMonth() + 1, //月份
+        "d+": dt.getDate(), //日
+        "h+": dt.getHours(), //小时
+        "m+": dt.getMinutes(), //分
+        "s+": dt.getSeconds(), //秒
+        "q+": Math.floor((dt.getMonth() + 3) / 3), //季度
+        "S": dt.getMilliseconds() //毫秒
+    };
+    // 处理年份
+    const yearMatch = fmt.match(/(y+)/);
+    if (yearMatch) {
+        const yearStr = dt.getFullYear().toString();
+        const pattern = yearMatch[0];
+        const len = pattern.length;
+        fmt = fmt.replace(pattern, yearStr.slice(-len));
+    }
+    // 处理其他格式
+    for (const k in o) {
+        const regex = new RegExp("(" + k + ")");
+        const match = fmt.match(regex);
+        if (match) {
+            const pattern = match[0];
+            const value = o[k].toString();
+            const replacement = pattern.length === 1
+                ? value
+                : ("00" + value).slice(-pattern.length);
+            fmt = fmt.replace(pattern, replacement);
+        }
+    }
+    return fmt;
+};
+/**
+ * 生成指定长度的uuid
+ * @param {Object} len
+ * @param {Object} radix 2,10,16进制
+ */
+export const uuidStr = (len, radix) => {
+    const chars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz".split("");
+    const uuid = [];
+    let i;
+    radix = radix || chars.length;
+    if (len) {
+        // Compact form
+        for (i = 0; i < len; i++)
+            uuid[i] = chars[0 | (Math.random() * radix)];
+    }
+    else {
+        let r;
+        uuid[8] = uuid[13] = uuid[18] = uuid[23] = "-";
+        uuid[14] = "4";
+        for (i = 0; i < 36; i++) {
+            if (!uuid[i]) {
+                r = 0 | (Math.random() * 16);
+                uuid[i] = chars[i == 19 ? (r & 0x3) | 0x8 : r];
+            }
+        }
+    }
+    return uuid.join("");
+};

package/ext_capabilities/workrelay-speak/CLONE_GUIDE.md

@@ -0,0 +1,129 @@
+# WorkRelay 语音合成（TTS）扩展能力 — 声音克隆配置说明书
+
+> 适用：已安装 workrelay-speak 扩展能力（默认 Kokoro 预设声音可用）的用户，
+> 需要**克隆自己的声音**（做视频配音、个性化语音等场景）时的进阶配置。
+
+---
+
+## 一、原理说明
+
+- WorkRelay TTS 扩展能力基于 Docker 部署的 **Voicebox** 服务，默认使用 **Kokoro** 小模型（82M，50+ 预设音色，开箱即用）。
+- **Kokoro 不支持声音克隆**（只支持预设音色）。
+- **声音克隆需要 Qwen3-TTS（千问）模型**（1.7B，约 4.6GB），Voicebox 内置支持 zero-shot 克隆：
+  上传一段参考音频 + 逐字稿 → 生成克隆声音 profile → 用该 profile 合成语音。
+
+---
+
+## 二、准备工作
+
+| 项目 | 要求 |
+|---|---|
+| 已安装 workrelay-speak 扩展 | Voicebox 容器运行中（`docker ps` 能看到 voicebox） |
+| 参考音频 | 1~5 段**清晰人声**（10~30 秒/段，44.1kHz 或 48kHz 更佳，无明显噪音） |
+| 逐字稿 | 每段音频对应的**逐字文本**（必须和音频内容一字不差，克隆质量关键） |
+| 磁盘空间 | ≥ 5GB（千问模型 4.6GB） |
+
+> 音频格式支持 wav / mp3 / m4a / webm 等（opuse/webm 会自动转码）。
+
+---
+
+## 三、配置步骤
+
+### 第 1 步：下载千问 TTS 模型
+
+> ⚠️ 容器内直连 huggingface.co 通常不通（国内网络），需在**宿主机**预下载后放入容器缓存卷。
+
+```bash
+# 1) 安装下载工具（宿主机执行，一次性）
+python3 -m pip install --break-system-packages huggingface_hub
+
+# 2) 找到容器缓存卷路径
+HF_VOL=$(docker volume inspect voicebox_huggingface-cache -f '{{.Mountpoint}}')
+
+# 3) 下载千问 1.7B 模型（约 4.6GB，视网速 5~30 分钟）
+HF_LOC=$(python3 -m pip show huggingface_hub | grep Location | awk '{print $2}')
+sudo env PYTHONPATH="$HF_LOC" HF_HUB_DISABLE_PROGRESS_BARS=1 python3 -c "
+from huggingface_hub import snapshot_download
+snapshot_download('Qwen/Qwen3-TTS-12Hz-1.7B-Base', cache_dir='$HF_VOL')
+print('模型下载完成')
+"
+```
+
+### 第 2 步：让容器离线加载模型
+
+```bash
+# 在 Voicebox 仓库目录生成 override 配置并重建容器
+cd ~/.workrelay/voicebox
+cat > docker-compose.override.yml <<'EOF'
+services:
+  voicebox:
+    environment:
+      - HF_HUB_CACHE=/home/voicebox/.cache/huggingface
+      - HF_HUB_OFFLINE=1
+EOF
+docker compose up -d
+# 等待容器 healthy（约 30 秒）
+```
+
+### 第 3 步：创建克隆声音 profile
+
+```bash
+# 创建克隆 profile（cloned 类型）
+curl -X POST http://127.0.0.1:17600/profiles \
+  -H "Content-Type: application/json" \
+  -d '{"name":"我的克隆声音","description":"我的声音克隆","language":"zh","voice_type":"cloned"}'
+# 记下返回的 "id"（形如 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx），下面用 <PROFILE_ID> 代替
+```
+
+### 第 4 步：上传参考音频样本
+
+```bash
+# 每段音频一条命令；reference_text 必须与音频内容逐字一致！
+curl -X POST "http://127.0.0.1:17600/profiles/<PROFILE_ID>/samples" \
+  -F "file=@/path/to/sample1.wav" \
+  -F "reference_text=这段音频里说的话，逐字写在这里"
+
+# 建议上传 2~5 段同一个人不同语句的样本，克隆效果更好
+```
+
+### 第 5 步：用克隆声音合成
+
+```bash
+# 方式 A：命令行直接合成（WR_VOICEBOX_PROFILE_ID 指向克隆 profile）
+WR_VOICEBOX_PROFILE_ID=<PROFILE_ID> \
+  ~/.workrelay/speak/workrelay-tts.sh "用克隆声音说的测试文字" /tmp/clone-test.wav
+
+# 方式 B：让 OpenClaw 默认用克隆声音回复（写入 profile_id 文件，覆盖默认预设）
+echo "<PROFILE_ID>" > ~/.workrelay/speak/profile_id
+```
+
+> 引擎无需手动指定：克隆 profile 未设引擎时，脚本自动使用 qwen（千问）。
+> 想切回默认 Kokoro 预设声音：`rm -f ~/.workrelay/speak/profile_id` 即可。
+
+---
+
+## 四、验证
+
+```bash
+# 检查克隆 profile 及样本
+curl http://127.0.0.1:17600/profiles/<PROFILE_ID>
+curl http://127.0.0.1:17600/profiles/<PROFILE_ID>/samples
+
+# 试听合成的 wav
+ls -la /tmp/clone-test.wav
+```
+
+---
+
+## 五、常见问题
+
+| 问题 | 原因 / 解决 |
+|---|---|
+| 合成报 `Profile not found` | profile_id 写错，或 profile 被删；重新创建并核对 |
+| 合成报模型下载失败/连不上 HF | 模型未预下载或 override 未生效；重做第 1、2 步 |
+| 克隆声音不像 | 样本太短/有噪音/逐字稿不匹配；换更清晰样本、多传几段 |
+| 想恢复默认声音 | 删除 `~/.workrelay/speak/profile_id` |
+
+---
+
+*文档版本：2026-08-12（基于 WorkRelay workrelay-speak 扩展能力实测）*

package/ext_capabilities/workrelay-speak/HARDWARE.md

@@ -0,0 +1,84 @@
+# WorkRelay 语音功能最低硬件配置
+
+## 一、语音转录（faster-whisper）
+
+| 项目 | 最低要求 | 推荐配置 |
+|------|----------|----------|
+| **CPU** | 双核 2.0GHz+ | 四核 2.5GHz+ |
+| **内存** | 4GB 可用 | 8GB+ |
+| **磁盘** | 2.5GB 可用 | 5GB+ |
+| **OS** | Linux / macOS | Ubuntu 22.04+ |
+| **Python** | 3.8+ | 3.10+ |
+
+**额外依赖：** `pip`, `git`（标准 Linux 发行版自带）
+
+**实测数据（8核 31GB Linux CPU）：**
+- 首次加载模型：10-20 秒
+- 10 秒语音转录：2-5 秒
+- 30 秒语音转录：5-10 秒
+
+> ⚠️ 不支持原生 Windows（需 WSL2）
+
+---
+
+## 二、语音合成 / 声音克隆（Voicebox TTS，Docker）
+
+| 项目 | 最低要求 | 推荐配置 |
+|------|----------|----------|
+| **CPU** | 双核 2.0GHz+ | 四核 3.0GHz+ |
+| **内存** | 4GB 可用 | 8GB+ |
+| **磁盘** | 10GB 可用 | 15GB+ |
+| **OS** | Linux（需 Docker） | Ubuntu 22.04+ |
+| **Docker** | 24.0+ | 27.0+ |
+| **GPU** | 无（CPU 推理） | NVIDIA CUDA（加速 5-10x） |
+
+**额外依赖：** `docker`, `docker compose v2`, `git`
+
+**Docker 资源（默认 Kokoro 引擎）：**
+- Voicebox 镜像：~11GB（含全部 TTS 引擎依赖）
+- Kokoro 模型：~350MB（默认，安装时自动预下载）
+- 运行内存：~2-3GB（Docker 内，Kokoro CPU 推理）
+
+**实测数据（8核 31GB Linux CPU，Kokoro）：**
+- 短句（10 字）：1-3 秒
+- 中句（30 字）：3-8 秒
+- 长句（100 字）：10-20 秒
+
+> 默认使用 Kokoro（82MB）轻量引擎，开箱即用；
+> 如需声音克隆或更高音质，可另配 Qwen3-TTS 1.7B（~4.6GB，内存需求 6GB+），详见 `CLONE_GUIDE.md`。
+
+---
+
+## 三、两个功能同时启用
+
+| 项目 | 最低要求 | 推荐配置 |
+|------|----------|----------|
+| **CPU** | 四核 2.5GHz+ | 八核 3.0GHz+ |
+| **内存** | 12GB 可用 | 16GB+（配置给 Docker 8GB） |
+| **磁盘** | 15GB 可用 | 25GB+ |
+| **GPU** | 无 | NVIDIA CUDA |
+
+**内存分配建议（16GB 总内存场景）：**
+- faster-whisper 模型常驻：~2GB
+- Voicebox Docker 容器：~6-8GB
+- 剩余系统缓冲：~6-8GB
+
+---
+
+## 四、客户端提示文案建议
+
+### 转录
+```
+最低：2核 CPU + 4GB 内存 + 2.5GB 磁盘
+推荐：4核 CPU + 8GB 内存 + 5GB 磁盘
+不支持原生 Windows（需 WSL2）
+首次安装需下载 1.6GB 模型文件
+```
+
+### 语音合成
+```
+最低：2核 CPU + 4GB 内存 + 10GB 磁盘 + Docker
+推荐：4核 CPU + 8GB 内存 + 15GB 磁盘 + Docker
+首次安装需下载 Docker 镜像 + Kokoro 模型（~350MB）
+默认 Kokoro 轻量引擎，CPU 推理快，开箱即用
+```

package/ext_capabilities/workrelay-speak/QWEN_GUIDE.md

@@ -0,0 +1,151 @@
+# WorkRelay 语音合成（TTS）— 使用 Qwen3-TTS（千问）引擎说明书
+
+> 适用：已安装 workrelay-speak 扩展能力，想把 TTS 引擎从默认 Kokoro 换成
+> **Qwen3-TTS 1.7B**（千问）的用户。千问模型效果更好、支持声音克隆，
+> 代价是模型大（~4.6GB）、CPU 合成较慢。
+
+---
+
+## 一、两个引擎怎么选
+
+| 项目 | Kokoro（默认） | Qwen3-TTS 1.7B（千问，可选） |
+|------|---------------|------------------------------|
+| 模型大小 | 82M（~350MB 落盘） | 1.7B（~4.6GB 落盘） |
+| CPU 合成速度 | 快（秒级） | 较慢（10~60 秒/句，视文本长度） |
+| 音色 | 50+ 预设音色 | 预设音色（Vivian 中文女声等）+ **声音克隆** |
+| 中英混读 | 支持（install.sh 自动打补丁） | 支持 |
+| 适合场景 | 默认开箱即用 | 追求音质 / 需要克隆自己的声音 |
+
+> 声音克隆的完整步骤见同目录 `CLONE_GUIDE.md`；本说明聚焦「把引擎切到千问」。
+
+---
+
+## 二、第 1 步：下载千问模型（宿主机执行，一次性）
+
+> ⚠️ 容器内直连 huggingface.co 通常不通（国内网络），必须在**宿主机**预下载后放入容器缓存卷。
+
+```bash
+# 1) 安装下载工具（没有则装）
+python3 -m pip install --break-system-packages huggingface_hub
+
+# 2) 找到容器缓存卷路径（compose 模式卷名带前缀；run 回退模式是裸卷，二选一）
+HF_VOL=$(docker volume inspect voicebox_huggingface-cache -f '{{.Mountpoint}}' 2>/dev/null)
+[ -z "$HF_VOL" ] && HF_VOL=$(docker volume inspect huggingface-cache -f '{{.Mountpoint}}' 2>/dev/null)
+
+# 3) 下载千问 1.7B 模型（约 4.6GB，视网速 5~30 分钟）
+HF_LOC=$(python3 -m pip show huggingface_hub | grep Location | awk '{print $2}')
+sudo env PYTHONPATH="$HF_LOC" HF_HUB_DISABLE_PROGRESS_BARS=1 python3 -c "
+from huggingface_hub import snapshot_download
+snapshot_download('Qwen/Qwen3-TTS-12Hz-1.7B-Base', cache_dir='$HF_VOL')
+print('模型下载完成')
+"
+```
+
+> 无 sudo 权限时：直接去掉 `sudo env`，用 `PYTHONPATH=... python3 -c "..."` 执行。
+
+---
+
+## 三、第 2 步：确认容器离线加载配置
+
+install.sh 安装时（compose 模式）已自动生成 `docker-compose.override.yml`，
+包含离线加载环境变量。确认一下即可：
+
+```bash
+# Voicebox 仓库目录：install.sh 输出的实际路径（默认 ~/.workrelay/voicebox，
+# snap docker 环境为 /var/snap/docker/common/workrelay-voicebox）
+cd ~/.workrelay/voicebox
+
+# 查看 override（应含 HF_HUB_CACHE 与 HF_HUB_OFFLINE=1）
+cat docker-compose.override.yml
+
+# 若文件缺失或内容不对，手动写入并重建容器：
+cat > docker-compose.override.yml <<'EOF'
+services:
+  voicebox:
+    environment:
+      - HF_HUB_CACHE=/home/voicebox/.cache/huggingface
+      - HF_HUB_OFFLINE=1
+EOF
+docker compose up -d
+```
+
+---
+
+## 四、第 3 步：选择 / 创建千问 profile
+
+**方式 A：用已有千问预设音色（Vivian 中文女声）**
+
+install.sh 已自动创建过「小朵中文女声」profile（`preset_engine=qwen_custom_voice`，`preset_voice_id=Vivian`）。
+查询确认并拿它的 id：
+
+```bash
+curl -s http://127.0.0.1:17600/profiles | python3 -m json.tool | grep -B2 -A6 "qwen"
+```
+
+**方式 B：新建一个千问 preset profile**
+
+```bash
+curl -X POST http://127.0.0.1:17600/profiles \
+  -H "Content-Type: application/json" \
+  -d '{"name":"我的千问声音","description":"Qwen3-TTS 预设","language":"zh","voice_type":"preset","preset_engine":"qwen_custom_voice","preset_voice_id":"Vivian"}'
+# 记下返回的 "id"，下面用 <PROFILE_ID> 代替
+```
+
+**方式 C：克隆自己的声音** → 走 `CLONE_GUIDE.md`（克隆出的 profile 引擎自动是千问）。
+
+---
+
+## 五、第 4 步：把千问设为默认引擎
+
+```bash
+# 写入 profile_id 文件（覆盖默认 Kokoro），workrelay-tts.sh 会自动读取
+echo "<PROFILE_ID>" > ~/.workrelay/speak/profile_id
+```
+
+> 也可以不写文件、临时指定：`WR_VOICEBOX_PROFILE_ID=<PROFILE_ID> ~/.workrelay/speak/workrelay-tts.sh "文本" /tmp/out.wav`
+>
+> 引擎无需手动指定：脚本按 profile 的 `default_engine` 自动匹配（qwen profile 自动走千问）。
+
+---
+
+## 六、验证
+
+```bash
+# 1) 确认 profile 存在
+curl http://127.0.0.1:17600/profiles/<PROFILE_ID>
+
+# 2) 命令行试合成（千问 CPU 较慢，耐心等）
+WR_VOICEBOX_PROFILE_ID=<PROFILE_ID> \
+  ~/.workrelay/speak/workrelay-tts.sh "你好，我是小朵，今天用千问模型给你合成语音。" /tmp/qwen-test.wav
+
+# 3) 听一下（或看文件大小/时长）
+ls -la /tmp/qwen-test.wav
+```
+
+---
+
+## 七、常见问题
+
+| 问题 | 原因 / 解决 |
+|------|------------|
+| 合成报模型下载失败 / 连不上 HF | 模型未预下载或 override 未生效；重做第 1、2 步 |
+| 合成很慢 | 千问 1.7B CPU 推理正常现象；短句更快，可调大 OpenClaw `timeoutMs`（默认 180s 够用） |
+| 合成报 `Profile not found` | profile_id 写错或 profile 被删；重新创建并核对 |
+| 重跑 install.sh 后声音变回 Kokoro | install.sh 每次安装会重置默认 profile_id；按第 4 步重新 `echo` 千问 id 即可 |
+| 想切回 Kokoro 默认声音 | `rm -f ~/.workrelay/speak/profile_id` |
+| 想克隆自己的声音 | 见 `CLONE_GUIDE.md` |
+
+---
+
+## 八、附：关键信息速查
+
+| 项目 | 值 |
+|------|-----|
+| 千问模型 | `Qwen/Qwen3-TTS-12Hz-1.7B-Base`（~4.6GB） |
+| Voicebox API | `http://127.0.0.1:17600`（compose 固定映射；run 回退模式可能为 17493，以 status.sh 输出 endpoint 为准） |
+| 缓存卷 | `voicebox_huggingface-cache`（compose）/ `huggingface-cache`（run 回退） |
+| 引擎自动匹配 | 脚本读 profile 的 `default_engine`（qwen_custom_voice → 千问） |
+
+---
+
+*文档版本：2026-08-13（基于 WorkRelay workrelay-speak 扩展能力实测）*

package/ext_capabilities/workrelay-speak/README.md

@@ -0,0 +1,79 @@
+# WorkRelay 语音合成（TTS）模块
+
+Agent 语音回复能力：Docker 部署 **Voicebox**（默认 **Kokoro** 引擎，82M 轻量模型），
+50+ 预设音色，开箱即用，CPU 推理快。
+
+## 文件说明
+
+| 文件 | 作用 |
+|------|------|
+| `workrelay-tts.sh` | TTS 桥接脚本（调 Voicebox Docker REST API） |
+| `install.sh` | 一键安装（Docker → 克隆仓库 → 启动容器 → 模型预下载 → 配置 OpenClaw） |
+| `status.sh` | 状态查询，输出 JSON，客户端判断"已启用/未启用" |
+| `CLONE_GUIDE.md` | 声音克隆进阶配置说明书（可选，需千问 Qwen3-TTS 模型） |
+| `QWEN_GUIDE.md` | 使用 Qwen3-TTS（千问）引擎说明书（含预设音色 Vivian + 切引擎步骤） |
+
+## 依赖
+
+- **Docker** (docker + docker compose v2)
+- **Voicebox** (`jamiepine/voicebox`) — 通过 Docker 部署
+- TTS 引擎：**Kokoro**（默认，82M，CPU 推理，50+ 预设音色）
+- 首次安装：下载 Docker 镜像 + Kokoro 模型（约 350MB）
+
+> 声音克隆（可选）：需另配 Qwen3-TTS 1.7B 模型（~4.6GB），详见 `CLONE_GUIDE.md`。
+
+## 客户端集成方案
+
+### 设置页面
+
+```
+┌─────────────────────────────────────┐
+│  🎙️ 语音合成（TTS）                 │
+│                                     │
+│  状态: ● 已启用 / ○ 未启用          │
+│                                     │
+│  引擎: Kokoro (预设 50+ 音色)       │
+│  服务: Voicebox (Docker)            │
+│                                     │
+│  [ 启用语音合成 ]  ← 仅未启用时显示  │
+└─────────────────────────────────────┘
+```
+
+### status.sh 返回格式
+
+```json
+{
+  "status": "enabled",
+  "description": "语音合成已启用",
+  "endpoint": "http://127.0.0.1:17493",
+  "checks": {
+    "docker": true,
+    "container": true,
+    "api": true,
+    "tts_script": true,
+    "openclaw_config": true
+  }
+}
+```
+
+### OpenClaw 自动配置项
+
+| 配置路径 | 值 |
+|----------|-----|
+| `messages.tts.auto` | `off`（手动触发） |
+| `messages.tts.provider` | `tts-local-cli` |
+| `messages.tts.providers.tts-local-cli.command` | `workrelay-tts.sh` |
+| `messages.tts.providers.tts-local-cli.args` | `["{{Text}}","{{OutputPath}}"]` |
+| `messages.tts.providers.tts-local-cli.outputFormat` | `wav` |
+| `messages.tts.providers.tts-local-cli.timeoutMs` | `180000` |
+| `mcp.servers.voicebox.url` | `http://127.0.0.1:17493/mcp` |
+
+## 环境变量（可选）
+
+| 变量 | 说明 | 默认 |
+|------|------|------|
+| `WR_VOICEBOX_PROFILE_ID` | 指定声音 profile（预设或克隆，不设则自动解析） | 自动 |
+| `WR_VOICEBOX_HOST` | Voicebox 地址 | 127.0.0.1 |
+| `WR_VOICEBOX_PORT` | Voicebox 端口 | 17493 |
+| `WR_VOICEBOX_ENGINE` | TTS 引擎（不设则按 profile 自动匹配） | 自动 |
+| `WR_VOICEBOX_LANG` | 语言 | zh |