Connecting an AI Coding Assistant to Alternative Models: A Complete Router Configuration Guide

    This guide explains how to route an AI coding assistant's requests through a local proxy to alternative language models. It covers how the router works, the prerequisites, installation, provider and routing configuration, startup, common troubleshooting, and security considerations.

    Introduction: Why Model Routing Matters

    Large language models are improving quickly, and developers increasingly want to choose the model that fits each task. Models differ in code understanding, multi-step reasoning, and long-context handling. Many AI coding tools, however, are tied by default to a specific model’s cloud service, which limits the options available to developers.

    A lightweight routing middleware layer solves this problem. It intercepts requests from the coding tool and forwards them to other compatible model services. The coding tool keeps its usual workflow, and the underlying model can be swapped flexibly. This approach lets developers use the models whose capabilities they prefer. It can also improve service availability and help control costs.

    How the Router Works

    The routing middleware is essentially a local proxy service. By default, the coding tool sends requests to the official model endpoint. After you configure the router, the tool sends requests to a proxy port on your own machine instead. The proxy receives each request, applies predefined routing rules (such as a default model, a reasoning model, or a long-context model), rewrites the request, and forwards it to the target model service’s standard interface. The process is transparent to the tool, so developers do not see the forwarding details.

    This approach is general. Any model service that offers an API format compatible with the original interface, such as the OpenAI-compatible format, can be connected this way. Most major model providers already offer compatible interfaces, which makes this routing approach practical.

    Prerequisites

    Before you begin, confirm that the following are in place:

    1. The AI coding tool
    Install the AI coding tool you plan to use. Installation usually requires only a global install command. Once installed, you can check the version to confirm the installation succeeded.

    2. Node.js runtime
    The router is built on Node.js. Use version 18 or later. Newer versions offer better ES Module support and performance. Check your current version with node -v.

    3. Model service API key
    Register an account on the target model provider’s developer platform and create an API key. For example, if you use a cloud provider’s generative model service, log in to its AI Studio platform, open the API key management page, and generate a new key. Copy the key immediately after creating it, because it is shown only once.

    4. Network proxy (optional)
    If your network requires a proxy to reach the target model service, prepare the local proxy address and port. Common local proxy ports are 7897 and 7890, but the correct value depends on your proxy software’s settings.

    Step 1: Install the Router

    Run the following command in your terminal to install the router globally:

    1. npm install -g claude-code-router

    After installation, verify it:

    1. ccr --version

    If your system cannot find the command, check whether the npm global installation path is included in your system’s PATH environment variable.

    Step 2: Get a Model Service API Key

    Go to the target model provider’s developer console and complete these steps:

    1. Log in and open the API key management page.
    2. Click the button to create a new API key.
    3. Give the key a name that describes its purpose, then copy and save it after creation.

    Providers set different free quotas and rate limits. Read the relevant documentation to understand the call limits, so your requests do not fail after you exceed a quota.

    Step 3: Write the Router Configuration File

    The router’s configuration file is stored in a hidden folder in your home directory. Create and edit the file as follows:

    1. mkdir -p ~/.claude-code-router
    2. vim ~/.claude-code-router/config.json

    Basic configuration example:

    1. {
    2. "LOG": true,
    3. "CLAUDE_PATH": "/usr/local/bin/claude",
    4. "HOST": "127.0.0.1",
    5. "PORT": 3456,
    6. "APIKEY": "",
    7. "API_TIMEOUT_MS": 600000,
    8. "PROXY_URL": "http://127.0.0.1:7897",
    9. "Providers": [
    10. {
    11. "name": "gemini",
    12. "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
    13. "api_key": "YOUR_API_KEY",
    14. "models": ["gemini-2.5-flash", "gemini-2.5-pro"],
    15. "transformer": {
    16. "use": ["gemini"]
    17. }
    18. }
    19. ],
    20. "Router": {
    21. "default": "gemini,gemini-2.5-flash",
    22. "background": "gemini,gemini-2.5-flash",
    23. "think": "gemini,gemini-2.5-pro",
    24. "longContext": "gemini,gemini-2.5-pro",
    25. "webSearch": "gemini,gemini-2.5-flash"
    26. }
    27. }

    Key configuration fields:

    Field Description
    CLAUDE_PATH Full path to the coding tool’s executable. Run which claude to find it.
    HOST / PORT Address and port the router listens on. The default port is 3456 on the local machine.
    PROXY_URL Network proxy address. Leave it empty if you do not need a proxy.
    API_TIMEOUT_MS API request timeout. Set it to 600000 milliseconds (10 minutes) so long tasks are not interrupted.
    Providers Array of model providers. You can configure more than one.
    Router.default Model used for default routing.
    Router.think Model used for reasoning-intensive scenarios, suited to complex reasoning tasks.
    Router.longContext Model used for long-context scenarios, suited to large files or long conversations.
    Router.webSearch Model used for web search scenarios.

    Step 4: Start the Router Service

    After you finish editing the configuration file, start the router:

    1. ccr start

    When the service starts, the terminal shows the listening address and port. Check that the service is running with curl:

    1. curl http://127.0.0.1:3456/health

    A health check response indicates that the service is running normally.

    Step 5: Start the AI Coding Tool

    With the router running, start the coding tool so its requests go to the local router. You can do this in one of two ways.

    Option 1: Start through the router command

    1. ccr code

    This command sets the required environment variables and points requests to the local router port. We recommend this method.

    Option 2: Set the environment variable manually

    Add the following line to your shell configuration file:

    1. export ANTHROPIC_BASE_URL=http://127.0.0.1:3456

    Then launch the coding tool with its native command. This method suits setups where you want the configuration to persist.

    Advanced Configuration

    Redundant Multi-Provider Setup

    If you are concerned about the stability of a single provider, add several providers to the Providers array and order them by priority in your routing rules. When the first service becomes unavailable, switch manually or use a script to fail over to the next one.

    Model Selection Strategy

    Models differ noticeably in code generation performance. In general:

    • Lightweight models respond quickly and cost less. They suit tasks such as code completion and simple refactoring.
    • High-capability models have stronger reasoning. They suit complex algorithm design, architecture design, and changes across multiple files.

    Configure routing according to task type to balance speed and output quality.

    Proxy Configuration Notes

    When you use a proxy, keep these points in mind:

    1. Confirm that the proxy is running and that a firewall does not block its port.
    2. Some proxy software handles HTTPS traffic differently. Make sure the proxy supports the CONNECT method.
    3. If you use PAC mode instead of global mode, add the target service’s domain to the proxy rules.

    Troubleshooting

    Issue 1: The port is already in use

    Change the PORT value in the configuration file to another free port, such as 3457, and restart the router.

    Issue 2: Requests time out or fail to connect

    First check network connectivity:

    1. curl -I http://127.0.0.1:3456

    If the local port responds normally, test connectivity to the target model service. Confirm that your proxy settings and API key are correct.

    Issue 3: Authentication fails

    Check that the api_key field is correct, that the key has not expired, and that it has permission to call the model. Some providers issue separate keys for different models, so verify each one.

    Issue 4: The model name is not available

    Make sure the names in the models array exactly match the model identifiers the provider lists, including capitalization and hyphens. You can send a simple request to test which models are available.

    Security and Compliance

    1. Protect your keys: The configuration file contains sensitive credentials. Restrict file permissions and keep the file out of version control repositories.
    2. Local listening: The router binds to 127.0.0.1 by default, so only the local machine can reach it. Do not change the address to 0.0.0.0, because that exposes the service to other devices on your network.
    3. Data privacy: Code sent to a model service may contain confidential business information. Assess the compliance risk, and use a self-hosted model service where necessary.
    4. Usage monitoring: Set usage limits or alerts on your API keys to prevent unusual traffic from causing unexpected charges.

    Summary: When Model Routing Fits

    A routing middleware layer that connects alternative models offers three main benefits:

    Flexibility. Developers can choose the model best suited to each task instead of depending on the coding tool’s default binding.

    Cost control. Lightweight models can handle simple coding tasks, and advanced models can be reserved for complex ones. This helps control API spending without sacrificing quality.

    Service resilience. When one model service fails or throttles requests, you can quickly switch to a backup service and keep your development workflow running.

    This approach suits development teams with detailed requirements for model capabilities, and it also suits independent developers who want to compare how different models perform. Setup takes about ten minutes and gives you a flexible, extensible routing layer for your existing AI coding tool.