Air Router

外观

常见问题与排错 ​

建议先执行最小化请求，将“客户端配置问题”和“API Key 或网关问题”分开定位。

先做三个检查 ​

1. 检查 Base URL ​

text
Claude Code: https://www.air-router.com
Codex:       https://www.air-router.com/v1
Grok Build:  https://www.air-router.com/v1

2. 检查 Key 是否可读模型列表 ​

bash
curl -i https://www.air-router.com/v1/models \
  -H "Authorization: Bearer $AIR_ROUTER_API_KEY"

3. 检查模型 ID ​

客户端中的模型 ID 必须与 /v1/models 返回结果完全一致，包括大小写、连字符和版本后缀。

按状态码定位 ​

400 Bad Request ​

常见原因：

  • 请求体不是合法 JSON
  • model、messages、input 等必填字段缺失
  • 将 Responses 参数发送到 Chat Completions 路由
  • 模型不支持当前工具、图片、搜索或推理参数

先删除非必要参数，只保留 model 和最小输入；成功后再逐项加回。

401 Unauthorized ​

检查：

  • 是否发送 Authorization: Bearer sk-... 或 x-api-key: sk-...
  • Bearer 后是否有一个空格
  • 环境变量是否在当前终端生效
  • API Key 是否被禁用、删除或复制不完整
  • Codex/Grok 的 env_key 是否误填成了真实密钥

403 Forbidden ​

认证已通过，但当前 Key 无权访问目标模型或能力。检查 Key 分组、模型包状态、账户状态和权限限制。

404 Not Found ​

最常见的是 /v1 重复或缺失：

  • Claude Code 配置应去掉 /v1
  • Codex 与 Grok Build 配置应保留 /v1
  • 自己发送 HTTP 请求时，完整路径应为 /v1/models、/v1/messages 或 /v1/responses

429 Too Many Requests ​

可能是余额、套餐额度、并发或速率限制。先停止并行任务，等待一小段时间后发送一次最小请求；若持续出现，再检查控制台额度和限制说明。

客户端自动重试可能放大 429。应使用带抖动的指数退避，并限制最大重试次数。

500 / 502 / 503 / 504 ​

通常表示网关或上游暂时不可用：

  1. 记录发生时间、路由、模型和请求 ID。
  2. 用同一 Key 请求 /v1/models，确认基础链路。
  3. 降低并发并在短暂等待后重试一次。
  4. 检查站点公告或服务状态说明。

持续失败时向客服提供脱敏信息，不要发送完整密钥和完整私有代码。

客户端专项问题 ​

Claude Code 配置不生效 ​

  • 确认文件是 ~/.claude/settings.json
  • 用 JSON 校验工具检查逗号和引号
  • 完全退出旧进程并重新打开终端
  • 检查系统环境变量是否覆盖了设置文件

Codex 仍要求官方登录 ​

  • Provider 配置必须在用户级 ~/.codex/config.toml
  • 顶层必须有 model_provider = "air_router"
  • Provider 段名必须是 [model_providers.air_router]
  • wire_api 应为 responses

Grok Build 搜索不可用 ​

  • [models].web_search 应指向已定义的模型配置
  • 模型段需要 supports_backend_search = true
  • 当前模型包必须实际支持后端搜索

网络与代理检查 ​

bash
curl -I https://www.air-router.com

如果域名无法解析或 TLS 握手失败，先检查本机 DNS、系统时间、代理环境变量和公司网络策略。若使用自建 Nginx，再确认请求头未被过滤，且超时足以覆盖模型响应时间。

提交问题时提供什么 ​

  • 客户端名称和版本
  • 操作系统与终端类型
  • 脱敏后的 Base URL 和配置片段
  • 请求时间、HTTP 状态码、错误原文和请求 ID
  • 模型 ID、API 路由和是否开启流式响应
  • API Key 名称或末尾 4 位，不要提供完整 Key