Claude Code + OmniRoute Complete Setup Kit

Every click after this is a node on that diagram. When in doubt, trace where you are on it.

Your OmniRoute Base URL and a token/API key, from your OmniRoute account. Everything else you need is in this guide. Never share these with anyone, and never paste a real value while someone else watches your screen live.

We use claude-sonnet-4-6 as the worked example. If your OmniRoute dashboard names a different route/model, note it now and substitute it in Module 05.

Claude Code is the CLI you talk to. OmniRoute sits between it and the model providers. Claude Code sends every request to OmniRoute; OmniRoute decides which model answers, tracks usage, and keeps provider keys off your machine.

Claude Code treats OmniRoute as a gateway. A gateway is simply an address (ANTHROPIC_BASE_URL) plus a credential (ANTHROPIC_AUTH_TOKEN). No OmniRoute files to install — it’s two variables. The entire kit is making those two variables true and proving it.

Follow the diagram: access → connect → choose → verify → run. The decision node is your checkpoint at Module 05.

Go to the OmniRoute dashboard and sign in. If you don’t yet have an account, sign up and finish onboarding.

Follow the dashboard’s API keys section. Copy the key once — most providers show it only a single time. Save it in your password manager, not a scratch note.

Dashboard usually shows it near API keys or in the docs. It looks like https://… with no trailing slash. If your dashboard shows one sample endpoint per provider, note the OmniRoute-specific one.

OmniRoute may expose named routes (e.g. a smart router for Claude models) or plain model ids (e.g. claude-sonnet-4-6). Note exactly which string you’ll test with.

Run claude --version in your terminal. If it errors, install Claude Code first (see the README), then return here.

ANTHROPIC_BASE_URL = your OmniRoute Base URL. ANTHROPIC_AUTH_TOKEN = your API key (this is the bearer-token credential). Each variable maps to one HTTP header — the token travels as Authorization: Bearer …. If your OmniRoute key is meant to be sent as x-api-key instead, swap ANTHROPIC_AUTH_TOKEN → ANTHROPIC_API_KEY.

Paste the block below. Replace https://omniroute.example.com with your real Base URL and sk-your-token with your real key. This proves OmniRoute answers before Claude Code is involved.

export ANTHROPIC_BASE_URL=https://omniroute.example.com
export ANTHROPIC_AUTH_TOKEN=sk-your-token

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"hi"}]}'

Shell exports die with the terminal. Put both variables in the env block of your user-level settings file so every new terminal picks them up. Open ~/.claude/settings.json and add the block below.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://omniroute.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-token"
  }
}

Put the credential in user-level settings only (~/.claude/settings.json), or in a shell export. Never commit a credential to a project’s .claude/settings.json — that file can be shared with the repo. When both a shell export and the settings env block set a variable, the settings block wins.

Inside an active session, type /model. Built-in Claude models appear. If your gateway serves model names that aren’t in the built-in list and you want them in the picker, do step 2 first.

Set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 anywhere Claude Code reads it (shell or the env block). At startup Claude Code then queries OmniRoute’s model list and adds those names to the picker, labeled “From gateway”.

{
  "env": {
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

To confirm discovery ran: start with claude --debug and look for [gatewayDiscovery] in ~/.claude/debug/<session-id>.txt.

Some gateways route or tag requests with a custom header (tenant, routing key, environment). Use ANTHROPIC_CUSTOM_HEADERS with one Name: Value pair per line — inside JSON, separate pairs with \n.

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-OmniRoute-Route: fast\nX-Tenant: acme"
  }
}

Quit and relaunch claude (or open a fresh terminal) so it re-reads settings and re-runs discovery.

Run the Module 03 curl block again in a fresh terminal. JSON in = the plumbing is good.

Run claude. If it opens straight to a session, your credential was picked up. If it asks you to log in instead, your env isn’t being read — see Module 07 “asks to log in even though curl works.”

Open Claude Code’s status view and confirm it reports your OmniRoute Base URL as the active endpoint, not the default Anthropic API.

Type a tiny prompt: “Reply with exactly: routed ok”. Confirm the reply arrives and, ideally, that your OmniRoute dashboard shows one request for this session.

Start claude --debug. Look at ~/.claude/debug/<session-id>.txt for gateway auth and model discovery lines. This is your most direct evidence of what Claude Code is trying to reach.

Never commit ~/.claude/settings.json or any file containing ANTHROPIC_AUTH_TOKEN. If you must store config in a repo, use placeholders (YOUR_OMNIROUTE_TOKEN) and document how it maps to the real value.

A project’s .claude/settings.json and .claude/settings.local.json apply only after first-run setup and trust prompts — and the project file can ride into a repo. Both reasons: user-level or shell only for secrets.

Revoke and reissue from the OmniRoute dashboard when a key leaks or a teammate leaves. If your provider issues short-lived credentials, set up an apiKeyHelper (a command Claude Code runs to fetch the credential instead of a static variable) — covered further in the troubleshooting/notes section of this package.

Debug logs and error reports can contain headers. Clean ~/.claude/debug/ before sharing a log for support, and scrub Authorization lines.

80% of gateway failures are the same curl test failing. Run the Module 03 curl block first, always. Its result picks the right row below.

Claude Code and OmniRoute change fast. Set a quarterly calendar reminder to run the curl test once and skim the changelog in this package. Update the “Last verified” date when you do.

The package ships with changelog.md. Check it before upgrading Claude Code or an OmniRoute plan change — known breakages are listed there first.

When any variable changes, prove it on one machine (Module 05 all green) before reproducing on the rest. That’s the whole update discipline.

Same two variables, same settings file, same curl test. Ten minutes the second time — that’s the payoff of a written procedure.