Why
The first failed run is the highest-risk moment for a new user. OpenGUI has several moving parts: backend, model config, APK, server URL, AccessibilityService, overlay permission, and battery settings. A troubleshooting guide would reduce abandonment and convert failures into useful issue reports.
Scope
Cover common symptoms:
- Android client cannot reach backend
- emulator uses the wrong host address
- physical phone cannot connect to the laptop backend
- AccessibilityService is disabled or killed
- overlay permission blocks task feedback
- missing model API configuration
- Redis or PostgreSQL port conflicts
Suggested files
docs/troubleshooting.md
- README and release notes link to it
Done when
The guide maps symptoms to likely causes, checks, and fixes with short commands or screenshots where useful.
Why
The first failed run is the highest-risk moment for a new user. OpenGUI has several moving parts: backend, model config, APK, server URL, AccessibilityService, overlay permission, and battery settings. A troubleshooting guide would reduce abandonment and convert failures into useful issue reports.
Scope
Cover common symptoms:
Suggested files
docs/troubleshooting.mdDone when
The guide maps symptoms to likely causes, checks, and fixes with short commands or screenshots where useful.