跳到主要内容

安装与启动

CountBot 是一个 Python 3.11+ 应用，支持源码运行和桌面模式。后端基于 FastAPI，前端基于 Vue 3 + Vite。

环境要求​

运行 CountBot​

  • Python 3.11+
  • Windows、macOS 或 Linux
  • 能访问你准备接入的模型服务

构建前端或文档（可选）​

  • Node.js 18+
  • 需要构建前端时才使用（Release 包已包含构建产物）

方式一：源码运行​

1. 获取代码​

git clone https://github.com/countbot-ai/countbot.git
cd countbot

2. 安装依赖​

pip install -r requirements.txt

如果你在国内环境中安装较慢，可以改用镜像：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

requirements.txt 包含的依赖分类：

类别依赖说明
Web 框架fastapi, uvicorn, websocketsFastAPI 服务、ASGI 服务器、WebSocket
数据层sqlalchemy, aiosqlite, pydanticORM、异步 SQLite、数据验证
LLM SDKanthropic, openaiOpenAI、Anthropic SDK
渠道 SDKqq-botpy, dingtalk-stream, lark-oapi, python-telegram-botQQ、钉钉、飞书、Telegram
工具beautifulsoup4, python-frontmatter, PyYAML网页解析、Markdown 解析、YAML
可选scrapling, camoufox, jieba网页抓取增强、中文分词（默认注释）
MCPmcpMCP 协议支持

3. 启动服务​

python start_app.py

启动后会打印以下信息：

  • Local: http://127.0.0.1:8000 — 本机访问地址
  • Network: http://<局域网IP>:8000 — 局域网其他设备访问地址
  • Setup URL（首次运行时）: 远程初始化地址，用于无法本地访问的场景

启动 15 秒后会自动打开默认浏览器访问 Local 地址。

如果你需要从其他设备访问，设置环境变量：

# PowerShell
$env:COUNTBOT_HOST = '0.0.0.0'
$env:COUNTBOT_PORT = '9000'
python start_app.py
# Bash
export COUNTBOT_HOST=0.0.0.0
export COUNTBOT_PORT=9000
python start_app.py

启动流程​

start_app.py 的启动流程：

1. 初始化 loguru 日志系统
2. 从环境变量读取 COUNTBOT_HOST（默认 127.0.0.1）和 COUNTBOT_PORT（默认 8000）
3. 打印 Local 和 Network 访问地址
4. 启动后台线程，15 秒后调用 webbrowser.open() 打开 Local 地址
5. 启动 uvicorn.run()，传入 backend.app:app 和 lifespan

backend/app.py 的 lifespan 初始化流程：

1. 初始化 SQLite 数据库（data/countbot.db）
2. 从数据库加载配置到内存
3. 创建 ProviderRegistry，注册 22 个 LLM provider
4. 创建 MemoryStore、SkillsLoader、ToolRegistry、SubAgentManager、AgentLoop
5. 初始化消息队列和速率限制器
6. 初始化 ChannelManager
7. 后台启动已启用的渠道连接
8. 启动消息处理器
9. 初始化 CronScheduler，加载定时任务并启动调度
10. 启动心跳问候任务（每 24 小时问候最近活跃的渠道用户）
11. 注册定时清理临时文件的后台任务

开发模式​

如果需要热重载：

uvicorn backend.app:app --reload --host 0.0.0.0 --port 8000

构建前端（可选）​

Release 包已包含构建好的前端产物（frontend/dist/），通常不需要手动构建。

如果你修改了前端代码或拿到的是纯源码：

cd frontend
npm install
npm run build
cd ..

构建产物会输出到 frontend/dist/，后端会自动提供该目录下的静态文件。

方式二：桌面模式​

python start_desktop.py

桌面模式使用 pywebview 打开一个原生窗口，后端在同一进程启动。窗口关闭时自动退出服务。

桌面模式适合：

  • 不想手动配置 Python 环境
  • 主要在本机使用图形界面
  • 想快速验证聊天、团队、渠道和编程工具配置

桌面模式仍然会启动同一套后端服务，只是前端运行在原生窗口中而非浏览器中。

::: warning 桌面版远程访问限制 桌面预编译版（如 .exe 安装包）不支持修改监听地址，无法开启远程访问模式。

如需远程访问，请使用源码版本。 :::

桌面模式依赖​

Windows 需要安装 WebView2 Runtime（Windows 10/11 通常已内置）。

Linux 需要安装 libwebkit2gtk-4.0：

# Ubuntu/Debian
sudo apt install libwebkit2gtk-4.0-dev

方式三：Docker（可选）​

如果你使用 Docker：

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "start_app.py"]
docker build -t countbot .
docker run -d -p 8000:8000 -v ./data:/app/data -v ./workspace:/app/workspace countbot

首次进入后的建议顺序​

1. 配置模型​

在设置页完成：

  • 默认提供商（provider）
  • API Key
  • 默认模型
  • 温度（temperature）、最大输出（max_tokens）等运行参数

可以通过 POST /api/settings/test-connection 测试连接是否成功。

2. 确认工作空间​

工作空间路径（默认 workspace/）会承载：

  • 技能目录（skills/）
  • 记忆文件（memory/）
  • 临时文件与截图（temp/）
  • 运行中的业务产物
  • 外部编程工具配置文件（external_coding_tools.json）

修改工作空间路径后需要重启应用。

3. 设置人格与默认行为​

建议先补齐：

  • AI 名称（ai_name）
  • 用户称呼（user_name）
  • 输出语言
  • 默认人格（personality）

4. 再配置团队、渠道和编程工具​

推荐顺序：

  1. 先把默认模型和工作空间配稳定
  2. 再配置团队和角色
  3. 再接入渠道账号
  4. 最后决定是否给某些渠道账号接入外部编程工具

启动后自检清单​

  • Web 页面能正常打开
  • 设置页能读取并保存模型配置
  • 聊天页能完成一次基础问答
  • 工作空间路径可读可写
  • 如需外部渠道，渠道测试接口可以通过
  • 日志输出正常，无 ERROR 级别错误

目录结构​

countbot/
── backend/                  # 后端代码
│   ├── app.py               # FastAPI 应用和 lifespan
│   ├── api/                 # API 路由
│   ├── database.py          # 数据库配置
│   ├── middleware/          # 中间件（认证、远程访问）
│   ├── modules/             # 核心模块
│   │   ├── agent/           # Agent Loop、Memory、Skills
│   │   ├── channels/        # 渠道管理
│   │   ├── config/          # 配置管理
│   │   ├── cron/            # 定时任务
│   │   ├── external_agents/ # 外部编码工具
│   │   ├── providers/       # LLM Provider
│   │   ├── queue/           # 消息队列
│   │   ├── session/         # 会话管理
│   │   ├── tasks/           # 后台任务
│   │   └── tools/           # 工具集
│   └── ws/                  # WebSocket
├── frontend/                 # 前端代码
│   └── dist/                # 构建产物（Release 包包含）
├── data/                     # 运行时数据
│   └── countbot.db          # SQLite 数据库
├── workspace/                # 工作空间
│   ├── skills/              # 技能目录
│   ├── memory/              # 记忆文件
│   └── temp/                # 临时文件
├── start_app.py              # 启动脚本（浏览器模式）
├── start_desktop.py          # 启动脚本（桌面模式）
└── requirements.txt          # Python 依赖

下一步​