常见问题与排障
开发者接入网关时最常问的问题，以及每种报错该去哪里查。
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 在控制台 → API 密钥里是否还存在、未过期。用 Claude Code 的话，再检查 ~/.claude/settings.json——它 env 块的优先级高于 shell 环境变量，旧 Key 留在里面会盖过新的 export。最常见的写坏形态：Bearer 重复两次（Bearer Bearer sk-…，客户端自动加前缀而变量里已经带了）、把引号也粘进了值里、Key 中间混入换行、或者把控制台登录 token 当成 API Key 发了——被这样改坏的有效 Key 在查库之前就会被拒绝。
报 402 Payment Required。
Key 有效，但钱包余额（或该 Key 的 maxSpend）不够覆盖这次请求所需的初始预留——通常是已经用完；请求输入很大，或其他进行中的请求暂时占用了资金，也会出现。支付宝或银行卡在同一个托管收银台完成充值，也支持 6 条链上的 USDT/USDC（Tron、BSC、以太坊、Polygon、Base、Arbitrum）——或调高 Key 的 maxSpend。
报 429 Too Many Requests。
正常付费使用不设低额度固定上限；每把 Key 和每个账户按默认的每分钟请求数与每分钟 token 数限流，上游约束也可能生效。遇到 429 时请退避重试（有 Retry-After 时按它等待）；需要更高限额时发邮件到 support@router.one 申请调高 Key 或账户限额。code 指明命中的是哪一种限制（RATE_LIMIT_EXCEEDED、TOKEN_QUOTA_EXCEEDED、SUBSCRIPTION_QUOTA_EXCEEDED）；Key 或账户限额触发的 429 在调用任何模型之前就被拒绝，日志里只会出现网关重试之后上游仍返回的 429。
请求返回 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 下变量写在用户级环境变量里，新开的会话自动生效。
Codex 报 stream disconnected before completion。
这是 SSE 流提前结束时 Codex 自己抛出的报错。后面跟 idle timeout waiting for SSE，表示在 stream_idle_timeout_ms（默认 300000 毫秒）内没收到任何事件：GPT 模型长时间推理时可能这么久都没有事件，在自定义的 [model_providers.<id>] 块里把它调大即可，例如 600000。后面跟 stream closed before response.completed，表示连接在最终事件之前就关闭了，先查代理、VPN 或网络。网关不会因为空闲而结束原生 Responses 流。
流式输出、工具调用和结构化输出在不同模型上用法一样吗？
请求格式一样：同一端点设 stream: true 即收到官方形态的 SSE 分块；tools 按 OpenAI 兼容格式声明一次；response_format（json_object，或带命名 schema 的 json_schema）也放在同一个请求里。支持程度仍因模型而异——目录按模型标注了工具调用能力，schema 是否强制执行由模型决定，不是网关。目录不显示的一条厂商规则：按 OpenAI 文档（2026-10-01 核对），GPT-6 Astra 与 GPT-6.1 Sol 的工具调用只走 Responses API，GPT-6 Sol 在 Chat Completions 上只有 reasoning_effort 为 none 时才能调用函数。网关会校验 response_format 外层结构：缺 json_schema、name 或 schema 时，在调用任何模型之前就返回 400。各模型的差异可在控制台 → 日志的请求 Trace 中看到。
模型 ID 去哪里查？model 填 "auto" 是什么意思？
模型目录列出了每个模型的 ID、价格、上下文窗口和能力标签——ID 区分大小写，直接复制最稳妥。填 auto 时，网关用规则加一个轻量分类器把请求分到低、中、高三档之一，再用该档服务端维护的模型列表中的模型处理；需要指定模型时填精确 ID——指定目录模型 ID 的请求由该模型处理。以 azure/、aws/、vertex/ 为前缀的 ID 选择同一基础模型的独立定价销售渠道，路由池与配额口径都独立；裸名和带厂商前缀（openai/、anthropic/）的 ID 保持默认渠道。
怎么看每次请求花了多少钱？
网关发往模型的请求通常都会记录实际处理请求的模型、发起请求的 API Key、tokens、花费、总耗时（产生过输出的流式请求另有首字延迟）和状态。控制台 → 日志看单次请求明细，可按模型、API Key、状态和日期筛选；控制台 → 用量看花费趋势。日志里查不到某个请求只是线索，不能单独下结论：它可能没到达网关（base URL、Key 或网络问题），也可能在调用模型之前就被拒绝（Key 校验失败的 401、余额不足或 Key 达到 maxSpend 上限的 402、Key 或账户限额触发的 429，或模型 ID、端点不对的 400 / 404），也可能是在输出任何内容之前就失败的流式请求，或仍在等待定价。
其他工具（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} 轮询结果。不要给这类接口设太短的客户端超时；对话场景建议开流式，边生成边接收。
Claude Code 2.1.284 发出 claude-sonnet-5-5：Router One 能用吗？套餐覆盖吗？
按 Claude Code 更新日志与模型配置文档（2026-10-01 核对），2.1.284（2026-09-28）把 sonnet 别名指向 Claude Sonnet 5.5，发出的 ID 是 claude-sonnet-5-5。Router One 自 2026-09-29 起列出 claude-sonnet-5-5，但 2026-09-29 的套餐接口里 Pro、Max、Ultra 都没有档位列出它，所以用套餐时，/model sonnet、定义为 model: sonnet 的子代理、/statusline 以及 opusplan 的执行阶段都按 token 从钱包扣费（控制台 → 日志的模型列显示每次调用用的 ID）。想继续消耗套餐额度，把 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 写进 ~/.claude/settings.json 的 env 块；不论是否用套餐，也可以在这个 env 块里加上 ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5，然后重启 Claude Code。按 Claude Code 2.1.300 的更新日志与模型配置文档（2026-10-15 核对），fable 别名解析为 claude-fable-5-1，截至 2026-10-15 的模型目录 Router One 已重新列出它，无需固定；2.1.293 及以后的版本把 haiku 别名解析为 claude-haiku-5-5（Claude Haiku 5.5），截至 2026-10-10 的模型目录 Router One 已列出它，但 2026-10-10 的套餐接口里没有档位列出它，不加 Haiku 这一行时这个别名按 token 从钱包扣费。截至 2026-10-15 的套餐接口，Claude Fable 5.1 与 Claude Fable 5 都不在任何套餐档位，fable 别名的请求按 token 从钱包扣费。之前加过 ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5 的，要删掉这一行，fable 别名才会改用 Claude Fable 5.1。
订阅了 Pro、Max 或 Ultra，为什么 Claude Code 还在扣钱包？
先看控制台 → 日志里的模型列。按 Claude Code 更新日志与模型配置文档（2026-10-01 核对），2.1.280 及以后默认使用 Claude Opus 5.5，没有固定模型时发出 claude-opus-5-5；截至 2026-09-29 的套餐接口，Pro、Max、Ultra 都没有任何档位列出这个 ID，这些调用按 token 从钱包扣费。想继续用套餐额度，在 ~/.claude/settings.json 的 env 块里设置 ANTHROPIC_MODEL=claude-opus-5 和 ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5——Claude Opus 5 在三个套餐的「高级模型」档。套餐各档之外的模型，以及某一档月度额度用完之后的请求，同样从钱包扣费。2.1.284 及以后，sonnet 别名在套餐下同样走钱包，除非固定它（见上一问）。
为什么一次请求扣了好几次套餐额度？
因为这次请求的总输入超过了该模型的长上下文门槛。普通请求从所属模型档位扣 1 次；单次请求的总输入严格超过门槛时，按输入长度分段多扣——例如 Claude Opus 5 超过 256,000 输入 token 扣 2 次、超过 512,000 扣 4 次（按 2026-10-01 的目录）。输入只计一次（含缓存输入），输出不计入，恰好等于门槛的输入仍按较低一段计。从钱包扣费的调用不消耗套餐次数，仍按模型公示的 token 单价计费。各套餐覆盖模型的实时分段见 /pricing.md。
Claude Code 2.1.285 及以后：为什么长会话扣套餐额度更快？
按 Claude Code 更新日志与模型配置文档（2026-10-01 核对），自 2.1.285 起，在通过自定义 ANTHROPIC_BASE_URL 接入的会话里，Sonnet 5 及以后、Opus 4.7 及以后的模型和 Fable 系列都使用与 Anthropic API 上相同的 1M 上下文窗口，默认要到约 967K token 才压缩。每一轮都会重发整段对话，长会话的请求就会越过上一问所说的扣次分段：claude-sonnet-5 或 claude-opus-5 的单次请求输入超过 256,000 token 扣 2 次套餐额度，超过 512,000 扣 4 次（按 2026-10-01 的目录）。想在越过第一段之前就压缩，就在 ~/.claude/settings.json 的 env 块里加 CLAUDE_CODE_AUTO_COMPACT_WINDOW=240000（只接受纯整数）并重启 Claude Code，它对所有模型生效。也可以在会话里运行 /autocompact 240k，但按模型配置文档（2026-10-03 核对），Claude Code 2.1.288 起它只为当前模型保存，换到哪个模型就要在那个模型上再运行一次；两者都设时以环境变量为准。某一轮加入很大的文件或工具结果时，仍可能越过这一段。另一种做法是设置 CLAUDE_CODE_DISABLE_1M_CONTEXT=1，把这些模型的窗口限制在 200K。
Claude Code 提示 this session isn't eligible（auto 模式分类器请求），是什么意思？
按 Claude Code 的 auto 模式分类器计费文档（2026-10-01 核对），这条提示的意思是：auto 模式可用的服务端审查没有到达这个会话，所以 Claude Code 改为自己发起分类器请求，计费方式与以前相同；功能没有坏，auto 模式照常工作。Claude Code 能识别出路径上的网关时，提示里会写出它的名字。提示会先挂起第一个待审查的动作：按 Enter 继续；如果提示点名了网关，这台机器 24 小时内不再显示；按 Esc 或 Ctrl+C 则取消这个动作并结束本轮。想让提示不再出现，在启动会话前把 CLAUDE_CODE_AUTO_MODE_SERVER=0 写进 ~/.claude/settings.json 的 env 块（或 shell）：分类器请求从此都由 Claude Code 自己发起，计费方式不变。文档说明这是临时设置，以后的版本可能移除。