Clawdbot完整配置指南：从安装到Claude Code中转

DevOps 1 周前 0 92

简介

Clawdbot是一个开源的本地AI助手，支持通过消息应用或Web UI与AI模型交互。

核心特点：

完全开源，数据本地存储
支持多种消息平台
提供Web控制面板
可自定义AI模型和API端点

系统要求

必需条件

操作系统: macOS / Linux / Windows
Node.js: 22.0.0 或更高版本
包管理器: pnpm（推荐）或 npm

可选条件

Xcode（仅macOS，如需构建原生应用）
消息平台账号（Telegram Bot Token、Discord Bot等）

安装步骤

1. 升级Node.js版本

Clawdbot要求Node.js 22+，使用nvm管理版本：

# 安装Node.js 22
nvm install 22

# 设置为默认版本
nvm use 22
nvm alias default 22

# 验证版本
node --version

应该显示 v22.x.x

2. 选择安装方式

方式一：npm安装（推荐）

npm install -g clawdbot

方式二：一键安装脚本

curl -fsSL https://clawd.bot/install.sh | bash

方式三：从源码安装

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

# 安装依赖
pnpm install

# 构建
pnpm build

# 链接CLI
npm link

3. 初始化配置

安装完成后运行配置向导：

clawdbot onboard

步骤1：安全确认

Clawdbot agents can run commands, read/write files, and act through any tools you enable.

Please read: https://docs.clawd.bot/security

I understand this is powerful and inherently risky. Continue? Yes

步骤2：选择AI后端

Model/auth provider: Anthropic
Anthropic auth method:
  Anthropic token (paste setup-token) - 推荐Claude Max用户
  Anthropic token (Claude Code CLI)
  Anthropic API key

认证方式对比：

认证方式	适用场景	优点	缺点
setup-token	Claude Max/Pro订阅用户	无需额外付费	需要额外步骤生成token
Claude Code CLI	已配置Claude Code的用户	自动读取凭证	可能找不到凭证文件
API Key	API按量付费用户	最直接	需要独立付费

步骤3：生成setup-token（Claude Max用户）

在另一个终端运行：

claude setup-token

复制生成的token，粘贴到配置向导中。

提示： Claude Max订阅用户不需要单独购买API Key，使用setup-token即可复用订阅额度。

步骤4：配置消息平台（可选）

获取Telegram Bot Token：

在Telegram中搜索 @BotFather
发送 /newbot
按提示输入Bot名称和用户名
复制Bot Token

步骤5：完成配置

Telegram: ok (@YourBotName) (1416ms)
Agents: main (default)
Heartbeat interval: 1h (main)

Control UI:
Web UI: http://127.0.0.1:18789/
Web UI (with token): http://127.0.0.1:18789/?token=your-token

Onboarding complete.

步骤6：配对验证（如使用Telegram）

去Telegram给你的Bot发消息，会收到配对码，然后在终端批准配对：

clawdbot pairing approve telegram ABC12345

配置Claude Code API中转

1. 获取API凭证

从Claude Code API中转服务获取：

API Base URL: https://code.claude-opus.top/api
API Key: cr_xxxxxxxxxxxxx

推荐服务：

购买链接：https://maynorai.tqfk.xyz/item/7
推荐中转API：https://apipro.maynor1024.live/

2. 修改配置文件

重要提示： Clawdbot不支持通过环境变量ANTHROPIC_BASE_URL来设置自定义API端点。必须通过配置文件的models.providers来配置。

步骤1：备份配置文件

cp ~/.clawdbot/clawdbot.json ~/.clawdbot/clawdbot.json.bak

步骤2：编辑配置文件

nano ~/.clawdbot/clawdbot.json

在配置文件中添加models部分：

{
  "models": {
    "providers": {
      "anthropic": {
        "baseUrl": "https://code.claude-opus.top/api",
        "apiKey": "cr_你的API密钥",
        "api": "anthropic-messages",
        "models": []
      }
    }
  }
}

关键配置说明：

字段	说明	必需
baseUrl	自定义API端点	是
apiKey	你的API密钥	是
api	必须设置为anthropic-messages	是
models	必须包含此字段，可以为空数组[]	是

完整配置示例：

{
  "meta": {
    "lastTouchedVersion": "2026.1.25"
  },
  "models": {
    "providers": {
      "anthropic": {
        "baseUrl": "https://code.claude-opus.top/api",
        "apiKey": "cr_你的API密钥",
        "api": "anthropic-messages",
        "models": []
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-5"
      },
      "workspace": "/Users/你的用户名/clawd",
      "maxConcurrent": 4
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "你的gateway_token"
    }
  },
  "channels": {
    "telegram": {
      "enabled": false
    }
  }
}

步骤3：验证配置格式

cat ~/.clawdbot/clawdbot.json | jq '.models'

3. 重启Gateway服务

clawdbot gateway restart

4. 验证配置生效

clawdbot channels status

正常输出：Gateway reachable.

验证和测试

1. 检查Gateway状态

clawdbot channels status

2. 访问Web UI

打开浏览器访问：http://127.0.0.1:18789/?token=你的token

Web UI功能：

Chat: 直接与AI对话
Overview: 查看系统状态
Channels: 管理消息通道
Config: 修改配置

3. 发送测试消息

在Web UI的Chat界面输入消息并发送，等待AI回复。

4. 查看日志

# Gateway主日志
tail -f ~/.clawdbot/logs/gateway.log

# 错误日志
tail -f ~/.clawdbot/logs/gateway.err.log

# 详细调试日志
tail -f /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log

常见踩坑点

踩坑1：环境变量配置无效

错误做法： 设置 ANTHROPIC_BASE_URL=https://code.claude-opus.top/api

问题原因： Clawdbot不支持通过环境变量ANTHROPIC_BASE_URL来设置自定义API端点。

正确做法： 在配置文件中添加models部分。

踩坑2：缺少models字段

错误配置： 缺少 models 字段

错误信息： models.providers.anthropic.models: Invalid input: expected array

正确做法： 必须包含models字段，即使是空数组 []

踩坑3：Telegram连接失败导致Gateway不稳定

症状： Gateway不断重启，日志显示TypeError: fetch failed

解决方案： 临时禁用Telegram

clawdbot config set channels.telegram.enabled false
clawdbot gateway restart

踩坑4：Node.js版本过低

错误信息： clawdbot requires Node >=22.0.0. Detected: node 20.19.0

解决方案：

nvm install 22
nvm use 22
nvm alias default 22

踩坑5：忘记重启Gateway

问题： 修改配置后没有重启Gateway，配置不生效。

解决方案： 每次修改配置后运行 clawdbot gateway restart

常用命令

Gateway管理

# 查看状态
clawdbot channels status

# 深度检查
clawdbot channels status --deep

# 重启Gateway
clawdbot gateway restart

# 停止Gateway
launchctl unload ~/Library/LaunchAgents/com.clawdbot.gateway.plist

# 启动Gateway
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.clawdbot.gateway.plist

配置管理

# 交互式配置
clawdbot configure

# 配置特定部分
clawdbot configure --section gateway
clawdbot configure --section channels
clawdbot configure --section model

# 设置配置项
clawdbot config set gateway.mode local
clawdbot config set channels.telegram.enabled false

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

日志查看

# Gateway主日志
tail -f ~/.clawdbot/logs/gateway.log

# 错误日志
tail -f ~/.clawdbot/logs/gateway.err.log

# 详细日志（JSON格式）
tail -f /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log

诊断工具

# 运行诊断
clawdbot doctor

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

Web UI

# 打开Web UI（浏览器）
clawdbot dashboard

# 获取带token的URL（不打开浏览器）
clawdbot dashboard --no-open

TUI（终端界面）

# 启动TUI
clawdbot tui

# TUI快捷键
# Ctrl+C: 退出
# Enter: 发送消息
# Shift+Enter: 换行

更新

# 从源码更新
cd /path/to/clawdbot
git pull --rebase
pnpm install
pnpm build
clawdbot gateway restart

# 从npm更新（全局安装）
npm install -g clawdbot@latest

配置文件位置

~/.clawdbot/
├── clawdbot.json          # 主配置文件
├── credentials/           # API凭证
├── sessions/             # 会话数据
├── logs/                 # 日志文件
│   ├── gateway.log       # Gateway主日志
│   └── gateway.err.log   # 错误日志
└── agents/               # Agent工作空间

~/Library/LaunchAgents/  # macOS服务配置
└── com.clawdbot.gateway.plist

/tmp/clawdbot/            # 临时日志
└── clawdbot-YYYY-MM-DD.log

安全建议

保护API Key: 不要将API Key提交到Git，定期轮换API Key
Gateway Token: 不要分享Web UI的token URL，定期更换Gateway token
网络安全: Gateway默认只监听localhost，如需远程访问，使用Tailscale或VPN，不要直接暴露到公网
数据备份: tar -czf clawdbot-backup-$(date +%Y%m%d).tar.gz ~/.clawdbot/

参考资源

官方文档: https://docs.clawd.bot/
GitHub仓库: https://github.com/clawdbot/clawdbot
官方网站: https://clawd.bot/

总结

通过本教程，你应该已经：

成功安装Clawdbot
正确配置Claude Code API中转（通过配置文件）
启动Gateway服务
通过Web UI与AI对话
了解常用命令和故障排除
避开所有常见踩坑点

关键要点

API配置方式： 必须使用配置文件~/.clawdbot/clawdbot.json中的models.providers
必需字段： baseUrl、apiKey、api、models四个字段缺一不可
配置后重启： 每次修改配置后必须运行clawdbot gateway restart
Telegram问题： 如遇连接问题，先禁用Telegram使用Web UI
Node.js版本： 必须22.0.0或更高

快速参考

# 查看状态
clawdbot channels status

# 重启Gateway
clawdbot gateway restart

# 查看日志
tail -f ~/.clawdbot/logs/gateway.log

# 打开Web UI
clawdbot dashboard

# 配置文件位置
~/.clawdbot/clawdbot.json

祝使用愉快！

教程版本： v2.0 (2026-01-27)

适用版本： Clawdbot 2026.1.25+

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。

elasticsearch

简介