Claude Code with OmniRoute Setup and Configuration

Yes—OmniRoute can work with Claude Code as an AI gateway and, separately, as an MCP server that exposes OmniRoute management tools. The reliable model-routing setup is to run OmniRoute on port 20128, create an OmniRoute key, and set Claude Code’s ANTHROPIC_BASE_URL to http://localhost:20128 without adding /v1.

Version Match and Installation

Use current versions of both packages. The published OmniRoute CLI reference states that npm-based tools require Node.js 22.22.2+ or 24.x.

node --version
npm install -g @anthropic-ai/claude-code
claude --version
npm install -g omniroute

Confirm that npm can see both global packages:

npm list -g @anthropic-ai/claude-code --depth=0
npm list -g omniroute --depth=0

A referenced CLI document is attached to the release/v3.8.51 branch and dated August 23, 2026, while the project site has continued changing. If omniroute run, omniroute launch, or omniroute setup-claude is missing, update OmniRoute and compare the available commands with omniroute --help and the OmniRoute project repository.

Start OmniRoute and Create a Client Key

To start the gateway and dashboard on the documented default port, run npm install -g omniroute followed by omniroute. Then open http://localhost:20128/dashboard. From there, add or sign in to at least one upstream provider and wait for its connection to become usable. Generate a client API key under /dashboard/api-manager and copy the complete key. Finally, test the OpenAI-compatible endpoint with a command such as curl -H "Authorization: Bearer YOUR_KEY" http://localhost:20128/v1/models.

Documentation shows both sk-... keys and newer-looking oma_live_... remote examples. Use the exact key generated by your installation rather than assuming a particular prefix.

For a guided checklist, you can also use the OmniRoute Claude Code setup helper.

Configure Claude Code

Option 1: Use the OmniRoute Launcher

The universal launcher injects the required settings and starts Claude Code:

omniroute run claude

The Claude-specific launcher remains available:

omniroute launch

According to the CLI documentation, omniroute launch resolves the active OmniRoute context, checks server health, and then starts the claude process.

To create separate profiles for available models, run:

omniroute setup-claude

This fetches models from the running gateway and writes per-model settings under paths such as:

~/.claude/profiles/PROFILE_NAME/settings.json

Launch a generated profile with:

omniroute launch --profile PROFILE_NAME

Use the profile name printed by setup-claude; do not invent a model or folder name.

Option 2: Set Environment Variables Manually

For macOS or Linux:

export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="YOUR_OMNIROUTE_KEY"
claude

For Windows PowerShell:

$env:ANTHROPIC_BASE_URL = "http://localhost:20128"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_OMNIROUTE_KEY"
claude

These commands configure the current terminal session. Add the variables to your shell startup file or Windows user environment if you want the manual configuration to persist.

Do not append /v1 to ANTHROPIC_BASE_URL. Claude Code uses the Anthropic Messages route and appends /v1/messages itself. Some third-party examples show http://localhost:20128/v1, but the published OmniRoute CLI reference specifies the gateway root. The /v1 form is used for OpenAI-compatible clients and direct routes such as /v1/models.

ANTHROPIC_AUTH_TOKEN sends the credential as Authorization: Bearer .... You can alternatively use:

export ANTHROPIC_API_KEY="YOUR_OMNIROUTE_KEY"

That variable sends x-api-key. If both variables are present, ANTHROPIC_AUTH_TOKEN takes precedence, so avoid setting both unless you intentionally want the Bearer-token method.

To force a particular routed model, use the exact ID displayed by OmniRoute:

export ANTHROPIC_MODEL="provider/model-id"
claude

Run omniroute models list first rather than guessing an ID. Environment changes are read when Claude Code starts, so restart it after editing them.

For a remote OmniRoute server, the documented workflow is:

omniroute connect 192.168.0.15
omniroute launch

The connect process requests the server password, saves a scoped access context, and lets later commands target that server.

Optional: Connect OmniRoute as an MCP Server

MCP integration is separate from model routing. It lets Claude Code call OmniRoute tools for providers, routing combos, cache, compression, memory, and related gateway controls:

claude mcp add-server omniroute --type http \
  --url http://localhost:20128/api/mcp/stream

You do not need this MCP command merely to send Claude Code model requests through OmniRoute. The API endpoint and authentication variables—or omniroute run claude—handle model traffic. Community Claude Code plugins can register the same MCP endpoint, but they are independently maintained and are not required for the gateway connection.

Verify the Connection

Run these checks in order:

curl http://localhost:20128/v1/models
omniroute doctor
omniroute providers list
omniroute providers test-all
omniroute models list

The doctor command checks configuration, the database, storage and encryption, ports, Node runtime, native binary, memory, and server liveness. Add --json when you need machine-readable diagnostic output.

Finally, start Claude Code through OmniRoute:

omniroute launch

Send a short test prompt in Claude Code. A successful launch performs OmniRoute’s health check before starting Claude, while a successful model response confirms that the client, key, provider, and route are working together.

Troubleshooting

Connection issues between Claude Code and OmniRoute typically manifest as specific errors or incorrect behaviors. The following table outlines common symptoms alongside their corresponding fixes to help resolve configuration and connection problems.

Symptom	What to check or fix
claude: command not found	Confirm Node.js meets the documented version requirement, reinstall @anthropic-ai/claude-code, and run claude --version.
omniroute run or setup-claude is unknown	Check the installed OmniRoute package with npm list -g omniroute --depth=0, update it, and inspect omniroute --help.
Connection refused	Start OmniRoute with omniroute, confirm port 20128, and run omniroute doctor.
401 or 403	Copy a new client key from /dashboard/api-manager. Use either ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY, not an old key left in both places.
404 or a path containing /v1/v1	Remove /v1 from ANTHROPIC_BASE_URL. The correct local value is http://localhost:20128.
Empty /model list or 400 Ambiguous model	Run omniroute models list, set an exact ANTHROPIC_MODEL, or generate and launch a profile with setup-claude.
Provider request fails	Run omniroute providers test for the affected provider or providers test-all, then repair its credentials in the dashboard.
Configuration changes have no effect	Close every running Claude Code process and start it again after changing environment variables.

Resolving these common errors typically involves verifying the Node.js environment, confirming the installation of the latest package versions, and accurately setting the authentication variables and base URL.

FAQ

Can OmniRoute be used as the backend for Claude Code?

Yes. OmniRoute exposes a gateway that Claude Code can call through its Anthropic-compatible configuration. The easiest methods are omniroute run claude, omniroute launch, or manual environment variables.

What is the correct OmniRoute base URL for Claude Code?

Use http://localhost:20128 for ANTHROPIC_BASE_URL on a local installation. Claude Code appends the Messages API path itself, so adding /v1 can cause a malformed route. Use http://localhost:20128/v1 when testing the OpenAI-compatible models endpoint.

Do I need the Claude Code plugin or MCP command?

No, not for normal model routing. The MCP connection exposes OmniRoute’s management tools inside Claude Code. The gateway connection still requires a valid base URL, client key, working provider, and a Claude Code launch method.

How do I select a specific model through OmniRoute?

Run omniroute models list and copy an available identifier into ANTHROPIC_MODEL. Alternatively, run omniroute setup-claude and launch one of the generated profiles to avoid ambiguous or unsupported model names.

Why do authentication failures occur even when OmniRoute is running?

A reachable server does not guarantee that the supplied key or provider is valid. Create a fresh client key, send it through the correct authentication variable, test the provider with omniroute providers test, and make sure the Claude Code process was restarted after the change.