2026年1月28日星期三

Clawdbot Setup Guide ： Key Steps and Common Pitfalls for Third-Party API Integration

Summary: This guide details setting up Clawdbot, a local AI assistant, using a third-party API. It covers installation, configuration (emphasizing correct model provider setup with `mode: "merge"`), and troubleshooting common errors like incorrect base URLs. Essential commands and config management are included.

Clawdbot配置实战：我踩过的坑都在这了

image-20260127105421885
image-20260127105421885

最近在折腾Clawdbot，想用第三方API省点钱。网上的教程要么过时，要么写得太简略，踩了不少坑。

这篇文章记录一下完整的配置过程，以及我遇到的所有问题和解决方法。

什么是Clawdbot？

简单说，就是一个开源的本地AI助手。你可以通过Telegram、Discord或者网页跟它聊天。

为什么要用它？

  • 数据存在本地，不用担心隐私
  • 支持自定义API，可以用便宜的中转服务
  • 可以接入多个消息平台
  • 有Web界面，不用一直开着终端

开始之前

检查你的环境

先看看你的Node.js版本够不够：

# 检查Node.js版本（需要 >= 22）
node --version

如果版本低于22，需要升级：

# macOS用Homebrew安装
brew install node@22

# 或者用nvm管理版本
nvm install 22
nvm use 22
nvm alias default 22

其他要求：

项目
要求
Node.js
>= 22（推荐LTS）
操作系统
macOS / Linux / Windows（WSL2）
内存
>= 4GB（推荐8GB）
磁盘
>= 2GB可用空间

可选：安装pnpm

pnpm比npm快，但不是必须的：

# 检查是否已安装
pnpm --version

# 如果没有，安装它
npm install -g pnpm

安装Clawdbot

有三种安装方式，我推荐第一种。

方式一：npm安装

最简单直接：

npm install -g clawdbot

方式二：一键安装脚本（推荐）

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

这个脚本会自动：

  • 检测你的系统
  • 安装1000多个依赖包（需要点时间）
  • 编译TypeScript代码
  • 构建Web界面
  • 把命令行工具装到~/.local/bin/

方式三：从源码安装

如果你想自己编译：

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

# 2. 安装依赖
pnpm install

# 3. 构建
pnpm build

# 4. 链接CLI（可选）
npm link

初始化配置

安装完后运行：

clawdbot onboard

会出现一个有趣的ASCII龙虾Logo：

░████░█░░░░░█████░█░░░█░███░░████░░████░░▀█▀
█░░░░░█░░░░░█░░░█░█░█░█░█░░█░█░░░█░█░░░█░░█░
█░░░░░█░░░░░█████░█░█░█░█░░█░████░░█░░░█░░█░
█░░░░░█░░░░░█░░░█░█░█░█░█░░█░█░░█░░█░░░█░░█░
░████░█████░█░░░█░░█░█░░███░░████░░░███░░░█░
              🦞 FRESH DAILY 🦞

然后是一系列配置问题。

步骤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

这是提醒你Clawdbot有很大权限，选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用户）

如果你选择了"Anthropic token (paste setup-token)"，在另一个终端运行：

claude setup-token

会生成一个有效期1年的OAuth token：

✓ Long-lived authentication token created successfully!

Your OAuth token (valid for 1 year):

sk-ant-oat01-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...

Store this token securely. You won't be able to see it again.

复制这个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就能复用订阅额度。

Claude Max订阅链接：https://m.tb.cn/h.7K9RG5J?tk=ukJgUheYji3

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

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

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

如果你想用Telegram，需要先获取Bot Token：

  1. 在Telegram中搜索 @BotFather
  2. 发送 /newbot
  3. 按提示输入Bot名称和用户名
  4. 复制Bot Token（类似 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ123456789）

然后粘贴到配置向导：

◇  Telegram bot token ────────────────────────────╮
│  1) Open Telegram and chat with @BotFather      │
│  2) Run /newbot (or /mybots)                    │
│  3) Copy the token (looks like 123456:ABC...)   │
├─────────────────────────────────────────────────╯

◇  Enter Telegram bot token
│  123456789:ABCdefGHIjklMNOpqrSTUvwxYZ123456789

我的建议： 第一次配置可以跳过，先用Web界面测试。

步骤5：安装Gateway服务

◇  Gateway service runtime ────────────────────────────────────────────╮
│  QuickStart uses Node for the Gateway service (stable + supported).  │
├──────────────────────────────────────────────────────────────────────╯

◒  Installing Gateway service…
Installed LaunchAgent: /Users/your-username/Library/LaunchAgents/com.clawdbot.gateway.plist
Logs: /Users/your-username/.clawdbot/logs/gateway.log
◇  Gateway service installed

这一步会自动安装并启动Gateway服务。

步骤6：完成配置

◇
Telegram: ok (@YourBotName) (1416ms)  ← 你的Bot已连接
Agents: main (default)
Heartbeat interval: 1h (main)
Session store (main): /Users/your-username/.clawdbot/agents/main/sessions/sessions.json

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

记下这个Web UI的链接，待会要用。

步骤7：配对验证（如果配置了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

配对完成后，再发消息就能正常对话了。

配置第三方API（重点）


image-20260127103629796

这是最容易出错的地方。我前前后后试了好几次才搞定。

1. 获取API凭证

你需要从第三方API服务商那里拿到：

  • API地址（Base URL）
  • API密钥（API Key）

我用的是这个：https://apipro.maynor1024.live/

image-20260127103853734
image-20260127103853734

2. 正确的配置方法

重要提醒： 网上很多教程都是错的！不要直接覆盖anthropic provider，会导致其他模型用不了。

正确做法是创建一个独立的provider。

第一步：备份配置文件

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

第二步：编辑配置

nano ~/.clawdbot/clawdbot.json

找到或添加models部分，改成这样：

{
  "models": {
    "mode": "merge",
    "providers": {
      "myapi": {
        "baseUrl": "https://apipro.maynor1024.live",
        "apiKey": "sk-你的API密钥",
        "auth": "api-key",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-haiku-4-5-20251001",
            "name": "Claude Haiku 4.5",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "myapi/claude-haiku-4-5-20251001"
      }
    }
  }
}

几个关键点：

  1. mode: "merge" - 保留原有的模型，同时添加你的自定义模型
  2. providers.myapi - 这是你自定义的名字，可以改成任何你喜欢的
  3. baseUrl - 不要加/v1后缀，SDK会自动加
  4. models - 必须手动列出可用的模型
  5. primary - 格式是provider名称/模型ID

第三步：验证配置

# 检查JSON格式是否正确
cat ~/.clawdbot/clawdbot.json | jq '.models'

# 检查主模型设置
cat ~/.clawdbot/clawdbot.json | jq '.agents.defaults.model.primary'

如果没报错，说明格式是对的。

第四步：重启Gateway

clawdbot gateway restart

第五步：检查是否生效

clawdbot channels status

如果显示Gateway reachable.，说明配置成功了。

测试一下

打开Web界面

浏览器访问：

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

token在配置时会显示，如果忘了可以运行：

clawdbot dashboard --no-open
image-20260127104248766
image-20260127104248766

发个消息试试

在Chat界面输入：你好，能听到吗？

如果AI回复了，说明配置成功。

右上角会显示你用的模型名称，应该是myapi/claude-haiku-4-5-20251001。

如果没反应

看看日志：

tail -f ~/.clawdbot/logs/gateway.log

如果有错误，往下看"常见问题"部分。

我踩过的坑

坑1：直接改anthropic配置

我一开始这样做的：

{
  "providers": {
    "anthropic": {
      "baseUrl": "https://apipro.maynor1024.live"
    }
  }
}

结果其他Claude模型全挂了。

正确做法： 创建独立的provider，用mode: "merge"保留原有模型。

坑2：baseUrl加了/v1

我一开始写的：

{
  "baseUrl": "https://apipro.maynor1024.live/v1"
}

结果一直404。

原因： SDK会自动加/v1/messages，你再加一次就变成/v1/v1/messages了。

正确做法： baseUrl不要加/v1。

坑3：用环境变量配置

我试过这样：

export ANTHROPIC_BASE_URL="https://apipro.maynor1024.live"

完全没用。

原因： Clawdbot不支持通过环境变量设置自定义API。

正确做法： 只能用配置文件。

坑4：忘了models字段

我一开始漏了这个：

{
  "providers": {
    "myapi": {
      "baseUrl": "https://apipro.maynor1024.live",
      "apiKey": "sk-xxx",
      "api": "anthropic-messages"
      // 没有models字段
    }
  }
}

启动时报错：expected array, received undefined

正确做法： 必须加上models: []，即使是空数组也要写。

坑5：模型ID格式错误

我一开始写的：

{
  "primary": "claude-haiku-4-5-20251001"
}

结果找不到模型。

原因： 必须加上provider前缀。

正确做法：myapi/claude-haiku-4-5-20251001

坑6：改完配置忘了重启

这个最坑。改完配置文件，发现没生效，折腾半天才想起来没重启。

记住： 每次改配置都要运行：

clawdbot gateway restart

常见问题

Q: 怎么测试API是否可用？

用curl测试一下：

curl -s https://apipro.maynor1024.live/v1/messages \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":20,"messages":[{"role":"user","content":"hi"}]}'

注意：curl测试时要加/v1，但配置文件里不要加。

Q: 怎么看详细错误？

# 看Gateway日志
tail -50 ~/.clawdbot/logs/gateway.err.log

# 实时监控错误
tail -f /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep -i error

Q: 怎么添加多个模型？

在models数组里加就行：

{
  "models": [
    {
      "id": "claude-haiku-4-5-20251001",
      "name": "Claude Haiku 4.5"
    },
    {
      "id": "claude-sonnet-4-5",
      "name": "Claude Sonnet 4.5"
    }
  ]
}

Q: 怎么切换模型？

# 方法1：改配置文件
nano ~/.clawdbot/clawdbot.json
# 修改 agents.defaults.model.primary

# 方法2：用命令行
clawdbot config set agents.defaults.model.primary "myapi/claude-sonnet-4-5"

# 别忘了重启
clawdbot gateway restart

Q: Gateway连不上怎么办？

# 1. 看看Gateway是不是在运行
ps aux | grep clawdbot-gateway

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

# 3. 检查配置文件格式
cat ~/.clawdbot/clawdbot.json | jq '.'

# 4. 重启试试
clawdbot gateway restart

# 5. 看日志找原因
tail -50 ~/.clawdbot/logs/gateway.log

Q: 想重新配置怎么办？

# 1. 先备份
cp -r ~/.clawdbot ~/.clawdbot.backup

# 2. 停止Gateway
clawdbot gateway stop

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

# 4. 重新配置
clawdbot onboard

常用命令

Gateway管理

# 查看状态
clawdbot channels status

# 重启
clawdbot gateway restart

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

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

查看日志

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

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

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

配置管理

# 交互式配置
clawdbot configure

# 设置配置项
clawdbot config set gateway.mode local

# 查看配置
cat ~/.clawdbot/clawdbot.json | jq '.'

打开Web界面

# 直接打开浏览器
clawdbot dashboard

# 只显示URL不打开
clawdbot dashboard --no-open

配置文件位置

~/.clawdbot/
├── clawdbot.json              # 主配置文件
├── logs/                      # 日志文件
│   ├── gateway.log           # 主日志
│   └── gateway.err.log       # 错误日志
└── agents/                    # Agent工作空间

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

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

我的配置（已验证可用）

这是我现在在用的配置，确认可以正常工作：

API服务： https://apipro.maynor1024.live/
模型： claude-haiku-4-5-20251001

{
  "models": {
    "mode": "merge",
    "providers": {
      "myapi": {
        "baseUrl": "https://apipro.maynor1024.live",
        "apiKey": "sk-你的密钥",
        "auth": "api-key",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-haiku-4-5-20251001",
            "name": "Claude Haiku 4.5",
            "reasoning": false,
            "input": ["text"],
            "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "myapi/claude-haiku-4-5-20251001"
      }
    }
  }
}

测试结果：

  • Web界面正常对话
  • Token计数准确
  • 响应速度正常
  • 原有的Anthropic模型还能用

Gateway服务管理

这部分很重要，我一开始搞不清楚这些命令的区别。

常用命令

命令
作用
说明
clawdbot gateway
前台运行
关闭终端会停止
clawdbot gateway install
安装服务
同时启动，开机自启
clawdbot gateway start
启动服务
需要先install
clawdbot gateway stop
停止服务
会卸载服务
clawdbot gateway status
查看状态
检查服务是否运行

查看服务状态

clawdbot gateway status

运行中的输出：

◇
Service: LaunchAgent (loaded)
Runtime: running (pid 14416, state active)
RPC probe: ok
Listening: 127.0.0.1:18789

未运行的输出：

◇
Service: LaunchAgent (not loaded)
Runtime: unknown
RPC probe: failed
Service not installed. Run: clawdbot gateway install

一个坑：stop后无法start

我遇到过这个问题：

clawdbot gateway stop
# Stopped LaunchAgent: gui/501/com.clawdbot.gateway

clawdbot gateway start
# Gateway service not loaded.
# Start with: clawdbot gateway install

原因：clawdbot gateway stop会完全卸载LaunchAgent，而不是只暂停它。

解决方案：

# 方法1：重新安装（推荐）
clawdbot gateway install

# 方法2：用launchctl手动加载
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.gateway.plist

# 方法3：直接前台运行
clawdbot gateway

我的建议：

  • 需要重启时，用clawdbot gateway install（会自动重启）
  • 想要前台调试时，用clawdbot gateway（看实时日志）
  • 不要轻易用stop，除非你确定要停止服务

TUI模式：和Bot"培养感情"

Clawdbot有个独特的TUI（终端UI）模式，用来初始化Bot的人格：

clawdbot tui

会出现这样的界面：

┌ clawdbot tui - ws://127.0.0.1:18789 - agent main - session main ┐
│                                                                  │
│  session agent:main:main                                         │
│                                                                  │
│  Wake up, my friend!                                             │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
⠋ dillydallying… • 0s | gateway connected
agent main | session main | anthropic/claude-opus-4-5 | tokens 0/200k

在TUI中，你可以：

  • 告诉它你的偏好和习惯
  • 设置它的性格和说话风格
  • 进行初始化对话，建立"记忆基础"

提示： Clawdbot会记住你在TUI中说的所有内容，这就是它"认识你"的开始。

让它24小时运行

如果你希望Clawdbot一直在线（推荐）：

macOS（LaunchAgent自动配置）

# onboard时选择安装Gateway服务即可
# 或者手动安装
clawdbot gateway install

服务文件位置：~/Library/LaunchAgents/com.clawdbot.gateway.plist

Linux（使用systemd）

创建service文件：

sudo cat > /etc/systemd/system/clawdbot.service << 'EOF'
[Unit]
Description=Clawdbot Gateway
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/usr/bin/node /usr/lib/node_modules/clawdbot/dist/entry.js gateway --port 18789
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 启用并启动
sudo systemctl enable clawdbot
sudo systemctl start clawdbot

配置文件位置

这些位置你可能会用到：

文件/目录
作用
~/.clawdbot/clawdbot.json
主配置文件
~/.clawdbot/agents/main/agent/auth-profiles.json
认证配置
~/.clawdbot/agents/main/sessions/
会话存储
~/.clawdbot/skills/
用户技能目录
~/clawd/
工作空间（Workspace）
/tmp/clawdbot/clawdbot-YYYY-MM-DD.log
日志文件
~/Library/LaunchAgents/com.clawdbot.gateway.plist
macOS服务配置

写在最后

Clawdbot的配置确实有点复杂，特别是第三方API这块，文档写得不够清楚。

我踩了这么多坑，总结下来就几个要点：

  1. 不要覆盖原有的provider，创建独立的
  2. baseUrl不要加/v1
  3. 模型ID要加provider前缀
  4. 必须有models字段
  5. 改完配置记得重启

希望这篇文章能帮你少走弯路。

如果还有问题，可以看看官方文档：https://docs.clawd.bot/

或者去GitHub Issues找找：https://github.com/clawdbot/clawdbot

最后更新： 2026-01-27
适用版本： Clawdbot 2026.1.25+

时间：

没有评论:

发表评论

订阅： 博文评论 (Atom)

腾讯“元宝派”内测引爆AI社交，百人群聊秒满，微信QQ首度打通

2026年腾讯推出AI社交功能"元宝派"，用户可创建百人群聊，微信QQ好友首次互通。元宝集成对话、生图、总结等AI能力，斗图聊天趣味十足，未来将打通腾讯全生态。目前内测火爆，功能持续优化中。 劲爆的东西来了。 2026年开年，腾讯正式进军AI社交赛道。 元...

  • 让你头疼的扣子(coze)工作流异常解决方案
    点击上方卡片关注 不要错过精彩文章 　 🎉 读完这篇文章，别忘记给舰长点一个关注！舰长的智能体搭建文章，不仅是节点的构建，也有思路的分享。智能体搭建最重要的就是思路。最希望，能给大家带来不一样的搭建思路和方法。　 　 点一点上方的🔵蓝色小字关注，你的支持是我最大的动力！...
  • 元镜：AI短剧创作新利器 (附实操示例)
    大家好，今天要聊聊一款新发现的AI工具——元镜（aimovie.gstai.com）。 它不仅仅是一个文本创作工具，更是一款强大的短视频创作利器。 什么是元镜？ 元镜是一个基于人工智能的短视频创作平台，它利用AI技术帮助用户快速、轻松地创作出各种类型的短视频内容。无论是文旅宣...