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 Key
4.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_KEY="sk-or-v1-xxxxxxxxxxxx" # Windows PowerShell $env:OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxx"为了方便后续代码调用，也可以写入.env文件：
OPENROUTER_API_KEY=sk-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": f"Bearer {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, json=payload, headers=headers, timeout=120) print(response.status_code) print(response.json())如果使用 curl：
curl -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 中配置 OpenRouter
cc-switch 的核心配置项有两个：
- API Base URL：
https://openrouter.ai/api/v1 - API Key：你在 OpenRouter 生成的 Key
在 cc-switch 中新建一个供应商，名称填OpenRouter，Base URL 填：
https://openrouter.ai/api/v1API Key 填：
sk-or-v1-xxxxxxxxxxxx部分版本还支持自定义请求头或模型列表，按需填写即可。
6.3 手动配置 Claude Code 环境变量
如果不使用 cc-switch，也可以直接手动配置环境变量。打开终端，设置：
export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1" export ANTHROPIC_AUTH_TOKEN="sk-or-v1-xxxxxxxxxxxx"然后启动 Claude Code：
claude启动后，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，充值 |
| 请求返回 401 | API 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_retries=5): url = "https://openrouter.ai/api/v1/chat/completions" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } for attempt in range(max_retries): response = requests.post(url, json=payload, headers=headers, timeout=120) if response.status_code == 200: return response.json() if response.status_code == 429: wait_time = 2 ** attempt * 1.5 print(f"429 限流，等待 {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, times=5): latencies = [] for _ in range(times): start = time.time() requests.post(url, json=payload, headers=headers, timeout=120) 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, model="meta-llama/llama-3.3-70b-instruct:free"): # 单条调用逻辑 return item items = list(range(20)) results = [] with ThreadPoolExecutor(max_workers=3) 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” 时，不要把所有鸡蛋放在一个篮子里，准备备用模型或官方直连渠道，比单纯等恢复更可靠。
