Claude Code Proxy - 轻量级 Claude 代理切换工具

简介

轻量级 Claude API 反向代理工具，提供 Web UI 管理多个供应商，支持自动模型发现、即时切换等功能。

适用场景：无需修改 Claude Code 配置，在多个转发站之间快速切换。

拓展功能：测试模型健康（保持囤囤鼠的账户活跃）。

快速开始

复制配置文件

copy config.in.json config.json

编辑配置文件

打开 config.json，填入转发站信息。

启动代理

python ccproxy.py --config config.json

打开 Web UI

浏览器访问 http://127.0.0.1:3456 查看状态并管理 provider
使用 sk-your-local-ui-key 作为密码登录（用户名任意）

配置 Claude Code

修改 Claude Code 配置文件：

Windows: %USERPROFILE%\.claude\settings.json
macOS/Linux: ~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-local-ui-key",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456"
  }
}

修改后无需重启 Claude Code。

配置说明

config.json 结构

{
  "HOST": "0.0.0.0",
  "PORT": 3456,
  "APIKEY": "sk-your-local-ui-key",
  "Providers": [
    {
      "name": "example-provider1",
      "api_base_url": "https://api.example.com/v1/messages",
      "api_key": "sk-provider-key-1",
      "models": [
        "claude-sonnet-4-5-20250929",
        "claude-opus-4-5-20251101"
      ],
      "comment": "可选的备注信息"
    }
  ]
}

配置项说明

配置项	说明
`HOST`	代理服务器监听地址（通常使用 0.0.0.0 或 127.0.0.1）
`PORT`	代理服务器端口（默认 3456）
`APIKEY`	本地认证密钥 - 用于 Claude Code 连接（`ANTHROPIC_AUTH_TOKEN`）和 Web UI 登录
`Providers`	上游供应商列表，可配置多个

Provider 配置项

字段	说明
`name`	供应商名称（自定义，用于识别）
`api_base_url`	上游 API 地址（支持 /v1/messages、/v1/chat/completions、/v1/responses 端点）
`api_key`	上游 API 密钥
`models`	可用模型列表（可通过 Web UI 自动刷新）
`comment`	可选备注（用于记录供应商信息）

Web UI 使用

界面布局说明

Web UI 分为以下几个主要区域：

顶部状态栏：显示当前选中的 Provider 和 Reload Config 按钮
Providers 面板：显示所有 provider 列表，可点击切换和操作
Models 面板：显示当前 provider 的模型列表，可刷新和复制
HTTP Overrides 面板：配置 Token 传递方式和覆写规则
Provider Test 面板：测试 provider 可用性

按钮功能说明

1. 全局按钮

按钮	功能说明
`Reload Config`	重新加载 `config.json` 配置文件，无需重启代理

2. Providers 面板按钮

按钮	功能说明
`签到`	打开对应站点的签到页面领取额度（默认 `{domain}/console/personal`，可在 provider 中配置 `checkin` 字段自定义）
`settings.json`	复制当前 provider 的 Claude Code 配置到剪贴板（可直接粘贴到 `~/.claude/settings.json`）
`Token`	复制当前 provider 的 API Key 到剪贴板
`URL`	复制当前 provider 的 API Base URL 到剪贴板
`Select`	选择当前 provider 作为活动 provider（已选中时显示 Selected ）

3. Models 面板按钮

按钮	功能说明
`Refresh`	刷新当前 provider 的模型列表（从上游 `/v1/models` 获取）
`Copy`	复制 `/model xxx` 命令到剪贴板，粘贴到 Claude Code 切换模型

4. HTTP Overrides 面板按钮

此面板用于配置代理转发时的 HTTP 覆写规则，分为两个部分：

Token Configuration（Token 配置）

按钮	功能说明
`Default (Auto)`	使用默认的透传模式（自动替换 APIKEY）
`?token={token}`	将 Token 放在 URL 查询参数中（`token_in=query`）
`Authorization: Bearer {token}`	使用 Bearer Token 格式的 Authorization 头
`Authorization: {token}`	直接使用 Token 作为 Authorization 头的值
`x-api-key: {token}`	使用 x-api-key 头传递 Token

Override Presets（覆写预设）

按钮	功能说明
`Preset: Claude CLI`	应用 Claude Code 预设组合（Header + Request 覆写 + Query Params）
`Preset: OpenAI`	应用 OpenAI 预设组合（适用于 OpenAI 格式的端点）
`Reset Override`	清空所有覆写配置，恢复为透传模式
`Apply`	应用当前配置的 HTTP 覆写规则（所有 provider 共享）

5. Provider Test 面板按钮

按钮	功能说明
`Refresh & Test All`	重置测试状态 + 刷新所有 provider 的模型列表 + 测试所有 provider（后台执行）
`Retest Failed`	只测试失败的 provider（不刷新模型列表，速度快，后台执行）
`Test Selected`	测试当前选中的 provider（可在 Test Model 输入框中指定模型，后台执行）

使用技巧

💡 测试站点

在 config.json 中填写每个 provider 的 models 列表
点击 Reload Config 重新加载配置
重复点击 Retest Failed 直到所有节点成功

📊 查看日志

测试完成后，刷新页面可查看 Provider 名称颜色变化：绿色表示测试成功。

程序会输出每次请求与返回内容，用于分析测试失败的原因。

测试机制：请求体根据端点类型自动构造（/v1/messages 使用 Claude Messages 格式，/v1/chat/completions 使用 OpenAI Chat Completions 格式，/v1/responses 使用 OpenAI Responses 格式），自动应用对应的覆写预设（/v1/messages 使用 ClaudeCode 预设 + beta=true，/v1/chat/completions 和 /v1/responses 使用 OpenAI 预设 + Bearer 认证）。因为测试机制是通过模仿真实客户端发送请求，所以测试功能可用于保持账户活跃。

高级功能

1. HTTP 覆写（HTTP Overrides）

HTTP Overrides 功能允许你自定义代理转发时的请求头、请求体和查询参数，用于绕过某些站点的客户端检测或适配不同的 API 格式。

使用场景

场景 1：透传模式（默认）

适用于大多数情况，代理会自动替换客户端的 APIKEY 为 provider 的 api_key，保持其他请求内容不变。

配置：Token Placement 选择 Auto (Passthrough)

场景 2：模拟 Claude Code 客户端

某些 provider 需要完整的客户端特征才能通过验证，使用内置的 ClaudeCode 预设可以模拟真实的 Claude Code 客户端。

配置：点击 Preset: Claude CLI 按钮，然后点击 Apply

场景 3：OpenAI 格式端点

如果 provider 使用 OpenAI 格式的端点（/v1/chat/completions 或 /v1/responses），使用 OpenAI 预设可以正确转换请求格式和认证方式（Bearer token）。

配置：点击 Preset: OpenAI 按钮，然后点击 Apply

场景 4：自定义覆写

如果需要自定义请求头或请求体（如固定 IP、添加自定义字段），可以在 config.json 中定义自己的预设。

配置：参考下方"如何生成自定义覆写配置"章节

重要提示：

内置的 ClaudeCode 预设会完全覆盖请求头和请求体，仅用于 Provider Test 或转发非 Claude Code 的请求
正常使用 Claude Code 时，如需覆写（如固定 IP），应自定义预设仅覆盖部分字段（如 X-Real-IP、X-Forwarded-For），避免破坏工具调用等功能
HTTP Overrides 配置仅影响正常的代理转发，不影响 Provider Test 功能（测试会自动选择合适的配置）

可扩展设计

你可以在 config.json 中定义多个自定义预设，Web UI 会自动识别并在下拉列表中显示：

"HeaderOverrides": {
  "ClaudeCode": { ... },
  "MyCustomHeaders": {
    "User-Agent": "MyClient/1.0",
    "X-Custom-Header": "value"
  }
},
"RequestOverrides": {
  "ClaudeCode": { ... },
  "MyCustomRequest": {
    "max_tokens": 16000,
    "stream": false
  }
}

2. 如何生成自定义覆写配置

如果现有预设无法通过某些 provider 的检测，可以从实际请求日志中生成自定义覆写配置。

正常访问获取基准请求

在 Web UI 中将 Token Placement 设置为 Auto (Passthrough)，Header Override 和 Request Override 留空
点击 Apply 应用配置
使用 Claude Code 正常访问一次目标 provider

查看请求日志

打开 ccproxy.log 文件，找到刚才的请求记录，定位到 forward: upstream_headers 和 forward: request_body 部分。

使用 Claude Code 自动更新配置

复制以下提示词到 Claude Code，让 AI 自动分析日志并更新配置：

查看最新的 ccproxy.log 日志，对比当前 config.json 中 HeaderOverrides.ClaudeCode 和 RequestOverrides.ClaudeCode 的配置，以及 ccproxy.py 中测试请求的 model, messages 格式，找出日志中实际发送的请求与配置文件的差异，然后同时更新 config.json 和 ccproxy.py 使其与实际请求一致。

具体步骤：
1. 检查日志中最近的 "forward: upstream_headers" 部分，提取所有请求头字段
2. 检查日志中最近的 "forward: request_body" 部分，提取请求体中的特殊字段（如 system, tools, metadata, max_tokens, stream, thinking 等）
3. 对比 config.json 中现有的 HeaderOverrides.ClaudeCode 和 RequestOverrides.ClaudeCode 配置
4. 对比 ccproxy.py 中 _test_provider 方法的 request_data 格式（应仅包含 model, messages）
5. 更新 config.json 中缺失或不一致的字段（RequestOverrides.ClaudeCode 应包含 max_tokens, stream 等完整字段）
6. 更新 ccproxy.py 中的测试请求格式（仅保留 model, messages，其他字段移到 RequestOverrides）
7. 告诉我更新了哪些内容

在 Web UI 中应用新配置

点击 Reload Config 重新加载配置
选择 ClaudeCode 预设并点击 Apply
测试是否能正常访问 provider

3. 后台运行与状态持久化

后台运行（Linux）

使用提供的 run.sh 脚本管理后台运行：

./run.sh start    # 启动
./run.sh stop     # 停止
./run.sh restart  # 重启
./run.sh status   # 查看状态

日志文件：ccproxy.log | PID 文件：ccproxy.pid

状态持久化

代理会将当前选择的 Provider 和认证覆盖规则保存到 proxy_state.json。删除此文件会重置为第一个 Provider。