Repository navigation
FAQ
| 症状 | 相关章节 |
|---|---|
| 收不到消息 / 连接不上 / 协议配置 | 连接与协议 |
| AI 提示未配置 Provider / 多 Provider | AI 能力 |
| 插件开发 / 安装 / 定时任务 | 插件开发与安装 |
| 备份 / 导出 / 自动停用 / 告警 | 数据与备份 |
| 登录锁定 / Cron / 文件锁 / 公网部署 | 排查与运维 |
| 命令速查 / 主题快捷键 / 账户管理 | 其他 |
默认接入 OneBot（NapCat 反向 WebSocket）。NapCat 或 LLOneBot 以反向 WebSocket 方式连接本框架：
- 在 NapCat 中新建 WebSocket 客户端，地址填
ws://127.0.0.1:8080/onebot/v11/ws。 - 若设置了
access_token，NapCat 与「连接中心」对应连接里的 Access Token 必须一致。 - 保存后在「连接中心」查看状态是否为「已连接」。
正向模式（本框架主动连接 NapCat 的 WS 地址）可在「连接中心」将模式切换为 forward_ws 并填写 host/port。
Chronocat 项目已停止更新，Red 协议仅作兼容保留；新版 Chronocat 仅支持 Satori 协议。
- 在「连接中心」新增连接：协议
red、模式forward_ws，填写host/port/token。 - 保存后连接即时生效，确认状态为「已连接」。
可以。transport.connections 支持多连接并存，每个连接独立启停与状态；出站消息默认走第一个已连接适配器，也可在「监听环境」页为每个群/私聊绑定指定账号（账号绑定只影响出站，入站事件来自实际收到消息的连接）。
「监听环境」页（侧边栏 → 管理 → 监听环境）展示功能三态开关矩阵：每行是一个群或私聊环境，每列是插件功能，可分别设为「开启 / 关闭 / 跟随默认」。支持批量操作（某功能在所有群一键开/关/恢复默认）。关闭后：命令被拦截（默认友好提示，可设为静默）、定时任务与监听器跳过、/help 不展示该功能。
按顺序检查：
- 「连接中心」适配器状态是否为「已连接」；未连接时检查协议配置与端口占用。
- 群消息是否被群白名单拦截：系统插件
/whitelist list查看，需要时/whitelist add <群号>。 - 消息是否以命令前缀开头（默认
/或!），config.yaml的basic.command_start可调整。 - 机器人账号是否在目标群内，且未被禁言。
AI 服务未配置或未启用。前往「AI 能力」页选择 Provider（OpenAI 兼容 / Anthropic / Gemini / Ollama 等），填写 API Key 与模型名后保存。Ollama 本地模型无需 Key。未配置时 AI 类命令会返回友好提示，不会影响其他功能。
可以。多 Provider 支持按优先级切换与失败降级；某个 Provider 不可用时框架会尝试下一个可用 Provider。
推荐两种方式：
- Web 后台「插件」页的「新建插件」：输入插件名并选择示例模板，自动生成可运行包。
- 命令行脚手架：
ofbot2 plugin new my_plugin，可加--with-task/--with-listener/--with-web/--with-model附带对应示例。
插件目录结构：
plugins/my_plugin/
plugin.json # 元信息、权限、配置 Schema、依赖、features（命令/任务/监听声明）
__init__.py # create_plugin() 入口
handlers.py # 命令/任务/监听处理器（由 plugin.json 引用）
命令、定时任务与监听器推荐在 plugin.json 的 features 中声明（全声明式），加载时自动注册并校验；字段参考见 Plugin-Manifest。开发前可用 ofbot2 plugin check my_plugin 静态校验。
插件在 features[].tasks 中声明的任务会自动登记到「定时任务」页的「插件任务」区：参数只读，支持启停（即时生效并持久化）；执行前按任务目标所在群的功能开关门控。修改参数需改 plugin.json 后重载插件。
使用 ofbot2 plugin install <zip> 安装。任意 zip 属于代码执行，安装前请确认来源可信；官方示例仅用于参考，不会自动覆盖同名插件。
插件入口接收 PluginContext，通过 ctx.commands、ctx.db、ctx.scheduler、ctx.ai、ctx.records、ctx.state_machine、ctx.aggregation、ctx.workflow 等访问能力，完整示例见 Plugin-Development 与仓库内 docs/DEVELOPMENT.md。
- 「数据备份」页点击「立即备份」或启用自动备份（可设间隔小时）。
- 恢复时系统自动创建回退点，恢复后可在备份列表回到恢复前状态。
- 恢复完成后需重启服务生效；若文件被占用会提示"已暂存待手动替换"。
- 记录中心、审计日志、任务历史、Webhook 历史、命令统计均支持导出。
- 小数据量走同步下载；审计等大数据量建议用「后台导出全部」，任务在「导出中心」执行完成后下载。
这是自愈保护：配置了连续失败阈值（scheduler.auto_disable_after_failures / web.auto_disable_workflows_after_failures）后，连续失败达到阈值会自动停用并触发 task.auto_disabled / workflow.auto_disabled 告警。在任务页 / 流程页点击「重新启用」或启用任务即可恢复，建议先排查失败原因。
「执行历史」页（侧边栏 → 自动化 → 执行历史）合并展示定时任务与流程运行，支持来源 / 结果 / 日期筛选、导出 CSV 与失败一键重试；自动停用的实体带「自动停用」标识。
设置全局去抖 web.alert_min_interval_seconds（同一规则同一事件在间隔内只通知一次），或为单条规则单独设置「通知去抖间隔」覆盖全局；告警历史仍会完整记录。
登录失败会触发延迟与锁定（默认 5 次失败锁定 5 分钟）。等待自动解锁，或检查 security.max_login_attempts / security.login_lock_seconds 配置。
表达式必须为标准的 5 段 cron（分 时 日 月 周），例如 0 8 * * *。可在「定时任务」页使用 Cron 预设快速生成，非法表达式会被拒绝并提示。
Windows 下常见于服务仍在运行。先停止服务（关闭 main.py 进程）再操作数据库文件；测试环境偶发文件锁可通过重启进程解决。
在「导出中心」查看任务消息，可点击「重试」。常见原因：格式依赖缺失（如 Excel 需要 openpyxl）、磁盘空间不足、数据量超出单次上限（审计后台导出上限 50000 条）。
框架默认面向本地/私域使用。公网部署务必：启用 HTTPS（反向代理）、修改默认 admin/admin 密码、为 REST API 配置 web.api_keys（未配置时 /api/v1/* 要求后台管理员登录会话）、为 Webhook 接收配置 web.webhook_secret（未配置时 /webhook/{name} 不校验）、为每个连接配置 access_token（反向 WS/HTTP 事件入口会校验 Authorization: Bearer）、按需关闭 8080 公网暴露。完整清单见 Security。
Web 后台「命令速查」页列出全部命令（名称、别名、说明、权限、冷却、限流），支持搜索与复制；机器人内可使用 /help 查看内置帮助。
侧边栏「主题」按钮或按 T 切换暗色/亮色（按钮会显示当前主题）；/ 聚焦当前页搜索框；Esc 关闭弹窗或清除搜索。
框架面向本地/私域部署，已移除 QQ 用户管理页面（数据仍保留用于统计）。Web 后台账户（增删、权限级别）统一在「账户」页管理，仅管理员可见；修改自身密码也在同一页面。
- Troubleshooting — 按症状排查
- Connections — 连接配置
- Glossary — 术语表