# Claude Code Gateway

**Repository Path**: energyaudit/Claude-Code-Gateway

## Basic Information

- **Project Name**: Claude Code Gateway
- **Description**: 打造一个企业级的、专为 Claude Code 优化的智能网关，兼具 CCR 的深度适配能力和企业网关的基础设施能力。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-05-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code Gateway

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.11+-blue.svg" alt="Python">
  <img src="https://img.shields.io/badge/FastAPI-0.115+-green.svg" alt="FastAPI">
  <img src="https://img.shields.io/badge/LiteLLM-1.40+-orange.svg" alt="LiteLLM">
  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
</p>

> 企业级智能 API 网关，专为 Claude Code 优化设计。支持多 API Key 负载均衡、智能路由、多用户隔离和会话管理。

## 特性

| 特性 | 描述 |
|------|------|
| **智能路由** | 根据请求特征（上下文长度、任务类型、工具调用）自动选择最优模型 |
| **多 Key 负载均衡** | 加权轮询 + 会话亲和性，支持 DeepSeek/Gemini/OpenRouter/Ollama |
| **多用户隔离** | 基于 Session ID 的用户隔离和配额控制 |
| **流式响应** | 低延迟 SSE 流式转发，支持工具调用 |
| **限流控制** | 滑动窗口算法，支持用户/模型多级限流 |
| **会话管理** | 多轮对话上下文保持，自动管理上下文窗口 |
| **监控告警** | Prometheus 指标、Grafana 仪表板、实时健康检查 |
| **LiteLLM 集成** | 统一的多提供商接口，自动格式转换 |

## 架构预览

```
┌─────────────────────────────────────────────────────────────┐
│                    Claude Code Client                        │
└────────────────────────┬────────────────────────────────────┘
                         │ Anthropic API
                         ▼
┌─────────────────────────────────────────────────────────────┐
│               Claude Code Gateway (FastAPI)                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Auth       │  │   Router     │  │  Rate Limit  │     │
│  │  Middleware  │  │   Engine     │  │   Limiter    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │Load Balancer │  │    LiteLLM   │  │  Session     │     │
│  │              │  │     SDK      │  │  Manager     │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────────────────────┬────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
    ┌─────────┐    ┌─────────┐    ┌─────────┐
    │ DeepSeek│    │  Gemini │    │ OpenRouter│
    └─────────┘    └─────────┘    └─────────┘
```

## 快速开始

### 安装

```bash
# 克隆项目
git clone https://gitee.com/energyaudit/Claude-Code-Gateway.git
cd Claude-Code-Gateway

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入你的 API Keys
```

### 启动

```bash
# 开发模式
python -m gateway.main

# 或指定端口
python -m gateway.main --port 5000
```

### 使用

```bash
# 健康检查
curl http://localhost:5000/health

# 聊天补全
curl -X POST http://localhost:5000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: user123" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# 流式响应
curl -X POST http://localhost:5000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: user123" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Write a story"}],
    "stream": true
  }'
```

## 智能路由

Claude Code Gateway 自动根据请求特征选择最优模型：

| 场景 | 检测条件 | 路由模型 |
|------|---------|---------|
| **长上下文** | tokens > 60,000 | Gemini 2.0 Flash |
| **推理任务** | 包含 "plan"/"think" | DeepSeek Reasoner |
| **工具调用** | 有 tools 参数 | Claude 3.5 Sonnet |
| **网页搜索** | 包含 "search" 关键词 | Gemini 2.0 Flash |
| **用户指定** | `/model xxx` 命令 | 用户选择 |
| **默认** | 其他 | DeepSeek Chat |

### 自定义路由

在 `config.yaml` 中配置：

```yaml
routing:
  default: "deepseek/deepseek-chat"
  think: "deepseek/deepseek-reasoner"
  long_context: "gemini/gemini-2.0-flash-exp"
  long_context_threshold: 60000
```

## 多 Key 负载均衡

配置多个 API Keys 进行负载均衡：

```bash
# .env
DEEPSEEK_API_KEYS=sk-key1,sk-key2,sk-key3
```

特性：
- **加权轮询**：自动分配请求
- **会话亲和性**：同一会话使用同一 Key
- **健康检查**：自动跳过不健康的 Key

## Docker 部署

```bash
# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f gateway

# 停止服务
docker-compose down
```

## 监控

### Prometheus 指标

```
curl http://localhost:5000/metrics
```

### Grafana 仪表板

访问 http://localhost:3000 查看：
- 请求速率
- 延迟分布 (P50/P95/P99)
- 错误率
- Token 使用量

## 配置参考

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GATEWAY_PORT` | 服务端口 | 5000 |
| `APIKEY` | 网关认证 Key | - |
| `DEEPSEEK_API_KEY` | DeepSeek Key | - |
| `GEMINI_API_KEY` | Gemini Key | - |
| `REDIS_URL` | Redis 连接 | redis://localhost:6379/0 |
| `LITELLM_TIMEOUT` | 请求超时 (秒) | 120 |
| `DEFAULT_RATE_LIMIT` | 默认限流 (RPM) | 40 |

完整配置见 [config.yaml.example](./config.yaml.example)

## 项目结构

```
gateway/
├── main.py                 # FastAPI 入口
├── config.py               # 配置管理
├── api_router.py           # API 路由端点
│
├── core/                   # 核心模块
│   ├── proxy.py            # 代理核心逻辑
│   ├── load_balancer.py     # 负载均衡器
│   ├── rate_limiter.py     # 限流器
│   └── session_manager.py  # 会话管理
│
├── routing/                # 智能路由
│   ├── smart_router.py     # 路由决策引擎
│   ├── context_analyzer.py # 上下文分析
│   └── performance_store.py # 性能指标
│
├── user/                   # 用户管理
│   ├── user_manager.py     # 用户配置
│   └── quota_manager.py    # 配额管理
│
├── middleware/             # 中间件
│   └── auth.py             # 认证
│
├── models/                 # 数据模型
│   └── anthropic.py        # Anthropic API 模型
│
└── utils/                  # 工具类
    ├── token_counter.py    # Token 计数
    └── metrics.py          # Prometheus 指标
```

## 文档

- [设计文档](./design_docs/CLAUDE-CODE-GATEWAY-DESIGN.md) - 架构设计与核心模块详解
- [部署指南](./design_docs/DEPLOYMENT.md) - Docker/Kubernetes 部署详细说明
- [快速参考](./design_docs/QUICK-REFERENCE.md) - 命令速查
- [架构决策](./design_docs/ARCHITECTURE-DECISIONS.md) - ADR 记录

## 技术栈

- **FastAPI** - 高性能异步 Web 框架
- **LiteLLM** - 统一的多 LLM 提供商接口
- **Redis** - 分布式缓存和限流存储
- **Prometheus** - 指标收集和告警
- **Grafana** - 可视化监控仪表板

## License

MIT License - 详见 [LICENSE](./LICENSE) 文件

## 贡献

欢迎提交 Issue 和 Pull Request！

## 致谢

本项目参考了以下优秀项目：

- [Claude Code Router (CCR)](design_docs/claude-code-router-main/) - Claude Code 请求路由
- [LiteLLM](https://github.com/BerriAI/litellm) - 统一 LLM 调用接口