Clawdbot 完整安装教程：打造你的 24/7 私人 AI 助手
📖 目录
- [什么是 Clawdbot](#什么是 Clawdbot)
- 核心特性
- 系统要求
- 安装前准备
- 安装步骤
- [Windows 安装](#Windows 安装)
- [macOS 安装](#macOS 安装)
- [Linux 安装](#Linux 安装)
- [Docker 安装](#Docker 安装)
- 初始化配置
- 连接聊天平台
- [MCP 工具集成](#MCP 工具集成)
- 常见问题解决
- 最佳实践
- 总结
什么是 Clawdbot
Clawdbot 是一个开源的自托管 AI 助手，由 PSPDFKit 创始人 Peter Steinberger 创建。它可以 24/7 运行在您自己的硬件上，作为个人数字助理，通过 WhatsApp、Telegram、Slack、Discord 等聊天应用访问。
与 ChatGPT、Siri、Alexa 等商业助手不同，Clawdbot 的最大优势在于：
- ✅ 完全自托管：所有数据保留在您的基础设施中
- ✅ 隐私保护：对话、记忆和集成都存储在本地
- ✅ 无限记忆：持久化记忆功能，跨对话和时间
- ✅ 开源免费：MIT 许可证，完全免费使用
- ✅ 多平台支持：原生支持 WhatsApp、Telegram 等主流聊天工具
- ✅ 50+ 集成：支持 Google Calendar、Gmail、Notion、Spotify 等
核心特性
🔒 隐私与控制
- 完全自托管：所有数据保留在您的基础设施中
- 数据安全：对话、记忆和集成都存储在本地
- 可选本地模型：支持使用本地 AI 模型以获得最大隐私
🤖 AI 模型支持
- Anthropic Claude（推荐，最新的 Claude 3.5 Sonnet）
- OpenAI GPT-4 和 GPT-3.5
- 其他兼容 OpenAI API 的模型
- 可在不同提供商之间灵活切换
💬 通讯渠道集成
- WhatsApp（原生集成，无需 Business API）
- Telegram
- Slack
- Discord
- 其他消息平台
🛠️ MCP 工具集成（50+ 种）
日程管理：Google Calendar、Apple Calendar、Fantastical
邮件管理：Gmail、Outlook、IMAP
任务管理：Todoist、Things 3、Apple Reminders
笔记文档：Notion、Obsidian、Apple Notes
智能家居：Philips Hue、HomeKit、Home Assistant
媒体控制：Spotify、Apple Music
⚡ 高级功能
- 持久化记忆（跨对话和时间）
- 计划任务和自动化
- 主动通知
- 文件和文档访问
- 每日简报
系统要求
硬件要求
- CPU：任何现代处理器（x86_64 或 ARM64）
- 内存：最低 2GB RAM（推荐 4GB，特别是使用浏览器自动化时）
- 存储：约 500MB 磁盘空间（用于程序和数据）
- 网络：稳定的互联网连接（访问 AI API）
软件要求
- Node.js：v22.0.0 或更高版本（严格要求）
- 操作系统 ：
- Windows 10/11（需要 WSL2）
- macOS 11 或更高版本
- Linux（任何现代发行版）
成本预估
- Clawdbot 软件 ：免费（MIT 开源许可证）
- AI API 使用 ：
- Claude API：约 0.003/1K 输入 tokens，0.015/1K 输出 tokens
- 预计月成本：$5-30（取决于使用频率）
- 服务器成本：如在自己的 Mac/PC 上运行则无额外成本
安装前准备
1. 获取 AI API 密钥
推荐：Anthropic Claude API
- 访问 Anthropic Console
- 注册账号并登录
- 进入 API Keys 页面
- 点击 "Create Key" 创建新密钥
- 复制并保存密钥（格式：
sk-ant-...）
备选：OpenAI API
- 访问 OpenAI Platform
- 注册账号并登录
- 进入 API Keys 页面
- 创建新密钥并保存
2. 检查 Node.js 版本
打开终端，执行：
bash
node --version如果版本低于 v22.0.0，需要先升级 Node.js。
升级 Node.js（推荐使用 nvm）：
bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 安装 Node.js 22
nvm install 22
nvm use 22安装步骤
Windows 安装
由于 Clawdbot 依赖 Unix 环境，Windows 用户需要通过 WSL2（Windows Subsystem for Linux）安装。
步骤 1：启用 WSL2
打开 PowerShell（管理员模式），执行：
powershell
wsl --install -d Ubuntu安装完成后，重启计算机。
步骤 2：验证 WSL2
重启后，打开 PowerShell，执行：
powershell
wsl --list --verbose确保输出中 VERSION 列显示为 2。
步骤 3：进入 Ubuntu 环境
在开始菜单中搜索 "Ubuntu" 并打开，首次启动会要求设置用户名和密码。
步骤 4：安装 Node.js
在 Ubuntu 终端中执行：
bash
# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
# 安装 Node.js
sudo apt-get install -y nodejs
# 验证安装
node --version
npm --version步骤 5：安装 Clawdbot
bash
# 下载并执行安装脚本
curl -fsSL https://clawd.bot/install.sh | bash
# 启动初始化向导
clawdbot onboard --install-daemon步骤 6：访问 Web 界面
安装完成后，在 Windows 浏览器中访问：
http://localhost:18789macOS 安装
macOS 用户有两种安装方式：Homebrew（推荐）和通用脚本。
方法 1：Homebrew 安装（推荐）
适用于 macOS 15 或更高版本
bash
# 安装 Clawdbot
brew install --cask clawdbot这将安装 macOS 原生应用，包含：
- 菜单栏集成
- 自动更新
- 图形化配置界面
方法 2：通用脚本安装
适用于 macOS 11 或更高版本
bash
# 下载并执行安装脚本
curl -fsSL https://clawd.bot/install.sh | bash
# 启动初始化向导
clawdbot onboard --install-daemon验证安装
bash
# 检查版本
clawdbot --version
# 检查运行状态
clawdbot status
# 运行诊断
clawdbot doctorLinux 安装
Linux 安装最为简单，支持所有现代发行版。
步骤 1：安装 Clawdbot
bash
# 下载并执行安装脚本
curl -fsSL https://clawd.bot/install.sh | bash步骤 2：配置 24/7 运行（可选）
如果希望 Clawdbot 在服务器上 24/7 运行，执行：
bash
# 启用用户级 systemd 服务持久化
loginctl enable-linger $USER步骤 3：启动初始化向导
bash
clawdbot onboard --install-daemon验证安装
bash
# 检查版本
clawdbot --version
# 检查运行状态
clawdbot status
# 测试对话
clawdbot chat "Hello, can you confirm you're working?"Docker 安装
Docker 方式适合容器化部署和云服务器。
步骤 1：创建配置目录
bash
mkdir -p ~/.clawdbot步骤 2：创建 docker-compose.yml
yaml
version: '3.8'
services:
clawdbot:
image: clawdbot/clawdbot:latest
container_name: clawdbot
restart: unless-stopped
ports:
- "18789:18789"
volumes:
- ~/.clawdbot:/root/.clawdbot
environment:
- ANTHROPIC_API_KEY=your_api_key_here
# 或使用 OpenAI
# - OPENAI_API_KEY=your_api_key_here步骤 3：启动容器
bash
docker-compose up -d步骤 4：查看日志
bash
docker logs -f clawdbot初始化配置
安装完成后，需要进行初始化配置。
1. 运行初始化向导
bash
clawdbot onboard向导会引导您完成以下配置：
- 选择 AI 提供商：Claude 或 OpenAI
- 输入 API 密钥
- 选择默认模型：claude-3-5-sonnet-20241022（推荐）
- 配置聊天渠道：WhatsApp、Telegram 等
- 设置记忆功能：启用持久化记忆
2. 手动配置（高级）
配置文件位于 ~/.clawdbot/clawdbot.json，可以手动编辑：
json
{
"aiProvider": "anthropic",
"apiKey": "sk-ant-...",
"model": "claude-3-5-sonnet-20241022",
"port": 18789,
"memory": {
"enabled": true,
"maxTokens": 100000
},
"channels": []
}3. 启动服务
bash
# 启动 Clawdbot
clawdbot start
# 检查状态
clawdbot status连接聊天平台
Clawdbot 支持多种聊天平台，以下是详细配置步骤。
WhatsApp 集成
WhatsApp 是最受欢迎的集成方式，无需 Business API。
步骤 1：启动 WhatsApp 登录
bash
clawdbot channels login whatsapp步骤 2：扫描二维码
终端会显示一个二维码，使用 WhatsApp 扫描：
- 打开 WhatsApp
- 点击右上角菜单 → "已连接的设备"
- 点击 "连接设备"
- 扫描终端中的二维码
注意：必须在 60 秒内完成扫描。
步骤 3：验证连接
bash
clawdbot channels list应该看到 WhatsApp 已连接。
Telegram 集成
步骤 1：创建 Telegram Bot
- 在 Telegram 中搜索
@BotFather - 发送
/newbot命令 - 按提示设置 Bot 名称和用户名
- 复制 Bot Token（格式：
123456:ABC-DEF...）
步骤 2：添加到 Clawdbot
bash
clawdbot channels add telegram按提示输入 Bot Token。
步骤 3：开始对话
在 Telegram 中搜索您的 Bot，发送 /start 开始对话。
Discord 集成
步骤 1：创建 Discord 应用
- 访问 Discord Developer Portal
- 点击 "New Application"
- 进入 "Bot" 页面，点击 "Add Bot"
- 复制 Bot Token
步骤 2：启用权限
在 Bot 设置页面：
- 启用 "MESSAGE CONTENT INTENT"
- 启用 "SERVER MEMBERS INTENT"
步骤 3：添加到 Clawdbot
bash
clawdbot channels add discord按提示输入 Bot Token。
步骤 4：邀请 Bot 到服务器
在 Discord Developer Portal 的 "OAuth2" → "URL Generator" 页面：
- 勾选
botscope - 勾选必要的权限（Send Messages、Read Message History）
- 复制生成的 URL 并在浏览器中打开
- 选择要添加 Bot 的服务器
MCP 工具集成
MCP（Model Context Protocol）工具让 Clawdbot 能够访问外部服务。
查看可用工具
bash
clawdbot mcp list添加 Google Calendar
bash
clawdbot mcp add google-calendar按提示完成 OAuth 授权。
添加 Gmail
bash
clawdbot mcp add gmail添加 Notion
bash
clawdbot mcp add notion需要提供 Notion Integration Token。
添加 Spotify
bash
clawdbot mcp add spotify配置文件位置
MCP 工具配置存储在 ~/.clawdbot/mcp.json。
常见问题解决
问题 1：命令未找到（Command not found）
症状 ：执行 clawdbot 命令时提示 "command not found"
解决方案：
bash
# 添加 npm bin 目录到 PATH
export PATH="$(npm config get prefix)/bin:$PATH"
# 永久生效（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc问题 2：端口冲突
症状：启动时提示端口 18789 已被占用
解决方案 1：检查占用端口的进程
bash
# macOS/Linux
lsof -i :18789
# 杀死进程
kill -9 <PID>解决方案 2：更改端口
编辑 ~/.clawdbot/clawdbot.json：
json
{
"port": 18790
}问题 3：权限错误
症状：安装时提示权限不足
解决方案：配置 npm 用户目录
bash
# 创建全局目录
mkdir ~/.npm-global
# 配置 npm
npm config set prefix '~/.npm-global'
# 添加到 PATH
export PATH=~/.npm-global/bin:$PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc问题 4：API 密钥无效
症状：对话时提示 API 错误
解决方案：
- 检查 API 密钥是否正确
- 确认 API 账户有余额
- 重新配置：
bash
clawdbot config set apiKey "your_new_api_key"问题 5：WhatsApp 二维码过期
症状：扫描二维码时提示已过期
解决方案：
bash
# 重新生成二维码
clawdbot channels logout whatsapp
clawdbot channels login whatsapp必须在 60 秒内完成扫描。
问题 6：Docker 容器重启后数据丢失
症状：重启容器后记忆和配置丢失
解决方案：确保正确挂载数据卷
yaml
volumes:
- ~/.clawdbot:/root/.clawdbot # 确保路径正确检查目录权限：
bash
ls -la ~/.clawdbot问题 7：响应速度慢
症状：对话响应时间过长
解决方案：
- 检查网络连接
- 检查服务器资源（CPU、内存）
- 切换到更快的 AI 模型：
bash
clawdbot config set model "claude-3-5-sonnet-20241022"问题 8：MCP 工具未显示
症状：添加 MCP 工具后无法使用
解决方案：
bash
# 验证配置
clawdbot mcp list
# 重启服务
clawdbot restart
# 检查日志
clawdbot logs最佳实践
1. 安全建议
- ✅ 保护 API 密钥：不要将密钥提交到 Git 仓库
- ✅ 定期更新：保持 Clawdbot 和依赖项最新
- ✅ 限制访问：如果部署在服务器上，配置防火墙规则
- ✅ 备份数据 ：定期备份
~/.clawdbot目录
2. 性能优化
- ✅ 选择合适的模型：Claude 3.5 Sonnet 平衡了速度和质量
- ✅ 限制记忆大小：避免记忆过大导致响应变慢
- ✅ 使用本地缓存：启用记忆功能减少重复查询
3. 成本控制
- ✅ 监控 API 使用：定期检查 API 使用量
- ✅ 设置预算警报：在 Anthropic/OpenAI 控制台设置预算限制
- ✅ 优化提示词：避免过长的对话历史
4. 日常使用技巧
设置每日简报：
bash
clawdbot schedule add "每天早上 8 点总结我的日程和待办事项"快速访问：
bash
# 创建别名（添加到 ~/.bashrc）
alias cb="clawdbot chat"
# 使用
cb "今天天气如何？"批量操作：
bash
# 批量添加 MCP 工具
clawdbot mcp add google-calendar gmail notion todoist5. 故障排查流程
遇到问题时，按以下顺序排查：
- 检查状态 ：
clawdbot status - 运行诊断 ：
clawdbot doctor - 查看日志 ：
clawdbot logs - 重启服务 ：
clawdbot restart - 重新配置 ：
clawdbot onboard
总结
Clawdbot 是一个功能强大的自托管 AI 助手，通过本教程，您应该已经成功：
✅ 理解了 Clawdbot 的核心特性和优势 ✅ 完成了适合您操作系统的安装 ✅ 配置了 AI 提供商和 API 密钥 ✅ 连接了至少一个聊天平台（WhatsApp/Telegram/Discord） ✅ 了解了如何添加 MCP 工具集成 ✅ 掌握了常见问题的解决方法
下一步建议
- 探索 MCP 工具：根据需求添加更多集成（日历、邮件、笔记等）
- 设置自动化：配置定时任务和主动通知
- 优化记忆：调整记忆设置以适应您的使用习惯
- 加入社区 ：访问 GitHub 参与讨论
官方资源
- 📖 官方网站 ：clawd.bot
- 📚 完整文档 ：docs.clawd.bot
- 💻 GitHub 仓库 ：github.com/clawdbot/clawdbot
- 💬 社区讨论：GitHub Discussions
成本参考
- 软件成本：免费（MIT 开源）
- API 成本：$5-30/月（取决于使用频率）
- 服务器成本：0（本地运行）或 5-10/月（云服务器）
祝您使用愉快！如果遇到问题，欢迎在评论区讨论。
参考资料
本文参考了以下官方资源和社区教程：
- Clawdbot Official Documentation
- Clawdbot GitHub Repository
- How to Install Clawdbot on Windows, Mac, and Linux
- Clawdbot Complete Setup Guide
关键词：Clawdbot, AI 助手, 自托管, WhatsApp AI, Telegram Bot, Claude API, 开源 AI, 私人助手, MCP 工具, 安装教程