KiroStudio 用 Rust / Axum 编写，接收标准 Anthropic Messages API 请求，转换后转发到 Kiro / AWS Q 上游，并把上游响应翻译回 Anthropic 格式。任何兼容 Anthropic 协议的客户端（Claude Code、各类 SDK、自研应用）都可以把 base_url 指向本网关直接使用。

前端管理面板（React + Vite）在编译期通过 rust-embed 嵌入二进制，最终产物是单个可执行文件，不依赖任何外部静态资源目录，拷贝即可运行。

致谢

本项目基于 hank9999/kiro.rs（MIT License）深度魔改与增强，在原项目「Anthropic ↔ Kiro 协议转换」核心之上做了大量工程化扩展。感谢原作者 hank9999 打下的基础。

相较原项目，主要增强点：

• 多凭据智能调度 —— 负载均衡、故障转移、失败冷却、会话亲和、RPM 软限流
• 入口安全层 —— API Key 鉴权、CORS 白名单、IP 白名单（CIDR）、每-IP 限流、请求体大小限制
• SSRF 防护 —— 出站地址校验，拦截指向内网/回环的请求
• 输入压缩管道 —— 请求体接近上游硬限制时自动压缩（空白折叠 + 超长 tool_result 智能截断）
• 多种上号方式 —— Social / IAM Identity Center (IdC) / External IdP，面板内网页上号
• 实时用量统计 —— 请求埋点、SQLite 落盘、按模型/凭据/客户端聚合、设备识别
• 现代化管理面板 —— 概览、凭据管理、用量分析、系统设置
• 一键部署 —— Docker Compose、预编译静态二进制、systemd 服务脚本

特性

🛠️ 招牌能力：根治 Invalid tool parameters。 Claude Code 调用工具时因参数含 \U 反斜杠 / 裸控制符 / 上游截断导致的 Invalid tool parameters，KiroStudio 在发给 客户端前把坏 JSON 修成合法再发。完整原理、与 #70544（模型侧丢标签，网关碰不到）的边界、 以及如何验证，见 docs/INVALID-TOOL-PARAMETERS.md。

快速开始

一键部署（最省事，二选一）

两条一键路径都会：交互式设置端口/密钥（回车即自动生成安全随机密钥）、生成配置、启动服务， 已有配置不覆盖（幂等）。全程无需手改配置文件。

git clone https://github.com/dwgx/KiroStudio.git && cd KiroStudio

# 路径 A：Docker（需 Docker + Compose，跨平台）
bash install.sh

# 路径 B：预编译二进制 + systemd（仅 Linux x86_64，无需 Docker/Rust/Node）
bash install-binary.sh

非交互（CI/无人值守）：KIROSTUDIO_YES=1 KIROSTUDIO_PORT=8990 bash install.sh （密钥留空自动生成；install-binary.sh 支持 KIROSTUDIO_NO_SYSTEMD=1 只下载配置不装服务）。

启动后访问 http://<本机IP>:<端口>/admin 打开管理面板，上号即可用。

下面是手动分步方式（需要更细控制时用）。推荐用 Docker，无需本地 Rust / Node 环境。

Docker（推荐）

git clone https://github.com/dwgx/KiroStudio.git
cd KiroStudio

# 准备配置：复制示例并改成你自己的 key
mkdir -p config
cp config.docker.example.json config/config.json
cp credentials.example.social.json config/credentials.json   # 按你的上号方式选择示例

# 起服务
docker compose up -d

默认映射到宿主机 8991 端口（容器内 8990，见 docker-compose.yml）。启动后访问 http://localhost:8991/admin 打开管理面板。

预编译二进制（GitHub Release）

从 Releases 下载对应平台的静态二进制（Linux x86_64 为 kirostudio-linux-x86_64，纯 rustls、静态链接、无运行时依赖）：

# 下载并校验
curl -LO https://github.com/dwgx/KiroStudio/releases/latest/download/kirostudio-linux-x86_64
curl -LO https://github.com/dwgx/KiroStudio/releases/latest/download/kirostudio-linux-x86_64.sha256
sha256sum -c kirostudio-linux-x86_64.sha256
chmod +x kirostudio-linux-x86_64

# 准备配置后运行
./kirostudio-linux-x86_64 -c config/config.json --credentials config/credentials.json

从源码构建

需要 Rust（2024 edition）、Node 20+、pnpm 9+。前端必须先构建产出 admin-ui/dist，rust-embed 才能在编译期嵌入：

# 1. 构建前端
cd admin-ui
pnpm install --frozen-lockfile
pnpm build
cd ..

# 2. 构建后端（纯 rustls 发布构建）
cargo build --release --no-default-features

# 3. 运行
./target/release/kirostudio -c config/config.json --credentials config/credentials.json

配置

KiroStudio 读取两份文件：config.json（服务与安全配置）和 credentials.json（上游登录凭据）。默认在工作目录下查找，也可用命令行参数指定：

kirostudio -c <config.json 路径> --credentials <credentials.json 路径>

config.json

最小可用配置：

{
  "host": "127.0.0.1",
  "port": 8990,
  "apiKey": "sk-换成你自己的强随机-客户端密钥",
  "adminApiKey": "sk-换成你自己的强随机-管理密钥",
  "tlsBackend": "rustls",
  "region": "us-east-1",
  "defaultEndpoint": "ide"
}

常用字段：

安全相关（对外部署建议开启）：

调度与用量：

完整字段与默认值以 src/model/config.rs 为准；未列出的字段均有安全的内置默认值。

credentials.json

上游登录凭据，支持单对象或数组（多凭据）两种格式。凭据含刷新令牌，权限务必收紧为 600：

chmod 600 config/credentials.json

仓库提供多份示例，按你的上号方式选用：

• credentials.example.social.json —— Social 登录
• credentials.example.idc.json —— IAM Identity Center (IdC)
• credentials.example.apikey.json —— Kiro API Key
• credentials.example.multiple.json —— 多凭据数组（含 priority / disabled / endpoint）

也可以不手写凭据文件，直接在管理面板里网页上号。

使用引导

打开管理面板

浏览器访问 http://<host>:<port>/admin，用 adminApiKey 登录。面板包含四个主要区域：

• 概览 —— 服务状态、凭据健康、实时请求速率与用量总览
• 凭据 —— 查看/添加/禁用/删除凭据、优先级、余额、故障计数、导出
• 用量 —— 按时间、模型、凭据、客户端维度的用量分析与设备识别
• 设置 —— 在线调整服务配置

上号

进入「凭据」页，点击添加凭据，选择上号方式：

• Social —— 走浏览器 OAuth 授权，面板轮询完成后自动落库
• IdC（IAM Identity Center） —— 填入 IdC 参数完成设备授权流程
• External IdP —— 外部身份提供方登录

Docker / 服务器部署时，若浏览器无法直连后端本机回调端口，请在 config.json 设置 callbackBaseUrl 为可公网访问的地址（如 https://kiro.example.com），网页回调会打到 {callbackBaseUrl}/api/admin/auth/callback。

客户端接入

任何 Anthropic 协议客户端把 base URL 指向本网关、API Key 用 config.json 里的 apiKey 即可。

以 Claude Code 为例：

export ANTHROPIC_BASE_URL="http://localhost:8990"
export ANTHROPIC_API_KEY="sk-你的-apiKey"
claude

直接调用 API：

# 列出模型
curl http://localhost:8990/v1/models \
  -H "x-api-key: sk-你的-apiKey"

# 创建消息
curl http://localhost:8990/v1/messages \
  -H "x-api-key: sk-你的-apiKey" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'

主要端点：

认证支持 x-api-key 头或 Authorization: Bearer <token> 头。

目录结构

KiroStudio/
├── src/
│   ├── main.rs            # 入口：加载配置/凭据，装配路由与后台任务
│   ├── model/             # 配置与命令行参数模型
│   ├── anthropic/         # Anthropic 协议入站：路由、鉴权、handlers、流式
│   ├── kiro/              # Kiro/AWS Q 上游：协议转换、凭据、token 管理、调度
│   ├── admin/             # 管理 API：凭据管理、上号、用量查询、配置
│   ├── admin_ui/          # 面板静态资源服务（rust-embed 嵌入 dist）
│   ├── usage/             # 用量埋点、聚合、SQLite/JSONL 落盘
│   └── common/            # 安全（CORS/IP/限流）、SSRF 防护等公共组件
├── admin-ui/              # React + Vite 管理面板前端
├── deploy/                # systemd 安装 / 部署 / 蓝绿脚本
├── Dockerfile
├── docker-compose.yml
└── config.example.json    # 配置示例

开发

# 后端
cargo run -- -c config/config.json --credentials config/credentials.json
cargo test                                   # 运行测试

# 前端（独立热更，代理到后端；改完 pnpm build 才会被嵌入）
cd admin-ui
pnpm install
pnpm dev

参与贡献请阅读 CONTRIBUTING.md。

License

本项目基于 MIT License 开源，Copyright (c) 2026 dwgx。

衍生自 hank9999/kiro.rs（MIT License, Copyright (c) 2026 hank9999），原始许可声明一并保留于 LICENSE 文件中。