Xbot

What is xbot?

xbot is a self-hosted AI agent framework. Deploy it once on your own server, then talk to it through Feishu, QQ, the terminal, or a web browser. It uses tools — Shell, file I/O, web search, scheduled tasks, sub-agents — to get real work done, and your data never leaves your server.

💡 Different from terminal-only agents (Codex / Claude Code / OpenCode): xbot connects to every channel your team uses. Configure it once, and your whole team reaches the same agent through Feishu group chats, QQ, a web UI, or the terminal — with shared LLM credentials.

Quick Start

1. Install

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/ai-pivot/xbot/master/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ai-pivot/xbot/master/scripts/install.ps1 | iex

curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/ai-pivot/xbot/master/scripts/install-cn.sh | bash

The script auto-detects a working CDN mirror and proxies all GitHub downloads. You can also set GH_MIRROR=ghfast.top manually.

The installer lets you choose a mode:

Most teams should choose Server mode.

2. Configure your LLM

Run xbot-cli. The first launch opens a Setup wizard:

1. Choose a provider (OpenAI / Anthropic / OpenAI-compatible)
2. Enter your API key
3. Set the base URL (change for DeepSeek, Qwen, Ollama, etc.)
4. Pick a model
5. Configure model tiers (Vanguard / Balance / Swift)

xbot uses a subscription system — create multiple (e.g. work Claude, personal DeepSeek) and switch per session. Re-run the wizard anytime with /setup or Ctrl+K → Setup.

TUI at a glance

Type / in the TUI to see all slash commands.

Channel configuration

Each channel is enabled in ~/.xbot/config.json.

Feishu

Create an app on the Feishu Open Platform, then:

{
  "feishu": {
    "enabled": true,
    "app_id": "cli_xxx",
    "app_secret": "xxx"
  }
}

Required permissions: im:message, im:message.receive_v1, im:message:send_as_bot, contact:user.base:readonly

See the Feishu guide.

QQ / NapCat / Web

See the Channels documentation.

Built-in tools

The agent can call these tools in conversation:

Extensibility

• Skills — Markdown capability packs in ~/.xbot/skills/
• SubAgents — Role-based child agents (explore, code-reviewer, …); custom roles in ~/.xbot/agents/
• Group Chat — Multi-agent moderated discussion (Meeting Mode)
• MCP — Global and session-level MCP servers (stdio + HTTP)
• Plugins — Tools, hooks, widgets, channel plugins

Build from source

git clone https://github.com/ai-pivot/xbot.git && cd xbot
make build          # build xbot (server + runner)
go build -o xbot-cli ./cmd/xbot-cli   # build CLI only

Requires Go 1.26+.

Architecture

┌──────────┐     ┌──────────────┐     ┌────────────┐     ┌──────────┐
│  Feishu  │────▶│  Dispatcher  │────▶│  Backend    │────▶│   LLM    │
│  QQ      │◀────│  (channel/)  │◀────│  (RPC)      │◀────│ (llm/)   │
│  Web     │     └──────────────┘     │             │     └──────────┘
│  CLI     │                          │  Transport  │
└──────────┘                          │  (local/    │────▶ Tools
                                      │   remote)   │      (tools/)
                                      │  Agent Loop │────▶ Memory
                                      │  (agent/)   │      (memory/)
                                      └────────────┘

Backend is a pure RPC client (zero business logic); Transport is the execution layer. Read the full Architecture overview.

Documentation

Full docs: ai-pivot.github.io/xbot

License

MIT