docs: add FAQ and Troubleshooting section to README#7763
docs: add FAQ and Troubleshooting section to README#7763meichuanyi wants to merge 1 commit intoAstrBotDevs:masterfrom
Conversation
dosubot
Bot
added
the
size:M
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The
PLACEHOLDERline under## ❤️ Sponsorswill be rendered in the README; consider removing it or replacing it with actual content before merging. - The internal links to
[Supported Messaging Platforms](#supported-messaging-platforms)and[Supported Model Services](#supported-model-services)assume specific heading IDs; please confirm these IDs match the existing section headers or adjust the link targets to avoid broken navigation.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The `PLACEHOLDER` line under `## ❤️ Sponsors` will be rendered in the README; consider removing it or replacing it with actual content before merging.
- The internal links to `[Supported Messaging Platforms](#supported-messaging-platforms)` and `[Supported Model Services](#supported-model-services)` assume specific heading IDs; please confirm these IDs match the existing section headers or adjust the link targets to avoid broken navigation.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive FAQ and Troubleshooting section to the README.md, covering common questions about messaging platforms, LLM providers, and general troubleshooting steps. Feedback suggests aligning the Python version requirement with other sections of the documentation, providing cross-platform commands for port checking, and removing a placeholder string in the Sponsors section.
| - Test the API key independently with `curl` to isolate provider issues | ||
|
|
||
| **Q: AstrBot fails to start or crashes on launch.** | ||
| - Ensure Python 3.10+ is installed: `python --version` |
There was a problem hiding this comment.
There's an inconsistency in the required Python version. This line states Python 3.10+, but the "Quick Start" section for uv deployment recommends Python 3.12 or later. To avoid confusion for new users, please align the version requirement across the document. Based on the deployment instructions, 3.12+ seems to be the current recommendation.
| - Ensure Python 3.10+ is installed: `python --version` | |
| - Ensure Python 3.12+ is installed: `python --version` |
| **Q: The WebUI is not accessible.** | ||
| - Verify AstrBot is running and the WebUI port (default: 6185) is not blocked | ||
| - Check firewall rules if accessing from a remote machine | ||
| - Ensure no other process is using port 6185: `lsof -i :6185` |
There was a problem hiding this comment.
The lsof command is specific to Unix-like systems (Linux, macOS) and won't work on Windows. To make this troubleshooting step more helpful for all users, consider adding the equivalent command for Windows.
For example, you could suggest netstat -ano | findstr :6185 for Windows users.
| - Ensure no other process is using port 6185: `lsof -i :6185` | |
| - Ensure no other process is using port 6185 (e.g., `lsof -i :6185` on Linux/macOS, or `netstat -ano | findstr :6185` on Windows) |
|
|
||
|
|
||
| ## ❤️ Sponsors | ||
| PLACEHOLDER |
There was a problem hiding this comment.
This PLACEHOLDER text appears to be temporary. It should be replaced with the actual content or removed before merging to maintain the quality of the documentation. If there is no content yet, it's better to remove this line for now.
|
Hi! Just checking if there's any feedback on this FAQ addition. Happy to make adjustments if needed. 🙏 |
1 participant
Summary
Add a FAQ and Troubleshooting section to the English README to help new users quickly resolve common issues.
Changes
Motivation
The README currently lacks a dedicated FAQ/Troubleshooting section. New users frequently encounter setup and configuration questions that could be self-served with this documentation, reducing support burden on maintainers.
Checklist
Summary by Sourcery
Add a new FAQ and Troubleshooting section to the main README to help users resolve common setup and runtime issues.
Documentation: