💡 小贴士: 为获得最佳体验，建议通过 Web UI 控制台 进行可视化授权管理。

🌐 Web UI 快速授权（推荐）

在 Web UI 管理界面中，您可以快速完成授权配置：

1. 生成授权：在 “提供商池” 页面或 “配置” 页面，点击相应提供商（如 Gemini、Qwen）右上角的 “生成授权” 按钮。
2. 扫描/登录：会弹出授权对话框，您可以点击 “在浏览器中打开” 进行登录验证。对于 Qwen，只需完成网页登录；而对于 Gemini 和 Antigravity，则需完成 Google 账号授权。
3. 自动保存：授权成功后，系统会自动获取凭据并将其保存到 configs/ 目录下的对应文件中。您可以在 “配置文件” 页面查看新生成的凭据。
4. 可视化管理：您可以在 Web UI 中随时上传或删除凭据，也可以使用 “快速关联” 功能，一键将现有凭据文件绑定到提供商。

Gemini CLI OAuth 配置

1. 获取 OAuth 凭据：访问 Google Cloud 控制台 创建项目并启用 Gemini API。
2. 项目配置：您可能需要提供有效的 Google Cloud 项目 ID，可通过启动参数 --project-id 指定。
3. 确保项目 ID：在 Web UI 中配置时，请确保输入的项目 ID 与 Google Cloud 控制台和 Gemini CLI 中显示的项目 ID 一致。

Antigravity OAuth 配置

1. 个人账号：个人账号需要单独授权，申请渠道已关闭。
2. Pro 会员：Antigravity 目前暂时对 Pro 会员开放，您需要先购买 Pro 会员资格。
3. 组织账号：组织账号需要单独授权，请联系管理员获取授权。

Qwen Code OAuth 配置

1. 首次授权：配置 Qwen 服务后，系统会自动在浏览器中打开授权页面。
2. 推荐参数：为获得最佳效果，建议使用官方默认参数：

   {
     "temperature": 0,
     "top_p": 1
   }
   

Kiro API 配置

1. 环境准备：下载并安装 Kiro 客户端。
2. 完成授权：在客户端登录您的账户以生成 kiro-auth-token.json 凭证文件。
3. 最佳实践：建议与 Claude Code 搭配使用，以获得最佳体验。
4. 重要提示：Kiro 服务的使用政策已更新，请访问官方网站了解最新的使用限制和条款。

Kiro 扩展思维（Claude 模型）

AIClient-2-API 在使用 Claude 兼容请求（/v1/messages）或 OpenAI 兼容请求（/v1/chat/completions）并路由至 claude-kiro-oauth 时，支持 Kiro 扩展思维功能。

Claude 兼容（/v1/messages）：

curl http://localhost:3000/claude-kiro-oauth/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "thinking": { "type": "enabled", "budget_tokens": 10000 },
    "messages": [{ "role": "user", "content": "请逐步解答。" }]
  }'

OpenAI 兼容（/v1/chat/completions）：

curl http://localhost:3000/claude-kiro-oauth/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{ "role": "user", "content": "请逐步解答。" }],
    "extra_body": {
      "anthropic": {
        "thinking": { "type": "enabled", "budget_tokens": 10000 }
      }
    }
  }'

自适应模式：

• Claude："thinking": { "type": "adaptive", "effort": "high" }
• OpenAI："extra_body.anthropic.thinking": { "type": "adaptive", "effort": "high" }

注意事项：

• budget_tokens 的取值范围被限制为 [1024, 24576]（若未指定或无效，则默认为 20000）。
• 令牌的获取、刷新及池内轮换机制保持不变。

Codex OAuth 配置

1. 生成授权：在 Web UI 的“提供商池”或“配置”页面，点击 Codex 的“生成授权”按钮。
2. 浏览器登录：系统会打开 OpenAI Codex 的授权页面，供您完成 OAuth 登录。
3. 自动保存：授权成功后，系统会自动保存 Codex 的 OAuth 凭证文件。
4. 回调端口：请确保 OAuth 回调端口 1455 未被占用。

Grok Cookie/SSO 配置

1. 获取 SSO 令牌：登录 Grok 官方网站 后，在浏览器开发者工具的 Application -> Cookies 中复制 sso 的值。
2. 进入配置：在 Web UI 的“配置”页面或直接修改配置文件，将该令牌填入 GROK_COOKIE_TOKEN。
3. 支持的功能：
   • 聊天和思维模型（Grok 3 Thinking）
   • 图像生成（Grok Imagine）
   • 视频生成（Grok Video）
4. 注意事项：请确保 GROK_USER_AGENT 与获取 Cookie 时使用的浏览器一致，以免被封禁。

账户池管理配置

1. 创建池配置文件：参照 provider_pools.json.example 创建配置文件。
2. 配置池参数：在 configs/config.json 中设置 PROVIDER_POOLS_FILE_PATH，使其指向池配置文件。
3. 启动参数配置：使用 --provider-pools-file <路径> 参数指定池配置文件的路径。
4. 健康检查：系统会自动进行定期健康检查，并避免使用不健康的提供商。

各服务授权凭证文件的默认存储位置：

注意: ~ 表示用户主目录（Windows: C:\Users\用户名, Linux/macOS: /home/用户名 或 /Users/用户名）

自定义路径: 可通过配置文件中的相关参数或环境变量指定自定义存储位置

1. 接入代理配置

本项目支持灵活的代理配置，既可为不同提供商统一配置代理，也可使用各提供商专用的代理端点。

配置方式：

1. Web UI 配置（推荐）：便捷的配置管理

   在 Web UI 的“配置”页面中，您可以直观地配置所有代理选项：

   • 统一代理：在“代理设置”区域填写代理地址，并勾选需要使用该代理的提供商
   • 提供商端点：在每个提供商的配置区域，直接将 Base URL 修改为代理后的端点
   • 点击“保存配置”：无需重启服务即可立即生效

2. 统一代理配置：配置全局代理并指定哪些提供商使用该代理

   • Web UI 配置：在“配置”页面的“代理设置”区域填写代理地址，并勾选需要使用代理的提供商
   • 配置文件：在 configs/config.json 中配置

   {
     "PROXY_URL": "http://127.0.0.1:7890",
      "PROXY_ENABLED_PROVIDERS": [
        "gemini-cli-oauth",
        "gemini-antigravity",
        "claude-kiro-oauth",
        "grok-custom"
      ]
   }
   

3. 提供商专用代理端点：部分提供商（如 OpenAI、Claude）支持配置代理后的 API 端点

   • Web UI 配置：在“配置”页面的各提供商配置区域，修改对应的 Base URL
   • 配置文件：在 configs/config.json 中配置

   {
     "OPENAI_BASE_URL": "https://your-proxy-endpoint.com/v1",
     "CLAUDE_BASE_URL": "https://your-proxy-endpoint.com"
   }
   

支持的代理类型：

• HTTP 代理：http://127.0.0.1:7890
• HTTPS 代理：https://127.0.0.1:7890
• SOCKS5 代理：socks5://127.0.0.1:1080

使用场景：

• 网络受限环境：适用于无法直接访问 Google、OpenAI 等服务的网络环境
• 混合配置：部分提供商使用统一代理，另一些则使用各自的代理端点
• 灵活切换：可在 Web UI 中随时启用或禁用特定提供商的代理

注意事项：

• 代理配置优先级：统一代理配置 > 提供商专用端点 > 直连
• 请确保代理服务稳定可用，否则可能影响服务质量
• SOCKS5 代理通常比 HTTP 代理性能更好

2. 模型过滤配置

支持通过 notSupportedModels 配置排除不支持的模型，系统会自动跳过这些提供商。

配置：在 configs/provider_pools.json 中为提供商添加 notSupportedModels 字段：

{
  "gemini-cli-oauth": [
    {
      "uuid": "provider-1",
      "notSupportedModels": ["gemini-3.0-pro", "gemini-3.5-flash"],
      "checkHealth": true
    }
  ]
}

工作原理：

• 当请求特定模型时，系统会自动过滤掉已配置为不支持该模型的提供商
• 只有支持该模型的提供商才会被选中来处理请求

使用场景：

• 某些账号因配额或权限限制而无法访问特定模型
• 需要为不同账号分配不同的模型访问权限

3. 跨类型回退配置

当某个提供商类型（如 gemini-cli-oauth）下的所有账号因 429 配额限制或被标记为不健康而耗尽时，系统可以自动回退到另一个兼容的提供商类型（如 gemini-antigravity），而不是直接返回错误。

配置：在 configs/config.json 中添加 providerFallbackChain 配置：

{
  "providerFallbackChain": {
    "gemini-cli-oauth": ["gemini-antigravity"],
    "gemini-antigravity": ["gemini-cli-oauth"],
    "claude-kiro-oauth": ["claude-custom"],
    "claude-custom": ["claude-kiro-oauth"]
  }
}

工作原理：

1. 尝试从主要提供商类型的池中选择一个健康的账号
2. 如果该类型的全部账号都不健康或返回 429 错误：
   • 查找配置的回退类型
   • 检查回退类型是否支持请求的模型（协议兼容性检查）
   • 从回退类型的池中选择一个健康的账号
3. 支持多级降级链：gemini-cli-oauth → gemini-antigravity → openai-custom
4. 仅当所有回退类型也都不可用时，才会返回错误

使用场景：

• 在批量任务场景中，单个提供商类型的免费 RPD 配额很容易在短时间内耗尽
• 通过跨类型回退，可以充分利用多个提供商的独立配额，提高整体可用性和吞吐量

注意事项：

• 回退仅发生在协议兼容的类型之间（如 gemini-* 之间、claude-* 之间）
• 系统会自动检查目标提供商类型是否支持请求的模型

4. TLS Sidecar（绕过 403/Cloudflare）

对于像 Grok 这样严格验证 TLS 指纹（JA3/JA4）的服务，本项目集成了基于 Go uTLS 的 Sidecar 代理，通过模拟浏览器的 TLS 特性，有效解决 403 Forbidden 错误。

配置说明：

1. 编译二进制文件： 由于 TLS 模拟需要 Go 语言支持，您需要先编译 Sidecar：

   cd tls-sidecar
   go build -o tls-sidecar
   

   Windows 用户编译后，请确保生成的 tls-sidecar.exe 位于 tls-sidecar/ 或根目录下。

2. 启用配置： 在 Web UI 的“配置”页面中启用 TLS Sidecar，或修改 configs/config.json：

   {
     "TLS_SIDECAR_ENABLED": true,
     "TLS_SIDECAR_PORT": 9090
   }
   

3. 工作原理：

   • 启用后，系统会自动启动并管理 Go 进程。
   • 对特定提供商（如 Grok）的请求会自动路由到 Sidecar。
   • Sidecar 使用最新的 Chrome 指纹进行 TLS 握手，并支持自动 HTTP/2 协商。

注意事项：

• 本地运行需要 Go 环境（1.20 及以上版本）。
• Docker 用户：镜像中已包含预编译的二进制文件，只需在配置中启用即可，无需手动编译。

1. OAuth 授权失败

问题描述：点击“生成授权”后，浏览器会打开授权页面，但授权失败或无法完成。

解决方案：

• 检查网络连接：确保可以正常访问 Google、阿里云等服务。
• 检查端口占用：OAuth 回调需要特定端口（Gemini：8085，Antigravity：8086，Codex：1455，Kiro：19876-19880），请确保这些端口未被占用。
• 清除浏览器缓存：尝试使用无痕模式或清除浏览器缓存后重试。
• 检查防火墙设置：确保防火墙允许访问本地回调端口。
• Docker 用户：确保所有 OAuth 回调端口已正确映射。

2. 端口已被占用

问题描述：启动服务时提示端口已被占用（例如 EADDRINUSE）。

解决方案：

# Windows - 查找占用端口的进程
netstat -ano | findstr :3000
# 然后使用任务管理器结束对应的 PID 进程

# Linux/macOS - 查找并结束占用端口的进程
lsof -i :3000
kill -9 <PID>

或者修改 configs/config.json 中的端口配置，使用其他端口。

3. Docker 容器无法启动

问题描述：Docker 容器无法启动或立即退出。

解决方案：

• 查看日志：运行 docker logs aiclient2api 查看错误信息。
• 检查挂载路径：确保 -v 参数中的本地路径存在且具有读写权限。
• 检查端口冲突：确保主机上所有映射的端口未被占用。
• 重新拉取镜像：运行 docker pull justlikemaki/aiclient-2-api:latest。

4. 凭证文件无法识别

问题描述：上传或配置凭证文件后，系统提示无法识别或格式错误。

解决方案：

• 检查文件格式：确保凭证文件为有效的 JSON 格式。
• 检查文件路径：确保文件路径正确，Docker 用户需确认文件位于挂载目录中。
• 检查文件权限：确保服务有权限读取该凭证文件。
• 重新生成凭证：若凭证已过期，可尝试通过 OAuth 重新授权。

5. 请求返回 429 错误

问题描述：API 请求频繁返回 429 Too Many Requests 错误。

解决方案：

• 配置账号池：在 provider_pools.json 中添加多个账号，启用轮询机制。
• 配置回退机制：在 config.json 中配置 providerFallbackChain 实现跨类型降级。
• 降低请求频率：适当增加请求间隔，避免触发限流。
• 等待配额重置：免费配额通常每日或每分钟重置。

6. 模型不可用或返回错误

问题描述：请求特定模型时，返回错误或提示模型不可用。

解决方案：

• 检查模型名称：确保使用的模型名称正确（区分大小写）。
• 检查提供商支持：确认当前配置的提供商是否支持该模型。
• 检查账号权限：部分高级模型可能需要特定的账号权限。
• 配置模型过滤：使用 notSupportedModels 排除不支持的模型。

7. Web UI 无法访问

问题描述：浏览器无法打开 http://localhost:3000。

解决方案：

• 检查服务状态：确认服务已成功启动，查看终端输出。
• 检查端口映射：Docker 用户需确保 -p 3000:3000 参数正确。
• 尝试其他地址：尝试访问 http://127.0.0.1:3000。
• 检查防火墙：确保防火墙允许访问 3000 端口。

8. 流式响应中断

问题描述：使用流式输出时，响应中途中断或不完整。

解决方案：

• 检查网络稳定性：确保网络连接稳定。
• 增加超时时间：在客户端配置中增加请求超时时间。
• 检查代理设置：若使用代理，确保代理支持长连接。
• 查看服务日志：检查是否有错误信息。

9. 配置更改未生效

问题描述：在 Web UI 中修改配置后，服务行为未发生变化。

解决方案：

• 刷新页面：修改后刷新 Web UI 页面。
• 检查保存状态：确认配置已成功保存（查看提示信息）。
• 重启服务：部分配置可能需要重启服务才能生效。
• 检查配置文件：直接查看 configs/config.json，确认更改是否已写入。

10. API 返回 404

解决方案：

• 检查端点路径：确保使用正确的端点路径，如 /v1/chat/completions 等。
• 检查客户端自动补全：某些客户端（如 Cherry-Studio、NextChat）会在 Base URL 后自动追加路径（如 /v1/chat/completions），导致路径重复。请在控制台中查看实际请求 URL，并移除多余的路径部分。
• 检查服务状态：确认服务已正常启动，访问 http://localhost:3000 查看 Web UI。
• 检查端口配置：确保请求发送到正确的端口（默认 3000）。
• 查看可用路由：在 Web UI 仪表盘页面的“交互式路由示例”中查看所有可用端点。

11. 未授权：API 密钥无效或缺失

问题描述：调用 API 端点时，返回 Unauthorized: API key is invalid or missing. 错误。

解决方案：

• 检查 API 密钥配置：确保在 configs/config.json 或 Web UI 中正确配置了 API 密钥。
• 检查请求头格式：确保请求包含正确的 Authorization 头格式，例如 Authorization: Bearer your-api-key。
• 检查服务日志：在 Web UI 的“实时日志”页面查看详细错误信息，以定位具体原因。

12. 该类型无可用且健康的提供商

问题描述：调用 API 时，返回 No available and healthy providers for type xxx 错误。

解决方案：

• 检查提供商状态：在 Web UI 的“提供商池”页面中，检查相应类型的提供商是否处于健康状态。
• 检查凭证有效性：确认 OAuth 凭证未过期；若过期，请重新生成授权。
• 检查配额限制：部分提供商可能已达到免费配额上限，需等待配额重置或添加更多账号。
• 启用回退机制：在 config.json 中配置 providerFallbackChain，以便在主提供商不可用时自动切换到备用提供商。
• 查看详细日志：在 Web UI 的“实时日志”页面中查看具体的健康检查失败原因。

13. 请求返回403 Forbidden错误

问题描述：API请求返回403 Forbidden错误。

解决方案：

• 启用TLS Sidecar：对于Grok等服务，403错误通常是由于TLS指纹拦截导致的。请参考高级配置 - TLS Sidecar来启用并编译Sidecar。
• 检查节点状态：如果在Web UI的“Provider Pools”页面上看到节点状态正常（健康检查通过），则可以忽略此错误，系统会自动处理。
• 检查账户权限：确认账户是否有权限访问所请求的模型或服务。
• 检查API密钥权限：某些提供商的API密钥可能存在访问范围限制；请确保该密钥具有足够的权限。
• 检查区域限制：部分服务可能有区域访问限制；可尝试使用代理或VPN。
• 检查凭证状态：OAuth凭证可能已被撤销或过期；可尝试重新生成授权。
• 检查请求频率：部分提供商对请求频率有严格限制；请降低请求频率后重试。
• 查看提供商文档：访问相应提供商的官方文档，了解具体的访问限制和要求。