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.

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 Pilot 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. The portable installer and the PowerShell source installer install it via winget; the uv tool install path does not.

If logs show DLL load failed:

1. Install the Visual C++ Redistributable (2015-2022 x64).
2. Restart the shell and gateway.

Router Degraded or Pinned to One Tier#

A missing or incomplete ONNX model bundle is the usual cause. From a source checkout:

git lfs pull --include="src/agentos/agentos_router/models/**"

Then rebuild and reinstall. Release installs ship the bundle in the wheel.

To use the llm_judge strategy instead (no local model files), pick it during onboarding or set:

[agentos_router]
strategy = "llm_judge"

Restart the gateway after changing the file. See Configuration.

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

Browser Tool Not Found or Not Working#

The browser tool stays hidden until the agent-browser binary is installed:

npm install -g agent-browser
agent-browser install          # downloads Chromium

On Debian, Ubuntu, or Docker, also install system libraries:

agent-browser install --with-deps

agentos doctor reports whether the binary and Chromium are present.

A gateway started by the desktop app, launchd or systemd does not inherit your shell's PATH, so AgentOS also looks in the usual npm global directories: the newest nvm and fnm Node versions, Volta, pnpm, Bun, Homebrew (/opt/homebrew/bin, /usr/local/bin) and ~/.npm-global/bin. If your install lives somewhere else, set the path explicitly:

[browser]
binary_path = "/path/to/agent-browser"   # output of `which agent-browser`

Headless Chromium Gets Blocked#

Some sites detect headless Chromium and serve CAPTCHAs or refuse to load. Do not try to solve CAPTCHAs. Switch to web_search / web_fetch, or use attach mode with a signed-in Chrome.

Attach Mode Will Not Connect#

Start Chrome with a debug port on localhost:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

Then set both the port and the consent flag:

[browser]
cdp_port = 9222
attach_confirmed = true

The port alone is not enough. attach_confirmed = true is required because attach mode can drive whatever the Chrome session is logged into.

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 Tool Compression.

Memory or Embeddings Not Working#

Memory search uses local ONNX embeddings by default. Inspect:

agentos memory status

If the embedding model is not loaded, the recommended extra may be missing:

uv tool install --force "use-agent-os[recommended]"

For source installs, pull the Git LFS weights:

git lfs pull --include="src/agentos/memory/models/**"

If the model files are pointer stubs instead of real weights, embeddings will not load. agentos doctor will report memory embeddings as FTS-only.

Docker-Specific Issues#

The shipped Dockerfile already sets AGENTOS_LISTEN=0.0.0.0. Custom images must bind 0.0.0.0 (--listen 0.0.0.0 or AGENTOS_LISTEN=0.0.0.0) so the port mapping reaches the gateway. Binding 127.0.0.1 inside the container is valid, but the process is then unreachable from the host.

• ONNX Runtime and Pilot Router may need extra system packages depending on the base image. The repo Dockerfile handles this; a custom image may not.
• Mount ~/.agentos if config and sessions should persist across restarts.

Still Stuck?#

1. Run agentos doctor and read the findings.
2. Check the docs index for the feature you are using.
3. Open a documentation issue or a bug report on GitHub.