How to Use Claude Code with Any API Provider (Custom Base URL Guide)

variable. This variable instructs the agent to send all HTTP requests to the specified base path instead of Anthropic's default endpoint.

Best Practice: Avoid hardcoding values in shell profiles. Use a .env file managed by a dotenv loader to prevent secret leakage and ensure reproducibility.

# .env.example
# Gateway endpoint configuration
ANTHROPIC_BASE_URL=https://gateway.internal.net/v1
ANTHROPIC_API_KEY=your-gateway-api-key

# Optional: Custom timeout for gateway latency
ANTHROPIC_TIMEOUT_MS=30000

For production scripts, wrap the execution to ensure variables are loaded:

#!/usr/bin/env bash
# scripts/run-claude.sh
set -euo pipefail

# Load environment variables
if [ -f .env ]; then
  export $(grep -v '^#' .env | xargs)
fi

# Validate required configuration
if [ -z "${ANTHROPIC_BASE_URL:-}" ]; then
  echo "Error: ANTHROPIC_BASE_URL is not set." >&2
  exit 1
fi

# Execute Claude Code with passed arguments
exec claude "$@"

2. Project-Level Configuration

To scope routing to a specific repository, create a .claude configuration file in the project root. This ensures all team members use the same gateway settings without relying on local environment state.

// .claude/settings.json
{
  "routing": {
    "apiBaseUrl": "https://gateway.internal.net/v1",
    "apiKeyRef": "VAULT:claude-gateway-key",
    "modelAliases": {
      "default": "claude-sonnet-4-6",
      "fast": "claude-haiku-4-5"
    }
  },
  "telemetry": {
    "projectTag": "backend-api-v2"
  }
}

Rationale: Using apiKeyRef allows integration with secret management tools (e.g., HashiCorp Vault, AWS Secrets Manager) rather than storing keys in plain text. Model aliases enable consistent model naming across the team, abstracting version strings.

3. IDE Integration

When using Claude Code via VS Code extensions, configuration can be injected through workspace settings. This overrides global settings for the active workspace.

// .vscode/settings.json
{
  "aiCoding.agentConfig": {
    "baseUrl": "https://gateway.internal.net/v1",
    "authToken": "${env:GATEWAY_TOKEN}",
    "model": "claude-sonnet-4-6"
  }
}

Architecture Decision: IDE settings should reference environment variables (${env:...}) to keep secrets out of version control. This maintains security while providing a seamless developer experience.

4. Multi-Model Orchestration

A key advantage of gateway routing is the ability to route different tasks to optimal models. Gateways often support OpenAI-compatible endpoints, allowing tools like Aider or custom scripts to switch models dynamically.

# Example: Using curl to test gateway multi-model support
# Request routed to GPT for structured output tasks
curl -X POST "https://gateway.internal.net/v1/chat/completions" \
  -H "Authorization: Bearer ${GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Generate pytest fixtures for this schema..."}],
    "response_format": {"type": "json_object"}
  }'

This pattern enables a hybrid workflow: use Claude for complex refactoring and reasoning, while routing syntax-heavy or structured generation tasks to models optimized for those operations, all through a single billing relationship.

Pitfall Guide

Misconfiguration of custom base URLs can lead to silent failures, security vulnerabilities, or degraded performance. The following pitfalls are derived from production deployments.

1. Trailing Slash Mismatch

   • Explanation: Appending a trailing slash to the base URL (e.g., https://api.com/v1/) can cause path concatenation errors, resulting in 404 Not Found responses.
   • Fix: Normalize URLs in configuration scripts. Ensure the base URL ends with the version path without a trailing slash.

2. Model String Incompatibility

   • Explanation: Gateways may use different model identifiers than the provider. For example, claude-sonnet-4.6 might be aliased as claude-sonnet-4-6 or sonnet-v2.
   • Fix: Consult the gateway's model alias map. Use project-level aliases to abstract these differences and validate model names before deployment.

3. Key Leakage in Version Control

   • Explanation: Storing API keys in .claude/settings.json or .env files committed to Git exposes credentials.
   • Fix: Add .env to .gitignore. Use apiKeyRef patterns or CI/CD secret injection. Never commit raw keys.

4. Protocol Downgrade

   • Explanation: Using http:// instead of https:// transmits API keys in plaintext, risking interception.
   • Fix: Enforce TLS in gateway configuration. Reject non-HTTPS base URLs in validation scripts.

5. Config Precedence Confusion

   • Explanation: Conflicts between environment variables, project configs, and IDE settings can lead to unpredictable routing behavior.
   • Fix: Document the precedence order. Typically: Environment Variables > Project Config > IDE Settings > Defaults. Use logging to verify the active configuration at runtime.

6. Rate Limit Aggregation Misunderstanding

   • Explanation: Assuming gateways eliminate rate limits. While they pool limits, they still enforce caps based on subscription tier.
   • Fix: Monitor gateway usage dashboards. Implement exponential backoff in scripts. Upgrade tier if consistent throttling occurs.

7. Timeout Latency

   • Explanation: Gateways introduce network hops, potentially increasing latency. Default timeouts may trigger prematurely.
   • Fix: Adjust ANTHROPIC_TIMEOUT_MS to account for gateway overhead. A value of 30000 ms is recommended for complex coding tasks.

Production Bundle

Action Checklist

• Audit Current Spend: Analyze token usage patterns to identify cost optimization opportunities.
• Select Gateway Provider: Evaluate providers based on model support, failover capabilities, and pricing tiers.
• Implement Secret Management: Configure .env files and CI/CD secrets; remove hardcoded keys.
• Configure Project Routing: Add .claude/settings.json with gateway URL and model aliases.
• Validate Model Aliases: Test model strings against the gateway's supported list.
• Set Up Usage Alerts: Configure gateway dashboards for cost and rate limit notifications.
• Document Precedence: Create internal docs explaining config hierarchy for the team.

Decision Matrix

Use this matrix to determine the appropriate routing strategy based on team size and requirements.

Scenario	Recommended Approach	Why	Cost Impact
Solo Developer	Environment Variables	Simple setup; low overhead; easy to switch providers	Baseline; potential 10% savings via gateway
Small Team (<10)	Project Config + .env	Ensures consistency; shared aliases; reproducible builds	Moderate savings; unified billing reduces admin cost
Enterprise / CI-CD	Gateway with Secret Refs	Security compliance; granular tracking; failover resilience	High savings (10-30%); reduced downtime costs
Multi-Model Workflow	OpenAI-Compatible Gateway	Enables routing to best-fit models per task; single key	Optimized costs by using cheaper models for simple tasks

Configuration Template

Copy this template to bootstrap a secure, production-ready configuration.

# .env.template
# Copy to .env and fill values
ANTHROPIC_BASE_URL=https://your-gateway-domain.com/v1
ANTHROPIC_API_KEY=your-gateway-key-here
ANTHROPIC_TIMEOUT_MS=30000

// .claude/settings.json
{
  "routing": {
    "apiBaseUrl": "https://your-gateway-domain.com/v1",
    "apiKeyRef": "ENV:ANTHROPIC_API_KEY",
    "modelAliases": {
      "default": "claude-sonnet-4-6",
      "fast": "claude-haiku-4-5",
      "reasoning": "claude-opus-4-7"
    }
  },
  "telemetry": {
    "projectTag": "my-project-id",
    "costCenter": "engineering"
  }
}

Quick Start Guide

Get routing configured in under five minutes.

1. Obtain Gateway Credentials: Sign up with your chosen API gateway and generate an API key. Note the base URL.
2. Set Environment Variables: Export ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY in your terminal or .env file.
3. Verify Connection: Run claude --version or a simple prompt to confirm requests are routed through the gateway.
4. Check Dashboard: Log into the gateway dashboard to verify traffic is flowing and billing is active.
5. Commit Config: Add .claude/settings.json to your repository to share routing settings with your team.