diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 000000000..4ae510726
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,174 @@
+# 🦞 Moltbot — 个人 AI 助手
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/moltbot/moltbot/main/docs/whatsapp-clawd.jpg" alt="Clawdbot" width="400">
+</p>
+
+<p align="center">
+  <strong>EXFOLIATE! EXFOLIATE!</strong>
+</p>
+
+**Moltbot** 是一个运行在你自己设备上的*个人 AI 助手*。
+它可以在你常用的渠道上回复你（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat），以及扩展渠道如 BlueBubbles、Matrix、Zalo 等。它可以在 macOS/iOS/Android 上语音交互，还可以渲染你控制的实时 Canvas。Gateway 只是控制平面——产品就是助手本身。
+
+如果你想要一个感觉本地化、快速且始终在线的个人单用户助手，这就是它。
+
+[官网](https://molt.bot) · [文档](https://docs.molt.bot) · [快速开始](https://docs.molt.bot/start/getting-started) · [更新指南](https://docs.molt.bot/install/updating) · [展示](https://docs.molt.bot/start/showcase) · [FAQ](https://docs.molt.bot/start/faq) · [向导](https://docs.molt.bot/start/wizard) · [Discord](https://discord.gg/clawd)
+
+---
+
+## 🚀 快速开始
+
+**系统要求：** Node ≥22
+
+### 安装（推荐）
+
+```bash
+npm install -g moltbot@latest
+# 或: pnpm add -g moltbot@latest
+
+moltbot onboard --install-daemon
+```
+
+向导会安装 Gateway 守护进程（launchd/systemd 用户服务），使其保持运行。
+
+### 快速开始（TL;DR）
+
+```bash
+moltbot onboard --install-daemon
+
+moltbot gateway --port 18789 --verbose
+
+# 发送消息
+moltbot message send --to +1234567890 --message "来自 Moltbot 的问候"
+
+# 与助手对话
+moltbot agent --message "今日待办清单" --thinking high
+```
+
+---
+
+## 📦 从源码安装（开发）
+
+推荐使用 `pnpm` 从源码构建。
+
+```bash
+git clone https://github.com/moltbot/moltbot.git
+cd moltbot
+
+pnpm install
+pnpm ui:build  # 首次运行会自动安装 UI 依赖
+pnpm build
+
+pnpm moltbot onboard --install-daemon
+
+# 开发循环（TS 变更自动重载）
+pnpm gateway:watch
+```
+
+---
+
+## 🔑 模型支持
+
+**推荐订阅（OAuth）：**
+- **[Anthropic](https://www.anthropic.com/)** (Claude Pro/Max) — 推荐
+- **[OpenAI](https://openai.com/)** (ChatGPT/Codex)
+
+模型说明：虽然支持任何模型，但强烈推荐 **Anthropic Pro/Max + Opus 4.5**，具有更强的长上下文能力和更好的提示注入抵抗力。
+
+---
+
+## 📱 支持的渠道
+
+### 核心渠道
+| 渠道 | 说明 |
+|------|------|
+| WhatsApp | 通过 Baileys 支持 |
+| Telegram | 通过 grammY 支持 |
+| Slack | 通过 Bolt 支持 |
+| Discord | 通过 discord.js 支持 |
+| Google Chat | 通过 Chat API 支持 |
+| Signal | 通过 signal-cli 支持 |
+| iMessage | 通过 imsg 支持（仅 macOS） |
+| WebChat | 内置 web 界面 |
+
+### 扩展渠道
+BlueBubbles、Microsoft Teams、Matrix、Zalo、Mattermost、Nextcloud Talk 等
+
+---
+
+## ⚙️ 配置
+
+配置文件位置：`~/.clawdbot/moltbot.json`
+
+**最小配置：**
+```json5
+{
+  agent: {
+    model: "anthropic/claude-opus-4-5"
+  }
+}
+```
+
+**带渠道配置：**
+```json5
+{
+  channels: {
+    telegram: {
+      botToken: "YOUR_BOT_TOKEN",
+      allowFrom: ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+详细配置请参考：[配置参考](https://docs.molt.bot/gateway/configuration)
+
+---
+
+## 💬 聊天命令
+
+在 WhatsApp/Telegram/Slack 等渠道发送：
+
+| 命令 | 说明 |
+|------|------|
+| `/status` | 查看会话状态（模型 + tokens） |
+| `/new` 或 `/reset` | 重置会话 |
+| `/compact` | 压缩会话上下文 |
+| `/think <级别>` | off\|minimal\|low\|medium\|high\|xhigh |
+| `/verbose on\|off` | 详细模式 |
+| `/usage off\|tokens\|full` | 每次响应的用量页脚 |
+
+---
+
+## 🔒 安全模型
+
+- **默认：** 工具在宿主机上为 **main** 会话运行，所以当只有你使用时，助手有完全访问权限。
+- **群组/渠道安全：** 设置 `agents.defaults.sandbox.mode: "non-main"` 可以在 Docker 沙箱中运行非 main 会话。
+
+详情：[安全指南](https://docs.molt.bot/gateway/security)
+
+---
+
+## 📚 文档链接
+
+- [入门指南](https://docs.molt.bot/start/getting-started)
+- [配置参考](https://docs.molt.bot/gateway/configuration)
+- [架构概述](https://docs.molt.bot/concepts/architecture)
+- [渠道文档](https://docs.molt.bot/channels)
+- [工具文档](https://docs.molt.bot/tools)
+- [故障排除](https://docs.molt.bot/channels/troubleshooting)
+
+---
+
+## 🤝 贡献
+
+欢迎贡献！参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。
+
+AI 辅助的 PR 也欢迎！🤖 只需在 PR 中标注即可。
+
+---
+
+## 📜 许可证
+
+[MIT License](LICENSE)
diff --git a/docs/gateway/configuration.zh-CN.md b/docs/gateway/configuration.zh-CN.md
new file mode 100644
index 000000000..d81899b9f
--- /dev/null
+++ b/docs/gateway/configuration.zh-CN.md
@@ -0,0 +1,400 @@
+---
+summary: "~/.clawdbot/moltbot.json 的所有配置选项及示例"
+read_when:
+  - 添加或修改配置字段
+---
+
+# 配置 🔧
+
+Moltbot 从 `~/.clawdbot/moltbot.json` 读取可选的 **JSON5** 配置（支持注释和尾随逗号）。
+
+如果文件不存在，Moltbot 使用安全的默认值（嵌入式 Pi 代理 + 每发送者会话 + 工作区 `~/clawd`）。通常只需要配置以下内容：
+- 限制谁可以触发机器人（`channels.whatsapp.allowFrom`、`channels.telegram.allowFrom` 等）
+- 控制群组允许列表 + 提及行为
+- 自定义消息前缀
+- 设置代理的工作区
+- 调整嵌入式代理默认值和会话行为
+
+---
+
+## 严格配置验证
+
+Moltbot 只接受完全匹配架构的配置。
+未知键、格式错误的类型或无效值会导致网关**拒绝启动**以确保安全。
+
+验证失败时：
+- 网关不会启动。
+- 只允许诊断命令（例如：`moltbot doctor`、`moltbot logs`、`moltbot health`）。
+- 运行 `moltbot doctor` 查看确切问题。
+- 运行 `moltbot doctor --fix` 应用迁移/修复。
+
+---
+
+## 最小配置（推荐起点）
+
+```json5
+{
+  agents: { defaults: { workspace: "~/clawd" } },
+  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
+}
+```
+
+---
+
+## 常用选项
+
+### 环境变量
+
+Moltbot 从父进程读取环境变量。另外加载：
+- 当前工作目录的 `.env`（如果存在）
+- `~/.clawdbot/.env` 的全局回退
+
+```json5
+{
+  env: {
+    OPENROUTER_API_KEY: "sk-or-...",
+    vars: {
+      GROQ_API_KEY: "gsk-..."
+    }
+  }
+}
+```
+
+### 配置中的环境变量替换
+
+可以使用 `${VAR_NAME}` 语法在任何配置字符串值中引用环境变量：
+
+```json5
+{
+  models: {
+    providers: {
+      "custom-provider": {
+        apiKey: "${CUSTOM_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 渠道配置
+
+### WhatsApp
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      dmPolicy: "pairing",  // pairing | allowlist | open | disabled
+      allowFrom: ["+15555550123", "+447700900123"],
+      textChunkLimit: 4000,  // 可选出站块大小（字符）
+      mediaMaxMb: 50  // 可选入站媒体上限（MB）
+    }
+  }
+}
+```
+
+**DM 策略说明：**
+| 值 | 说明 |
+|----|------|
+| `pairing` | 默认，未知发送者获得配对码；所有者必须批准 |
+| `allowlist` | 只允许 `allowFrom` 中的发送者 |
+| `open` | 允许所有入站 DM（**需要** `allowFrom` 包含 `"*"`） |
+| `disabled` | 忽略所有入站 DM |
+
+### Telegram
+
+```json5
+{
+  channels: {
+    telegram: {
+      botToken: "123456:ABC...",
+      allowFrom: ["5347394567"],  // 你的 Telegram 用户 ID
+      groups: {
+        "*": { requireMention: true }
+      }
+    }
+  }
+}
+```
+
+**获取 Bot Token：**
+1. 在 Telegram 中找 [@BotFather](https://t.me/BotFather)
+2. 发送 `/newbot` 创建新机器人
+3. 复制返回的 token
+
+**获取用户 ID：**
+给机器人发消息后，机器人会返回你的用户 ID。
+
+### Discord
+
+```json5
+{
+  channels: {
+    discord: {
+      token: "YOUR_BOT_TOKEN",
+      dm: {
+        policy: "pairing",
+        allowFrom: ["USER_ID"]
+      },
+      guilds: {
+        "GUILD_ID": {
+          channels: {
+            "CHANNEL_NAME": { allow: true }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Slack
+
+```json5
+{
+  channels: {
+    slack: {
+      botToken: "xoxb-...",
+      appToken: "xapp-...",
+      channels: {
+        "#general": { allow: true }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 代理配置
+
+### 模型配置
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "anthropic/claude-opus-4-5",
+        fallbacks: ["openai/gpt-5"]
+      },
+      workspace: "~/clawd"
+    }
+  }
+}
+```
+
+### 多代理配置
+
+```json5
+{
+  agents: {
+    defaults: {
+      workspace: "~/clawd"
+    },
+    list: [
+      {
+        id: "main",
+        default: true,
+        identity: {
+          name: "助手",
+          emoji: "🦞"
+        }
+      },
+      {
+        id: "work",
+        workspace: "~/clawd-work",
+        model: "openai/gpt-5"
+      }
+    ]
+  }
+}
+```
+
+### 代理身份
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        identity: {
+          name: "小龙",
+          theme: "友好的助手",
+          emoji: "🦞",
+          avatar: "avatars/lobster.png"
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 群组聊天配置
+
+### 提及门控
+
+群组消息默认**需要提及**（元数据提及或正则模式）。
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        groupChat: {
+          mentionPatterns: ["@小龙", "小龙", "助手"]
+        }
+      }
+    ]
+  }
+}
+```
+
+### 群组策略
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groupPolicy: "allowlist",  // open | disabled | allowlist
+      groups: {
+        "*": { requireMention: true }
+      }
+    },
+    telegram: {
+      groupPolicy: "allowlist",
+      groups: {
+        "*": { requireMention: true }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 网关配置
+
+```json5
+{
+  gateway: {
+    mode: "local",
+    port: 18789,
+    bind: "loopback",
+    auth: {
+      mode: "token",
+      token: "your-secret-token"
+    },
+    tailscale: {
+      mode: "off"  // off | serve | funnel
+    }
+  }
+}
+```
+
+---
+
+## 日志配置
+
+```json5
+{
+  logging: {
+    level: "info",
+    file: "/tmp/moltbot/moltbot.log",
+    consoleLevel: "info",
+    consoleStyle: "pretty",  // pretty | compact | json
+    redactSensitive: "tools"
+  }
+}
+```
+
+---
+
+## 沙箱配置
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main",  // off | non-main | all
+        scope: "session",  // session | agent | shared
+        workspaceAccess: "rw"  // none | ro | rw
+      }
+    }
+  }
+}
+```
+
+---
+
+## 完整示例
+
+```json5
+{
+  // 代理设置
+  agents: {
+    defaults: {
+      workspace: "~/clawd",
+      model: {
+        primary: "anthropic/claude-opus-4-5"
+      }
+    },
+    list: [
+      {
+        id: "main",
+        identity: {
+          name: "小龙",
+          emoji: "🦞"
+        },
+        groupChat: {
+          mentionPatterns: ["@小龙", "小龙"]
+        }
+      }
+    ]
+  },
+
+  // 网关设置
+  gateway: {
+    port: 18789,
+    bind: "loopback",
+    auth: {
+      mode: "token",
+      token: "your-secret-token"
+    }
+  },
+
+  // 渠道设置
+  channels: {
+    telegram: {
+      enabled: true,
+      botToken: "YOUR_BOT_TOKEN",
+      allowFrom: ["YOUR_USER_ID"]
+    },
+    whatsapp: {
+      dmPolicy: "pairing",
+      allowFrom: ["+8612345678901"]
+    }
+  },
+
+  // 日志设置
+  logging: {
+    level: "info",
+    consoleStyle: "pretty"
+  }
+}
+```
+
+---
+
+## 更多信息
+
+- [配置示例](https://docs.molt.bot/gateway/configuration-examples)
+- [安全指南](https://docs.molt.bot/gateway/security)
+- [多代理配置](https://docs.molt.bot/multi-agent-sandbox-tools)
diff --git a/docs/start/getting-started.zh-CN.md b/docs/start/getting-started.zh-CN.md
new file mode 100644
index 000000000..ada04e8a3
--- /dev/null
+++ b/docs/start/getting-started.zh-CN.md
@@ -0,0 +1,192 @@
+---
+summary: "入门指南：从零到第一条消息（向导、认证、渠道、配对）"
+read_when:
+  - 首次从零开始设置
+  - 你想要从安装→引导→第一条消息的最快路径
+---
+
+# 快速开始
+
+目标：尽快从 **零** → **第一个运行的聊天**（使用合理的默认值）。
+
+最快的聊天方式：打开控制 UI（无需渠道设置）。运行 `moltbot dashboard` 并在浏览器中聊天，或在网关主机上打开 `http://127.0.0.1:18789/`。
+文档：[Dashboard](/web/dashboard) 和 [Control UI](/web/control-ui)。
+
+推荐路径：使用 **CLI 引导向导** (`moltbot onboard`)。它会设置：
+- 模型/认证（推荐 OAuth）
+- 网关设置
+- 渠道（WhatsApp/Telegram/Discord/Mattermost(插件)/...）
+- 配对默认值（安全 DM）
+- 工作区引导 + 技能
+- 可选的后台服务
+
+---
+
+## 0) 前置条件
+
+- Node `>=22`
+- `pnpm`（可选；如果从源码构建则推荐）
+- **推荐：** Brave Search API 密钥用于网络搜索。最简单的方式：
+  `moltbot configure --section web`（存储 `tools.web.search.apiKey`）。
+
+**macOS：** 如果计划构建应用，需安装 Xcode / CLT。仅 CLI + 网关只需要 Node。
+
+**Windows：** 使用 **WSL2**（推荐 Ubuntu）。WSL2 是强烈推荐的；原生 Windows 未经测试，问题更多，工具兼容性较差。
+
+---
+
+## 1) 安装 CLI（推荐）
+
+```bash
+curl -fsSL https://molt.bot/install.sh | bash
+```
+
+**Windows (PowerShell)：**
+```powershell
+iwr -useb https://molt.bot/install.ps1 | iex
+```
+
+**替代方案（全局安装）：**
+```bash
+npm install -g moltbot@latest
+# 或
+pnpm add -g moltbot@latest
+```
+
+---
+
+## 2) 运行引导向导（并安装服务）
+
+```bash
+moltbot onboard --install-daemon
+```
+
+你将选择：
+- **本地 vs 远程** 网关
+- **认证**：OpenAI Code (Codex) 订阅 (OAuth) 或 API 密钥。对于 Anthropic 推荐使用 API 密钥。
+- **提供商**：WhatsApp 二维码登录、Telegram/Discord 机器人令牌等。
+- **守护进程**：后台安装（launchd/systemd；WSL2 使用 systemd）
+- **网关令牌**：向导默认生成一个并存储在 `gateway.auth.token` 中。
+
+### 认证：存储位置（重要）
+
+- **推荐 Anthropic 路径：** 设置 API 密钥（向导可以为服务使用存储它）。
+- OAuth 凭证（旧版导入）：`~/.clawdbot/credentials/oauth.json`
+- 认证配置文件（OAuth + API 密钥）：`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
+
+**无头/服务器提示：** 先在普通机器上进行 OAuth，然后将 `oauth.json` 复制到网关主机。
+
+---
+
+## 3) 启动网关
+
+如果在引导期间安装了服务，网关应该已经在运行：
+
+```bash
+moltbot gateway status
+```
+
+**手动运行（前台）：**
+```bash
+moltbot gateway --port 18789 --verbose
+```
+
+**仪表板（本地回环）：** `http://127.0.0.1:18789/`
+
+如果配置了令牌，将其粘贴到控制 UI 设置中。
+
+⚠️ **Bun 警告（WhatsApp + Telegram）：** Bun 在这些渠道上有已知问题。如果使用 WhatsApp 或 Telegram，请用 **Node** 运行网关。
+
+---
+
+## 3.5) 快速验证（2 分钟）
+
+```bash
+moltbot status
+moltbot health
+moltbot security audit --deep
+```
+
+---
+
+## 4) 配对 + 连接你的第一个聊天界面
+
+### WhatsApp（二维码登录）
+
+```bash
+moltbot channels login
+```
+
+通过 WhatsApp → 设置 → 链接设备 扫描。
+
+### Telegram / Discord / 其他
+
+向导可以为你写入令牌/配置。如果偏好手动配置：
+- Telegram：设置 `TELEGRAM_BOT_TOKEN` 环境变量或配置文件
+- Discord：设置 `DISCORD_BOT_TOKEN` 环境变量
+
+**Telegram DM 提示：** 你的第一个 DM 会返回一个配对码。需要批准它（见下一步），否则机器人不会响应。
+
+---
+
+## 5) DM 安全（配对批准）
+
+默认行为：未知 DM 会收到一个短代码，消息在批准前不会被处理。
+如果你的第一个 DM 没有收到回复，批准配对：
+
+```bash
+moltbot pairing list whatsapp
+moltbot pairing approve whatsapp <code>
+```
+
+**注意：** Telegram 不使用配对，而是使用 `allowFrom` 配置：
+
+```json5
+{
+  channels: {
+    telegram: {
+      allowFrom: ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+---
+
+## 6) 从源码安装（开发）
+
+```bash
+git clone https://github.com/moltbot/moltbot.git
+cd moltbot
+pnpm install
+pnpm ui:build  # 首次运行会自动安装 UI 依赖
+pnpm build
+pnpm moltbot onboard --install-daemon
+```
+
+**网关（从此仓库）：**
+```bash
+node moltbot.mjs gateway --port 18789 --verbose
+```
+
+---
+
+## 7) 端到端验证
+
+在新终端中，发送测试消息：
+
+```bash
+moltbot message send --target +15555550123 --message "来自 Moltbot 的问候"
+```
+
+如果 `moltbot health` 显示 "no auth configured"，返回向导设置 OAuth/密钥认证——没有它助手无法响应。
+
+**提示：** `moltbot status --all` 是最好的可粘贴、只读调试报告。
+
+---
+
+## 下一步（可选，但很棒）
+
+- macOS 菜单栏应用 + 语音唤醒：[macOS 应用](/platforms/macos)
+- iOS/Android 节点（Canvas/相机/语音）：[节点](/nodes)
+- 远程访问（SSH 隧道 / Tailscale Serve）：[远程访问](/gateway/remote)