文档首页 · English

常见问题与排障

现象	首先检查
模型无回复或鉴权失败	接口地址、API Key、模型名、服务商配额和网络；已有环境变量是否覆盖 .env
修改配置未生效	是否从正确目录启动、是否编辑实际挂载的 .env；修改启动配置后重启进程
宿主访问不到容器 Webhook	ENABLE_WEBHOOK、容器监听地址、端口映射、鉴权头；见部署文档
飞书不响应	应用凭证、事件订阅、长连接和用户绑定；见通道文档
文件工具拒绝访问	FILE_SAFE_DIRS 和容器挂载路径；避免为排障无限扩大白名单
MCP 无工具	执行 /mcp list 和 /mcp tools <id>，核对连接、认证和工具上限
人工确认卡片不工作	card.action.trigger 回调配置；用 /question 重发，或在原入口文字回答/取消
历史图片无法读取	原附件文件是否保留、容器路径是否正确挂载

提交 Issue 时附上操作系统、Python 版本、代码提交/镜像标签、脱敏配置、最小复现步骤及错误日志。

待补充

飞书错误码、模型服务商差异、网络代理和典型故障案例。