Integration Guide

Claude Code

Claude Code v2.x speaks the Anthropic Messages API. Point it at CodeRouter's /api/v1 base and use auto as the model.

Quickest setup — env vars

export ANTHROPIC_BASE_URL=https://www.coderouter.io/api/v1
export ANTHROPIC_AUTH_TOKEN=cr_YOUR_KEY_HERE
export ANTHROPIC_MODEL=auto
export ANTHROPIC_DEFAULT_OPUS_MODEL=auto
export ANTHROPIC_DEFAULT_SONNET_MODEL=auto
export ANTHROPIC_DEFAULT_HAIKU_MODEL=auto

# v2.x experimental beta features can break third-party gateways.
# This env disables them; harmless to leave on permanently.
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

claude

Persistent — ~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://www.coderouter.io/api/v1",
    "ANTHROPIC_AUTH_TOKEN": "cr_YOUR_KEY_HERE",
    "ANTHROPIC_MODEL": "auto",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "auto",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "auto",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "auto",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Verify it's routing through us

After launch, the Claude Code header should show API Usage Billing — not Claude Max. If you still see Claude Max, your existing OAuth session is winning over the env vars:

claude logout       # clear OAuth session
# then re-launch with the env vars set

Cursor

Cursor whitelists model names by string — you must add auto as a custom model before it appears in the picker. Setup is UI-only, no env vars.

1. Open Cursor, press Cmd+Shift+P (or Ctrl+Shift+P) → type "Cursor Settings"
2. Click Models in the left sidebar
3. Find the OpenAI API Key section, toggle "Override OpenAI Base URL" ON, paste:
   • URL: https://www.coderouter.io/api/v1
   • Key: cr_YOUR_KEY_HERE
4. Click Verify — must show ✓ green
5. Scroll up to Models, click + Add custom model, type auto
6. Tick the auto checkbox to enable it
7. In the chat model dropdown (top right of chat), pick auto

Aider

Aider has a hardcoded model whitelist. The openai/ prefix bypasses the validator and routes through whatever endpoint OPENAI_API_BASE points to.

Env vars + CLI

export OPENAI_API_BASE=https://www.coderouter.io/api/v1
export OPENAI_API_KEY=cr_YOUR_KEY_HERE

# Single-model mode
aider --model openai/auto

# Architect mode — both planner + editor route through CodeRouter
# (phase detector picks Opus for planning, DeepSeek for diff apply)
aider --model openai/auto --architect

Persistent — ~/.aider.conf.yml

model: openai/auto
openai-api-base: https://www.coderouter.io/api/v1
openai-api-key: cr_YOUR_KEY_HERE
# Optional: pin editor model for architect mode
# editor-model: openai/deepseek-chat

Cline

Cline (formerly Claude Dev) supports custom OpenAI-compatible endpoints out of the box. Configure via the extension settings panel:

1. VS Code → install Cline extension
2. Open Cline panel → click ⚙ Settings icon
3. API Provider: OpenAI Compatible
4. Base URL: https://www.coderouter.io/api/v1
5. API Key: cr_YOUR_KEY_HERE
6. Model ID: auto

Or via settings.json

{
  "cline.apiProvider": "openai",
  "cline.openAiBaseUrl": "https://www.coderouter.io/api/v1",
  "cline.openAiApiKey": "cr_YOUR_KEY_HERE",
  "cline.openAiModelId": "auto"
}

Continue.dev

Continue uses ~/.continue/config.json for provider config. Add two entries: one for chat (using auto) and one for tab autocomplete (pinned to a fast model).

{
  "models": [
    {
      "title": "CodeRouter (auto)",
      "provider": "openai",
      "model": "auto",
      "apiBase": "https://www.coderouter.io/api/v1",
      "apiKey": "cr_YOUR_KEY_HERE"
    }
  ],
  "tabAutocompleteModel": {
    "title": "CodeRouter Tab",
    "provider": "openai",
    "model": "gpt-5-mini",
    "apiBase": "https://www.coderouter.io/api/v1",
    "apiKey": "cr_YOUR_KEY_HERE"
  }
}

Windsurf

Windsurf supports custom OpenAI-compatible providers via Settings → Cascade → Custom Models. Same pattern as Cursor: add auto as a custom model first, then select it.

1. Windsurf → Settings → Cascade
2. Provider: Custom OpenAI
3. Base URL: https://www.coderouter.io/api/v1
4. API Key: cr_YOUR_KEY_HERE
5. Custom Models → add auto
6. Active model → select auto

OpenClaw

OpenClaw uses ~/.openclaw/openclaw.json for provider configuration. The fastest setup uses our auto-detect script:

One-line setup script

curl -fsSL https://www.coderouter.io/setup.sh | bash -s -- cr_YOUR_KEY_HERE

Manual — ~/.openclaw/openclaw.json

{
  "models": {
    "providers": {
      "coderouter": {
        "baseUrl": "https://www.coderouter.io/api/v1",
        "apiKey": "cr_YOUR_KEY_HERE",
        "api": "openai-completions",
        "models": [{ "id": "auto", "name": "CodeRouter Auto" }]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "coderouter/auto" }
    }
  }
}

GitHub Copilot

GitHub Copilot doesn't support custom endpoints natively. The proven pattern is to run LiteLLM as a local proxy that translates Copilot's requests into our OpenAI-compatible format.

1. Install LiteLLM: pip install "litellm[proxy]"
2. Create a config pointing LiteLLM at CodeRouter (single openai-compatible model named auto)
3. Run litellm --config config.yaml --port 4000
4. Point Copilot at http://localhost:4000 via VSCode setting github.copilot.advanced.debug.overrideProxyUrl

Detailed walkthrough in our blog: Cut Copilot bills with CodeRouter.

OpenAI SDK (Python / Node / Go)

Just override base_url and api_key. Set model="auto" to enable phase routing.

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://www.coderouter.io/api/v1",
    api_key="cr_YOUR_KEY_HERE",
)
resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Refactor this function"}],
)
print(resp.choices[0].message.content)
print(resp._clawrouters)
# {request_id, model_used, task_type, complexity, cost, ...}

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://www.coderouter.io/api/v1",
  apiKey: process.env.CODEROUTER_KEY,
});

const resp = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Write a Python quicksort" }],
});
console.log(resp.choices[0].message.content);

Anthropic SDK

If your code is already using @anthropic-ai/sdk or anthropic (Python), you can point it at our endpoint and we'll route via the /v1/messages protocol.

Python

from anthropic import Anthropic

client = Anthropic(
    base_url="https://www.coderouter.io/api/v1",
    auth_token="cr_YOUR_KEY_HERE",  # NOT api_key — use auth_token for third-party gateways
)
msg = client.messages.create(
    model="auto",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(msg.content[0].text)

Verify your setup

Use the X-Dry-Run: true header to get a routing decision back without actually invoking a model:

curl https://www.coderouter.io/api/v1/chat/completions \
  -H "Authorization: Bearer cr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Dry-Run: true" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Refactor this Python function"}]}'

Response should include the chosen model, detected phase, and cost estimate:

{
  "dryRun": true,
  "routing": {
    "taskType": "coding",
    "complexity": "low",
    "modelSelected": "deepseek-chat",
    "strategy": "balanced",
    "fallbackChain": ["claude-sonnet-4.6", "gemini-3-pro"],
    "estimatedCost": { "selected": "$0.0002", "ifOpus": "$0.0377", "savings": "99.4%" }
  }
}

For a real call (small request, real tokens):

curl https://www.coderouter.io/api/v1/chat/completions \
  -H "Authorization: Bearer cr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'

Response headers carry the routing trace — X-CodeRouter-Model, X-CodeRouter-Phase, X-CodeRouter-Cost, X-CodeRouter-Savings — so you can confirm phase routing is active even from a black-box agent.

Troubleshooting

"There's an issue with the selected model (auto)"

Claude Code only. Three causes (in order of likelihood):

1. Using ANTHROPIC_API_KEY instead of ANTHROPIC_AUTH_TOKEN — switch env var name and check the badge reads API Usage Billing, not Claude Max.
2. Old Claude Code v2.1.x with new beta features — add CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 to env.
3. Wrong base URL shape causing double /v1 on requests. We accept both https://www.coderouter.io and https://www.coderouter.io/api/v1 via internal rewrites.

"Free plan requires your own provider API keys" (HTTP 403)

Free trial requires BYOK — either upgrade to a paid plan at /pricing, or add your own provider key at /dashboard/models.

"Rate limit exceeded" (HTTP 429)

Per-key + per-user rate limits. Defaults: Free 60, Starter 100, Solo 200, Pro 600, Studio 1200, Team 2400 req/min. Check X-RateLimit-Reset response header for retry timing.

"Invalid max_tokens value" from DeepSeek

Should not happen — we clamp max_tokens to 8192 (DeepSeek's cap) before forwarding. If you hit this, your client is sending a value our clamp doesn't cover; report it via issues.

"Unable to download the file" from Anthropic

Sending an image as a data URL. Should be auto-converted to base64 by our Anthropic adapter; if you still hit this, the image MIME type is unrecognized (only image/png, image/jpeg, image/gif, image/webp are supported by Anthropic).

Anything else

Email support@coderouter.io with:

• The exact error message + HTTP status code
• Your agent name + version
• The full curl reproduction (omit your cr_ key)