部署与启动
MaiBot 启动失败怎么办？
先查看启动日志中的第一条实际错误。常见原因包括 Python 或依赖版本不符合要求、配置文件不存在或格式错误、模型配置不完整、端口被占用和文件权限不足。
不要在没有确认原因时反复卸载重装。带有明确错误代码时，可在错误排查中继续查询。
配置文件不存在或格式错误怎么办？
优先通过 WebUI 修改配置。必须手动编辑时，确认 TOML 的字符串带引号、数字不带引号、布尔值使用小写 true 或 false，并检查段落名称和数组格式。
配置文件路径和字段说明见配置概览。
端口被占用怎么办？
先根据日志确认被占用的是哪个服务：
- MaiBot WebUI 默认使用
8001。 - MaiBot 的旧版消息 WebSocket 服务默认使用
8000。 - Docker 部署中的 NapCat 管理面板通常映射到
6099。 - NapCat 或 SnowLuma 的正向 WebSocket 常使用
3001，但应以适配器配置为准。
找到占用端口的进程后，可以关闭重复进程，或者同时修改服务端和客户端的端口配置。详细命令见端口占用排查。
WebUI 怎么打开？
本地部署默认访问 http://127.0.0.1:8001。请先确认启动日志已经显示 WebUI 服务启动成功；修改过端口时，应使用修改后的端口。
Docker 部署还需要正确配置端口映射和监听地址，详见Docker 安装。
WebUI 中找不到某个配置项怎么办？
先检查页面是否提供“高级设置”开关，再确认当前 MaiBot 版本和文档对应版本。配置项可能被移动、改名或由其他字段替代；不要因为旧截图中存在某个按钮就直接修改未知配置。