claude-api-hub

v6.4.0

Published

2 days ago

Multi-provider API gateway for Claude Code — route requests to any LLM provider with zero config switching

0High
0Medium
0Low

claude claude-code api-gateway kimi minimax glm zhipu moonshot deepseek kiro anthropic openai-compatible llm multi-provider proxy

Claude API Hub

一个网关，将 Claude Code 路由到任意 LLM 供应商

中文 | English

一个本地 API 网关，通过模型别名（haiku / sonnet / opus）让 Claude Code 将请求路由到任意 LLM 供应商。通过 Web 仪表盘管理一切 —— 无需配置文件。

为什么选择 Claude API Hub？

在 Claude Code 中使用任意 LLM —— 将 Sonnet 请求路由到 Kimi、GLM、MiniMax、DeepSeek 或任何兼容 OpenAI 的 API
零配置切换 —— 从 Web 仪表盘更改模型路由，无需重启
零运行时依赖 —— 基于 Node.js 原生 http 模块构建，安装体积约 50KB

30 秒快速开始

# 1. 安装（或直接用 npx 运行）
npm install -g claude-api-hub

# 2. 启动网关
claude-api-hub
# ✓ api-hub listening on http://0.0.0.0:9800

# 3. 配置 Claude Code
claude config set ANTHROPIC_BASE_URL http://127.0.0.1:9800

# 备选：手动写入 settings.json
# echo '{"env":{"ANTHROPIC_BASE_URL":"http://127.0.0.1:9800"}}' > ~/.claude/settings.json

# 4. 验证安装
curl http://localhost:9800/health
# 或在浏览器打开 http://localhost:9800 查看仪表盘

# 5. 完成！Claude Code 现在通过网关路由请求

安全提示： 默认绑定 127.0.0.1:9800（仅本地访问）。生产环境或局域网使用请设置 password 或 --host 0.0.0.0。

架构

┌─────────────────────────────────────────────────────────────────────┐
│                        Claude API Hub                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐ │
│  │   Dashboard  │    │  API Router  │    │   Protocol Bridge   │ │
│  │  (Web UI)    │    │              │    │                      │ │
│  │  :9800       │    │  /v1/messages│    │  Anthropic ↔ OpenAI │ │
│  │              │    │              │    │                      │ │
│  └──────────────┘    └──────┬───────┘    └──────────┬───────────┘ │
│                              │                        │             │
│                              │                        │             │
│                              ▼                        ▼             │
│                     ┌─────────────────┐       ┌────────────┐      │
│                     │  Alias Resolver │       │  Provider  │      │
│                     │  haiku → model   │       │   Pool     │      │
│                     │  sonnet → model  │       │            │      │
│                     │  opus → model    │       │ Key Health │      │
│                     └─────────────────┘       │ Fallbacks   │      │
│                                                └──────┬─────┘      │
└────────────────────────────────────────────────────────┼────────────┘
                                                         │
    ┌─────────────────────────────────────────────────────┼──────────┐
    │                       Providers                      │          │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐   │
    │  │  Kimi     │ │  GLM     │ │ MiniMax   │ │   Kiro     │   │
    │  │ OpenAI    │ │  OpenAI  │ │  OpenAI   │ │  OAuth     │   │
    │  │ Compatible│ │ Compatible│ │ Compatible│ │ (AWS Q)    │   │
    │  └──────────┘ └──────────┘ └──────────┘ └────────────┘   │
    │         │           │           │              │            │
    └─────────┴───────────┴───────────┴──────────────┴────────────┘
              │           │           │              │
              ▼           ▼           ▼              ▼
         ┌─────────────────────────────────────────────┐
         │            External LLM Providers            │
         │                                             │
         │   ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
         │   │ Moonshot│ │ Zhipu │ │ MiniMax│ │  AWS  │ │
         │   │  AI    │ │  AI   │ │  AI   │ │  Q    │ │
         │   └───────┘ └───────┘ └───────┘ └───────┘ │
         └─────────────────────────────────────────────┘

功能特性

核心

多供应商 API 网关，支持模型别名（haiku/sonnet/opus → 任意模型）
自动协议转换（Anthropic ↔ OpenAI）
零运行时依赖 —— 基于 Node.js 原生模块
热重载配置，无需重启

仪表盘与监控

实时 SSE 仪表盘，支持请求监控
Token 用量图表、请求趋势图和用量热力图
模型明细表，支持搜索、排序和分页
快速开始指南，支持复制配置
供应商健康检测

路由与可靠性

降级链，自动供应商故障转移
多密钥池，支持轮询和自动恢复
按层级超时配置（haiku/sonnet/opus）
模型别名映射，无缝切换供应商

安全

时间安全认证（常量时间比较）
基于 IP 的速率限制，带标准响应头
基于会话的管理员认证
安全响应头（CSP、X-Frame-Options 等）

高级功能

Kiro OAuth 集成（Google/GitHub/AWS Builder ID）
基于文件的请求日志，支持轮转
CORS 配置
配置中的环境变量插值

Web 仪表盘

访问 http://localhost:9800 —— 一个受 Traefik 启发的仪表盘，带侧边栏导航，使用 Preact 组件构建：

左侧面板：

快速开始：3 步设置指南，支持复制配置片段
别名映射：将 haiku/sonnet/opus 映射到任意模型。组合下拉框自动从供应商 API 检测模型，也支持自定义模型名称。按层级配置超时
供应商：卡片展示名称、协议标识（Anthropic/OpenAI/Kiro）、模型（从 API + 配置合并）、前缀、默认模型、密钥状态。每个卡片有测试/编辑/删除按钮

右侧面板：

请求日志：实时 SSE 更新，保留展开状态。按全部/正常/错误筛选。每条记录显示 claudeModel → resolvedModel → provider 及耗时。点击展开详情（请求 ID、目标 URL、错误信息、日志文件路径）
文件日志开关：启用/禁用磁盘详细日志记录

配置页面（双模式）：

UI 模式：结构化表单，卡片式展示常规、安全、Token 刷新、流/超时、CORS 设置
JSON 模式：原始 JSON 编辑器，支持验证、导入/导出和重置

仪表盘截图

运行 npx claude-api-hub 并访问 http://localhost:9800 探索仪表盘。

支持的供应商

| 供应商 | 协议 | 状态 | |----------|----------|--------| | Claude (Anthropic) | Anthropic 透传 | 已验证 | | Kiro (AWS Q / CodeWhisperer) | Kiro OAuth → AWS Q API | 已验证 | | Kimi (Moonshot AI) | Anthropic 透传 | 已验证 | | MiniMax | Anthropic 透传 | 已验证 | | GLM (Zhipu AI) | Anthropic 透传 | 已验证 | | DeepSeek | Anthropic 透传 | 已验证 | | 任意兼容 OpenAI 的 API | 自动转换（Anthropic ↔ OpenAI） | 支持 |

快速开始

前提条件

Node.js >= 22

方案 1：使用 npx 运行（无需安装）

前提条件： Node.js >= 22。使用 node -v 检查。从 nodejs.org 安装或使用 nvm install 22。

npx claude-api-hub
# ✓ api-hub listening on http://0.0.0.0:9800
# ✓ Open http://localhost:9800 for the web dashboard

⚠️ 安全提示： 默认情况下，网关绑定到 0.0.0.0:9800 且无密码。生产环境请在 providers.json 中设置 password 并考虑绑定到 127.0.0.1。

方案 2：全局安装

npm install -g claude-api-hub
claude-api-hub
# ✓ api-hub listening on http://0.0.0.0:9800
# ✓ Open http://localhost:9800 for the web dashboard

方案 3：Docker

git clone https://github.com/LeenixP/claude-api-hub.git
cd claude-api-hub
# 编辑 docker-compose.yml 添加你的 API 密钥
docker compose up -d

仪表盘：http://localhost:9800

打开 http://localhost:9800 访问 Web 仪表盘。

在 ~/.claude/settings.json 中将 Claude Code 指向网关：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:9800"
  }
}

重启 Claude Code，所有请求将通过网关路由。

验证

curl http://localhost:9800/health
# {"status":"ok","timestamp":"..."}

示例请求

curl -X POST http://localhost:9800/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-key" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":100,"messages":[{"role":"user","content":"Hello"}]}'

如果 sonnet 被别名为 kimi-k2.6，请求将自动路由到 Kimi 并进行协议转换。

别名映射

将 Claude Code 的三个模型层级映射到任意供应商的模型：

{
  "aliases": {
    "haiku": "glm-4-flash",
    "sonnet": "kimi-k2.6",
    "opus": "claude-opus-4-6"
  }
}

当请求模型包含 haiku、sonnet 或 opus 时，将被替换为别名目标。日志会显示层级名称（Haiku/Sonnet/Opus）以及解析后的模型，便于调试。

添加供应商

通过 Web 仪表盘（推荐）或配置文件 ~/.claude-api-hub/providers.json：

"deepseek": {
  "name": "DeepSeek",
  "baseUrl": "https://api.deepseek.com/anthropic",
  "apiKey": "${DEEPSEEK_API_KEY}",
  "models": ["deepseek-chat", "deepseek-reasoner"],
  "defaultModel": "deepseek-chat",
  "enabled": true,
  "prefix": "deepseek-",
  "passthrough": true
}

供应商配置字段

| 字段 | 说明 | |-------|-------------| | name | 显示名称 | | baseUrl | API 端点基础 URL | | apiKey | API 密钥（支持 ${ENV_VAR} 语法）。Kiro OAuth 供应商不需要 | | models | 可用模型 ID 列表 | | defaultModel | 该供应商的默认模型 | | prefix | 路由前缀（字符串或数组），如 "kimi-" | | passthrough | true = Anthropic Messages API（直接转发），false = OpenAI Chat Completions API（自动转换） | | enabled | true / false 启用/禁用 | | providerType | "standard"（默认）或 "kiro" 用于 Kiro OAuth 供应商 | | authMode | "apikey"（默认）或 "oauth" 用于基于 OAuth 的认证 | | kiroRegion | Kiro 供应商的 AWS 区域（默认：us-east-1） | | kiroCredsPath | Kiro OAuth 凭证文件路径 | | kiroStartUrl | Builder ID 认证的自定义 AWS SSO 起始 URL |

协议选择

每个供应商可以使用三种协议之一 —— 在供应商模态表单中选择：

Anthropic API（透传）：请求通过 x-api-key 原样转发。用于 Anthropic 官方 API 或兼容代理（如 MiniMax Anthropic 端点）
兼容 OpenAI（自动转换）：请求从 Anthropic 格式自动转换为 OpenAI 格式。通过 Bearer token 认证。用于 Kimi、GLM、DeepSeek 和任何兼容 OpenAI 的 API
Kiro（AWS Q）：选择 "Kiro" 作为供应商类型。使用 OAuth 凭证通过 AWS Q generateAssistantResponse 端点调用 Claude 模型。直接从 Web UI 授权

Kiro 供应商

Kiro 供应商通过 AWS Q（CodeWhisperer）路由请求，允许你使用 Kiro OAuth 凭证而非 Anthropic API 密钥来使用 Claude 模型。

Web UI 授权（推荐）

打开 Web 仪表盘 → 点击 添加供应商 → 选择 Kiro 作为供应商类型
在 Kiro 授权 部分，选择认证方式：
- Sign in with Google —— 一键登录，最简单
- Sign in with GitHub —— 一键登录，最简单
- AWS Builder ID —— 使用你的 AWS 开发者账户（需要验证码）
可选设置 Region 和 Start URL（用于自定义 AWS SSO 端点）
点击认证按钮 —— 弹出窗口进行授权
授权完成后，状态自动更新
点击 Fetch 加载可用模型，然后 Save

凭证保存到 ~/.kiro/oauth_creds.json 并在后台自动刷新（可配置间隔，默认 30 分钟）。

手动配置

或者，直接在配置文件中添加供应商：

"kiro": {
  "name": "Kiro",
  "baseUrl": "https://q.us-east-1.amazonaws.com",
  "apiKey": "",
  "models": ["claude-sonnet-4-6", "claude-haiku-4-5"],
  "defaultModel": "claude-sonnet-4-6",
  "enabled": true,
  "providerType": "kiro",
  "authMode": "oauth",
  "kiroRegion": "us-east-1",
  "kiroCredsPath": "~/.kiro/oauth_creds.json"
}

Token 自动刷新

OAuth token 在过期前由后台服务自动刷新。在配置页面或配置文件中配置间隔：

{
  "tokenRefreshMinutes": 30
}

API 端点

| 端点 | 方法 | 说明 | |----------|--------|-------------| | / | GET | Web 仪表盘 | | /v1/messages | POST | Anthropic Messages API 代理（主端点） | | /v1/models | GET | 列出所有可用模型 | | /health | GET | 网关健康检查 | | /api/events | GET | SSE 实时事件流 | | /api/stats | GET | 速率追踪统计（QPS、RPM、TPS） | | /api/auth/login | POST | 密码登录（返回认证 token） | | /api/config | GET | 当前配置（API 密钥已脱敏） | | /api/config/providers | POST | 添加供应商（热重载路由） | | /api/config/providers/:name | PUT/DELETE | 更新或删除供应商（热重载路由） | | /api/config/import | POST | 导入完整配置（替换并重载） | | /api/config/reload | POST | 从磁盘重载配置 | | /api/tier-timeouts | GET/PUT | 获取或更新按层级超时配置 | | /api/aliases | GET/PUT | 获取或更新别名映射 | | /api/fetch-models | GET | 从供应商 API 获取真实模型列表 | | /api/health/providers | GET | 测试所有供应商的连通性 | | /api/test-provider/:key | POST | 用完整请求流测试供应商（绕过别名） | | /api/oauth/kiro/* | Various | Kiro OAuth 流程端点 | | /api/logs | GET | 请求日志（最近 200 条，轻量） | | /api/logs/clear | POST | 清空日志缓冲区 | | /api/logs/file-status | GET | 文件日志状态和文件数量 | | /api/logs/file-toggle | PUT | 开关文件日志 |

多密钥配置

每个供应商通过 apiKey 字段支持多个 API 密钥。用逗号分隔密钥：

"deepseek": {
  "apiKey": "${DEEPSEEK_KEY_1},${DEEPSEEK_KEY_2},${DEEPSEEK_KEY_3}",
  ...
}

网关通过 KeyPool 管理密钥：

轮询轮换：请求均匀分布在健康密钥上
自动禁用：连续 5 次错误后，密钥被标记为不健康并跳过
自动恢复：不健康密钥在 60 秒后重新启用
成功重置：成功请求立即重置错误计数器

密钥健康状态在仪表盘的供应商卡片中可见。

降级链

配置供应商之间的自动故障转移，当主供应商不健康时：

{
  "fallbackChain": {
    "kimi": "deepseek",
    "deepseek": "glm"
  }
}

当供应商不健康（所有密钥耗尽）时，路由跟随降级链寻找健康的替代方案。循环检测防止无限循环。

路由规则

别名解析：模型名称包含 haiku/sonnet/opus → 替换为别名目标
前缀匹配：按供应商的 prefix 配置路由
模型列表匹配：检查供应商的 models 数组
自动选择：使用第一个健康的启用供应商

日志

双层日志系统：

内存日志（始终开启）：RAM 中的轻量摘要，显示在仪表盘中。最近 200 条记录，包含 claudeModel 层级、resolvedModel、provider、状态、耗时、错误信息
文件日志（可选）：~/.claude-api-hub/logs/ 中的详细 JSON 文件，包含原始请求体、转换后的请求体、转发头、上游响应。通过仪表盘开关。4096 个文件时自动清理

安全

密码登录门户：配置 adminToken 时仪表盘显示登录页面。输入管理员密码认证 —— 凭证存储在 localStorage 中，后续请求以 x-admin-token 头发送
管理员认证：在配置中设置 adminToken 或 ADMIN_TOKEN 环境变量以保护管理 API 端点
基于 IP 的速率限制：配置 rateLimitRpm 限制每 IP 每分钟请求数
CORS 限制：默认 localhost；配置 corsOrigins 指定来源
时间安全比较：管理员 token 使用 crypto.timingSafeEqual 防止定时攻击
环境变量白名单：只有 ANTHROPIC_*、MOONSHOT_*、MINIMAX_*、ZHIPUAI_*、OPENAI_*、DEEPSEEK_* 前缀会被插值
API 密钥脱敏：所有 API 响应和日志中密钥已脱敏

查看 SECURITY.md 了解漏洞报告。

故障排查

连接被拒绝 (ECONNREFUSED)

症状： Claude Code 无法连接到网关。

解决方案：

验证网关正在运行：curl http://127.0.0.1:9800/health

检查 ~/.claude/settings.json 配置正确：

{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:9800" } }

如果使用 Docker，确保端口映射：-p 9800:9800
检查防火墙设置允许本地连接

401 未授权

症状： 请求返回 401 错误。

解决方案：

验证 API 密钥在 providers.json 中设置正确
检查密钥格式符合供应商要求（Bearer vs x-api-key）
对于 Kiro：确保 OAuth 凭证有效且未过期
运行 /api/health/providers 测试连通性

模型未找到

症状： 错误信息指示模型未找到。

解决方案：

检查别名映射是否配置：/api/aliases
验证供应商已启用：/api/health/providers
确保模型存在于供应商的模型列表中
尝试获取最新模型：/api/fetch-models

请求超时

症状： 请求挂起或超时。

解决方案：

检查供应商 API 状态
调整配置中的超时：streamTimeout 或 requestTimeout
检查网络/防火墙设置
尝试不同的供应商作为降级

SSRF（服务器端请求伪造）警告

症状： 可疑的内部请求被阻止。

这是有意为之的安全行为。 网关阻止对以下地址的请求：

私有 IP 范围（10.x、172.16.x、192.168.x、127.x）
Localhost 地址
内部云元数据端点

如果你需要访问内部资源，确保供应商 baseUrl 使用公共端点。

Docker：无法从宿主机访问网关

解决方案：

配置中使用 host: "0.0.0.0"（不是 127.0.0.1）
确保 Docker 端口映射：-p 9800:9800
运行 docker compose up 以获得正确的网络

端口 9800 已被占用

解决方案：

查找并停止冲突进程：lsof -i :9800
更改配置中的端口：API_HUB_PORT=9801
如果安全则终止现有进程：kill <PID>

路线图

计划的功能和增强（尚未实现）：

进行中

当前无进行中项目

计划中

Gemini 支持 —— 添加 Google Gemini 作为路由目标
插件系统 —— 可扩展架构，支持自定义供应商和转换
Webhook 集成 —— 请求事件的实时通知
Prometheus 指标 —— 导出指标用于 Prometheus/Grafana 监控
请求重放 —— 重放历史请求用于调试

待办

按模型速率限制
成本追踪和预算
批量请求支持
多区域供应商选择
API 密钥自动轮换

开发

npm run dev         # 开发模式（热重载）
npm run dev:ui      # 前端监视模式
npm run build       # 编译 TypeScript
npm run build:ui    # 生产前端构建
npm test            # 运行测试（100+ 测试）
npm run test:coverage # 运行测试并生成覆盖率报告
npm run lint        # 运行 ESLint

贡献

查看 CONTRIBUTING.md 了解开发设置和 PR 指南。

许可证

MIT 许可证 —— 详见 LICENSE。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Claude API Hub

最新动态

为什么选择 Claude API Hub？

30 秒快速开始

架构

目录

功能特性

核心

仪表盘与监控

路由与可靠性

安全

高级功能

Web 仪表盘

仪表盘截图

支持的供应商

快速开始

前提条件

方案 1：使用 npx 运行（无需安装）

方案 2：全局安装

方案 3：Docker

验证

示例请求

别名映射

添加供应商

供应商配置字段

协议选择

Kiro 供应商

Web UI 授权（推荐）

手动配置

Token 自动刷新

API 端点

多密钥配置

降级链

路由规则

日志

安全

故障排查

连接被拒绝 (ECONNREFUSED)

401 未授权

模型未找到

请求超时

SSRF（服务器端请求伪造）警告

Docker：无法从宿主机访问网关

端口 9800 已被占用

路线图

进行中

计划中

待办

开发

贡献

许可证