常见问题
首次配置的链接在本机浏览器打不开
终端输出的首次配置地址绑定在 127.0.0.1 随机端口上，仅限运行 LenBot 的那台机器访问。若 LenBot 部署在远程服务器上，先在个人电脑终端建立 SSH 端口转发（将端口号替换为终端实际输出的端口），再在个人电脑浏览器打开原链接：
ssh -L 52811:127.0.0.1:52811 你的服务器测试 OneBot 连接时读取不到 Bot 账号
按以下顺序逐项核对：
- OneBot 客户端（如 NapCat）已完成 QQ 登录，且对应的 WebSocket 服务已启用。
- 正向 WebSocket 模式下，地址以
ws://或wss://开头；OneBot 运行在容器中时需将端口发布到宿主机，LenBot 运行在容器中连接宿主机 OneBot 时使用ws://host.docker.internal:<端口>。 - 反向 WebSocket 模式下，OneBot 客户端需选用 Universal 模式，目标地址和端口与 LenBot 的监听配置一致。
- 两侧填写的访问令牌完全一致。
按钮下方会直接展示握手失败的具体原因，详细网络拓扑见接入 QQ。
向导保存后页面停在配置已保存
该提示说明 lenbot.config.json 已成功写入磁盘，但浏览器在等待时间内未连上正式面板端口（默认 8088）：
- 通过 SSH 转发访问远程服务器时，向导随机端口已关闭，需新建转发
8088端口的 SSH 隧道后访问http://127.0.0.1:8088。 - 本机直连未响应时，检查终端输出是否提示
8088端口被其他程序占用；若是端口冲突，先停止进程，修改lenbot.config.json中的panel.port后重新运行len-bot即可。
Bot 在群内不说话
按从外到内的顺序检查六项状态：
- 连接与群开关：在总览确认状态显示 Bot 在线，且目标群右侧的开关处于开启状态。
- 聊天模式：在总览查看该群的方形按钮；插件表示只响应插件和命令，点击切换为聊天后模型参与对话。
- 参与方式：在群聊 → 设置 → 参与方式中确认选的是同时参与群内讨论；选只在被
@、回复或私聊时的群，Bot 不主动接话。 - 安静状态与发言上限：查看群工作台顶栏是否标有安静中或已达发言上限（也可在总览待处理事项中查看并点击本小时临时放开）。
- 每日 token 上限：在模型 → 用量与上限中确认今日消耗未触发全局或单群额度封顶。
- 回合决策或报错：打开群聊 → 现场，确认消息旁是月亮（未达唤醒门槛）还是闪电（已唤醒但模型判断无需接话记为旁听，或卡片标红报错）。
模型调用报错
报错提示首句会直接标明处置方向，常见状态码（401、404、429、5xx、输出或上下文超限）的对应设置见模型调用失败排查。在总览点开合并错误项或在群聊 → 现场展开失败步骤可查看上游返回的原始报文与 request id。
读取网页或拉取图片提示私有或保留地址
本机代理软件开启了 fake-ip 模式，将公网域名解析到了 198.18.0.0/15 等保留地址段。前往能力 → 网页，在代理的 fake-ip 网段中填入代理使用的虚拟网段并配置公网 DNS JSON 查询地址后保存重启，详见代理软件的 fake-ip 模式。
启动或执行维护命令提示实例锁被占用
同一实例目录的 .lenbot-instance.lock 在同一时刻只允许运行一个 len-bot 进程或一条写操作维护命令。请先停止正在运行的实例；若此前在终端误按 Ctrl+Z 将进程挂起在后台，执行 fg 切回前台后再按 Ctrl+C 正常退出，锁会自动释放。
启动提示配置或数据库格式版本不匹配
在首个候选发布版（RC）定稿前，开发分支若调整了内部表结构且未附带迁移步骤，旧开发实例文件无法直接打开。请使用新目录重新初始化（或按 CONTRIBUTING.md 手动调整本地开发库），原目录保留作数据参考。
登录面板提示尝试过于频繁
同一客户端 IP 在 15 分钟内连续输错 5 次密码后触发临时锁定，15 分钟后自动解除。若面板部署在远程反向代理之后，所有访客流量可能被识别为同一个代理服务器 IP；停止 LenBot 后将该代理服务器的 IP 填入 lenbot.config.json 的 panel.trusted_proxies，即可按转发头中的真实访客 IP 独立计数。
平台、语音与用量相关
- 支持哪些聊天平台：当前仅支持通过 OneBot v11 接入 QQ。
- 能否发送语音消息：配置语音转写后可把群友发送的语音识别为文字，Bot 自身不生成语音回复。
- 在哪里核对 token 消耗：在模型 → 用量与上限中可按今天或本月、按具体模型或按群与用途查看精确到每次调用的输入、输出及缓存命中 token 统计。