Why and How to Redirect Your Coding CLI to a Third-Party API

Command-line AI coding tools typically connect to their official model services by default. However, in scenarios such as corporate intranets, private deployments, or aggregator gateways, developers often need to point these tools at third-party compatible endpoints. Fortunately, most such tools provide a standardized configuration entry point — a few environment variables are all it takes to switch, with no code changes required.

The configuration itself is simple; the real time sink is troubleshooting. The three most common errors in practice are:

• 401 Unauthorized: authentication failure
• 404 Not Found: wrong request path
• Model not found / invalid model: incorrect model name

Each has different causes, and the order of troubleshooting matters. This article covers configuration first, then troubleshooting, and closes with a reusable verification workflow.

Throughout this article, your-api-host.example.com is a placeholder — replace it with the domain assigned by your service provider — and sk-xxxx should be replaced with your API key.

Step 1: Verify Protocol Compatibility First

This is the most frequently skipped — and most commonly tripped-over — step.

AI coding tools send requests in the Anthropic Messages format: the path is /v1/messages, authentication is passed via the x-api-key header, and an anthropic-version header is included. Meanwhile, many third-party endpoints only support the OpenAI Chat format: the path is /v1/chat/completions, with authentication via the Authorization: Bearer header.

These two formats differ in request body structure, response structure, and field naming. If the target endpoint only supports the OpenAI format, setting environment variables alone won’t work — it’s not a misconfiguration, it’s a protocol mismatch.

Before configuring anything, verify protocol connectivity with curl:

curl https://your-api-host.example.com/v1/messages \
  -H "x-api-key: sk-xxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "<use the /v1/models response as the source of truth>",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

The interpretation criteria are straightforward:

• A normal model response in JSON means the protocol, key, and model name are all fine — only then is it worth touching the tool’s configuration;
• A 404 means the service has no /v1/messages endpoint and likely only supports the OpenAI format; you’ll need a different provider or a protocol translation gateway;
• A 401 means you should check the key and authentication header first;
• A “model not found” error means you should call /v1/models to list the available models.

A note for Windows users: curl in PowerShell is actually an alias for Invoke-WebRequest, which behaves differently from standard curl and has incompatible parameter passing. Use curl.exe instead, or run the command in Git Bash.

One key principle: if curl doesn’t work, changing the tool’s configuration will have no effect. Get the endpoint working first, then connect the tool — this saves enormous amounts of wasted troubleshooting time.

Configuration: Core Environment Variables

Temporary Configuration (Current Terminal Session)

Ideal for quick testing. macOS / Linux:

export ANTHROPIC_BASE_URL="https://your-api-host.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-xxxx"
claude

Windows PowerShell:

$env:ANTHROPIC_BASE_URL = "https://your-api-host.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-xxxx"
claude

This approach only applies to the current terminal window and expires when it closes, without affecting other projects — perfect for validating your configuration.

A common pitfall: ANTHROPIC_BASE_URL should contain only the domain — do not include /v1. The tool appends /v1/messages automatically. This is the opposite of the base_url convention in many OpenAI-family SDKs (which usually require /v1) — so copying configuration examples from other tools is a frequent source of errors. If you add /v1 here, the final request path becomes /v1/v1/messages, causing an immediate 404.

Also note that some services use Authorization: Bearer authentication rather than x-api-key. In that case, use ANTHROPIC_AUTH_TOKEN; if the provider requires the x-api-key method, you may need ANTHROPIC_API_KEY instead. The difference between the two is worth confirming in the provider’s documentation — using the wrong auth variable is a common cause of 401 errors.

Persistent Configuration (settings.json)

Write the configuration to ~/.claude/settings.json in your user directory (on Windows: %USERPROFILE%\.claude\settings.json):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-api-host.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxx"
  }
}

Important notes:

1. The file must be strict JSON: comments are not supported, and the last entry cannot have a trailing comma. When the config file fails to parse, the tool usually silently falls back to default behavior, making you think the configuration “didn’t take effect.”
2. Don’t put your key in the project-level .claude/settings.json: that file is typically committed to version control, creating a key leakage risk. Personal keys belong in .claude/settings.local.json (usually covered by gitignore) or your user directory’s global configuration.
3. After editing the config file, open a new terminal and run echo $ANTHROPIC_BASE_URL to confirm that stale shell environment variables aren’t overriding the file — environment variables typically take precedence over configuration files, which is a common reason “changes don’t take effect.”

Specifying Models (Optional)

Model names available on third-party gateways often differ from official naming, so you may need to specify them explicitly:

export ANTHROPIC_MODEL="<use the /v1/models response as the source of truth>"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="<use the /v1/models response as the source of truth>"

The first variable controls the main conversation model; the second controls the small model the tool uses internally for lightweight tasks (such as summaries and title generation). Many “model not found” errors actually come from these background auxiliary calls rather than the main conversation you see — so the small model also needs to point to a name the provider actually supports.

Troubleshooting the Three Most Common Errors

401 Unauthorized: Authentication Failure

Troubleshooting order:

1. Is the key itself valid? Make a direct curl request with the x-api-key header to rule out expired keys, exhausted quotas, or missing permissions;
2. Does the auth header method match? Does the provider expect x-api-key or Authorization: Bearer? The corresponding environment variables differ;
3. Are the environment variables actually in effect? Check with echo in the same terminal session; if configured via settings.json, verify the JSON parses correctly;
4. Is the key polluted by quotes or whitespace? Extra characters from copy-pasting are a common, easily overlooked mistake.

404 Not Found: Wrong Path

Troubleshooting order:

1. Check whether BASE_URL has an extra /v1 (see above — this is the number one cause);
2. Trailing slash issues: some gateways are sensitive to a trailing /; avoid adding one after the domain;
3. Does the protocol match? Go back to the verification step and confirm the provider actually implements the /v1/messages endpoint;
4. Is a proxy interfering? Local HTTP proxy environment variables (such as HTTP_PROXY) may route requests to the wrong address; temporarily disable the proxy to test if needed.

Model Not Found / Invalid Model

Troubleshooting order:

1. Call the provider’s /v1/models endpoint to get the actual list of available model IDs — don’t guess from memory or copy official naming;
2. Confirm both the main model and the small model are updated: if the default auxiliary model used by background calls isn’t overridden, you’ll see intermittent errors;
3. Pay attention to case sensitivity and version suffixes: most gateways match strings exactly;
4. Confirm your plan’s permissions: some services return “model not found” when the real issue is “no access to that model.”

Recommended Troubleshooting Workflow

1. Use curl to hit /v1/messages directly and verify the three essentials: protocol, key, and model name;
2. Once curl works, launch the tool with temporary environment variables to validate;
3. After validation succeeds, persist the configuration in settings.json, keeping keys in your local personal configuration;
4. When errors occur, troubleshoot in order: 401 → authentication, 404 → path, model errors → match against the model list. Change only one variable at a time to avoid changes interfering with each other.

Follow the workflow of “verify the endpoint first, configure the tool second, then localize the error,” combined with the checklists in this article, and the vast majority of integration issues can be resolved within minutes.