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 多个模型。

三个步骤：

1. 获取一个 key。在 key 管理页面创建一个。OpenRouter key 以 `sk-or-` 开头，这能让工具识别出它正在与 OpenRouter 通信，而非直接与 OpenAI 通信。将其存储在环境变量中，不要写在源代码里。普通的 `sk-...` key 是 OpenAI key，无法进行路由。
2. 将 base URL 指向 `https://openrouter.ai/api/v1`。由于该 API 与 OpenAI 兼容，一旦你更换了这个值，官方的 OpenAI SDK 就能正常工作。
3. 以 `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 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

同一个 API 密钥适用于以下所有工具，因此一旦你拥有一个密钥，就无需为列表中的每个工具单独配置。终端智能体读取配置文件或环境变量；编辑器与扩展则在设置面板中进行配置。

工具	连接方式	设置方法
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 加上 API 密钥	指南
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 美元后，每日上限提升至 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 会记录我的代码或提示词吗？

不会，默认情况下不会记录，即使请求出错也不会，除非你明确选择加入。有一个可选加入的设置，用记录日志换取小幅度的使用折扣。详情请查看隐私政策。