Troubleshooting

Start with:

opensquilla doctor
opensquilla doctor --json
opensquilla 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.

opensquilla Command Not Found

After uv tool install, open a new terminal or run:

uv tool update-shell

Check the executable:

command -v opensquilla

On Windows PowerShell:

where.exe opensquilla

Gateway Is Not Running

Start it:

opensquilla gateway run

Or use the managed background process:

opensquilla gateway start --json
opensquilla 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:

opensquilla gateway run --port 18792

Or stop the managed gateway:

opensquilla gateway stop

Provider Not Configured

Run:

opensquilla onboard
opensquilla providers list
opensquilla providers configure openrouter

Use environment-variable secrets:

export OPENAI_API_KEY="sk-..."
opensquilla configure provider --provider openai --api-key-env OPENAI_API_KEY

Router Dependency Problems

If SquillaRouter cannot load, OpenSquilla can still run with direct model routing. To disable the router:

opensquilla configure router --router disabled
opensquilla 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:

opensquilla search list
opensquilla search status

Use DuckDuckGo for a no-key path:

opensquilla configure search --search-provider duckduckgo

Use Brave with a key:

export BRAVE_SEARCH_API_KEY="..."
opensquilla 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:

opensquilla gateway restart
opensquilla 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:

opensquilla sandbox status
opensquilla doctor

For one-shot runs, choose an explicit permission posture:

opensquilla agent --permissions restricted -m "Read only"
opensquilla 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:

opensquilla sessions show <session-key>
opensquilla 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:

opensquilla configure router --router recommended
opensquilla diagnostics on
opensquilla cost

For automation:

opensquilla agent --max-iterations 20 --timeout 600 -m "Bounded task"

For large tool outputs, see features/tool-compression.md.

Docs index · Product guide · Improve this page · Report a docs issue