Route Claude Code Through a Local Model Proxy

The salvage value in Claude Model Proxy is not the long provider list. The useful idea is a local boundary where a Claude Code user can pin aliases, route real model names, inspect status, and test provider behavior without rewriting the client setup for every experiment.

That makes the seed worth saving, but only if the article refuses the easy pitch. A proxy does not make every provider a drop-in Claude Code model. It can make routing observable. It can keep Claude aliases stable while the upstream changes. It can also hide compatibility breaks if the reader treats a text adapter as full tool-use support.

Why this seed should be rescued

The original article failed as a magazine piece because it was too close to a README summary. The source itself is still strong: a local Node proxy, default model routes, Claude semantic aliases, a Claude Code environment file, a Claude Desktop MCPB extension, a read-only status tool, a health endpoint, and tests that prove alias rewriting and provider routing.

The editorial angle is a boundary guide. Use the project when you need controlled routing experiments. Do not use it as a blanket claim that DeepSeek, Kimi, GLM, MiMo, OpenAI, Gemini, Qwen, and Anthropic will behave the same under Claude Code.

Start with one route, not a provider zoo

The documented server path is small enough to audit:

cp .env.example .env
# add one provider key first
set -a
. ./.env
set +a
npm start

The first run should use one Anthropic-format provider such as DeepSeek, Moonshot/Kimi, GLM, Xiaomi MiMo, or Anthropic. That keeps the first test focused on routing, keys, and model names. Once curl http://127.0.0.1:8787/healthz shows the provider has an API key and the expected route, run one harmless Claude Code task with a real model name. Only add a second provider after the first path is observable.

Keep client keys and provider keys separate

The Claude Code example is easy to misread. The client uses ANTHROPIC_BASE_URL=http://127.0.0.1:8787 and a dummy ANTHROPIC_API_KEY. That placeholder only satisfies the Claude Code client. Real provider keys live in the proxy .env, MCPB install settings, or the LaunchAgent environment file.

That distinction should become an adoption rule. If a test fails, do not rotate the dummy client key. Check the proxy environment, then check /healthz or model_proxy_status. If a team copies this setup, document where provider keys are allowed to live. Otherwise a local experiment turns into scattered secrets across shell profiles, extension config, and launchd files.

Treat Claude aliases as contracts

The proxy separates real model names from Claude semantic aliases. By default, claude-haiku maps to deepseek-v4-flash, while claude-sonnet and claude-opus map to deepseek-v4-pro. proxy.mjs merges MODEL_MAP, CLAUDE_MODEL_MAP, MODEL_ALIASES, and MODEL_ROUTES, then rewrites the request model upstream and can rewrite the response model back to the client-facing alias.

That is useful, but it is also where bad experiments become confusing. If claude-sonnet points to a non-Claude upstream this week and a different upstream next week, logs and review notes need to record the map. Put the chosen alias map in the project runbook or AGENTS.md trial notes, then test explicit real model names before relying on semantic aliases in subagents.

Claude Code setup should be visible

The .env.claude-code.example file gives the client side of the contract:

ANTHROPIC_BASE_URL=http://127.0.0.1:8787
ANTHROPIC_API_KEY=dummy-claude-model-proxy
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus
CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku
ANTHROPIC_MODEL=sonnet

For a Codex-style evaluation, do not start with a production task. Source the file in one terminal, run claude --model deepseek-v4-pro or the chosen real model, and ask for a short non-destructive answer. Then inspect the proxy log or status endpoint. The test passes only when the requested model, upstream route, and returned model name match the map you intended.

Tool-use compatibility is the hard boundary

This is the most important part of the article. The README says Claude Code works best with Anthropic Messages-compatible upstreams because tool-use payloads pass through as-is. The same source says OpenAI, Gemini, and Qwen routes use a basic Chat Completions adapter for text, image content, and streaming text deltas; they are not a full Claude Code tool-use compatibility layer.

That line decides whether the tool is a good fit. A text-only prompt can pass while a real coding agent fails later on tool calls, stop reasons, or provider-specific payload fields. For Claude Code, test a small task that exercises tool use before any serious adoption. If OpenAI-compatible routes are in the matrix, label them as text/image adapter tests unless your own run proves the required tool path.

Use healthz and model_proxy_status before debugging Claude

The proxy exposes GET /healthz, and the MCPB server exposes model_proxy_status. Both report local listener state and mappings. The status tool also returns provider hasApiKey flags, external, localUrl, modelMap, claudeModelMap, modelAliases, modelRoutes, and rewriteResponses.

That gives the reader a concrete debugging order. First check whether the proxy is listening on 127.0.0.1:8787. Next check whether the provider key flag is true. Then check whether the requested model resolves to the expected provider. Only after those pass should you blame Claude Code, Claude Desktop, or the provider. This order is what turns a local proxy from a mystery box into an inspectable test rig.

Desktop extension is useful for status, not magic

The MCPB path is source-backed: npm run build:mcpb creates dist/claude-model-proxy-0.1.1.mcpb, and the manifest declares a Node server at server/index.mjs plus the read-only model_proxy_status tool. In Claude Desktop, the gateway URL is still http://127.0.0.1:8787, and the Gateway API key is still a non-empty placeholder.

The extension improves setup because it keeps proxy settings and status checks near Claude Desktop. It does not remove the need to decide which provider keys are installed or which aliases map to which real models. If the tool is unavailable in the first new chat and works on retry, the README names that as a client tool-list timing issue, not proof that the proxy failed.

Use LaunchAgent only after the manual path works

The README describes a startup race: Claude Desktop can probe the gateway before the MCPB process has finished starting, causing a local reachability warning. The suggested fix is npm run launch-agent:install, then putting provider keys in ~/.claude-model-proxy.env, restarting the agent with launchctl kickstart -k gui/$(id -u)/local.claude-model-proxy, and checking /healthz.

That is an operations step, not the first install step. Use npm start or ./start.sh foreground while validating provider routes. Move to LaunchAgent only after the map is correct, logs are readable, and the team knows that provider keys now live in a launchd environment file.

A small adoption checklist

A strong trial has five checks. First, choose one provider and one real model. Second, start the proxy and verify curl http://127.0.0.1:8787/healthz. Third, source .env.claude-code in a fresh terminal and run Claude Code with the real model name. Fourth, run the same test through claude-sonnet or another semantic alias and verify that response rewriting behaves as expected. Fifth, run one tiny tool-use task before trusting the route for coding work.

Keep the output. Save the alias map, the health JSON, the command used to start Claude Code, and the result of the tool-use task. If any of those are missing, the trial is not ready for a published recommendation inside an AGENTS.md workflow.

When to skip the proxy

Skip it when the goal is simply to use one known Anthropic model. Direct Claude Code configuration has fewer moving parts. Skip it when the organization needs central key governance, audited shared routing, or policy enforcement. Skip OpenAI-compatible routes for Claude Code tasks that depend on tool-use behavior unless the exact path has been tested.

Use the proxy when a developer wants a local, reversible way to compare routing behavior, keep semantic aliases stable, or connect Claude Desktop Gateway and Claude Code to a small provider matrix. That is narrower than the original headline implied, but much more useful.

Save Claude Model Proxy as a local routing guide, not as a provider-switching promise. It is useful when /healthz, model_proxy_status, explicit model names, and a tiny tool-use test prove the route; it is risky when aliases hide provider differences or when OpenAI-compatible adapters are treated as full Claude Code compatibility.

Practical takeaway

Start one Anthropic-format provider, run curl http://127.0.0.1:8787/healthz, source .env.claude-code, test claude --model <real-model>, then test the Claude alias. Do not use the route for real coding work until a small tool-use task proves the same path.