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

在终端批准配对：

```bash
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](https://maynorai.tqfk.xyz/item/7)
- 推荐中转API：[https://apipro.maynor1024.live/](https://apipro.maynor1024.live/)

### 2. 修改配置文件

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

#### 步骤1：备份配置文件

```bash
cp ~/.clawdbot/clawdbot.json ~/.clawdbot/clawdbot.json.bak
```

#### 步骤2：编辑配置文件

```bash
nano ~/.clawdbot/clawdbot.json
```

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

```json
{
"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 | 必须包含此字段，可以为空数组[] | ✅ |

完整配置示例：

```json
{
"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：验证配置格式

```bash
# 使用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服务

```bash
clawdbot gateway restart
```

### 4. 验证配置生效

```bash
# 检查Gateway状态
clawdbot channels status

# 应该显示：
# Gateway reachable.
```

## 验证和测试

### 1. 检查Gateway状态

```bash
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界面：
- 输入消息：Hello, can you hear me?
- 点击Send按钮
- 等待AI回复

预期结果：
- 状态显示"Health OK"
- 收到AI的回复消息
- 右上角显示token使用情况

### 4. 查看日志

如果遇到问题，检查日志：

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

**错误做法：**

```xml

ANTHROPIC_BASE_URL
https://code.claude-opus.top/api
```

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

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

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

### ❌ 踩坑2：缺少models字段

**错误配置：**

```json
{
"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字段，即使是空数组：

```json
{
"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：

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

### ❌ 踩坑4：Node.js版本过低

**错误信息：**

```
clawdbot requires Node >=22.0.0.
Detected: node 20.19.0
```

**✅ 解决方案：**

```bash
nvm install 22
nvm use 22
nvm alias default 22
node --version # 应显示 v22.x.x
```

### ❌ 踩坑5：忘记重启Gateway

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

**✅ 解决方案：**

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

# 验证配置生效
clawdbot channels status
```

## 常见问题FAQ

### Q1: Gateway无法连接

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

**解决方案：**

```bash
# 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"

**解决方案：**

```bash
# 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发送消息后无响应
- 日志显示请求完成但耗时很短（<100ms）

**解决方案：**
- 确认使用配置文件方式（见"配置Claude Code API中转"章节）
- 检查配置文件格式正确
- 重启Gateway
- 在Web UI中发送测试消息

### Q4: 如何查看详细日志？

```bash
# 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: 如何完全重置配置？

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

# 2. 停止Gateway
clawdbot gateway stop

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

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

## 常用命令

### Gateway管理

```bash
# 查看状态
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
```

### 配置管理

```bash
# 交互式配置
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
```

### 日志查看

```bash
# 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
```

### 诊断工具

```bash
# 运行诊断
clawdbot doctor

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

# 安全审计
clawdbot security audit --deep
```

### Web UI

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

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

### TUI（终端界面）

```bash
# 启动TUI
clawdbot tui

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

### 更新

```bash
# 从源码更新
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. 数据备份

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

## 参考资源

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

## 总结

通过本教程，你应该已经：
✅ 成功安装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或更高

### 快速参考

```bash
# 查看状态
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+

cnbugsai

打赏 海报 链接