🌉 kiro2cc-proxy

将 Anthropic Claude API 请求转换为 Kiro API 请求的 Rust 代理服务

🇺🇸 English | 🇨🇳 中文

✅ 支持模型：Claude Sonnet 5.5 · Claude Sonnet 5 · Claude Sonnet 4.5 · Claude Sonnet 4.6 · Claude Opus 5.5 · Claude Opus 5 · Claude Opus 4.5 · Claude Opus 4.6 · Claude Opus 4.7 · Claude Opus 4.8 · Claude Haiku 5.5 · Claude Haiku 4.5 · DeepSeek 3.2 · GLM-5 · MiniMax M2.1 · MiniMax M2.5 · Qwen3-Coder · Kimi K3 · GPT-5.6 Sol · GPT-5.6 Terra · GPT-5.6 Luna

📖 快速导航

🚀 快速开始・ 🍎 macOS 部署・ 🪟 Windows 部署・ 🐧 Linux 部署・ 🔑 获取账号・ ⚙️ 配置详解・ 🤖 接入 Claude Code ・ 🧬 接入 Codex CLI ・ 🔌 API 端点・ 🗺️ 模型映射・ 🛡️ Admin 面板・ ❓ 常见问题・ ⚠️ 注意事项

⚠️ 免责声明

本项目仅供研究使用，Use at your own risk，使用本项目所导致的任何后果由使用人承担，与本项目无关。本项目与 AWS/KIRO/Anthropic/Claude 等官方无关，不代表官方立场。

✨ 功能特性

特性	说明
🔌 Anthropic API 兼容	完整支持 Anthropic Claude API 格式
🧬 OpenAI 兼容 / Codex CLI	提供 `/v1/chat/completions` 与 `/v1/responses` 端点，可直接接入 Codex CLI 及任意 OpenAI SDK 客户端
📡 流式响应	支持 SSE (Server-Sent Events) 流式输出
🔍 WebSearch	内置 WebSearch 工具转换逻辑，即支持CC中网络搜索功能
🔄 Token 自动刷新	自动管理和刷新 OAuth Token
👥 多账号支持	支持配置多个账号，按优先级自动故障转移
⚖️ 负载均衡	支持 `priority`（按优先级）和 `balanced`（均衡分配）两种模式
🔁 智能重试	单账号最多重试 3 次，单请求最多重试 9 次
🧠 Thinking 模式	支持 Claude 的 extended thinking 功能
🛠️ 工具调用	完整支持 function calling / tool use
🛡️ Admin 管理	可选的 Web 管理界面，支持账号管理、余额查询等
🌐 账号级代理	支持为每个账号单独配置 HTTP/SOCKS5 代理

🚀 快速开始（新手必读）

这个项目是什么？

kiro2cc-proxy 是一个代理服务。它把标准的 Anthropic Claude API 请求转发给 Kiro（AWS 的 AI 编程工具），让你可以用 Claude Code使用Kiro账号的模型。

一句话说明白，就是：它能把登录的Kiro账号上的模型代理到claude code上进行使用。否则的话就只能在Kiro IDE或者Kiro Cli上使用。

使用前提：

拥有一个 Kiro 账号（通过 kiro.dev 注册，支持 Social 登录）
从 Kiro IDE 或账号管理工具中导出账号（refreshToken 等信息）
⚠️ 【重要】国内用户：必须配置本地 HTTP/SOCKS5 代理（Clash/V2Ray 等），否则所有 Claude 模型请求均会返回 INVALID_MODEL_ID 错误，无法使用。

整体流程：

安装依赖 → 构建项目 → 启动服务 → 填入账号 → 配置客户端

🍎 本地部署（macOS）

第一步：安装依赖

打开终端，安装 Node.js 和 Rust：

# 安装 Homebrew（如已安装跳过）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 安装完成后重新打开终端，或执行：
source "$HOME/.cargo/env"

第二步：获取项目代码

git clone https://github.com/TsinHzl/kiro2cc-proxy.git
cd kiro2cc-proxy

（可选）安装 Shell 快捷命令

运行项目自带的一键安装脚本，以后可在任意终端直接使用 build_kiro2cc_proxy、build_and_run_kiro2cc_proxy 和 run_kiro2cc_proxy 命令，无需切换到项目目录：

bash setup_shell_aliases.sh
source ~/.zshrc   # zsh 用户；bash 用户执行 source ~/.bashrc

安装后即可使用：

build_kiro2cc_proxy         # 等同于 ./build-mac.sh
build_and_run_kiro2cc_proxy # 等同于 ./build-and-run-mac.sh（先构建后启动）
run_kiro2cc_proxy           # 等同于 ./run-local-service-mac.sh

脚本仅适用于 macOS，自动修改 ~/.zshrc 和 ~/.bashrc（如存在），可重复运行（幂等）。

第三步：构建项目

./build-mac.sh

脚本会依次构建 web-ui/admin-ui 前端、web-ui/user-ui 前端，最后编译 Rust 二进制。首次构建约需 5~15 分钟。

构建成功后输出：

  构建成功！
  二进制位置: ./target/release/kiro2cc-proxy

后续除非更新了代码，否则无需重新构建。

第四步：启动服务

方式一：双击启动（推荐）

在 Finder 中找到项目目录，双击 run-local-service-mac.sh 文件。

方式二：终端启动

./run-local-service-mac.sh

首次启动会进入配置向导：

Admin Password（管理后台密码(http://ip:端口/admin页面)，直接回车跳过）: [默认my-admin-pass]
端口 [默认: 5678]:
Region [默认: us-east-1]:
本地 HTTP 代理端口（例如: 7890 / 10089）: [填入你的代理端口]

⚠️【重要】本地 HTTP 代理端口：也就是开魔法的端口。注意：本地搭建的话，不配置将无法访问 Claude 模型，如Claude4.6和Claude4.7模型
⚠️ 【重要】代理端口（国内用户必须配置）

常在终端上使用的命令如：export http_proxy=http://127.0.0.1:10089; export https_proxy=http://127.0.0.1:10089;

这里的10089就是你开魔法的端口

不知道端口号请查看代理软件的设置页面
Admin Password：管理面板的登录密码(http://ip:端口/admin页面)，建议设置

配置完成后自动生成 app/config/config.json，服务启动，浏览器自动打开管理面板。

后续启动直接读取已有配置，无需重新填写。

第五步：填入 Kiro 账号

服务启动后，打开管理面板 http://127.0.0.1:5678/admin，在账号管理页面点击「KAM导入账号」。该入口兼容单账号和多账号 KAM 导出 JSON，支持粘贴 JSON 文本或拖入 .json 文件。点击「导入」后，账号会先以禁用状态创建并自动执行额度验活；验活成功后自动启用，验活失败时保留账号并保持禁用。

也可以直接创建 app/config/credentials.json，格式见"获取 Kiro 账号"章节。

停止服务

在运行服务的终端窗口按 Ctrl+C，或直接关闭终端窗口。

🪟 本地部署（Windows）

第一步：安装依赖

安装 Node.js（LTS 版本）
安装 Rust（下载并运行 rustup-init.exe）
安装 Git

安装完成后重新打开 PowerShell，确认以下命令可用：

node -v
cargo -v
git -v

第二步：获取项目代码

git clone https://github.com/TsinHzl/kiro2cc-proxy.git
cd kiro2cc-proxy

（可选）安装 PowerShell 快捷命令

运行项目自带的安装脚本，以后可在任意 PowerShell 直接使用 build_kiro2cc_proxy、build_and_run_kiro2cc_proxy 和 run_kiro2cc_proxy 命令，无需切换到项目目录：

.\setup_shell_aliases.ps1
. $PROFILE

安装后即可使用：

build_kiro2cc_proxy         # 等同于 .\build-windows.ps1
build_and_run_kiro2cc_proxy # 等同于 .\build-and-run-windows.ps1（先构建后启动）
run_kiro2cc_proxy           # 等同于 .\run-local-service-windows.ps1

脚本同时更新 Windows PowerShell 5.x 和 PowerShell 7+ 的 profile，可重复运行（幂等）。

第三步：构建项目

以管理员身份打开 PowerShell，先允许执行脚本（仅需一次）：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

然后构建：

.\build-windows.ps1

脚本会依次构建 web-ui/admin-ui 前端、web-ui/user-ui 前端，最后编译 Rust 二进制。首次构建约需 5~15 分钟。

后续除非更新了代码，否则无需重新构建。

第四步：启动服务

.\run-local-service-windows.ps1

首次启动会进入配置向导：

Admin Password（管理后台密码(http://ip:端口/admin页面)，直接回车跳过）: [默认my-admin-pass]
端口 [默认: 5678]:
Region [默认: us-east-1]:
本地 HTTP 代理端口（例如: 7890 / 10089）: [填入你的代理端口]

⚠️【重要】本地 HTTP 代理端口：也就是开魔法的端口。注意：本地搭建的话，不配置将无法访问 Claude 模型，如Claude4.6和Claude4.7模型
⚠️ 【重要】代理端口（国内用户必须配置）

常在终端上使用的命令如：export http_proxy=http://127.0.0.1:10089; export https_proxy=http://127.0.0.1:10089;

这里的10089就是你开魔法的端口

不知道端口号请查看代理软件的设置页面
Admin Password：管理面板的登录密码(http://ip:端口/admin页面)，建议设置

配置完成后自动生成 app/config/config.json，服务启动，浏览器自动打开管理面板。

后续启动直接读取已有配置，无需重新填写。

第五步：填入 Kiro 账号

服务启动后，打开管理面板 http://127.0.0.1:5678/admin，在账号管理页面点击「KAM导入账号」。该入口兼容单账号和多账号 KAM 导出 JSON，支持粘贴 JSON 文本或拖入 .json 文件。点击「导入」后，账号会先以禁用状态创建并自动执行额度验活；验活成功后自动启用，验活失败时保留账号并保持禁用。

停止服务

在运行服务的 PowerShell 窗口按 Ctrl+C，或直接关闭窗口。

🐧 服务器部署（Linux）

方式一：Docker（最简单，推荐）

前置要求：服务器已安装 Docker 和 Docker Compose。

# 1. 克隆仓库
git clone https://github.com/TsinHzl/kiro2cc-proxy.git /opt/kiro2cc-proxy
cd /opt/kiro2cc-proxy

# 2. 创建配置文件（注意：配置文件在 data/ 目录下，不是 data/config/）
mkdir -p data
cp config.example.json data/config.json
nano data/config.json   # 填入 adminPsw

data/config.json 最小配置：

{
  "host": "0.0.0.0",
  "port": 5678,
  "region": "us-east-1",
  "adminPsw": "your-admin-password"
}

⚠️ 【重要】port 字段必须是整数，不能填写 Docker 端口映射格式（如 "0.0.0.0:5678:5678"），否则服务启动失败。正确写法："port": 5678。

# 3. 创建账号文件（也可启动后在管理面板添加）
echo "[]" > data/credentials.json

# 4. 启动
docker compose up -d

# 查看日志
docker compose logs -f

# 停止
docker compose down

服务启动后访问 http://服务器IP:5678/admin 进入管理面板。

注意：docker-compose.yml 中 ports 默认为 "5678:5678"，监听所有网卡。如需限制只允许本机访问，可改为 "127.0.0.1:5678:5678"。同时确保云服务商安全组（腾讯云/阿里云等）已开放 5678 端口的入站规则，否则外网无法访问。

更新到最新版本

cd /opt/kiro2cc-proxy
git pull
docker compose pull
docker compose down && docker compose up -d

说明：每次推送新 tag（如 v1.x.x）后，GitHub Actions 会自动构建并推送新镜像到 ghcr.io。docker compose pull 会拉取最新的 latest 镜像。

方式二：systemd 一键安装

适合不想用 Docker、希望直接跑二进制的场景。

# 1. 克隆仓库
git clone https://github.com/TsinHzl/kiro2cc-proxy.git /opt/kiro2cc-proxy-src
cd /opt/kiro2cc-proxy-src

# 2. 创建配置文件
cp config.example.json app/config/config.json
nano app/config/config.json   # 填入 adminPsw

# 3. 一键安装（自动编译 + 注册 systemd 服务）
sudo bash install_server.sh

安装完成后服务开机自启，常用命令：

systemctl status kiro2cc-proxy       # 查看状态
systemctl restart kiro2cc-proxy      # 重启
systemctl stop kiro2cc-proxy         # 停止
journalctl -u kiro2cc-proxy -f       # 实时日志

方式三：手动后台运行（无 systemd）

bash start_server.sh start     # 后台启动
bash start_server.sh status    # 查看状态
bash start_server.sh log       # 实时日志
bash start_server.sh stop      # 停止
bash start_server.sh restart   # 重启

服务器代理配置

国内服务器无法直接访问 Kiro API，需要在 config.json 中配置代理：

{
  "proxyUrl": "http://your-proxy-host:port"
}

或使用境外服务器（推荐），无需代理。

🔑 获取 Kiro 账号

完整流程：从 Kiro Account Manager 导出到管理面板导入

第一步：从 Kiro Account Manager 导出账号 JSON

安装 Kiro IDE 或 Kiro Account Manager
使用 GitHub / Google 等 Social 账号登录
在账号管理界面找到"导出账号信息"或"Export Account"选项
导出为 JSON 文件（或复制 JSON 内容）

第二步：启动 kiro2cc-proxy 服务

按照"本地部署"或"服务器部署"章节启动服务，确保服务正常运行。

第三步：通过「KAM导入账号」功能导入（推荐）

打开管理面板：http://127.0.0.1:5678/admin（服务器部署则替换为对应 IP）
输入 config.json 中配置的 adminPsw（Admin Password）登录
进入账号管理页面
点击「KAM导入账号」；该入口同时兼容单账号和多账号 KAM 导出 JSON
将导出的 JSON 内容直接粘贴到输入框，或将 .json 文件拖拽到页面上
点击「导入」后，账号会先以禁用状态创建，管理面板随后自动执行额度验活
验活成功后账号自动启用；验活失败时账号会保留并保持禁用，请检查账号配置

ℹ️ HTTP 访问管理面板导入账号

v2.7.3 起已内置纯 JS 降级实现，通过 http://服务器IP:端口/admin（非 HTTPS、非 localhost）访问管理面板也可正常导入账号，无需再配置 HTTPS 或浏览器 flags。

若你使用的是 v2.7.2 及更早版本，仍会因浏览器安全策略禁用 crypto.subtle 而报错 Cannot read properties of undefined (reading 'digest')，请升级到最新版本。

第四步（可选）：手动创建账号文件

也可以跳过管理面板，直接将导出的 JSON 内容保存为文件：

本地部署：app/config/credentials.json
Docker 部署：data/credentials.json

文件格式见下方说明，保存后重启服务生效。

credentials.json 格式

Social 登录（单账号）：

{
  "refreshToken": "your-refresh-token",
  "expiresAt": "2025-12-31T02:32:45.144Z",
  "authMethod": "social"
}

IDC/Builder-ID 登录（单账号）：

{
  "refreshToken": "your-refresh-token",
  "expiresAt": "2025-12-31T02:32:45.144Z",
  "authMethod": "idc",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

多账号（数组格式，支持故障转移）：

[
  {
    "refreshToken": "token-1",
    "expiresAt": "2025-12-31T02:32:45.144Z",
    "authMethod": "social",
    "priority": 0
  },
  {
    "refreshToken": "token-2",
    "expiresAt": "2025-12-31T02:32:45.144Z",
    "authMethod": "social",
    "priority": 1
  }
]

priority 数值越小优先级越高，单账号最多重试 3 次，单请求最多重试 9 次，自动故障转移。

多端点负载均衡（v2.8.7+）

Kiro 上游的 4 个接入端点（ide / runtime / codewhisperer / amazonq）走独立的限流桶。本代理在单账号内自动轮询这些端点：429 时只封禁命中桶（30s 后自动恢复），不影响其它端点、不切换账号。

默认启用全部 4 端点。账号可通过 endpoint 字段声明首选端点（首选在首 + 剩余端点按默认序去重追加）：

{
  "accessToken": "...",
  "endpoint": ["runtime", "codewhisperer"]
}

默认端点顺序：ide → runtime → codewhisperer → amazonq。

回滚指引：若某端点异常，修改 endpoint 字段移除该端点，重启即可（无需重发版本）。

⚙️ 配置详解

config.json 字段说明

字段	必填	默认值	说明
`host`	否	`127.0.0.1`	监听地址，`0.0.0.0` 允许外网/局域网访问
`port`	否	`8080`（本地启动脚本默认写入 `5678`）	监听端口；通过设置页修改后写入 `config.json`，重启后生效
`region`	否	`us-east-1`	AWS 区域
`authRegion`	否	同 `region`	Token 刷新使用的区域
`apiRegion`	否	同 `region`	API 请求使用的区域
`adminPsw`	否	—	Admin Password（管理面板登录密码），不填则不启用管理面板
`proxyUrl`	否	—	HTTP/SOCKS5 代理，如 `http://127.0.0.1:7890`
`proxyUsername`	否	—	代理用户名
`proxyPassword`	否	—	代理密码
`tlsBackend`	否	`rustls`	TLS 后端：`rustls` 或 `native-tls`
`loadBalancingMode`	否	`priority`	`priority`（按优先级）或 `balanced`（轮询）
`maxRpmPerCredential`	否	`0`	单个账号每分钟最大请求数；`0` 表示不限。设置页保存后立即热生效并写入 `config.json`
`forwardSuggestionMode`	否	`false`	Suggestion Mode 输入建议请求放行开关。`false`（默认）时服务端拦截 Claude Code 每轮对话后自动发起的全量上下文预测请求并返回空响应，不产生 Token 消耗；`true` 时正常转发上游，以展示输入建议，但每轮会额外产生一次全量上下文计费请求。可用环境变量 `FORWARD_SUGGESTION_MODE` 覆盖
`clientTokenPassthrough`	否	`false`	客户端 token 直通：`true` 时返回给客户端的 `usage` 字段 1:1 上报真实值；`false`（默认）时按 `0.6657` 系数缩放展示。适用于按返回用量统计上下文占用的第三方客户端；无论开关状态如何，Claude Code 的 auto-compact 触发时机保持不变。可用环境变量 `CLIENT_TOKEN_PASSTHROUGH` 覆盖
`promptCacheAccounting`	否	`false`	按 Anthropic `cache_control` 断点规则模拟缓存记账：`true` 时 `cache_read` / `cache_creation`（含 5m/1h 拆分）按请求中的断点、20 block 回看窗口与 TTL 计算，取代"除最后一条消息外全部计为缓存读、写入恒为 0"的前缀估算；不带 `cache_control` 的请求全部计为普通输入（OpenAI 兼容端点按自动前缀缓存计算）。缓存按 API Key 隔离（类似官方的 workspace 级隔离），模型按映射后的 Kiro 模型 ID 区分；缓存表落盘到配置目录 `prompt_cache.json`，重启后恢复。这是本地模拟：只让下游账单的拆分口径贴近官方，不反映 Kiro 侧真实缓存命中与真实成本（真实成本以 credits 为准）。适用于下游按 usage 计费的网关。可用环境变量 `PROMPT_CACHE_ACCOUNTING` 覆盖
`promptCacheMinTokens`	否	`0`	断点记账最小可缓存长度的全局覆盖（token）。`0`（默认）按模型取 Anthropic 官方值：Opus 5.5 / Opus 5 / Sonnet 5.5 / Haiku 5.5 等为 512，Opus 4.7 为 2048，Opus 4.6 / Opus 4.5 / Haiku 4.5 为 4096，其余为 1024；`> 0` 时对所有模型统一使用该值。可用环境变量 `PROMPT_CACHE_MIN_TOKENS` 覆盖
`modelsOfficialAliases`	否	`false`	`true` 时 `/v1/models` 为上游点号模型 ID 追加官方连字符别名（如 `claude-opus-4.6` → `claude-opus-4-6`，4.5 代际再追加带日期的 ID），供按模型列表生成映射的下游网关使用；默认关闭，避免 Claude Code 模型选择器出现重复项。可用环境变量 `MODELS_OFFICIAL_ALIASES` 覆盖
`outputTokensIncludeThinking`	否	`false`	`true` 时返回给客户端的 `output_tokens` 包含 thinking（与 Anthropic 官方口径一致）；`false`（默认）只计可见输出。可用环境变量 `OUTPUT_TOKENS_INCLUDE_THINKING` 覆盖
`writeChunkingMaxLines`	否	`300`	分块写入约束的行数上限（见常见问题中 `Reset(StreamId(1), INTERNAL_ERROR, Remote)` 一条）：请求带 Write / Edit / MultiEdit 工具时，在系统提示末尾要求单次工具调用的参数不超过约 N 行。调大更省 credits 但更易触发上游约 240s 的流重置，`0` 表示不追加约束。可在 Admin 设置页热修改，仅影响之后的新请求。可用环境变量 `WRITE_CHUNKING_MAX_LINES` 覆盖
`thinkingAsText`	否	`false`	思考内容文本化（仅 Claude Code 客户端）：`true` 时把 thinking 块改写为 markdown 引用文本、以 ANSI 变暗（灰色）样式逐行流式展示（类似 Kiro CLI），解决 CC 默认折叠/隐藏 thinking 导致长推理期间像卡住的问题。两种模式下客户端（Claude Code）上下文都包含思考内容，但回传上游时都会整块丢弃：关闭时丢弃原生 thinking 块，开启时丢弃「💭 Thinking」标记行、思考正文与时长行，上游上下文不含思考内容（仅当流被中断、缺少时长行时，保守降级为只剥标记行）。可用环境变量 `THINKING_AS_TEXT` 覆盖
`debugLogs`	否	`false`	DEBUG 日志开关：`true` 时控制台、日志文件（`logFile`）与 Admin「查看日志」页三处同步输出 DEBUG 级别事件，可在 Admin 设置页热切换（无需重启）并写回 config.json；关闭后停止捕获新的 DEBUG，已捕获的记录保留。注意该开关返回/保存的是开关状态而非实际生效档位：设置 `RUST_LOG` 环境变量时，其指令仍优先（开关仅在 `RUST_LOG` 基础上追加全局 `debug` 指令，target 定向指令不受影响）。日志量会显著增加，排障后建议关闭。可用环境变量 `DEBUG_LOGS` 覆盖

TLS 说明：如遇到 Token 刷新失败或请求报错，尝试将 tlsBackend 改为 native-tls。

完整配置示例：

{
  "host": "0.0.0.0",
  "port": 8080,
  "region": "us-east-1",
  "adminPsw": "my-admin-password",
  "proxyUrl": "http://127.0.0.1:7890",
  "tlsBackend": "rustls",
  "loadBalancingMode": "priority",
  "maxRpmPerCredential": 0,
  "forwardSuggestionMode": false,
  "clientTokenPassthrough": false,
  "thinkingAsText": false,
  "debugLogs": false
}

设置页的运行时配置

配置 adminPsw 后，可在 Admin 设置页直接管理以下选项；每次保存都会写回 config.json。

设置	`config.json` 字段	保存后的行为
Suggestion Mode 输入建议	`forwardSuggestionMode`	立即热生效
客户端 token 直通	`clientTokenPassthrough`	立即热生效
思考内容文本化展示	`thinkingAsText`	立即热生效，仅影响之后的新请求
DEBUG 日志	`debugLogs`	立即热生效，控制台 / 日志文件 / 日志页三处一致
每账号 RPM 上限	`maxRpmPerCredential`	立即热生效，`0` 表示不限
分块写入行数上限	`writeChunkingMaxLines`	立即热生效，仅影响之后的新请求，`0` 表示不追加约束
监听端口	`port`	重启服务后生效，范围为 `1–65535`
上游代理地址	`proxyUrl`	重启服务后生效；支持 `http`、`https`、`socks5`，留空表示不使用代理

客户端鉴权说明：config.json 不再提供全局 API Key。客户端调用 /v1/messages、/cc/v1/messages 时，需使用 Admin 后台（adminPsw 登录）创建并启用的子 API Key 进行鉴权。注：若未配置 adminPsw，Admin 面板本身将被禁用，无法创建子 API Key，需先完成配置。

账号级代理

可以为每个账号单独配置代理，优先级高于全局代理：

[
  {
    "refreshToken": "token-a",
    "authMethod": "social",
    "proxyUrl": "socks5://proxy-a.example.com:1080"
  },
  {
    "refreshToken": "token-b",
    "authMethod": "social",
    "proxyUrl": "direct"
  }
]

proxyUrl: "direct" 表示该账号强制直连，不走任何代理。

Region 配置优先级

Auth Region（Token 刷新）：账号.authRegion > 账号.region > config.authRegion > config.region

API Region（API 请求）：账号.apiRegion > config.apiRegion > config.region

🤖 接入 Claude Code

方式一：cc-switch 一键导入（推荐）

管理员：Admin 面板 → API Key 管理，在目标 Key 那一行点 🤖 图标
终端用户：用 API Key 登录用户面板（/user），在「一键导入 cc-switch」卡片点「导入 Claude Code」

方式二：环境变量

服务启动后，在终端中设置以下环境变量即可让 Claude Code 使用本代理：

export ANTHROPIC_BASE_URL="http://127.0.0.1:5678"
export ANTHROPIC_API_KEY="在管理面板 API Key 管理页面创建的 Key"

永久生效（加入 ~/.zshrc 或 ~/.bashrc）：

echo 'export ANTHROPIC_BASE_URL="http://127.0.0.1:5678"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="在管理面板 API Key 管理页面创建的 Key"' >> ~/.zshrc
source ~/.zshrc

方式三：settings.json 配置

在 Claude Code 的配置文件中直接写入代理地址，无需每次设置环境变量。

配置文件路径：

全局配置：~/.claude/settings.json
项目配置：<项目根目录>/.claude/settings.json（仅对当前项目生效）

在配置文件中添加以下内容：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:5678",
    "ANTHROPIC_API_KEY": "在管理面板 API Key 管理页面创建的 Key"
  }
}

如果文件已有其他配置，将 env 字段合并进去即可：

{
  "theme": "dark",
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:5678",
    "ANTHROPIC_API_KEY": "在管理面板 API Key 管理页面创建的 Key"
  }
}

验证是否生效：

curl http://127.0.0.1:5678/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "hi"}]
  }'

🧬 接入 Codex CLI / OpenAI SDK

除 Anthropic 协议外，代理同时提供两个 OpenAI 兼容端点，因此可以直接用 Kiro 额度驱动 Codex CLI 或任意 OpenAI SDK 客户端。两个端点都是"翻译 + 转发"：请求转成 Anthropic 格式后复用 /v1/messages 的完整下游链路（多账号故障转移、RPM 计数、用量统计、限流处理），响应再转回 OpenAI 格式。

接入 Codex CLI

方式一：cc-switch 一键导入（推荐）

管理员：Admin 面板 → API Key 管理，在目标 Key 那一行点 ⌨️ 图标
终端用户：用 API Key 登录用户面板（/user），在「一键导入 cc-switch」卡片点「导入 Codex」

方式二：手动编辑 config.toml

编辑 ~/.codex/config.toml（Codex CLI 与 ChatGPT.app 桌面客户端共用同一份文件）：

model = "gpt-5.6-terra"
model_provider = "kiro"

[model_providers.kiro]
name = "kiro2cc-proxy"
base_url = "http://127.0.0.1:5678/v1"  # 本机部署用 127.0.0.1；服务器部署请替换为你的域名或公网 IP
wire_api = "responses"        # 推荐填 "responses"，也可填 "chat"
env_key = "KIRO_API_KEY"

密钥写进 ~/.codex/.env（Codex 底层静态链接了 Rust dotenvy crate，每次调用都会自动重新加载该文件，配置全部集中在 ~/.codex/ 目录内，不需要碰任何 shell 环境变量，改完立即生效也不用重启）：

echo 'KIRO_API_KEY=your-api-key' > ~/.codex/.env
chmod 600 ~/.codex/.env
codex

避免重复定义：若用 -p/--profile <name> 建了 ~/.codex/<name>.config.toml，profile 会层叠在 config.toml 之上——只有 profile 里显式写的字段才会覆盖，未写的字段从 base config 继承。若 profile 的 model/model_provider 等字段与 base config 完全一样，说明这份 profile 已经冗余（可用 codex exec 分别不带 -p 和带 -p <name> 各跑一次对比输出验证），直接删掉即可，没必要维护两份相同配置。

ChatGPT.app 桌面客户端同样读取这份 config.toml（顶层 model_provider 生效，暂无独立 profile 机制），但它是常驻进程启动时一次性加载配置，改 config.toml 后需要完全重启 App 才生效；而 ~/.codex/.env 每次调用都重新读取，改完立即生效，不用重启。

wire_api 两种取值：

取值	使用的端点	说明
`responses`	`/v1/responses`	Codex CLI 默认协议，功能最完整（含 reasoning 事件、自由文本工具）
`chat`	`/v1/chat/completions`	通用 Chat Completions 协议，兼容性最广

两者都支持流式与工具调用往返，日常使用推荐 responses。

接入 OpenAI SDK

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

模型名可填 gpt-5.6-terra / gpt-5.6-luna / gpt-5.6-sol，也可直接填 claude-* 系模型名（原样透传给上游）。Codex CLI 自带的 gpt-5-codex / gpt-5.1-codex 会自动映射到 gpt-5.6-terra，gpt-5.1-codex-max 映射到 gpt-5.6-luna。

已知限制

不支持 previous_response_id —— 代理无状态，不保存历史响应。带该字段的请求直接返回 400 且不产生上游调用；请在 input 中回传完整对话历史（Codex CLI 默认即如此，无需额外配置）。
tool_choice 仅支持 auto —— 其他取值（required / 指定函数名）会记 WARN 后按 auto 处理，这是上游 Kiro API 的既有限制。
reasoning.effort 对 gpt-5.6-luna 无效 —— 该模型上游恒返回 thinking=0。
include: ["reasoning.encrypted_content"] 被忽略 —— 代理不产出加密 reasoning 内容。

🔌 API 端点

标准端点 (/v1)

端点	方法	说明
`/v1/models`	GET	获取可用模型列表
`/v1/messages`	POST	创建消息（对话）
`/v1/messages/count_tokens`	POST	估算 Token 数量

OpenAI 兼容端点 (/v1)

端点	方法	说明
`/v1/chat/completions`	POST	OpenAI Chat Completions 协议，支持流式、工具调用、`reasoning_effort`
`/v1/responses`	POST	OpenAI Responses 协议，Codex CLI 默认 `wire_api`

详见 🧬 接入 Codex CLI / OpenAI SDK。

Claude Code 兼容端点 (/cc/v1)

端点	方法	说明
`/cc/v1/messages`	POST	实时流式转发，带 300s 上游挂起保护
`/cc/v1/messages/count_tokens`	POST	估算 Token 数量

/cc/v1/messages 与 /v1/messages 同为实时流式转发（上游首帧到达即转发），唯一差异是带 300 秒全局 deadline —— 上游长时间无响应时发送 overloaded_error 后终止，已流出的内容保持有效。两个端点均每 25 秒发送 ping 保活。

客户端认证

支持两种方式：

x-api-key: your-api-key

或

Authorization: Bearer your-api-key

🗺️ 模型映射

发送请求时可使用任意包含以下关键词的模型名，会自动映射到对应 Kiro 模型：

请求模型名（含关键词）	实际使用的 Kiro 模型
`sonnet`（含 5.5/5-5）	`claude-sonnet-5.5`
`sonnet`（含 4.6/4-6）	`claude-sonnet-4.6`
`sonnet`（含 5/sonnet-5）	`claude-sonnet-5`
`sonnet`（其他）	`claude-sonnet-4.5`
`opus`（含 5.5/5-5）	`claude-opus-5.5`
`opus`（含 5/opus-5）	`claude-opus-5`
`opus`（含 4.5/4-5）	`claude-opus-4.5`
`opus`（含 4.7/4-7）	`claude-opus-4.7`
`opus`（含 4.8/4-8）	`claude-opus-4.8`
`opus`（其他）	`claude-opus-4.6`
`fable`	`claude-fable-5`
`haiku`（含 5.5/5-5）	`claude-haiku-5.5`
`haiku`	`claude-haiku-4.5`
`deepseek`	`deepseek-3.2`
`glm`	`glm-5`
`minimax`（含 2.5/2-5）	`minimax-m2.5`
`minimax`（其他）	`minimax-m2.1`
`qwen`	`qwen3-coder-next`
`kimi`	`kimi-k3`
`gpt`（含 terra）	`gpt-5.6-terra`
`gpt`（含 luna）	`gpt-5.6-luna`
`gpt`（含 sol，或含 5.6/5-6 但无具体变体名，默认落到旗舰档）	`gpt-5.6-sol`

🛡️ Admin 管理面板

配置了 adminPsw（Admin Password）后，访问 http://127.0.0.1:5678/admin 进入管理面板。

功能：

查看所有账号状态（是否有效、失败次数等）
添加 / 删除账号
通过「KAM导入账号」导入单个或多个 KAM 账号并自动验活
启用 / 禁用单个账号
调整账号优先级
查看各账号余额
重置账号失败状态

Admin API（需要 x-api-key 或 Authorization: Bearer 认证）：

端点	方法	说明
`/api/admin/credentials`	GET	获取所有账号
`/api/admin/credentials`	POST	添加账号
`/api/admin/credentials/:id`	DELETE	删除账号
`/api/admin/credentials/:id/balance`	GET	查询余额

❓ 常见问题

Q：启动后提示"已加载 0 个账号配置"

需要创建 app/config/credentials.json（本地）或 data/credentials.json（Docker），参考"获取 Kiro 账号"章节。

Q：请求返回 INVALID_MODEL_ID

⚠️ 【重要】 国内 IP 无法直接访问 Claude 模型。必须在 app/config/config.json 中配置 proxyUrl（如 "proxyUrl": "http://127.0.0.1:7890"），或使用境外服务器。这是国内用户最常见的问题。

Q：使用 GPT-5.6 系列模型（sol/terra/luna）时，thinking 模式、output effort 或 max_tokens 设定似乎没有生效

GPT-5.6 系列的 Kiro 后端 schema 不支持 additionalModelRequestFields（涵盖 thinking / output_config effort / max_tokens 三个子字段），与 Claude 4.5 代际（Sonnet 4.5 / Opus 4.5 / Haiku 4.5）一样会被整体跳过，属已知限制，非本项目 bug。

Q：请求返回 401 Unauthorized

检查客户端使用的 API Key 是否是 Admin 后台创建且已启用的子 API Key，未启用或已删除的 Key 会被拒绝。

Q：Token 刷新失败 / 请求报错

尝试将 config.json 中的 tlsBackend 改为 native-tls 后重启服务。

Q：通过管理面板导入账号时报错 Cannot read properties of undefined (reading 'digest')

此问题已在 v2.7.3 修复：crypto.subtle 加密 API 只在 HTTPS 或 localhost 环境下可用，公网 IP + HTTP 访问会触发此错误，v2.7.3 起自动降级为纯 JS 实现，无需再配置 HTTPS。若仍报错，请升级到最新版本。

Q：企业版 IdC 账号请求返回 502，日志显示 profileArn is required for this request

企业版（Enterprise）IdC 账号调用 Q 端点强制要求 profileArn，但 IdC Token 刷新接口不会返回该字段，需要手动填写。管理面板「添加账号 / 编辑账号」对话框中已提供 Profile ARN 输入框，填入形如 arn:aws:codewhisperer:<region>:<account-id>:profile/<profile-id> 的值即可。profileArn 可从 Kiro IDE 本地缓存或 ListAvailableProfiles 获取，其所在 region 需与账号的 apiRegion 保持一致。Social 账号一般无需填写。

Q：填写了 profileArn 后，企业版 IdC 账号查询余额仍返回 403 Forbidden: Invalid token

此问题已修复：AWS SSO OIDC 刷新接口会同时返回 accessToken（SSO portal session token）和 idToken（JWT），Amazon Q 数据面接口（对话请求）只接受 idToken，而额度查询接口（getUsageLimits）需要的是原始 accessToken——此前代理内部只保存了一份 token 并复用于两处，导致二者只能满足其一。修复后代理会分别保存两个 token 并按接口用途选用，无需用户任何操作，账号下一次刷新 Token 后自动生效（credentials.json 会新增内部字段 ssoAccessToken，向后兼容旧配置文件，无需手动编辑）。若升级后仍报错，尝试在管理面板重置该账号或等待 Token 自动过期刷新。

Q：子 API Key 消费额度能按真实 Kiro credits 计量吗（而不是估算的美元）

能。创建/编辑子 API Key 时，额度单位可选「美元估算」或「真实 Credits」（limitUnit：usd/credits）。选择 credits 时，额度按 usage 记录中的真实 credits_used 累加计量（旧记录无 credits_used 字段时按 estimated_cost × k_ref 回退估算）。默认为 usd，向后兼容现有配置。

Q：长生成轮约 4 分钟（~247s）后报 Server error mid-response，代理日志出现 Reset(StreamId(1), INTERNAL_ERROR, Remote)

这是上游（Kiro 网关）主动重置 HTTP/2 流，不是代理超时（代理上游超时为 1000s）。代理收到 Reset 时若已有部分输出，会立即向客户端补发 overloaded_error（不会伪装成正常完成），客户端随后自动重试。该问题在不经代理、直接使用 Kiro CLI 时同样复现，可确认根因在上游一侧，与代理转发链路和客户端无关。

实测定位到一个可复现的触发条件：模型一次生成很大的工具调用参数（典型是用 Write 一次写入上万字的文件）。上游不会增量流式输出工具参数，生成期间该流没有任何数据，静默约 240s 后上游以 RST_STREAM(INTERNAL_ERROR) 重置（实测写入约 8000 字耗时约 215s 可成功，约 20000 字约 240s 必定失败，且与 thinking adaptive 开关无关；原样重试会再次失败；HTTP/2 PING 保活无效）。纯文本流和 thinking 阶段持续输出，实测 794s 仍正常结束。

代理的处理：请求带 Write / Edit / MultiEdit 任一工具时，会在系统提示末尾追加一条固定的分块写入约束（单次工具调用的参数不超过约 N 行，N 默认 300，由 writeChunkingMaxLines 配置：Write 的 content、Edit 的 new_string、一次 MultiEdit 内所有编辑的合计都按此计；更大内容先用 Write 写开头，再用多次 Edit / Bash 追加，大的 MultiEdit 拆成多次调用），让模型把大改动拆成多次调用。该约束对 Write 的实测使 4 次大文件写入请求全部在约 2 分钟内正常结束（Edit / MultiEdit 部分尚未单独实测）；不改动客户端的工具描述。

取舍（issue #46 后续反馈）：该约束会让模型把一次大写入拆成多轮，而客户端每轮都携带 thinking: adaptive、每轮都会重新思考。用户在自己环境的统计显示，同类任务的 credits 约为无约束时的 3 倍（我没有复现）。因此上限做成了可配置的 writeChunkingMaxLines：调大更省 credits，但单次写入更容易撞到约 240s 的重置；调小更稳但更贵；设为 0 则完全不追加约束（需自行控制单次写入粒度）。默认值 300 是按 issue 里的实测输出速度（约 8000 汉字 ~215s 可成功、约 20000 汉字 ~240s 必失败）折算的估计，未在真实 Claude Code 上验证；如仍遇到 Reset，请调小。可在 Admin 设置页热修改（仅影响之后的新请求），也可用环境变量 WRITE_CHUNKING_MAX_LINES 覆盖。

仍可能发生的情况：模型不遵从约束，或同一回合并行调用多个写入类工具（各自不超限、但合计生成时间过长，该场景尚未实测）时，仍可能触发同样的重置，此时可手动让模型分段写入，或在 issue 中附上日志（stream_elapsed_secs 字段记录流断开时已持续的时长）。注意：这是在本地环境（单账号、Opus 4.6、SOCKS5 出口）的实测结论，issue 作者环境未验证。

说明：agentContinuationId 是代理从 conversationId 派生的会话稳定标识（用于 prompt cache 与账号粘性路由），并不是上游的"断点续跑"句柄，代理无法在 Reset 后自动续写剩余内容；代理到客户端方向已每 25 秒发送 ping 保活，而 Reset 来自上游一侧，客户端侧保活无法避免。

Q：端口被占用

run-local-service-mac.sh 会自动终止占用端口的进程。如仍报错，手动执行：

lsof -ti:5678 | xargs kill -9

Q：Write Failed / 会话卡死

输出过长被截断导致，调低客户端的 max_tokens 上限。

Q：局域网内其他设备无法访问

将 config.json 中的 host 改为 0.0.0.0，确认防火墙已开放对应端口。

Q：如何更新到最新版本（Docker 部署）

cd /opt/kiro2cc-proxy
git pull
docker compose pull
docker compose down && docker compose up -d

Q：如何更新到最新版本（本地部署）

git pull
./build-and-run-mac.sh   # 或分开执行：./build-mac.sh && ./run-local-service-mac.sh

⚠️ 注意事项

credentials.json 包含敏感 Token，不要提交到版本控制，不要分享给他人
服务会自动刷新过期 Token，无需手动干预
多账号模式下 Token 刷新后自动回写到文件
国内用户必须配置代理才能访问 Claude 模型

📂 项目结构

kiro2cc-proxy/
├── src/                    # Rust 源码
├── web-ui/                 # 前端源码根目录
│   ├── admin-ui/           # 管理面板前端
│   └── user-ui/            # 用户面板前端
├── app/config/             # 本地配置目录（gitignored）
├── config.example.json     # 配置示例
├── docker-compose.yml      # Docker 部署配置
├── Dockerfile              # Docker 镜像构建
├── build-mac.sh            # 一键构建脚本（macOS）
├── build-windows.ps1       # 一键构建脚本（Windows）
├── build-and-run-mac.sh            # 一键构建并启动脚本（macOS）
├── build-and-run-windows.ps1       # 一键构建并启动脚本（Windows）
├── run-local-service-mac.sh         # macOS 本地启动脚本
├── run-local-service-windows.ps1   # Windows 本地启动脚本
├── setup_shell_aliases.sh  # macOS Shell 快捷命令安装脚本
├── setup_shell_aliases.ps1 # Windows PowerShell 快捷命令安装脚本
├── install_server.sh       # Linux systemd 一键安装脚本
└── start_server.sh         # Linux 手动后台管理脚本

📜 License

MIT

🙏 致谢

本项目基于 kiro.rs 二次开发，感谢原作者的开源贡献。

感谢所有为本项目做出贡献的开发者（排名不分先后）：

特别致谢——以下 Issue 直接推动了关键修复：

AX10MER — #47 定位 history[0] 冻结缓存 key 漂移导致 Kiro 前缀缓存逐轮失效
C2Y-cyber — #46 定位长生成轮约 247s 被上游 Reset，促成大参数工具调用分块写入约束
XiaoZhuiWang — #40 反馈 sonnet 5 反代响应慢，促成 effort 兜底值下调

感谢每一位提交 Issue、反馈建议和参与讨论的用户，是你们让这个项目不断完善。

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.claude/skills/cache-credits-analyzer		.claude/skills/cache-credits-analyzer
.github/workflows		.github/workflows
.vscode		.vscode
app/config		app/config
assets		assets
docs		docs
openspec		openspec
scripts		scripts
src		src
tools		tools
web-ui		web-ui
.dockerignore		.dockerignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
build-and-run-mac.sh		build-and-run-mac.sh
build-and-run-windows.ps1		build-and-run-windows.ps1
build-mac.sh		build-mac.sh
build-windows.ps1		build-windows.ps1
config.example.json		config.example.json
docker-compose.yml		docker-compose.yml
fly.toml		fly.toml
install_server.sh		install_server.sh
kiro2cc-proxy.service		kiro2cc-proxy.service
run-debug-mac.sh		run-debug-mac.sh
run-local-service-mac.sh		run-local-service-mac.sh
run-local-service-windows.ps1		run-local-service-windows.ps1
server.env.example		server.env.example
setup_shell_aliases.ps1		setup_shell_aliases.ps1
setup_shell_aliases.sh		setup_shell_aliases.sh
start_server.sh		start_server.sh
test-cache.sh		test-cache.sh

Latest commit

History

Folders and files

Repository files navigation

🌉 kiro2cc-proxy

📖 快速导航

⚠️ 免责声明

✨ 功能特性

🚀 快速开始（新手必读）

🍎 本地部署（macOS）

第一步：安装依赖

第二步：获取项目代码

（可选）安装 Shell 快捷命令

第三步：构建项目

第四步：启动服务

第五步：填入 Kiro 账号

停止服务

🪟 本地部署（Windows）

第一步：安装依赖

第二步：获取项目代码

（可选）安装 PowerShell 快捷命令

第三步：构建项目

第四步：启动服务

第五步：填入 Kiro 账号

停止服务

🐧 服务器部署（Linux）

方式一：Docker（最简单，推荐）

更新到最新版本

方式二：systemd 一键安装

方式三：手动后台运行（无 systemd）

服务器代理配置

🔑 获取 Kiro 账号

完整流程：从 Kiro Account Manager 导出到管理面板导入

credentials.json 格式

多端点负载均衡（v2.8.7+）

⚙️ 配置详解

config.json 字段说明

设置页的运行时配置

账号级代理

Region 配置优先级

🤖 接入 Claude Code

方式一：cc-switch 一键导入（推荐）

方式二：环境变量

方式三：settings.json 配置

🧬 接入 Codex CLI / OpenAI SDK

接入 Codex CLI

方式一：cc-switch 一键导入（推荐）

方式二：手动编辑 config.toml

接入 OpenAI SDK

已知限制

🔌 API 端点

标准端点 (/v1)

OpenAI 兼容端点 (/v1)

Claude Code 兼容端点 (/cc/v1)

客户端认证

🗺️ 模型映射

🛡️ Admin 管理面板

❓ 常见问题

⚠️ 注意事项

📂 项目结构

📜 License

🙏 致谢

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages