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 聊天介面的開發者的實用工具。