Claude Code Custom API Setup: Base URL, Keys, and Models (2026)

Claude Code is the command-line coding tool from Anthropic and connects to Anthropic's official API by default. In practice, many teams point it at a self-hosted or third-party gateway to address access stability, unified billing, and quota management. Connecting a custom API really comes down to changing three things: where requests go (the Base URL), what identity authenticates them (the key), and which model is called (the model name).

This article walks through a reusable setup process in the order of installation, environment variables, configuration files, model selection, connection verification, team rollout, and security. Commands target macOS and Linux; Windows differences are noted separately.

Note: Claude and Anthropic are trademarks of their respective owners. This article is a technical integration guide and implies no affiliation with those vendors. Claude Code changes quickly, so environment variables, configuration items, and menu names may shift between versions. Defer to claude --help, the official documentation, and the on-site integration guide.

1. Confirm three things before you connect

Claude Code speaks the Anthropic Messages protocol, not OpenAI's Chat Completions protocol. A custom API must therefore provide at least two things: an Anthropic-compatible /v1/messages endpoint, and model names that match what the gateway actually offers. A gateway that only exposes an OpenAI-compatible endpoint cannot be entered directly into Claude Code unless it also provides an Anthropic-compatible route.

Prepare three items before starting:

Base URL: the gateway root address, for example https://ai.zhongshangqihang.com. Whether it includes /v1 depends on the gateway implementation; follow its integration guide.
API key: create one in the console with a spending cap and expiration date. Do not test with a long-lived, uncapped key.
Model name: copy it from the console or pricing page rather than typing from memory. A single wrong character, capital letter, or hyphen can produce a model-not-found error.

If you do not have an account yet, start at the sign-up page and create a low-quota test key first.

2. Install Claude Code

Claude Code is usually distributed through npm, and other installation methods exist. The most common flow:

Confirm Node.js is installed. Use a maintained LTS release; check the official documentation for the current minimum version.
Run npm install -g @anthropic-ai/claude-code to install globally.
Run claude --version, confirm the command works, and note the version number.
Move into a test project directory, run claude, and complete first-run setup such as theme and directory trust.
If your team manages versions, pin the version and document it in the onboarding guide; validate upgrades in a test project first.

node --version
npm install -g @anthropic-ai/claude-code
claude --version
cd /path/to/your-project
claude

With a custom API you usually do not need to sign in to an Anthropic account, but whether login is skipped depends on the version and configuration. If you are still asked to log in, first check that the environment variables are active in the same shell that launches Claude Code.

3. Environment variables: BASE_URL and AUTH_TOKEN

Claude Code reads two common authentication variables:

ANTHROPIC_BASE_URL: the request root address.
ANTHROPIC_AUTH_TOKEN: sent as Authorization: Bearer, common for gateway access.
ANTHROPIC_API_KEY: sent as x-api-key, closer to Anthropic's native authentication.

Choose one. If the gateway authenticates with Bearer, use ANTHROPIC_AUTH_TOKEN; if it uses native authentication, use ANTHROPIC_API_KEY. When both are set, precedence can differ between versions, which easily produces a "correct key, still 401" situation. Keep only one.

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-key"
claude

Add the lines to ~/.zshrc or ~/.bashrc to make the configuration persist, then run source ~/.zshrc. In Windows PowerShell, $env:ANTHROPIC_BASE_URL="..." applies only to the current window; for persistence use the system environment variable interface or setx, then reopen the terminal.

Do not put exports in a project script and commit it. Once a key enters Git history, deleting the file does not delete the record.

4. settings.json: make the configuration permanent

Environment variables suit temporary switching; for long-term use, write the configuration into Claude Code's settings file. There are three common levels:

User level: ~/.claude/settings.json, applying to every project on the machine.
Project level: .claude/settings.json, which can be committed and is suitable for sharing non-sensitive settings.
Local project level: .claude/settings.local.json, not committed, suitable for personal overrides.

Example:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.zhongshangqihang.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key"
  },
  "model": "claude-sonnet-4-5"
}

Note that keys in settings.json are stored in plain text. That is acceptable on a personal machine, but not on shared machines, in CI, or in a code repository. Put only the Base URL and model name in project-level files and keep keys in environment variables or a secrets manager. Precedence generally runs from enterprise managed settings, command-line arguments, local project, project, and user settings, each overriding the previous one; check the current version's documentation.

5. Model selection: tier by task

Claude models usually come in three tiers, suited to different tasks:

Tier	Typical use	Trade-off
Opus	Complex refactoring, cross-file analysis, long-running agents	Stronger capability, usually higher cost, potentially slower
Sonnet	Everyday coding, bug fixes, code review	Balanced capability and cost, a good default
Haiku	Simple completion, formatting, small batch jobs	Fast and inexpensive, but struggles with complex tasks

In Claude Code you can set the primary model with ANTHROPIC_MODEL, and override tier mappings with ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL. Supported variables vary by version; check claude --help or the official documentation before configuring.

Model names must match the gateway's catalog. A gateway may use its own naming for upstream models, so names copied from official documentation may not resolve. See model pricing for available models and billing; prices change with model versions and upstream policy.

6. Verify the connection: curl first, then Claude Code

First bypass Claude Code and use curl to verify the gateway itself:

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Reply with OK only"}]
  }'

If the gateway uses Bearer authentication, replace x-api-key with Authorization: Bearer $ANTHROPIC_AUTH_TOKEN. A 200 response with normal content means at least one working combination of Base URL, key, and model exists.

Then return to Claude Code and check in order:

claude --version confirms the client is executable.
Run claude doctor in the project directory (if the current version provides it) to check installation and configuration.
Start claude and use /status to see the current model and account information.
Enter a low-risk task, such as "explain the structure of this directory without modifying files."
Watch for a normal response and for errors such as 401, 404, or model not found.

Common symptom reference:

Symptom	Check first	Action
401	Key, variable name, request header	Re-copy the key; keep only one auth variable
404	Base URL with too much or too little `/v1`	Follow gateway docs and use the root or compatible endpoint
model not found	Model name does not match the gateway catalog	Copy from the console or pricing page
Request timeout	Network, DNS, proxy	Test another network; check whether the proxy rewrites headers
429	Concurrency or quota limit	Reduce concurrency; check the key's limit

7. Team rollout: one key per person, one entry point

Teams should not share a single key. Safer practice:

One key per person, named with the person or purpose, disabled immediately when someone leaves.
Set quotas by project or environment, separating production from testing.
Use a unified gateway to monitor usage, model distribution, and abnormal calls.
Distribute the Base URL and allowed models through enterprise managed settings to reduce manual configuration errors.
Write the integration steps into an onboarding document with verification commands and common errors.
Review usage weekly or monthly and act on abnormal keys promptly.

If your company has procurement and compliance processes, confirm the data flow first: code snippets are sent to the gateway and its upstream model service. Whether data is retained, for how long, and whether it is used for training depends on the terms of service; do not assume.

8. Security boundaries: keys, code, and data

A few bottom lines:

Keys must not enter Git, container images, frontend code, screenshots, or chat logs.
Add a .gitignore covering at least .env, .env.*, and .claude/settings.local.json.
If a leak is suspected, revoke the old key first, then investigate usage; changing a password alone is not enough.
Set expiration dates on keys and rotate them on personnel changes.
On shared machines, use a secrets manager or apiKeyHelper instead of plain text in settings.json.
Install Claude Code only from trusted sources and read the changelog before upgrading.

FAQ

Not necessarily. With a working Base URL and authentication variable, the client can use a custom API directly; first-run prompts such as theme and directory trust may still appear. Whether login is required depends on the version and configuration. If you hit problems, first check that the environment variables are active in the launching shell.

What is the difference between ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN?

The former is usually sent as the x-api-key header, the latter as Authorization: Bearer. Which to use depends on the gateway's authentication method. Set only one to avoid conflicting headers.

Should the Base URL be the root address or include /v1?

Claude Code generally takes the root address and appends /v1/messages itself; some gateways expect the compatible endpoint directly. A simple test: request the root address plus /v1/messages with curl. If it works, use the root address; otherwise adjust per the gateway documentation.

Why does curl work but Claude Code report an error?

Common causes are shell variables not reaching a GUI or IDE-integrated terminal, or two authentication variables being set at once. Run echo $ANTHROPIC_BASE_URL in the same terminal that launches Claude Code to confirm.

Technically yes, but it is not advisable. A shared key cannot separate per-member usage, and a leak makes it hard to identify the source. One key per person, with quotas and expiration dates, costs less to manage.

Next steps

If you do not yet have a gateway account, start at the sign-up page, create a low-quota test key, and verify it with the curl and Claude Code steps above. See model pricing for models and billing; prices are adjusted over time and the live page takes precedence.