SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场claude-code-proxy-patterns

claude-code-proxy-patterns

部署与运维

查看项目

更新于 10-16 02:08

技能介绍

用途

本技能围绕 Claude Code 的多提供商代理展开，用于构建或调试一个本地反向代理，使 Claude Code 在 OAuth 订阅（Max 计划）模式下能够按请求体中的模型名称将请求路由到不同的后端：Haiku 模型路由至 MiniMax（出于成本/速度考虑），Sonnet/Opus 则通过原生 OAuth 直通回 Anthropic。适用于设置带 OAuth 订阅模式的 ANTHROPIC_BASE_URL、集成 Anthropic 兼容的提供商（如 MiniMax）、诊断通过代理出现的「OAuth not supported」或认证失败，以及理解 Claude Code 如何存储和传输 OAuth 令牌。

明确不适用：仅使用 Claude API Key 的设置（无需代理）、MCP 服务器开发、Claude Code hooks（作用于工具层而非 API 层）以及企业 HTTPS 代理穿透。

架构与主要能力

架构为：Claude Code（OAuth/Max 订阅）通过 ANTHROPIC_BASE_URL=http://127.0.0.1:8082 指向 Go 代理；Go 代理（:8082）由 launchd 管理并自动重启；代理读取每个 /v1/messages 请求体中的 model 字段，若匹配配置的 Haiku 模型 ID 则转发至 MiniMax，其余则通过 OAuth 直通回真实 Anthropic。

端口配置：:8082 为 Go 代理入口，由 launchd 管理并自动重启。Go 代理使用 cenkalti/backoff/v4 实现内置重试逻辑。

工作模式（Working Patterns）包括：

  • WP-01：从 macOS Keychain 读取 OAuth 令牌。服务名 "Claude Code-credentials"（注意连字符前有空格），账户名为当前用户名（通过 getpass.getuser()）。
  • WP-02：令牌 JSON 结构。Keychain 存储带有 claudeAiOauth 键的 JSON 信封，包含 accessToken、refreshToken、expiresAt（毫秒，Unix epoch × 1000）、subscriptionType。
  • WP-03：OAuth Beta 请求头。OAuth 令牌认证需要 anthropic-beta: oauth-2025-04-20 头，且必须追加到已有 beta 头而非替换。
  • WP-04：ANTHROPIC_API_KEY=proxy-managed。仅设置 ANTHROPIC_BASE_URL 在 OAuth 模式下不够，还需设置 ANTHROPIC_API_KEY 为占位值 "proxy-managed"（代理会拦截该哨兵值，不会转发给提供商）。
  • WP-05：带 TTL 的 OAuth 令牌缓存（300 秒），缓存失效触发条件包括 TTL 过期、令牌 expiresAt 已过、代理重启。
  • WP-06：认证优先级链（REAL_ANTHROPIC_API_KEY 环境变量 → Keychain OAuth 令牌 → ~/.claude/.credentials.json → 转发客户端 Authorization → 无认证将返回 401）。
  • WP-07：count_tokens 端点认证。该端点需要与 /v1/messages 相同的认证；非 Anthropic 提供商（MiniMax 不支持）返回 501。
  • WP-08：Anthropic 兼容提供商 URL。例如 MiniMax highspeed 的 Base URL 为 https://api.minimax.io/anthropic。
  • WP-09：并发信号量。按提供商限流，默认 MAX_CONCURRENT_REQUESTS=5；Anthropic 不设信号量。
  • WP-10：proxy-toggle 启用/禁用脚本，原子管理 .zshenv 条目与标志文件；切换后必须重启 Claude Code。
  • WP-11：/health 健康端点返回提供商配置状态。
  • WP-12：带重试的 Go 代理（指数退避 500ms → 1s → 2s，最长持续 5s），位于 /usr/local/bin/claude-proxy。
  • WP-13：launchd 服务配置（Plist：/Library/LaunchDaemons/com.terryli.claude-proxy.plist），用于崩溃自动重启和开机持久化。
  • WP-14：OAuth 令牌自动刷新。后台 goroutine 每 30 分钟刷新，在到期前 5 分钟进行；API 刷新失败时回退到 Keychain。

使用方式

反模式（Anti-Patterns）给出了需规避的做法与修复建议，例如：CCP-01 仅设 ANTHROPIC_BASE_URL 而未设 ANTHROPIC_API_KEY（HIGH）；CCP-02 缺少 anthropic-beta: oauth-2025-04-20 头（HIGH）；CCP-04 Keychain 服务名大小写/空格错误（HIGH）；CCP-06 硬编码 OAuth 令牌（HIGH）；CCP-07 在代理/钩子中使用 gh auth token 会导致进程风暴（HIGH）；CCP-08 有 OAuth 令牌时仍设置 ANTHROPIC_API_KEY 造成认证冲突（HIGH）；CCP-09 向 MiniMax 发送 cache_control 参数（MEDIUM）；CCP-11 未处理 /v1/messages/count_tokens（MEDIUM）；CCP-12 在 0.0.0.0 上运行代理（LOW，应绑定 127.0.0.1）。

文档还提供故障排查表（如 Claude Code 忽略 ANTHROPIC_BASE_URL、Anthropic 返回 401、Keychain 读取为空、count_tokens 认证失败等对应原因与解决方案）、TodoWrite 任务模板（设置、添加提供商、诊断、禁用）、变更后检查清单（如反模式表与参考文档一致、示例中无硬编码 OAuth 令牌、beta 头版本为 oauth-2025-04-20、内部链接使用相对路径、链接与技能校验器通过、将变更追加至 references/evolution-log.md），以及执行后反思流程。

参考实现文件包括：/usr/local/bin/claude-proxy（Go 代理二进制，约 960 行）、~/.claude/tools/claude-code-proxy-go/main.go（Go 代理源码）、oauth_refresh.go（OAuth 自动刷新，80 行）、.env（提供商配置，chmod 600）、launchd 配置 plist、~/.zshenv 环境配置。

适用场景与限制

适用于在 macOS 上使用 Claude Code OAuth/Max 订阅、需要按模型层级在多提供商间路由的用户，以及需要诊断代理认证问题的开发者。限制包括：仅面向 OAuth 订阅模式的本地反向代理；仅使用 API Key 的场景无需代理；不适用于 MCP 服务器开发、Claude Code hooks 或企业 HTTPS 代理穿透。文档中未提供具体的定价、性能数据或跨平台（非 macOS）支持说明。