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

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

目录

• 简介
• 系统要求
• 安装步骤
• 配置Claude Code API中转
• 验证和测试
• 常见踩坑点
• 常见问题FAQ
• 常用命令

简介

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

核心特点：

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

系统要求

必需条件

可选条件

• 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：安全确认

◇ Security ───────────────────────────────────────────────────────╮
│ 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

认证方式对比：

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

在另一个终端运行：

claude setup-token

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

◇ Paste Anthropic setup-token
│ sk-ant-oat01-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx…

◇ Token name (blank = default)
│ default

◇ Default model
│ Keep current (default: anthropic/claude-opus-4-5)

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

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

◇ Channel status ────────────────────────────╮
│ Telegram: not configured │
│ WhatsApp: not configured │
│ Discord: not configured │
│ …共支持 12+ 平台 │
├─────────────────────────────────────────────╯

◇ Select channel (QuickStart)
│ Telegram (Bot API)

获取Telegram 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 │
│ Gateway WS: ws://127.0.0.1:18789 │
├──────────────────────────────────────────────────────────────────╯

└ Onboarding complete.

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

去Telegram给你的Bot发消息，会收到配对码：

Clawdbot: access not configured.

Your Telegram user id: 1234567890
Pairing code: ABC12345

Ask the bot owner to approve with:
clawdbot pairing approve telegram <code>

在终端批准配对：

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": []
}
}
}
}

关键配置说明：

完整配置示例：

{
"meta": {
"lastTouchedVersion": "2026.1.25",
"lastTouchedAt": "2026-01-27T01:05:21.233Z"
},
"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：验证配置格式

# 使用jq验证JSON格式
cat ~/.clawdbot/clawdbot.json | jq '.models'

# 应该输出：
# {
# "providers": {
# "anthropic": {
# "baseUrl": "https://code.claude-opus.top/api",
# "apiKey": "cr_…",
# "api": "anthropic-messages",
# "models": []
# }
# }
# }

3. 重启Gateway服务

clawdbot gateway restart

4. 验证配置生效

# 检查Gateway状态
clawdbot channels status

# 应该显示：
# Gateway reachable.

验证和测试

1. 检查Gateway状态

clawdbot channels status

正常输出：

Gateway reachable.
– Telegram default: disabled, configured, stopped

2. 访问Web UI

打开浏览器访问：

http://127.0.0.1:18789/?token=你的token

Web UI功能：

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

3. 发送测试消息

在Web UI的Chat界面：

预期结果：

• 状态显示"Health OK"
• 收到AI的回复消息
• 右上角显示token使用情况

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：环境变量配置无效

错误做法：

# 在LaunchAgent中设置环境变量（无效！）
<key>ANTHROPIC_BASE_URL</key>
<string>https://code.claude-opus.top/api</string>

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

✅ 正确做法： 在~/.clawdbot/clawdbot.json配置文件中添加：

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

❌ 踩坑2：缺少models字段

错误配置：

{
"models": {
"providers": {
"anthropic": {
"baseUrl": "https://code.claude-opus.top/api",
"apiKey": "cr_xxx",
"api": "anthropic-messages"
// 缺少models字段！
}
}
}
}

错误信息：

Invalid config at ~/.clawdbot/clawdbot.json:
– models.providers.anthropic.models: Invalid input: expected array

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

{
"models": {
"providers": {
"anthropic": {
"baseUrl": "https://code.claude-opus.top/api",
"apiKey": "cr_xxx",
"api": "anthropic-messages",
"models": [] // 必须有这一行！
}
}
}
}

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

症状：

• Gateway不断重启
• 日志显示TypeError: fetch failed
• Web UI无法连接

✅ 解决方案： 临时禁用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
node –version # 应显示 v22.x.x

❌ 踩坑5：忘记重启Gateway

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

✅ 解决方案：

# 每次修改配置后都要重启
clawdbot gateway restart

# 验证配置生效
clawdbot channels status

常见问题FAQ

Q1: Gateway无法连接

症状： Web UI显示"disconnected (1006): no reason"

解决方案：

# 1. 检查Gateway是否运行
ps aux | grep clawdbot-gateway

# 2. 检查端口占用
lsof -i :18789

# 3. 检查配置文件是否有效
cat ~/.clawdbot/clawdbot.json | jq '.'

# 4. 重启Gateway
clawdbot gateway restart

# 5. 查看错误日志
tail -50 ~/.clawdbot/logs/gateway.err.log

Q2: API调用失败

症状： 日志显示"TypeError: fetch failed"

解决方案：

# 1. 测试API端点可访问性
curl -s https://code.claude-opus.top/api/v1/messages \\
-H "x-api-key: 你的API密钥" \\
-H "anthropic-version: 2023-06-01" \\
-H "content-type: application/json" \\
-d '{"model":"claude-sonnet-4-5","max_tokens":100,"messages":[{"role":"user","content":"hi"}]}'

# 2. 验证配置文件
cat ~/.clawdbot/clawdbot.json | jq '.models.providers.anthropic'

# 3. 确保包含所有必需字段
# – baseUrl
# – apiKey
# – api: "anthropic-messages"
# – models: []

# 4. 重启Gateway
clawdbot gateway restart

Q3: Assistant不回复消息

症状：

• Web UI发送消息后无响应
• 日志显示请求完成但耗时很短（< 1秒）
• 没有错误信息

解决方案：

Q4: 如何查看详细日志？

# 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

# 过滤错误信息
tail -f /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep -i "error\\|fail"

Q5: 如何完全重置配置？

# 1. 备份当前配置
cp -r ~/.clawdbot ~/.clawdbot.backup

# 2. 停止Gateway
clawdbot gateway stop

# 3. 删除配置
rm -rf ~/.clawdbot

# 4. 重新运行配置向导
clawdbot onboard

常用命令

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

# 安全审计
clawdbot security audit –deep

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工作空间
└── main/
└── sessions/ # 会话存储

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

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

安全建议

1. 保护API Key

• ❌ 不要将API Key提交到Git
• ✅ 定期轮换API Key
• ✅ 使用配置文件而非环境变量

2. Gateway Token

• ❌ 不要分享Web UI的token URL
• ✅ 定期更换Gateway token

3. 网络安全

• ✅ Gateway默认只监听localhost
• ✅ 如需远程访问，使用Tailscale或VPN
• ❌ 不要直接暴露到公网

4. 数据备份

# 备份配置和会话
tar -czf clawdbot-backup-$(date +%Y%m%d).tar.gz ~/.clawdbot/

参考资源

• 官方文档: https://docs.clawd.bot/
• GitHub仓库: https://github.com/clawdbot/clawdbot
• 官方网站: https://clawd.bot/
• 社区讨论: GitHub Issues

总结

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

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

关键要点

快速参考

# 查看状态
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) 更新内容： 修正API配置方式，添加完整踩坑指南 适用版本： Clawdbot 2026.1.25+