kiro2claude

用你自己的 kiro-cli 套餐,给任何 Claude / OpenAI 客户端供能。

双协议兼容网关:把 kiro-cli(Kiro 后端)包装成 Anthropic Messages API + OpenAI Chat Completions / Responses API。改个 base URL,Claude Code、Cursor、OpenAI SDK、Codex CLI 直接接入,账单走你的 kiro-cli,后端对客户端透明。

免责声明:非官方项目,与 AWS、Amazon、Anthropic、OpenAI、Kiro 均无关联、未获授权;上述名称为各自所有者的商标,此处仅用于说明 API 协议兼容。仅供学习研究、非商业用途;接入第三方代理可能违反上游服务条款并导致账号封停。软件按 MIT「原样(AS IS)」提供、不含任何担保,风险与法律责任自负。

• 双协议、三端点——/claude/v1(Messages)+ /openai/v1(Chat Completions & Responses)。一套凭据同时喂 Anthropic 和 OpenAI 生态,不用起两个服务。
• 模型全,reasoning 原生——Claude 全系 + GPT-5.6(Sol / Terra / Luna)。Extended Thinking(adaptive)与 reasoning_effort 直接映射 Kiro 原生 reasoning,不靠 prompt 硬凑。
• 真客户端跑通,不只是"兼容 SDK"——Claude Code、Codex CLI 的对话 + 工具调用端到端实测过(harness 在 tools/)。
• 替你抠上游的坑——工具调用文本救援、空流自动重试、/api/* 去插件字段镜像:把 Kiro 的偶发毛病在网关层吸收掉,客户端无感。
• 插件化,全 MIT——计量、credit 反演都是插件,经 @kiro2claude/plugin-api 契约接入;写自己的插件不用碰 core。
• 零配置文件——纯环境变量,复用 kiro-cli 的 SQLite 凭据,token 到期自动刷新。

此外支持 Vision、流式 SSE 和 count_tokens。Messages 接口还支持 hosted WebSearch(web_search_20250305 → Kiro MCP),流式与非流式均保留结构化搜索结果及来源 URL。

flowchart LR
    client["Claude / OpenAI 客户端"]
    gw["kiro2claude · Fastify"]
    kiro["runtime.{region}.kiro.dev"]
    oidc["AWS SSO OIDC"]
    db[("kiro-cli data.sqlite3")]

    client -->|"Messages / Chat / Responses"| gw
    gw -->|"请求 · Smithy awsJson1.0"| kiro
    kiro -->|"响应 · AWS Event Stream"| gw
    gw <-->|"读取 / 到期刷新 token"| db
    gw -->|"CreateToken 刷新"| oidc

• 认证——kiro-cli device code flow(Builder ID / IAM Identity Center),见 kiro.dev 文档
• 上游——POST runtime.<region>.kiro.dev/,请求 Smithy awsJson1.0、按 x-amz-target 区分操作:对话走 GenerateAssistantResponse(响应 AWS Event Stream),WebSearch 走 InvokeMCP
• 存储——复用 kiro-cli 的 SQLite 凭据,token 到期就地刷新

# 1. 装好 kiro-cli 并登录(凭据写入本地 SQLite)
kiro-cli login --use-device-flow --identity-provider https://your-idc.awsapps.com/start --region us-east-1
# 或 Builder ID:kiro-cli login --use-device-flow --license free

# 2. 装依赖、起服务
pnpm install
KIRO2CLAUDE_API_KEY=sk-local-test \
KIRO2CLAUDE_SQLITE_DB_PATH="$HOME/Library/Application Support/kiro-cli/data.sqlite3" \
pnpm dev

Linux 的 SQLite 路径是 ~/.local/share/kiro-cli/data.sqlite3(macOS 路径含空格,必须带引号)。

服务默认监听 127.0.0.1:8080。Claude 客户端(Anthropic SDK / Claude Code)base URL 指向 http://127.0.0.1:8080/claude(SDK 自动补 /v1/messages)、key 设为 sk-local-test:

curl -s http://127.0.0.1:8080/claude/v1/messages \
  -H 'x-api-key: sk-local-test' -H 'content-type: application/json' \
  -d '{"model":"claude-opus-4-8","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}' \
  | jq '.content[0].text'

core 的接口用 KIRO2CLAUDE_API_KEY 鉴权(/、/health 除外);插件路由由插件自己用 ctx.apiKey 鉴权。

想要计量字段用 /claude/v1;想要纯标准响应用 /api/claude/v1(计量后台照跑)。OpenAI 客户端 base URL 指到 .../openai/v1、Authorization: Bearer <key>。模型 ID 见 models-catalog.ts,Claude 每个模型都有 -thinking 变体。

单一镜像 ghcr.io/yupanzi/kiro2claude(公开、免鉴权 pull),内置 core + 两个默认启用的插件。

docker pull ghcr.io/yupanzi/kiro2claude:latest
cp .env.example .env   # 填 KIRO2CLAUDE_API_KEY;删掉 KIRO2CLAUDE_SQLITE_DB_PATH 行(镜像已内置,--env-file 不剥引号)

docker run -d --name kiro2claude --env-file .env \
  -e KIRO2CLAUDE_HOST=0.0.0.0 \
  -e KIRO2CLAUDE_LOGIN_START_URL=https://d-xxx.awsapps.com/start \
  -e KIRO2CLAUDE_LOGIN_REGION=us-east-1 \
  -p 8080:8080 \
  -v kiro-home:/home/kiro/.local/share/kiro-cli \
  ghcr.io/yupanzi/kiro2claude:latest

docker logs -f kiro2claude   # 跟随日志,浏览器打开 device flow URL 完成认证

设了 KIRO2CLAUDE_LOGIN_START_URL 即容器免交互登录:首次启动在日志打出 device flow URL。本地构建用 ./scripts/docker-build.sh -t kiro2claude。

实现 @kiro2claude/plugin-api 契约即可扩展网关(加路由、往 usage 注入 wire 字段),不用改 core——loader 发现 core 所在 node_modules 第一层里带 kiro2claude-plugin keyword 的包,按 dependsOn 拓扑加载(第三方插件要装成 core 的依赖)。指南见 docs/PLUGIN-DEVELOPMENT.md,示范见 echo-plugin。

镜像内置两个插件(默认开):

• plugin-metering——计量本次 credit 消耗,注入 usage.kiro_metering(KIRO2CLAUDE_METERING_DISABLE=true 可关)
• plugin-derived——把 Kiro credit 反演成 Anthropic 风格 token/cache 字段:默认直接覆写标准 input_tokens / cache_*(OpenAI 侧为 cached_tokens),KIRO2CLAUDE_DERIVED_INCLUDE_FIELD=true 时改为注入 usage.kiro_derived(含 USD 成本拆分)

pnpm test        # vitest 全套
pnpm typecheck   # tsc --noEmit
pnpm check       # biome format + lint(不写盘)
pnpm run ci      # biome ci + typecheck + test

pnpm workspace,Node ≥ 22 / TypeScript / ES Modules。husky pre-commit 强制 biome check + typecheck + vitest + markdownlint,pnpm install 后自动生效;提交遵循 Conventional Commits,细节见 CONTRIBUTING.md。

网关只能修上游 wire 与协议翻译层的问题;下面这些在链路里仍然存在,单测全绿不等于会话无损:

• system prompt 只能以 user 级权重进模型,身份覆写因此不可靠:Kiro wire 没有 system 字段,additionalContext 这类结构化字段上游收下即丢(2026-09-10 实测:塞进去的内容模型一概不知、input token 不变)。网关把 system 文本折进首条 user 消息正文,不造任何 assistant 轮次;但它压不过上游自己的系统提示,直接问「你是谁」时模型多半自报 Kiro / AWS。KIRO2CLAUDE_IDENTITY_OVERRIDE 追加的身份指令实测 opus-5 只有约三成、opus-4-6 0/2 生效,换措辞与位置都改不了,故默认关。长上下文 + 真实工具调用的 A/B(24 会话、352 次调用)显示,折进正文与另起合成轮次相比,工具调用与任务完成率没有可测差异。
• continuation 文案偶发进正文:请求以 assistant 结尾时(prefill 或上轮中断的续接),Kiro 只接受 user 作为当前消息,网关把该 assistant 内容留在历史并追加一句续写指令。实测 7 次里 2 次模型把指令句尾复述进可见输出;这也不是字节级 prefill。
• 客户端省略的历史无法还原:上轮的 thinking、被自动压缩掉的内容不再随请求发来时,网关没有跨请求存储,不擅自复活。Claude Code 自动压缩(实测约第 50 个请求触发)保留主线任务与未完成项,但会丢部分 API 签名、返回结构、错误码拼写等细节。
• GPT 推理不可读,Chat Completions 上不回传:上游只给占位文本和密文签名,网关不把它当明文展示。Messages 下发为 redacted_thinking、Responses 在声明 include:["reasoning.encrypted_content"] 时(Codex 默认如此)放进 encrypted_content,下一轮都原样回传上游;Chat Completions 没有对应通道,GPT 推理不回传。
• Claude Opus 5.5 的 thinking 关不掉,冷请求比 opus-5 贵:上游只收 adaptive(显式 disabled 回 400),网关把 thinking:{type:"disabled"} / reasoning_effort:"none" 按 adaptive 发,effort 取客户端值或模型默认 medium,想少思考就降 effort。Kiro 标 2.0x,但缓存未命中的输入另按约 1.94 倍计价(2026-09-27 实测):冷启动 / 缓存失效的请求比 opus-5 贵约 77%,命中与输出比 opus-5 便宜约 9%;kiro_derived 已按实测费率反演。Fable 系列上游尚不成熟,暂不支持。
• 旧模型不做 thinking 控制:opus-4.6 及以下、sonnet-4.5、haiku 没有原生 reasoning,网关不注入提示词也不发字段,thinking / -thinking 后缀对它们无效,走上游默认。
• 无签名的历史 thinking 不回传:thinking 块要带上游给的 signature 才走原生 reasoningContent;无签名的(旧模型文本解码、不带 encrypted_content 的 reasoning summary)丢弃,不拼成文本;签名失效时网关剥掉全部历史推理重发一次。
• 多张图片只能靠位置归属:Kiro wire 只有消息级 images[],tool_result 里放图上游静默丢弃、正文是纯字符串,所以「这张图属于哪个工具调用」在 wire 上表达不了。网关做了三件事:tool_result 按 tool_use 顺序规范化、tool_result 内占位符带序号、消息里 ≥2 张 tool_result 图时在正文前置一行 [Attached images, in order: image k = …] 图例。2026-09-09 真实上游实测:6 个并行 Read 各回一张图,无图例时两个模型 4/4 错位,有图例 4/4 全对;Docker 里真实 Claude Code / Codex 读 4–6 张不同数字图能正确对应文件。仍不可控的是模型自己的判断:GPT-5.6 对两张字节相同的图稳定答「1 张」(token 计数证明两张都送到了),以及对低分辨率点阵数字偶发误读一位。真实复跑:packages/core/test/manual/multi-image-attribution-probe.mjs(API)与 multi-image-cli-probe.mjs(Docker 真 CLI,计费)。
• 超长工具描述会被截断:单个工具的 description 超过 KIRO2CLAUDE_TOOL_DESCRIPTION_MAX_LEN(默认 32768 字符)时截掉尾部并打 warn,防止单个畸形描述吃掉上下文窗口;已知最大的合法工具(Workflow)远低于此,需要时调大。工具名超过 63 字符(上游硬限制)会改写成「前缀 + 哈希」发给模型,回给客户端时还原。
• tool_result 的 is_error 不会到达模型:网关同 kiro-cli 发 status:"error",但上游不把它当失败信号交给模型(对照实验:正文保持中性、只改 status / isError,luna 与 opus-5 全部答成功),成败只能从正文判断。Claude Code 的报错结果正文自带 <tool_use_error> / Exit code 等信息,不受影响;只靠 is_error 标记、正文中性的客户端会被当成成功。
• 错误前已输出的文字留在客户端历史:上游中途报错时,之前已流出的正文客户端已经收到并保存;保留原文不等于它经过验证。
• Claude Code 2.1.263 的 Unicode 转义改写(客户端侧):工具参数里字面的 \u0000 / \u000a JSON 转义序列会被 CLI 还原成真实 NUL / LF,导致 Bash 参数校验失败、Write 写坏源码。绕过网关直连 Anthropic 同样复现,整块 / 7 字符 / 逐字符 / \u005c 等价编码四种分片方式无一幸免。网关不做双重转义、不改写工具命令。零上游复现:packages/core/test/manual/claude-unicode-input-probe.mjs。

已修复且有守卫的那些(帧边界 EOF 当成功、截断 tool_use 到达客户端、坏帧后拼接正文、孤儿 tool_result、空流当正常完成等)见 CLAUDE.md 踩坑「流式传输」组;真实 CLI 复跑入口在 packages/core/test/manual/。

MIT,Copyright (c) 2026 yupanzi。