Claude Code Fallback

中文 | English

API 代理工具，为 Claude Code 提供自动 fallback 能力。当 API 调用遇到超时、速率限制(429)、服务端错误(5xx) 时，自动切换到备用 endpoint。

特性

• 🔄 自动 Fallback - 检测可恢复错误，自动切换到备用 endpoint
• ❄️ 冷却机制 - endpoint 失败后冷却期间跳过，稳定使用健康节点
• ⏱️ 智能重试 - 指数退避 + Retry-After 头支持
• 🌊 SSE 流式代理 - 完整支持流式响应
• 📊 监控端点 - Prometheus 格式的 /metrics 端点
• ⚙️ 灵活配置 - YAML 配置文件 + 环境变量覆盖

安装

从 npm 安装（推荐）：

npm install -g claude-code-fallback

从 GitCode 克隆安装：

# 克隆仓库
git clone [email protected]:air9/claude-code-fallback.git
cd claude-code-fallback

# 安装依赖并构建
npm install
npm run build

# 全局链接（开发推荐）
npm link

或者直接从 git 安装：

npm install -g git+ssh://[email protected]:air9/claude-code-fallback.git

快速开始

1. 创建配置文件：

mkdir -p ~/.claude-code-fallback
vim ~/.claude-code-fallback/config.yaml

2. 启动后台服务：

ccf start        # 后台启动
ccf dev          # 前台启动（开发调试）

2. 管理服务：

ccf status       # 查看状态
ccf logs         # 查看日志
ccf stop         # 停止服务

3. 设置环境变量（让 Claude Code 使用代理）：

export ANTHROPIC_BASE_URL=http://127.0.0.1:8765

4. 正常使用 Claude Code

配置

配置文件

创建 ~/.claude-code-fallback/config.yaml：

# 查看示例配置
cat $(npm root -g)/claude-code-fallback/config.example.yaml

# 创建配置文件
mkdir -p ~/.claude-code-fallback
cp $(npm root -g)/claude-code-fallback/config.example.yaml ~/.claude-code-fallback/config.yaml
# 或编辑配置
vim ~/.claude-code-fallback/config.yaml

最小配置示例：

endpoints:
  - name: anthropic
    baseUrl: https://api.anthropic.com
    apiKey: ${ANTHROPIC_API_KEY}

server:
  port: 8765

环境变量

| 变量 | 说明 | |------|------| | CLAUDE_FALLBACK_ENDPOINTS | JSON 数组或逗号分隔的 URL 列表 | | CLAUDE_FALLBACK_PORT | 代理服务器端口 | | CLAUDE_FALLBACK_HOST | 代理服务器主机 | | CLAUDE_FALLBACK_LOG_LEVEL | 日志级别 (trace/debug/info/warn/error) | | ANTHROPIC_API_KEY | 默认 API key |

CLI 选项

claude-code-fallback [options]

选项:
  --config, -c <path>     配置文件路径
  --port, -p <number>     代理服务器端口 (默认: 8765)
  --host, -h <host>       代理服务器主机 (默认: 127.0.0.1)
  --log-level <level>     日志级别
  --help                  显示帮助信息

端点

| 端点 | 说明 | |------|------| | GET /health | 健康检查 | | GET /metrics | Prometheus 格式指标 | | * | 代理到 Anthropic API |

错误处理

可恢复错误（触发 fallback）

• HTTP 429 (Too Many Requests)
• HTTP 500, 502, 503, 504 (Server Errors)
• 网络超时
• 连接被拒绝 (ECONNREFUSED)
• DNS 解析失败 (ENOTFOUND)

不可恢复错误（直接返回）

• HTTP 400 (Bad Request)
• HTTP 401 (Unauthorized)
• HTTP 403 (Forbidden)
• HTTP 404 (Not Found)

配置选项

retry 重试策略

| 选项 | 默认值 | 说明 | |------|--------|------| | enabled | true | 是否启用重试 | | initialDelay | 1000 | 首次重试等待时间 (ms) | | maxDelay | 60000 | 最大等待时间 (ms) | | backoffFactor | 2 | 退避因子 | | maxRetries | 3 | 每个 endpoint 最大重试次数 | | cooldownSeconds | 300 | endpoint 失败后冷却时间 (秒) |

冷却机制：当 endpoint 失败后进入冷却期，期间跳过该 endpoint，优先使用健康的备用节点。冷却结束后才重新尝试。

server 服务器配置

| 选项 | 默认值 | 说明 | |------|--------|------| | port | 8765 | 代理端口 | | host | 127.0.0.1 | 监听地址 |

logging 日志配置

| 选项 | 默认值 | 说明 | |------|--------|------| | level | info | 日志级别 | | format | json | 输出格式 (json/pretty) | | redactKeys | true | 是否脱敏 API key |

监控示例

# 健康检查
curl http://127.0.0.1:8765/health

# Prometheus 指标
curl http://127.0.0.1:8765/metrics

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 测试
npm test

License

MIT