Mirrowel/LLM-API-Key-Proxy · 上手攻略

• 仓库：Mirrowel/LLM-API-Key-Proxy
• 链接：https://github.com/Mirrowel/LLM-API-Key-Proxy
• 分类：LLM Gateway / API Proxy / Key Rotation
• 作者：Jay
• 更新：2026-09-08

是什么

LLM-API-Key-Proxy 是一个自托管的统一 LLM 网关，通过单个 OpenAI / Anthropic 兼容端点，接入所有主流 LLM 提供商（Gemini / OpenAI / Anthropic / OpenRouter / Groq / Mistral / NVIDIA / Cohere 等）。所有请求通过模型的 provider/model_name 格式路由，由内置的 RotatingClient 完成自动 key 轮换、failover 和负载均衡，客户端完全无需修改代码。

该项目的设计哲学是：一个 API Key，一套代码，访问所有模型。通过 OpenAI 和 Anthropic 双协议兼容，任何支持自定义 base URL 的应用（Claude Code、Cursor、Continue、Roo/Kilo Code、JanitorAI、SillyTavern 等）均可即插即用。

解决什么问题

1. 管理多个 API Key 的复杂度：每个提供商都有自己的 key 和 API 端点，手动切换容易出错，proxy 提供统一的 /v1 入口。
2. 单 provider rate limit 瓶颈：通过 key 轮换和负载均衡，把请求分散到多个 key，降低 rate limit 触发概率。
3. failover 高可用：某 provider 出错时自动切换到其他 provider，无需人工干预。
4. 模型格式统一：所有 provider 使用 provider/model_name 格式，客户端代码完全不用改。
5. 多 provider 同一 key：通过 OpenRouter 等聚合层或直接配置，实现用一个 proxy key 访问多个 provider。

快速安装

方式一：下载可执行文件（推荐，最简）

# 下载最新 release
# https://github.com/Mirrowel/LLM-API-Key-Proxy/releases/latest

# macOS / Linux
chmod +x proxy_app
./proxy_app

# Windows: 双击 proxy_app.exe

方式二：Docker（推荐生产使用）

docker run -d \
  --name llm-api-proxy \
  -p 8000:8000 \
  -v $(pwd)/.env:/app/.env:ro \
  -v $(pwd)/oauth_creds:/app/oauth_creds \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/usage:/app/usage \
  -e SKIP_OAUTH_INIT_CHECK=true \
  ghcr.io/mirrowel/llm-api-key-proxy:latest

⚠️ 必须预先创建 usage/ 目录以持久化用量统计。Docker 方式支持无头运行（加 --host 0.0.0.0 --port 8000 参数绕过 TUI 直接启动）。

方式三：从源码运行

git clone https://github.com/Mirrowel/LLM-API-Key-Proxy.git
cd LLM-API-Key-Proxy
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python src/proxy_app/main.py

核心用法

1. 配置 API Keys

创建 .env 文件（参考 .env.example）：

# 必需：proxy 自身的认证 key
PROXY_API_KEY="your-secret-proxy-key"

# 各 provider 的 key（多个 key 用 _1, _2 后缀）
GEMINI_API_KEY_1="your-gemini-key"
GEMINI_API_KEY_2="another-gemini-key"
OPENAI_API_KEY_1="your-openai-key"
ANTHROPIC_API_KEY_1="your-anthropic-key"

或使用 TUI 交互式管理（运行 ./proxy_app 或 python -m rotator_library.credential_tool）。

2. 客户端配置

启动后，客户端统一配置为：

设置项	值
Base URL / API Endpoint	http://127.0.0.1:8000/v1
API Key	your-proxy-api-key

模型名称格式：provider/model_name

gemini/gemini-2.5-flash       ← Gemini API
openai/gpt-4o                  ← OpenAI API
anthropic/claude-3-5-sonnet   ← Anthropic API
openrouter/anthropic/claude-3-opus  ← OpenRouter
gemini_cli/gemini-2.5-pro     ← Gemini CLI (OAuth)

3. Python OpenAI SDK 调用

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="your-proxy-api-key"
)

response = client.chat.completions.create(
    model="gemini/gemini-2.5-flash",
    messages=[{"role": "user", "content": "What is the capital of France?"}]
)
print(response.choices[0].message.content)

4. Claude Code 配置

编辑 Claude Code 的 settings.json：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-proxy-api-key",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8000",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gemini/gemini-3-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gemini/gemini-3-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "openai/gpt-5-mini"
  }
}

5. curl 直接调用

curl -X POST http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-proxy-api-key" \
  -d '{
    "model": "gemini/gemini-2.5-flash",
    "messages": [{"role": "user", "content": "What is the capital of France?"}]
  }'

6. API 端点一览

端点	描述
GET /	状态检查
POST /v1/chat/completions	OpenAI 格式对话补全
POST /v1/messages	Anthropic 格式（Claude Code 兼容）
POST /v1/messages/count_tokens	token 计数（Anthropic 格式）
POST /v1/embeddings	文本向量化
GET /v1/models	列出所有可用模型（含定价和能力）
GET /v1/models/{model_id}	特定模型详情
GET /v1/providers	列出已配置的 provider
POST /v1/token-count	计算 payload token 数
POST /v1/cost-estimate	基于 token 计数估算成本

典型适用场景

场景	为什么用 LLM-API-Key-Proxy
多 provider 统一入口	一个 endpoint 管所有模型，客户端代码零改动
key 轮换防 rate limit	多 key 自动负载均衡，避免单 key 触发限制
Claude Code 接入非 Anthropic 模型	通过 Anthropic 兼容端点让 Claude Code 用 Gemini
开发/测试环境隔离	本地 proxy 指向不同环境，切换 provider 只需改 .env
用量统计与审计	/v1/models 含定价信息，usage/ 目录记录每 provider 用量

坑与注意

1. 模型名称必须带 provider 前缀：不能用裸模型名如 gpt-4o，必须写成 openai/gpt-4o 或 gemini/gemini-2.5-flash。这是最常见的配置错误。
2. Docker 方式需预先创建 usage/ 目录：否则用量统计无法持久化（文档有说明但容易忽略）。
3. OAuth provider（如 Gemini CLI）需要本地交互登录：credential tool 需要浏览器完成 OAuth 流程 headless 环境需额外配置。
4. 并发控制需要理解 optimal vs max：optimal 是软目标（key 低于此值时优先使用），max 是硬上限；不了解这个机制可能导致 key 被意外堆叠使用或限流。
5. PROXY_API_KEY 必须设置：这是 proxy 自身的认证 key，不是 provider 的 key，缺少会导致所有请求被拒绝。
6. RotatingClient 是独立 Python 库：rotator_library 可以单独 pip 安装使用，不一定要跑完整的 proxy_app——有二次开发能力的用户可以直接嵌入自己的应用。

与同类对比

项目	协议兼容	key 轮换	failover	TUI	自托管
LLM-API-Key-Proxy	OpenAI + Anthropic	✅ 多 key / 负载均衡	✅ 自动切换	✅	✅
LiteLLM	OpenAI + 30+	✅	✅	❌	✅
OpenRouter	OpenAI 兼容	❌（平台管理）	❌	❌	❌（SaaS）
Portkey	OpenAI 兼容	✅	✅	❌	SaaS + 自托管
FastChat	OpenAI 兼容	❌	❌	✅	✅

核心差异：LLM-API-Key-Proxy 通过 TUI 和 .env 配置实现了零代码接入，最大的差异化卖点是 Anthropic 协议兼容（让 Claude Code 可以通过 proxy 接入 Gemini 等非 Anthropic 模型），加上内置的 RotatingClient Python 库可以直接嵌入其他应用。相比 LiteLLM 更轻量，但 provider 覆盖数量不如 LiteLLM。

一句话推荐结论

LLM-API-Key-Proxy 是需要在本地统一管理多个 LLM provider key、实现自动 failover 和负载均衡的开发者的最佳选择——尤其是当你希望 Claude Code 或任何 Anthropic SDK 客户端直接使用 Gemini / OpenAI / OpenRouter 等其他模型时，一行配置即可完成切换，生产部署用 Docker 也极为简单；但如果你需要最广泛的 provider 支持或云端托管方案，LiteLLM / Portkey 是更成熟的选择。

---

⚠️ 本攻略基于 2026-09-08 GitHub README web_fetch，Docker image 路径、OAuth 流程细节以官方文档为准。