Troubleshooting
Start with:
agentos doctor
agentos doctor --json
agentos gateway status
The Web UI health view at http://127.0.0.1:18791/control/ also reports readiness and recovery steps when the gateway is running.
agentos Command Not Found
After uv tool install, open a new terminal or run:
uv tool update-shell
Check the executable:
command -v agentos
On Windows PowerShell:
where.exe agentos
Gateway Is Not Running
Start it:
agentos gateway run
Or use the managed background process:
agentos gateway start --json
agentos gateway status
Open:
http://127.0.0.1:18791/control/
For a focused gateway guide, see gateway.md.
Port Already In Use
Use another port:
agentos gateway run --port 18792
Or stop the managed gateway:
agentos gateway stop
Provider Not Configured
Run:
agentos onboard
agentos providers list
agentos providers configure openrouter
Use environment-variable secrets:
export OPENAI_API_KEY="sk-..."
agentos configure provider --provider openai --api-key-env OPENAI_API_KEY
Router Dependency Problems
If AgentOS Router cannot load, AgentOS can still run with direct model routing. To disable the router:
agentos configure router --router disabled
agentos gateway restart
On Windows, ONNX Runtime may need the Visual C++ Redistributable for Visual Studio 2015-2022 x64. Install it, then restart the shell and gateway.
Search Does Not Work
Inspect search providers:
agentos search list
agentos search status
Use DuckDuckGo for a no-key path:
agentos configure search --search-provider duckduckgo
Use Brave with a key:
export BRAVE_SEARCH_API_KEY="..."
agentos configure search --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY
Channel Config Saved but Channel Is Offline
Restart the gateway after editing channel config:
agentos gateway restart
agentos channels status <name> --json
For webhook channels, confirm the gateway is reachable from the provider and that callback secrets match.
A Tool Was Denied
Check sandbox and permission state:
agentos sandbox status
agentos doctor
For one-shot runs, choose an explicit permission posture:
agentos agent --permissions restricted -m "Read only"
agentos agent --permissions full -m "Trusted local automation"
The Agent Seems to Forget Old Context
Long sessions may compact old history. This is expected under context pressure.
Inspect sessions:
agentos sessions show <session-key>
agentos sessions export <session-key>
If exact old text matters, keep it in a file, memory note, or exported session.
A Turn Is Too Expensive or Too Slow
Try:
agentos configure router --router recommended
agentos diagnostics on
agentos cost
For automation:
agentos agent --max-iterations 20 --timeout 600 -m "Bounded task"
For large tool outputs, see
features/tool-compression.md.