当前位置： 首页 > news >正文

kirolink：基于Go的AWS SSO令牌代理，无缝桥接Claude Code与内部CodeWhisperer

news 2026/5/7 18:26:12

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 的最小可用子集：

  1. POST /v1/messages: 核心的聊天补全端点。
  2. GET /v1/models: 返回一个预定义的模型别名列表，让客户端认为它在与一个支持多模型的 Anthropic 服务对话。
  3. 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本身不负责登录，它依赖于已存在的令牌文件。

  1. 登录 Kiro：使用你公司提供的 Kiro CLI 工具完成登录。命令通常类似于：
    kiro login --profile your-profile-name
    按照提示完成浏览器认证流程。
  2. 验证令牌文件：登录成功后，检查令牌文件是否已生成：
    ls -la ~/.aws/sso/cache/ | grep kiro
    你应该能看到一个类似kiro-auth-token.json的文件。
  3. 使用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 启动代理服务器并验证

现在可以启动代理服务了。

  1. 启动服务器：使用默认端口（8080）：
    ./kirolink server
    如果 8080 端口被占用，可以指定另一个端口，例如 9000：
    ./kirolink server 9000
    重要：如果使用了自定义端口，你必须手动更新ANTHROPIC_BASE_URL环境变量，例如export ANTHROPIC_BASE_URL=http://localhost:9000，因为export命令的输出是固定的。
  2. 验证服务器运行：服务器启动后，会监听指定端口。你可以通过健康检查端点快速验证：
    curl http://localhost:8080/health
    如果返回OK，说明服务器已就绪。
  3. 验证模型列表端点：测试 Anthropic 兼容的/v1/models端点：
    curl http://localhost:8080/v1/models
    你应该能收到一个 JSON 响应，其中列出了kirolink支持的所有模型别名。

3.6 集成 Claude Code 客户端

这是最后一步，也是收获成果的一步。

  1. 确保 Claude Code 已安装：在你的 IDE（如 VS Code）中安装 Claude Code 扩展。
  2. （可选）运行配置助手：kirolink提供了一个claude子命令，可以自动修改 Claude Code 的本地配置文件（通常位于~/.claude.json），将其标记为已完成初始设置，并添加一个kirolink=true的标志。
    ./kirolink claude

    注意：此命令会直接修改你的配置文件。建议首次运行时使用，或者提前备份你的~/.claude.json文件。

  3. 重启 IDE 或 Reload Window：为了让 Claude Code 扩展重新读取环境变量和配置，最好重启你的 IDE 或者执行“Reload Window”命令。
  4. 开始使用：现在，当你打开一个代码文件，使用 Claude Code 的快捷命令（如Cmd+I）时，它发出的请求将会被发送到你本地运行的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 小时运行的场景，可以结合cron（Linux/macOS）或 Task Scheduler（Windows）创建一个定时任务。例如，每 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 实操心得与避坑指南

  1. 环境变量作用域陷阱：在 macOS 上，如果你从启动台（Launchpad）打开 VS Code，它不会继承你在终端（Terminal）里设置的环境变量。最可靠的方法是在~/.zshrc或~/.bash_profile中永久设置ANTHROPIC_*变量，或者总是从终端命令行用code .命令启动 VS Code。
  2. 令牌文件权限：确保~/.aws/sso/cache/kiro-auth-token.json的权限是安全的（如600），防止其他用户读取你的令牌。
  3. 长期运行与监控：对于生产环境或重要工作流，考虑将kirolink server包装为一个系统服务（如使用systemd或launchd），并配置日志轮转和失败重启机制。
  4. 理解“代理”的局限性：kirolink是一个协议转换代理，它的功能受限于两方面：一是它实现的 Anthropic API 子集的完整度，二是后端 CodeWhisperer 服务本身的能力。如果后端不支持某些特性（如特定的工具调用），kirolink也无法无中生有。
  5. 参与开源改进：如果你发现 bug 或有功能需求，可以考虑在项目的 GitHub 仓库提交 Issue 或 Pull Request。例如，实现自动令牌刷新、支持更多 Anthropic API 参数、提供 Docker 镜像等，都是很有价值的贡献方向。

这个工具的精妙之处在于它用很小的代价解决了一个具体的、高频的痛点。它不试图做大而全的网关，而是精准地扮演了“适配器”的角色。通过深入理解其工作原理并妥善处理上述常见问题，你可以将它无缝地集成到自己的开发工作流中，显著提升在内部 AI 基础设施下的开发体验。

http://www.jsqmd.com/news/771719/

相关文章：

  • ContentClaw：基于AI与事实核查的自动化内容生成引擎实践
  • WordPress多语言建站实战操作 WordPress建站多少钱 - 麦麦唛
  • FanControl风扇控制软件：3步完成Windows系统散热优化配置
  • ShawzinBot：在Warframe中实现MIDI音乐自动化演奏的终极指南
  • N_m3u8DL-RE：如何用5分钟掌握跨平台流媒体下载核心技术？
  • 从被动到主动：国内制造业10大质量管理软件厂商盘点 - 资讯焦点
  • 别再死记硬背了！用Java代码和动画图解，5分钟搞懂基数排序的LSD和MSD
  • TIDAL音乐下载完整指南：tidal-dl-ng高效工具终极方案
  • 实测4家武汉财税公司：谁更懂你的企业？ - 小征每日分享
  • 2026年5月天津宠物/手术/生病/医院选择指南：手术专科实力成关键考量因素 - 2026年企业推荐榜
  • 滑动窗口算法在不同场景下的解题模板
  • 5步解决MeteoInfo中GRIB转ARL格式转换问题的完整指南
  • 基于OpenAssistantGPT SDK快速构建智能对话机器人：架构、工具与实战
  • 5分钟告别重复劳动：用KeymouseGo让电脑自动完成枯燥工作
  • 别再被销售坑了！手把手教你用Java搞定华夏T83相机的LED屏与语音播报（附完整Demo）
  • 如何从GoPro视频中提取GPS轨迹数据：gopro2gpx完整指南
  • 成都本地 GEO 优化公司推荐：AI 搜索时代的本地化流量解决方案指南 - 品牌评测官
  • AISMM成熟度评估实战复盘（SITS2026最新版深度解码）：为什么83%的组织卡在L3→L4跃迁？
  • 路径规划算法实战指南：从原理到代码实现的完整解析
  • 3步掌握AI绘画模型训练：kohya_ss图形化界面终极指南
  • Playnite游戏库管理器：3步打造你的终极游戏中心
  • Go语言构建轻量级反向代理Kraken：从核心原理到生产部署
  • AISMM模型实施倒计时预警：政策合规收紧+AI审计常态化下，未完成成熟度L3认证的企业将面临3项运营风控升级
  • OpenCV.js深度解析：浏览器端计算机视觉架构揭秘与实践指南
  • 2026最新深圳跨境电商合规服务商排行：5家机构客观盘点 - 奔跑123
  • Golembot：基于Go的插件化机器人框架设计与自动化实践
  • Taotoken在多模型聚合场景下如何保障API调用的稳定性与低延迟
  • 从开发者视角看Taotoken计费透明与账单追溯的便利性
  • 如何在5分钟内用ChanlunX实现通达信缠论自动化分析：新手终极指南
  • 如何轻松实现跨平台弹幕转换？DanmakuFactory让弹幕文件格式兼容不再是难题