Claude Code Proxy Patterns

Multi-provider proxy that routes Claude Code model tiers to different backends. Haiku to MiniMax (cost/speed), Sonnet/Opus to Anthropic (native OAuth passthrough). Includes Go binary proxy with launchd auto-restart and failover wrapper for resilience.

Scope: Local reverse proxy for Claude Code with OAuth subscription (Max plan). Routes based on model name in request body.

Reference implementations:

• Go proxy binary:

  /usr/local/bin/claude-proxy

  (port 8082)

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

• Building or debugging a Claude Code multi-provider proxy
• Setting up

  ANTHROPIC_BASE_URL

  with OAuth subscription mode
• Integrating Anthropic-compatible providers (MiniMax, etc.)
• Diagnosing "OAuth not supported" or auth failures through a proxy
• Understanding how Claude Code stores and transmits OAuth tokens

Do NOT use for: Claude API key-only setups (no proxy needed), MCP server development, Claude Code hooks (operate at tool level, not API level), or corporate HTTPS proxy traversal.

Architecture

Claude Code (OAuth/Max subscription)
    |
    |  ANTHROPIC_BASE_URL=http://127.0.0.1:8082 (Go proxy)
    |  (unset ANTHROPIC_API_KEY to avoid auth conflict)
    v
+----------------------------------+
| Go proxy (:8082)                 |
| launchd managed, auto-restart   |
+----------------------------------+
    |
    | model =
    | claude-haiku-
    | 4-5-20251001
    v
+-----------+
| MiniMax   |
| highspeed |
+-----------+

Port Configuration:

• :8082

  - Go proxy (entry point, launchd-managed, auto-restart)

The Go proxy uses

cenkalti/backoff/v4

The proxy reads the

model

/v1/messages

Working Patterns

WP-01: Keychain OAuth Token Reading

Read OAuth tokens from macOS Keychain where Claude Code stores them.

Service:

"Claude Code-credentials"

getpass.getuser()

import subprocess, json, getpass

result = subprocess.run(
    ["security", "find-generic-password",
     "-s", "Claude Code-credentials",
     "-a", getpass.getuser(), "-w"],
    capture_output=True, text=True, timeout=5, check=False,
)
if result.returncode == 0:
    data = json.loads(result.stdout.strip())
    oauth = data.get("claudeAiOauth")

See references/oauth-internals.md for the full deep dive.

WP-02: Token JSON Structure

The Keychain stores a JSON envelope with the

claudeAiOauth

{
  "claudeAiOauth": {
    "accessToken": "eyJhbG...",
    "refreshToken": "rt_...",
    "expiresAt": 1740268800000,
    "subscriptionType": "claude_pro_2025"
  }
}

Note:

expiresAt

time.time() _ 1000

WP-03: OAuth Beta Header

The

anthropic-beta: oauth-2025-04-20

Critical: APPEND to existing beta headers, do not replace them.

# proxy.py:304-308
existing_beta = original_headers.get("anthropic-beta", "")
beta_parts = [b.strip() for b in existing_beta.split(",") if b.strip()] if existing_beta else []
if "oauth-2025-04-20" not in beta_parts:
    beta_parts.append("oauth-2025-04-20")
target_headers["anthropic-beta"] = ",".join(beta_parts)

WP-04: ANTHROPIC_API_KEY=proxy-managed

Setting

ANTHROPIC_BASE_URL

ANTHROPIC_API_KEY

ANTHROPIC_BASE_URL

# In .zshenv (managed by proxy-toggle)
export ANTHROPIC_BASE_URL="http://127.0.0.1:8082"
export ANTHROPIC_API_KEY="proxy-managed"

The value

"proxy-managed"

WP-05: OAuth Token Cache with TTL

Avoid repeated Keychain subprocess calls by caching the token for 5 minutes.

# proxy.py:117-118
_oauth_cache: dict = {"token": None, "expires_at": 0.0, "fetched_at": 0.0}
_OAUTH_CACHE_TTL = 300  # Re-read from Keychain every 5 minutes

Cache invalidation triggers:

• TTL expired (5 minutes since last fetch)
• Token's

  expiresAt

  has passed
• Proxy restart

WP-06: Auth Priority Chain

The proxy tries multiple auth sources in order for Anthropic-bound requests.

1. REAL_ANTHROPIC_API_KEY env var   -> x-api-key header (explicit config)
2. Keychain OAuth token             -> Authorization: Bearer + anthropic-beta
3. ~/.claude/.credentials.json      -> Authorization: Bearer (plaintext fallback)
4. Forward client Authorization     -> Pass through whatever Claude Code sent
5. No auth                          -> Will 401 (expected)

See

proxy.py:293-314

WP-07: count_tokens Endpoint Auth

The

/v1/messages/count_tokens

/v1/messages

WP-08: Anthropic-Compatible Provider URLs

Third-party providers that support the Anthropic

/v1/messages

https://api.minimax.io/anthropic

base_resp

thinking

See references/provider-compatibility.md for the full matrix.

WP-09: Concurrency Semaphore

Per-provider rate limiting prevents overwhelming third-party APIs. No semaphore for Anthropic (they handle their own rate limiting).

# proxy.py:207-209
MAX_CONCURRENT_REQUESTS = int(os.getenv("MAX_CONCURRENT_REQUESTS", "5"))
haiku_semaphore = asyncio.Semaphore(MAX_CONCURRENT_REQUESTS)
opus_semaphore = asyncio.Semaphore(MAX_CONCURRENT_REQUESTS)
sonnet_semaphore = asyncio.Semaphore(MAX_CONCURRENT_REQUESTS)

WP-10: proxy-toggle Enable/Disable

The

proxy-toggle

.zshenv

~/.claude/bin/proxy-toggle enable    # Adds env vars, creates flag file, checks health
~/.claude/bin/proxy-toggle disable   # Removes env vars, removes flag file
~/.claude/bin/proxy-toggle status    # Shows routing flag, proxy process, .zshenv state

Important: Claude Code must be restarted after toggling because

ANTHROPIC_BASE_URL

WP-11: Health Endpoint

The

/health

curl -s http://127.0.0.1:8082/health | jq .

WP-12: Go Proxy with Retry

Go proxy with built-in retry using

cenkalti/backoff/v4

import "github.com/cenkalti/backoff/v4"

backoffConfig := backoff.NewExponentialBackOff(
    backoff.WithInitialInterval(500 * time.Millisecond),
    backoff.WithMultiplier(2),
    backoff.WithMaxInterval(2 * time.Second),
    backoff.WithMaxElapsedTime(5 * time.Second),
)
err := backoff.Retry(operation, backoffConfig)

Location:

/usr/local/bin/claude-proxy

ANTHROPIC_BASE_URL=http://127.0.0.1:8082

.zshenv

WP-13: Launchd Service Configuration

The Go proxy runs as a macOS launchd daemon for auto-restart on crash and boot persistence.

Plist:

/Library/LaunchDaemons/com.terryli.claude-proxy.plist

Full plist configuration, commands, verification checklist, and debugging: references/launchd-configuration.md

WP-14: OAuth Token Auto-Refresh

Background goroutine refreshes OAuth tokens every 30 minutes, 5 minutes before expiry. Falls back to Keychain if API refresh fails.

Full implementation and refresh logic: references/oauth-auto-refresh.md

Anti-Patterns Summary

Full details with code examples: references/anti-patterns.md

ANTHROPIC_API_KEY=proxy-managed

anthropic-beta: oauth-2025-04-20

/api/oauth/claude_cli/create_api_key

org:create_api_key

user:inference

"claude-code-credentials"

"Claude Code-credentials"

~/.claude/.credentials.json

gh auth token

/v1/messages/count_tokens

TodoWrite Task Templates

Setup, provider addition, diagnostics, and disable templates: references/task-templates.md

Reference Implementation

The working production deployment (Go proxy is primary):

/usr/local/bin/claude-proxy

~/.claude/tools/claude-code-proxy-go/main.go

~/.claude/tools/claude-code-proxy-go/oauth_refresh.go

~/.claude/tools/claude-code-proxy-go/.env

/Library/LaunchDaemons/com.terryli.claude-proxy.plist

~/.zshenv

Post-Change Checklist

After modifying this skill:

1. Anti-patterns table matches references/anti-patterns.md
2. Working patterns verified against proxy.py source
3. No hardcoded OAuth tokens in examples
4. Beta header version current (

   oauth-2025-04-20

   )
5. All internal links use relative paths (

   ./references/...

   )
6. Link validator passes
7. Skill validator passes
8. Append changes to references/evolution-log.md

Troubleshooting

ANTHROPIC_API_KEY=proxy-managed

oauth-2025-04-20

"Claude Code-credentials"

proxy-managed

/v1/messages/count_tokens

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.