Claude Relay RS

English | 简体中文

高性能 AI API 中转服务，使用 Rust 实现。支持 Claude、Gemini、OpenAI Responses (Codex) 多平台账户管理与智能调度。

✨ 功能特性

多平台支持

平台	认证方式	说明
Claude	OAuth / API Key	支持 Claude Code CLI 的 OAuth 认证和标准 API Key
Gemini	Google OAuth	支持 Google OAuth 认证
OpenAI Responses	API Key	支持 OpenAI Responses API (Codex CLI)

核心功能

• 智能账户调度 - 基于优先级的多账户自动切换
• 粘性会话 - 同一会话绑定同一账户，确保上下文连续性
• 自动 Token 刷新 - OAuth Token 自动续期，10秒提前刷新策略
• 代理支持 - 每个账户支持独立的 SOCKS5/HTTP 代理配置
• 自定义 API URL - 支持配置自定义 API 端点（镜像站/代理）
• 流式响应 - 完整的 SSE 流式传输支持
• 错误故障转移 - 智能错误检测与账户自动切换

🚀 快速开始

Docker（推荐）

mkdir cc-relay && cd cc-relay
curl -O https://raw.githubusercontent.com/wakaka6/claude-code-relay/main/config.example.toml
curl -O https://raw.githubusercontent.com/wakaka6/claude-code-relay/main/docker-compose.yml
mv config.example.toml config.toml
# 编辑 config.toml 配置账户信息
docker compose up -d

或使用 docker run：

docker run -d \
  --name cc-relay-server \
  -p 3000:3000 \
  -v ./config.toml:/app/config.toml:ro \
  -v ./data:/app/data \
  wakaka6/claude-code-relay:latest

注意： Docker 部署需要将配置中的 host 设置为 0.0.0.0，详见 FAQ。

Arch Linux (AUR)

paru -S claude-code-relay
sudo vim /etc/cc-relay-server/config.toml  # 配置账户信息
sudo systemctl enable --now cc-relay-server

macOS (Homebrew)

brew tap wakaka6/tap
brew install claude-code-relay
vim $(brew --prefix)/etc/cc-relay-server/config.toml  # 配置账户信息
brew services start claude-code-relay

二进制安装

从 Releases 下载对应平台的二进制文件：

./cc-relay-server --config config.toml

从源码构建

git clone https://github.com/wakaka6/claude-code-relay.git
cd claude-code-relay
cargo build --release
cp config.example.toml config.toml
# 编辑 config.toml
./target/release/cc-relay-server --config config.toml

验证安装

curl http://localhost:3000/health

⚙️ 配置说明

最小配置示例

api_keys = ["your-relay-key"]  # 必须在 [server] 之前

[server]
host = "127.0.0.1"  # Docker 部署请改为 "0.0.0.0"
port = 3000

[[accounts]]
type = "claude-api"
id = "main"
name = "Main Account"
priority = 100
enabled = true
api_key = "sk-ant-api03-xxxx"

服务器配置

[server]
host = "127.0.0.1"
port = 3000
database_path = "data/relay.db"
log_level = "info"  # trace, debug, info, warn, error

API Key 认证

用于客户端访问 Relay 服务的身份验证，与上游 API 的密钥无关。客户端请求时需在 Authorization 或 x-api-key 头中携带此处配置的 key。

api_keys = [
    "your-api-key-1",
    "your-api-key-2",
]

留空 api_keys = [] 则禁用认证，任意 key 都可访问，统计时标记为 anonymous。

会话配置

[session]
sticky_ttl_seconds = 3600            # 会话 TTL（默认 1 小时）
renewal_threshold_seconds = 300       # 续期阈值（剩余 5 分钟时续期）
unavailable_cooldown_seconds = 3600   # 账户不可用冷却时间（默认 1 小时）
rate_limit_cooldown_seconds = 60      # 速率限制冷却时间（默认 60 秒）
                                      # 优先使用 API 返回的 Retry-After 头，未提供时使用此默认值

账户配置

只需配置你需要使用的平台即可。

Claude OAuth 账户

[[accounts]]
type = "claude-oauth"
id = "claude-1"
name = "Claude OAuth Account"
priority = 100
enabled = true
refresh_token = "your-refresh-token"
api_url = "https://api.anthropic.com"  # 可选

Claude API Key 账户

[[accounts]]
type = "claude-api"
id = "claude-api-1"
name = "Claude API Account"
priority = 90
enabled = true
api_key = "sk-ant-api03-xxxx"

Gemini 账户

[[accounts]]
type = "gemini"
id = "gemini-1"
name = "Gemini Account"
priority = 100
enabled = true
refresh_token = "your-google-refresh-token"

OpenAI Responses 账户

[[accounts]]
type = "openai-responses"
id = "codex-1"
name = "OpenAI Responses Account"
priority = 100
enabled = true
api_key = "sk-your-openai-api-key"

代理配置

[accounts.proxy]
type = "socks5"  # 或 "http"
host = "127.0.0.1"
port = 1080
username = "user"  # 可选
password = "pass"  # 可选

🔌 API 端点

服务	端点	说明
Claude	POST /api/v1/messages	Claude Messages API
	POST /claude/v1/messages	别名路由
Gemini	POST /gemini/v1/models/:model:generateContent	标准生成
	POST /gemini/v1/models/:model:streamGenerateContent	流式生成
OpenAI 兼容	POST /openai/v1/chat/completions	转换为 Claude
OpenAI Responses	POST /openai/v1/responses	Responses API
系统	GET /health	健康检查

📱 客户端配置

Claude Code CLI

export ANTHROPIC_BASE_URL=http://localhost:3000
export ANTHROPIC_API_KEY=your-relay-api-key
claude

Gemini CLI

export GEMINI_API_BASE=http://localhost:3000/gemini
export GEMINI_API_KEY=your-relay-api-key
gemini

OpenAI Codex CLI

export OPENAI_BASE_URL=http://localhost:3000/openai/v1
export OPENAI_API_KEY=your-relay-api-key
codex

Python / Node.js SDK

Python:

import anthropic
client = anthropic.Anthropic(base_url="http://localhost:3000", api_key="your-key")

Node.js:

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
  baseURL: "http://localhost:3000",
  apiKey: "your-key",
});

🛠️ 开发

cargo test       # 运行测试
cargo clippy     # 代码检查
cargo fmt        # 格式化代码

❓ 常见问题

Docker Compose 启动后无法连接服务

问题： 客户端无法连接到 localhost:3000。

原因： 配置中 host = "127.0.0.1" 只监听容器内部网络。

解决： 修改为 host = "0.0.0.0"：

[server]
host = "0.0.0.0"
port = 3000

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT License