Skip to content

Add troubleshooting guide for backend connection and Android permissions #12

@xiaohuantech

Description

@xiaohuantech

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions