Claude Code 代理

一个代理服务器，使 Claude Code 能够与兼容 OpenAI 的 API 提供商协同工作。它会将 Claude API 请求转换为 OpenAI API 调用，从而允许您通过 Claude Code CLI 使用各种 LLM 提供商。

功能特性

• 完全兼容 Claude API：完整支持 /v1/messages 端点
• 多提供商支持：OpenAI、Azure OpenAI、本地模型（Ollama）以及任何兼容 OpenAI 的 API
• 智能模型映射：通过环境变量配置 BIG 和 SMALL 模型
• 函数调用：完整支持工具使用，并进行正确转换
• 流式响应：实时 SSE 流式传输支持
• 图像支持：Base64 编码的图像输入
• 自定义头部：自动注入用于 API 请求的自定义 HTTP 头部
• 错误处理：全面的错误处理和日志记录

快速开始

1. 安装依赖

# 使用 UV（推荐）
uv sync

# 或者使用 pip
pip install -r requirements.txt

2. 配置

cp .env.example .env
# 编辑 .env 文件并添加您的 API 配置
# 注意：环境变量会自动从 .env 文件加载

3. 启动服务器

# 直接运行
python start_proxy.py

# 或者使用 UV
uv run claude-code-proxy

# 或者使用 Docker Compose
docker compose up -d

4. 与 Claude Code 一起使用

# 如果代理中未设置 ANTHROPIC_API_KEY：
ANTHROPIC_BASE_URL=http://localhost:8082 ANTHROPIC_API_KEY="any-value" claude

# 如果代理中设置了 ANTHROPIC_API_KEY：
ANTHROPIC_BASE_URL=http://localhost:8082 ANTHROPIC_API_KEY="exact-matching-key" claude

配置说明

应用程序会使用 python-dotenv 自动从项目根目录下的 .env 文件加载环境变量。您也可以直接在 shell 中设置环境变量。

环境变量

必填项：

• OPENAI_API_KEY - 您的目标提供商的 API 密钥

安全性：

• ANTHROPIC_API_KEY - 用于客户端验证的预期 Anthropic API 密钥
  • 如果已设置，客户端必须提供此确切的 API 密钥才能访问代理
  • 如果未设置，任何 API 密钥都将被接受

模型配置：

• BIG_MODEL - 用于 Claude opus 请求的模型（默认：gpt-4o）
• MIDDLE_MODEL - 用于 Claude opus 请求的模型（默认：gpt-4o）
• SMALL_MODEL - 用于 Claude haiku 请求的模型（默认：gpt-4o-mini）

API 配置：

• OPENAI_BASE_URL - API 基础 URL（默认：https://api.openai.com/v1）

服务器设置：

• HOST - 服务器主机（默认：0.0.0.0）
• PORT - 服务器端口（默认：8082）
• LOG_LEVEL - 日志级别（默认：WARNING）

性能：

• MAX_TOKENS_LIMIT - 令牌限制（默认：4096）
• REQUEST_TIMEOUT - 请求超时时间，单位为秒（默认：90）

自定义头部：

• CUSTOM_HEADER_* - 用于 API 请求的自定义头部（例如：CUSTOM_HEADER_ACCEPT、CUSTOM_HEADER_AUTHORIZATION）
  • 在 .env 文件中取消注释以启用自定义头部

自定义头部配置

通过设置以 CUSTOM_HEADER_ 为前缀的环境变量，您可以为 API 请求添加自定义头部：

# 取消注释以启用自定义头部
# CUSTOM_HEADER_ACCEPT="application/jsonstream"
# CUSTOM_HEADER_CONTENT_TYPE="application/json"
# CUSTOM_HEADER_USER_AGENT="your-app/1.0.0"
# CUSTOM_HEADER_AUTHORIZATION="Bearer your-token"
# CUSTOM_HEADER_X_API_KEY="your-api-key"
# CUSTOM_HEADER_X_CLIENT_ID="your-client-id"
# CUSTOM_HEADER_X_CLIENT_VERSION="1.0.0"
# CUSTOM_HEADER_X_REQUEST_ID="unique-request-id"
# CUSTOM_HEADER_X_TRACE_ID="trace-123"
# CUSTOM_HEADER_X_SESSION_ID="session-456"

头部转换规则

以 CUSTOM_HEADER_ 为前缀的环境变量会自动转换为 HTTP 头部：

• 环境变量：CUSTOM_HEADER_ACCEPT

• HTTP 头部：ACCEPT

• 环境变量：CUSTOM_HEADER_X_API_KEY

• HTTP 头部：X-API-KEY

• 环境变量：CUSTOM_HEADER_AUTHORIZATION

• HTTP 头部：AUTHORIZATION

支持的头部类型

• 内容类型：ACCEPT、CONTENT-TYPE
• 认证：AUTHORIZATION、X-API-KEY
• 客户端标识：USER-AGENT、X-CLIENT-ID、X-CLIENT-VERSION
• 追踪：X-REQUEST-ID、X-TRACE-ID、X-SESSION-ID

使用示例

# 基本配置
OPENAI_API_KEY="sk-your-openai-api-key-here"
OPENAI_BASE_URL="https://api.openai.com/v1"

# 启用自定义头部（根据需要取消注释）
CUSTOM_HEADER_ACCEPT="application/jsonstream"
CUSTOM_HEADER_CONTENT_TYPE="application/json"
CUSTOM_HEADER_USER_AGENT="my-app/1.0.0"
CUSTOM_HEADER_AUTHORIZATION="Bearer my-token"

代理会自动将这些头部包含在所有针对目标 LLM 提供商的 API 请求中。

模型映射

代理会将 Claude 模型请求映射到您配置的模型：

Claude 请求	映射到	环境变量
包含 "haiku" 的模型	SMALL_MODEL	默认：gpt-4o-mini
包含 "sonnet" 的模型	MIDDLE_MODEL	默认：BIG_MODEL
包含 "opus" 的模型	BIG_MODEL	默认：gpt-4o

提供商示例

OpenAI

OPENAI_API_KEY="sk-your-openai-key"
OPENAI_BASE_URL="https://api.openai.com/v1"
BIG_MODEL="gpt-4o"
MIDDLE_MODEL="gpt-4o"
SMALL_MODEL="gpt-4o-mini"

Azure OpenAI

OPENAI_API_KEY="your-azure-key"
OPENAI_BASE_URL="https://your-resource.openai.azure.com/openai/deployments/your-deployment"
BIG_MODEL="gpt-4"
MIDDLE_MODEL="gpt-4"
SMALL_MODEL="gpt-35-turbo"

本地模型（Ollama）

OPENAI_API_KEY="dummy-key"  # 必需，但可以是假的
OPENAI_BASE_URL="http://localhost:11434/v1"
BIG_MODEL="llama3.1:70b"
MIDDLE_MODEL="llama3.1:70b"
SMALL_MODEL="llama3.1:8b"

其他提供商

只需设置相应的 OPENAI_BASE_URL，即可使用任何兼容 OpenAI 的 API。

使用示例

基本聊天

import httpx

response = httpx.post(
    "http://localhost:8082/v1/messages",
    json={
        "model": "claude-3-5-sonnet-20241022",  # 映射到 MIDDLE_MODEL
        "max_tokens": 100,
        "messages": [
            {"role": "user", "content": "Hello!"}
        ]
    }
)

与 Claude Code 的集成

该代理专为与 Claude Code CLI 无缝协作而设计：

# 启动代理
python start_proxy.py

# 使用 Claude Code 并连接代理
ANTHROPIC_BASE_URL=http://localhost:8082 claude

# 或者永久设置
export ANTHROPIC_BASE_URL=http://localhost:8082
claude

测试

测试代理功能：

# 运行全面测试
python src/test_claude_to_openai.py

开发

使用 UV

# 安装依赖
uv sync

# 运行服务器
uv run claude-code-proxy

# 格式化代码
uv run black src/
uv run isort src/

# 类型检查
uv run mypy src/

项目结构

claude-code-proxy/
├── src/
│   ├── main.py                     # 主服务器
│   ├── test_claude_to_openai.py    # 测试脚本
│   └── [其他模块...]
├── start_proxy.py                  # 启动脚本
├── .env.example                    # 配置模板
└── README.md                       # 本文档

性能

• 使用 async/await 实现高并发
• 采用 连接池 提升效率
• 支持 流式传输，实现实时响应
• 可配置的 超时 和 重试机制
• 具备 智能错误处理 并记录详细日志

许可证

MIT 许可证

Claude Code Proxy 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)
• Python 版本：Python 3.8+
• 包管理工具：推荐使用 uv (速度更快)，也可使用 pip
• API Key：拥有一个 OpenAI 兼容的 API Key（如 OpenAI 官方、Azure OpenAI、Ollama 本地模型等）

安装步骤

1. 克隆项目并安装依赖

推荐使用 uv 进行依赖管理，以获得更快的安装速度。

# 使用 UV (推荐)
git clone <repository-url>
cd claude-code-proxy
uv sync

# 或者使用 pip
pip install -r requirements.txt

2. 配置环境变量

复制示例配置文件并根据您的需求进行修改。

cp .env.example .env

编辑 .env 文件，填入必要的配置信息：

# .env 文件示例内容

# [必填] 目标提供商的 API Key
OPENAI_API_KEY="sk-your-api-key-here"

# [可选] 目标提供商的基础 URL (默认为 OpenAI 官方)
# OpenAI: https://api.openai.com/v1
# Azure: https://your-resource.openai.azure.com/openai/deployments/your-deployment
# Ollama: http://localhost:11434/v1
OPENAI_BASE_URL="https://api.openai.com/v1"

# [可选] 模型映射配置 (将 Claude 模型映射到实际可用的模型)
BIG_MODEL="gpt-4o"        # 对应 Claude Opus/Sonnet 请求
MIDDLE_MODEL="gpt-4o"     # 对应 Claude Sonnet 请求
SMALL_MODEL="gpt-4o-mini" # 对应 Claude Haiku 请求

# [可选] 客户端验证密钥 (若设置，调用代理时必须提供此密钥)
# ANTHROPIC_API_KEY="any-secret-key"

基本使用

1. 启动代理服务

您可以选择直接运行 Python 脚本或使用 uv 启动。

# 方式一：直接运行
python start_proxy.py

# 方式二：使用 UV
uv run claude-code-proxy

# 方式三：使用 Docker Compose (如果已安装 Docker)
docker compose up -d

默认情况下，服务将运行在 http://0.0.0.0:8082。

2. 配合 Claude Code CLI 使用

启动代理后，通过设置环境变量将 claude 命令指向本地代理服务。

场景 A：未在 .env 中设置 ANTHROPIC_API_KEY 此时代理接受任意 Key，只需指定 Base URL：

ANTHROPIC_BASE_URL=http://localhost:8082 ANTHROPIC_API_KEY="any-value" claude

场景 B：已在 .env 中设置了 ANTHROPIC_API_KEY 此时必须提供完全匹配的 Key 才能通过验证：

ANTHROPIC_BASE_URL=http://localhost:8082 ANTHROPIC_API_KEY="exact-matching-key" claude

3. 验证功能

您也可以通过简单的 HTTP 请求测试代理是否正常工作（需安装 httpx 或使用 curl）：

import httpx

response = httpx.post(
    "http://localhost:8082/v1/messages",
    json={
        "model": "claude-3-5-sonnet-20241022",  # 会自动映射为配置的 MIDDLE_MODEL
        "max_tokens": 100,
        "messages": [
            {"role": "user", "content": "Hello!"}
        ]
    }
)
print(response.json())

现在，您可以像使用原生 Claude 一样，通过该代理调用各种 OpenAI 兼容的大模型服务了。