开源 · MIT License Python 3.10+ Docker Ready

不只是聊天接口，
是角色型智能体
基础设施

NekoBot 采用「统一 AI 内核 + 频道适配层」架构，内置角色运行时、记忆系统、 工具调用、工作区与可视化 Web 管理后台——一套可持续运行、可配置、 可观测、可扩展的多频道 AI 角色扮演系统。

$ git clone https://github.com/asukaneko/nekobot.git
nekobot · web console — :5000
NekoBot Web 管理后台 — AI 配置中心
NekoBot 吉祥物
CHANNELS ONLINE
QQ · Web · CLI · TG · 飞书
5+
频道接入
QQ / Web / CLI / Telegram / 飞书
13
MCP Tools
状态 · 链路 · 队列 · 节点
6
六维关系模型
亲密 / 信任 / 依赖 / 好感…
MIT
开源协议
自由使用 · 欢迎贡献
QQ (NapCatQQ)Web ConsoleCLI 终端Telegram飞书 FeishuAndroid 客户端MCP (Claude Code)MCP (Cursor)ChatGPT AgentQQ (NapCatQQ)Web ConsoleCLI 终端Telegram飞书 FeishuAndroid 客户端MCP (Claude Code)MCP (Cursor)ChatGPT Agent
01Core Capabilities

一个内核，装下角色的全部

不是把消息转发给模型那么简单。NekoBot 把角色扮演所需的运行时、记忆、工具与运维能力收进同一条流水线。

5 个频道适配器

多渠道接入

QQ、Web、CLI、Telegram、飞书共用统一的 ChatRequest / ChatResponse 处理链路，一次部署，处处在线。

Affective Runtime

角色运行时

实时情感引擎、六维关系模型、动态 PromptStack，把角色设定转化为持续一致的对话行为。

Dashboard

Web 控制台

会话、角色卡、模型、工作流、知识库、记忆、日志与调试——日常运维全部可视化。

Workspace

工具与工作区

工具调用、文件读写、共享 / 私有工作区、文件变更预览与任务执行，对话中直接动手。

Cross-Provider

模型适配

兼容 OpenAI Chat Completions / Responses、Anthropic、Gemini 接口，可接入 Deepseek、GLM、Kimi、MiMo 等。

Extensible

插件与技能

通过插件与技能系统扩展能力，而不破坏核心处理流程。

MCP Server

MCP 接口

以标准 MCP 协议暴露 Gateway 能力，Claude Code、Cursor、ChatGPT Agent 可直接调用。

TTS / STT

语音能力

可插拔 TTS / STT 适配器：OpenAI 兼容、小米 MiMo、豆包，以及 faster-whisper 本地离线识别。

02Character Runtime

角色不是一段 Prompt，是一套运行时

nbot/character/ 把「角色设定」转译为持续一致的对话行为：情绪有惯性，关系会生长，记忆被隔离。

Ppriority-aware

PromptStack

动态提示词栈

按优先级动态拼装提示词，而不是把所有状态污染进历史消息，角色设定始终稳定可控。

Sinertia-safe

StateMachine

状态机

控制情绪惯性与关系平滑变化，避免单轮输入导致角色剧烈失真。

Aself-tuning

AutoState

自动状态评估

定期总结近期互动，自动调整情绪强度、精力与六维关系值。

Mlong / short term

Memory

角色记忆

按角色、按用户隔离的长期与短期记忆，跨会话记得你是谁。

Rper-turn plan

ReactionPlan

反应策略

每轮回复前生成风格与行为策略，约束角色输出的语气与行动。

6relation model

六维关系模型

随互动平滑生长
亲密
信任
依赖
好感
默契
敬畏
03Architecture

统一 AI 内核，频道只是适配层

请求流经过预处理、对话、后处理三段管线，角色运行时在每轮前后挂载——任何一个频道，得到的都是同一个「她」。

REQUEST FLOW
Channel Adapter01
ChatRequest02
AI Pipeline03
Character Runtime04
Model Adapter05
ChatResponse06
before_turn() → chat → after_turn() · 钩子全程挂载
01
core/ 不依赖频道层

统一 AI 流水线只面向 ChatRequest / ChatResponse，与具体平台解耦。

02
BaseChannelAdapter

所有新频道都通过适配器接入，而不是直接调用模型。

03
before / after turn

角色逻辑通过钩子挂入流水线，情感与记忆随每轮对话更新。

PROJECT TREE
bot.py
└── nbot/
    ├── core/        # 统一 AI 流水线
    ├── character/   # 情感运行时与关系模型
    ├── channels/    # QQ / Web / TG / 飞书适配
    ├── services/    # AI 客户端、工具、TTS/STT
    ├── plugins/     # 插件与技能系统
    ├── gateway/     # 消息总线 · 路由 · 去重
    ├── mcp/         # MCP Server（AI Agent 接口）
    └── web/         # Flask 蓝图 · Socket.IO · 后台
04Model Context Protocol

让 AI Agent 直接操纵 Gateway

内置 MCP Server，把消息、事件、队列、节点等能力以标准协议暴露出去——Claude Code、Cursor、ChatGPT Agent 即刻接入。

mcp — zsh
$ ▋
.mcp.json — Claude Code
{
  "mcpServers": {
    "nekobot": {
      "command": "python",
      "args": ["bot.py", "--mcp-only"],
      "env": { "PYTHONPATH": "." }
    }
  }
}
AVAILABLE TOOLS13 tools · 3 resources · 3 prompts
gateway_get_status只读
gateway_get_stats只读
gateway_query_trace只读
gateway_query_events只读
gateway_get_queue_stats只读
gateway_list_nodes只读
gateway_receive_message操作
gateway_submit_internal_task操作
gateway_send_message高危
gateway_retry_dead_letter高危

高危能力默认关闭，支持审计日志与确认机制；传输支持 stdio 本地与 streamable-http 远程两种模式。

05Quick Start

三分钟，让她上线

只需要 Python 3.10+ 与一个 OpenAI 兼容的 API。没有 QQ 配置时，项目可以仅以 Web 模式运行。

# 克隆并安装
git clone https://github.com/asukaneko/nekobot.git
cd nekobot
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# 配置环境变量（至少填写 Web 密码）
cp .env.example .env
# WEB_PASSWORD=your_web_password
# API_KEY / BASE_URL / MODEL —— 或在 Web 界面配置

# 启动（自动检测 QQ 配置）
python bot.py                # QQ + Web
python bot.py --only-web     # 仅 Web，默认 :5000
python bot.py --cli          # 仅 CLI
01
打开 Web 控制台

访问 :5000，用 WEB_PASSWORD 登录，可视化配置你的第一个模型。

02
创建角色卡

在「人格设置」中创建、编辑或导入角色卡，设定语气与边界。

03
接入频道

部署 NapCatQQ 或配置 Telegram / 飞书，让角色在你所在的平台上线。