Instrucciones de origen · Vista previa de solo lectura
name
claude-code-proxy-patterns
description
Claude Code OAuth proxy patterns and anti-patterns for multi-provider model routing. TRIGGERS - proxy Claude Code, OAuth token Keychain, route Haiku to MiniMax, ANTHROPIC_BASE_URL, model routing proxy, claude-code-proxy, proxy-toggle, multi-provider setup, anthropic-beta oauth, proxy auth failure, go proxy, failover proxy, launchd proxy, proxy failover
allowed-tools
Read, Write, Edit, Bash, Grep, Glob
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
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 for built-in retry logic.
The proxy reads the model field from each /v1/messages request body. If it matches the configured Haiku model ID, the request goes to MiniMax. Everything else falls through to real Anthropic with OAuth passthrough.
Working Patterns
WP-01: Keychain OAuth Token Reading
Read OAuth tokens from macOS Keychain where Claude Code stores them.
Service: "Claude Code-credentials" (note the space before the hyphen)
Account: Current username via 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")
Note: expiresAt is in milliseconds (Unix epoch _ 1000). Compare with time.time() _ 1000 or divide by 1000 for seconds.
WP-03: OAuth Beta Header
The anthropic-beta: oauth-2025-04-20 header is required for OAuth token authentication. Without it, Anthropic rejects the Bearer token.
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"notin 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 alone is insufficient in OAuth mode. Claude Code must also see ANTHROPIC_API_KEY set to switch from OAuth-only mode to API-key mode, which then honors 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" is a dummy sentinel. The proxy intercepts it (line 324) and never forwards it to providers.
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 for the implementation.
WP-07: count_tokens Endpoint Auth
The /v1/messages/count_tokens endpoint needs the same auth as /v1/messages. Claude Code calls this for preflight token counting. Missing auth here causes silent failures. Returns 501 for non-Anthropic providers (MiniMax doesn't support it).
WP-08: Anthropic-Compatible Provider URLs
Third-party providers that support the Anthropic /v1/messages API format.
Did the command succeed? — If not, fix the instruction or error table that caused the failure.
Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
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.
