常见问题与排障
开发者接入网关时最常问的问题，以及每种报错该去哪里查。
Base URL 到底填哪个？带不带 /v1？
OpenAI 兼容客户端（OpenAI SDK、Chat Completions、Responses、图片、视频、Codex CLI）用 https://api.router.one/v1——带 /v1。Anthropic 兼容客户端（Anthropic SDK、Claude Code）用 https://api.router.one——不带 /v1，因为客户端会自己拼接 /v1/messages。刚配置完就 404，基本都是这个原因。
报 401 Unauthorized，查什么？
按顺序查三件事：Key 是否复制完整（sk- 开头、末尾没有空格）；请求是否以 Authorization: Bearer <key> 发送；Key 在 Dashboard → API Keys 里是否还存在、未过期。用 Claude Code 的话，再检查 ~/.claude/settings.json——它 env 块的优先级高于 shell 环境变量，旧 Key 留在里面会盖过新的 export。
报 402 Payment Required。
Key 有效，但钱包余额（或该 Key 的消费上限）用完了。支付宝或银行卡在同一个托管收银台完成充值，也支持 6 条链上的 USDT/USDC（Tron、BSC、以太坊、Polygon、Base、Arbitrum）——或调高 Key 的 maxSpend。
报 429 Too Many Requests。
正常付费使用不设低额度固定上限；但平台仍保留滥用防护、账号级保护限制和上游约束。若遇到 429，可在 Dashboard -> Logs 查看原因或联系支持提升额度。按 Retry-After 退避后重试；code 指明命中的是哪一种限制（RATE_LIMIT_EXCEEDED、TOKEN_QUOTA_EXCEEDED、SUBSCRIPTION_QUOTA_EXCEEDED）。
请求返回 200，但 message 内容是空的。
这是一次已完成的响应，不是报错，不要自动重试。模型有时会消耗 token 却不写出答案——系统提示要求它保持沉默、推理完没有产出，或者以 message.refusal 形式拒答。这样的回复会被原样返回，结算依据是该响应报告的 usage，循环重试只会为同一份沉默重复付费。先看回复里的 finish_reason、refusal 和 usage。完全没有 usage 的空响应才算故障：会按上游错误处理，换同一模型的下一个候选重试。
Claude Code 还是弹官方登录界面（或用错了账号）。
说明网关环境变量没有生效。一键脚本会把 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 写进 ~/.claude/settings.json 的 env 块——先确认它们在文件里，然后重启 Claude Code。如果你是手动配置 shell 环境变量，请开一个新终端让 export 生效，并确认 settings.json 里没有残留旧值把它覆盖。
Codex 提示缺少 ROUTER_ONE_API_KEY 环境变量。
Codex 通过 ~/.codex/config.toml 里声明的 env_key 从 ROUTER_ONE_API_KEY 环境变量读取 Key。安装脚本已把 export 追加到你的 shell 配置文件——当前终端先执行 source ~/.zshrc（或对应的 shell 配置），或者直接开个新终端。Windows 下变量写在用户级环境变量里，新开的会话自动生效。
流式输出、工具调用和结构化输出在不同模型上用法一样吗？
请求格式一样：同一端点设 stream: true 即收到官方形态的 SSE 分块；tools 按 OpenAI 兼容格式声明一次；response_format（json_object，或带命名 schema 的 json_schema）也放在同一个请求里。支持程度仍因模型而异——目录按模型标注了工具调用能力，schema 是否强制执行由模型决定，不是网关。网关会检查 response_format 信封：缺 json_schema、name 或 schema 时，在调用任何模型之前就返回 400。各模型的差异可在 Dashboard → Logs 的请求 Trace 中看到。
模型 ID 去哪里查？model 填 "auto" 是什么意思？
模型目录列出了每个模型的 ID、价格、上下文窗口和能力标签——ID 区分大小写，直接复制最稳妥。填 auto 时，网关在服务端维护的候选集内按延迟、标价成本和可靠性信号路由；需要指定模型时填精确 ID。
怎么看每次请求花了多少钱？
经过网关的每次请求都会记录模型、tokens、花费、延迟、状态和路由决策。Dashboard → Logs 看单次请求明细，Dashboard → Usage 看花费趋势。如果一个请求在 Logs 里完全没出现，说明它没到达网关——问题在本地（base URL、Key 或网络）。
其他工具（LangChain、Cherry Studio、Cline 等）怎么接入？
任何支持自定义 OpenAI 兼容 base URL 的工具都能接：base URL 填 https://api.router.one/v1，粘贴 sk- 开头的 Key，再从目录选一个模型 ID。走 Anthropic 协议的工具则填 https://api.router.one。
中国大陆能直连吗？
能——大陆无需 VPN 即可直连网关，配置在任何地区完全一致。
图片/视频请求很慢，要不要设客户端超时？
生成类接口天然比对话慢：图片生成通常要几十秒；视频生成是异步的——提交后返回 task_id，用 GET /v1/videos/generations/{task_id} 轮询结果。不要给这类接口设太短的客户端超时；对话场景建议开流式，边生成边接收。