常见问题
连接问题
无法连接到代理
症状：客户端报错 Connection refused 或 ECONNREFUSED
解决方案：
确认代理已启动
python run.py # 应该看到: Kiro API Proxy v1.7.1 # http://localhost:8080检查端口是否正确
- 默认端口是 8080
- 如果修改了端口，客户端配置也要对应修改
检查防火墙
- Windows: 允许 Python 通过防火墙
- macOS: 系统偏好设置 → 安全性与隐私 → 防火墙
401 认证失败
症状：请求返回 401 Unauthorized
原因：Token 已过期或无效
解决方案：
- 点击账号卡片的「刷新 Token」
- 如果刷新失败，重新登录获取新 Token
- 检查账号状态是否为 Active
请求问题
429 Too Many Requests
症状：请求返回 429 错误
原因：Kiro 有请求频率限制，短时间内请求过多
代理自动处理：
- 将该账号冷却 5 分钟
- 自动切换到其他可用账号
- 冷却结束后自动恢复
建议：
- 添加多个账号分散请求
- 避免短时间内大量请求
- 在「监控」页面查看配额状态
对话太长 (CONTENT_LENGTH_EXCEEDS_THRESHOLD)
症状：请求返回错误 Input is too long
原因：Kiro API 有输入长度限制，这是服务端限制
代理自动处理：
代理内置了历史消息管理功能，可以在「设置」页面配置：
- 自动截断 - 发送前优先保留最新上下文并摘要前文，必要时截断保留最近 N 条
- 错误重试 - 遇到长度错误时自动截断并重试（默认启用）
- 预估检测 - 发送前预估 token 数量，超限则预先截断
推荐组合：错误重试（默认）或 自动截断 + 预估检测
手动解决方案：
- 在 Claude Code 中输入
/clear清空对话历史 - 清空后告诉 AI 你之前在做什么
- AI 会读取代码文件恢复上下文
预防措施：
- 复杂任务分阶段完成
- 每个阶段结束后清空对话
- 避免在对话中粘贴大量代码
响应很慢
可能原因：
- 网络延迟
- Kiro 服务端繁忙
- 请求内容过长
解决方案：
- 在「监控」页面运行速度测试
- 尝试切换账号
- 检查网络连接
Token 问题
Token 过期了怎么办
自动处理：代理会自动检测并刷新 Token
手动处理：
- 点击账号卡片的「刷新 Token」按钮
- 如果刷新失败，说明 refresh_token 也过期了
- 需要重新登录获取新 Token
如何添加多个账号
方法一：多次在线登录
- 使用不同的 Google/GitHub 账号
- 每次登录后自动添加新账号
方法二：扫描 Token
- 在 Kiro IDE 中用不同账号登录
- 每次登录后点击「扫描 Token」
- 选择新的 Token 文件添加
Token 文件在哪里
Token 保存在 ~/.aws/sso/cache/ 目录下：
~/.aws/sso/cache/
├── xxxxxxxx.json # Token 文件
├── yyyyyyyy.json # 另一个 Token
└── ...
每个 JSON 文件包含一个账号的 Token 信息。
模型问题
支持哪些模型
| 模型 | 能力 | 推荐场景 |
|---|---|---|
| claude-sonnet-4 | ⭐⭐⭐ 均衡 | 日常编程，推荐 |
| claude-sonnet-4.5 | ⭐⭐⭐⭐ 更强 | 复杂任务 |
| claude-haiku-4.5 | ⚡ 快速 | 简单问答，速度优先 |
模型映射关系
使用 OpenAI 模型名时会自动映射：
| 请求模型 | 实际使用 |
|---|---|
| gpt-4o, gpt-4 | claude-sonnet-4 |
| gpt-4o-mini, gpt-3.5-turbo | claude-haiku-4.5 |
| o1, o1-preview | claude-sonnet-4.5 |
支持工具调用吗
支持！ Claude Code 的工具调用功能已验证可用，包括：
- 文件读写
- 命令执行
- 代码搜索
- 等等
其他问题
如何查看请求日志
- 打开「日志」标签页
- 查看最近的请求记录
- 包含时间、路径、模型、状态、耗时
如何监控账号状态
- 打开「监控」标签页
- 查看服务状态和统计信息
- 查看配额状态和冷却中的账号
配置文件在哪里
- 账号配置：
~/.kiro-proxy/config.json - Token 文件：
~/.aws/sso/cache/*.json