Clawdbot 完整配置指南

概述

Clawdbot 是一个开源的本地 AI 助手，支持通过消息应用（Telegram、WhatsApp、Discord 等）或 Web UI 与 AI 模型交互。本指南将详细介绍从安装到配置的完整流程。

注意： 当前 clawdbot 已改名为 openclaw，新版本需要将指令中的 clawdbot 替换为 openclaw

核心特点：

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

参考资源：

本文摘自：https://github.com/xianyu110/clawbot/blob/main/README.md
推荐新教程：Clawdbot 安装教程：从零开始到接入飞书

系统要求

必需条件

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

可选条件

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

安装步骤

升级 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

选择安装方式

方式一：npm 安装（推荐）

1	npm install -g clawdbot

方式二：一键安装脚本

1	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

初始化配置

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

1	clawdbot onboard

配置向导详解

安全确认

首先会显示安全提示：

◇  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

⚠️ 重要提示： Clawdbot 具有执行命令和读写文件的权限，使用前请仔细阅读安全文档。

选择 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 按量付费用户	最直接	需要独立付费

生成 setup-token（Claude Max 用户）

如果选择 setup-token 方式，在另一个终端运行：

1	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 即可复用订阅额度。

配置消息平台（可选）

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

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

获取 Telegram Bot Token

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

完成配置

◇  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.

配对验证（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>

在终端批准配对：

1	clawdbot pairing approve telegram ABC12345

配置自定义 API 中转

多模型中转站配置（推荐）

该方案支持同时配置 GPT、Claude、Gemini 等多个模型。

获取 API 凭证

推荐服务：

API Base URL: https://apipro.maynor1024.live
API Key: sk-xxxxxxxxxxxxx
推荐链接：
- API 地址：https://apipro.maynor1024.live/
- 购买链接：https://maynorai.tqfk.xyz/item/7

修改主配置文件

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

备份配置文件：

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

编辑配置文件：

1	nano ~/.clawdbot/clawdbot.json

配置示例：

{
  "models": {
    "mode": "merge",
    "providers": {
      "api-proxy-gpt": {
        "baseUrl": "https://apipro.maynor1024.live/v1",
        "api": "openai-completions",
        "apiKey": "sk-你的API密钥",
        "models": [
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      },
      "api-proxy-claude": {
        "baseUrl": "https://apipro.maynor1024.live",
        "api": "anthropic-messages",
        "apiKey": "sk-你的API密钥",
        "models": [
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      },
      "api-proxy-google": {
        "baseUrl": "https://apipro.maynor1024.live/v1beta",
        "api": "google-generative-ai",
        "apiKey": "sk-你的API密钥",
        "models": [
          {
            "id": "gemini-3-pro-preview",
            "name": "Gemini 3 Pro",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 2000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "api-proxy-claude/claude-sonnet-4-5-20250929"
      },
      "models": {
        "api-proxy-gpt/gpt-4o": {
          "alias": "GPT-4o"
        },
        "api-proxy-claude/claude-sonnet-4-5-20250929": {
          "alias": "Claude Sonnet 4.5"
        },
        "api-proxy-google/gemini-3-pro-preview": {
          "alias": "Gemini 3 Pro"
        }
      }
    }
  },
  "auth": {
    "profiles": {
      "api-proxy-gpt:default": {
        "provider": "api-proxy-gpt",
        "mode": "api_key"
      },
      "api-proxy-claude:default": {
        "provider": "api-proxy-claude",
        "mode": "api_key"
      },
      "api-proxy-google:default": {
        "provider": "api-proxy-google",
        "mode": "api_key"
      }
    }
  }
}

关键配置说明：

字段	说明	必需
baseUrl	自定义 API 端点	✅
apiKey	你的 API 密钥	✅
api	API 类型（openai-completions/anthropic-messages/google-generative-ai）	✅
models	模型列表，必须包含此字段	✅

配置鉴权文件

编辑 ~/.clawdbot/agents/main/agent/auth-profiles.json：

1	nano ~/.clawdbot/agents/main/agent/auth-profiles.json

添加以下内容：

{
  "version": 1,
  "profiles": {
    "api-proxy-gpt:default": {
      "type": "api_key",
      "provider": "api-proxy-gpt",
      "key": "sk-你的API密钥"
    },
    "api-proxy-claude:default": {
      "type": "api_key",
      "provider": "api-proxy-claude",
      "key": "sk-你的API密钥"
    },
    "api-proxy-google:default": {
      "type": "api_key",
      "provider": "api-proxy-google",
      "key": "sk-你的API密钥"
    }
  },
  "lastGood": {
    "api-proxy-gpt": "api-proxy-gpt:default",
    "api-proxy-claude": "api-proxy-claude:default",
    "api-proxy-google": "api-proxy-google:default"
  }
}

Claude Code 中转配置（需要 User-Agent）

如果使用需要 Claude Code User-Agent 验证的中转站：

获取 API 凭证

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

配置文件（带 User-Agent）

{
  "models": {
    "providers": {
      "code-claude-opus": {
        "baseUrl": "https://code.claude-opus.top/api",
        "apiKey": "cr_你的API密钥",
        "auth": "api-key",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-opus-4-20250514",
            "name": "Claude Opus 4",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192,
            "headers": {
              "User-Agent": "Claude-Code/1.0.0"
            }
          }
        ]
      }
    }
  }
}

关键点： 在 models 数组的每个模型中添加 headers 字段来设置自定义 User-Agent。

验证配置格式

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

# 验证鉴权配置
cat ~/.clawdbot/agents/main/agent/auth-profiles.json | jq '.'

重启 Gateway 服务

1	clawdbot gateway restart

验证配置生效

# 检查 Gateway 状态
clawdbot channels status

# 应该显示：
# Gateway reachable.

验证和测试

检查 Gateway 状态

1	clawdbot channels status

正常输出：

1 2	Gateway reachable. - Telegram default: disabled, configured, stopped

访问 Web UI

打开浏览器访问：

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

Web UI 功能：

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

发送测试消息

在 Web UI 的 Chat 界面：

输入消息：Hello, can you hear me?
点击 Send 按钮
等待 AI 回复

预期结果：

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

查看日志

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

# 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
2
3

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

缺少 models 字段

❌ 错误配置：

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

错误信息：

1 2	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": []  // 必须有这一行！
      }
    }
  }
}

Telegram 连接失败导致 Gateway 不稳定

症状：

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

✅ 解决方案： 临时禁用 Telegram：

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

Node.js 版本过低

错误信息：

1 2	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

中转 API 需要特定 User-Agent

症状： API 返回 403 错误，提示 "本服务仅限 Claude Code 官方客户端使用"

问题原因： 某些中转站要求特定的 User-Agent header。

✅ 解决方案： 在模型配置中添加 headers 字段：

{
  "models": {
    "providers": {
      "code-claude-opus": {
        "baseUrl": "https://code.claude-opus.top/api",
        "apiKey": "cr_你的密钥",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-opus-4-20250514",
            "name": "Claude Opus 4",
            "headers": {
              "User-Agent": "Claude-Code/1.0.0"
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

忘记重启 Gateway

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

✅ 解决方案：

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

# 验证配置生效
clawdbot channels status

常见问题

Gateway 无法连接

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

解决方案：

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

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

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

# 重启 Gateway
clawdbot gateway restart

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

API 调用失败

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

解决方案：

# 测试 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"}]}'

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

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

# 重启 Gateway
clawdbot gateway restart

Assistant 不回复消息

症状：

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

解决方案：

确认使用配置文件方式（见"配置自定义 API 中转"章节）
检查配置文件格式正确
重启 Gateway
在 Web UI 中发送测试消息

如何查看详细日志

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

如何完全重置配置

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

# 停止 Gateway
clawdbot gateway stop

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

# 重新运行配置向导
clawdbot onboard

常用命令参考

Gateway 管理

# 查看状态
clawdbot channels status

# 深度检查
clawdbot channels status --deep

# 重启 Gateway
clawdbot gateway restart

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

# 启动 Gateway（macOS）
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 和 TUI

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

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

# 启动 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   # 详细调试日志

安全建议

保护 API Key

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

Gateway Token

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

网络安全

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

数据备份

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

最佳实践

配置要点

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

参考资源

官方资源：

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

│ └── 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/
GitHub仓库: https://github.com/clawdbot/clawdbot
官方网站: https://clawd.bot/
社区讨论: GitHub Issues

关键要点

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