# CC-proxy-GUI

**Repository Path**: azhw/cc-proxy-gui

## Basic Information

- **Project Name**: CC-proxy-GUI
- **Description**: 该仓库基于源码https://github.com/fuergaosi233/claude-code-proxy进行了gui的封装。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code Proxy

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

![Claude Code Proxy](demo.png)

## 功能特性

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

### GUI 桌面应用
- **图形化配置界面**：无需手动编辑 .env 文件，通过直观的界面管理所有配置
- **服务控制**：一键启动/停止代理服务，实时查看服务状态
- **实时日志查看**：内置日志查看器，实时显示服务运行日志
- **聊天测试**：内置聊天测试功能，快速验证代理配置是否正常
- **Claude 设置集成**：自动检测并更新 Claude Code 的 settings.json 文件，实现无缝集成
- **跨平台支持**：支持 Windows、macOS 和 Linux

## 快速开始

### 方式一：使用 GUI 桌面应用（推荐）

#### 1. 安装依赖

```bash
# 使用 UV（推荐）
uv sync

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

#### 2. 启动 GUI 应用

```bash
# 使用 UV
uv run start_gui.py

# 或直接运行
python start_gui.py
```

#### 3. 配置并启动

1. 在 GUI 的"配置"选项卡中填写您的 API 配置
2. 点击"保存配置"按钮
3. 点击"启动服务"按钮
4. GUI 会自动更新 Claude Code 的 settings.json 文件
5. 在"聊天测试"选项卡中测试代理是否正常工作

### 方式二：使用命令行

#### 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: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 中设置环境变量，或通过 GUI 应用进行可视化配置。

### GUI 配置界面

GUI 应用提供了三个主要选项卡：

#### 配置选项卡
- **OpenAI 配置**：API Key、Base URL、API Version
- **模型配置**：大模型（Opus）、中模型（Sonnet）、小模型（Haiku）
- **服务器配置**：主机、端口、超时时间
- **安全配置**：客户端验证密钥

#### 日志选项卡
- 实时显示服务运行日志
- 支持清除日志功能

#### 聊天测试选项卡
- 快速测试代理配置
- 支持自定义模型、API Key 和 Base URL
- 实时显示对话内容

### 环境变量

**必需：**

- `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` - Token 限制（默认：`4096`）
- `REQUEST_TIMEOUT` - 请求超时时间（秒，默认：`90`）

**自定义请求头：**

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

代理会自动在所有对目标 LLM 提供商的 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"
```

#### 本地模型（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"
```

#### 其他提供商

通过设置适当的 `OPENAI_BASE_URL`，可以使用任何 OpenAI 兼容的 API。

## 使用示例

### 基本聊天

```python
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": "你好！"}
        ]
    }
)
```

## 与 Claude Code 集成

### 使用 GUI 自动集成

GUI 应用会自动检测并更新 Claude Code 的 settings.json 文件：

1. 启动 GUI 应用
2. 在"配置"选项卡中完成配置
3. 点击"启动服务"按钮
4. GUI 会自动更新 `~/.claude/settings.json` 文件
5. 直接运行 `claude` 命令即可使用代理

如果 GUI 无法自动找到 settings.json 文件，会提示您手动选择。

### 手动集成

此代理设计为与 Claude Code CLI 无缝协作：

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

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

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

## 测试

测试代理功能：

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

## 开发

### 使用 UV

```bash
# 安装依赖
uv sync

# 运行服务器（命令行）
uv run claude-code-proxy

# 运行 GUI 应用
uv run start_gui.py

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

# 类型检查
uv run mypy src/
```

### GUI 开发

GUI 应用使用 PyQt6 构建，主要组件：

- **ConfigManager**：管理 .env 配置文件的读写
- **ServiceThread**：后台服务线程，处理代理服务的启动和停止
- **ConfigTab**：配置界面选项卡
- **LogTab**：日志查看选项卡
- **ChatTab**：聊天测试选项卡
- **SettingsManager**：管理 Claude settings.json 文件

### 项目结构

```
claude-code-proxy/
├── src/
│   ├── main.py                     # 主服务器
│   ├── api/                        # API 端点
│   ├── conversion/                 # 请求/响应转换
│   ├── core/                       # 核心功能
│   ├── gui/                        # GUI 桌面应用
│   │   ├── main_window.py          # 主窗口
│   │   └── settings_manager.py     # Claude 设置管理
│   └── models/                     # 数据模型
├── start_proxy.py                  # 命令行启动脚本
├── start_gui.py                    # GUI 启动脚本
├── .env.example                    # 配置模板
└── README.md                       # 本文件
```

## 性能

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

## 许可证

MIT License