OpenRouter 最近状态页挂出 “Having Issues”不少依赖它做模型聚合调用的开发者当天就感受到了影响接口时报 429、某些模型在列表里消失、通过 cc-switch 把 OpenRouter 接到 Claude Code 后对话中断。这篇文章不绕弯直接梳理 OpenRouter 的核心能力、注册充值、API 调用、Claude Code 接入以及遇到 “Having Issues” 时该怎么定位和恢复。先说结论OpenRouter 是当前比较省事的 LLM API 聚合网关用一个 Key 就能调用几十家模型服务商的模型支持按量计费、免费模型、统一接口格式。它适合做多模型对比、Claude Code 切换供应商、批量任务接入也适合不想为每个模型单独注册账号的开发者。但因为是聚合网关它的问题通常不是单一模型的问题而是路由、额度、限流或模型下架引起的排查思路要按这个方向走。本文会从核心能力、适用场景、账号准备、API 调用、cc-switch 接入 Claude Code、常见故障排查、成本控制几个方面展开。所有命令和配置都给出可直接复制的版本但具体参数需要按你自己的 Key、模型名和网络环境调整。1. OpenRouter 核心能力速览能力项说明项目类型多模型 LLM API 聚合网关核心功能统一 API 调用多厂商模型、免费模型、模型路由、按量计费调用方式OpenAI 兼容的 Chat Completions 接口也支持 Anthropic 接口格式主要模型范围开源模型Llama、Qwen、DeepSeek、闭源模型Anthropic、OpenAI、Google 等视上架情况而定免费模型部分模型标注:free可零成本试用计费方式按 token 计费预充值后使用支持多种支付渠道API Key 管理网页端生成可设置额度、可轮换接入客户端Claude Code、Cline、Continue、自研脚本等批量任务支持但需注意速率限制和并发策略稳定性依赖上游模型供应商和各节点状态偶发 “Having Issues”适合场景多模型对比、Claude Code 供应商切换、API 批量调用、低成本原型验证需要注意OpenRouter 是一个平台不是模型本身。任何“模型不能用”“模型变慢”“模型消失”的问题都要先分清是 OpenRouter 平台故障、上游供应商故障还是你自己的 Key/网络/额度问题。2. 适用场景与使用边界2.1 适合谁OpenRouter 最适合的是“模型选择困难症”的开发者和团队。你需要对比不同模型的输出质量但又不想在每个模型服务商那里单独开户、单独管理 Key这时候用聚合 API 能省掉不少重复工作。尤其是 Claude Code 这类客户端它默认只支持 Anthropic 官方接口通过 OpenRouter 可以快速切到其他 Anthropic 兼容模型或第三方模型改一下环境变量就能切换。2.2 不适合什么场景如果业务要求极低延迟、极高稳定性、严格的数据不出域那 OpenRouter 这类第三方聚合网关不是首选。中间多一层路由延迟会略高故障点也会增加。另外如果你的场景长期只用一个模型直接在官方渠道开 Key 往往更便宜也更稳定。2.3 合规与安全边界使用 OpenRouter 时要注意三点账号和 Key 不要泄露到公开仓库避免被恶意盗刷。通过 API 上传的文本、文件要遵守模型服务商的隐私政策敏感数据不要走未加密的公网 API。生成内容的版权归属、商用范围要看你实际调用的上游模型协议OpenRouter 本身不改变版权条款。涉及人脸、声音、版权素材、个人隐私数据的功能更要确认上游模型的处理规则做到合法授权、合规使用。3. 环境准备与前置条件OpenRouter 是纯云端服务不需要本地显卡和模型文件但对网络环境、开发工具和客户端版本有一定要求。3.1 基础条件项目要求网络能正常访问 OpenRouter 官网和 API 域名国内网络环境下时延可能偏高需先确认连通性账号需注册 OpenRouter 账号并生成 API Key余额调用付费模型需要余额免费模型不需要客户端使用 Claude Code 需要安装 Node.js 18 并安装 Claude Code CLI工具使用 cc-switch 需要下载对应桌面端或命令行工具开发语言Python / Node.js 均可取决于你的调用方式3.2 网络连通性检查很多用户遇到的“OpenRouter 用不了”先从网络连通性排查。在命令行执行curl -I https://openrouter.ai/api/v1/models如果长时间无响应或报连接失败说明当前网络到 OpenRouter 不通或存在代理/防火墙干扰。如果返回200 OK说明网络正常继续查 Key、额度和模型状态。3.3 安装 Claude Code如果准备接入Claude Code 是 Anthropic 推出的终端编程助手支持通过环境变量替换 API 地址。安装命令npm install -g anthropic-ai/claude-code安装完成后确认版本claude --version如果安装失败检查 Node.js 版本和 npm 源配置。国内服务器如果 npm 下载慢可以临时切换 npm 镜像源但要注意镜像源的同步延迟。4. 注册、充值、获取 API Key4.1 注册账号打开 OpenRouter 官网用邮箱或 Google/GitHub 账号注册。注册后进入 Dashboard可以看到可用余额、使用记录和 API Key 管理入口。4.2 充值方式OpenRouter 的充值入口在 Billing 页面。官方支持的支付渠道会随地区和时间变化常见的是信用卡、借记卡。也有部分用户通过虚拟信用卡或第三方支付渠道完成充值但这类方式不稳定且有支付风险建议优先使用官方页面列出的支付方式。这里特别提醒任何充值操作都要在 OpenRouter 官网的 Billing 页面完成不要轻信“代充”“低价Key”等渠道防止账号被盗和资金损失。4.3 生成 API Key在 Dashboard 的 Keys 页面点击创建 Key可以设置名称、额度上限和过期时间。创建后只显示一次建议立即复制并保存到本地密码管理器。# 设置环境变量macOS / Linux export OPENROUTER_API_KEYsk-or-v1-xxxxxxxxxxxx # Windows PowerShell $env:OPENROUTER_API_KEYsk-or-v1-xxxxxxxxxxxx为了方便后续代码调用也可以写入.env文件OPENROUTER_API_KEYsk-or-v1-xxxxxxxxxxxx注意不要把.env文件提交到 Git 仓库建议加入.gitignore。5. OpenRouter API 调用示例OpenRouter 的 API 兼容 OpenAI 格式base_url 是https://openrouter.ai/api/v1。官方文档中chat/completions是核心接口。下面给出 Python 和 curl 两种示例。5.1 获取模型列表先检查自己能看到哪些模型特别是状态curl https://openrouter.ai/api/v1/models \ -H Authorization: Bearer $OPENROUTER_API_KEY返回 JSON 中会包含模型 ID、名称、上下文长度、价格、是否免费等信息。如果某个模型找不到先确认它是否在列表中以及是否被下架或临时隐藏。5.2 调用对话接口使用 Python 调用import requests API_KEY sk-or-v1-xxxxxxxxxxxx url https://openrouter.ai/api/v1/chat/completions headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } payload { model: meta-llama/llama-3.3-70b-instruct:free, messages: [ {role: user, content: 用一句话介绍 OpenRouter} ], max_tokens: 200, temperature: 0.7, } response requests.post(url, jsonpayload, headersheaders, timeout120) print(response.status_code) print(response.json())如果使用 curlcurl -X POST https://openrouter.ai/api/v1/chat/completions \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -H Content-Type: application/json \ -d { model: meta-llama/llama-3.3-70b-instruct:free, messages: [ {role: user, content: 用一句话介绍 OpenRouter} ], max_tokens: 200 }请求成功时返回的 JSON 和 OpenAI 格式几乎一致{ id: gen-xxxx, model: meta-llama/llama-3.3-70b-instruct:free, choices: [ { role: assistant, message: { content: OpenRouter 是一个统一的多模型 API 平台。, role: assistant } } ], usage: { prompt_tokens: 20, completion_tokens: 30, total_tokens: 50 } }5.3 使用 Anthropic 格式调用OpenRouter 还支持部分 Anthropic 兼容接口。如果你的客户端只认 Anthropic 格式可以把https://openrouter.ai/api/v1作为ANTHROPIC_BASE_URL把 OpenRouter 的 Key 作为ANTHROPIC_AUTH_TOKEN。这种配置方式在 Claude Code 中很常见。5.4 免费模型与令牌使用模型 ID 带:free后缀的表示免费模型。例如meta-llama/llama-3.3-70b-instruct:free这类开源模型经常出现在免费列表里。免费模型通常有每分钟请求数RPM和每日请求数限制并发较高时会返回 429。不要把免费模型用于生产环境只建议做功能验证。6. 通过 cc-switch 将 OpenRouter 接入 Claude Code网络热词里频繁出现 “cc-switch”它是一个用于切换 Claude Code 供应商/API 地址的图形化工具。使用它可以把 Claude Code 的默认 Anthropic 接口切换到 OpenRouter从而使用 OpenRouter 上的模型。6.1 安装 cc-switch具体安装方式以项目 README 为准常见方式是通过 npm 或 Release 包安装。这里以 npm 方式示例npm install -g cc-switch如果项目提供桌面版安装包也可以直接下载运行。安装完成后启动界面里可以新增供应商。6.2 在 cc-switch 中配置 OpenRoutercc-switch 的核心配置项有两个API Base URLhttps://openrouter.ai/api/v1API Key你在 OpenRouter 生成的 Key在 cc-switch 中新建一个供应商名称填OpenRouterBase URL 填https://openrouter.ai/api/v1API Key 填sk-or-v1-xxxxxxxxxxxx部分版本还支持自定义请求头或模型列表按需填写即可。6.3 手动配置 Claude Code 环境变量如果不使用 cc-switch也可以直接手动配置环境变量。打开终端设置export ANTHROPIC_BASE_URLhttps://openrouter.ai/api/v1 export ANTHROPIC_AUTH_TOKENsk-or-v1-xxxxxxxxxxxx然后启动 Claude Codeclaude启动后Claude Code 会把所有原生 Anthropic 模型请求发到 OpenRouter。OpenRouter 会把请求路由到对应的上游模型。如果 OpenAI 或第三方模型不支持 Anthropic 的某些参数可能会报错或返回异常这是正常现象需要换用兼容性更好的模型或调整 Claude Code 配置。6.4 切换后若模型找不到怎么办有用户反馈“在 OpenRouter API 配置后找不到 stealth/ox-alpha 这个模型”。这种情况说明你正在尝试使用的模型并未在 OpenRouter 的模型列表公开上架或者该模型 ID 是临时测试地址仅对特定账号生效也可能是已经下架。处理方式如下先调用模型列表接口确认模型 ID 是否存在。在 OpenRouter 官网模型页面搜索该模型确认上架状态。如果模型没有被公开列出说明该 ID 无法直接访问需要更换等价公开模型。检查 cc-switch 或 Claude Code 中配置的模型名是否拼写正确不要带多余空格。7. 常见问题与排查方法这里汇总 OpenRouter 使用中最高频的问题以及对应的排查思路。问题现象可能原因排查方式解决方案状态页显示 “Having Issues”OpenRouter 平台或上游供应商异常查看状态页更新、调用日志等待恢复切换到备用模型或官方直连API 返回 429触发速率限制或余额不足查看响应头、错误消息、账户余额降低请求频率增加 retry充值请求返回 401API Key 无效或过期检查 Key 是否复制完整、是否过期重新生成 Key请求返回 402 / 403余额不足或账号被限制查看 Billing 和账户状态充值联系官方支持模型列表找不到某个模型模型被下架、拼写错误、未公开查询官方模型列表、搜索模型 ID更换可用模型 ID调用报 400 Bad Request参数不兼容、模型不支持某些参数查看返回错误信息修改参数或换用其他模型连接超时网络不通、服务不稳定curl 测试连通性、换网络更换网络环境或等待恢复响应很慢上游模型负载高、路由延迟对比不同模型耗时换更快的模型或使用官方直连Claude Code 接入 OpenRouter 后不工作模型不支持 Anthropic 格式、模型名错误查看 Claude Code 日志、API 响应使用 Anthropic 官方模型或兼容模型免费模型突然不可用免费额度用尽、模型下架查看模型详情换其他免费模型或付费模型7.1 429 错误详细处理429 是 OpenRouter 使用中最常见的错误。OpenRouter 会基于账号、模型、IP 做速率限制。处理思路import time import requests def call_with_retry(payload, max_retries5): url https://openrouter.ai/api/v1/chat/completions headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } for attempt in range(max_retries): response requests.post(url, jsonpayload, headersheaders, timeout120) if response.status_code 200: return response.json() if response.status_code 429: wait_time 2 ** attempt * 1.5 print(f429 限流等待 {wait_time:.1f}s 后重试) time.sleep(wait_time) continue response.raise_for_status() return None重试时要配合指数退避不要立刻用 1ms 间隔去猛刷否则会被更严格限制。7.2 模型找不到的处理调用/api/v1/models后用 Python 过滤关键字import requests import json response requests.get(https://openrouter.ai/api/v1/models) models response.json().get(data, []) for model in models: model_id model.get(id, ) if stealth in model_id.lower() or ox-alpha in model_id.lower(): print(model_id)如果输出为空说明该模型不在公开列表中。7.3 “Having Issues”时如何降低影响当 OpenRouter 状态页显示不稳定时建议采用以下降级策略准备两个备用模型一个开源免费模型一个付费稳定模型。在代码里实现 fallback主模型失败后自动切换备用模型。在本地或服务器监控 API 可用率发现连续失败就切换。对关键业务直接使用模型官方 API不依赖聚合网关。8. 资源消耗与性能观察8.1 Token 消耗统计OpenRouter 按 token 计费使用记录在 Dashboard 中可以看到每个请求的 token 和费用。建议在代码中记录 usage 字段便于核对账单{ prompt_tokens: 1200, completion_tokens: 800, total_tokens: 2000 }8.2 延迟观察聚合网关本身会增加一层网络转发延迟通常在几百毫秒到几秒不等。测试一个模型的延迟时可以多次请求取平均值import time import statistics def measure_latency(url, headers, payload, times5): latencies [] for _ in range(times): start time.time() requests.post(url, jsonpayload, headersheaders, timeout120) latencies.append(time.time() - start) return statistics.mean(latencies), statistics.stdev(latencies)需要关注的是 p95 延迟而不仅仅是平均值。偶发超时在聚合网关中很常见。8.3 批量任务和并发控制批量调用时不要一次性开几十个并发。OpenRouter 对单账号的并发有限制超额后直接 429。合理的批量策略是from concurrent.futures import ThreadPoolExecutor, as_completed import time def process_item(item, modelmeta-llama/llama-3.3-70b-instruct:free): # 单条调用逻辑 return item items list(range(20)) results [] with ThreadPoolExecutor(max_workers3) as executor: future_to_item {executor.submit(process_item, item): item for item in items} for future in as_completed(future_to_item): try: result future.result() results.append(result) except Exception as e: print(f任务失败: {e}) time.sleep(0.5) # 避免瞬时并发过高建议单线程并发限制在 2-3 个批量任务中间加小延迟配合失败重试。8.4 额度控制为避免一个死循环把余额刷光建议在 OpenRouter Key 上设置月度额度限制同时在代码里记录累计 token 消耗超过阈值就停止调用。9. 最佳实践与使用建议9.1 第一次使用从小流量开始不要直接在长文本、大批量任务中测试 OpenRouter。先调一个短 prompt确认返回正常再看响应耗时和 token 用量。稳定后再逐步增加任务量。9.2 建立模型白名单OpenRouter 的模型列表会经常变化建议在代码里维护一份模型白名单避免因为模型下架导致任务中断。对关键模型提前测试自动切换逻辑。9.3 日志和监控每次请求都要记录时间、模型、token、状态码、耗时。批量任务尤其需要。可以使用 JSON 日志每行一条方便后续分析{timestamp: 2025-01-01T12:00:00Z, model: xxx, status: 200, latency: 1.2, tokens: 150}9.4 接口服务限制访问范围如果你构建了自己的代理服务把 OpenRouter Key 封装在后端前端不要直接暴露 Key。服务层面加 IP 白名单、访问频率限制和用户鉴权。9.5 数据安全提醒不要通过 OpenRouter API 发送未脱敏的个人信息、商业机密或受版权保护的数据。所有数据都经过第三方平台和上游模型处理敏感场景请确认数据合规性。9.6 定期检查账单OpenRouter 支持设置每月配额建议开启。每次充值不要充太多防止 Key 泄露导致大额损失。如果发现异常调用立即在 Dashboard 吊销 Key 并重新生成。10. 总结与下一步OpenRouter 是一个低成本、多模型接入的 API 聚合平台对个人开发者和中小团队很友好。它最大的价值是“一个 Key 试遍所有模型”尤其是在 Claude Code 这类工具中通过 cc-switch 或环境变量就能切换供应商。最容易踩的坑集中在三处一是网络不通导致请求超时二是模型 ID 写错或在官方列表失效三是触发速率限制后没有做退避重试。建议新用户先完整跑通一次/api/v1/models再选一个:free免费模型完成首次对话最后再考虑充值接入 Claude Code。如果接下来要做生产级接入优先关注稳定性配置多模型 fallback、限制并发、记录 tokens、设置月度限额。OpenRouter 状态页出现 “Having Issues” 时不要把所有鸡蛋放在一个篮子里准备备用模型或官方直连渠道比单纯等恢复更可靠。