ClawBot 使用手册

是一个 Claude Code 的自托管版本（又名 Claw），它是一个功能强大的 AI 助手平台，支持 Claude 等多种 AI 模型。：ClawBot agents 可以执行命令、读写文件，请务必了解其风险后继续使用。文档地址：https://docs.claw.bot/security。• 新增 Claude API 密钥配置支持。- 支持 Claude Code API。- 支持 Tel

还在忙碌的吴小二

1352人浏览 · 2026-02-11 09:16:35

还在忙碌的吴小二 · 2026-02-11 09:16:35 发布

📱 ClawBot 使用手册

🌟 项目简介

ClawBot 是一个 Claude Code 的自托管版本（又名 Claw），它是一个功能强大的 AI 助手平台，支持 Claude 等多种 AI 模型。

主要特性：

• 🤖 Claude 集成 - 支持 Claude Code API
• 💬 Telegram Bot - 支持 Telegram 机器人交互
• 📊 Web UI - 提供现代化的 Web 界面
• 🌐 终端界面 - 支持命令行交互
• 📝 历史记录 - 自动保存对话历史
• 🔧 自托管 - 完全本地部署，数据安全可控

🚀 环境要求

组件	要求	说明
操作系统	macOS / Linux / Windows	跨平台支持
Node.js	≥ 22.0.0	强烈推荐 22.x 版本
包管理器	npm / pnpm / bun	推荐 pbash

检查 Node.js 版本

node --version

推荐：使用 nvm 安装 Node.js 22

nvm install 22
nvm use 22

---

## 📦 安装方式

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

```bash
# 全局安装 ClawBot
npm install -g clawbot

# 启动服务
clawbot

方式二：使用 install.sh 脚本

# 下载并执行安装脚本
curl -fsSL https://claw.bot/install.sh | bash

方式三：从源码编译

#
``` 克隆仓库
git clone https://github.com/clawbot/clawbot.git
cd clawbot

# 安装依赖
npm install

# 构建项目
npm build

# 创建软链接
npm link

⚠️ 安全警告

🔐 重要提示：ClawBot agents 可以执行命令、读写文件，请务必了解其风险后继续使用。

文档地址：https://docs.claw.bot/security

🔧 快速配置

1️⃣ 配置 API 和模型

ClawBot 支持多种认证方式：

认证方式对比：

认证方式	说明	适用场景
`setup-token`	Claude Max/Pro 用户	个人订阅用户
`Claude Code CLI`	Claude Code

# 执行配置命令
claw setup-token

# 按提示操作：
# 1. 粘贴 Anthropic setup-token
# 2. 输入 Token name（留空则使用默认）
# 3. 选择默认模型（推荐：anthropic/claude-sonnet-4-50k）

2️⃣ 配置 Telegram Bot（可选）

前置步骤：

1. 搜索 @bash

启用

claw config set channels.telegram.enabled true
claw config set channels.telegram.token "你的BotToken"

# 重启服务
clawbot gateway restart

🎮 启动服务

启动服务

# 启动 ClawBot
clawbot onboard

查看服务状态

# 检查所有通道状态
clawbot channels status

正常状态示例：

Gateway reachable.
Telegram default: disabled, configured, stopped
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/

💻 使用界面

Web UI 界面

访问地址：http://127.0.0.1:18789/

功能特点：

• 📝 完整的聊天界面
• 📊 历史对话记录
• ⚙️ 参数配置面板
• 🔒 支持 Token 验证访问

带 Token 访问：

http://127.0.0.1:18789/?token=your-token

终端界面

# 启动终端模式
clawbot dashboard

# 快捷键说明：
# Ctrl+C: 退出程序
# Enter: 发送消息
# Shift+Enter: 换行

📁 项目结构

~/.clawbot/
├── clawbot.json          # 主配置文件（重要！）
├── credentials/          # API 凭证配置
├── sessions/             # 对话历史记录
├── logs/
│   ├── gateway.log       # 网关日志
│   └── gateway.err.log   # 错误日志
└── agents/              # 自定义 Agent 配置

🔍 故障排除

问题 1：Web UI 连接失败bash

1. 检查进程

ps aux | grep clawbot-gateway

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

# 3. 验证配置文件
cat ~/.clawbot/clawbot.json | jq '.'

# 4. 重启网关服务
clawbot gateway restart

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

问题 2：API 认证失败

错误信息： TypeError: fetch failed

**解决方案：bash

1. 测试 API 连接

curl -s https://api.claude.com/v1/messages
-H "x-api-key

<code class="language-: 你的API密钥" \"="" style="box-sizing: border-box; border-width: 0px; border-style: solid; border-color: rgb(229, 229, 229); font-family: "Fira Code", Menlo, "Operator Mono", Consolas, Monaco, monospace; font-feature-settings: normal; font-variation-settings: normal; font-size: 14px; display: -webkit-box; padding: 0.5em 1em 1em; overflow-x: auto; text-indent: 0px; text-align: left; line-height: 1.75; margin: 0px; white-space: pre-wrap;">  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-50k","max_tokens":100,"messages":[{"role":"user","content":"hi"}]}'

# 2. 检查配置文件格式
cat ~/.clawbot/clawbot.json | jq '.models.providers.anthropic'

# 3. 确认配置项：
# - baseUrl: 基础 URL
# - apiKey: API 密钥
# - api: 固定值 "anthropic-messages"
# - models: 空数组 []

# 4. 重启服务
clawbot gateway restart

问题 3：Assistant 无响应

解决方案：

# 1. 检查网络连接
curl -I https://api.claude.com

# 2. 验证 Claude Code CLI 配置
clawbot config set channels.telegram.enabled false
clawbot gateway restart

# 3. 查看 Web UI 状态
clawbot dashboard

问题 4：日志显示异常

**查看bash

实时查看网关日志

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

查看错误日志

tail -f ~/.

# 查看指定日期日志
tail -f /tmp/clawbot/clawbot-$(date +%Y-%m-%d).log

📚 常用命令速查表

功能	命令
启动服务	`clawbot onboard`
查看状态	`clawbot channels status`
重启网关	`clawbot gateway restart`
Web UI	`clawbot dashboard`
配置指南	`clawbot doctor --fix`
安全审计	`clawbot security audit --deep`
查看帮助	`clawbot doctor`