Clawdbot安装教程:2026一步步完整指南

最后更新: 2026年1月27日 | 难度: 入门 | 预计时间: 10-30分钟

📋 目录

你将学到什么
前置要求
方法1:npm安装(推荐)
方法2:从源码安装
方法3:Docker部署
首次配置
验证安装
常见问题排查
下一步

你将学到什么

完成本教程后,你将能够:

✅ 在Mac/Linux/Windows上成功安装Clawdbot
✅ 配置Claude API Key和基础设置
✅ 启动Clawdbot服务(前台/后台)
✅ 运行你的第一次AI对话
✅ 排查常见安装问题
✅ 设置开机自启动(可选)

适合人群:

想要部署Clawdbot的开发者
希望拥有24/7 AI助手的技术爱好者
重视隐私,想要本地部署的用户
对AI自动化感兴趣的创业者

前置要求

必需 ✅

1. Node.js 18+

Clawdbot基于Node.js构建,需要v18或更高版本。

检查是否已安装:

node --version
# 应显示 v18.x.x, v20.x.x, 或 v22.x.x

如何安装Node.js:

📱 macOS (使用Homebrew)

# 安装Homebrew (如果还没有)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装Node.js
brew install node@20

# 验证安装
node --version
npm --version

🐧 Ubuntu/Debian Linux

# 使用NodeSource仓库
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

🪟 Windows (使用WSL2)

Clawdbot在Windows上推荐使用WSL2 (Windows Subsystem for Linux)。

启用WSL2:

# 以管理员身份打开PowerShell
wsl --install
# 重启电脑

安装Ubuntu:

wsl --install -d Ubuntu-22.04

在WSL2中安装Node.js:

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

💡 提示: WSL2提供完整的Linux环境,Clawdbot运行更稳定。

详细WSL2教程: Clawdbot Windows WSL2完整指南

2. Claude API Key

Clawdbot使用Anthropic的Claude API。

获取API Key步骤:

访问 https://console.anthropic.com
注册/登录账号(支持Google登录)
进入 API Keys 页面
点击 "Create Key"
复制API Key (格式: sk-ant-api03-xxxxx)

Claude API Key获取

💰 费用说明:

新用户: 送$5免费额度(可用数周)
按使用付费: Claude 3.5 Sonnet约$3/百万tokens
典型使用: 轻度用户$5-15/月

🔒 安全提示: 不要将API Key提交到Git或分享给他人!

3. 操作系统

Clawdbot支持:

✅ macOS 11+ (Big Sur及以上)
✅ Linux (Ubuntu 20.04+, Debian 11+, Fedora 35+)
✅ Windows 10/11 (通过WSL2)

可选 🔹

1. Git (如果从源码安装)

# macOS
brew install git

# Ubuntu/Debian
sudo apt-get install git

# 验证
git --version

2. Docker (如果使用Docker部署)

# 安装Docker Desktop
# macOS: https://www.docker.com/products/docker-desktop
# Linux: https://docs.docker.com/engine/install/

# 验证
docker --version
docker-compose --version

3. Mac Mini M4 / VPS服务器 (推荐但非必需)

如果想24/7运行Clawdbot:

🖥️ Mac Mini M4: 静音、高效、$599起
☁️ VPS: DigitalOcean、AWS、阿里云(2核4G $10-20/月)
🥧 Raspberry Pi 5: 8GB版本,$80

方法1: npm安装 (推荐⭐)

这是最简单最快的安装方式,适合大多数用户。

步骤1: 安装Clawdbot CLI

# 全局安装clawdbot
npm install -g clawdbot

# 等待安装完成 (约1-2分钟)
# 看到 "added XX packages" 表示成功

npm安装过程

步骤2: 验证安装

# 检查版本
clawdbot --version
# 应显示: clawdbot/2.4.1 darwin-arm64 node-v20.11.0 (或类似)

# 查看帮助
clawdbot --help

成功标志:

✅ clawdbot命令可用
✅ 显示版本号
✅ 帮助信息正常显示

步骤3: 初始化配置

# 初始化Clawdbot
clawdbot init

# 你会看到交互式配置向导:

配置向导流程:

🤖 Welcome to Clawdbot Setup!

📍 Where should we store Clawdbot data?
   Default: /Users/你的用户名/.clawdbot
   > [按Enter使用默认路径]

🔑 Enter your Claude API Key:
   > sk-ant-api03-xxxxx  [粘贴你的API Key]

🎯 Select Claude model:
   ❯ claude-3-5-sonnet-20241022 (Recommended - 性价比最高)
     claude-3-opus-20240229 (Most powerful - 最强大)
     claude-3-haiku-20240307 (Fastest - 最快)
   > [选择claude-3-5-sonnet-20241022]

💬 Select default interface:
   ❯ CLI (命令行)
     Web (浏览器界面)
     Telegram Bot
     WhatsApp
   > [选择CLI]

✅ Configuration saved to /Users/你的用户名/.clawdbot/config.json

步骤4: 启动Clawdbot

# 前台运行 (测试用,Ctrl+C停止)
clawdbot start

# 看到以下输出表示成功:

🤖 Clawdbot v2.4.1
✅ Configuration loaded
✅ Database connected: /Users/你/.clawdbot/data.db
✅ Claude API verified (Model: claude-3-5-sonnet-20241022)
🚀 Clawdbot is ready!

Type 'help' for available commands, or start chatting...
>

Clawdbot启动成功

步骤5: 第一次对话

> 你好,Clawdbot!介绍一下你自己

Clawdbot回复:
你好!我是Clawdbot,你的AI个人助手。我基于Claude AI,但具有以下独特能力:

1. 持久记忆 - 我会记住我们的对话和你的偏好
2. 主动行为 - 我可以设置定时任务,主动提醒你
3. 565+技能 - 我能帮你编程、写作、数据分析等
4. 多平台 - 你可以在WhatsApp、Telegram等平台找到我

我会记住这是我们的第一次对话。有什么我可以帮你的吗?

🎉 恭喜!你已成功安装Clawdbot!

方法2: 从源码安装

适合想要最新开发版或需要自定义的用户。

步骤1: 克隆仓库

# 克隆GitHub仓库
git clone https://github.com/clawdbot/clawdbot.git

# 进入目录
cd clawdbot

# 检查当前版本
git describe --tags

步骤2: 安装依赖

# 安装所有依赖包
npm install

# 等待安装完成 (约2-3分钟)

步骤3: 构建

# TypeScript编译
npm run build

# 看到 "Build completed" 表示成功

步骤4: 链接到全局

# 创建全局命令链接
npm link

# 现在可以在任何位置使用clawdbot命令

步骤5: 初始化和启动

# 和npm安装方式相同
clawdbot init
clawdbot start

优点:

✅ 最新开发功能
✅ 可以修改源码
✅ 参与贡献开发

缺点:

⚠️ 可能不稳定
⚠️ 需要更多技术知识

方法3: Docker部署

适合需要隔离环境或在VPS上部署的用户。

步骤1: 创建工作目录

mkdir ~/clawdbot-docker
cd ~/clawdbot-docker

步骤2: 创建docker-compose.yml

# docker-compose.yml
version: '3.8'

services:
  clawdbot:
    image: clawdbot/clawdbot:latest
    container_name: clawdbot
    restart: unless-stopped
    environment:
      - CLAUDE_API_KEY=sk-ant-api03-xxxxx  # 替换你的API Key
      - CLAUDE_MODEL=claude-3-5-sonnet-20241022
      - TZ=Asia/Shanghai  # 时区设置
    volumes:
      - ./data:/app/data  # 持久化数据
      - ./config:/app/config  # 配置文件
    ports:
      - "3000:3000"  # Web界面(如果启用)
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

步骤3: 启动容器

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f clawdbot

# 看到 "Clawdbot is ready!" 表示成功

步骤4: 进入容器交互

# 进入容器CLI
docker exec -it clawdbot clawdbot chat

# 或者通过Web界面访问
# 浏览器打开: http://localhost:3000

Docker管理命令

# 停止服务
docker-compose stop

# 重启服务
docker-compose restart

# 查看状态
docker-compose ps

# 删除容器(保留数据)
docker-compose down

# 完全删除(包括数据)
docker-compose down -v

首次配置详解

配置文件位置

# 默认配置路径
~/.clawdbot/config.json

# 查看配置
cat ~/.clawdbot/config.json

配置文件结构

{
  "apiKey": "sk-ant-api03-xxxxx",
  "model": "claude-3-5-sonnet-20241022",
  "dataPath": "/Users/你的用户名/.clawdbot",
  "interface": "cli",
  "memory": {
    "enabled": true,
    "maxContextLength": 100000
  },
  "proactive": {
    "enabled": true,
    "checkInterval": 300000
  },
  "integrations": {
    "telegram": {
      "enabled": false
    },
    "whatsapp": {
      "enabled": false
    }
  }
}

手动编辑配置

# 使用你喜欢的编辑器
nano ~/.clawdbot/config.json
# 或
vim ~/.clawdbot/config.json
# 或
code ~/.clawdbot/config.json  # VS Code

高级配置选项

1. 启用Web界面

{
  "interface": "web",
  "web": {
    "port": 3000,
    "host": "0.0.0.0"
  }
}

然后访问: http://localhost:3000

2. 配置代理(国内用户)

{
  "proxy": {
    "enabled": true,
    "url": "http://127.0.0.1:7890"
  }
}

3. 自定义数据库

{
  "database": {
    "type": "postgresql",
    "url": "postgresql://user:pass@localhost:5432/clawdbot"
  }
}

验证安装

基础验证清单

运行以下命令检查一切正常:

# 1. 检查版本
clawdbot --version
# ✅ 应显示版本号

# 2. 检查配置
clawdbot config show
# ✅ 应显示当前配置

# 3. 测试API连接
clawdbot test api
# ✅ 应显示 "API connection successful"

# 4. 检查数据库
clawdbot test db
# ✅ 应显示 "Database connection OK"

# 5. 运行健康检查
clawdbot health
# ✅ 所有检查项应为绿色✅

健康检查输出示例

🏥 Clawdbot Health Check

✅ Node.js Version: v20.11.0 (OK)
✅ Configuration File: Found at ~/.clawdbot/config.json
✅ Claude API: Connected (Model: claude-3-5-sonnet-20241022)
✅ Database: SQLite connected (10MB, 234 messages)
✅ Memory System: Enabled (12 contexts cached)
✅ Skills: 8 installed, 8 active
✅ Disk Space: 45GB available

🎉 All systems operational!

测试基本功能

# 启动CLI模式
clawdbot chat

# 测试1: 基础对话
> 1+1等于几?
# 应能正常回复

# 测试2: 记忆功能
> 记住我的名字是张三,我是一名开发者
> [新对话] 我的名字是什么?
# 应该记得你是张三

# 测试3: 技能系统
> /help
# 应显示可用技能列表

# 测试4: 文件操作
> 帮我创建一个hello.txt文件,内容是"Hello Clawdbot"
# 应能成功创建文件

常见问题排查

问题1: `clawdbot: command not found`

症状:

$ clawdbot --version
bash: clawdbot: command not found

原因: npm全局安装路径不在PATH中

解决方法:

# 检查npm全局安装路径
npm config get prefix
# 输出示例: /usr/local

# 将npm bin路径添加到PATH
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

# 或者使用npx临时运行
npx clawdbot --version

问题2: API Key错误

症状:

❌ Error: Authentication failed. Please check your API key.

解决方法:

# 1. 验证API Key格式
# 正确格式: sk-ant-api03-xxxxx (以sk-ant-开头)

# 2. 重新配置
clawdbot config set apiKey sk-ant-api03-xxxxx

# 3. 测试连接
clawdbot test api

# 4. 检查API Key是否有额度
# 访问: https://console.anthropic.com/settings/billing

问题3: 端口占用 (Web模式)

症状:

Error: listen EADDRINUSE: address already in use :::3000

解决方法:

# 方法1: 更改端口
clawdbot config set web.port 3001

# 方法2: 查找占用进程并kill
lsof -i :3000
kill -9 <PID>

# 方法3: 使用CLI模式替代
clawdbot config set interface cli

问题4: 权限错误

症状:

EACCES: permission denied, mkdir '/Users/你/.clawdbot'

解决方法:

# 创建目录并设置权限
mkdir -p ~/.clawdbot
chmod 755 ~/.clawdbot

# 如果使用sudo安装的npm包,需要修复
sudo chown -R $(whoami) ~/.clawdbot

问题5: Node.js版本过低

症状:

Error: Clawdbot requires Node.js v18.0.0 or higher
Current version: v16.14.2

解决方法:

# macOS (使用n模块)
sudo npm install -g n
sudo n 20

# 或使用nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# 验证
node --version

问题6: 国内网络访问Claude API失败

症状:

Error: connect ETIMEDOUT 160.79.104.0:443

解决方法:

# 1. 配置代理
clawdbot config set proxy.enabled true
clawdbot config set proxy.url "http://127.0.0.1:7890"

# 2. 或设置环境变量
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 3. 测试连接
clawdbot test api --verbose

问题7: Clawdbot无输出 (No Output)

症状: Clawdbot启动成功但不响应消息

排查步骤:

# 1. 检查日志
clawdbot logs --tail 50

# 2. 增加日志级别
clawdbot config set logLevel debug
clawdbot start

# 3. 检查API额度
curl https://api.anthropic.com/v1/usage \
  -H "x-api-key: $CLAUDE_API_KEY"

# 4. 尝试不同模型
clawdbot config set model claude-3-haiku-20240307

详细排查: Clawdbot无输出完整指南

下一步做什么?

🎉 恭喜!你已经成功安装Clawdbot!

加入社区

遇到问题?想要分享经验?

💬 Discord: discord.gg/clawdbot - 15K+活跃用户
🐙 GitHub: github.com/clawdbot/clawdbot
🐦 Twitter/X: @clawdbot
📺 YouTube: youtube.com/@clawdbot
💬 中文社区: Discord中文频道

总结清单

安装成功的标志:

✅ clawdbot --version 显示版本号
✅ clawdbot test api 连接成功
✅ clawdbot start 启动无错误
✅ 能进行正常对话
✅ 记忆功能工作正常

如果以上都打勾,那么你已经成功部署Clawdbot!🎉

关于本教程

作者: Clawdbot AI Team
最后更新: 2026-01-27
字数: 约4500字
预计时间: 15分钟阅读

反馈: 教程有帮助吗?在评论区留言让我们知道!

相关标签: #ClawdbotSetup #AI安装教程 #Claude #Mac #Linux #Docker #技术教程 #AI助手部署

下一篇: Clawdbot vs ChatGPT对比分析

Clawdbot安装教程:2026一步步完整指南

📋 目录

你将学到什么

前置要求

必需 ✅

1. Node.js 18+

2. Claude API Key

3. 操作系统

可选 🔹

1. Git (如果从源码安装)

2. Docker (如果使用Docker部署)

3. Mac Mini M4 / VPS服务器 (推荐但非必需)

方法1: npm安装 (推荐⭐)

步骤1: 安装Clawdbot CLI

步骤2: 验证安装

步骤3: 初始化配置

步骤4: 启动Clawdbot

步骤5: 第一次对话

方法2: 从源码安装

步骤1: 克隆仓库

步骤2: 安装依赖

步骤3: 构建

步骤4: 链接到全局

步骤5: 初始化和启动

方法3: Docker部署

步骤1: 创建工作目录

步骤2: 创建docker-compose.yml

步骤3: 启动容器

步骤4: 进入容器交互

Docker管理命令

首次配置详解

配置文件位置

配置文件结构

手动编辑配置

高级配置选项

1. 启用Web界面

2. 配置代理(国内用户)

3. 自定义数据库

验证安装

基础验证清单

健康检查输出示例

测试基本功能

常见问题排查

问题1: clawdbot: command not found

问题2: API Key错误

问题3: 端口占用 (Web模式)

问题4: 权限错误

问题5: Node.js版本过低

问题6: 国内网络访问Claude API失败

问题7: Clawdbot无输出 (No Output)

下一步做什么?

推荐下一步

1. 安装热门技能 🛠️

2. 配置多平台集成 💬

3. 设置主动提醒 ⏰

4. 24/7后台运行 🔄

5. 自定义配置 ⚙️

推荐阅读

加入社区

总结清单

关于本教程

问题1: `clawdbot: command not found`