最近不少开发者反馈在对接 OpenRouter 时会遇到请求变慢、突然 429、5xx甚至 Claude Code 会话中途断开的情况。这个现象不是个别项目特有的而是 OpenRouter 作为一个模型聚合服务在高峰期或上游模型不稳定时经常出现的问题。很多网上的帖子只贴一个报错截图没有把排查思路讲清楚所以这篇文章围绕“OpenRouter 服务异常”的完整应对方式展开包含错误码认知、健康检查脚本、重试封装、Claude Code 接入排查以及降级容灾方案。无论你是在做 AI 应用开发还是只是用 OpenRouter 的 API Key 接入 Claude Code这篇文章都能直接拿来用。1. OpenRouter 是什么异常时你会看到什么1.1 OpenRouter 的核心定位OpenRouter 是一个 LLM API 聚合服务平台。它的做法是把多家模型厂商的模型接口统一成一个 OpenAI 兼容的接口开发者只需要注册一个 OpenRouter 账号、申请一个 API Key就可以通过同一个 Base URL 调用不同厂商的模型例如 Anthropic 的 Claude、OpenAI 的 GPT 系列、Google 的 Gemini 系列、Meta 的 Llama 系列等等。在业务中引入 OpenRouter最大的价值不是“省一个账号”而是三点接入成本低只需要适配一套 OpenAI 风格的接口后续切换模型不需要改业务代码结构。模型替换灵活同一个接口里把参数 model 改掉就能从 Claude 换到 GPT 或其他模型。统一计费与用量所有模型在一个后台查看用量、余额和扣费明细方便做成本分析。正因为它处在“应用层”和“模型层”之间它的稳定性就受到两层因素影响。第一层是 OpenRouter 自己的网关、账户和限流系统第二层是上游模型厂商的接口稳定性。所以 OpenRouter 出现 Issues 时有可能问题出在它本身也有可能出在上游排查时需要先区分清楚。1.2 “OpenRouter Is Having Issues”的常见表现当你看到社区里有人说“OpenRouter Is Having Issues”通常会对应下面几种现象官方状态页亮起黄灯或红灯标记出 incident事件。请求返回 5xx尤其是 502、503、504。很多请求开始超时超时时间明显变长。原本正常的 API Key 突然返回 401 或 402但你的 Key 没有动过。请求频率稍微高一点就触发 429。某些具体模型不可用例如 Claude 系列临时下线或容量不足。Claude Code 使用 OpenRouter 接入时报错主模型和 small fast model 都请求失败。这些表现并不一定同时出现。有时候只是部分模型受影响有时候是整个平台变慢。后面我会按照“先确认服务状态再排查本地最后做容灾”的顺序给出一套系统化的应对方法。2. 先确认是不是 OpenRouter 的服务问题2.1 查看官方状态页遇到异常不要先改代码第一步应该是确认服务端是否正在发生故障。OpenRouter 提供了官方状态页地址是https://status.openrouter.ai。这个页面会列出各个核心服务的实时状态包括 API 可用性、模型路由、账户系统等。状态页一般会显示三种状态Operational正常。Degraded Performance服务可用但延迟升高或部分请求失败。Partial Outage / Major Outage部分服务或全部服务不可用。如果状态页显示当前有 incident那么你遇到超时、5xx 等问题大概率是服务端原因此时重点是“降级和等待”而不是反复重试同一个请求。如果状态页显示全部正常但你的请求仍然失败那就要把注意力放回本地环境比如网络连通性、API Key、请求参数和模型 ID。2.2 通过 curl 快速自测确认服务状态后可以用 curl 直接请求 OpenRouter 的基础接口来判断问题到底出在哪一层。先做一次最简单的模型列表请求export OPENROUTER_API_KEYsk-or-v1-你的key curl -sS https://openrouter.ai/api/v1/models \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -o models.json \ -w HTTP状态码: %{http_code}\n这条命令会把返回的模型列表保存到 models.json并在终端输出 HTTP 状态码。如果返回 200说明 OpenRouter 的网关和鉴权链路基本正常。如果返回 401说明 Key 有问题如果返回 5xx说明服务端异常。再检查一下当前 Key 的额度和使用情况curl -sS https://openrouter.ai/api/v1/key \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -o key.json \ -w HTTP状态码: %{http_code}\n这个接口在正常工作情况下会返回 Key 的标签、额度、已使用金额等信息。通过它可以快速判断是否因为余额不足导致 402。如果你在浏览器端能看到余额但在 API 层调用失败那这条命令能帮你确认是不是请求链路本身出了问题。如果想进一步解析返回内容可以配合 jqjq .data key.json jq .data[0].id models.json这里的思路是先用最简单的 GET 请求做连通性测试再逐层往里检查。不要一开始就去跑复杂的 Chat Completion 请求因为一旦失败你很难分清是模型路由问题、参数问题还是网关问题。2.3 区分本地问题与服务端故障在 OpenRouter 异常排查中很多开发者的第一反应是“我的代码写错了”但实际情况往往是服务端波动。这里有一个简单的判断流程如果 curl 请求 api/v1/models 已经是 5xx说明 OpenRouter 服务端异常。如果 curl 请求正常但你的项目代码请求失败检查项目里 Base URL 是否写错、API Key 是否真的被读取、网络环境是否一致。如果同一个模型 id 在浏览器 Playground 正常但在代码里失败检查请求参数例如 max_tokens 设置、temperature 范围、或 messages 格式是否符合要求。如果某个模型失败但其他模型正常说明问题大概率在上游模型供应商而不是 OpenRouter 全部故障。另外要注意OpenRouter 偶尔会在响应体里返回业务错误信息即使 HTTP 状态码是 200。最常见的场景是模型在流式输出中途因为上游超时而中断。所以排查时不仅要看状态码还要看 response body 和完整错误信息这个习惯在 AI 应用调试里非常重要。3. 常见错误码与系统性排查思路OpenRouter 采用 OpenAI 兼容的错误结构错误信息通常包含在 JSON 的 error 字段里。理解这些错误码能让你在服务异常时更快定位问题。3.1 401 与 402认证与配额问题401 Unauthorized 表示请求没有通过鉴权。常见原因是请求头里没有携带Authorization: Bearer xxx或者 Key 本身错误。排查时注意以下几点检查环境变量是否真的被加载很多项目在 .env 文件里写了 Key但没有安装 python-dotenv 或没有 source 配置。检查 Key 前后是否有多余空格、引号或换行符。检查是否误用了其他平台的 KeyOpenRouter 的 Key 通常以 sk-or-v1 开头。检查代码里是否有硬编码覆盖了环境变量。402 Payment Required 表示账户余额不足或当前 Key 没有可用额度。OpenRouter 是预付费模式账户余额用完后就无法调用付费模型。遇到 402优先到官网 Credits 页面查看余额并确认支付方式是否可用。不要轻信任何第三方“代充”或“成品 Key”这类 Key 来源不明随时可能被官方封禁也会带来资金安全风险。3.2 404模型 ID 找不到404 在 OpenRouter 场景里通常不是接口地址错了而是请求参数里的 model 不存在。OpenRouter 的模型 ID 是动态变化的社区里分享的某个模型 ID 可能过几天就下线、改名或者需要特定权限才能访问。例如有时你在别人的配置里看到一个类似stealth/ox-alpha的模型 ID但在自己的账号里怎么都找不到。这种情况最大的可能就是该模型 ID 已经变更、下线或者只对特定账号开放。正确做法是访问 OpenRouter 的 Models 页面搜索最新的模型 ID而不是死记社区里的旧配置。还要注意某些模型名在不同时期会有后缀变化例如版本号后缀、日期后缀等直接用旧 ID 往往会 404。3.3 429限流与配额触发429 Too Many Requests 是 OpenRouter 异常期间最常见的错误。触发原因有两类请求频率超过 OpenRouter 的速率限制。不同账号等级和套餐对应不同 RPM每分钟请求数和 TPM每分钟 Token 数。账户余额不足以支撑当前请求量OpenRouter 也会用 429 来限制消费防止产生超额费用。OpenRouter 在 429 响应中通常会附带重试时间提示常见的是响应头里的 Retry-After或响应体里的 metadata.retry_after_ms。它在错误 JSON 里的结构大致如下但字段可能随版本调整以实际响应为准{ error: { code: 429, message: Rate limit exceeded for request, metadata: { retry_after_ms: 5000 } } }遇到 429简单粗暴地原地重试意义不大应该使用指数退避策略。线程 sleep 固定 3 秒这种写法也不能算错但在高并发场景下会造成惊群效应。后面我会给出一个更规范的 Python 重试封装。3.4 5xx 与超时服务端故障5xx 错误说明 OpenRouter 或上游模型服务出现了故障。502 通常是上游模型返回错误503 通常表示服务暂时过载504 则表示网关超时。这类错误出现时业务代码如果继续高频重试反而会加剧服务端压力。超时问题则要区分两种情况。第一种是 OpenRouter 响应很慢超过了客户端超时时间第二种是模型本身生成很慢比如长文生成或长时间思考模型客户端设置 30 秒超时可能就不够。建议把连接超时和读取超时分开设置不要混在一起否则很难定位问题。下面这个错误速查表可以帮你快速对照处理错误码常见原因排查方向解决思路401API Key 无效或未携带检查请求头和 Key 来源重新生成 Key修正环境变量402余额不足到官网检查余额充值或更换可用 Key404模型 ID 不存在对照 Models 页面更新 model 参数429触发限流或配额查看响应头重试时间指数退避降低并发500/502/503服务端或上游故障查看官方状态页降级重试或切换模型504/超时网关超时或生成过慢检查超时参数和请求大小拉长超时拆分请求4. 代码层面的健康检查与重试实战4.1 使用 Python 调用 OpenRouter 的最小示例OpenRouter 的接口兼容 OpenAI SDK所以可以直接用 openai 库调用。下面是一个最小示例请求模型选用openai/gpt-4o-mini实际使用时以 OpenRouter 官方模型列表为准。# 文件路径demo_openrouter.py from openai import OpenAI client OpenAI( base_urlhttps://openrouter.ai/api/v1, api_keysk-or-v1-你的key, ) response client.chat.completions.create( modelopenai/gpt-4o-mini, messages[ {role: user, content: 用一句话介绍 OpenRouter} ], timeout60, ) print(response.choices[0].message.content)运行前先安装依赖pip install openai这个例子中有几个点需要注意。base_url 必须完整写成https://openrouter.ai/api/v1不能只写到域名否则 SDK 会按默认 OpenAI 地址请求。timeout 参数在 openai 1.x 版本里可以接受整数或元组生产环境建议设置成(10, 120)分别代表连接超时 10 秒、读取超时 120 秒这样可以把网络连接问题与模型生成慢的问题分开观察。4.2 带指数退避的重试封装在 OpenRouter 异常期间简单重试解决不了问题更需要“有节奏的重试”。这里用 Python 的 tenacity 库做演示它在 try 之外会等待一个指数增长的时间并且只在临时性错误上重试。# 文件路径openrouter_retry.py import time from openai import OpenAI from tenacity import ( retry, stop_after_attempt, wait_exponential, retry_if_exception_type, ) client OpenAI( base_urlhttps://openrouter.ai/api/v1, api_keysk-or-v1-你的key, ) class OpenRouterTemporaryError(Exception): OpenRouter 临时性错误适合重试。 retry( stopstop_after_attempt(5), waitwait_exponential(multiplier1, min2, max30), retryretry_if_exception_type(OpenRouterTemporaryError), reraiseTrue, ) def chat_once(messages): try: resp client.chat.completions.create( modelopenai/gpt-4o-mini, messagesmessages, timeout(10, 120), ) return resp.choices[0].message.content except Exception as e: status_code getattr(e, status_code, None) if status_code in (429, 502, 503, 504): # 这类错误可能只是暂时性过载可以重试 raise OpenRouterTemporaryError(str(e)) from e # 401、402、404 等属于不可恢复错误直接抛出 raise if __name__ __main__: result chat_once([ {role: user, content: 分别给我三个关于 Go 语言的面试题} ]) print(result)这段代码的核心在于不是所有错误都适合重试。401 说明 Key 不对重试一百次也一样404 说明模型 ID 写错了重试也找不到但是 429、502、503、504 属于临时性故障等待一段时间后可能恢复。wait_exponential会让重试间隔从 2 秒开始逐步拉长避免把你自己的应用打挂也给 OpenRouter 服务端留出恢复时间。从工程角度看重试次数不宜太多建议本地单次请求最多重试 3 到 5 次。如果重试了 5 次仍然失败应该直接失败并进入降级逻辑而不是无限循环。这个设计思路在 OpenRouter 异常期间尤其重要因为服务恢复可能需要几分钟甚至几小时。4.3 模型列表与余额接口的健康检查脚本除了代理层重试你还可以在项目里维护一个健康检查脚本定时探测 OpenRouter 的关键接口。这样当服务出现异常时你的监控系统能第一时间感知到不用等用户投诉。#!/usr/bin/env bash # 文件路径check_openrouter.sh set -euo pipefail API_KEY${OPENROUTER_API_KEY:-} if [ -z $API_KEY ]; then echo 缺少 OPENROUTER_API_KEY exit 2 fi HTTP_CODE$(curl -sS -o /tmp/openrouter_models.json \ -w %{http_code} \ https://openrouter.ai/api/v1/models \ -H Authorization: Bearer $API_KEY) if [ $HTTP_CODE 200 ]; then echo OpenRouter models 接口正常 exit 0 else echo OpenRouter models 接口异常http_code$HTTP_CODE exit 1 fi把这个脚本接入 cron、GitHub Actions 或者运维平台的定时任务每周或每天跑一次。如果 OpenRouter 正在发生大规模故障这个脚本会返回非零退出码你的告警系统就能收到通知。脚本里的检查逻辑比较简单你在实际项目里可以扩展为“连续 3 次失败才告警”避免单次抖动引起误报。5. Claude Code 接入 OpenRouter 的故障排查5.1 环境变量接入方式OpenRouter 不仅适合普通代码调用很多开发者还会把 OpenRouter 的 API Key 配置到 Claude Code 里让 Claude Code 通过 OpenRouter 使用不同模型。Claude Code 本身支持通过环境变量覆盖 API 地址和 Token。典型的配置方式是export ANTHROPIC_BASE_URLhttps://openrouter.ai/api/v1 export ANTHROPIC_AUTH_TOKENsk-or-v1-你的key export ANTHROPIC_MODELanthropic/claude-3.5-sonnet export ANTHROPIC_SMALL_FAST_MODELopenai/gpt-4o-mini claude这里的原理是Claude Code 默认请求 Anthropic 官方接口但当你配置了ANTHROPIC_BASE_URL它就会把请求发到自定义地址。OpenRouter 提供 Anthropic 兼容接口所以 Claude Code 才能通过这个方式使用 OpenRouter 接入模型。需要注意ANTHROPIC_MODEL的值必须和你在 OpenRouter Models 页面看到的 ID 完全一致。模型 ID 写错的话Claude Code 启动时会报模型不存在或者请求失败。把ANTHROPIC_SMALL_FAST_MODEL单独配置成一个便宜的小模型也能降低系统内部摘要等功能的成本。5.2 使用 cc-switch 切换供应商时的注意事项cc-switch 是一个开源的配置切换工具常用于在 Claude Code 或 Codex 的不同供应商配置之间快速切换。它做的事情本质上是修改 Claude Code 的配置文件把你选中的供应商的 Base URL、Token 等写入环境变量区。当你想通过 cc-switch 接入 OpenRouter 时真正生效的配置大致是下面这样但具体字段和文件路径会因 cc-switch 版本而异{ provider: { name: openrouter, type: claude, env: { ANTHROPIC_BASE_URL: https://openrouter.ai/api/v1, ANTHROPIC_AUTH_TOKEN: sk-or-v1-你的key } } }接入过程中最常见的问题是切换之后 Claude Code 仍然连接旧地址。这通常是因为 Claude Code 读取配置有缓存或者当前的 shell 环境里已经存在旧的 ANTHROPIC_BASE_URL 导出。切换配置后建议在新终端里执行env | grep ANTHROPIC检查环境变量是否已经更新再启动 Claude Code。5.3 Claude Code 使用 OpenRouter 时的常见故障Claude Code 通过 OpenRouter 接入时遇到服务异常的情况和普通 API 调用有些差异。下面几个现象值得留意启动时报 connection failed先检查ANTHROPIC_BASE_URL是否被正确设置再检查网络能否访问openrouter.ai。对话过程中突然报 401很可能是 OpenRouter 服务端临时异常导致鉴权链路故障或者 Key 因为余额问题被暂时禁用。先到官网确认 Key 状态。对话过程中出现内容截断这通常是上游模型或 OpenRouter 网关超时属于服务端问题可以稍后继续或在配置里把请求重试打开。模型列表里找不到某个模型例如配置了stealth/ox-alpha但对话时提示不存在那是因为模型 ID 已经不在官方列表中。你需要到 OpenRouter Models 页搜索最新 ID。如果你的 Claude Code 使用的是 OpenRouter 的 Anthropic 兼容接口当你看到 429 或 529 类错误时本质上和处理普通 API 一样核心策略是降低请求频率、稍后重试和切换备用模型。6. 服务异常时的降级与容灾方案6.1 配置多个模型作为互相备份OpenRouter 的优势是它聚合了很多模型所以当某个模型不可用或某个模型供应商服务异常时你可以快速切到另一个模型。日常开发中建议在配置中心维护两个以上的模型至少包含一个主模型和一个备用模型。例如主模型用anthropic/claude-3.5-sonnet备用模型用openai/gpt-4o-mini。在代码里写一个简单的降级逻辑PRIMARY_MODEL anthropic/claude-3.5-sonnet FALLBACK_MODEL openai/gpt-4o-mini def chat_with_fallback(messages): try: return chat_once(messages, modelPRIMARY_MODEL) except Exception as primary_error: print(f主模型失败{primary_error}切换到备用模型) return chat_once(messages, modelFALLBACK_MODEL)这里要注意主模型失败后是否继续调用备用模型取决于你的业务容忍度。如果是非核心的摘要、翻译类场景降级到便宜的小模型是可以接受的。如果是对逻辑推理要求很高的场景盲目降级到小模型可能导致回答质量明显下降这时应该直接抛错并进入人工处理流程而不是硬切模型。6.2 多 Provider 路由思路如果 OpenRouter 故障持续时间较长你可能需要考虑多 Provider 路由。思路是在代码里维护多个 Provider 信息每个 Provider 都有自己的 Base URL 和 Key。例如 Provider A 是 OpenRouterProvider B 是模型厂商官方接口。正常流量走 Provider A当连续 N 次请求失败时把流量切到 Provider B。这里不展开具体代码因为不同团队的 SDK 封装差别很大但核心设计原则是一样的供应商抽象成 Provider 接口调用方只依赖接口不依赖具体实现。从工程角度看多 Provider 路由不是越复杂越好。小团队维护一个简单的 failover 列表就够了核心是能够快速切换。引入过重的网关组件反而会增加运维成本甚至变成新的故障点。6.3 请求队列与熔断在 OpenRouter 异常期间直接拒绝新请求比把请求堆积在内存里更安全。生产环境建议实现简单的熔断逻辑如果连续 10 次请求都因为 5xx 或超时失败就打开熔断开关后续请求直接进入快速失败分支。熔断打开后每隔 30 秒尝试放行少量请求去探测服务是否恢复。服务恢复后关闭熔断恢复流量。这个机制在 OpenRouter 状态页还没有更新时能靠你的应用自身感知故障并保护你的后端服务不被拖垮。很多团队忽略这一点最后会在 OpenRouter 故障期间出现业务系统的雪崩因为大量请求阻塞在等待响应上数据库连接和线程池都被耗尽。7. 常见问题速查表问题现象常见原因解决思路请求返回 429请求频率超限或余额不足指数退避重试检查余额并优化并发请求返回 5xxOpenRouter 网关或上游模型故障查看官方状态页降级重试请求返回 401API Key 错误或未携带检查 Authorization 请求头和环境变量配置模型后提示 404模型 ID 不存在或已下线到 Models 页面查询最新 ID请求超时网络或模型生成过慢拆分连接超时和读取超时Claude Code 无法连接Base URL 配置失效或网络异常检查 env检查 key 状态模型 ID 找不到社区流传的 ID 已变更只使用官方列表中的 ID请求中途截断上游模型中断或网关超时适当重试降低单次请求长度这张表可以作为你在 OpenRouter 异常期间的排查入口。实际定位时先用 curl 确认接口返回再看官方状态页最后结合项目日志中的 request_id、model、status_code 等字段做判断。8. 工程最佳实践建议8.1 密钥与配置管理不要把 OpenRouter API Key 直接写在代码仓库里尤其是公开仓库。推荐做法是统一放在环境变量或配置中心并设置最小权限。一个账号可以生成多个 Key建议为不同项目创建独立的 Key这样某个 Key 泄露或异常时只需要吊销那一个不会影响全部业务。充值方面一定要通过 OpenRouter 官网 Credits 页面操作不要使用来路不明的代充渠道也不要购买二手 Key。这类 Key 轻则被封禁重则涉及资金安全问题。OpenRouter 的支付方式和可用地区可能会变化以官网展示为准不要在网络上轻信过时的充值教程。8.2 日志与可观测性在 OpenRouter 服务异常时好的日志是你排查问题的第一手资料。每次请求至少应该记录以下字段请求时间戳使用的模型 ID是否开启了流式输出HTTP 状态码错误码和错误消息本轮请求的耗时OpenRouter 返回的 request_id如果响应头里有有了这些日志你才能快速判断故障范围是所有模型都失败还是只有特定模型失败是网络超时还是 OpenRouter 返回了明确错误码。OpenRouter 本身也提供了用量后台你可以结合自己的日志和后台数据交叉验证。8.3 请求参数与重试边界给 OpenRouter 发请求时建议显式设置 timeout不要依赖 SDK 默认的无限等待。连接超时和读取超时分开设置避免模型生成时间长但网络正常时被误判为异常。重试只用于临时性错误不要对 401、402、404 做无意义重试。流式请求失败时客户端可能已经接收了一部分内容此时最简单的处理方式是整轮请求重试而不是尝试拼接断掉的内容。如果你的业务不允许重复生成需要在业务层面加上幂等标识。8.4 服务异常时的落地 Checklist最后整理一份可以贴在项目文档里的 Checklist确认 OpenRouter 官方状态页是否显示 incident。用 curl 请求 /api/v1/models 和 /api/v1/key 确认 API 层状态。查看项目日志中的 status_code 和错误消息区分临时错误与不可恢复错误。如果大量 429检查应用的并发和重试策略不要盲目调大并发。如果大量 5xx用备用模型或备用 Provider 降级。如果只是某个模型不可用通过配置中心快速切换模型 ID。服务恢复后观察一段时间再逐步恢复流量不要瞬间放量。OpenRouter 作为一个聚合服务它的故障并不可怕真正可怕的是应用层没有应对故障的机制。把状态检查、错误分类、重试策略和降级方案提前做好即使 OpenRouter 再次出现 Issues你的服务也能平稳度过。