xianyu110/clawbot

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

What is Clawdbot?

Clawdbot is an open‑source, locally‑run AI assistant that lets you chat with large‑language‑model back‑ends (Anthropic Claude, OpenAI GPT, Google Gemini, etc.) through a web dashboard or popular messaging apps such as Telegram, WhatsApp and Discord. All conversation data stays on your machine, and you can point the assistant at any compatible API endpoint – including custom “proxy” services that re‑route requests to the original providers.

Core capabilities

Feature What it means for you
Multi‑platform chat Interact via a browser UI, a terminal UI, or bots on Telegram/WhatsApp/Discord and other 12+ channels.
Pluggable model back‑ends Choose from Claude, GPT‑4o, Gemini 3 Pro, or any other model that speaks the supported OpenAI/Anthropic/Google APIs, simply by adding a provider entry in ~/.clawdbot/clawdbot.json.
Local data storage Conversations, session files and credentials are kept under ~/.clawdbot/, never sent to a third‑party server.
Self‑hosted gateway A lightweight Node.js gateway (clawdbot gateway) runs on localhost:18789, exposing a WebSocket and HTTP UI while keeping the service isolated from the internet.
Customizable security The gateway uses a token for UI access, and the tool includes a clawdbot security audit command to spot risky settings.
CLI/TUI tools Manage configuration, restart services, view logs, and even chat from the terminal with clawdbot tui.

Who might use it?

  • Developers who want a personal AI coding assistant without sending code to the cloud.
  • Teams that need a shared, on‑premise assistant that can be hooked into existing chat tools.
  • Privacy‑conscious users who want full control over API keys and conversation logs.

Quick‑start snapshot (from the README)

  1. Install Node 22+ (via nvm).
  2. Install Clawdbot – npm install -g clawdbot (or use the one‑click script).
  3. Run the onboarding wizard – clawdbot onboard walks you through:
    • Accepting the security disclaimer.
    • Selecting an Anthropic model and providing a setup‑token (Claude Max) or API key.
    • Adding a messaging channel (e.g., Telegram Bot Token).
  4. Launch the gateway – clawdbot gateway restart.
  5. Open the UI – visit http://127.0.0.1:18789/ (add ?token=… if you generated one).
  6. Chat! Send a message in the web UI or via your chosen messenger.

Extending with multiple models (the “proxy” mode)

The README shows a concrete JSON snippet that adds three providers (api‑proxy‑gpt, api‑proxy‑claude, api‑proxy‑google). Each provider defines:

  • baseUrl – the proxy endpoint you pay for.
  • apiKey – the secret for that endpoint.
  • api – which vendor’s request format to use (openai‑completions, anthropic‑messages, google‑generative‑ai).
  • models – an array describing each model (ID, name, context window, token limits, etc.).

After editing ~/.clawdbot/clawdbot.json you must also add matching entries to auth‑profiles.json and then restart the gateway for the changes to take effect.

Common pitfalls & fixes (summarised)

  • Node version too low – Clawdbot requires Node ≥ 22. Use nvm to upgrade.
  • Environment variables ignored – Custom API URLs must be set in the JSON config, not via ANTHROPIC_BASE_URL.
  • Missing models array – The config validator will reject a provider without a models field; add an empty array if you have no models yet.
  • Telegram bot crashes – Disable the channel (clawdbot config set channels.telegram.enabled false) while troubleshooting.
  • User‑Agent required – Some proxy services reject requests unless you add a User-Agent header inside the model definition.
  • Changes not applied – Always run clawdbot gateway restart after editing config files.

Typical commands you’ll use

# Service control
clawdbot gateway restart          # apply config changes
clawdbot channels status          # health check

# Configuration
clawdbot configure                # interactive editor
clawdbot config set gateway.mode local
clawdbot config set channels.telegram.enabled false

# Diagnostics & logs
clawdbot doctor                   # run automated checks
clawdbot doctor --fix            # attempt auto‑fixes
tail -f ~/.clawdbot/logs/gateway.log

# UI shortcuts
clawdbot dashboard                # open browser UI
clawdbot tui                      # terminal chat UI

Where the files live

~/.clawdbot/
├─ clawdbot.json          # main configuration
├─ credentials/           # API keys (not committed to Git)
├─ sessions/              # conversation history
├─ logs/
│  ├─ gateway.log
│  └─ gateway.err.log
└─ agents/main/...        # per‑agent workspace

Security best‑practices (from the guide)

  • Keep API keys out of version control.
  • Rotate keys regularly.
  • Use the gateway token for UI access and change it periodically.
  • Run the gateway bound to localhost unless you explicitly expose it via a VPN/Tailscale.
  • Back up ~/.clawdbot/ (config + sessions) with tar -czf backup‑$(date +%F).tar.gz ~/.clawdbot/.

Bottom line

Clawdbot is a fully‑featured, self‑hosted AI assistant platform that lets you plug in any major LLM provider (Claude, GPT, Gemini) through a unified, locally stored configuration. The README provides step‑by‑step installation, detailed JSON‑based model proxy setup, and a thorough troubleshooting guide, making it a practical tool for developers who want a private, extensible AI chat interface.

Related

  • Project
    crabwise-ai/crabwalk

    Crabwalk is a real‑time web UI that visualises OpenClaw AI agents’ activity across WhatsApp, Telegram, Discord and Slack. It streams events from the OpenClaw gateway via WebSocket, shows a live node‑graph of sessions, lets you inspect tool calls, and supports Docker, CLI, or source‑install deployment.

  • Project
    Spr-Aachen/Easy-Voice-Toolkit

    Easy Voice Toolkit bundles open‑source speech models (Whisper, GPT‑SoVITS) into a GUI/Colab workflow for cleaning audio, transcribing it, building a voice‑conversion dataset, training a custom voice model, and generating converted speech. It offers a ready‑to‑run Windows portable package and a Colab notebook, with a developer‑friendly install guide. The project is academic‑use only and plans future LLM chatbot integration and Linux support.

  • Project
    Aethena-Lab/Z3r0

    Z3r0 is an AI‑native red‑team workbench that combines a React UI, FastAPI control plane, multi‑agent runtime with LightRAG retrieval, and Docker‑sandboxed execution. It records every action as immutable evidence and provides replayable timelines, making authorized penetration testing auditable and collaborative.

  • Project
    Deng-m1/MaliangAINovalWriter

    Maliang AI Novel Writer (AINoval) is an open‑source web platform that lets Chinese web‑novel authors write long‑form fiction with AI assistance. It bundles a Flutter‑Web rich‑text editor, hierarchical content management, AI‑driven outline/scene generation, structured world‑building trees, prompt/preset handling, and a full admin console for user, model, cost and content‑moderation management. The backend is Spring Boot 3 (Java 21) using LangChain4j for LLM orchestration, MongoDB for storage and Chroma for vector embeddings. Deploy with a single Docker‑Compose file, then create an admin account via the provided script. Ideal for solo writers, writing teams, or platform operators who need AI‑augmented novel creation and robust operational tooling.