Skip to main content

Basic Configuration

Learn how to configure Claude Code Router to suit your needs.

Configuration File Location​

The configuration file is located at:

~/.claude-code-router/config.json

Configuration Structure​

Providers​

Configure LLM providers to route requests to:

{
  "Providers": [
    {
      "NAME": "deepseek",
      "HOST": "https://api.deepseek.com",
      "APIKEY": "your-api-key",
      "MODELS": ["deepseek-chat", "deepseek-coder"]
    },
    {
      "NAME": "groq",
      "HOST": "https://api.groq.com/openai/v1",
      "APIKEY": "your-groq-api-key",
      "MODELS": ["llama-3.3-70b-versatile"]
    }
  ]
}

Router​

Configure which model to use by default:

{
  "Router": {
    "default": "deepseek,deepseek-chat"
  }
}

Format: {provider-name},{model-name}

Transformers​

Apply transformations to requests/responses:

{
  "transformers": [
    {
      "name": "anthropic",
      "providers": ["deepseek", "groq"]
    }
  ]
}

Environment Variables​

Use environment variables in your configuration:

{
  "Providers": [
    {
      "NAME": "deepseek",
      "HOST": "https://api.deepseek.com",
      "APIKEY": "$DEEPSEEK_API_KEY"
    }
  ]
}

Both $VAR_NAME and ${VAR_NAME} syntax are supported.

Proxy​

  • PROXY_URL (optional): HTTP(S) proxy used for outbound provider requests, for example "PROXY_URL": "http://127.0.0.1:7890".
  • Requests to loopback addresses (localhost, 127.0.0.1, ::1) always bypass the proxy.
  • Hosts listed in the process environment variables NO_PROXY / no_proxy also bypass the proxy. The list is comma-separated and supports bare hosts, .domain / *.domain suffixes, CIDR ranges, and optional :port entries.

Example:

export NO_PROXY="api.anthropic.com,.internal,10.0.0.0/8,localhost"

Models API ID output​

MODEL_ID_OUTPUT controls only the IDs returned by GET /v1/models, /models, and GET /v1/models/{id}:

{
  "MODEL_ID_OUTPUT": "masked"
}
  • "literal" (default): emit canonical provider,model IDs.
  • "masked": emit otherwise-filtered IDs as reversible claude-<lowercase UTF-8 hex> aliases.

Inbound requests always accept both canonical and masked IDs regardless of this setting.

Readable reasoning summaries​

Hosts such as OpenAI Responses / OpenCode Zen only return readable thinking when reasoning.summary is set. Chat Completions clients often send reasoning_effort alone. Opt in globally:

{
  "REASONING_AUTO_SUMMARY": true
}
  • true / "detailed" → inject reasoning.summary: "detailed"
  • "auto" / "concise" → inject that level instead
  • Per provider: "Providers": [{ "name": "…", "reasoningSummary": "detailed" }]
  • Explicit client reasoning.summary (including "none") always wins

This applies after Unified normalization for every client protocol (Chat Completions, Responses, Anthropic Messages) and every destination (Responses, Codex, Anthropic, Gemini, …).

Hosted web search cap​

Responses ({type: "web_search"}) and Chat Completions (web_search_options) clients have no per-request limit on hosted searches, and every search routed to Anthropic is billed. Cap the searches per request on the tool CCR builds for them:

{
  "WEB_SEARCH_MAX_USES": 3
}
  • Unset (default): no cap, as on OpenAI's and Anthropic's own APIs.
  • Applies to Anthropic destinations. Anthropic Messages clients keep the max_uses on their own web_search_* tool.
  • Destinations that cannot run a hosted search (plain Chat Completions providers) never receive the search tool; the request proceeds without it.

Complete Example​

{
  "port": 8080,
  "Providers": [
    {
      "NAME": "deepseek",
      "HOST": "https://api.deepseek.com",
      "APIKEY": "$DEEPSEEK_API_KEY",
      "MODELS": ["deepseek-chat", "deepseek-coder"],
      "transformers": ["anthropic"]
    },
    {
      "NAME": "groq",
      "HOST": "https://api.groq.com/openai/v1",
      "APIKEY": "$GROQ_API_KEY",
      "MODELS": ["llama-3.3-70b-versatile"],
      "transformers": ["anthropic"]
    }
  ],
  "Router": {
    "default": "deepseek,deepseek-chat",
    "longContextThreshold": 100000,
    "background": "groq,llama-3.3-70b-versatile"
  },
  "transformers": [
    {
      "name": "anthropic",
      "providers": ["deepseek", "groq"]
    }
  ]
}

Editing Configuration​

Use the CLI to edit the configuration:

ccr config edit

This will open the configuration file in your default editor.

Reloading Configuration​

After editing the configuration, restart the router:

ccr restart

Next Steps​