How to Evaluate a Claude Code Relay or API Gateway: Protocol, Real Cost, and Data Boundaries

Before pointing Claude Code at a third-party relay or LLM gateway, the most helpful first step is not comparing headline discount claims or editing your global configuration file—it is answering four practical questions in order:

1. Do you actually need a third-party gateway? If you already have an official claude.ai subscription (Pro, Max, Team, or Enterprise) that covers your interactive coding volume, simply run /login. If you only need single-vendor pay-as-you-go billing or CI automation, use the official Anthropic Claude Console API directly without adding an extra hop.
2. Does the gateway support the full Claude Code workflow? A basic chat wrapper only needs to exchange short text completions. Claude Code relies on the native Anthropic Messages endpoint, prompt caching, multi-step tool execution, and long-thinking SSE keep-alives—and the terminal CLI, VS Code extension, and Claude Desktop app each read different configuration surfaces.
3. What will a multi-turn coding session actually cost? Real coding bills are determined by all four token buckets (uncached input, output, cache write, and cache read), plus top-up processing fees, credit expiry or refund rules, and how the provider defines its channel routing tiers.
4. Where do your prompts and code snippets travel? Routing requests through a non-Anthropic ANTHROPIC_BASE_URL sends your prompts, file context, and tool results through that gateway and its upstream provider. Because projects differ in sensitivity, check the gateway's and upstream provider's data-handling and retention terms against what your specific repository requires before sending private code.

1. Separate the Connection Paths First: Official Subscription, Direct Console API, and Gateways

Before setting any environment variables, verify which account authenticates and settles your requests. Per Anthropic's official Authentication documentation, LLM gateway overview, and gateway connection guide (all checked 2026-10-23), these paths use distinct credentials and billing models:

Why You Should Never Set ANTHROPIC_BASE_URL Without a Gateway Credential

Per Anthropic's official LLM gateway overview and Connect Claude Code to an LLM gateway (checked 2026-10-23):

• Setting ANTHROPIC_BASE_URL alone does not change how Claude Code authenticates: Without ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, or apiKeyHelper, Claude Code does not replace a saved claude.ai subscription login—it sends requests to ANTHROPIC_BASE_URL using that saved login (and enterprise gateways that forward subscription traffic to Anthropic must forward the OAuth flag in the anthropic-beta header).
• Gateways that issue their own keys require the matching credential variable: Commercial pay-as-you-go gateways or proxies configured with per-user gateway keys require the client to pass that gateway credential. In Claude Code, ANTHROPIC_AUTH_TOKEN sends Authorization: Bearer <token>, whereas ANTHROPIC_API_KEY sends x-api-key: <key>. Omitting the credential variable or choosing the wrong one sends your key in a header the gateway does not read (or sends no gateway key at all), causing authentication failures.

Check Authentication Precedence and Managed Policy Locks

Per Anthropic's official Authentication precedence and Settings documentation (checked 2026-10-23), local environment variables do not always win:

1. Enterprise Claude apps gateway and managed settings take top priority: If you are signed into an enterprise Claude apps gateway session, it overrides cloud provider flags (CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY), ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, and standard /login. In addition, administrators can configure forceLoginMethod (such as restricting logins to claudeai or console), forceLoginOrgUUID, or allowedProviders (such as restricting to firstParty) in managed-settings.json to block third-party gateways.
2. Standard CLI precedence and headless -p behavior: In a standard shell without organization locks, cloud provider flags take precedence over ANTHROPIC_AUTH_TOKEN, which in turn takes precedence over ANTHROPIC_API_KEY. When ANTHROPIC_API_KEY is selected, interactive sessions show a one-time approval prompt and remember your choice (if previously declined, re-enable Use custom API key in /config). Non-interactive mode (claude -p) skips that approval prompt and uses ANTHROPIC_API_KEY directly, but -p does not alter precedence order—if ANTHROPIC_AUTH_TOKEN or a cloud provider flag is also set, the higher-precedence credential still wins.

For official API key creation steps, Max/Team monthly API credit eligibility, and a redaction-safe SET/UNSET shell audit snippet, see our Claude Code API Key & Authentication Precedence Guide.

2. Why "Works in a Basic Chat App" Does Not Mean "Works in Claude Code"

Many providers advertise support for Claude models, yet fail or silently lose prompt caching during multi-file edits, tool calls, or long-context refactoring in Claude Code. That happens because Claude Code relies on specific protocol and streaming behaviors from the underlying gateway.

Six Protocol Requirements for a Claude Code Gateway

Checked against Anthropic's official LLM gateway protocol requirements (2026-10-23), evaluate any candidate gateway across these six areas:

Client Surface Differences: Why Terminal Settings Don't Apply Everywhere

Always match your configuration method to the client surface you actually use. Per Connect Claude Code to an LLM gateway and Settings (checked 2026-10-23):

• Terminal CLI: Reads shell environment variables and managed policy files, plus user settings (~/.claude/settings.json), local project settings (.claude/settings.local.json), and shared project settings (.claude/settings.json).
• VS Code Extension: Requires setting claudeCode.environmentVariables in VS Code settings; placing variables only in ~/.claude/settings.json covers the spawned process but does not cover the extension's own login check.
• Claude Desktop App: Does not read terminal shell variables or CLI ~/.claude/settings.json. You must configure a gateway separately via Help → Troubleshooting → Enable Developer Mode → Configure Third-Party Inference, and Desktop sessions remain separate from CLI sessions (see our Claude Code Terminal vs. Desktop Guide).
• Web Cloud Sessions (Claude Code on the Web) & Slack: Always ignore local gateway environment variables and cannot be routed to a third-party ANTHROPIC_BASE_URL.
• First-Party-Only Feature Limits: Remote Control and Voice Dictation are unavailable whenever you use gateway credentials or a custom ANTHROPIC_BASE_URL.

3. Pricing and Account Terms: Why Headline Discounts Don't Tell the Whole Story

Comparing gateways by a single "dollars per million input tokens" number or a promotional discount multiplier rarely reflects real Claude Code spend. In multi-turn coding sessions, file reads, tool outputs, and growing conversation history generate heavy prompt-cache activity alongside background helper-model calls.

Five Cost and Account Checks Before Topping Up

1. All Four Token Billing Buckets Disclosed Up Front:
   • Uncached Input
   • Output (including extended thinking tokens)
   • Cache Write (distinguishing 5-minute default TTL from 1-hour extended TTL multipliers)
   • Cache Read / Hit If a provider only lists input/output rates while hiding cache-write pricing—or breaks cache_control so cache hits fall back to uncached input—your multi-turn session cost can easily exceed standard pay-as-you-go rates. See our Claude Code API Pricing & Token Budget Guide for full bucket formulas.
2. Primary and Helper Role Model Mapping: Claude Code invokes helper models for background summaries, session titles, and subagents. Verify that your gateway catalog includes the target model IDs and map them explicitly via ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, and CLAUDE_CODE_SUBAGENT_MODEL so subagents never request a default model ID the gateway does not serve.
3. Currency Unit, Top-Up Fees, and Exchange Math: Check whether balances are denominated in USD or custom point credits, whether checkout adds a payment processing fee, and compare total cost across identical workloads in the same currency.
4. Channel Tier Definitions and Per-Key Channel Restrictions: Some gateways divide routes into multiple channel tiers (such as standard vs. promotional/discounted channels). Because each provider defines its own upstream pools, rate-limit behavior, and fallback rules differently, inspect how the provider documents its channel tiers and whether you can restrict an API key to specific channels.
5. Principal Expiry, Bonus Credit TTL, and Refund Policy: Before depositing funds, check the Terms of Service for refund windows (whether unused principal is refundable or non-refundable except as required by law), whether purchased principal ever expires, and the exact expiration window for promotional bonus credits.

4. Data Flow, Local Cache, and Privacy Boundaries: Match the Policy to Your Project

Evaluating how a gateway handles your code does not require one-size-fits-all slogans, but it does require knowing which nodes touch your request payload and matching the provider's policies to your project's sensitivity.

The Three Data Nodes on a Gateway Request Path

When you point ANTHROPIC_BASE_URL at a third-party gateway, a coding request flows through the following three nodes:

[1. Local Workspace & Terminal Process]
   ├── Reads repo files, Git status, CLAUDE.md, env vars, and local tool outputs
   ├── Writes local plaintext session transcripts: ~/.claude/projects/ (30-day default retention via cleanupPeriodDays)
   └── Direct non-inference traffic to api.anthropic.com (auto-update, telemetry, /fast checks, WebFetch domain preflight)
          │
          ▼ (Sends /v1/messages JSON payload over HTTPS/TLS)
[2. Third-Party Gateway / Relay (ANTHROPIC_BASE_URL)]
   ├── Receives system prompts, conversation history, code snippets, tool schemas, and gateway credentials
   └── Governed by the gateway's own Terms of Service, logging policy, and security controls
          │
          ▼ (Forwarded by the gateway to its selected upstream channel)
[3. Upstream Model Provider / Channel Behind the Gateway]
   └── Governed by the upstream provider's training, abuse-monitoring, and data-retention rules

Three Privacy Concepts Not to Confuse

Per Anthropic's official Data usage, Security, and LLM gateway overview documentation (checked 2026-10-23):

1. Transport Encryption (HTTPS / TLS) ≠ Zero Server-Side Retention: HTTPS protects payloads in transit across the public network, but once the request reaches ANTHROPIC_BASE_URL, the gateway process terminates TLS and reads the JSON payload to route and bill the call.
2. "No Model Training" ≠ "No Request Retention": Under Anthropic's official data usage policy, commercial plans (Team, Enterprise, and Claude API) do not use prompts or code to train generative models by default, but standard commercial retention is 30 days unless a qualified Claude for Enterprise organization has Zero Data Retention (ZDR) enabled by its account team. More importantly, Anthropic's commercial terms apply only to Anthropic's own services and never automatically extend to a third-party gateway or its upstream channels.
3. Gateway Terms vs. Upstream Channel Policies: Different codebases have different requirements. For open-source repos or non-sensitive sandbox scripts, standard metered routing is often fine; if your repository contains customer data, proprietary algorithms, or regulated workloads, review the data-handling and retention policies of both the gateway and the upstream channel it routes to before connecting.

Local Plaintext Transcripts and Background Traffic to api.anthropic.com

Even when ANTHROPIC_BASE_URL points to a custom gateway, the following local and background behaviors remain active by default (verified against official docs on 2026-10-23):

• Local session transcripts: Claude Code stores plaintext session logs under ~/.claude/projects/ to support session resumption, retaining them for 30 days by default (configurable via cleanupPeriodDays in settings).
• Non-inference background traffic: By default, Claude Code still contacts api.anthropic.com directly for auto-update checks, telemetry events, session quality surveys, /fast mode checks, and target-domain safety preflight checks when the WebFetch tool runs. Use the environment variable below to disable auto-updates, /bug reporting, error reporting, telemetry, surveys, and /fast checks; WebFetch domain preflight is not affected by that variable and must be disabled separately via skipWebFetchPreflight in settings:

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
# settings.json: "skipWebFetchPreflight": true

5. Worked Example Using UniRoute's Public Docs: Verified Facts vs. Unverified Boundaries

To show how the 6-point checklist works in practice, the table below applies the exact same rules to UniRoute's public documentation, pricing page, and legal terms (checked 2026-10-23). Facts explicitly stated in public docs are cited directly; anything not disclosed or dependent on your specific workload is marked as unverified / check for your workload.

If you are comparing multiple gateway options side by side (such as keeping OpenRouter and tuning provider.order / zdr, connecting directly to a single model vendor, self-hosting LiteLLM, or using UniRoute), see our Claude Code with OpenRouter Setup & Cost Guide and OpenRouter Alternatives Comparison.

6. Voluntary Small-Scale Acceptance Test and Child-Subshell Rollback

Once you have reviewed the documentation and terms—and voluntarily choose to run a small live acceptance test against a gateway—the safest approach is to run the test inside a temporary child subshell (bash -c). Because the gateway variables only exist inside that child process, exiting the session leaves your parent shell's existing environment variables and ~/.claude/settings.json untouched.

Billing & Execution Notice: Sending a test request to /v1/messages or running claude -p / interactive prompts executes a real model call that consumes balance or quota on the active account. The commands below are provided strictly for your voluntary local testing; no new paid model calls were executed while authoring this guide.

Step 1: Check Your CLI Version and Make a Non-Overwriting Backup (If You Plan to Edit Settings Later)

Never place secret keys inside a project-committed .claude/settings.json. If you ever plan to edit ~/.claude/settings.json, create a timestamped backup with cp -n so you never overwrite an earlier backup:

claude --version
if [ -f "$HOME/.claude/settings.json" ]; then
  backup_path="$HOME/.claude/settings.json.bak.$(date +%Y%m%d-%H%M%S)"
  cp -n "$HOME/.claude/settings.json" "$backup_path"
  echo "Created non-overwriting backup: $backup_path"
else
  echo "No ~/.claude/settings.json found; no backup needed"
fi

Step 2: Launch Inside an Isolated Child Subshell (Without Touching Parent Shell or Global Files)

For your first acceptance test, do not edit ~/.claude/settings.json and do not export gateway variables in your parent shell. Instead, read the key silently inside a temporary bash -c child subshell, align primary and helper role model variables, and run claude auth status --text inside that same child process before launching claude (shown below with https://api.uniroute.app as an example; substitute your chosen gateway's root URL and exact model ID if testing another provider):

bash -c '
  set +x
  read -r -s -p "Gateway API key: " ANTHROPIC_AUTH_TOKEN
  printf "\n"
  [ -n "$ANTHROPIC_AUTH_TOKEN" ] || exit 1
  read -r -p "Target Claude model ID: " route_model
  [ -n "$route_model" ] || exit 1
  export ANTHROPIC_BASE_URL="https://api.uniroute.app"
  export ANTHROPIC_AUTH_TOKEN
  export ANTHROPIC_API_KEY=""
  export ANTHROPIC_DEFAULT_HAIKU_MODEL="$route_model"
  export ANTHROPIC_DEFAULT_SONNET_MODEL="$route_model"
  export ANTHROPIC_DEFAULT_OPUS_MODEL="$route_model"
  export CLAUDE_CODE_SUBAGENT_MODEL="$route_model"
  claude auth status --text
  claude --model "$route_model"
'

Step 3: Record the Four Minimum Acceptance Checks in Order

Inside that child subshell's Claude Code session, complete Check 1 before sending any prompt, then run Checks 2–4 only if the active auth source matches and your test budget allows:

Step 4: Exit the Child Subshell to Return to Your Prior Setup (and Targeted Restore If You Edited Files)

• If you launched via the Step 2 bash -c child subshell: Simply type /exit to close Claude Code. When the child subshell exits, its temporary ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, and role-model exports disappear automatically while leaving any pre-existing variables in your parent shell (such as an official ANTHROPIC_API_KEY or custom model defaults you already used) and ~/.claude/settings.json unchanged. Do not run bulk unset commands in your parent shell, which would delete variables your existing environment relied on.
• If you manually edited ~/.claude/settings.json or exported gateway variables directly in your current shell: Restore your ~/.claude/settings.json from the timestamped backup created in Step 1, revert only the specific shell variables you modified back to their prior values (or open a fresh terminal session), and run /status inside claude (or /login if returning to an official subscription) to verify your original auth source is active.

7. Frequently Asked Questions (FAQ)

If I already have a Claude Pro or Max subscription, do I need a Claude Code relay?

Usually no. As long as your interactive coding fits within your subscription usage limits and you can sign into claude.ai, running /login in Claude Code is the simplest path. You only need to evaluate the official Console API or a third-party gateway if you want separate metered budgets, multi-provider model routing under one wallet, or isolated per-key spend caps for scripts and teams.

Why does a relay work in a basic chat client but fail inside Claude Code?

Basic chat clients usually send simple /v1/chat/completions requests. Claude Code sends native /v1/messages requests with anthropic-beta capability flags, cache_control blocks, strict tool schemas, and multi-turn tool_result blocks. If a relay performs lossy format conversion, strips anthropic-beta feature headers or cache_control blocks, alters the system array order, or drops SSE ping events during long thinking pauses, beta features, prompt caching, tool execution, or streaming can break inside Claude Code.

How can I tell whether a gateway's advertised low price will actually save money?

Look beyond headline discount multipliers or single input-token rates. Run a representative multi-turn file read/edit task in a scratch folder, then inspect all four token buckets (uncached input, 5m/1h cache write, cache read, and output) and the actual total charge in the gateway's usage ledger, factor in any top-up fees or non-refundable principal/bonus expiry rules, and check how the provider documents the routing and rate-limit rules for that channel tier.

Does Claude Code still contact Anthropic's servers when ANTHROPIC_BASE_URL points to a third-party gateway?

Yes. Per Anthropic's official gateway and data-usage documentation, even when inference traffic goes to ANTHROPIC_BASE_URL, Claude Code still contacts api.anthropic.com by default for auto-update checks, telemetry, session quality surveys, /fast availability checks, and WebFetch domain safety preflight requests. Set the environment variable below to disable auto-updates, error reporting, telemetry, surveys, and /fast checks, and configure skipWebFetchPreflight in settings to disable WebFetch domain preflight checks:

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
# settings.json: "skipWebFetchPreflight": true

Next Steps: Verify Pricing, Docs, and Optional Setup in Order

If you have completed the checklist above and want to inspect UniRoute's exact pricing or configuration details before deciding whether to test, follow these steps in order:

1. Check live pricing and token bucket rules first: Review the UniRoute Live Model Pricing Table alongside our Claude Code API Pricing & Cache Bucket Guide to compare standard and discounted channel rates and context tiers.
2. Read the setup, native endpoint, and billing documentation: Inspect the Claude Code CLI Setup & Rollback Guide, Native Route Selection Guide, and Wallet Top-Up & Billing Rules.
3. Create a restricted API key and reconcile usage only when ready: If you choose to run a small test, follow the Create API Key Guide to set a Spend Limit, Channel Restriction, and Model Restriction, then verify your per-request token buckets and charges in the UniRoute Console.