docs: add Chinese documentation (README, getting-started, configuration)
This commit is contained in:
tianqishu
parent
9688454a30
commit
06b915592a
174
README.zh-CN.md
Normal file
174
README.zh-CN.md
Normal file
@ -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)
|
||||||
400
docs/gateway/configuration.zh-CN.md
Normal file
400
docs/gateway/configuration.zh-CN.md
Normal file
@ -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)
|
||||||
192
docs/start/getting-started.zh-CN.md
Normal file
192
docs/start/getting-started.zh-CN.md
Normal file
@ -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)
|
||||||
Loading…
Reference in New Issue
Block a user