xianyu110/clawbot

什么是 Clawdbot？

Clawdbot 是一个开源、本地运行的 AI 助手，可通过 Web 仪表板或 Telegram、WhatsApp、Discord 等流行消息应用，与大型语言模型后端（Anthropic Claude、OpenAI GPT、Google Gemini 等）进行聊天。所有对话数据都保留在您的机器上，您可以将助手指向任何兼容的 API 端点——包括自定义的“代理”服务，这些服务会将请求重定向到原始提供商。

核心功能

功能	对您意味着什么
多平台聊天	可通过浏览器 UI、终端 UI，或 Telegram/WhatsApp/Discord 等 12+ 个渠道的机器人进行交互。
可插拔模型后端	仅需在 `~/.clawdbot/clawdbot.json` 中添加提供者条目，即可从 Claude、GPT‑4o、Gemini 3 Pro 或任何支持 OpenAI/Anthropic/Google API 的模型中选择。
本地数据存储	对话、会话文件和凭据均保存在 `~/.clawdbot/` 下，从不发送到第三方服务器。
自托管网关	一个轻量级 Node.js 网关（`clawdbot gateway`）在 `localhost:18789` 上运行，暴露 WebSocket 和 HTTP UI，同时将服务与互联网隔离。
可自定义安全	网关使用令牌进行 UI 访问，工具包含 `clawdbot security audit` 命令以发现高风险设置。
CLI/TUI 工具	可管理配置、重启服务、查看日志，甚至通过 `clawdbot tui` 从终端聊天。

谁会使用它？

希望拥有个人 AI 编码助手但不想将代码发送到云端的 开发者。
需要一个可集成到现有聊天工具中的共享、本地部署助手的团队。
希望完全控制 API 密钥和对话日志的 注重隐私的用户。

快速入门快照（来自 README）

安装 Node 22+（通过 nvm）。
安装 Clawdbot – npm install -g clawdbot（或使用一键脚本）。
运行引导向导 – clawdbot onboard 会引导您完成：
- 接受安全免责声明。
- 选择 Anthropic 模型并提供 setup‑token（Claude Max）或 API 密钥。
- 添加一个消息渠道（例如，Telegram Bot Token）。
启动网关 – clawdbot gateway restart。
打开 UI – 访问 http://127.0.0.1:18789/（如果生成了令牌，请添加 ?token=…）。
开始聊天！ 在 Web UI 或所选消息应用中发送消息。

通过多个模型扩展（“代理”模式）

README 提供了一个具体的 JSON 片段，用于添加三个提供者（api‑proxy‑gpt、api‑proxy‑claude、api‑proxy‑google）。每个提供者定义：

baseUrl – 您付费的代理端点。
apiKey – 该端点的密钥。
api – 使用哪个供应商的请求格式（openai‑completions、anthropic‑messages、google‑generative‑ai）。
models – 描述每个模型的数组（ID、名称、上下文窗口、令牌限制等）。

编辑 ~/.clawdbot/clawdbot.json 后，还必须在 auth‑profiles.json 中添加对应条目，然后 重启网关 才能使更改生效。

常见陷阱与修复（摘要）

Node 版本过低 – Clawdbot 要求 Node ≥ 22。使用 nvm 升级。
环境变量被忽略 – 自定义 API URL 必须在 JSON 配置中设置，而不是通过 ANTHROPIC_BASE_URL。
缺少 models 数组 – 配置验证器会拒绝没有 models 字段的提供者；如果尚无模型，请添加空数组。
Telegram 机器人崩溃 – 排查时禁用该渠道（clawdbot config set channels.telegram.enabled false）。
需要 User-Agent – 某些代理服务会拒绝没有在模型定义中添加 User-Agent 头的请求。
更改未生效 – 编辑配置文件后，务必运行 clawdbot gateway restart。

你将使用的典型命令

# 服务控制
clawdbot gateway restart          # 应用配置更改
clawdbot channels status          # 健康检查

# 配置
clawdbot configure                # 交互式编辑器
clawdbot config set gateway.mode local
clawdbot config set channels.telegram.enabled false

# 诊断与日志
clawdbot doctor                   # 运行自动检查
clawdbot doctor --fix            # 尝试自动修复
tail -f ~/.clawdbot/logs/gateway.log

# UI 快捷方式
clawdbot dashboard                # 打开浏览器 UI
clawdbot tui                      # 终端聊天 UI

文件存放位置

~/.clawdbot/
├─ clawdbot.json          # 主配置
├─ credentials/           # API 密钥（不提交到 Git）
├─ sessions/              # 对话历史
├─ logs/
│  ├─ gateway.log
│  └─ gateway.err.log
└─ agents/main/...        # 每个代理的工作区

安全最佳实践（来自指南）

将 API 密钥保留在版本控制之外。
定期轮换密钥。
使用网关令牌访问 UI 并定期更改。
除非通过 VPN/Tailscale 明确暴露，否则将网关绑定到 localhost 运行。
使用 tar -czf backup‑$(date +%F).tar.gz ~/.clawdbot/ 备份 ~/.clawdbot/（配置 + 会话）。

总结

Clawdbot 是一个功能齐全的自托管 AI 助手平台，可通过统一的本地存储配置连接任何主要 LLM 提供商（Claude、GPT、Gemini）。README 提供了分步安装、基于 JSON 的详细模型代理设置以及全面的故障排除指南，是希望拥有私有、可扩展 AI 聊天界面的开发者的实用工具。