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

简介

轻量级 Claude API 反向代理工具，通过 Web 切换管理多个供应商，支持模型发现、快速复制、热重载配置。

适用场景：在多个公益站/转发站之间快速切换，无需重启 Claude Code。

快速开始

复制配置文件

copy config.in.json config.json

编辑配置文件

打开 config.json，填入你的供应商信息（详见下方配置说明）。

启动代理

python ccproxy.py --config config.json

配置 Claude Code

修改 Claude Code 配置文件，指向本地代理（详见下方 Claude Code 配置）。

打开 Web UI

浏览器访问 http://127.0.0.1:3456，使用 APIKEY 作为密码登录。

提示：首次使用建议先在 Web UI 中点击 Refresh 按钮，确保能��常获取上游模型。

配置说明

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 连接和 Web UI 登录
`Providers`	上游供应商列表，可配置多个

Provider 配置项

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

APIKEY 的双重作用：

作为 Claude Code 连接代理的认证密钥（ANTHROPIC_AUTH_TOKEN）
作为 Web UI 的登录密码（用户名任意）

Claude Code 配置

配置文件位置

Claude Code 的配置文件通常位于：

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

配置示例

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

重要：ANTHROPIC_AUTH_TOKEN 必须与 config.json 中的 APIKEY 一致，ANTHROPIC_BASE_URL 指向本地代理地址（HOST:PORT）。修改配置后需要重启 Claude Code。

Web UI 使用

浏览器访问 http://127.0.0.1:3456，使用 APIKEY 作为密码登录（用户名任意）。

主要功能

切换供应商：从下拉列表选择不同的 Provider，立即生效
刷新模型列表：点击 Refresh 按钮，从上游 /v1/models 获取最新模型列表
切换模型：选择模型后，点击 Copy 按钮复制 /model xxx 命令，粘贴到 Claude Code 即可切换
重载配置：修改 config.json 后，点击 Reload Config 按钮重新加载配置，无需重启代理

高级功能

HTTP 覆写（HTTP Overrides）

某些上游 API 需要特殊的请求头或请求体格式。在 Web UI 的 HTTP Overrides (Selected Provider) 面板中可以动态配置当前选中供应商的 HTTP 覆写规则：

Token Configuration（令牌配置）

配置项	说明	默认值
`Token Placement`	Token ��递方式：`Auto (Passthrough)` / `Query` / `Header` / `Both`	`Auto`
`Query Key`	Query 参数名（如 `?token=xxx` 中的 "token"）	`token`
`Header Key`	HTTP Header 名称	`Authorization`
`Header Value`	Header 值格式（`{token}` 会被替换为实际密钥）	`Bearer {token}`

Override Presets（覆写预设）

Header Override：选择预定义的请求头覆写（如伪装成 Claude CLI）
Request Override：选择预定义的请求体覆写（如移除 tools 字段）
Query Params：添加额外的 URL 查询参数（如 beta=true）

提供快捷按钮快速配置常见格式：?token={token}、Authorization: Bearer {token}、Authorization: {token}、x-api-key: {token}。修改后点击 Apply 按钮应用，配置会保存到 proxy_state.json。

后台运行（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。

常见问题

Q: Claude Code 连接失败？

A: 请检查：

ccproxy 是否正在运行
ANTHROPIC_AUTH_TOKEN 是否与 APIKEY 一致
ANTHROPIC_BASE_URL 地址是否正确（注意 HOST 和 PORT）
防火墙是否阻止了端口访问

Q: Web UI 无法登录？

A: 请确认：

密码是否为 config.json 中的 APIKEY
用户名不能为空（可以是任意值）
浏览器是否保存了错误的密码（尝试清除缓存）

Q: 刷新模型列表失败？

A: 可能原因：

上游 API 地址不正确
上游 API 密钥无效或过期
上游服务器不支持 /v1/models 端点
网络连接问题

Q: 切换 Provider 后 Claude Code 没反应？

A: 这是正常的。切换 Provider 只影响后续的新请求。当前正在进行的对话会继续使用之前的 Provider。建议开启新对话测试。

Q: 支持哪些上游 API？

A: 支持所有兼容 Claude API 格式的端点，包括：

Anthropic 官方 API
各类公益站/转发站
GLM 等兼容 Claude 格式的 API

注意：本项目不提供模型转换功能（如 OpenAI → Claude），仅支持原生 Claude 格式。

Q: 如何添加新的供应商？

A: 编辑 config.json，在 Providers 数组中添加新条目，然后在 Web UI 点击 Reload Config 按钮即可。

Q: 配置文件格式兼容性？

A: config.json 格式兼容 ccr 和 ccproxy，可通用。本项目不包含模型转换功能。