1. 项目概述与核心价值如果你和我一样日常开发中重度依赖像 Claude Code 这样的 AI 编程助手但同时又因为公司或项目使用了 Kiro 这类基于 AWS SSO 的内部身份认证平台而头疼那么kirolink这个工具的出现绝对能让你眼前一亮。简单来说它是一个用 Go 语言编写的轻量级命令行工具核心功能是充当一个“翻译官”和“桥梁”。它能自动读取你本地缓存的 Kiro 认证令牌然后在本机启动一个符合 Anthropic API 规范的代理服务器。这样一来所有原本需要直接调用 Anthropic 官方 API 的工具比如 Claude Code现在都可以无缝地、零配置地通过这个本地代理去调用你公司内部的 AWS CodeWhisperer 服务。这解决了什么痛点想象一下你每次打开 IDE 想用 Claude Code都得手动去 AWS 控制台复制临时令牌再设置一堆环境变量不仅繁琐而且令牌过期后还得重复操作严重打断了开发的心流。kirolink的价值就在于自动化这个流程一次登录 Kiro工具帮你搞定令牌的读取、刷新和 API 格式的转换让你能像使用原版 Claude 一样流畅地使用内部的 CodeWhisperer 能力。它尤其适合那些在受控网络环境或使用私有化 AI 模型的企业开发者将复杂的认证和协议转换问题简化为一个./kirolink server命令。2. 核心工作原理与架构拆解要理解kirolink为什么能工作我们需要拆解其背后的几个关键组件和它们之间的协作流程。这不仅仅是“一个脚本启动了服务器”而是一套精巧的、针对特定工作流的自动化方案。2.1 身份认证链从 Kiro 到本地令牌整个流程的起点是 Kiro 的 AWS SSO 认证。Kiro 本质上是一个身份代理当你执行kiro login时它会与公司的身份提供商如 Okta, Azure AD交互完成 OAuth 2.0 或 SAML 流程最终从 AWS SSO 服务获取一组短期有效的访问凭证。这些凭证通常包含一个accessToken用于 API 调用和一个refreshToken用于在accessToken过期后获取新的令牌。kirolink的聪明之处在于它没有尝试重新实现复杂的登录流程而是直接“寄生”在标准的 AWS SSO 缓存机制上。AWS CLI 和 SDK 会将获取到的令牌以 JSON 格式缓存在用户主目录的一个固定路径下~/.aws/sso/cache/。Kiro 兼容这一机制因此也会将令牌写入类似kiro-auth-token.json的文件中。kirolink的read和refresh命令其核心操作就是读写这个文件。这种设计保证了工具的无状态性和安全性——它不存储你的长期密码只操作已经存在的、短期有效的令牌文件。2.2 协议转换层Anthropic API 与 CodeWhisperer API 的“翻译”这是kirolink最核心的技术部分。Anthropic 的 Messages API (/v1/messages) 和 AWS CodeWhisperer 的 API (/generateAssistantResponse) 在请求格式、响应结构以及流式传输Server-Sent Events, SSE的实现上完全不同。请求转换当代理服务器收到一个标准的 Anthropic 格式的 POST 请求时包含model,messages,max_tokens等字段kirolink需要将其“翻译”成 CodeWhisperer 后端能理解的格式。这包括模型映射将 Anthropic 的模型别名如claude-sonnet-4-5映射或忽略因为后端服务可能只认一种内部模型。消息重组将messages数组可能包含system,user,assistant角色转换为 CodeWhisperer 预期的对话历史结构。参数适配将max_tokens转换为maxTokensToSample并处理temperature,top_p等参数的映射关系。响应转换收到 CodeWhisperer 的响应后kirolink再将其包装回 Anthropic API 的标准格式。对于流式响应它需要实时地将后端的数据块转换为 SSE 格式data: {...}这对于实现 Claude Code 中的“打字机”效果至关重要。错误处理它还需要处理并转换两套 API 不同的错误码和消息格式确保客户端如 Claude Code能收到可读的错误提示。2.3 本地代理服务器轻量且专注kirolink使用 Go 的标准库net/http启动一个本地 HTTP 服务器。它的路由设计非常精简只暴露了三个端点完美模拟了 Anthropic API 的最小可用子集POST /v1/messages: 核心的聊天补全端点。GET /v1/models: 返回一个预定义的模型别名列表让客户端认为它在与一个支持多模型的 Anthropic 服务对话。GET /health: 用于健康检查简化了运维和监控。这种极简设计降低了维护成本也减少了攻击面。服务器默认运行在8080端口避免了与常用服务端口的冲突。3. 从零开始的完整部署与配置指南了解了原理我们来一步步实现它。以下操作基于 macOS/Linux 环境Windows 用户只需在命令提示符或 PowerShell 上做对应调整。3.1 环境准备与源码获取首先确保你的系统已经安装了 Go 1.23.3 或更高版本。你可以通过go version来验证。# 克隆项目仓库 git clone https://github.com/alexandephilia/kiro-claude-proxy.git cd kiro-claude-proxy # 检查项目结构 ls -la你应该能看到kirolink.go这个主文件以及可能的go.mod、README.md等。注意由于项目依赖可能变化建议在构建前先运行go mod tidy来同步和清理依赖项确保所有必要的库都已就位。3.2 构建可执行文件Go 的编译过程非常简单直接。在项目根目录下执行go build -o kirolink kirolink.go这条命令会编译kirolink.go及其所有依赖并生成一个名为kirolink的独立可执行文件。这个文件包含了完整的运行时可以随意复制到任何同架构的机器上运行无需额外安装 Go 环境。3.3 前置条件获取 Kiro 认证令牌这是最关键的一步。kirolink本身不负责登录它依赖于已存在的令牌文件。登录 Kiro使用你公司提供的 Kiro CLI 工具完成登录。命令通常类似于kiro login --profile your-profile-name按照提示完成浏览器认证流程。验证令牌文件登录成功后检查令牌文件是否已生成ls -la ~/.aws/sso/cache/ | grep kiro你应该能看到一个类似kiro-auth-token.json的文件。使用kirolink read进行验证运行以下命令确认kirolink能正确读取令牌./kirolink read如果成功你会看到 JSON 格式的输出其中包含accessToken和refreshToken等字段。请务必谨慎处理此命令的输出避免将令牌内容泄露到日志或截图中。3.4 配置客户端环境变量为了让 Claude Code 或其他客户端找到我们的代理需要设置环境变量。kirolink提供了export命令来自动生成设置命令。在 macOS/Linux (bash/zsh) 上最方便的方法是使用命令替换command substitution直接执行输出eval $(./kirolink export)这条命令会执行./kirolink export其输出是类似export ANTHROPIC_BASE_URL...的 shell 命令然后由eval在当前 shell 会话中执行它们。在 Windows 上直接运行./kirolink export它会贴心地同时输出 CMD 和 PowerShell 两种格式的命令你只需复制对应版本的命令行并执行即可。执行后可以通过echo $ANTHROPIC_BASE_URL(Linux/macOS) 或echo %ANTHROPIC_BASE_URL%(Windows CMD) 来验证变量是否已设置。默认情况下ANTHROPIC_BASE_URL会被设置为http://localhost:8080而ANTHROPIC_API_KEY会被设置为当前有效的accessToken。3.5 启动代理服务器并验证现在可以启动代理服务了。启动服务器使用默认端口8080./kirolink server如果 8080 端口被占用可以指定另一个端口例如 9000./kirolink server 9000重要如果使用了自定义端口你必须手动更新ANTHROPIC_BASE_URL环境变量例如export ANTHROPIC_BASE_URLhttp://localhost:9000因为export命令的输出是固定的。验证服务器运行服务器启动后会监听指定端口。你可以通过健康检查端点快速验证curl http://localhost:8080/health如果返回OK说明服务器已就绪。验证模型列表端点测试 Anthropic 兼容的/v1/models端点curl http://localhost:8080/v1/models你应该能收到一个 JSON 响应其中列出了kirolink支持的所有模型别名。3.6 集成 Claude Code 客户端这是最后一步也是收获成果的一步。确保 Claude Code 已安装在你的 IDE如 VS Code中安装 Claude Code 扩展。可选运行配置助手kirolink提供了一个claude子命令可以自动修改 Claude Code 的本地配置文件通常位于~/.claude.json将其标记为已完成初始设置并添加一个kirolinktrue的标志。./kirolink claude注意此命令会直接修改你的配置文件。建议首次运行时使用或者提前备份你的~/.claude.json文件。重启 IDE 或 Reload Window为了让 Claude Code 扩展重新读取环境变量和配置最好重启你的 IDE 或者执行“Reload Window”命令。开始使用现在当你打开一个代码文件使用 Claude Code 的快捷命令如CmdI时它发出的请求将会被发送到你本地运行的kirolink代理进而转发到公司的 CodeWhisperer 服务。你应该能看到和直接使用 Anthropic API 几乎无延迟的代码补全和建议。4. 高级用法与集成场景kirolink的价值不仅在于服务 Claude Code。任何能够配置 HTTP 客户端和 API 密钥的工具理论上都可以通过它来接入内部的 CodeWhisperer。4.1 与 OpenClaw 开源框架集成OpenClaw 是一个支持多后端、可扩展的开源 AI 助手框架。你可以将kirolink配置为 OpenClaw 的一个自定义 Anthropic 提供商。在你的 OpenClaw 配置文件例如openclaw.json中添加如下配置节{ providers: { kiro-claude: { api: anthropic-messages, baseURL: http://localhost:8080, apiKey: your-kiro-access-token-here, defaultModel: claude-sonnet-4-5, timeout: 120 } }, defaultProvider: kiro-claude }配置说明api: 必须指定为anthropic-messages以匹配kirolink实现的协议。baseURL: 指向你本地运行的kirolink服务器地址和端口。apiKey: 这里可以填写从./kirolink read获取的accessToken。更佳实践是让 OpenClaw 从ANTHROPIC_API_KEY环境变量中读取这需要参考 OpenClaw 的文档进行配置。defaultModel: 指定默认使用的模型别名需在kirolink支持的列表内。timeout: 根据网络情况适当调整超时时间。这样配置后你就可以在 OpenClaw 中使用kiro-claude这个提供商来调用内部的 AI 能力。4.2 处理令牌刷新与长期运行AWS SSO 的accessToken有效期通常很短例如1小时。kirolink的refresh命令就是用来解决这个问题的。手动刷新当令牌过期客户端请求开始返回 401 错误时你可以手动执行./kirolink refresh这个命令会使用缓存文件中的refreshToken向认证服务器申请一个新的accessToken并更新本地的缓存文件。之后你需要重启kirolink server或者设计一个更复杂的机制让服务器重载令牌。自动化刷新思路对于需要 7x24 小时运行的场景可以结合cronLinux/macOS或 Task SchedulerWindows创建一个定时任务。例如每 50 分钟运行一次refresh命令。然而更健壮的方式是修改kirolink的服务器代码使其在每次请求前检查令牌的有效期或在收到 401 响应时自动触发刷新流程。这属于进阶改造范畴。4.3 直接调用代理 API 进行测试除了通过 GUI 客户端你也可以直接用curl或任何 HTTP 客户端测试代理功能这对于调试和编写脚本非常有用。# 发送一个简单的非流式请求 curl -X POST http://localhost:8080/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $(cat ~/.aws/sso/cache/kiro-auth-token.json | jq -r .accessToken) \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 用Python写一个快速排序函数}], max_tokens: 500 } # 发送一个流式请求 (Server-Sent Events) curl -X POST http://localhost:8080/v1/messages \ -H Content-Type: application/json \ -H Accept: text/event-stream \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 解释一下什么是RESTful API}], max_tokens: 300, stream: true }在流式请求中你会看到以data:开头的行源源不断地输出直到遇到[DONE]事件。5. 故障排查与常见问题实录在实际使用中你可能会遇到一些问题。下面是我在部署和使用过程中遇到的一些典型情况及其解决方法。5.1 令牌相关问题问题现象可能原因解决方案运行./kirolink read时报错file not found1. 未执行kiro login。2. 令牌文件路径非默认。3. Kiro 的缓存文件名不匹配。1. 确保先使用kiro login完成认证。2. 检查~/.aws/sso/cache/目录下是否存在名称包含kiro和token的 JSON 文件。3. 可以尝试grep -l accessToken ~/.aws/sso/cache/*.json查找正确的文件。服务器启动正常但 Claude Code 返回认证错误1. 令牌已过期。2.ANTHROPIC_API_KEY环境变量设置错误或未生效。1. 运行./kirolink refresh刷新令牌并重启kirolink server。2. 在终端中执行echo $ANTHROPIC_API_KEY确认值正确并确保 Claude Code 是在设置了该环境变量的终端中启动的 IDE。对于 macOS 的 App可能需要通过.zprofile或.bash_profile全局设置。./kirolink refresh失败1.refreshToken本身已过期通常有效期更长但可能失效。2. 网络问题或认证服务不可用。1. 这是最麻烦的情况需要重新进行完整的kiro login流程。2. 检查网络连接并确认公司的 SSO 服务状态正常。5.2 网络与服务器问题问题现象可能原因解决方案无法启动服务器提示port already in use默认的 8080 端口被其他进程占用。使用./kirolink server 9000指定另一个空闲端口并相应更新ANTHROPIC_BASE_URL。Claude Code 连接超时或无响应1.kirolink server未运行。2. 防火墙阻止了本地回环地址localhost的端口访问。3. Claude Code 未使用配置的环境变量。1. 在终端确认kirolink server进程正在运行。2. 尝试用curl http://localhost:8080/health从命令行测试如果失败检查系统防火墙设置。3. 彻底关闭 IDE 并重新启动确保环境变量被加载。请求速度慢或响应时间长1. 公司内部 CodeWhisperer 服务端延迟高。2. 本地代理增加了微小开销。3. 网络波动。1. 此问题非kirolink所能解决属于后端服务问题。2. Go 编写的代理开销极低通常可忽略。可通过对比直接调用如果可能和通过代理调用的耗时来定位。5.3 功能与兼容性问题问题现象可能原因解决方案Claude Code 的某些高级功能如“解释代码”不工作kirolink可能只实现了 Anthropic Messages API 的一个子集未完全覆盖 Claude Code 使用的所有参数或端点。检查kirolink项目的 Issue 或源码看是否支持该功能。可以尝试在 Claude Code 设置中禁用某些高级特性或使用更基础的聊天补全功能。流式输出打字机效果不生效1. 请求未设置stream: true。2. 客户端或代理的 SSE 实现有兼容性问题。1. 确保客户端请求正确。2. 使用上文中的curl流式请求示例进行测试如果curl可以收到流式数据则问题在客户端。/v1/models返回的列表与后端实际能力不符kirolink的模型别名列表是硬编码的用于兼容客户端并不代表后端真实支持这么多模型。这是预期行为。选择一个列表中存在的别名使用即可kirolink在转发时可能会将其映射为后端唯一的模型标识符。5.4 实操心得与避坑指南环境变量作用域陷阱在 macOS 上如果你从启动台Launchpad打开 VS Code它不会继承你在终端Terminal里设置的环境变量。最可靠的方法是在~/.zshrc或~/.bash_profile中永久设置ANTHROPIC_*变量或者总是从终端命令行用code .命令启动 VS Code。令牌文件权限确保~/.aws/sso/cache/kiro-auth-token.json的权限是安全的如600防止其他用户读取你的令牌。长期运行与监控对于生产环境或重要工作流考虑将kirolink server包装为一个系统服务如使用systemd或launchd并配置日志轮转和失败重启机制。理解“代理”的局限性kirolink是一个协议转换代理它的功能受限于两方面一是它实现的 Anthropic API 子集的完整度二是后端 CodeWhisperer 服务本身的能力。如果后端不支持某些特性如特定的工具调用kirolink也无法无中生有。参与开源改进如果你发现 bug 或有功能需求可以考虑在项目的 GitHub 仓库提交 Issue 或 Pull Request。例如实现自动令牌刷新、支持更多 Anthropic API 参数、提供 Docker 镜像等都是很有价值的贡献方向。这个工具的精妙之处在于它用很小的代价解决了一个具体的、高频的痛点。它不试图做大而全的网关而是精准地扮演了“适配器”的角色。通过深入理解其工作原理并妥善处理上述常见问题你可以将它无缝地集成到自己的开发工作流中显著提升在内部 AI 基础设施下的开发体验。