夜雨聆风
三种通用设置方法 哪些编程智能体和 AI 工具支持 OpenRouter 路由机制如何让你的智能体保持运行 使用 SDK 构建你自己的智能体 费用与速率限制 常见问题解答
OpenRouter 位于你的编程工具与它所调用的模型提供商之间。你的工具仍然发送请求。OpenRouter 通过单一 API key 处理提供商关系、模型目录、使用可见性、计费和路由。
当你使用多个工具、模型或提供商时，这一点就变得重要了。如果没有它，你需要为 OpenAI、Anthropic、谷歌以及其他所有提供商分别管理独立的 key、独立的计费面板和独立的配置路径。有了它，每个受支持的工具都使用同一个 `sk-or-...` key、同一个模型 slug 格式和同一个 base URL。
连接一个工具一次，你就可以通过编辑一个字符串来切换模型，在一个地方查看所有支出，并在某个提供商宕机时让智能体继续运行。以下是设置模式以及已经支持该模式的工具。
三种通用设置方法
任何支持 OpenAI Chat Completions API 的工具都可以与 OpenRouter 配合使用，因为 OpenRouter 暴露的是同一个 API。你只需更改两个值——base URL 和 key——然后选择一个模型，其余代码保持不变。这一个端点覆盖了 60 多个提供商的 300 多个模型。
三个步骤：
获取一个 key。在 key 管理页面创建一个。OpenRouter key 以 `sk-or-` 开头，这能让工具识别出它正在与 OpenRouter 通信，而非直接与 OpenAI 通信。将其存储在环境变量中，不要写在源代码里。普通的 `sk-...` key 是 OpenAI key，无法进行路由。 将 base URL 指向 `https://openrouter.ai/api/v1`。由于该 API 与 OpenAI 兼容，一旦你更换了这个值，官方的 OpenAI SDK 就能正常工作。 以 `provider/model` 形式选择一个模型 slug，例如 `openai/gpt-4o` 或 `anthropic/claude-sonnet-4`。切换模型时只需更改这个 slug。在 `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 osfrom openai import OpenAIclient = 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 OpenRouterimport oswith 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
同一个 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 美元后，每日上限提升至 1,000 次。不过在你依赖免费套餐之前，有两个注意事项：失败的尝试同样计入每日配额，并且热门免费模型在高峰时段可能会被上游供应商限制速率。即便如此，在推理上投入任何费用之前，它足以让你将一个智能体从端到端跑通。
在付费使用方面，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 美元额度，请求上限将提升至每天 1,000 次。
我可以在 VS Code 中使用 OpenRouter 吗？
可以。使用像 Cline 或 Kilo Code 这类暴露了 OpenRouter 提供商的智能体扩展，或者任何允许你设置自定义 OpenAI 基础 URL 的扩展。将基础 URL 设置为 `https://openrouter.ai/api/v1`，粘贴你的密钥，然后选择一个模型即可。
OpenRouter 使用什么样的模型 slug 格式？
格式为 `提供商/模型`，例如 `openai/gpt-4o` 或 `anthropic/claude-sonnet-4`。在作者名前加上 `~` 前缀，例如 `~anthropic/claude-sonnet-latest`，即可始终解析为该系列的最新版本。浏览完整列表请访问 `openrouter.ai/models`。
OpenRouter 会记录我的代码或提示词吗？
不会，默认情况下不会记录，即使请求出错也不会，除非你明确选择加入。有一个可选加入的设置，用记录日志换取小幅度的使用折扣。详情请查看隐私政策。
