clawbot

883 124 简单 1 次阅读昨天语言模型Agent插件

AI 解读由 AI 自动生成，仅供参考

Clawdbot 是一款开源的本地 AI 助手，旨在让用户通过 Telegram、WhatsApp、Discord 等常用消息应用或网页界面，便捷地与 Claude 等大语言模型进行交互。它主要解决了用户在不同平台间切换繁琐以及担心云端数据隐私的问题，通过将数据存储在本地并支持自定义 API 端点，实现了安全、灵活的 AI 接入体验。

这款工具特别适合希望将 AI 能力融入日常沟通流程的开发者、技术爱好者及注重隐私的普通用户。无论是想在工作群聊中直接调用代码辅助，还是希望通过手机随时与 AI 对话，Clawdbot 都能提供无缝支持。其独特的技术亮点在于强大的适配性：不仅支持多种消息平台的一键配置，还允许用户灵活选择认证方式（如复用 Claude Max 订阅额度），甚至能搭建多模型中转站，同时调度 GPT、Gemini 等不同后端。配合直观的 Web 控制面板和详细的中文部署指南，即使是非资深技术人员也能轻松完成从安装到实战的全流程配置，打造专属的个性化 AI 工作流。

使用场景

某独立开发者希望利用自己的 Claude Max 订阅额度，在 Telegram 上构建一个能随时响应代码审查请求的私人 AI 助手，同时确保所有对话数据留存本地。

没有 clawbot 时

订阅资源浪费：拥有昂贵的 Claude Max 会员资格，却无法在非网页端（如手机即时通讯软件）直接调用，必须频繁切换浏览器标签页。
数据隐私担忧：使用第三方封装的机器人存在聊天记录泄露风险，且无法掌控数据存储位置，敏感代码片段不敢随意发送。
配置门槛极高：若想自建中转服务，需手动处理复杂的 API 鉴权、Node.js 环境依赖及多平台 Bot Token 对接，极易因配置错误而放弃。
多模型管理混乱：若需同时测试不同模型（如对比 Opus 与 Sonnet），缺乏统一的管理面板，每次切换都需修改底层配置文件。

使用 clawbot 后

无缝复用额度：通过简单的 claude setup-token 命令生成凭证，即可让 Telegram 机器人直接复用本地的 Claude Max 订阅，无需额外支付 API 费用。
数据完全自主：所有交互记录默认存储在本地设备，配合开源架构，彻底消除了将核心代码上传至未知服务器的安全顾虑。
一键极速部署：运行 clawdbot onboard 向导，几分钟内自动完成从环境检测、模型认证到 Telegram 配对的全流程，无需编写任何胶水代码。
灵活中控管理：内置 Web 控制面板可实时查看状态，并轻松切换或新增其他模型后端（如 Gemini 或 GPT），实现“一个入口，多模型调度”。

clawbot 将原本繁琐的私有化 AI 部署转化为简单的命令行交互，让开发者能以零成本、高隐私的方式将顶级大模型能力延伸至任意即时通讯场景。

运行环境要求

操作系统

macOS
Linux
Windows

GPU

未说明

内存

未说明

依赖

notes该工具基于 Node.js 运行，非 Python 项目。必需安装 Node.js 22.0.0 或更高版本（推荐使用 nvm 管理）。包管理器推荐使用 pnpm。如需在 macOS 上构建原生应用，需安装 Xcode。支持通过配置文件自定义多种 AI 模型后端（如 Anthropic, OpenAI, Google 等），不支持通过环境变量设置自定义 API 端点，必须修改 JSON 配置文件。

python未说明

Node.js >= 22.0.0

pnpm (推荐) 或 npm

快速开始

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

推荐新的部署教程，从零开始打造你的AI工作助手：最全面的中文教程，涵盖安装、配置、实战案例和避坑指南！

简介

Clawdbot是一个开源的本地AI助手，支持通过消息应用（Telegram、WhatsApp、Discord等）或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：安全确认

◇  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

认证方式对比：

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

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

在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   │
│  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

配置自定义中转站（多模型支持）

方案一：配置多模型中转站（推荐）

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

1. 获取API凭证

从中转服务获取：

API Base URL: https://apipro.maynor1024.live
API Key: sk-xxxxxxxxxxxxx

推荐服务：

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

2. 修改主配置文件

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

步骤1：备份配置文件

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

步骤2：编辑配置文件

nano ~/.clawdbot/clawdbot.json

在配置文件中添加多个 provider：

{
  "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	模型列表，必须包含此字段	✅

步骤3：配置鉴权文件

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

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 验证的中转站：

1. 获取API凭证

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

2. 配置文件（带 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。

完整配置示例：

{
  "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
    }
  }
}

步骤4：验证配置格式

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

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

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界面：

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

预期结果：

状态显示"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：环境变量配置无效

错误做法：

export ANTHROPIC_BASE_URL="https://code.claude-opus.top/api"
export ANTHROPIC_API_KEY="cr_你的API密钥"
export CLAWDBOT_MODELS='{"providers": {"anthropic": {"baseUrl": "https://code.claude-opus.top/api", "apiKey": "cr_你的API密钥", "api": "anthropic-messages", "models": [{"id": "claude-sonnet-4-5", "name": "Claude Sonnet 4.5", "reasoning": false, "input": ["text"], "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0}, "contextWindow": 200000, "maxTokens": 8192}]} }}'

# 在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：中转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
          }
        ]
      }
    }
  }
}

❌ 踩坑6：忘记重启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秒）
没有错误信息

解决方案：

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

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对话
✅ 了解常用命令和故障排除
✅ 避开了所有常见踩坑点

关键要点

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

Clawdbot 快速上手指南

Clawdbot 是一个开源的本地 AI 助手，支持通过 Telegram、Discord 等消息应用或 Web UI 与 AI 模型（如 Claude、GPT-4）交互。它完全开源，数据本地存储，并支持自定义 API 端点。

1. 环境准备

在开始之前，请确保你的系统满足以下要求：

操作系统：macOS / Linux / Windows
Node.js：版本 22.0.0 或更高（必需）
包管理器：推荐使用 pnpm，也可使用 npm

升级 Node.js 版本

Clawdbot 强依赖 Node.js 22+。如果你使用的是 nvm (Node Version Manager)，请执行以下命令：

# 安装并切换到 Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

# 验证版本
node --version  # 应显示 v22.x.x

2. 安装步骤

你可以选择以下任意一种方式进行安装：

方式一：全局安装（推荐）

直接使用 npm 全局安装 CLI 工具：

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
npm link

3. 基本使用

安装完成后，通过初始化向导完成配置即可开始使用。

第一步：运行初始化向导

在终端输入以下命令启动配置流程：

clawdbot onboard

第二步：跟随向导配置

向导将引导你完成以下关键步骤：

安全确认：阅读风险提示并输入 Yes 继续。
选择 AI 后端：
- 推荐选择 Anthropic。
- 认证方式：
  - 若你是 Claude Max/Pro 订阅用户：选择 Anthropic token (paste setup-token)。需在另一终端运行 claude setup-token 获取令牌并粘贴。
  - 若使用 API Key：选择 Anthropic API key 并粘贴密钥。
配置消息通道（可选）：
- 可选择连接 Telegram、WhatsApp 或 Discord。
- 以 Telegram 为例：选择 Telegram (Bot API)，然后填入从 @BotFather 获取的 Bot Token。
完成配置：
- 配置成功后，终端会显示 Web UI 地址（通常为 http://127.0.0.1:18789/）。

第三步：开始对话

方法 A：使用 Web UI（最直观）

打开浏览器访问终端显示的地址（例如：http://127.0.0.1:18789/?token=你的 token）。
进入 Chat 界面。
输入消息（如 Hello），即可直接与 AI 对话。

方法 B：使用 Telegram（需配对）

如果你在向导中配置了 Telegram：

在 Telegram 中向你的 Bot 发送任意消息。
Bot 会回复一个 配对码 (Pairing code) 和你的 User ID。

在终端执行批准命令：

clawdbot pairing approve telegram <配对码>

批准后，即可直接在 Telegram 中与 AI 聊天。

进阶提示：配置国内中转 API

如果需要访问更快的节点或使用多模型（GPT/Claude/Gemini），需手动编辑配置文件，因为环境变量方式无效。

备份并编辑配置文件：

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

在 models.providers 中添加自定义服务商（示例）：

{
  "models": {
    "providers": {
      "my-proxy": {
        "baseUrl": "https://你的中转站域名/v1",
        "api": "openai-completions", 
        "apiKey": "sk-你的密钥",
        "models": [
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

注意：必须包含 models 数组字段，即使为空也不能省略。

重启服务使配置生效：
```
clawdbot gateway restart
```

常见问题

项目是否改名了？现在的项目名称是什么？

配置 Claude 中转时遇到凭证授权错误（invalid_request_error）怎么办？

遇到 "500 No available Claude accounts support the requested model" 错误如何解决？

如何设置 OpenAI 的中转配置？关键字段该怎么填？

是否有推荐的折扣版 Claude 中转服务提供商？

遇到配置问题无法自行解决时，如何联系官方支持？

相似工具推荐

openclaw

OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。 OpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你

★ 349.3k|★★★☆☆|3天前

Agent开发框架图像

stable-diffusion-webui

stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。

★ 162.1k|★★★☆☆|4天前

开发框架图像Agent

everything-claude-code

everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上

★ 146.8k|★★☆☆☆|今天

开发框架Agent语言模型

ComfyUI

ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。

★ 108.1k|★★☆☆☆|昨天

开发框架图像Agent

markitdown

MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器

★ 93.4k|★★☆☆☆|2天前

插件开发框架

LLMs-from-scratch

LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。 LLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备

★ 90.1k|★★★☆☆|3天前

语言模型图像Agent

使用场景

没有 clawbot 时

使用 clawbot 后

运行环境要求

快速开始

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

目录

推荐新的部署教程，从零开始打造你的AI工作助手：最全面的中文教程，涵盖安装、配置、实战案例和避坑指南！

简介

系统要求

必需条件

可选条件

安装步骤

1. 升级Node.js版本

2. 选择安装方式

3. 初始化配置

步骤1：安全确认

步骤2：选择AI后端

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

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

步骤5：完成配置

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

配置自定义中转站（多模型支持）

方案一：配置多模型中转站（推荐）

1. 获取API凭证

2. 修改主配置文件

方案二：配置 Claude Code 中转（需要 User-Agent）

1. 获取API凭证

2. 配置文件（带 User-Agent）

步骤4：验证配置格式

3. 重启Gateway服务

4. 验证配置生效

验证和测试

1. 检查Gateway状态

2. 访问Web UI

3. 发送测试消息

4. 查看日志

常见踩坑点

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

❌ 踩坑2：缺少models字段

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

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

❌ 踩坑5：中转API需要特定User-Agent

❌ 踩坑6：忘记重启Gateway

常见问题FAQ

Q1: Gateway无法连接

Q2: API调用失败

Q3: Assistant不回复消息

Q4: 如何查看详细日志？

Q5: 如何完全重置配置？

常用命令

Gateway管理

配置管理

日志查看

诊断工具

Web UI

TUI（终端界面）

更新

配置文件位置

安全建议

1. 保护API Key

2. Gateway Token

3. 网络安全

4. 数据备份

参考资源

总结

关键要点

快速参考

Clawdbot 快速上手指南

1. 环境准备

升级 Node.js 版本

2. 安装步骤

方式一：全局安装（推荐）

方式二：一键脚本安装

方式三：源码安装

3. 基本使用

第一步：运行初始化向导

第二步：跟随向导配置

第三步：开始对话

方法 A：使用 Web UI（最直观）