1. 项目概述与核心价值如果你和我一样日常开发中重度依赖像 Claude Code 这样的 AI 编程助手但又对某些平台的访问限制或复杂的认证流程感到头疼那么kirolink这个工具的出现可能会让你眼前一亮。简单来说它是一个用 Go 语言编写的轻量级命令行工具核心功能是充当一个“翻译官”和“桥梁”。它能自动读取你本地 Kiro 认证系统缓存的令牌然后启动一个本地的 HTTP 代理服务器。这个服务器的神奇之处在于它对外暴露的 API 接口完全模仿了 AnthropicClaude 的母公司官方的 API 格式。这意味着任何原本设计用来与 Claude API 对话的工具——无论是 Claude Code 编辑器插件、OpenClaw 这样的开源 AI 助手框架还是你自己写的脚本——都可以无缝地、零配置地通过这个本地代理将请求转发到 AWS CodeWhisperer 服务并获取响应。这解决了什么痛点最直接的就是认证简化。你不再需要手动管理复杂的 API Key或者为不同的工具配置不同的认证方式。kirolink利用了现有的 AWS SSO 缓存机制实现了认证的自动化。其次它统一了接口。无论后端实际调用的是哪个服务这里是 CodeWhisperer对前端应用来说它始终是在与一个“标准的 Claude API”对话极大地降低了集成复杂度。对于开发者而言这相当于获得了一个稳定、本地化、且兼容性极强的 AI 能力接入点无论是用于代码补全、对话分析还是构建更复杂的 AI 应用原型都提供了极大的便利。2. 核心原理与架构拆解要理解kirolink如何工作我们需要拆解它的数据流和核心组件。整个流程可以看作一个精心设计的协议转换管道。2.1 认证令牌的获取与管理这是整个工具的起点也是其“无感”体验的关键。kirolink并没有实现一套独立的登录逻辑而是巧妙地“借用”了已有的认证状态。令牌来源工具期望在~/.aws/sso/cache/目录下找到一个名为kiro-auth-token.json的文件。这个文件通常在你通过 AWS CLI 或 SDK 使用 Kiro或其他基于 AWS SSO 的服务成功登录后自动生成并缓存。文件内容包含了访问令牌accessToken和刷新令牌refreshToken这些都是标准的 OAuth 2.0 令牌。读取机制kirolink read命令的核心就是读取并解析这个 JSON 文件将内部的令牌信息提取出来用于后续的 API 调用。这种方式避免了在工具内重复输入密码或进行繁琐的 OAuth 授权流程。刷新机制访问令牌通常有较短的有效期例如一小时。kirolink refresh命令的作用是当当前访问令牌过期时利用文件中存储的刷新令牌向认证服务器申请一个新的访问令牌并更新本地的缓存文件。这个过程对用户是透明的确保了代理服务的长期可用性。注意这种设计意味着kirolink严重依赖于上游的登录流程。你必须先通过aws sso login或其他兼容 Kiro 的 CLI 工具完成登录生成这个缓存文件kirolink才能正常工作。这是使用前最重要的前置条件。2.2 协议转换从 Anthropic 到 AWS CodeWhisperer这是kirolink最核心的技术价值。它需要理解两种不同的 API 规范并在它们之间进行实时翻译。入站请求Anthropic 格式当 Claude Code 发送一个请求时其格式遵循 Anthropic Messages API。例如一个典型的请求体包含model模型名称如claude-3-5-sonnet-20241022、messages对话历史数组、max_tokens生成令牌数等字段。内部转换kirolink的服务器接收到这个请求后会进行一系列操作令牌注入从本地缓存中读取当前的accessToken将其作为Authorization: Bearer token头部添加到即将发送给 CodeWhisperer 的请求中。请求体映射将 Anthropic 格式的请求字段映射到 CodeWhisperer API 所期望的格式。这包括消息角色的转换如user-humanassistant-assistant、内容格式的调整以及可能忽略一些 CodeWhisperer 不支持的参数。端点路由转换后的请求会被发送到硬编码的 CodeWhisperer 服务端点https://codewhisperer.us-east-1.amazonaws.com/generateAssistantResponse。出站响应转换回 Anthropic 格式收到 CodeWhisperer 的响应后kirolink再执行反向转换将响应结构包装成 Anthropic API 客户端期望的格式包括正确的 JSON 结构、流式输出Server-Sent Events, SSE的支持等然后返回给最初的调用者。2.3 模型别名Alias系统你可能会注意到在请求中指定的模型如claude-sonnet-4-6可能并不是 CodeWhisperer 后端实际使用的模型标识符。kirolink实现了一个模型别名系统。它维护了一个内部映射表将常见的、用户友好的 Claude 模型名称别名映射到后端实际可用的模型。当收到请求时代理会查找这个映射表使用对应的真实模型标识符去调用下游服务。通过GET /v1/models接口可以查询当前代理支持的所有别名这为客户端提供了灵活性。3. 详细部署与实操指南理论清晰后我们来一步步完成从零到一的部署和使用。这个过程大致分为环境准备、构建工具、配置认证和启动服务四个阶段。3.1 环境准备与依赖检查在开始之前请确保你的系统满足以下基本要求Go 语言环境kirolink是 Go 项目需要 Go 1.23.3 或更高版本。你可以通过go version命令检查。如果未安装请从 golang.org 下载并安装。Git用于克隆项目仓库。通常系统已自带或可通过包管理器安装。AWS CLI v2 与 Kiro 登录这是获取认证令牌的前提。你需要安装并配置 AWS CLI v2并确保已经完成了针对 Kiro 的 SSO 登录。通常的命令流程是# 配置 AWS CLI 使用 SSO (假设你的 SSO 配置名为 kiro-sso) aws configure sso # 随后按照提示输入 SSO 启动 URL、区域等信息。 # 完成配置后执行登录 aws sso login --profile kiro-sso # 浏览器会打开完成认证流程。成功登录后令牌文件~/.aws/sso/cache/kiro-auth-token.json应该会自动生成。你可以用cat ~/.aws/sso/cache/*.json | grep -i accessToken粗略检查一下是否有包含相关字段的文件。3.2 获取与构建 kirolink项目源码托管在 GitHub。我们通过 Git 获取并手动构建这能确保我们使用的是最新代码也便于后续可能的自定义修改。# 1. 克隆仓库到本地 git clone https://github.com/alexandephilia/kiro-claude-proxy.git cd kiro-claude-proxy # 2. 构建可执行文件 # 这会将 kirolink.go 及其依赖编译成一个名为 kirolink 的二进制文件 go build -o kirolink kirolink.go # 3. (可选) 将可执行文件移动到系统 PATH 包含的目录方便全局调用 # 例如在 macOS/Linux 下 sudo mv kirolink /usr/local/bin/ # 在 Windows 下可以将其放入 C:\Windows\System32\ 或任何在 PATH 中的目录。 # 如果不移动后续所有命令都需要使用 ./kirolink 的相对路径或绝对路径。构建完成后可以运行./kirolink或kirolink如果已加入 PATH查看帮助信息确认构建成功。3.3 认证状态验证与环境变量配置在启动代理服务器之前我们必须确保认证令牌可用并为客户端工具配置好连接信息。验证令牌使用read命令检查工具是否能正确读取到令牌。这是一个重要的诊断步骤。./kirolink read如果成功你会看到 JSON 格式的输出其中包含accessToken和refreshToken等字段。如果失败通常会提示文件未找到这时你需要返回上一步确认 AWS SSO 登录是否成功。配置环境变量为了让 Claude Code 等客户端知道去哪里找我们的代理服务器需要设置两个关键环境变量ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL。kirolink的export命令为我们生成了设置这些变量的脚本。在 macOS 或 Linux 的 Bash/Zsh 终端中最方便的方法是使用eval直接执行命令的输出eval $(./kirolink export)这条命令会执行./kirolink export其输出类似于export ANTHROPIC_BASE_URL...和export ANTHROPIC_API_KEY...然后eval会立即在当前 shell 会话中执行这些导出命令。在 Windows 上export命令会同时输出 CMD 和 PowerShell 的语法你需要根据自己使用的终端手动复制并执行对应的命令块。环境变量详解ANTHROPIC_API_KEY这里被设置成了你当前的accessToken。对于客户端来说它以为自己在向真正的 Anthropic API 发送请求并使用这个“API Key”进行认证。实际上这个令牌会被kirolink用于向 CodeWhisperer 认证。ANTHROPIC_BASE_URL被设置为http://localhost:8080。这告诉客户端所有 API 请求都应该发送到你本机的 8080 端口也就是即将启动的kirolink代理服务器。重要提示export命令设置的ANTHROPIC_BASE_URL是固定的http://localhost:8080。如果你计划使用非 8080 的其他端口运行服务器你需要手动修改这个环境变量例如export ANTHROPIC_BASE_URLhttp://localhost:9000。3.4 启动代理服务器与基础测试一切就绪后就可以启动代理服务了。启动服务器在终端中运行以下命令。建议在一个独立的、持久的终端窗口或标签页中运行以便观察日志。# 使用默认端口 8080 ./kirolink server # 或者使用自定义端口例如 9000 ./kirolink server 9000如果启动成功你会看到类似Server listening on http://localhost:8080的日志输出。基础健康检查打开另一个终端窗口使用curl测试服务器是否正常运行。curl http://localhost:8080/health预期返回一个简单的OK。这证明 HTTP 服务本身是活的。查询支持的模型测试核心的/v1/models端点查看代理对外宣称支持哪些模型别名。curl http://localhost:8080/v1/models这会返回一个 JSON 数组列出所有可用的模型别名如[default, claude-sonnet-4-6, ...]。发送一个测试请求模拟客户端发送一个完整的对话请求。curl -X POST http://localhost:8080/v1/messages \ -H Content-Type: application/json \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-6, messages: [{role: user, content: Hello, world!}], max_tokens: 100 }如果一切配置正确你应该能收到一个结构完整的 JSON 响应其中包含content字段里面是 AI 生成的回复。这标志着你的kirolink代理已经成功搭建并可以处理请求了。4. 高级集成与客户端配置让代理跑起来只是第一步接下来要让它真正为我们所用的工具服务。这里以 Claude Code 和 OpenClaw 两个典型场景为例。4.1 与 Claude Code 编辑器插件集成Claude Code 通常通过读取环境变量ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL来配置其后端。我们在上一步已经设置了这些变量。关键在于启动 Claude Code 的编辑器进程必须继承这些环境变量。最佳实践在设置了环境变量的同一个终端会话中直接启动你的代码编辑器如 VS Code。例如# 在已经执行了 eval $(./kirolink export) 的终端中 code .这样从该终端启动的 VS Code 进程会继承所有环境变量其内部的 Claude Code 插件就能自动发现并使用我们的本地代理。验证集成在 VS Code 中打开一个文件尝试触发 Claude Code 的代码补全或聊天功能。如果配置成功你应该能看到来自 AI 的响应同时在运行kirolink server的终端里会看到相应的请求和响应日志。使用claude命令可选kirolink提供了一个./kirolink claude命令。这个命令会直接修改 Claude Code 的本地配置文件通常是~/.claude.json将其中的hasCompletedOnboarding设置为true并添加一个kirolink: true的标记。这可以跳过一些初始设置步骤。使用前请注意这会修改你的配置文件建议先备份原文件。4.2 与 OpenClaw 开源框架集成OpenClaw 是一个支持多模型后端的 AI 助手框架配置灵活性更高。你需要在其配置文件中添加一个自定义的“提供商”。定位配置文件OpenClaw 的配置通常位于~/.config/openclaw/config.json或项目根目录的openclaw.json。请根据你的安装方式确定。编辑配置在配置文件的providers部分添加一个名为kiro-claude或其他你喜欢的名字的新提供商。{ version: 1, providers: { // ... 其他已有提供商 ... kiro-claude: { type: anthropic, // 告诉 OpenClaw 使用 Anthropic 的 API 格式 apiKey: YOUR_KIRO_ACCESS_TOKEN, // 这里可以填令牌或留空从环境变量读取 baseURL: http://localhost:8080/v1, // 注意这里的路径包含 /v1 models: [claude-sonnet-4-6, claude-opus-4-6] // 指定可用的模型别名 } }, defaultProvider: kiro-claude // (可选) 将其设为默认 }关于 apiKey你可以像上面一样硬编码但更安全的方式是留空或使用一个占位符然后通过环境变量ANTHROPIC_API_KEY来提供。OpenClaw 通常会自动读取这个环境变量。启动 OpenClaw配置完成后启动 OpenClaw。它现在会使用你配置的kiro-claude提供商将所有请求发送到本地的kirolink代理。4.3 处理流式响应 (Server-Sent Events)现代 LLM 应用为了更好的用户体验普遍支持流式响应即服务器一边生成一边将结果片段推送给客户端。Anthropic API 也支持此功能通过stream: true参数。kirolink的一个重要特性就是完整地支持了 SSE 的透传。客户端请求当你在请求体中加入stream: true时Claude Code 或你自己的客户端会期望一个 SSE 流。代理处理kirolink在收到这样的请求后会以流式模式调用下游的 CodeWhisperer API如果其支持并将收到的数据流实时地、按照 SSE 格式规范转发回客户端。测试流式请求你可以用curl测试流式输出但需要添加-N参数来禁用缓冲以便实时看到输出。curl -N -X POST http://localhost:8080/v1/messages \ -H Content-Type: application/json \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-6, messages: [{role: user, content: 用几句话介绍你自己。}], max_tokens: 200, stream: true }你会看到一系列以data:开头的行每行是一个 JSON 片段最后以data: [DONE]结束。这种机制使得在聊天界面中实现“逐字打印”的效果成为可能。5. 运维、问题排查与进阶技巧将工具用于生产环境或长期使用必然会遇到一些问题。下面是我在实际使用中总结的常见问题清单和运维建议。5.1 常见问题与解决方案速查表问题现象可能原因排查步骤与解决方案运行./kirolink read提示 “token file not found”1. 未执行 Kiro/AWS SSO 登录。2. 令牌文件路径不符。3. 令牌已过期且缓存被清理。1. 执行aws sso login --profile your-profile重新登录。2. 检查~/.aws/sso/cache/目录下是否存在名称类似的.json文件。kirolink默认查找kiro-auth-token.json有时文件名可能不同。3. 登录后重试。服务器启动失败提示端口被占用默认的 8080 端口已被其他程序使用。1. 使用lsof -i :8080(macOS/Linux) 或netstat -ano | findstr :8080(Windows) 查找占用进程并停止它。2. 更简单的方式使用./kirolink server 9090指定另一个空闲端口并记得更新ANTHROPIC_BASE_URL环境变量。Claude Code 无响应或报错 “Invalid API Key”1. 环境变量未正确设置。2.kirolink server未运行。3. 访问令牌已过期。1. 在终端中执行echo $ANTHROPIC_BASE_URL和echo $ANTHROPIC_API_KEY确认变量已设置且值正确。2. 确认运行kirolink server的终端进程仍在活动。3. 运行./kirolink refresh刷新令牌然后重启kirolink server因为服务器进程内缓存了旧的令牌。请求响应慢或超时1. 网络问题。2. 下游 CodeWhisperer 服务延迟。3. 本地代理处理瓶颈。1. 检查本地网络连接。2. 这是上游服务问题通常只能等待。3. 对于复杂请求Go 程序的转换开销极小基本可排除。可查看服务器日志是否有异常。流式响应不工作一次性返回全部内容客户端未正确设置stream: true参数或下游服务不支持该模型的流式输出。1. 确认请求 JSON 中包含了stream: true。2. 使用curl测试流式请求确认代理本身功能正常。3. 查阅 CodeWhisperer 文档确认你所用的模型别名是否支持流式。5.2 令牌管理与自动刷新策略令牌过期是最常见的中断原因。虽然可以手动执行./kirolink refresh但在长期运行的服务器场景下我们需要自动化方案。方案一Cron 定时任务在 Linux/macOS 上可以设置一个 cron 作业定期执行刷新命令。例如每 50 分钟刷新一次在 1 小时过期前。# 编辑当前用户的 cron 任务 crontab -e # 添加一行例如每小时的 10 分和 40 分各执行一次 */30 * * * * /path/to/your/kirolink refresh /tmp/kirolink-refresh.log 21注意刷新命令会更新磁盘上的令牌文件但已经运行的kirolink server进程需要重启才能加载新令牌。一个粗糙但有效的办法是同时重启服务kirolink refresh pkill -f “kirolink server” /path/to/kirolink server 。但这会中断现有连接。方案二包装脚本与信号处理更优雅的方式是编写一个包装脚本。该脚本启动kirolink server并同时启动一个后台循环定期检查令牌过期时间并在接近过期时执行刷新然后向服务器进程发送一个信号如 SIGHUP通知其重新读取令牌文件。这需要修改kirolink源码使其支持热重载配置。方案三使用系统服务管理器将kirolink配置为 systemd (Linux) 或 launchd (macOS) 服务并利用其内置的定时重启功能。例如配置 systemd 服务单元文件设置Restarton-failure和RuntimeMaxSec330055分钟让服务每55分钟自动重启一次配合一个启动前执行的脚本ExecStartPre来刷新令牌。5.3 性能监控与日志管理对于稳定使用建议对代理服务进行简单的监控。日志重定向默认情况下kirolink server将日志输出到标准错误stderr。你可以将其重定向到文件便于后续查看。./kirolink server 2 /var/log/kirolink.log 基础健康监控你可以编写一个简单的监控脚本定期调用/health端点如果返回非OK或超时则触发报警或自动重启。#!/bin/bash if ! curl -f -s http://localhost:8080/health /dev/null; then echo “kirolink health check failed at $(date)” /var/log/kirolink-monitor.log # 这里可以添加重启命令例如 pkill kirolink; /path/to/kirolink server fi网络与资源监控使用netstat或ss查看连接数使用top或htop查看进程的 CPU/内存占用。kirolink作为 Go 编写的轻量级代理资源消耗通常非常低。5.4 安全考量与最佳实践虽然这是一个本地代理但安全意识不可少。令牌文件权限确保~/.aws/sso/cache/kiro-auth-token.json文件权限设置合理仅限当前用户可读例如600。避免其他用户或恶意程序窃取你的访问令牌。chmod 600 ~/.aws/sso/cache/kiro-auth-token.json代理服务监听地址kirolink server默认监听在所有网络接口0.0.0.0:8080。如果你的机器处于共享网络或不可信网络这可能导致本地服务被他人访问。一个更安全的做法是只监听本地回环地址./kirolink server 127.0.0.1:8080但请注意这样配置后只有本机上的应用能访问代理。如果某些客户端如 Docker 容器内的应用需要连接则需使用0.0.0.0。环境变量管理避免在 shell 配置文件如.bashrc,.zshrc中永久设置ANTHROPIC_API_KEY因为它包含敏感令牌。更推荐在使用时通过脚本临时设置或使用类似direnv的工具在特定项目目录中加载。审计与更新关注项目 GitHub 仓库的更新及时获取安全修复和功能改进。考虑定期重新构建二进制文件。6. 扩展思路与自定义开发kirolink项目本身结构清晰为二次开发提供了良好基础。如果你有特定需求可以考虑以下方向支持更多后端服务当前硬编码了 AWS CodeWhisperer 端点。你可以修改源码使其能够根据配置或请求参数将请求路由到不同的 LLM 服务提供商如 OpenAI、Google Gemini 等实现一个统一的本地 AI 网关。增强的模型映射配置将模型别名与后端真实模型的映射关系从代码中抽离出来做成可配置文件如 YAML 或 JSON。这样无需重新编译就能动态添加或修改支持的模型。请求/响应中间件在协议转换的前后加入中间件机制。例如可以添加日志中间件记录所有请求和响应注意脱敏添加缓存中间件对相同提示词的请求返回缓存结果以节省成本添加限流中间件防止滥用。集成到其他开发工具链除了 Claude Code可以为其开发其他编辑器如 JetBrains IDE、Vim/Neovim 等的专用插件这些插件直接内置对kirolink代理的支持提供更流畅的体验。容器化部署创建 Docker 镜像将kirolink以及其依赖的令牌刷新机制打包。这可以简化在团队环境或云服务器上的部署并通过 Docker Secrets 或卷挂载来管理令牌文件。实现这些扩展需要对 Go 语言和 HTTP 服务开发有一定了解。你可以从 fork 原仓库开始研究kirolink.go中的主要结构体、函数以及请求处理流程特别是handleMessages函数这是进行任何修改的起点。