xbot

xbot — 自托管 AI Agent，接入你的飞书 / QQ / 终端 / 浏览器

xbot 解决什么问题

你想让 AI 帮团队做事——写代码、查文档、跑命令、操作飞书表格——但又不想把数据交给第三方 SaaS。xbot 让你在自己的服务器上部署一个全功能 AI Agent，通过飞书/QQ/终端/浏览器与它对话，它能调用工具完成实际工作。

核心能力：

• 🧠 多轮对话 + 工具调用（Shell、文件读写、网页搜索、定时任务…）
• 📱 多渠道接入（飞书、QQ、终端 TUI、Web 浏览器）——同一套 Agent，不同入口
• 🔑 团队共享 LLM 订阅（管理员配置一次，所有人直接用）
• 🧩 可扩展（Skills、SubAgents、MCP 协议、Plugin 系统）
• 🖱️ 全功能 TUI（鼠标交互、命令面板、多会话管理、主题系统）
• 🏠 完全自托管，数据不出你的服务器

我该用哪个渠道

💡 飞书场景最常见：部署 server 模式 → 配置飞书应用 → 全团队在飞书群里 @机器人对话，无需各自配置 API Key。

快速开始

1. 安装

安装器会问你选哪种模式（区别见下文）：

# 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

指定安装路径：

INSTALL_PATH=~/.local/bin curl -fsSL ... | bash  # 自定义路径

2. 两种安装模式

安装器会让你选择：

大多数团队应选 Server 模式。 个人开发者想快速体验可选 Standalone。

3. 首次运行 & 配置 LLM

安装完成后直接运行：

xbot-cli

首次运行会自动弹出 Setup 向导，引导你创建 LLM 订阅：

1. 选择 LLM 提供商（OpenAI / Anthropic / 自定义兼容 API）
2. 输入 API Key
3. 配置 API 地址（使用第三方服务时修改，如 DeepSeek、Qwen、Ollama）
4. 选择模型
5. 配置模型层（Vanguard / Balance / Swift，可按不同场景选用不同模型）

也可以随时用 /setup 或 Ctrl+K → Setup 重新配置。

⚠️ 提示：xbot 使用订阅（Subscription）系统管理 LLM 配置，而非全局单一 llm 字段。你可以创建多个订阅（如工作用 Claude、个人用 DeepSeek），在不同会话中随时切换。

4. 配置文件

配置文件位于 ~/.xbot/config.json。首次运行 Setup 向导会自动生成。

Server 模式管理员配置订阅示例：

管理员在 TUI 中通过 /setup 创建订阅后，团队成员即可直接使用，无需各自配置。

Standalone 模式配置示例：

{
  "subscriptions": [
    {
      "name": "default",
      "provider": "openai",
      "api_key": "sk-xxx",
      "base_url": "https://api.openai.com/v1",
      "model": "gpt-4o"
    }
  ]
}

使用 DeepSeek：

{
  "subscriptions": [
    {
      "name": "deepseek",
      "provider": "openai",
      "api_key": "your-deepseek-key",
      "base_url": "https://api.deepseek.com/v1",
      "model": "deepseek-chat"
    }
  ]
}

TUI 功能速览

xbot CLI 提供了强大的终端用户界面：

💡 在 TUI 中输入 / 查看所有可用 slash 命令。

渠道配置

每个渠道通过 ~/.xbot/config.json 启用。

飞书

在 飞书开放平台 创建应用后：

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

最小必需的应用权限：im:message、im:message.receive_v1、im:message:send_as_bot、contact:user.base:readonly

详见 飞书配置指南。

QQ / NapCat / Web

详见各渠道的配置指南：Channels

从源码构建

git clone https://github.com/ai-pivot/xbot.git && cd xbot
make build          # 构建 xbot (server + runner)
make run            # 构建并运行 server

仅构建 CLI：

go build -o xbot-cli ./cmd/xbot-cli

功能概览

内置工具

Agent 在对话中可以调用这些工具：

记忆系统

Skills & SubAgents

• Skills — Markdown 定义的能力包，放在 ~/.xbot/skills/。Agent 按需加载获取专门指导
• SubAgents — 基于角色的子 Agent（explore、code-reviewer 等），自定义角色放 ~/.xbot/agents/
• Group Chat — 多 SubAgent 主持讨论（Meeting Mode），通过 @mentions 触发发言

MCP 协议

支持全局和会话级 MCP Server，stdio 和 HTTP 传输。通过 ManageTools 工具动态管理。

Plugin 系统

GUI 插件扩展系统，支持工具、hooks、上下文增强器的动态加载。

架构

┌──────────┐     ┌──────────────┐     ┌────────────┐     ┌──────────┐
│  飞书    │────▶│  Dispatcher  │────▶│  Backend    │────▶│   LLM    │
│  QQ      │◀────│  (channel/)  │◀────│  (RPC)      │◀────│ (llm/)   │
│  Web     │     └──────────────┘     │             │     └──────────┘
│  CLI     │                          │  Transport  │
└──────────┘                          │  (local/    │────▶ 工具
                                      │   remote)   │      (tools/)
                                      │             │
                                      │  Agent Loop │────▶ 记忆
                                      │  (agent/)   │      (memory/)
                                      └────────────┘

核心设计：

• Backend — 纯 RPC 客户端接口，零业务逻辑，方法均为 1-3 行类型化调用
• Transport — 执行层，localTransport 直接调用 Agent，remoteTransport 通过 WebSocket 转发
• Pipeline — 中间件链组装系统提示（prompt → 全局上下文 → Skills → Agents → Memory → 用户消息）
• 并发 — 全局 LLM 信号量控制、Read 工具并行执行、SubAgent 独立 goroutine

文档

完整文档：cjiw.github.io/xbot

License

MIT