# Claude Code Proxy

**Repository Path**: tufeiping/claude-code-proxy

## Basic Information

- **Project Name**: Claude Code Proxy
- **Description**: fork from https://github.com/fuergaosi233/claude-code-proxy.git
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-12-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code 代理服务

一个代理服务器，使 **Claude Code** 能够与 OpenAI 兼容的 API 提供商协作。将 Claude API 请求转换为 OpenAI API 调用，让你可以通过 Claude Code CLI 使用各种 LLM 提供商。

> 该项目`fork`自 [ https://github.com/fuergaosi233/claude-code-proxy.git](https://github.com/fuergaosi233/claude-code-proxy.git) 并在其上做了部分调整

![Claude Code Proxy](demo.png)

## 功能特性

- **完整 Claude API 兼容性**: 完全支持 `/v1/messages` 端点
- **多提供商支持**: OpenAI、Azure OpenAI、本地模型 (Ollama) 以及任何 OpenAI 兼容 API
- **智能模型映射**: 通过环境变量配置 BIG 和 SMALL 模型
- **函数调用**: 完整的工具使用支持和正确转换
- **流式响应**: 实时 SSE 流式支持
- **图片支持**: Base64 编码的图片输入
- **自定义请求头**: 自动为 API 请求注入自定义 HTTP 请求头
- **错误处理**: 完善的错误处理和日志记录
- **提供商能力配置**: 根据提供商支持情况灵活过滤功能（如图片、工具调用）
- **对话日志记录**: 自动记录所有转发的对话内容（问题-回复）到本地 JSONL 文件
- **日志查看工具**: 提供 CLI 工具查看、搜索、过滤和分析对话日志

## 快速开始

### 1. 安装依赖

```bash
# 使用 UV (推荐)
uv sync

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

### 2. 配置

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

### 3. 启动服务

```bash
# 直接运行
python start_proxy.py

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

# 或使用 docker compose
docker compose up -d
```

### 4. 与 Claude Code 集成

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

# 如果代理中已设置 ANTHROPIC_API_KEY:
ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_API_KEY="exact-matching-key" claude
```

## 环境变量配置

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

### 必需变量

- `OPENAI_API_KEY` - 目标提供商的 API 密钥

### 安全相关

- `ANTHROPIC_API_KEY` - 期望的 Anthropic API 密钥用于客户端验证
  - 如果设置，客户端必须提供完全匹配的 API 密钥才能访问代理
  - 如果未设置，任何 API 密钥都会被接受

### 模型配置

- `BIG_MODEL` - Claude opus 请求使用的模型 (默认: `gpt-4o`)
- `MIDDLE_MODEL` - Claude sonnet 请求使用的模型 (默认: `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` - 服务器端口 (默认: `4000`)
- `LOG_LEVEL` - 日志级别 (默认: `WARNING`)

### 日志记录

- `ENABLE_LOGGING` - 是否启用详细对话日志记录 (默认: `true`)
  - 设置为 `false` 在生产环境中禁用，以提高性能（减少 I/O 开销）
  - 启用时会记录所有对话到 `logs/conversations.jsonl`

### 性能相关

- `MAX_TOKENS_LIMIT` - Token 限制 (默认: `4096`)
- `REQUEST_TIMEOUT` - 请求超时时间，单位秒 (默认: `90`)

### 提供商能力配置

- `PROVIDER_SUPPORTS_IMAGES` - 提供商是否支持图片输入 (默认: `true`)
- `PROVIDER_SUPPORTS_TOOLS` - 提供商是否支持工具/函数调用 (默认: `true`)

某些提供商（如 DeepSeek）可能不支持所有功能。使用这些配置来禁用不支持的功能，代理会自动过滤这些内容而不会报错。

### 自定义请求头

- `CUSTOM_HEADER_*` - 为 API 请求添加自定义请求头 (例如 `CUSTOM_HEADER_ACCEPT`、`CUSTOM_HEADER_AUTHORIZATION`)
  - 在 `.env` 文件中取消注释以启用自定义请求头

### 自定义请求头配置

通过设置带有 `CUSTOM_HEADER_` 前缀的环境变量来为 API 请求添加自定义请求头：

```bash
# 取消注释以启用自定义请求头
# 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`

### 使用示例

```bash
# 基础配置
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"
```

代理会自动在所有 API 请求中包含这些请求头。

### 模型映射

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

| Claude 请求              | 映射到        | 环境变量              |
| ----------------------- | ------------- | -------------------- |
| 包含 "haiku"            | `SMALL_MODEL` | 默认值: `gpt-4o-mini` |
| 包含 "sonnet"           | `MIDDLE_MODEL`| 默认值: `BIG_MODEL`   |
| 包含 "opus"             | `BIG_MODEL`   | 默认值: `gpt-4o`      |

### 提供商配置示例

#### OpenAI

```bash
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

```bash
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"
```

#### DeepSeek

DeepSeek 不支持图片输入，需要禁用图片功能：

```bash
OPENAI_API_KEY="sk-your-deepseek-api-key"
OPENAI_BASE_URL="https://api.deepseek.com/v1"
BIG_MODEL="deepseek-chat"
MIDDLE_MODEL="deepseek-chat"
SMALL_MODEL="deepseek-chat"
# 关键配置：禁用图片支持
PROVIDER_SUPPORTS_IMAGES=false
PROVIDER_SUPPORTS_TOOLS=true
```

#### 本地模型 (Ollama)

```bash
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"
# Ollama 可能不支持所有功能
PROVIDER_SUPPORTS_IMAGES=false
PROVIDER_SUPPORTS_TOOLS=false
```

#### 其他提供商

任何 OpenAI 兼容的 API 都可以通过设置合适的 `OPENAI_BASE_URL` 来使用。

## 使用示例

### 基础聊天

```python
import httpx

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

### 使用图片

```python
import httpx
import base64

with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

response = httpx.post(
    "http://localhost:4000/v1/messages",
    json={
        "model": "claude-3-5-sonnet-20241022",
        "max_tokens": 100,
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "分析这个图片"},
                    {
                        "type": "image",
                        "source": {
                            "type": "base64",
                            "media_type": "image/png",
                            "data": image_data
                        }
                    }
                ]
            }
        ]
    }
)
```

> **注意**: 某些提供商（如 DeepSeek）不支持图片输入。使用这些提供商时，需要设置 `PROVIDER_SUPPORTS_IMAGES=false`，代理会自动过滤图片内容而不会报错。

## 对话日志记录

代理会自动记录所有转发的对话内容到 `logs/conversations.jsonl` 文件，用于审计和分析。

### 启用/禁用日志

日志记录默认启用。若要在生产环境中提高性能，可禁用详细日志：

```bash
# 在 .env 中配置
ENABLE_LOGGING="true"   # 启用日志（默认）
ENABLE_LOGGING="false"  # 禁用日志以提高性能
```

**性能影响**:
- 启用日志时，每次请求会进行文件 I/O 操作，在高并发下可能降低吞吐量 20-40%
- 禁用日志可显著提升性能，特别是在高并发场景（100+ req/s）下可提升 30-50%

### 日志文件位置

- **日志目录**: `./logs/`
- **日志文件**: `./logs/conversations.jsonl`
- **格式**: JSONL（每行一条记录）

### 日志内容示例

```json
{
  "timestamp": "2025-11-26T08:17:35.123456",
  "request_id": "req_abc123",
  "model": "gpt-4o",
  "user_content": "Hello, analyze this image",
  "assistant_content": "I see an image with...",
  "total_tokens": 156,
  "status": "success"
}
```

### 查看日志

使用提供的日志查看工具：

```bash
# 查看最新的 10 条对话
python tools/view_conversations.py --latest 10

# 搜索包含特定关键词的对话
python tools/view_conversations.py --search "image"

# 按模型过滤
python tools/view_conversations.py --model "gpt-4o"

# 统计信息
python tools/view_conversations.py --stats

# 导出为 CSV
python tools/view_conversations.py --export output.csv
```

### 日志功能特点

- ✅ **自动记录**: 启用时无需配置，所有对话自动记录
- ✅ **完整内容**: 记录实际的对话内容（文本、图片说明、工具调用等）
- ✅ **智能截断**: 大型内容自动截断（50KB 限制）防止日志文件过大
- ✅ **JSONL 格式**: 便于解析和分析
- ✅ **请求追踪**: 使用 `request_id` 关联请求和响应
- ✅ **性能优化**: 可通过 `ENABLE_LOGGING="false"` 禁用以提高性能

## 图片支持详解

### 支持的图片格式

代理支持通过 Base64 编码的图片输入：

- `image/jpeg` - JPEG 格式
- `image/png` - PNG 格式
- `image/gif` - GIF 格式
- `image/webp` - WebP 格式

### 使用图片的步骤

1. **编码图片**: 将图片转换为 Base64 格式

```python
import base64

with open("photo.jpg", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")
```

2. **构建消息**: 在消息中包含图片块

```python
{
    "role": "user",
    "content": [
        {"type": "text", "text": "描述一下这个图片"},
        {
            "type": "image",
            "source": {
                "type": "base64",
                "media_type": "image/jpeg",
                "data": image_data
            }
        }
    ]
}
```

3. **发送请求**: 正常发送 API 请求

### 提供商图片支持矩阵

| 提供商 | 图片支持 | 配置 | 说明 |
|--------|---------|------|------|
| OpenAI | ✅ 支持 | `PROVIDER_SUPPORTS_IMAGES=true` | 完全支持 |
| Claude | ✅ 支持 | `PROVIDER_SUPPORTS_IMAGES=true` | 完全支持 |
| Azure OpenAI | ✅ 支持 | `PROVIDER_SUPPORTS_IMAGES=true` | 完全支持 |
| DeepSeek | ❌ 不支持 | `PROVIDER_SUPPORTS_IMAGES=false` | 自动过滤 |
| Ollama | ❌ 不支持 | `PROVIDER_SUPPORTS_IMAGES=false` | 自动过滤 |

### 处理不支持的图片请求

当使用不支持图片的提供商（如 DeepSeek）且客户端发送包含图片的请求时：

1. 代理自动检测 `PROVIDER_SUPPORTS_IMAGES=false`
2. 自动过滤请求中的图片块
3. 保留文本内容
4. 向提供商发送纯文本请求
5. 日志中记录警告信息

**示例日志输出**:
```
WARNING - Provider does not support images. Skipping image content.
```

### 故障排除

**问题**: 发送包含图片的请求返回 400 错误

**解决方案**:
1. 检查你使用的提供商是否支持图片
2. 如果不支持，在 `.env` 中添加: `PROVIDER_SUPPORTS_IMAGES=false`
3. 重启代理后重试

## 与 Claude Code 集成

该代理设计用于与 Claude Code CLI 无缝协作：

```bash
# 启动代理
python start_proxy.py

# 使用代理运行 Claude Code
ANTHROPIC_BASE_URL=http://localhost:4000 claude

# 或永久设置
export ANTHROPIC_BASE_URL=http://localhost:4000
claude
```

## 测试

测试代理功能：

```bash
# 运行综合测试
python src/test_claude_to_openai.py
```

## 开发

### 使用 UV

```bash
# 安装依赖
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                  # 启动脚本
├── docs/                           # 文档
│   ├── API-MANUAL.md              # API 接口文档
│   ├── PROVIDER_CONFIGURATION.md  # 提供商配置指南
│   └── ...
├── .env.example                    # 配置模板
└── README.md                       # 英文文档
```

## 性能

- **异步/等待** 支持高并发
- **连接池** 提高效率
- **流式支持** 实时响应
- **可配置超时** 和重试机制
- **智能错误处理** 详细日志记录

## 许可证

[MIT License](./LICENSE)

## 相关文档

- [API 接口文档](./docs/API-MANUAL.md) - 详细的 Claude 和 OpenAI API 对比
- [提供商配置指南](./docs/PROVIDER_CONFIGURATION.md) - 不同提供商的配置说明
- [英文版本](./README.md) - English version