OpenRouter 位于你的编程工具与其调用的模型提供商之间。你的工具仍然发送请求。OpenRouter 负责处理提供商关系、模型目录、使用情况可见性、计费以及路由，所有这些都通过一个 API 密钥完成。
当你使用多个工具、模型或提供商时，这一点就变得至关重要。没有它，你需要为 OpenAI、Anthropic、Google 以及其他所有提供商分别管理独立的密钥、独立的计费面板和独立的配置路径。有了它，所有受支持的工具都使用同一个 sk-or-... 密钥、同一个模型标识符格式以及同一个基础 URL。
只需连接一次工具，你就可以通过编辑一个字符串来切换模型，在一个地方查看所有支出，并在某个提供商宕机时保持智能体继续运行。以下是设置模式以及已经支持该模式的工具。
三种通用设置方法
任何支持 OpenAI Chat Completions API 的工具都可以与 OpenRouter 配合使用，因为 OpenRouter 暴露的是相同的 API。你只需更改两个值——基础 URL 和密钥，然后选择一个模型，其余代码保持不变。这一个端点即可对接 60 多家提供商的 300 多个模型。
三个步骤：
- 获取密钥。在你的密钥页面创建一个。OpenRouter 密钥以 sk-or- 开头，工具据此知道它正在与 OpenRouter 而非 OpenAI 直接通信。将其存储在环境变量中，而不是源代码中。普通的 sk-... 密钥是 OpenAI 密钥，无法进行路由。
- 将基础 URL 指向 https://openrouter.ai/api/v1。由于该 API 与 OpenAI 兼容，一旦你替换了这个值，官方的 OpenAI SDK 就可以正常工作。
- 以 提供商/模型 的形式选择模型标识符，例如 openai/gpt-4o 或 anthropic/claude-sonnet-4。切换模型时，你只需要更改这个标识符。浏览目录请访问 openrouter.ai/models。
大多数工具将这些设置放在不同的位置——环境变量、配置文件或设置界面——但这些值在任何地方都是相同的。以下是三种方式调用同一个接口。
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-4",
"messages": [{"role": "user", "content": "Refactor this function."}]
}'import os
from openai import OpenAI
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
)
resp = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Refactor this function."}],
)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://openrouter.ai/api/v1",
apiKey: process.env.OPENROUTER_API_KEY,
});
const resp = await client.chat.completions.create({
model: "anthropic/claude-sonnet-4",
messages: [{ role: "user", content: "Refactor this function." }],
});这两者都使用 OpenAI SDK，而大多数项目已经安装了该 SDK。OpenRouter 也提供了自己的 SDK，无需设置基础 URL 即可进行同样的调用：Python 版使用 openrouter，TypeScript 版使用 @openrouter/sdk。
from openrouter import OpenRouter
import os
with OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"]) as client:
resp = client.chat.send(
model="anthropic/claude-sonnet-4",
messages=[{"role": "user", "content": "Refactor this function."}],
)import { OpenRouter } from "@openrouter/sdk";
const client = new OpenRouter({
apiKey: process.env.OPENROUTER_API_KEY,
});
const resp = await client.chat.send({
model: "anthropic/claude-sonnet-4",
messages: [{ role: "user", content: "Refactor this function." }],
});两个可选标头，HTTP-Referer 和 X-Title，可让你标记自己的应用，使其显示在 OpenRouter 的排行榜中。对于成功的请求，两者都不是必需的。详情请参见应用归属说明。
哪些编程智能体和 AI 工具支持 OpenRouter
同一个密钥适用于以下所有工具，因此一旦你拥有一个密钥，就完成了整个列表的配置。终端智能体读取配置文件或环境变量；编辑器和扩展则在设置面板中进行配置。
| 工具 | 连接方式 | 设置 |
|---|---|---|
| Claude Code（Anthropic 的终端智能体） | 环境变量，通过 OpenRouter 的 Anthropic 兼容端点 | 指南 |
| Codex CLI（OpenAI 的开源终端智能体） | ~/.codex/config.toml，设置 model_provider = "openrouter" | 指南 |
| OpenClaw（开源智能体，原名 Moltbot/Clawdbot） | ~/.openclaw/openclaw.json，或设置 OPENROUTER_API_KEY | 指南 |
| Hermes Agent（Nous Research 的开源 CLI 智能体） | ~/.hermes/config.yaml，密钥存放在 ~/.hermes/.env 中 | 指南 |
| Cursor（AI 代码编辑器） | 应用内设置：自定义 OpenAI 基础 URL 加密钥 | 指南 |
| Cline（VS Code 智能体扩展） | 扩展设置：OpenRouter 提供商 | 页面 |
| Kilo Code（VS Code 智能体扩展） | 扩展设置：OpenRouter 提供商 | 页面 |
| SillyTavern（本地优先的聊天前端） | 连接设置：OpenRouter API | 页面 |
这个列表并非详尽无遗。OpenRouter 同样适用于 Claude Desktop、Junie CLI、OpenCode 以及 MCP 服务器。模式始终如一：一个密钥，一个基础 URL，一个标识符。
路由如何让你的智能体保持运行
单一端点为你带来了路由功能，而这对智能体来说，比对一次性脚本更为重要。
一次失败的 API 调用本身很容易处理：你捕获错误然后重试。但一个执行多步骤任务的智能体就没那么好说话了，因为它会在多次调用之间保持状态。中途发生的供应商故障可能导致编辑只应用了一半、某个工具调用从未返回结果、或者智能体现在基于一个它以为已经完成的计划进行推理。当故障转移发生在路由层时，智能体根本看不到这次失败。它拿到结果后继续运行。有两种机制负责完成这项工作，并且它们可以叠加使用。
自动供应商故障转移
这无需任何配置。一个给定的模型通常由多个供应商提供服务，如果 OpenRouter 首先尝试的那个供应商宕机或对你进行限流，它会将同一个模型路由到提供该服务的另一个供应商。你只需为实际成功的调用付费。
手动模型回退
这是你可以选择加入的层级。你不是指定备用供应商，而是通过传递一个 models 数组（使用 OpenAI SDK 时，放在 `extra_body={"models": [...]}` 中）来指定备用模型。OpenRouter 会先尝试你的首选模型，然后按顺序尝试每个回退模型，并按照实际运行的模型向你收费，该信息会在响应的 model 字段中返回。这涵盖了这样一种情况：某个模型背后只有一个供应商，而该供应商宕机了——这正是供应商级别的故障转移无处可路由的情况。
如果你根本不想做选择，自动路由器（openrouter/auto）会为每个提示词挑选一个模型，将简单的请求发送给更便宜的模型，将更难的请求发送给更强的模型。你只需为其选择的模型支付标准费率，无需额外路由费用。在原型设计阶段，在你还不确定哪个模型适合某项任务时，这非常方便。
使用 SDK 构建你自己的智能体
如果你正在接入一个现有工具，上述步骤就足够了。如果你正在构建自己的智能体，OpenRouter 为你提供了两个 SDK。
客户端 SDK（适用于 TypeScript 和 Python）是一个轻量级的、类型安全的 REST API 封装层，它提供了生成的类型和自动补全功能，而无需手动编写 HTTP 代码。
Agent SDK 会替你运行这个循环。它通过一个单一的 callModel 原语来管理多轮对话、执行你的工具并追踪状态。由于你可以在不同轮次之间切换模型，因此在同一个循环内，像读取文件这样的廉价步骤可以路由到便宜的模型，而代码生成则交给更强的模型。
下面是一个使用工具的调用示例。这一次 callModel 调用会发送提示词，让模型调用 get_weather，运行该工具，将结果反馈回去，并返回最终的文本。
import { callModel, tool } from "@openrouter/agent";
import { z } from "zod";
const weatherTool = tool({
name: "get_weather",
description: "Get the current weather for a location",
inputSchema: z.object({ location: z.string() }),
execute: async ({ location }) => ({ temperature: 72, condition: "sunny", location }),
});
const result = await callModel({
model: "anthropic/claude-sonnet-4",
messages: [{ role: "user", content: "What is the weather in San Francisco?" }],
tools: [weatherTool],
});
const text = await result.getText();费用与速率限制
OpenRouter 提供免费套餐。有 20 多个模型可以免费使用，每日限制 50 次请求，每分钟限制 20 次；一旦你充值 10 美元积分，每日上限会提升至 1000 次。在你依赖免费套餐之前，有两个注意事项：失败的尝试仍然会计入每日配额，而且热门的免费模型在高峰时段可能会被上游供应商限制速率。即便如此，在你为推理付费之前，这些免费额度也足以将一个智能体完整跑通。
在付费使用方面，OpenRouter 不会对模型定价加价。你支付的每个 token 费率与直接向供应商支付的费率相同，也就是模型目录上显示的价格。在此基础上，购买积分会收取 5.5% 的手续费，最低 0.80 美元。因此，你的推理费用保持供应商原价，OpenRouter 的收益来自这笔积分手续费。定价页面有当前的具体数字，活动仪表盘会实时显示每次请求所用的模型和费用，这是发现智能体在比任务需求更重的模型上浪费积分的最快方式。
常见问题
每个工具都需要单独的 API 密钥吗？
不需要。一个 OpenRouter 密钥可以用于此列表中的所有工具。在 openrouter.ai/keys 生成一次，然后将同一个 sk-or-... 值粘贴到 Claude Code、Codex CLI、Cursor 或任何其他受支持的工具中。
OpenRouter 能与 OpenAI SDK 配合使用吗？
可以。将 base_url（Python）或 baseURL（TypeScript）指向 https://openrouter.ai/api/v1，并传入你的 OpenRouter 密钥即可。OpenRouter 是 OpenAI Chat API 的直接替代品，因此官方 SDK 无需任何其他更改即可使用。
如何免费使用 OpenRouter？
使用免费模型并保持在免费额度内。免费模型，即模型页面上的 `:free` 变体，每天最多可运行 50 次请求，一旦你充值 10 美元额度，请求次数将提升至每天 1000 次。
我可以在 VS Code 中使用 OpenRouter 吗？
可以。使用像 Cline 或 Kilo Code 这类暴露了 OpenRouter 提供商的智能体扩展，或者任何允许你设置自定义 OpenAI 基础 URL 的扩展。将基础 URL 设置为 `https://openrouter.ai/api/v1`，粘贴你的密钥，然后选择一个模型。
OpenRouter 使用什么样的模型标识符格式？
格式为 提供商/模型，例如 `openai/gpt-4o` 或 `anthropic/claude-sonnet-4`。在作者名前加上 `~`，例如 `~anthropic/claude-sonnet-latest`，以始终解析为该系列中的最新版本。在 openrouter.ai/models 浏览完整列表。