KiroGate：用你喜欢的任何工具调用Claude模型——开源API代理网关完全指南

你有没有遇到过这样的情况：想在自己的项目里用上强大的Claude模型，但官方API有地域限制、账号配额不够用，或者你更习惯用OpenAI格式的SDK，却不得不为Claude专门写一套适配代码？
我也是一个经常和各种大模型打交道的开发者，这些问题困扰了我很久，直到我发现了KiroGate——一个能够聚合多个Kiro账号、提供标准OpenAI/Anthropic接口的代理网关。今天，我就把它的所有细节、用法和背后的原理掰开揉碎了讲给你听。

什么是KiroGate？

KiroGate是一个开源API代理网关，它让你可以通过任何支持OpenAI或Anthropic API格式的工具，直接调用Claude系列模型（比如最新的claude-sonnet-4-5）。
它本质上是一个中间层：接收你发来的标准请求，转换成Kiro IDE的API格式，再分发到后端的多个Kiro账号上。这样一来，你既不用关心账号管理，也不用改变自己习惯的调用方式。

KiroGate由两部分核心组成：一部分来自kiro-openai-gateway的路由和转换能力，另一部分整合了kiro-account-manager的多账号调度功能。项目完全用Deno编写，不依赖任何外部数据库，开箱即用。

为什么要用KiroGate？

聚合多个账号：把多个Kiro账号塞进一个池子，自动分配请求，不用担心单个账号的配额耗尽。
兼容现有工具：无论是OpenAI的Python SDK、Anthropic的Node.js库，还是Postman、curl，只要能发HTTP请求，就能用KiroGate调用Claude。
智能容错：某个账号出错了？自动切换到下一个，你的应用几乎无感知。
上下文压缩：超长对话自动压缩，节省token消耗。
内置管理面板：可视化添加账号、创建API Key、查看实时统计。

核心功能深度解析

1. 双API兼容：OpenAI与Anthropic一网打尽

KiroGate同时提供了两个标准的API端点：

/v1/chat/completions —— 完全兼容OpenAI的Chat Completion格式
/v1/messages —— 完全兼容Anthropic的Messages API格式

这意味着你可以在同一个网关后面，同时服务两种不同习惯的客户端。例如，你的前端团队用OpenAI SDK写代码，后端分析团队用Anthropic SDK做实验，两个都能直接指向KiroGate，无需任何修改。

2. 多账号智能调度：让每个账号发挥最大价值

账号池是KiroGate最核心的模块之一。你可以往池子里添加任意数量的Kiro Refresh Token，系统会自动为每个账号维护以下状态：

健康分数（0–100）：基于请求成功率、错误类型、响应时间动态调整。分数高的账号优先使用，出错的账号分数下降，直至恢复。
并发计数：实时追踪每个账号正在处理的请求数，避免过载。
配额追踪：自动记录已使用的token和次数（需要账号支持配额查询）。

调度器支持三种模式：

Smart（默认）：结合健康分数和并发数，选择最优账号。
Priority：按你设置的优先级顺序使用，高优先级用满后才启用低优先级。
Balanced：均匀分配请求，适用于账号性能相近的场景。

当所有账号都不可用时，KiroGate会启动自愈机制：定期尝试恢复冷却中的账号，直到至少一个可用。

3. 三种认证方式：灵活应对不同场景

KiroGate提供了三种认证模式，满足从个人使用到多租户SaaS的各种需求：

简单模式：你只需要配置一个全局的PROXY_API_KEY，客户端带着这个Key来请求，由网关从账号池中自动分配账号。适合你自己一个人用，或者给团队共享一个账号池。
```
Authorization: Bearer your-proxy-key
```
组合模式：允许用户携带自己的Refresh Token，格式是PROXY_API_KEY:REFRESH_TOKEN。网关会用全局Key验证身份，然后用用户自带的Token去请求Kiro。这样既保证了安全性，又实现了用户自带账号的隔离。
```
Authorization: Bearer global-key:user-refresh-token
```
托管API Key模式：你可以在管理面板中创建以kg-开头的API Key，并为每个Key设置额度限制、模型白名单、过期时间。这些Key可以分发给不同的用户或应用，实现细粒度的访问控制。

4. 上下文压缩：处理超长对话的智能方案

当你和Claude聊到飞起，历史消息可能超过模型的上下文窗口。KiroGate内置的压缩器会自动介入，流程如下：

保留最近N条消息（N可配置）不压缩，保证对话的连贯性。
将更早的历史消息分批发送给Claude Haiku模型生成摘要。Haiku速度快、成本低，非常适合做文本总结。
三层缓存加速：
- 增量内存缓存：相同对话的后续请求，只对新增部分做摘要。
- LRU内存缓存：最近使用的摘要结果保存在内存中，淘汰策略为最近最少使用。
- Deno KV持久化：重启服务后，之前的摘要依然可以从本地KV存储中加载，避免重复计算。

这个机制能显著降低长对话的token消耗，同时保留核心语义。

5. 熔断器与限流：保护后端账号不被冲垮

为了防止突发流量打挂某个账号，KiroGate实现了经典的熔断器模式：

CLOSED（关闭）：正常转发请求。
OPEN（打开）：连续失败次数超过阈值（比如5次）后，熔断器打开，直接拒绝请求，不调用后端，给账号恢复时间。
HALF_OPEN（半开）：经过冷却时间（如30秒），允许少量请求试探，如果成功则关闭熔断器，否则继续保持打开。

同时，全局限流采用令牌桶算法，你可以通过RATE_LIMIT_PER_MINUTE环境变量设置每分钟允许的请求数。超过限制的请求会返回429状态码。

6. 管理面板：所有操作可视化

KiroGate自带一个Web管理界面，路径是/admin/accounts和/admin/keys，需要输入你在环境变量中设置的ADMIN_PASSWORD才能进入。在这里你可以：

添加、删除、禁用Kiro账号
手动刷新某个账号的Access Token
查看每个账号的健康状态、最近错误、剩余配额
创建和管理托管API Key（设置额度、模型限制）
查看全局实时统计：请求总数、成功/失败率、平均延迟

另外，还有一个公开的Dashboard（/dashboard）可以查看代理的简要健康状态，无需密码。

7. 零外部依赖：基于Deno原生能力

整个KiroGate只有一个可执行文件（main.ts）加几个库文件，不需要安装Redis、PostgreSQL或任何其他服务。它的数据存储完全依赖Deno内置的KV存储（--unstable-kv），配置信息、账号Token、缓存全部保存在本地文件系统中。部署时只需一个Deno运行时，极大简化了运维。

快速开始：10分钟跑通第一个请求

环境准备

安装Deno 2.x（推荐使用最新版）
获取至少一个Kiro IDE的Refresh Token（可以从Kiro客户端或网页登录后抓取）

步骤1：下载并运行KiroGate

git clone https://github.com/your-repo/kirogate.git  # 实际仓库地址请参考项目文档
cd kirogate

# 设置环境变量（建议改成你自己的密码）
export PROXY_API_KEY="my-super-secret-key"
export ADMIN_PASSWORD="admin123"

# 启动服务
deno run --allow-net --allow-env --unstable-kv main.ts

如果一切正常，你会看到类似Listening on http://0.0.0.0:8000的日志。

步骤2：添加账号

打开浏览器访问http://localhost:8000/admin/accounts，输入密码admin123进入管理界面。点击“添加账号”，粘贴你的Refresh Token，系统会自动换取Access Token并保存。你可以连续添加多个账号。

步骤3：发送测试请求

用curl发一个OpenAI格式的请求：

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer my-super-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "你好，请简单介绍一下自己"}],
    "stream": true
  }'

如果配置正确，你会看到Claude的流式回复一句一句地打印出来。

配置说明：所有环境变量一览

KiroGate通过环境变量进行配置，你可以把这些变量写在启动脚本或Docker Compose文件中。

变量名	默认值	说明
`PROXY_API_KEY`	`changeme_proxy_secret`	API代理密钥，用于简单模式和组合模式的身份验证
`ADMIN_PASSWORD`	`admin`	管理面板的登录密码
`PORT`	`8000`	HTTP监听端口
`LOG_LEVEL`	`INFO`	日志级别，可选DEBUG/INFO/WARN/ERROR
`RATE_LIMIT_PER_MINUTE`	`0`	全局限流，0表示不限流
`ENABLE_COMPRESSION`	`true`	是否启用上下文压缩功能

认证方式详解：三种模式的使用场景

模式1：简单模式——个人或团队共享池

你只需要把PROXY_API_KEY分发给团队成员，所有人共用账号池。这种方式最简单，适合信任环境。

模式2：组合模式——SaaS服务或开放平台

如果你想让用户使用自己的Kiro账号，但又不想让他们直接接触后端，可以用组合模式。用户提供全局Key:个人Refresh Token，网关先验证全局Key（代表你有权使用本服务），然后使用用户的Token去请求Kiro。这样既隔离了不同用户的消耗，又无需为每个用户单独配置账号。

模式3：托管API Key——精细化权限管理

在管理面板中创建的kg-开头的Key，可以绑定额度、模型和过期时间。例如，你可以创建一个Key只允许使用claude-haiku-4-5模型，每天最多消耗100万token，一周后自动失效。这些Key特别适合分发给外部合作伙伴或微服务。

API参考：端点清单

代理端点（需要API Key验证）

方法	路径	功能	说明
`GET`	`/v1/models`	获取可用模型列表	返回当前账号池支持的所有Claude模型
`POST`	`/v1/chat/completions`	OpenAI聊天补全	完全兼容OpenAI的请求/响应格式
`POST`	`/v1/messages`	Anthropic消息API	完全兼容Anthropic的请求/响应格式
`GET`	`/health`	健康检查	返回服务状态，用于负载均衡器检测

管理端点（需要Admin密码验证）

方法	路径	说明
`GET`	`/api/accounts`	获取所有账号列表
`POST`	`/api/accounts`	添加新账号（提供Refresh Token）
`PUT`	`/api/accounts/:id`	更新账号信息（如优先级、禁用）
`DELETE`	`/api/accounts/:id`	删除账号
`POST`	`/api/accounts/:id/refresh`	手动刷新该账号的Access Token
`GET`	`/api/keys`	获取所有托管API Key
`POST`	`/api/keys`	创建新的API Key（可设置额度、模型限制）
`PUT`	`/api/keys/:id`	更新API Key属性
`DELETE`	`/api/keys/:id`	删除API Key
`GET`	`/api/proxy/status`	获取代理当前状态（无需认证）
`GET`	`/api/proxy/health`	健康报告（无需认证）
`GET`	`/api/proxy/stats`	详细统计（请求数、成功率、平均延迟）
`GET`	`/api/proxy/logs`	最近请求日志
`PUT`	`/api/proxy/config`	动态更新运行时配置（如限流值）
`GET/PUT`	`/api/settings`	获取或更新全局设置

前端页面

路径	功能
`/`	首页，介绍项目
`/docs`	API文档
`/swagger`	Swagger UI交互式文档
`/playground`	在线测试工具
`/deploy`	部署指南
`/dashboard`	公开监控面板
`/admin/accounts`	账号管理
`/admin/keys`	API Key管理

支持的模型

根据KiroGate内置的模型映射，你可以使用以下模型名（在请求的model字段中填写）：

claude-opus-4-5
claude-sonnet-4-5
claude-sonnet-4
claude-haiku-4-5
claude-3-7-sonnet-20250219

实际上，只要你的Kiro账号有权限访问的Claude模型，都可以通过对应名称调用。

SDK使用示例

Python + OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="my-super-secret-key"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Explain quantum computing in simple terms."}],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content or "", end="")

Python + Anthropic SDK

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:8000",
    api_key="my-super-secret-key"
)

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is the capital of France?"}]
)
print(message.content[0].text)

Node.js + OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8000/v1",
  apiKey: "my-super-secret-key",
});

const stream = await client.chat.completions.create({
  model: "claude-sonnet-4-5",
  messages: [{ role: "user", content: "Tell me a joke." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

部署选项

Docker部署

项目提供了Dockerfile，你可以构建自己的镜像：

docker build -t kirogate .
docker run -d -p 8000:8000 \
  -e PROXY_API_KEY="your-key" \
  -e ADMIN_PASSWORD="admin123" \
  kirogate

Docker Compose

用compose文件管理服务：

version: "3"
services:
  kirogate:
    build: .
    ports:
      - "8000:8000"
    environment:
      - PROXY_API_KEY=your-key
      - ADMIN_PASSWORD=admin123
    restart: unless-stopped

然后docker-compose up -d即可。

Deno Deploy

KiroGate也可以部署到Deno Deploy（需要调整部分代码以适配Deploy的KV）。基本步骤：

deno install -A jsr:@deno/deployctl
deployctl deploy --project=your-project main.ts

架构深入：智能调度、压缩、熔断器的工作原理

多账号智能调度算法

每个账号在内存中都是一个对象，包含以下字段：

healthScore: 0–100，初始100
concurrent: 当前正在处理的请求数
lastError: 最后一次错误类型（超时、认证失败、速率限制等）
cooldownUntil: 如果因错误进入冷却，记录冷却结束时间戳

调度器每次选择账号时，执行以下步骤：

过滤掉健康分数为0或处于冷却中的账号。
如果是Priority模式，按优先级排序取第一个可用。
如果是Balanced模式，随机选择一个。
如果是Smart模式，计算每个账号的加权得分：healthScore / (concurrent + 1)，选得分最高的。这样既考虑健康度，又避免把请求全部塞给同一个账号。

当请求成功时，该账号的健康分数微增（不超过100）；请求失败时，根据错误类型扣减分数（如认证失败扣50，超时扣20）。如果分数降到0，账号进入冷却，冷却时间随失败次数指数增加。

上下文压缩工作流程

压缩器在检测到请求的messages总token数超过阈值（默认可配置，如10万token）时触发：

保留最近的K条消息（K默认20，可调整）。
将剩下的历史消息按时间顺序分成若干批次，每批次大小不超过max_batch_tokens（如2万token）。
对每个批次，调用Claude Haiku生成一句话摘要，提示为“请用一句话总结以上对话的核心内容”。
将生成的摘要作为系统消息插入到最终请求中，替换原始的历史消息。
同时，把本次生成的摘要和对应的原始消息范围存入缓存。

缓存分为三层：

增量内存缓存：以对话ID为键，缓存最近生成的摘要，后续请求只需要处理新增的消息。
LRU内存缓存：限制内存使用，最多缓存1000个对话的摘要，淘汰最近最少使用的。
Deno KV持久化：服务重启后，从KV中加载最近使用的摘要，避免重新生成。

熔断器状态机

熔断器作用于每个后端账号（或全局）。实现细节：

CLOSED：正常转发，同时记录连续失败次数。当连续失败次数达到failureThreshold（默认为5）时，切换到OPEN。
OPEN：立即拒绝所有请求，返回503。同时启动一个定时器，持续时间timeout（默认为30秒）。超时后切换到HALF_OPEN。
HALF_OPEN：允许通过一个请求（或少量请求）。如果请求成功，切换回CLOSED并重置计数器；如果失败，立即回到OPEN并重置定时器。

熔断器和健康分数协同工作：熔断器打开时，账号的健康分数会被强制设为0，调度器不会选择它；熔断器半开时，允许试探请求，健康分数根据试探结果恢复。

管理面板使用技巧

账号管理

在/admin/accounts页面，你可以看到每个账号的Refresh Token（部分隐藏）、Access Token有效期、健康分数、当前并发数、累计请求数。点击“刷新”可以手动触发Token刷新，如果发现某个账号频繁出错，可以暂时禁用。

托管API Key

创建Key时，你可以设置：

额度限制：按token数量或请求次数限制，达到限制后Key自动失效。
模型白名单：只允许使用指定的几个模型。
IP白名单：限制只有特定IP段可以调用。
过期时间：Key在指定日期后自动失效。

这些Key的统计数据也会实时显示，方便你追踪每个用户的使用情况。

实时统计

/dashboard页面（无需密码）展示：

最近5分钟请求量折线图
各模型调用占比
成功/失败比例
平均响应时间
当前账号池健康状态（绿灯/黄灯/红灯）

常见问题解答（FAQ）

Q: KiroGate需要数据库吗？
A: 不需要。所有数据（账号信息、API Key、缓存）都存储在Deno内置的KV中，数据保存在本地文件系统。

Q: 如何实现负载均衡？
A: 账号池本身就是一个负载均衡器。你只需添加多个账号，调度器会根据健康分数和并发数自动分配请求。如果想跨多个KiroGate实例做负载均衡，可以在前面加一层Nginx。

Q: 支持哪些Claude模型？
A: 支持所有通过Kiro API可调用的Claude模型，包括Opus、Sonnet、Haiku的最新版本。具体列表见“支持的模型”部分。

Q: 上下文压缩会影响回复质量吗？
A: 压缩只针对超出上下文窗口的历史消息，最近的对话保持原样。Haiku生成的摘要质量很高，绝大多数情况下不会影响新回复的准确性。

Q: 熔断器打开后，请求会返回什么错误？
A: 返回HTTP 503 Service Unavailable，并带有X-Kiro-Circuit-Open: true头部。

Q: 我可以动态调整限流值吗？
A: 可以。通过PUT /api/proxy/config接口可以实时修改RATE_LIMIT_PER_MINUTE，无需重启服务。

结语

KiroGate把繁琐的多账号管理和协议转换封装成了一个简单、可靠的工具。不管你是个人开发者想聚合多个Kiro账号，还是团队需要为不同项目分配配额，它都能帮你省下大量时间。它的设计充分考虑了生产环境的高可用和自愈能力——智能调度、熔断器、上下文压缩这些机制，都是经过实际考验的。

如果你也在用Claude模型做开发，不妨试试KiroGate，相信它会成为你工具箱里的一把利器。项目完全开源，你可以自由修改、部署，甚至基于它构建自己的商业化服务。

Claude模型调用神器KiroGate开源：一个API网关搞定所有账号与兼容问题