# Clawdbot 快速上手指南

> **你现在的状态**：新用户 + 已有 GLM 套餐账号
>
> **目标**：10 分钟内完成 Clawdbot 安装并配置 GLM 套餐

---

## 📦 什么是 Clawdbot？

**Clawdbot** 是一个 24/7 运行的个人 AI 助手，可以：
- ✅ 在 WhatsApp、Telegram、Discord 等平台与你对话
- ✅ 操作你的电脑（浏览器、文件系统）
- ✅ 执行任务（写代码、查资料、自动化）
- ✅ 主动给你发消息（不是被动响应）

**简单理解**：一个长在你电脑上的 AI 助理，类似"贾维斯"。

---

## 🚀 快速安装（Windows + WSL2）

### 步骤 1：安装 WSL2（5 分钟）

打开 PowerShell（管理员），运行：

```powershell
wsl --install
```

重启电脑，完成 Ubuntu 初始化设置。

### 步骤 2：安装 Node.js 22+（2 分钟）

在 WSL2 Ubuntu 终端运行：

```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node --version
```

### 步骤 3：安装 Clawdbot（1 分钟）

```bash
# 一键安装
curl -fsSL https://clawd.bot/install.sh | bash

# 或使用 npm
npm install -g clawdbot@latest
```

### 步骤 4：配置 GLM 套餐（2 分钟）

#### 获取你的 GLM API Key

1. 登录 [智谱AI开放平台](https://open.bigmodel.cn/)
2. 进入控制台 → API Keys
3. 复制你的 API Key

#### 配置环境变量

编辑 `~/.bashrc`：

```bash
vim ~/.bashrc
```

添加以下内容：

```bash
# GLM Coding Plan 配置
export OPENAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"
export OPENAI_API_KEY="你的GLM_API_KEY"
export MODEL_NAME="glm-4-flash"
```

保存后执行：

```bash
source ~/.bashrc
```

### 步骤 5：运行向导（可选）

```bash
clawdbot onboard --install-daemon
```

向导会帮你配置：
- 通信渠道（WhatsApp、Telegram 等）
- 后台服务
- 其他设置

**如果你有 GLM 套餐**，向导中的认证配置可以选择跳过或手动配置。

---

## 🔥 使用 GLM 套餐的注意事项

### ⚠️ 重要提醒

**Clawdbot 不在 GLM 官方支持的工具列表中**，这意味着：

1. **可能被识别为普通 API 调用**，消耗账户余额而非套餐额度
2. **需要验证配置**是否正确使用套餐

### 验证是否使用套餐额度

**方法 1：查看控制台**

1. 访问 [智谱AI控制台 - 套餐使用](https://open.bigmodel.cn/usercenter/billing)
2. 发送几条测试消息
3. 查看"套餐使用情况"是否减少
4. 如果"账户余额"减少，说明被识别为普通调用

**方法 2：使用 One-API 中转（推荐）**

```bash
# 安装 One-API
docker run -d --name one-api -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v /root/data/one-api:/data \
  ghcr.io/songquanpeng/one-api:latest

# 访问 http://localhost:3000
# 配置 GLM 套餐渠道
# 在 Clawdbot 中使用：
export OPENAI_BASE_URL="http://localhost:3000/v1"
export OPENAI_API_KEY="sk-one-api-token"
```

### 套餐并发限制

- **Lite**：并发数 2
- **Pro**：并发数 5
- **Max**：并发数 7

如果遇到并发错误，调整配置或升级套餐。

---

## ▶️ 启动 Clawdbot

### 方法 1：前台运行（测试用）

```bash
clawdbot gateway --port 18789 --verbose
```

### 方法 2：后台服务（推荐）

```bash
# 安装服务（如果向导中已安装可跳过）
clawdbot onboard --install-daemon

# 启动服务
sudo systemctl start clawdbot

# 查看状态
sudo systemctl status clawdbot

# 查看日志
journalctl -u clawdbot -f
```

---

## 🎯 开始使用

### 配置通信渠道

#### WhatsApp（推荐）

1. 在手机上打开 WhatsApp
2. 设置 → 关联设备
3. 扫描二维码完成登录

#### Telegram

1. 在 Telegram 中搜索 [@BotFather](https://t.me/BotFather)
2. 发送 `/newbot` 创建机器人
3. 获取 Bot Token
4. 在 Clawdbot 中配置

### 首次配对

第一条消息会收到配对代码，需要批准：

```bash
# 批准 WhatsApp 配对
clawdbot pairing approve whatsapp <配对代码>

# 批准 Telegram 配对
clawdbot pairing approve telegram <配对代码>
```

### 发送测试消息

在 WhatsApp/Telegram 中发送：

```
你好
```

如果收到回复，配置成功！🎉

---

## 🔧 常用命令

```bash
# 查看状态
clawdbot status

# 健康检查
clawdbot health

# 重启服务
sudo systemctl restart clawdbot

# 停止服务
sudo systemctl stop clawdbot

# 查看完整状态
clawdbot status --all
```

---

## ❓ 常见问题

### Q1: 安装失败怎么办？

**A**: 检查 Node.js 版本：

```bash
node --version  # 必须 >= 22
```

如果版本过低，重新安装 Node.js 22。

### Q2: GLM 套餐不生效？

**A**: 按以下步骤排查：

```bash
# 1. 检查配置
echo $OPENAI_BASE_URL
echo $OPENAI_API_KEY
echo $MODEL_NAME

# 2. 测试 API 连接
curl -X POST https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model":"glm-4-flash","messages":[{"role":"user","content":"测试"}]}'

# 3. 检查日志
journalctl -u clawdbot -n 50
```

### Q3: 服务启动失败？

**A**: 查看错误日志：

```bash
journalctl -u clawdbot -n 100
```

常见问题：
- 端口被占用：修改端口号 `--port 18790`
- 配置文件错误：检查 `~/.clawdbot/config.json`
- API Key 无效：重新获取并配置

### Q4: 如何更新 Clawdbot？

```bash
npm update -g clawdbot@latest
```

### Q5: 如何卸载？

```bash
# 停止服务
sudo systemctl stop clawdbot

# 卸载
npm uninstall -g clawdbot

# 删除配置
rm -rf ~/.clawdbot
```

---

## 📚 下一步

### 基础使用

1. **对话**：在 WhatsApp/Telegram 中直接对话
2. **任务**：让 AI 帮你写代码、查资料、分析日志
3. **自动化**：配置定时任务、消息转发等

### 高级功能

1. **浏览器操作**：让 AI 操作浏览器完成任务
2. **文件操作**：读取、编辑、管理文件
3. **工具集成**：接入搜索引擎、API 等
4. **多智能体**：配置多个 AI 代理协同工作

### 学习资源

- [Clawdbot GitHub](https://github.com/clawdbot/clawdbot)
- [官方文档](https://docs.clawd.bot/)
- [社区讨论](https://github.com/clawdbot/clawdbot/discussions)

---

## 💡 使用技巧

### 技巧 1：高效提示词

❌ 坏："帮我看看这个"
✅ 好："审查这段代码的性能问题，重点关注内存泄漏和循环效率"

### 技巧 2：利用文件系统能力

"读取 /var/log/app.log，分析过去 1 小时的错误模式"

### 技巧 3：多轮对话

保持上下文，可以持续追问：

```
你：解释一下 React hooks
AI：[解释]
你：给我一个 useEffect 的例子
AI：[代码示例]
你：这个例子中依赖数组的作用是什么？
AI：[详细说明]
```

---

## 🎉 恭喜！

你已经成功安装并配置了 Clawdbot + GLM 套餐！

**现在可以**：
- ✅ 在 WhatsApp/Telegram 中与 AI 对话
- ✅ 让 AI 帮你处理任务
- ✅ 享受 GLM 套餐的高性价比

**下一步**：
- 探索更多功能
- 配置自动化任务
- 优化使用体验

---

## 📝 快速参考

### 配置文件位置

```
~/.clawdbot/
├── config.json              # 主配置
├── credentials/             # 凭据
└── workspace/               # 工作空间
```

### 服务管理

```bash
# 启动
sudo systemctl start clawdbot

# 停止
sudo systemctl stop clawdbot

# 重启
sudo systemctl restart clawdbot

# 状态
sudo systemctl status clawdbot

# 日志
journalctl -u clawdbot -f
```

### GLM 套餐配置

```bash
# 环境变量
export OPENAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"
export OPENAI_API_KEY="你的API_KEY"
export MODEL_NAME="glm-4-flash"

# 验证
curl -X POST $OPENAI_BASE_URL/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model":"glm-4-flash","messages":[{"role":"user","content":"测试"}]}'
```

---

**祝使用愉快！** 🚀

有问题？查看 [常见问题](#-常见问题) 或访问 [GitHub Issues](https://github.com/clawdbot/clawdbot/issues)

---

## 📌 本机配置记录

> **最后更新**: 2026-01-28
> **配置环境**: Windows 11
> **Clawdbot 版本**: 2026.1.24-3

### ✅ 当前运行状态

| 项目 | 状态 | 详情 |
|------|------|------|
| **网关状态** | 🟢 运行中 | 端口 18789 (127.0.0.1) |
| **默认模型** | GLM-4.7 | `zai/glm-4.7` |
| **工作空间** | `C:\Users\23780\clawd` | |
| **进程 PID** | 20992 | |

### 📁 配置文件路径

#### 主配置目录
```
C:\Users\23780\.clawdbot\
├── clawdbot.json              # 主配置文件 ⭐
├── agents\
│   └── main\
│       ├── agent\
│       │   └── auth-profiles.json  # 认证配置
│       └── sessions\
│           └── sessions.json       # 会话存储
├── credentials\               # OAuth 凭证
├── cron\jobs.json            # 定时任务
└── devices\                  # 设备配对
```

#### 工作空间
```
C:\Users\23780\clawd\
├── canvas\                   # Canvas 文件
├── AGENTS.md                 # Agent 文档
├── BOOTSTRAP.md              # 启动文档
├── HEARTBEAT.md              # 心跳任务
├── SOUL.md                   # 系统提示
├── TOOLS.md                  # 工具文档
└── USER.md                   # 用户信息
```

### 🔑 GLM-4.7 模型配置

#### 配置文件: `C:\Users\23780\.clawdbot\clawdbot.json`

```json
{
  "gateway": {
    "mode": "local"
  },
  "env": {
    "ZAI_API_KEY": "7f83dc939a60488b8cf48a2ee1c8150e.NY3aOR0qlVS8m37a"
  },
  "agents": {
    "defaults": {
      "workspace": "C:\\Users\\23780\\clawd",
      "model": {
        "primary": "zai/glm-4.7"
      },
      "models": {
        "zai/glm-4.7": {
          "alias": "GLM"
        }
      }
    }
  }
}
```

#### GLM 模型信息

| 配置项 | 值 |
|--------|-----|
| **Provider** | Z.AI (智谱) |
| **Model ID** | `zai/glm-4.7` |
| **别名** | `GLM` |
| **API Key** | `7f83dc939a60488b8cf48a2ee1c8150e.NY3aOR0qlVS8m37a` |
| **环境变量** | `ZAI_API_KEY` |
| **通用端点** | `https://api.z.ai/api/paas/v4` |
| **编程端点** | `https://api.z.ai/api/coding/paas/v4` |

### 🚀 本机常用命令

#### 网关管理
```bash
# 启动网关
clawdbot gateway --port 18789

# 查看网关健康状态
clawdbot health

# 查看网关日志
clawdbot logs

# 重启网关 (Windows)
taskkill //F //PID <pid> && clawdbot gateway --port 18789
```

#### 模型管理
```bash
# 查看模型状态
clawdbot models status

# 列出可用模型
clawdbot models list

# 设置默认模型
clawdbot models set zai/glm-4.7
```

#### 诊断命令
```bash
# 运行完整诊断
clawdbot doctor

# 自动修复问题
clawdbot doctor --fix

# 查看频道状态
clawdbot status
```

#### 控制面板
```bash
# 打开 Web 控制面板
clawdbot dashboard
```

#### Agent 交互
```bash
# 运行 Agent (本地模式)
clawdbot agent --local --message "你好"

# 发送消息到会话
clawdbot message send --target <number> --message "测试消息"

# 查看会话列表
clawdbot sessions list
```

### 🛠️ 故障排查

#### 网关无法启动
```bash
# 检查端口占用
netstat -ano | grep 18789

# 终止占用进程 (Windows)
taskkill //F //PID <pid>

# 查看错误日志
clawdbot logs | tail -50
```

#### 模型认证失败
```bash
# 检查 API Key 配置
clawdbot models status

# 验证环境变量
echo $ZAI_API_KEY

# 重新配置
clawdbot configure
```

### 📊 配置验证

```bash
# 验证模型配置
clawdbot models status

# 输出应包含：
# Default       : zai/glm-4.7
# Aliases (1)   : GLM -> zai/glm-4.7
# Auth overview : zai effective=env:7f83dc93...lVS8m37a

# 验证网关健康
clawdbot health

# 输出应包含：
# Agents: main (default)
# Heartbeat interval: 30m (main)
```

### 📚 参考资源

#### 官方文档
- [Configuration - Clawdbot](https://docs.clawd.bot/gateway/configuration)
- [Clawdbot GitHub](https://github.com/clawdbot/clawdbot)

#### 中文指南
- [主权个人必看的Clawdbot 模型配置完全指南（2026版）](https://brave2049.com/groups/artificial-intelligence-learning/forum/discussion/zhu-quan-ge-ren-bi-kan-de-clawdbot-mo-xing-pei-zhi-wan-quan-zhi-nan-2026-ban/)
- [Clawdbot 完整配置指南](https://zhuanlan.zhihu.com/p/1999437992549447616)

#### 模型提供商
- [Z.AI (智谱AI)](https://open.bigmodel.cn/)
- [GLM-4.7 文档](https://open.bigmodel.cn/dev/howuse/model)

---

**提示**: 本节记录了本机 Clawdbot 的实际配置，定期更新以保持同步。