diff --git a/docs/shared/tts-guide.md b/docs/shared/tts-guide.md
new file mode 100644
index 0000000..574aecb
--- /dev/null
+++ b/docs/shared/tts-guide.md
@@ -0,0 +1,112 @@
+# OpenClaw TTS 语音功能配置指南
+
+## 1. 概述
+
+OpenClaw 内置 TTS（Text-to-Speech）语音功能，支持以下三种 provider：
+
+| Provider | 是否免费 | 需要 API Key |
+|----------|---------|-------------|
+| Microsoft Edge TTS | ✅ 免费 | ❌ 不需要 |
+| OpenAI TTS | ❌ 付费 | ✅ 需要 |
+| ElevenLabs | ❌ 付费 | ✅ 需要 |
+
+> **推荐方案：** Microsoft Edge TTS 免费且无需 API key，推荐作为默认方案。
+
+## 2. 配置方法
+
+在 `openclaw.json` 的 `messages.tts` 下配置：
+
+```json
+{
+  "messages": {
+    "tts": {
+      "auto": "off",
+      "provider": "microsoft",
+      "microsoft": {
+        "enabled": true,
+        "voice": "zh-CN-XiaoxiaoNeural",
+        "lang": "zh-CN"
+      }
+    }
+  }
+}
+```
+
+### auto 模式说明
+
+| 模式 | 说明 |
+|------|------|
+| `off` | 默认关闭，可通过 `/tts` 命令或 tts 工具手动触发 |
+| `always` | 每条回复自动转语音 |
+| `inbound` | 收到语音消息时才回复语音 |
+| `tagged` | 回复中包含 `[[tts]]` 标签时才转语音 |
+
+## 3. 可用中文音色
+
+### zh-CN 女声
+
+| 音色名称 | 风格特点 |
+|----------|---------|
+| `zh-CN-XiaoxiaoNeural` | 温暖（新闻/小说风格） |
+| `zh-CN-XiaoyiNeural` | 活泼可爱（卡通/小说风格） |
+
+### zh-CN 男声
+
+| 音色名称 | 风格特点 |
+|----------|---------|
+| `zh-CN-YunjianNeural` | 热血激情（体育/小说） |
+| `zh-CN-YunxiNeural` | 活泼阳光（小说） |
+| `zh-CN-YunxiaNeural` | 可爱少年（卡通/小说） |
+| `zh-CN-YunyangNeural` | 专业沉稳（新闻） |
+
+### zh-HK 粤语
+
+| 音色名称 | 性别 |
+|----------|------|
+| `zh-HK-HiuGaaiNeural` | 女 |
+| `zh-HK-HiuMaanNeural` | 女 |
+| `zh-HK-WanLungNeural` | 男 |
+
+## 4. 使用方式
+
+### tts 工具
+
+Agent 可直接调用内置 `tts` 工具发送语音消息。
+
+### /tts 命令
+
+用户可通过斜杠命令使用：
+
+```
+/tts audio <文字>       # 生成一条语音
+/tts always             # 开启自动语音模式
+/tts off                # 关闭自动语音
+/tts inbound            # 收到语音时才回复语音
+```
+
+## 5. Telegram 特别说明
+
+- Telegram 会显示**圆形语音气泡**（Opus 格式），体验最佳
+- 飞书目前收到的是**音频文件**而非语音气泡
+
+## 6. 踩坑记录
+
+### "produced empty audio file" 错误
+
+- **现象：** Microsoft Edge TTS 返回空音频文件
+- **原因：** 服务器网络到 Microsoft 端点不稳定
+- **解决：**
+    1. 重启 gateway 后通常恢复：`openclaw gateway restart`
+    2. 通过命令行验证 Edge TTS 是否可用：`npx node-edge-tts --text "测试" --voice zh-CN-XiaoxiaoNeural`
+
+### 自动 Fallback
+
+如果 Microsoft Edge TTS 不可用，系统会自动尝试 fallback 到 OpenAI 或 ElevenLabs（需要对应的 API key 已配置）。
+
+### 长文本处理
+
+长文本会自动摘要后再转语音（需在配置中设置 `summaryModel`）。
+
+### 短文本跳过
+
+短于 **10 个字符**的回复会自动跳过 TTS，不生成语音。
diff --git a/mkdocs.yml b/mkdocs.yml
index 7acca42..66e84f7 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -86,6 +86,7 @@ nav:
       - SiliconFlow 图片生成: shared/siliconflow-image-gen.md
       - A2A 跨队通信: shared/a2a-setup.md
       - Memex 知识管理: shared/memex-knowledge-base.md
+      - TTS 语音功能: shared/tts-guide.md
 
 extra:
   social: