适配器登录与使用指南
约 772 字大约 3 分钟
2026-03-19
各内置适配器的认证、配置与使用流程 — 从零开始接入每个平台。
适配器一览
| 适配器 | 平台 | 认证方式 | 协议 | 适用场景 |
|---|---|---|---|---|
| NapCat | WebUI 扫码 / 快速登录 | OneBot v11 (WebSocket) | QQ 群聊/私聊 Bot | |
| SnowLuma | WebUI 手动启用 OneBot v11 + 扫码登录 | OneBot v11 (WebSocket) | 独立协议端 / 外部 OneBot 服务 | |
| Bilibili | Bilibili | 终端扫码 | bilibili-api-python | 直播弹幕 / 私信 / 视频评论 |
| GitHub | GitHub | Personal Access Token | Webhook / REST Polling | Issue/PR/Push 事件处理 |
| Lark | 飞书 | App ID + App Secret | lark-oapi SDK (WebSocket) | 飞书群聊/私聊 Bot |
| AI | 多平台 LLM | API Key / 环境变量 | litellm (REST) | Chat / Embeddings / 图像与视频生成 |
| Mock | 测试 | 无需认证 | 内存模拟 | 插件集成测试 |
配置入口
推荐使用 CLI 管理适配器：
ncatbot adapter # 进入副屏交互式管理（启用/禁用/配置一站式完成）副屏中 ↑/↓ 移动光标，空格切换启用/禁用，Enter 进入配置流程，q 保存退出。
ncatbot init 的适配器配置也使用相同的副屏交互界面。部分适配器含智能跳过逻辑：
- NapCat：选择自动安装时跳过 WS/WebUI 地址输入（启动时自动配置）
- SnowLuma：选择自动安装时跳过 WS/WebUI 地址输入，返回默认连接参数；首次启动仍需在 WebUI 手动启用 OneBot v11 端点
- Bilibili：选择扫码登录时跳过 sessdata 等凭据手动输入（扫码自动获取）
完整 CLI 命令说明见 CLI 命令详解。
也可以直接编辑 config.yaml 的 adapters 列表：
adapters:
- type: napcat # 适配器名称
platform: qq # 平台标识
enabled: true
config: # 适配器专属配置
ws_uri: ws://localhost:3001
ws_token: napcat_ws多个适配器可同时运行：
adapters:
- type: napcat
platform: qq
enabled: true
config:
ws_uri: ws://localhost:3001
- type: bilibili
platform: bilibili
enabled: true
config:
live_rooms: [12345]
- type: github
platform: github
enabled: true
config:
token: "ghp_xxxx"
repos: ["owner/repo"]
- type: ai
platform: ai
enabled: true
config:
completion_model: "gpt-4"同一
BotClient内platform必须唯一，因此napcat与snowluma不能同时启用。
本目录索引
| 文档 | 说明 | 难度 |
|---|---|---|
| 1_napcat_qq.md | NapCat/QQ — Setup/Connect 两种模式、WebUI 登录、诊断 | ⭐ |
| 7_snowluma_qq.md | SnowLuma/QQ — 独立 OneBot v11 协议端、WebUI 手动启用、诊断 | ⭐ |
| 2_bilibili.md | Bilibili — 扫码登录、凭据持久化、多数据源配置 | ⭐ |
| 3_github.md | GitHub — Token 认证、Webhook/Polling 双模式、内网穿透 | ⭐⭐ |
| 6_lark.md | Lark — 飞书企业应用创建、WebSocket 长连接、群聊/私聊 | ⭐ |
| 5_ai.md | AI — litellm 统一接口、多提供商、Chat/Embeddings/ImageGen | ⭐ |
| AI 视频生成 | 视频任务提交、进度查询与内容下载 | ⭐⭐ |
| 4_mock.md | Mock — 测试用内存适配器 | ⭐ |
交叉引用
- 跨平台编程模式（Trait / Platform Filter）→ multi_platform/
- 适配器接口参考（BaseAdapter / AdapterRegistry）→ reference/adapter/
- 消息发送（按平台）→ send_message/
- Bot API（按平台）→ api_usage/
版权所有
版权归属：GEYUANwuqi