Clawdbot 完整安装教程：打造你的 24/7 私人 AI 助手

Clawdbot 完整安装教程：打造你的 24/7 私人 AI 助手

📖 目录

1. 什么是 Clawdbot
2. 核心特性
3. 系统要求
4. 安装前准备
5. 安装步骤
   • Windows 安装
   • macOS 安装
   • Linux 安装
   • Docker 安装
6. 初始化配置
7. 连接聊天平台
8. MCP 工具集成
9. 常见问题解决
10. 最佳实践
11. 总结

什么是 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

1. 访问 Anthropic Console
2. 注册账号并登录
3. 进入 API Keys 页面
4. 点击 "Create Key" 创建新密钥
5. 复制并保存密钥（格式：sk-ant-...）

备选：OpenAI API

1. 访问 OpenAI Platform
2. 注册账号并登录
3. 进入 API Keys 页面
4. 创建新密钥并保存

2. 检查 Node.js 版本

打开终端，执行：

node --version

如果版本低于 v22.0.0，需要先升级 Node.js。

升级 Node.js（推荐使用 nvm）：

# 安装 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（管理员模式），执行：

wsl --install -d Ubuntu

安装完成后，重启计算机。

步骤 2：验证 WSL2

重启后，打开 PowerShell，执行：

wsl --list --verbose

确保输出中VERSION列显示为2。

步骤 3：进入 Ubuntu 环境

在开始菜单中搜索 "Ubuntu" 并打开，首次启动会要求设置用户名和密码。

步骤 4：安装 Node.js

在 Ubuntu 终端中执行：

# 添加 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

# 下载并执行安装脚本 curl -fsSL https://clawd.bot/install.sh | bash # 启动初始化向导 clawdbot onboard --install-daemon

步骤 6：访问 Web 界面

安装完成后，在Windows 浏览器中访问：

http://localhost:18789

macOS 安装

macOS 用户有两种安装方式：Homebrew（推荐）和通用脚本。

方法 1：Homebrew 安装（推荐）

适用于 macOS 15 或更高版本

# 安装 Clawdbot brew install --cask clawdbot

这将安装 macOS 原生应用，包含：

• 菜单栏集成
• 自动更新
• 图形化配置界面

方法 2：通用脚本安装

适用于 macOS 11 或更高版本

# 下载并执行安装脚本 curl -fsSL https://clawd.bot/install.sh | bash # 启动初始化向导 clawdbot onboard --install-daemon

验证安装

# 检查版本 clawdbot --version # 检查运行状态 clawdbot status # 运行诊断 clawdbot doctor

Linux 安装

Linux 安装最为简单，支持所有现代发行版。

步骤 1：安装 Clawdbot

# 下载并执行安装脚本 curl -fsSL https://clawd.bot/install.sh | bash

步骤 2：配置 24/7 运行（可选）

如果希望 Clawdbot 在服务器上 24/7 运行，执行：

# 启用用户级 systemd 服务持久化 loginctl enable-linger $USER

步骤 3：启动初始化向导

clawdbot onboard --install-daemon

验证安装

# 检查版本 clawdbot --version # 检查运行状态 clawdbot status # 测试对话 clawdbot chat "Hello, can you confirm you're working?"

Docker 安装

Docker 方式适合容器化部署和云服务器。

步骤 1：创建配置目录

mkdir -p ~/.clawdbot

步骤 2：创建 docker-compose.yml

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：启动容器

docker-compose up -d

步骤 4：查看日志

docker logs -f clawdbot

初始化配置

安装完成后，需要进行初始化配置。

1. 运行初始化向导

clawdbot onboard

向导会引导您完成以下配置：

1. 选择 AI 提供商：Claude 或 OpenAI
2. 输入 API 密钥
3. 选择默认模型：claude-3-5-sonnet-20241022（推荐）
4. 配置聊天渠道：WhatsApp、Telegram 等
5. 设置记忆功能：启用持久化记忆

2. 手动配置（高级）

配置文件位于~/.clawdbot/clawdbot.json，可以手动编辑：

{ "aiProvider": "anthropic", "apiKey": "sk-ant-...", "model": "claude-3-5-sonnet-20241022", "port": 18789, "memory": { "enabled": true, "maxTokens": 100000 }, "channels": [] }

3. 启动服务

# 启动 Clawdbot clawdbot start # 检查状态 clawdbot status

连接聊天平台

Clawdbot 支持多种聊天平台，以下是详细配置步骤。

WhatsApp 集成

WhatsApp 是最受欢迎的集成方式，无需 Business API。

步骤 1：启动 WhatsApp 登录

clawdbot channels login whatsapp

步骤 2：扫描二维码

终端会显示一个二维码，使用 WhatsApp 扫描：

1. 打开 WhatsApp
2. 点击右上角菜单 → "已连接的设备"
3. 点击 "连接设备"
4. 扫描终端中的二维码

注意：必须在 60 秒内完成扫描。

步骤 3：验证连接

clawdbot channels list

应该看到 WhatsApp 已连接。

Telegram 集成

步骤 1：创建 Telegram Bot

1. 在 Telegram 中搜索@BotFather
2. 发送/newbot命令
3. 按提示设置 Bot 名称和用户名
4. 复制 Bot Token（格式：123456:ABC-DEF...）

步骤 2：添加到 Clawdbot

clawdbot channels add telegram

按提示输入 Bot Token。

步骤 3：开始对话

在 Telegram 中搜索您的 Bot，发送/start开始对话。

Discord 集成

步骤 1：创建 Discord 应用

1. 访问 Discord Developer Portal
2. 点击 "New Application"
3. 进入 "Bot" 页面，点击 "Add Bot"
4. 复制 Bot Token

步骤 2：启用权限

在 Bot 设置页面：

• 启用 "MESSAGE CONTENT INTENT"
• 启用 "SERVER MEMBERS INTENT"

步骤 3：添加到 Clawdbot

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 能够访问外部服务。

查看可用工具

clawdbot mcp list

添加 Google Calendar

clawdbot mcp add google-calendar

按提示完成 OAuth 授权。

添加 Gmail

clawdbot mcp add gmail

添加 Notion

clawdbot mcp add notion

需要提供 Notion Integration Token。

添加 Spotify

clawdbot mcp add spotify

配置文件位置

MCP 工具配置存储在~/.clawdbot/mcp.json。

常见问题解决

问题 1：命令未找到（Command not found）

症状：执行clawdbot命令时提示 "command not found"

解决方案：

# 添加 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：检查占用端口的进程

# macOS/Linux lsof -i :18789 # 杀死进程 kill -9 <PID>

解决方案 2：更改端口

编辑~/.clawdbot/clawdbot.json：

{ "port": 18790 }

问题 3：权限错误

症状：安装时提示权限不足

解决方案：配置 npm 用户目录

# 创建全局目录 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 错误

解决方案：

1. 检查 API 密钥是否正确
2. 确认 API 账户有余额
3. 重新配置：

clawdbot config set apiKey "your_new_api_key"

问题 5：WhatsApp 二维码过期

症状：扫描二维码时提示已过期

解决方案：

# 重新生成二维码 clawdbot channels logout whatsapp clawdbot channels login whatsapp

必须在 60 秒内完成扫描。

问题 6：Docker 容器重启后数据丢失

症状：重启容器后记忆和配置丢失

解决方案：确保正确挂载数据卷

volumes: - ~/.clawdbot:/root/.clawdbot # 确保路径正确

检查目录权限：

ls -la ~/.clawdbot

问题 7：响应速度慢

症状：对话响应时间过长

解决方案：

1. 检查网络连接
2. 检查服务器资源（CPU、内存）
3. 切换到更快的 AI 模型：

clawdbot config set model "claude-3-5-sonnet-20241022"

问题 8：MCP 工具未显示

症状：添加 MCP 工具后无法使用

解决方案：

# 验证配置 clawdbot mcp list # 重启服务 clawdbot restart # 检查日志 clawdbot logs

最佳实践

1. 安全建议

• ✅保护 API 密钥：不要将密钥提交到 Git 仓库
• ✅定期更新：保持 Clawdbot 和依赖项最新
• ✅限制访问：如果部署在服务器上，配置防火墙规则
• ✅备份数据：定期备份~/.clawdbot目录

2. 性能优化

• ✅选择合适的模型：Claude 3.5 Sonnet 平衡了速度和质量
• ✅限制记忆大小：避免记忆过大导致响应变慢
• ✅使用本地缓存：启用记忆功能减少重复查询

3. 成本控制

• ✅监控 API 使用：定期检查 API 使用量
• ✅设置预算警报：在 Anthropic/OpenAI 控制台设置预算限制
• ✅优化提示词：避免过长的对话历史

4. 日常使用技巧

设置每日简报：

clawdbot schedule add "每天早上 8 点总结我的日程和待办事项"

快速访问：

# 创建别名（添加到 ~/.bashrc） alias cb="clawdbot chat" # 使用 cb "今天天气如何？"

批量操作：

# 批量添加 MCP 工具 clawdbot mcp add google-calendar gmail notion todoist

5. 故障排查流程

遇到问题时，按以下顺序排查：

1. 检查状态：clawdbot status
2. 运行诊断：clawdbot doctor
3. 查看日志：clawdbot logs
4. 重启服务：clawdbot restart
5. 重新配置：clawdbot onboard

总结

Clawdbot 是一个功能强大的自托管 AI 助手，通过本教程，您应该已经成功：

✅ 理解了 Clawdbot 的核心特性和优势 ✅ 完成了适合您操作系统的安装 ✅ 配置了 AI 提供商和 API 密钥 ✅ 连接了至少一个聊天平台（WhatsApp/Telegram/Discord） ✅ 了解了如何添加 MCP 工具集成 ✅ 掌握了常见问题的解决方法

下一步建议

1. 探索 MCP 工具：根据需求添加更多集成（日历、邮件、笔记等）
2. 设置自动化：配置定时任务和主动通知
3. 优化记忆：调整记忆设置以适应您的使用习惯
4. 加入社区：访问 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 工具, 安装教程