新增：文档体系重构+CHANGELOG补充+发布产物清理

2026-05-01 22:22:06 +08:00
parent 3e1a540b83
commit 6eaaa56eb6
164 changed files with 40346 additions and 64 deletions
--- a/docs/08-用户指南/clawdbot安装使用.md
+++ b/docs/08-用户指南/clawdbot安装使用.md
@@ -0,0 +1,620 @@
+# 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 的实际配置，定期更新以保持同步。