Frequently Asked Questions
Browse questions by topic. If the log already contains a specific error or status code, go directly to Error Troubleshooting.
Categories
Basic Usage — Costs, supported platforms, first steps, and asking for help.
Deployment and Startup — Startup failures, configuration files, ports, and WebUI access.
One-click Package — Installation paths, user data, instance migration, and bundled adapters.
Adapter Connections — the unified QQ connector, the QQ official bot, and the access policy.
Chat and Replies — Speaking frequency, self-replies, consecutive messages, and reply splitting.
Models and APIs — API keys, model identifiers, vision models, and embeddings.
Memory and Learning — Long-term memory, relation vectors, incorrect memories, expressions, and jargon.
Plugin Issues — Plugin activation, command conflicts, downloads, and diagnosis.
Backup and Migration — What to back up, migration steps, and restore checks.
Troubleshooting
Enter the page that matches the error topic; when the log already contains a specific error code or keyword, use the quick reference on the overview page to jump straight there.
Error Troubleshooting Overview — error code quick reference, keyword index, and the troubleshooting flowchart.
Startup and Access Troubleshooting — configuration files, MCP, ports, WebUI access and login, Git operations.
Model and Rule Troubleshooting — API keys, network timeouts, regular expressions, keyword rules.
Runtime and Data Troubleshooting — missing replies, databases, emojis, memory, disk space, data anomalies.
Plugin and Adapter Troubleshooting — plugin loading failures, adapter connections and reconnects.
Getting Help — self-checks before asking, the issue checklist, community channels, and how to export logs.
Quick checks
- Record the MaiBot, package, and adapter versions.
- Keep the complete log around the failure, not only its last line.
- Note recent configuration, model, or plugin changes.
- Follow the relevant category or search Error Troubleshooting.
- When requesting help, include versions, sanitized logs, relevant settings, and reproduction steps.
Sources
Some answers were adapted from the community-maintained document MaiBot Tutorial — Quick FAQ / Community Tutorial. Thanks to all the authors for their support of MaiBot!
The text on this site was not copied verbatim. It was reorganized, corrected, and verified against the current MaiBot configuration and code.