Integration Guide
OpenClaw + 9Router: One Local Gateway for Several Providers
9Router runs as a gateway between your agent and upstream model providers, exposing one local OpenAI-compatible API with aliases, fallback combos and usage tracking. OpenClaw treats it as an ordinary custom endpoint — the interesting part is the network boundary and the credentials you put behind it.
The shape of the setup
OpenClaw → http://127.0.0.1:20128/v1 → 9Router → provider9Router authenticates the request, picks an account, model, alias or fallback combo, translates the request where needed, and returns an OpenAI-compatible response. To OpenClaw it is indistinguishable from any other OpenAI-compatible endpoint.
Install and secure it first
- Install 9Router from its official repository or package instructions.
- Replace the default first-login password before connecting any provider account.
- Enable endpoint API-key enforcement so the gateway is not open to anything that can reach it.
- Keep it on localhost, a private Docker network, or a private tunnel wherever possible.
- Connect only providers whose terms permit the workflow you have in mind.
Do this before pointing an agent at it. A routing gateway concentrates every provider credential you own into one process, which is convenient in exactly the same way it is dangerous.
The address trap
127.0.0.1 inside a container means that container. If OpenClaw runs in Docker and 9Router runs on the host, the agent connects to nothing and reports a connection refused that reads like the gateway is down. Use host.docker.internal, a service name on a shared Docker network, or a private IP that the OpenClaw runtime can genuinely reach.One caveat on
host.docker.internal: it resolves out of the box on Docker Desktop, but on Linux Docker Engine it exists only if the container was started with --add-host=host.docker.internal:host-gateway. On a Linux server without that mapping, use the host's address on the Docker bridge or put both containers on a shared network and use the service name.Configure OpenClaw
9Router speaks OpenAI's wire format, so this is the openai provider with a custom base URL:
{
"models": {
"providers": {
"openai": {
"baseUrl": "http://host.docker.internal:20128/v1",
"apiKey": "YOUR_9ROUTER_KEY"
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "openai/EXACT_MODEL_OR_COMBO_ID"
}
}
}
}The model ID must be exactly what 9Router's dashboard shows, including combo IDs. The provider prefix stays openai/ because that is the provider slot in use, not because OpenAI is serving the request.
Verify with the CLI, not with a chat reply
openclaw models list
openclaw models statusmodels status shows what will actually be used. This matters more than usual with a gateway in the path: if the config fails validation, OpenClaw keeps the previous model, the agent answers normally, and nothing tells you the gateway is not involved at all.
Aliases pair well with a router
openclaw models aliases add gw openai/EXACT_MODEL_OR_COMBO_ID
openclaw models aliases list
openclaw models set gwmodels aliases alone is just the parent command — add, list and remove are the subcommands that act. Likewise models set requires the model id or alias as an argument.
9Router already gives you aliases on its side. Adding an OpenClaw alias on top means you can change either layer independently — useful when you want to test a different route without touching any agent config.
What a router is genuinely for
- Fallback — move to another approved model when a provider is unavailable.
- Aliases — keep one stable model name in the agent while the route changes behind it.
- Usage visibility — request and cost records for several providers in one dashboard.
- Format translation — bridge compatible request formats where supported.
None of these improve answer quality. If you use one provider and do not need fallback or reporting, connect it directly — fewer moving parts, smaller credential surface, one less thing that can be down at 3am.
OpenClaw Launch manages the OpenClaw service itself. A private 9Router deployment stays your responsibility, including its updates, provider accounts, security and compliance.
OpenClaw and 9Router FAQ
Can OpenClaw connect to 9Router?
Yes. 9Router exposes a local OpenAI-compatible endpoint, commonly at http://127.0.0.1:20128/v1, and OpenClaw consumes it through the openai provider with a custom baseUrl.
Why does 127.0.0.1 not work from my OpenClaw container?
Because inside a container 127.0.0.1 is the container itself. If 9Router runs on the host or in a different container, use host.docker.internal, the other container's service name on a shared Docker network, or a private address reachable from the OpenClaw runtime.
Should 9Router be exposed to the internet?
Prefer localhost, a private Docker network, or a private tunnel. If it must be reachable publicly, enable API-key enforcement, put HTTPS in front, restrict by firewall, and change the default dashboard password before connecting any account.
Does 9Router make model usage free?
No. Cost and permitted usage depend on each connected provider and its terms. Review those terms before routing any subscription credential through a gateway.
What does it give me over connecting a provider directly?
Fallback when a provider is unavailable, stable aliases so the agent keeps one model name while the route behind it changes, and one dashboard for usage and cost. If you use a single provider, none of those apply and a direct connection is simpler.