Kiro Gateway 配置指南

Kiro Gateway 配置指南

前置要求

  • Python 3.10+
  • uv（Python 包管理器）— 未安装请先执行： 
    pip install uv
# 或 macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
  • Kiro IDE 已登录（用于提供认证凭证）

第一步：安装依赖

# 克隆项目
git clone https://github.com/jwadow/kiro-gateway.git
cd kiro-gateway

# Pin Python 版本（确保环境一致性）
uv python pin 3.10

# 创建虚拟环境并安装依赖
uv venv
uv pip install -r requirements.txt

第二步：创建启动脚本

项目默认不包含启动脚本，手动创建 bin/start.sh：

mkdir -p bin

cat > bin/start.sh << 'EOF'
#!/usr/bin/env bash
# Start kiro-gateway using uv
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"

cd "$PROJECT_ROOT"
exec uv run python main.py "$@"
EOF

chmod +x bin/start.sh

验证脚本已创建：

ls -la bin/start.sh

第三步：配置 .env

复制模板文件：

cp .env.example .env

编辑 .env，完成以下配置：

必填：API Key

自己设定一个密码，用于保护 gateway 接口。客户端连接时需要填写这个值。

PROXY_API_KEY="your-secret-password"

必填：Kiro 认证（四选一）

方式 A：Kiro IDE 凭证文件（推荐）

Kiro IDE 登录后会在本地生成凭证文件，填写其路径：

KIRO_CREDS_FILE="~/.aws/sso/cache/kiro-auth-token.json"

方式 B：直接填写 refresh token

从 Kiro IDE 网络请求中抓取 refresh token：

REFRESH_TOKEN="your_kiro_refresh_token_here"

方式 C：kiro-cli SQLite 数据库

KIRO_CLI_DB_FILE="~/.local/share/kiro-cli/data.sqlite3"

方式 D：AWS SSO 缓存文件

KIRO_CREDS_FILE="~/.aws/sso/cache/your-sso-cache-file.json"

推荐：代理（国内网络必填）

VPN_PROXY_URL="http://127.0.0.1:1082"
# 或 SOCKS5
# VPN_PROXY_URL="socks5://127.0.0.1:1080"

推荐：开启多账号故障转移

ACCOUNT_SYSTEM=true

开启后首次启动时，gateway 会自动将 .env 中的认证配置迁移到 credentials.json，后续通过 credentials.json 管理账号。

推荐：关闭 gateway 内容干预行为

gateway 默认开启了几个会主动修改请求/响应内容的功能。如果你使用的 agent 系统（如 Claude Code、自建 agent）自己管理这些逻辑，建议全部关闭，让 gateway 做纯粹的协议转发：

WEB_SEARCH_ENABLED=false
FAKE_REASONING=false
TRUNCATION_RECOVERY=false

详细说明见 [附录 C：gateway 内容干预行为]()。

第四步：启动服务

# 默认端口 8000
./bin/start.sh

# 指定端口
# ./bin/start.sh --port 9000

启动成功后日志中会显示：

INFO  | Kiro Gateway started on http://0.0.0.0:8000

验证服务正常运行：

curl http://localhost:8000/health

第五步：连接客户端

在 Claude Code、Cursor 等客户端中填写：

字段 值
API Base URL http://localhost:8000
API Key .env 中 PROXY_API_KEY 的值
API 格式 OpenAI 或 Anthropic 均可
  • Anthropic 端点：POST http://localhost:8000/v1/messages
  • OpenAI 端点：POST http://localhost:8000/v1/chat/completions

附录 A：多账号配置

开启 ACCOUNT_SYSTEM=true 并首次启动后，编辑自动生成的 credentials.json 添加更多账号：

[
  {
    "type": "json",
    "path": "~/.aws/sso/cache/kiro-auth-token.json",
    "comment": "主账号"
  },
  {
    "type": "refresh_token",
    "refresh_token": "eyJhbGci...",
    "profile_arn": "arn:aws:codewhisperer:us-east-1:...",
    "comment": "备用账号"
  }
]

支持的账号类型：

type 说明
json Kiro IDE 凭证文件，或指向包含多个凭证文件的文件夹
refresh_token 直接填写 refresh token 字符串
sqlite kiro-cli SQLite 数据库，或指向包含多个数据库的文件夹

每个账号支持的可选参数：

{
  "enabled": true,             // false 可临时禁用该账号
  "region": "us-east-1",      // SSO 认证区域
  "api_region": "us-east-1",  // Q API 区域
  "profile_arn": "arn:..."    // CodeWhisperer profile ARN
}

故障转移行为：

  • 主账号出现 429 / 5xx / 网络超时 → 自动切换到下一个账号
  • 故障账号进入冷却期（指数退避：1分钟 → 2分钟 → 4分钟 → ... 最长1天）
  • 冷却期内仍有 10% 概率被重试，防止永久卡死
  • 致命错误（400、401）直接返回客户端，不触发切换

附录 B：其他配置项

调试日志

遇到问题时开启，日志保存在 debug_logs/ 目录：

DEBUG_MODE=errors   # 只保存失败请求（推荐）
# DEBUG_MODE=all    # 保存所有请求

服务器监听设置

SERVER_HOST="127.0.0.1"  # 仅允许本机访问（默认 0.0.0.0 监听所有网卡）
SERVER_PORT="8000"

附录 C：gateway 内容干预行为

gateway 默认开启了几个会主动修改请求或响应内容的功能。理解这些行为有助于判断是否需要关闭它们。

FAKE_REASONING — 思考过程注入

默认：开启

Kiro API 底层是 Claude，支持扩展思考，但 Kiro 没有暴露对应的 API 参数。gateway 通过 prompt 工程绕过这个限制：在每条用户消息前自动插入以下内容：

<thinking_mode>enabled</thinking_mode>
<max_thinking_length>16000</max_thinking_length>
<thinking_instruction>Think in English...</thinking_instruction>

[用户原始消息]

模型收到这些标签后会在回答前输出 <thinking>...</thinking> 推理过程，gateway 再将其解析并转换为 OpenAI 的 reasoning_content 字段返回。

FAKE_REASONING_BUDGET_CAP 控制思考 token 的上限。由于思考内容消耗的是输出 token（不是独立配额），预算过大会导致模型把所有输出都用于思考，正文反而为空。建议设为总输出 token 的一半左右：

FAKE_REASONING_BUDGET_CAP=16000

关闭后的效果：

  • 消息原样转发，模型不会有思考过程
  • 即使客户端请求了 thinking 参数，Kiro API 也不支持，同样不会生效
  • 响应速度更快，输出 token 全部用于正文

建议： 如果你的 agent 系统自己管理推理策略，或不需要思考过程，关闭可以获得更干净、更快的响应：

FAKE_REASONING=false

WEB_SEARCH_ENABLED — 网络搜索工具注入

默认：开启

gateway 会在每个请求的工具列表里自动追加一个 web_search 工具定义。模型决定调用时，gateway 拦截该调用，转而请求 Kiro 内置的 MCP 搜索 API，再把结果注入回响应流。

关闭后的效果：

  • 工具列表不再被修改，请求原样转发
  • 如果你的 agent 系统自己声明了搜索工具并自己执行，这是正确的做法——agent 可以使用任意搜索服务（Tavily、Bing 等），结果也完全由 agent 控制

建议： 使用 agent 系统时关闭，由 agent 自己管理搜索能力：

WEB_SEARCH_ENABLED=false

TRUNCATION_RECOVERY — 截断恢复通知

默认：开启

Kiro API 有时会在流传输中途截断响应（比如模型生成大文件时写到一半就断了）。

截断检测原理： Kiro API 在每次正常完成的响应末尾会发送一个 contextUsagePercentage 事件（表示本次请求消耗了多少上下文窗口）。gateway 以这个事件作为"正常结束"的信号——如果流结束了但没有收到这个事件，且已有内容输出，就判定为截断。工具调用的截断则通过 JSON 完整性检测：如果工具参数的 JSON 括号不匹配（有开括号没有闭括号），说明参数被截断。

开启后，gateway 检测到截断时会在下一轮请求中自动插入一条系统通知：

[System Notice] Your previous response was truncated by the API due to output limits.
Please adapt your approach (e.g., split large outputs into smaller parts).

模型看到这条消息后可以调整策略，比如把大文件拆成多次写入。

关闭后的效果：

  • 截断照样发生，但不插入任何通知
  • 模型不知道自己被截断，会继续正常对话，用户看到不完整的结果

建议： 如果你的 agent 系统自己有截断检测和重试逻辑，关闭可以避免 gateway 插入的通知消息干扰 agent 的上下文管理：

TRUNCATION_RECOVERY=false

AUTO_TRIM_PAYLOAD — 超限 Payload 静默裁剪

默认：关闭

Kiro API 拒绝超过约 615KB 的请求体，返回一个很不友好的 "Improperly formed request" 错误，完全看不出是 payload 太大导致的。

关闭时（默认）： 超限时 gateway 返回清晰的错误信息，由调用方自行处理：

Request payload too large (XXX bytes > 600000 bytes limit).
Please reduce conversation history or tool definitions.

开启时： gateway 自动从对话历史里删除最旧的消息对，直到 payload 缩小到限制内，然后继续发请求。用户无感知，但最旧的上下文被静默丢弃，调用方不知道这件事发生过。

建议： agent 系统通常自己管理上下文窗口，如果 gateway 在背后静默删消息，agent 的上下文状态和实际发出去的请求会不一致，可能导致难以排查的问题。保持关闭，让 agent 自己响应超限错误：

# AUTO_TRIM_PAYLOAD=false  # 默认已关闭，无需显式设置