把大模型 API 接入 QQ、钉钉、Telegram 等社交平台的本地机器人控制台。当前重点支持 QQ 通过 NapCatQQ 与 OneBot v11 接入，再由本项目统一调用大模型并回复消息。
- QQ/OneBot、钉钉、Telegram webhook 入口
- OpenAI-compatible、Anthropic-compatible、OpenAI Responses、Ollama 协议
- 内置常见服务商和中转站预设，也支持自定义 base URL
- 本地 Web 控制台与四步首次设置向导
- 网页保存配置后立即热重载模型客户端
- NapCatQQ 网页安装、启动、停止、重启和 OneBot 自动配置
- 双击启动 Bot、NapCat 和浏览器控制台
- 本地测试对话、连接检查、运行状态和实时日志
- SQLite 会话记忆
- 保留
doctor、test-llm等 CLI 排障命令
需要 Python 3.11 或更高版本。下载项目后，直接双击根目录的：
start.bat
启动器会自动完成：
- 检查并安装 Python 依赖
- 没有
.env时从安全模板创建本地配置 - 启动已经安装的 NapCat
- 启动 Bot 服务
- 在浏览器打开
http://127.0.0.1:8000/
也可以在 PowerShell 中启动：
.\start.ps1如果 PowerShell 阻止脚本执行，使用 start.bat 即可。
首次打开控制台时会显示四步向导：
- 选择模型服务商、中转站或自定义兼容接口，填写模型和 API Key。
- 选择 QQ/OneBot、钉钉、Telegram 中需要的平台。
- 确认 OneBot API 与 NapCat WebUI 地址。
- 保存配置并启动；如果未安装 NapCat，控制台会在后台下载，完成后自动启动。
API Key 只写入本机 .env。管理接口返回配置时只会显示“密钥已设置”，不会把真实 Key 发送回浏览器。管理 API 也只允许从本机访问。
- 总览：Bot、模型、NapCat、QQ 登录状态，当前下一步与本地测试对话
- 模型服务：服务商、接口协议、Base URL、模型、API Key 和生成参数
- 图片与语音：独立启用、模型、Base URL、Key、尺寸、音色、格式和生成测试
- 平台接入：平台开关、QQ 群聊回复策略、OneBot、钉钉、Telegram 与服务监听地址
- NapCat：安装、启动、网页内悬浮扫码登录、OneBot 自动配置、重启与连接测试
- 运行日志：查看模型测试、QQ 消息、OneBot 发送和 NapCat 进程输出
推荐链路：
QQ -> NapCatQQ -> OneBot v11 -> /webhook/onebot -> LLM API -> OneBot 主动回复
控制台会始终显示当前需要执行的一步。完整流程是：
- 在“模型服务”中保存并测试 API。
- 在“NapCat”中点击“安装”或首页“启动全部”。
- NapCat 运行后点击“登录 QQ”，控制台会直接读取 NapCat 保存的
cache/qrcode.png并悬浮显示，无需复制地址或进入 WebUI。 - 登录成功后点击“自动配置”，写入 OneBot HTTP Server 和 Webhook。
- 点击“重启并检查”。显示 QQ 昵称和号码后即可收发消息。
NapCat 默认登录页为：
http://127.0.0.1:6099/webui/
OneBot 默认使用：
API: http://127.0.0.1:5700
Webhook: http://127.0.0.1:8000/webhook/onebot
不要用浏览器直接测试 /webhook/onebot 的消息收发。浏览器发送的是 GET，真正的平台消息由 NapCat 使用 POST 发送。请在首页“测试对话”和 NapCat 页“测试连接”中检查链路。
在控制台“模型服务”页面分别启用“图片生成”和“语音回复”。媒体 API 地址和 Key 留空时，会复用当前文本模型的 Base URL 与 API Key；也可以填写另一家中转站。
中转站需要支持以下 OpenAI-compatible 接口：
POST {IMAGE_API_BASE}/images/generations
POST {TTS_API_BASE}/audio/speech
如果服务商文档中的接口地址包含 /v1，Base URL 也要填写到 /v1，例如 https://example.com/v1。
QQ 聊天指令：
/image 一座漂浮在云端的中国古城
/voice 用三句话介绍杭州西湖
帮我生成一张在窗台晒太阳的橘猫图片
给我画一只穿宇航服的布偶猫
/image直接调用图片模型，生成后以 OneBotimage消息段发送。/voice先让文本模型回答，再调用语音合成，以 OneBotrecord消息段发送。- QQ 群聊默认只有在明确
@机器人时才会回复；可在“平台接入”中改为回复全部或关闭群聊回复。 - 图片 API 遇到临时 TLS 断线或服务端 5xx 时会携带同一幂等标识重试一次，图片下载会自动重试三次。
- 生成文件保存在本机
media/generated/，最多保留最近 100 个，并已被.gitignore排除。 - Telegram 发送媒体需要配置可访问的
PUBLIC_BASE_URL；QQ 与本机 NapCat 可以直接使用本地文件，不需要公网地址。 - 钉钉当前会回复文字和公网媒体链接；如需原生图片卡片，需要再接钉钉媒体上传接口。
图片和语音调用可能单独计费，因此功能默认关闭，只识别明确的媒体指令。
网页不能启动时，可以使用以下命令排障：
python -m pip install -r requirements.txt
python -m app.cli dashboard传统 CLI 向导仍然保留：
python -m app.cli init
python -m app.cli init --force常用诊断命令：
python -m app.cli providers
python -m app.cli doctor
python -m app.cli test-llm
python -m app.cli install-qq
python -m app.cli qq-login
python -m app.cli configure-napcat
python -m app.cli run网页配置最终保存在 .env，不要提交到 GitHub。公开仓库只提交 .env.example。一般不需要手动编辑该文件。
关键字段：
LLM_PROTOCOL=openai-compatible
LLM_API_KEY=
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-v4-flash
IMAGE_GENERATION_ENABLED=false
IMAGE_API_BASE=
IMAGE_API_KEY=
IMAGE_MODEL=gpt-image-1
IMAGE_SIZE=1024x1024
TTS_ENABLED=false
TTS_API_BASE=
TTS_API_KEY=
TTS_MODEL=gpt-4o-mini-tts
TTS_VOICE=alloy
TTS_RESPONSE_FORMAT=mp3
ONEBOT_API_BASE=http://127.0.0.1:5700
ONEBOT_ACCESS_TOKEN=
QQ_LOGIN_COMMAND=
NAPCAT_WEBUI_URL=http://127.0.0.1:6099/webui/大多数中转站使用：
LLM_PROTOCOL=openai-compatible
LLM_BASE_URL=https://你的中转站域名/v1如果中转站明确支持 OpenAI Responses API，才使用：
LLM_PROTOCOL=openai-responses
LLM_BASE_URL=https://你的中转站域名说明项目已经有本地配置文件。继续配置直接运行：
python -m app.cli init完全重置配置：
python -m app.cli init --force默认输入是可见的，直接粘贴或输入 key 后按 Enter。留空也可以继续，但 doctor 会提示 LLM_API_KEY is empty。
这是正常现象。webhook 是给 NapCat/qbot POST 消息用的，不是给浏览器手动测试聊天用的。
说明还没有安装或配置 QQ 接入层。先运行：
python -m app.cli install-qq
python -m app.cli init如果已经安装过 NapCatQQ，也可以直接：
python -m app.cli qq-login这是因为 NapCat 的启动命令在错误目录下运行。当前 CLI 会自动把工作目录切到 vendor/napcat，不要手动在项目根目录执行 node.exe ./index.js。
分两段排查：
python -m app.cli test-llm如果这里失败，问题在大模型配置或中转站。
如果这里成功，再看 python -m app.cli run 的日志中是否出现：
OneBot active send ok
出现这行说明 QQ 主动发送成功。
这通常不是 QQ 问题，也不像模型名错误，而是中转站域名前面的防护层拒绝了 API 请求。常见原因：
- Cloudflare/WAF/Bot Fight Mode 拦截了非浏览器 API 请求
- API 路径没有放行，例如
/v1/* - base URL 填成了网页登录地址，不是 API 地址
- 中转站只支持 Chat Completions，但配置成了 Responses API
建议先改成最通用配置测试：
LLM_PROTOCOL=openai-compatible
LLM_BASE_URL=https://你的中转站域名/v1
LLM_REASONING_EFFORT=然后运行：
python -m app.cli test-llm成功后再启动机器人。
确认这些文件不要提交：
.envbot.sqlite3vendor/*.log__pycache__/.pytest_cache/
项目已经在 .gitignore 中忽略这些内容。提交前可以运行：
git status --short确保没有 .env、数据库、NapCat 登录缓存或日志出现在待提交列表里。
如果 API key 曾经出现在终端截图、聊天记录或 Git 历史中，建议在服务商后台重新生成 key。
python -m pytestQQ 接入层建议使用成熟开源项目，不建议自己从零实现协议。生产使用时请注意平台规则、账号风控、用户隐私、内容安全、管理员白名单、群聊开关和审计日志。