MaiBot 文档中心

简体中文

English

简体中文

English

Appearance

🔧 错误排查 FAQ ​

⚠️ 网络是 80% 问题的根源 — API 连不上、Git 拉不下来、插件装不了，大概率都是网络问题。 遇到任何报错，先检查能不能访问外网（curl -I https://www.baidu.com），不行就换网络/开代理。

按错误出现的频率从高到低排列，新手请优先查看 🔴 极高频章节。 如果不确定问题属于哪一类，先看文末的「📋 错误排查流程图」。

🔴 极高频错误（新手必遇） ​

覆盖场景 1–6，新手部署和首次使用 MaiBot 时最容易遇到的问题。

场景 1：配置文件找不到或格式不对 ​

错误现象 ​

  • 启动 MaiBot 时立即崩溃
  • 终端打印 TOML 解析错误，如 Invalid TOML syntax
  • 或提示 FileNotFoundError: config/bot_config.toml
  • 或提示 API密钥不能为空，请在配置中设置有效的API密钥。
  • 或提示 API基础URL不能为空

快速自查三连 ​

1️⃣ 配置文件存在吗？看看 config/ 文件夹里有没有 bot_config.toml 2️⃣ TOML 语法对吗？字符串加引号、数字不引号、布尔值小写 3️⃣ 用 WebUI 改过吗？WebUI 会自动验证语法，不会出错

解决方案 ​

方法一（推荐）：用 WebUI 修改配置 WebUI 会自动创建和验证配置，不需要手写 TOML，不会出错：

  1. 启动 MaiBot，打开浏览器访问 http://localhost:8001
  2. 进入「配置管理」页面
  3. 按页面提示填写内容，保存即可

如果 MaiBot 因配置错误无法启动，可以先修好关键错误让程序跑起来，再通过 WebUI 调整配置。

方法二：手动复制示例文件 如果暂时用不了 WebUI，可以复制示例文件作为起点：

bash
cp config/bot_config.example.toml config/bot_config.toml
cp config/model_config.example.toml config/model_config.toml

方法三：检查 TOML 语法（手改文件时参考）

toml
# ✅ 正确示例
[bot]
nickname = "麦麦"           # 字符串要引号
port = 8001                 # 数字不要引号
enabled = true              # 布尔值小写

# ❌ 错误示例
[bot]
nickname = 麦麦             # 错误！没引号
port = "8001"              # 错误！数字不该引号
enabled = True             # 错误！应该小写 true

方法四：在线验证 如果手动改了文件不确定格式对不对，可以用 TOML 在线验证器 检查。

预防建议 ​

  • 📝 用 WebUI 改配置 — WebUI 会自动验证语法，不会出错
  • 💾 修改前备份 — cp bot_config.toml bot_config.toml.bak
  • 🔍 小步修改 — 每次只改几行，保存后测试能否启动

场景 2：API Key 错误/余额不足 ​

错误现象 ​

  • 机器人完全无回复
  • 后端日志出现 401 Unauthorized / 402 Payment Required / 403 Forbidden
  • 日志提示 API key is invalid 或 Insufficient balance

快速自查三连 ​

1️⃣ API Key 填对了吗？检查 model_config.toml 中 api_key 字段 2️⃣ 账户余额够吗？登录 API 提供商后台查看余额 3️⃣ 模型名对吗？检查 model_identifier 是否在提供商支持列表内

解决方案 ​

步骤 1：检查 API Key 配置

toml
# model_config.toml
[[api_providers]]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
api_key = "sk-your-api-key-here"    # 必填！替换为你的真实 Key
auth_type = "bearer"

步骤 2：验证 Key 是否有效

bash
# 测试 DeepSeek API
curl https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key-here"

步骤 3：检查余额

  • 登录 DeepSeek/OpenAI 等提供商后台
  • 查看账户余额是否大于 0
  • 检查 API Key 是否过期或被禁用

步骤 4：确认模型名

toml
# ✅ 正确示例
[[models]]
model_identifier = "deepseek-chat"   # 必须是 API 商支持的模型名
name = "deepseek-chat"
api_provider = "DeepSeek"

# ❌ 错误示例
[[models]]
model_identifier = "gpt-4"           # DeepSeek 不支持 GPT-4！
api_provider = "DeepSeek"

预防建议 ​

  • 🔑 Key 不要提交到 Git — 用环境变量或本地配置文件
  • 💰 设置余额提醒 — 在 API 后台设置低余额邮件通知
  • 📊 监控用量 — 定期检查 Token 消耗情况

场景 3：端口被占用 ​

错误现象 ​

  • 启动时报 OSError: [Errno 98] Address already in use
  • 或 [Errno 10048]（Windows）
  • 错误日志：端口 8001 已被占用 (host=127.0.0.1)

快速自查三连 ​

1️⃣ 哪个进程占用了端口？打开任务管理器/活动监视器找找 2️⃣ 能关掉占用进程吗？在任务管理器里结束占用进程 3️⃣ 能改 MaiBot 端口吗？编辑配置文件换其他端口

解决方案 ​

方法一：结束占用进程 在任务管理器（Windows）或活动监视器（macOS）中找到占用端口的进程并结束它。如果不知道哪个进程占用了，直接重启电脑也可以释放端口。

方法二：修改 MaiBot 端口

toml
# config/bot_config.toml

# WebUI 端口（默认 8001）
[webui]
port = 8002             # 改为 8002 或其他空闲端口

# WebSocket 端口（默认 8000）
[maim_message]
ws_server_port = 8001   # 改为 8001 或其他空闲端口

方法三：换个端口启动 启动时换个端口也很简单，改完配置文件重新启动 MaiBot 就行。建议用 8002、9000 这类不太常用的端口。`

预防建议 ​

  • 📝 记录端口分配 — 避免多个服务用同一端口
  • 🔄 重启后检查 — 有时旧进程未清理，重启后需手动结束
  • 🔧 使用非标准端口 — 如 8001 改为 18001，降低冲突概率

场景 4：WebUI 页面打不开 ​

错误现象 ​

  • 浏览器访问 http://localhost:8001 显示「无法访问此网站」或「连接被拒绝」
  • 页面白屏或加载超时
  • MaiBot 已启动但 WebUI 就是打不开

快速自查三连 ​

1️⃣ MaiBot 真的启动成功了吗？看终端有没有报错 2️⃣ 浏览器输入的地址对吗？默认是 http://localhost:8001 3️⃣ 防火墙有没有拦？Windows 防火墙/杀毒软件可能会阻止

解决方案 ​

步骤 1：确认 MaiBot 已启动 看运行 MaiBot 的终端窗口，有没有看到类似这样的日志：

WebUI 服务器 启动成功: http://127.0.0.1:8001

如果没看到，说明 MaiBot 还没完全启动，先解决启动报错。

步骤 2：检查地址和端口

  • 默认地址：http://127.0.0.1:8001（推荐用 127.0.0.1 而不是 localhost）
  • 如果改了端口，用你改的端口访问
  • 如果部署在远程服务器，把 127.0.0.1 换成服务器 IP

步骤 3：检查防火墙

  • Windows：打开「Windows 安全中心」→「防火墙和网络保护」→「允许应用通过防火墙」，确保 Python 被允许
  • macOS：系统设置 → 网络 → 防火墙，检查是否阻止了 Python
  • Linux：检查 iptables 或 ufw 规则

步骤 4：检查端口是否被占用 如果端口被其他程序占了，WebUI 也启动不了。参考场景 3 检查端口占用。

预防建议 ​

  • 🖥️ 启动后看日志 — 看到「WebUI 服务器 启动成功」再打开浏览器
  • 🔧 固定用 127.0.0.1 — 比 localhost 更稳定，避免 DNS 解析问题
  • 🛡️ 提前关防火墙 — 如果确定安全，可以暂时关防火墙测试

场景 5：MCP 配置错误 ​

错误现象 ​

  • 启动时报 MCP 服务器 {name} 使用 stdio 时必须填写 command
  • 或 MCP 服务器 {name} 使用 streamable_http 时必须填写 url
  • 或日志提示 MCP server xxx failed to connect

快速自查三连 ​

1️⃣ 服务器地址对吗？检查 mcp.servers[].url 或 command 字段 2️⃣ Token/Secret 匹配吗？确认 bearer_token 与 MCP 服务端一致 3️⃣ MCP 服务运行了吗？确认服务端已启动并可访问

解决方案 ​

步骤 1：检查 MCP 配置

toml
# config/bot_config.toml

[mcp]
enable = true

# STDIO 类型（本地进程通信）
[[mcp.servers]]
name = "local-filesystem"
enabled = true
transport = "stdio"
command = "node"                          # 必填！启动命令
args = ["/path/to/mcp-server/index.js"]   # 命令参数

# HTTP 类型（远程服务）
[[mcp.servers]]
name = "remote-search"
enabled = true
transport = "streamable_http"
url = "https://mcp-search.example.com/sse"    # 必填！HTTP 端点

[mcp.servers.authorization]
mode = "bearer"
bearer_token = "your-bearer-token-here"       # 必填！认证 Token

步骤 2：验证 MCP 服务可访问

bash
# 测试 HTTP 类型 MCP
curl -v https://mcp-search.example.com/sse \
  -H "Authorization: Bearer your-bearer-token-here"

# 测试 STDIO 类型 MCP
node /path/to/mcp-server/index.js
# 应该能看到 MCP 服务启动日志

步骤 3：检查常见错误

toml
# ❌ 错误示例 1：stdio 模式缺少 command
[[mcp.servers]]
transport = "stdio"
command = ""              # 错误！必须填写启动命令

# ❌ 错误示例 2：HTTP 模式缺少 url
[[mcp.servers]]
transport = "streamable_http"
url = ""                  # 错误！必须填写 HTTP 端点

# ❌ 错误示例 3：Bearer 认证未填 Token
[mcp.servers.authorization]
mode = "bearer"
bearer_token = ""         # 错误！必须填写 Token

预防建议 ​

  • 📋 逐项核对配置 — 参考 MCP 服务端文档确认参数
  • 🔍 先测试后上线 — 用 curl 测试连通性再配置到 MaiBot
  • 📝 记录 Token 变更 — Token 更新后同步更新 MaiBot 配置

场景 6：机器人不回复消息 ​

错误现象 ​

  • 消息已发送到平台（QQ 群/私聊）
  • 机器人无任何响应
  • 日志无报错，但就是没回复

快速自查三连 ​

1️⃣ 看后端终端输出，有没有收到消息的提示？ 2️⃣ 匹配到规则了吗？检查关键词/意图规则是否覆盖该消息 3️⃣ LLM 配置对吗？确认 API Key 和模型配置正确（参考场景 2）

解决方案 ​

步骤 1：看终端输出 重启 MaiBot 后观察终端日志，看有没有：

  • 收到消息：...（说明消息到了 MaiBot）
  • 正在调用 LLM...（说明在请求 AI）
  • 发送回复：...（说明回复发出去了） 如果这些都有，说明 MaiBot 本身没问题，可能是平台权限或网络问题。

步骤 2：检查回复规则

toml
# 检查关键词规则
[[keyword_reaction.keyword_rules]]
keywords = ["你好", "hello"]    # 确保包含你发送的消息
reaction = "你好呀！"
enabled = true                  # 确保规则启用

步骤 3：检查频率限制

toml
# config/bot_config.toml
[chat]
# 检查是否设置了过严的频率限制
reply_frequency_limit = 10      # 每 10 秒最多回复 1 次

步骤 4：检查平台权限

  • QQ 群：机器人是否被禁言？是否有发言权限？
  • 私聊：是否被拉黑？
  • 适配器：NapCat 是否正常连接？

步骤 5：测试 LLM 响应

bash
# 手动测试 API
curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'
# 应该能收到 API 返回的回复

预防建议 ​

  • 📊 监控日志 — 定期查看日志，发现异常及时处理
  • 🧪 测试新规则 — 添加新规则后先测试是否生效
  • 📝 记录配置变更 — 修改回复规则后记录变更内容

🟡 高频错误（常见） ​

覆盖场景 7–11，正常使用过程中较常遇到的问题。

场景 7：插件加载失败 ​

错误现象 ​

  • 启动时报 PluginLoadError，插件列表里对应插件灰色不可用
  • 日志显示 ImportError、ModuleNotFoundError 或 ManifestValidationError
  • 插件目录存在但没有任何插件被加载

快速自查三连 ​

1️⃣ 先试试重新安装插件，换个最新版本 2️⃣ 看看日志里提示缺少什么依赖 3️⃣ 确认 Python 版本 ≥ 3.10 且插件和 MaiBot 版本兼容

解决方案 ​

步骤 1：换个版本试试 重新下载插件，选一个和 MaiBot 版本兼容的版本。优先用官方插件或社区热门插件，兼容性更好。

步骤 2：安装缺少的依赖 看日志里有没有类似 No module named 'xxx' 的错误。如果有，说明插件缺少依赖，在插件目录下运行：

bash
cd plugins/你的插件目录
uv sync

步骤 3：看完整的错误日志 启动 MaiBot 时注意看终端的完整错误信息，找到类似这样的提示：

No module named 'requests'

根据提示缺什么装什么。

预防建议 ​

  • 安装插件前先看说明，确认兼容的 MaiBot 版本
  • 优先用官方插件或社区热门插件
  • 定期更新插件和 MaiBot 到最新版本

场景 8：数据库错误 ​

错误现象 ​

  • 运行时报 DatabaseError 或 OperationalError
  • 启动时提示数据库迁移失败
  • 日志显示 database is locked 或 disk I/O error

快速自查三连 ​

1️⃣ 检查是否同时启动多个 MaiBot 实例连接同一数据库 2️⃣ 查看磁盘空间是否已满（打开文件管理器看看） 3️⃣ 确认 data/maibot.db 文件权限是否正确（可读写）

解决方案 ​

步骤 1：解决数据库锁定

如果日志显示 database is locked，说明可能有多个 MaiBot 实例同时访问同一个数据库文件。关掉多余的 MaiBot 进程，只保留一个就行。

如果关掉后还是锁定，可以尝试把 data/maibot.db 文件删掉重来（注意先备份）。

步骤 2：修复损坏的数据库

如果怀疑数据库损坏（如突然断电后）：

  1. 先备份：复制 data/maibot.db 到安全位置
  2. 重启 MaiBot，程序会自动重建或修复数据库
  3. 如果还不行，删掉 data/maibot.db 让程序重新创建（之前的重要数据需要从备份恢复）

步骤 3：启用 WAL 模式（减少锁定冲突）

toml
[database]
# 启用 WAL 模式，减少多进程锁定冲突
journal_mode = "wal"

步骤 4：清理磁盘空间

打开 logs/ 文件夹，删除不需要的旧日志文件。如果磁盘空间严重不足，也检查一下其他目录的大文件。

预防建议 ​

  • 避免同时启动多个 MaiBot 实例连接同一数据库文件
  • 定期备份 data/maibot.db（建议每周一次）
  • 配置日志轮转，避免日志文件占满磁盘
  • 使用 WAL 模式减少锁定冲突

场景 9：网络超时/连接失败 ​

错误现象 ​

  • LLM 请求长时间无响应后报 APIConnectionError 或 TimeoutError
  • 日志显示 Connection refused、Connection reset 或 Read timed out
  • 机器人完全无回复，但本地功能正常

快速自查三连 ​

1️⃣ 测试网络通不通（curl -v https://api.deepseek.com） 2️⃣ 换个网络试试（比如切换手机热点） 3️⃣ 确认 timeout 参数不是太小（建议 60-120 秒）

解决方案 ​

步骤 1：测试网络连通性

bash
# 测试 API 端点是否可达
curl -v https://api.deepseek.com

如果能连上（返回 HTTP 200 或 401 都算连通），说明网络没问题。 如果超时或连不上，说明你的网络到 API 服务商的线路不通，换个网络试试。

步骤 2：增大超时时间

如果网络不太好，把超时设长一点：

toml
[[api_providers]]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
api_key = "sk-your-api-key-here"
timeout = 120              # 单次请求超时（秒），网络差时可设到 180
max_retry = 3              # 失败重试次数
retry_interval = 8         # 重试间隔（秒）

步骤 3：换一个 API 提供商试试

如果 DeepSeek 不稳定，可以在配置中加一个备用 API：

toml
[[api_providers]]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
api_key = "sk-key-1"

[[api_providers]]
name = "备用"
base_url = "https://api.openai.com/v1"  # 换成其他 API
api_key = "sk-your-backup-key"

预防建议 ​

  • 设置合理的 timeout（60-120 秒）和 max_retry（2-3 次）
  • 网络不稳定时换个网络试试（如切换手机热点）
  • 配置多个 API 提供商做备份，避免单点故障
  • 定期检查 API 服务商状态（关注官方公告）

场景 10：表情包系统错误 ​

错误现象 ​

  • 发送表情命令无反应
  • 表情生成失败，日志中有 VLMError 或 FilterError
  • 表情注册失败，提示数量超限

快速自查三连 ​

1️⃣ 确认 emoji.vlm_api_key 已配置（如使用 VLM 验证） 2️⃣ 检查 emoji.filter 规则是否过于严格 3️⃣ 确保 data/emojis/ 目录可写（权限正确）

解决方案 ​

步骤 1：检查 VLM 配置

如果使用 VLM 进行表情验证，确保配置了 API Key：

toml
[emoji]
# VLM API Key（如使用视觉模型验证表情）
vlm_api_key = "sk-your-vlm-key"

步骤 2：调整表情过滤规则

如果表情被过滤规则误杀：

toml
[emoji]
content_filtration = false   # 暂时关闭过滤，排查是否为规则问题

步骤 3：检查目录权限

确保 data/emojis/ 目录可写。如果权限不对，在文件管理器里右键设置读写权限。

步骤 4：调整表情数量限制

如果提示注册数量超限：

toml
[emoji]
emoji_send_num = 25          # 单次发送候选数（1-64）
max_reg_num = 64             # 最大注册表情包数量
do_replace = true            # 满额后替换旧表情

预防建议 ​

  • 首次使用时临时关闭 VLM 验证，排查是否为模型问题
  • 谨慎开启 content_filtration，避免误杀正常表情
  • 定期清理 data/emojis/ 目录，删除不用的表情
  • 设置合理的 max_reg_num，避免占用过多存储空间

场景 11：知识图谱/记忆系统错误 ​

错误现象 ​

  • 机器人回答"我不记得"或"未找到相关信息"
  • 日志提示知识文件加载失败
  • 记忆添加后无法检索到

快速自查三连 ​

1️⃣ 运行 maibot knowledge rebuild 重建知识索引 2️⃣ 检查 data/knowledge/ 目录下文件是否完整 3️⃣ 确认 knowledge.enabled 为 true

解决方案 ​

步骤 1：重建知识索引

bash
# 使用 CLI 命令重建索引
maibot knowledge rebuild

# 或在 WebUI 中点击"重建索引"按钮

步骤 2：检查知识文件

bash
# 查看知识目录
ls -la data/knowledge/

# 确认文件格式正确（JSON 或 TXT）
# 损坏的文件会导致加载失败

步骤 3：启用知识系统

在配置文件中确认知识系统已启用：

toml
[knowledge]
enabled = true

步骤 4：限制单条知识长度

如果知识太长超出 embedding 模型 Token 限制：

toml
[knowledge]
# 单条知识最大长度（Token 数）
max_chunk_size = 512
# 知识块重叠大小（避免上下文断裂）
chunk_overlap = 50

步骤 5：检查向量数据库

如果索引损坏，删除 data/vector_index/ 目录下的内容，然后重建：

bash
maibot knowledge rebuild

预防建议 ​

  • 添加知识时控制单条长度，避免超出 embedding 模型 Token 限制
  • 定期重建知识索引，确保索引与知识文件同步
  • 备份 data/knowledge/ 和 data/vector_index/ 目录
  • 使用 WebUI 的知识管理功能，避免手动编辑知识文件

🟢 中频错误（特定场景） ​

覆盖场景 12–17，在特定操作或配置场景下才会遇到的问题。

场景 12：WebUI 登录失败 / Token 过期 ​

错误现象 ​

  • 打开 WebUI 页面后自动跳回登录页
  • 输入密码登录后提示「登录失败」或「密码错误」
  • API 请求返回 401 Unauthorized 错误
  • 浏览器控制台显示 Token expired 或 Invalid session

快速自查三连 ​

1️⃣ 清除浏览器缓存 — Cookie/LocalStorage 可能已过期或损坏 2️⃣ 检查密码是否正确 — 确认大小写、特殊字符输入无误 3️⃣ 查看 WebUI 服务状态 — 确认服务正在运行且未重启过

解决方案 ​

方法一：清除 Cookie 重新登录

bash
# 浏览器操作：
# 1. 按 F12 打开开发者工具
# 2. 进入 Application → Cookies
# 3. 删除所有 MaiBot 相关的 Cookie
# 4. 刷新页面重新登录

方法二：重启 WebUI 服务

bash
# 如果修改了密码或 secret_key，需要重启服务
# Docker 部署
docker restart maibot

# 源码部署
# 先停止当前进程（Ctrl+C），再重新启动
python bot.py

方法三：检查 secret_key 配置

toml
# 编辑 config/bot_config.toml
[webui]
secret_key = "your-secret-key-here"  # 确保与之前保持一致
session_expire = 7                   # Session 有效期（天），默认 7 天

⚠️ 注意：修改 secret_key 后所有已登录的 Session 都会失效，需要重新登录。

预防建议 ​

  • 延长 Session 有效期 — 将 session_expire 改为 30 天
  • 固定 secret_key — 不要频繁修改，否则每次都要重新登录
  • 使用浏览器书签 — 保存登录后的页面，避免重复输入密码

场景 13：平台未配置机器人账号 ​

错误现象 ​

  • 某平台（如 QQ）的消息无法发送
  • 日志提示 No bot account configured for platform qq
  • 适配器已连接但机器人无响应
  • 消息发送失败，返回 400 Bad Request

快速自查三连 ​

1️⃣ 检查平台配置 — 确认 platforms.qq.bot_accounts 已填写 2️⃣ 验证账号凭证 — 确认 Token/密码正确且未过期 3️⃣ 查看适配器日志 — 确认适配器已正常连接

解决方案 ​

步骤一：配置机器人账号

toml
# 编辑 config/bot_config.toml
[platforms.qq]
enabled = true

# 添加机器人账号配置
[[platforms.qq.bot_accounts]]
uin = "123456789"              # 机器人 QQ 号
token = "your-bot-token"       # 机器人 Token（根据适配器类型填写）

# 如果使用 NapCat 适配器，还需配置：
[[platforms.qq.bot_accounts]]
uin = "123456789"
adapter = "napcat"
napcat_uin = "987654321"       # NapCat 登录的 QQ 号

步骤二：检查适配器连接

bash
# 查看适配器日志
# Docker 部署
docker logs maibot | grep -i adapter

# 源码部署
# 观察终端输出，寻找「适配器已连接」相关日志

步骤三：验证账号凭证

  • QQ 平台 — 确认 QQ 号能正常登录 NapCat/GoCQ
  • 微信平台 — 确认 Token 未过期且权限正确
  • 其他平台 — 参考对应适配器的文档

预防建议 ​

  • 使用小号 — 避免主号被封风险
  • 定期更新凭证 — Token 过期前及时更换
  • 配置备用账号 — 主账号异常时可快速切换

场景 14：正则表达式无效 ​

错误现象 ​

  • 启动或保存配置时报 re.error: bad escape 等错误
  • 日志提示 Invalid regex pattern 或 正则表达式编译失败
  • 关键词规则/消息过滤不生效
  • 配置页面提示「保存失败：正则语法错误」

快速自查三连 ​

1️⃣ 检查特殊字符转义 — \. \* \+ 等特殊字符是否加了反斜杠 2️⃣ 检查括号闭合 — () [] {} 是否成对出现 3️⃣ 使用在线工具测试 — 用 regex101.com 验证正则是否正确

解决方案 ​

方法一：使用在线正则测试工具

text
# 访问 https://regex101.com/
# 1. 在左侧输入你的正则表达式
# 2. 在下方输入测试文本
# 3. 查看是否报错并调整

方法二：转义特殊字符

toml
# 错误示例：未转义
ban_msgs_regex = ["\d{17}[\dXx"]  # 方括号未闭合

# 正确示例：转义并闭合
ban_msgs_regex = [
    "\\d{17}[\\dXx]",            # 身份证号（TOML 中需要双反斜杠）
    "1[3-9]\\d{9}",              # 手机号
    "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",  # 邮箱
]

方法三：使用普通字符串代替正则

toml
# 如果不需要复杂匹配，用普通字符串更安全
ban_words = ["广告", "加微信", "兼职"]  # 简单关键词，无需正则

# 避免写复杂的正则表达式
# ban_msgs_regex = ["(今天 | 明天 | 后天).*(天气 | 气温)"]  # 容易出错
# 改用关键词匹配
ban_words = ["天气", "气温", "温度"]

💡 提示：TOML 文件中正则表达式需要双反斜杠 \\ 转义，因为 \ 本身是 TOML 的转义字符。

预防建议 ​

  • 优先用关键词匹配 — 简单场景不需要正则
  • 复杂正则单独测试 — 先在 regex101.com 验证再填入配置
  • 添加注释说明 — 在正则旁边注释匹配的内容，方便后续维护

场景 15：关键词规则配置错误 ​

错误现象 ​

  • 消息匹配到错误的回复规则
  • 规则完全不生效，机器人不回复
  • 优先级冲突，高优先级规则覆盖低优先级
  • 中英文标点混用导致匹配失败

快速自查三连 ​

1️⃣ 检查规则优先级 — priority 高的规则会覆盖低的 2️⃣ 确认规则已启用 — enabled = true 是否设置 3️⃣ 测试标点符号 — 全角/半角符号差异会影响匹配

解决方案 ​

步骤一：检查关键词规则配置

toml
# 编辑 config/bot_config.toml
[keyword_reaction]

# 纯关键词规则
[[keyword_reaction.keyword_rules]]
keywords = ["你好", "hello", "嗨"]
regex = []
reaction = "你好呀！有什么可以帮你的吗？"
priority = 10                    # 优先级，数字越大优先级越高
enabled = true                   # 确保规则已启用

# 纯正则规则
[[keyword_reaction.regex_rules]]
keywords = []
regex = ["(早安 | 早上好 | 早 [上啊].*)"]
reaction = "早上好！今天又是美好的一天~"
priority = 20
enabled = true

# 关键词 + 正则混合规则
[[keyword_reaction.keyword_rules]]
keywords = ["天气"]
regex = ["(今天 | 明天 | 后天).*(天气 | 气温 | 温度)"]
reaction = "让我看看天气预报..."
priority = 15
enabled = true

步骤二：调整优先级

toml
# 优先级示例：
# priority = 30 — 最高优先级（精确匹配）
# priority = 20 — 中等优先级（正则匹配）
# priority = 10 — 默认优先级（普通关键词）
# priority = 1  — 最低优先级（兜底规则）

# 确保重要规则的优先级高于通用规则
[[keyword_reaction.keyword_rules]]
keywords = ["帮助", "help"]
reaction = "我可以帮你..."
priority = 30                    # 高优先级，确保优先匹配

[[keyword_reaction.keyword_rules]]
keywords = ["吗", "呢", "吧"]     # 通用疑问词，优先级放低
reaction = "这个嘛..."
priority = 5

步骤三：测试标点符号差异

toml
# 全角标点（中文输入法）
keywords = ["你好，", "你好，"]   # 逗号不同

# 半角标点（英文输入法）
keywords = ["hello,", "hello!"]

# 建议同时配置两种标点
keywords = ["你好，", "你好，", "hello", "hello!"]

预防建议 ​

  • 规则命名加注释 — 在规则旁边注释用途
  • 优先级分层管理 — 精确匹配 > 正则匹配 > 普通关键词 > 兜底规则
  • 定期测试规则 — 在群里发送测试消息验证匹配效果
  • 使用调试模式 — 打开 DEBUG 日志查看实际匹配链路

场景 16：Git 操作失败（WebUI） ​

错误现象 ​

  • WebUI 中知识库同步/Git 镜像操作失败
  • 日志显示 Git clone failed 或 Permission denied
  • SSH Key 验证失败提示 Host key verification failed
  • Git LFS 文件过大导致超时

快速自查三连 ​

1️⃣ 先确认网络 — 能不能访问 GitHub/Gitee？ 2️⃣ 换个公开仓库试试 — 不需要登录的仓库有没有问题？ 3️⃣ 仓库是不是太大了 — 大文件会导致超时

解决方案 ​

步骤一：确认网络连通 看看能不能打开 GitHub 或 Gitee 网站。如果打不开，说明网络有问题，先解决网络。

步骤二：换个不需要登录的仓库试试 如果提示权限错误（Permission denied），在 WebUI 中换个公开仓库（不需要 SSH Key 的那种）测试一下。如果公开仓库能正常同步，说明是 SSH 权限配置问题，去 GitHub/Gitee 检查 SSH Key 设置。

步骤三：调整 Git 超时配置 如果仓库较大，在 config/bot_config.toml 中把超时设长一点：

toml
[git_mirror]
timeout = 300                    # Git 操作超时（秒），默认 300 秒
max_file_size = 100              # 单文件最大体积（MB），超过会跳过

预防建议 ​

  • 先用公开仓库测试 — 确认能同步了再换私有仓库
  • 避免大文件 — 不要在仓库里放大型二进制文件

场景 17：日志文件过大 / 磁盘空间满 ​

错误现象 ​

  • 系统运行缓慢或崩溃
  • 日志轮转失败报 No space left on device
  • 磁盘使用率 100%，无法写入新文件
  • MaiBot 启动失败，提示数据库锁定或写入失败

快速自查三连 ​

1️⃣ 检查磁盘空间 — 打开文件管理器看看磁盘还剩多少空间 2️⃣ 查看日志文件大小 — 看看 logs/ 文件夹有多大 3️⃣ 检查日志级别 — DEBUG 级别会产生大量日志

解决方案 ​

步骤一：清理日志文件 打开 logs/ 文件夹，删除不需要的旧日志文件。一般只需要保留最近几天的日志，以前的可以直接删掉。

步骤二：配置日志轮转

toml
# 编辑 config/bot_config.toml
[logging]
level = "INFO"                 # 生产环境用 INFO，调试时用 DEBUG
max_bytes = 10485760           # 单文件最大 10MB
backup_count = 5               # 保留 5 个备份文件
enable_rotation = true         # 启用日志轮转

步骤三：清理其他垃圾文件

  • Docker 用户：清理未使用的镜像和容器释放空间
  • 检查 ~/.cache/ 目录，可以删除里面不需要的缓存文件

步骤四：如果还不行，换个盘 如果当前磁盘确实空间太小，考虑把 MaiBot 的日志和数据目录移到空间更大的磁盘上。

预防建议 ​

  • 生产环境用 INFO 级别 — 避免 DEBUG 日志过多
  • 配置日志轮转 — 限制日志文件大小和数量
  • 定期清理 — 设置 crontab 每周自动清理旧日志
  • 独立磁盘挂载 — 将日志目录挂载到独立磁盘分区
  • 监控磁盘空间 — 设置告警，使用率超过 80% 时通知

⚪ 低频错误（罕见） ​

覆盖场景 18–19，极少遇到但在特殊操作时可能出现的问题。

场景 18：人物/用户系统数据异常 ​

错误现象 ​

  • WebUI 中用户资料加载失败，显示空白或报错
  • 人物卡信息丢失，之前设置的性格/背景没了
  • 绑定账号时提示「用户已存在」或「外键约束失败」

快速自查三连 ​

1️⃣ 是不是直接改过 SQLite 数据库文件？ 2️⃣ data/persons/ 文件夹里的人物卡 JSON 格式对吗？ 3️⃣ 有没有多个 MaiBot 实例同时访问同一个数据库？

解决方案 ​

重建用户索引

bash
maibot person rebuild

检查人物卡格式

bash
# 进入人物卡目录
cd data/persons/

# 验证 JSON 格式（以某个角色为例）
python -m json.tool "角色名.json" > /dev/null

修复数据库（谨慎操作）

bash
# 备份数据库
cp data/maibot.db data/maibot.db.bak

# 使用 WebUI 管理用户，不要直接操作数据库

预防建议 ​

  • 🖥️ 用 WebUI 管理 - 不要直接改数据库文件
  • 💾 定期备份 - data/persons/ 和 data/maibot.db 很重要
  • 🔒 避免并发访问 - 不要同时启动多个 MaiBot 连同一个数据库

场景 19：适配器 WebSocket 断开重连循环 ​

错误现象 ​

适配器日志持续刷屏：

[WebSocket] Connection closed, reconnecting...
[WebSocket] Reconnecting in 3s...
[WebSocket] Connection established
[WebSocket] Connection closed, reconnecting...

消息收发不稳定，有时能收到有时收不到。

快速自查三连 ​

1️⃣ adapter.ws_url 地址和端口填对了吗？ 2️⃣ 网络稳不稳定？（服务器和适配器之间） 3️⃣ 服务端 WebSocket 服务正常运行吗？

解决方案 ​

检查 WebSocket 地址

toml
# 打开适配器配置文件
[adapter]
ws_url = "ws://127.0.0.1:8000"  # 确保地址和端口正确

调整重连间隔

toml
[adapter]
reconnect_interval = 5  # 增大间隔，避免频繁重连（单位：秒）

检查服务端状态 检查 MaiBot 终端输出，确认 WebSocket 服务已在正常运行（应该有类似 WebSocket 服务启动成功 的日志）。

添加心跳保活（高级） 如果网络环境较差，可以在适配器配置中启用心跳：

toml
[adapter]
enable_heartbeat = true
heartbeat_interval = 30  # 每 30 秒发送一次心跳

预防建议 ​

  • 🌐 确保网络稳定 - 服务器和适配器之间网络要通畅
  • 🔔 启用心跳检测 - 长连接建议开启心跳保活
  • 📊 监控日志 - 发现频繁重连及时排查
  • 🔄 考虑用进程管理 - systemd/supervisor 可以自动重启服务

⚡ 错误代码速查表 ​

按错误日志中常见的关键词快速定位到对应场景。

HTTP 状态码速查 ​

HTTP 400 Bad Request 🟧 严重 → 场景 13：平台未配置机器人账号 — 请求参数错误，消息发送失败

HTTP 401 Unauthorized 🟥 致命 → 场景 2：API Key 错误/余额不足 — API Key 无效或缺失

HTTP 401 Unauthorized 🟧 严重 → 场景 12：WebUI 登录失败 / Token 过期 — Session 过期或 Token 失效

HTTP 402 Payment Required 🟧 严重 → 场景 2：API Key 错误/余额不足 — 账户余额不足

HTTP 403 Forbidden 🟥 致命 → 场景 2：API Key 错误/余额不足 — API Key 权限不足

HTTP 429 Too Many Requests 🟧 严重 → 场景 9：网络超时/连接失败 — 请求频率过高被限流

HTTP 500 Internal Server Error 🟧 严重 → 场景 9：网络超时/连接失败 — API 服务端内部错误

HTTP 502 Bad Gateway 🟧 严重 → 场景 9：网络超时/连接失败 — 网关错误，上游服务不可达

HTTP 503 Service Unavailable 🟧 严重 → 场景 9：网络超时/连接失败 — 服务暂时不可用（过载/维护）

常见错误关键词索引 ​

Address already in use / [Errno 98] / [Errno 10048] 🟧 严重 → 场景 3：端口被占用 — 端口已被其他进程占用

APIConnectionError 🟧 严重 → 场景 9：网络超时/连接失败 — API 连接失败

Connection refused / 无法访问此网站 🟥 致命 → 场景 4：WebUI 页面打不开 — WebUI 服务未启动或端口不可达

database is locked 🟧 严重 → 场景 8：数据库错误 — 数据库被多进程锁定

DatabaseError / OperationalError 🟧 严重 → 场景 8：数据库错误 — 数据库操作异常

FileNotFoundError 🟥 致命 → 场景 1：配置文件找不到或格式不对 — 配置文件不存在

FilterError 🟨 警告 → 场景 10：表情包系统错误 — 表情过滤规则误杀

ImportError / ModuleNotFoundError 🟧 严重 → 场景 7：插件加载失败 — 插件依赖缺失

No space left on device 🟧 严重 → 场景 17：日志文件过大 / 磁盘空间满 — 磁盘空间不足

PluginLoadError 🟧 严重 → 场景 7：插件加载失败 — 插件加载异常

re.error / bad escape 🟨 警告 → 场景 14：正则表达式无效 — 正则语法错误

TimeoutError 🟧 严重 → 场景 9：网络超时/连接失败 — 请求超时

Token expired 🟨 警告 → 场景 12：WebUI 登录失败 / Token 过期 — 登录 Session 已过期

TOML syntax error 🟥 致命 → 场景 1：配置文件找不到或格式不对 — 配置文件格式错误

ValueError 🟥 致命 → 场景 5：MCP 配置错误 — MCP 服务器配置参数无效

VLMError 🟨 警告 → 场景 10：表情包系统错误 — 视觉语言模型调用失败

知识加载失败 🟧 严重 → 场景 11：知识图谱/记忆系统错误 — 知识文件损坏或格式错误

Session 过期 🟨 警告 → 场景 12：WebUI 登录失败 / Token 过期 — 浏览器 Session 已失效

🆘 获取帮助指引 ​

🤔 提问前自查 ​

在向别人求助之前，花 2 分钟做以下检查，大部分问题可以自己解决：

📖 1. 查阅官方文档 : 你的问题很可能已经在本文档的各个场景中有解答了。先搜一遍，省时省力。

🔍 2. 查看错误日志 : 日志里会写明具体的错误原因和堆栈跟踪，这是定位问题的第一线索。不知道怎么导出？往下看「如何获取日志」。

⚙️ 3. 检查近期改动 : 回想最近改过什么配置、装过什么插件、更新过什么版本。尝试回退到最后一次正常工作的状态，确认是不是哪步改错了。

🌐 4. 搜索已知问题 : 用错误关键词搜索 GitHub Issues 或搜索引擎，看看是否有别人遇到过相同的问题。

📋 提交 Issue 的信息清单 ​

向 GitHub 提交 Issue 时，请务必包含以下信息。缺少关键信息的问题可能会被延迟处理：

🖥️ 系统与环境 : 操作系统类型及版本、部署方式（源码/Docker）、Python 版本（源码部署时）

🔢 MaiBot 版本 : 运行 git log --oneline -1 查看当前 commit，或从 WebUI 底部的版本号获取

📄 完整错误日志 : 包含堆栈跟踪（traceback）的日志片段，不要只截图一小段。详见下方的「如何获取日志」

⚙️ 相关配置 : 与问题相关的配置内容（注意隐去 API Key 等敏感信息）

🎯 复现步骤 : 从启动到出现错误的具体操作步骤，越详细越好

🌐 社区支持渠道 ​

💬 QQ 群 : 加入 MaiBot 用户交流群，和其他用户一起交流使用经验。群号：[请填写群号]

🐱 GitHub Issues : 确认是 Bug 或功能建议，请在 GitHub Issues 提交。提交前记得先搜索，避免重复

📖 官方文档站 : 最新最全的文档请访问 MaiBot 文档站

💬 GitHub Discussions : 功能讨论、技术提问可访问 GitHub Discussions 参与社区讨论

📝 如何获取日志 ​

根据部署方式不同，获取日志的方法也不同：

🐍 源码部署 : 启动 MaiBot 的终端输出就是最直接的日志。如果终端已关闭，查看日志文件如下：

bash
cat logs/maibot-*.log

如果需要更详细的日志，在 config/bot_config.toml 中开启 DEBUG 级别：

toml
[log]
log_level = "DEBUG"

🐳 Docker 部署 : 使用 docker logs 命令查看容器日志：

bash
# 查看所有日志
docker logs maibot

# 持续跟踪日志输出
docker logs -f maibot

# 只查看最近 100 行
docker logs --tail 100 maibot

🪟 Windows 部署 : 日志文件默认在 logs\ 目录下：

powershell
type logs\maibot-*.log

# 或使用 PowerShell
Get-Content logs\maibot-*.log

💡 提示：获取日志后，用 ``` 代码块包起来粘贴到 Issue 中。如果日志很长，只贴最近一次启动到出错的部分即可，不要贴几千行的完整日志。

📋 错误排查流程图 ​

不确定问题属于哪一类？按流程图指引找到对应章节。