NekoBot 多频道AI角色扮演平台

Requirements

• Python 3.10+
• NapCatQQ
• ncatbot 3.8.5
• 可用的 OpenAI-compatible API 服务

说明：

• .env 是首选配置来源。
• config.ini 仍作为 QQ 连接参数的兼容回退。
• 项目默认使用 Flask + Flask-SocketIO + Eventlet 提供 Web 服务。

Installation

git clone https://github.com/asukaneko/nekobot.git
cd nekobot

```bash #配置虚拟环境（可选） python -m venv venv source venv/bin/activate

Docker 快速部署

官方镜像发布在 GitHub Container Registry (ghcr.io)，支持 linux/amd64 与 linux/arm64：

```bash

快速开始

```bash

拉取并运行

docker run -d --name nekobot --restart unless-stopped \ -p 5000:5000 \ -v "$(pwd)/data:/app/data" \ -v "$(pwd)/.env:/app/.env:ro" \ --env-file .env \ ghcr.io/asukaneko/nekobot:latest ```

启动后访问 http://<服务器IP>:5000。

提示 - 必须挂载 data/ 卷以持久化会话 / 角色卡 / Web 配置 - NapCatQQ 需独立部署，通过 WS_URI 连接（详见 Docker Compose 示例） - 生产环境建议使用精确版本号（如 :3.1.2）而非 latest，便于回滚

完整部署说明（Compose、升级、与 NapCatQQ 协同、HTTPS 等）见 Docker 部署指南。

启动 Bot + MCP

python bot.py --mcp ```

服务端：config.ini 设置 transport = streamable-http，然后启动

python bot.py --mcp-only

windows: venv\Scripts\activate.bat

python -m pip install -r requirements.txt

复制环境变量模板并填写必要配置：

至少建议先配置：

如需启用 QQ Bot，还需要补充：

AI 服务的最小示例：

但你仍然可以通过web界面来配置你的模型

准备配置

mkdir -p nekobot/data && cd nekobot cp .env.example .env # 编辑 .env，至少填 WEB_PASSWORD

Claude Code 配置

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "nekobot": {
      "command": "python",
      "args": ["bot.py", "--mcp-only"],
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

提示：bot.py 是相对路径，会从当前工作目录查找。如果 Claude Code 不在项目根目录启动，需要通过 cwd 指定项目路径，或将 args 改为绝对路径。

Cursor 配置

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "nekobot": {
      "command": "python",
      "args": ["bot.py", "--mcp-only"],
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

MCP 配置项

在 config.ini 中配置 MCP 行为：

[mcp]
; 是否允许 MCP 发送真实消息（高危，默认关闭）
send_message_enabled = false
; 重试死信是否需要确认
retry_require_confirmation = true
; 审计日志
audit_enabled = true
; 授予 MCP 全部权限（本地使用建议开启）
admin = true
; 传输模式: stdio (本地) | streamable-http (远程)
transport = stdio
; 服务端配置（streamable-http 模式）
host = 127.0.0.1
port = 5001
; 远程连接 URL（--mcp-connect 使用）
connect_url = http://127.0.0.1:5001/mcp

[gateway]
; Gateway 持久化存储（启用后可查询历史事件）
storage_enabled = true
data_dir = data/web

CLI only

python bot.py --cli

CLI + Web

python bot.py --cli-and-web