Add Custom Models to Claude Code and Codex (2026 Guide)

To add custom models to Claude Code, point it at an endpoint that speaks the Anthropic Messages format with ANTHROPIC_BASE_URL and a key, then pick the model with ANTHROPIC_MODEL or /model. To add a custom model provider to Codex, define it under [model_providers.<id>] in a Codex config file, and make sure the endpoint speaks the OpenAI Responses API, because that is the only format Codex supports. A plain OpenAI Chat Completions endpoint works with neither agent on its own. Before you switch, check three things: how the agent will size the model's context window, whose account gets billed, and which agent features stop working away from the vendor's own models.

This guide covers the manual setup for both agents, the traps in each, and a one-line install for SolCard Inference, SolCard's own API, which you can top up with crypto.

This is the question that decides whether a provider works at all. "OpenAI-compatible" usually means Chat Completions, and neither agent speaks it.

Anthropic's gateway guide lists the formats Claude Code can talk to: Anthropic Messages, Amazon Bedrock InvokeModel and Google Cloud's Agent Platform rawPredict. A third-party provider normally means the first one.

The Codex reference is blunter about its side. For wire_api it says: "responses is the only supported value, and it is the default when omitted."

So the first check on any provider is its docs. If it only offers /v1/chat/completions, you need a translating proxy in between, or a different provider.

Not by Anthropic. Its LLM gateway page says Anthropic "doesn't endorse, maintain, or audit third-party gateway products, and doesn't support routing Claude Code to non-Claude models through any gateway."

That doesn't stop it from working. It means that when something breaks, the fix comes from the model provider, not from Anthropic. Providers say the same thing in their own way. OpenRouter's Claude Code guide says the setup "is only guaranteed to work with the Anthropic first-party provider" and "may not work correctly with other providers."

Codex is more open by design. Its advanced config page describes a model provider as the definition of "how Codex connects to a model (base URL, wire API, authentication, and optional HTTP headers)", and custom providers are a documented feature.

Here is the manual route, using any provider with an Anthropic Messages endpoint. The examples use SolCard Inference's values; swap in your provider's base URL, key and model names.

You need two things from the provider's docs:

• The base URL without /v1/messages. Claude Code appends the path itself. SolCard Inference's quickstart gives https://api.solcardinference.ai for Anthropic clients, with no /v1. OpenRouter's is https://openrouter.ai/api. DeepSeek's Anthropic API page gives https://api.deepseek.com/anthropic.
• Which header carries the key. Per Anthropic's connect guide, ANTHROPIC_AUTH_TOKEN sends Authorization: Bearer, and ANTHROPIC_API_KEY sends x-api-key. "If you weren't told which kind, use ANTHROPIC_AUTH_TOKEN." SolCard Inference's quickstart sends its key as a Bearer token.

Anthropic's guide recommends a one-token request before you open Claude Code, so a failure points at the endpoint and not your config:

export ANTHROPIC_BASE_URL=https://api.solcardinference.ai
export ANTHROPIC_AUTH_TOKEN=sk-si-...

curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "solcard-inference-fast", "max_tokens": 16, "messages": [{"role": "user", "content": "Say hi."}]}'

A JSON reply with a content field means the URL and key work. A 401 means the key was rejected: if you guessed the header, switch to the other variable and try again.

Claude Code doesn't only call the model you chat with. Per the model configuration docs, ANTHROPIC_DEFAULT_HAIKU_MODEL also covers "background functionality", and CLAUDE_CODE_SUBAGENT_MODEL sets the default for subagents. If those still point at Claude model names, a provider that doesn't serve them returns errors in the middle of a session.

So set them all to models your provider serves:

export ANTHROPIC_MODEL="solcard-inference-large[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="solcard-inference-large[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="solcard-inference-fast[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="solcard-inference-fast[1m]"
export CLAUDE_CODE_SUBAGENT_MODEL="solcard-inference-fast[1m]"
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=32768

The [1m] suffix and the output cap are explained in the next section.

Exports in your shell profile apply to every Claude Code session. If you also use Claude Code on a Claude subscription, wrap the variables in a separate launcher instead, so claude stays on your plan and claude-si uses the custom models:

# ~/.zshrc or ~/.bashrc
claude-si() {
  ANTHROPIC_BASE_URL=https://api.solcardinference.ai \
  ANTHROPIC_AUTH_TOKEN="$SOLCARD_INFERENCE_KEY" \
  ANTHROPIC_MODEL="solcard-inference-large[1m]" \
  ANTHROPIC_DEFAULT_OPUS_MODEL="solcard-inference-large[1m]" \
  ANTHROPIC_DEFAULT_SONNET_MODEL="solcard-inference-fast[1m]" \
  ANTHROPIC_DEFAULT_HAIKU_MODEL="solcard-inference-fast[1m]" \
  CLAUDE_CODE_SUBAGENT_MODEL="solcard-inference-fast[1m]" \
  CLAUDE_CODE_MAX_OUTPUT_TOKENS=32768 \
  claude "$@"
}

Keep the key in an environment variable or a secrets manager rather than pasting it into the function. Anthropic's guide also warns: "Don't put the credential in a project's .claude/settings.json. That file is committed and shared with everyone who clones the repository."

Start the session and run /status. The Anthropic base URL line should show your provider, and an Auth token line should name the variable you set. If the line is missing, the variable didn't reach the session.

Custom model names don't appear in the picker by default. Two documented ways to add them:

• ANTHROPIC_CUSTOM_MODEL_OPTION adds one entry "without replacing the built-in aliases", per the model configuration docs. Claude Code "skips validation for the model ID set in ANTHROPIC_CUSTOM_MODEL_OPTION, so you can use any string your API endpoint accepts."
• CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 makes Claude Code query the endpoint's /v1/models list at startup and add what it returns. It only works if the provider serves that endpoint at the base URL without a redirect.

These are the problems that don't show up in a curl test.

Per the model configuration docs, when Claude Code doesn't recognize a model ID, "it can't tell the model's context window and assumes 200K tokens." It then compacts the conversation at 200K, even if the model can hold far more.

You have two fixes:

• For a 1M-token model, append [1m] to the ID where you set it. Claude Code "strips the suffix before sending the model ID to your provider."
• For any other window, set CLAUDE_CODE_MAX_CONTEXT_TOKENS to the real size. For an unrecognized ID that doesn't start with claude-, the docs say "the variable takes effect on its own."

Check each model's window on the provider's models page. On SolCard Inference, solcard-inference-large has 1M tokens and solcard-inference-fast about 1M, so [1m] fits both. solcard-inference-base has 262k, so use CLAUDE_CODE_MAX_CONTEXT_TOKENS for it instead.

If the provider caps output below what Claude Code asks for, long edits fail. Anthropic's troubleshooting table says to "set CLAUDE_CODE_MAX_OUTPUT_TOKENS below the gateway model's output limit." SolCard Inference caps output at 32,768 tokens per request, which is why the example above sets that value.

Anthropic's gateway page says that while a gateway credential is active, "requests carry that credential in place of a developer's claude.ai subscription login, and the subscription's usage limits don't apply to them." The traffic is billed to whoever owns that credential, so your Claude plan doesn't pay for it.

That is the point if you want to stop hitting plan limits, and a surprise if you don't. Run /status to see which credential is active.

Per the connect guide, Remote Control and voice dictation "are unavailable while ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or an apiKeyHelper is active." Remote Control is also off while ANTHROPIC_BASE_URL points at a non-Anthropic host.

Some providers rewrite names. DeepSeek's Anthropic API page says names starting with claude-opus map to deepseek-v4-pro, claude-sonnet and claude-haiku map to deepseek-flash, and unsupported names that don't start with "claude" return a 400 error. Read your provider's mapping rules before you pin names.

Codex keeps its settings in config.toml under CODEX_HOME, which "defaults to ~/.codex", per the advanced config page. A provider needs a name, a base URL, the variable that holds the key, and the wire API.

Profiles layer a second file on top of your main config. Per the same page, --profile "loads ~/.codex/config.toml and then overlays ~/.codex/profile-name.config.toml." In Codex 0.134.0 and later, profiles live in those separate files, not in [profiles.<name>] tables.

Create ~/.codex/solcard.config.toml:

model = "solcard-inference-large"
model_provider = "solcard"

[model_providers.solcard]
name = "SolCard Inference"
base_url = "https://api.solcardinference.ai/v1"
env_key = "SOLCARD_INFERENCE_KEY"
wire_api = "responses"

Then run it:

export SOLCARD_INFERENCE_KEY=sk-si-...
codex --profile solcard

Plain codex keeps using your main config. Put the same block in config.toml itself only if you want the custom provider to be the default.

• The provider ID can't be a built-in one. "Custom providers can't reuse the reserved built-in provider IDs: openai, ollama, and lmstudio."
• Check whether the base URL includes /v1. It can differ from the Claude Code value: SolCard Inference's OpenAI base URL is https://api.solcardinference.ai/v1, while its Anthropic one has no /v1.
• The endpoint must support Responses. Check the provider's API reference for a Responses page, not just Chat Completions.
• query_params and http_headers add extra query parameters or static headers if a provider needs them, per the config reference.

If you'd rather not edit config files, SolCard Inference has an install for both agents. Paste this into Claude Code or Codex:

Add SolCard Inference to my models: solcardinference.ai/install

The agent adds SolCard Inference's models next to your own Claude or ChatGPT models. You need an API key first: sign up at app.solcardinference.ai with an email or a Solana wallet, then create one on the API keys page. Keys start with sk-si- and are shown once, so copy it before you close the dialog. The coding agents guide describes what the install sets up.

As with any prompt that tells an agent to fetch and follow a URL, read the page yourself before you paste it.

From SolCard Inference's models page:

All three are text only, with no image, audio or file input. Output is capped at 32,768 tokens per request. The models are open-weight with refusal training removed, which SolCard frames for security research, malware analysis for defense, red-teaming and synthetic training data.

One prepaid USD balance covers chat, every key and every model, and there is no card on file. On the dashboard's Top up page you send crypto to the deposit address shown (the site lists SOL, USDC, ETH, BTC and more, on 9+ networks) or pay straight from a SolCard card balance. Any amount works, and the balance never expires. New email sign-ups may get $1 of free credit for 30 days; abuse checks apply, and wallet sign-ups get none.

Coding agents resend the same files and instructions on every turn, so most input tokens hit the cache. Here is one hypothetical heavy day: 30 million input tokens, 27 million of them cached, and 1 million output tokens. Prices are from SolCard Inference's pricing page, in USD per 1 million tokens.

Web search adds $0.008 per search. Your own cache hit rate decides most of the bill, so check the usage page after a day of real work before you commit to a plan.

For steady use there are plans that renew from the same balance: Starter at $20 a month, Pro at $100 (5x Starter usage) and Max at $200 (10x Starter usage). Starter and Pro give 20% more usage than pay as you go, and Max 25% more. Limits reset every 5 hours and every week, unused plan usage doesn't roll over, and API keys spend credits first, then the plan. Rate limits are 120, 300 and 600 requests a minute.

• You want Claude models, just paid differently. Don't add a custom provider. Pay for a Claude plan or Console credits instead: see how to buy Claude with crypto or the Anthropic API guide.
• You want other models inside Claude Code. Use a provider with an Anthropic Messages endpoint, pin every model slot, fix the context window, and accept that Anthropic doesn't support the setup.
• You want other models inside Codex. Use a provider with a Responses endpoint and a profile, so your default Codex config stays as it is.
• You want both agents on one balance you top up with crypto. SolCard Inference speaks Anthropic Messages, OpenAI Responses and Chat Completions behind one key format, and the one-line install covers both agents.

Two limits to weigh on that last option. SolCard Inference's models are text only, so screenshots and PDFs need another provider. And they are SolCard's own models, not Claude or GPT, so test them on your real tasks before you move a whole workflow.

If you stay on Anthropic or OpenAI, both bill by card. SolCard's standard Virtual and Platinum cards struggle at both checkouts in our data, so SolCard built Virtual for AI & Ad Spend for these merchants. For the full picture across providers, see how to pay for an LLM API with crypto. If you're loading a card for everyday spending too, note that the standard Virtual card charges a 5% top-up fee and Platinum 0%, per SolCard fees.

Yes, through any endpoint that speaks the Anthropic Messages format, set with ANTHROPIC_BASE_URL. Anthropic doesn't support routing Claude Code to non-Claude models, so features may break and support comes from the provider.

Not directly if the API only offers Chat Completions. Claude Code sends Anthropic Messages requests, so the provider needs an Anthropic-format endpoint or a proxy that translates. SolCard Inference, OpenRouter and DeepSeek each publish an Anthropic-format base URL.

Add a [model_providers.<id>] block with name, base_url, env_key and wire_api = "responses", then set model and model_provider. Put it in a profile file such as ~/.codex/solcard.config.toml and run codex --profile solcard to keep your default config unchanged.

No. The Codex config reference says responses is the only supported wire_api value. Use a provider with a Responses endpoint.

Claude Code assumes a 200K window for model IDs it doesn't recognize. Append [1m] for a 1M-token model, or set CLAUDE_CODE_MAX_CONTEXT_TOKENS to the model's real window.

No. While a provider credential is active, requests carry it instead of your claude.ai login, and the plan's usage limits don't apply. The provider bills you for those requests.

Unset the variables, or use a separate launcher like claude-si so your normal claude command never had them. Run /status to confirm the base URL line is gone.

Adding custom models to a coding agent comes down to the API format. Claude Code needs Anthropic Messages, Codex needs OpenAI Responses, and neither works with a Chat Completions-only provider. Pin every model slot, tell Claude Code the real context window, and keep the setup in a launcher or profile so your default agent stays on your own plan. If you want one balance for both agents that you top up with crypto, SolCard Inference's one-line install handles the config, and SolCard covers the card side when a vendor only takes cards.

• Other LLM gateways, Connect Claude Code to an LLM gateway, Gateway compatibility guide and Model configuration, Claude Code docs
• Advanced configuration and Configuration reference, Codex docs
• Claude Code integration, OpenRouter
• Anthropic API, DeepSeek API docs
• solcardinference.ai, Quickstart, Claude Code and Codex, Models and Pricing, SolCard Inference