如何用 OpenRouter 接入任意编码代理或 AI 工具

• 三个通用设置技巧
• 哪些编程智能体和 AI 工具支持 OpenRouter
• 路由如何让你的智能体保持在线
• 使用 SDK 构建你自己的智能体
• 费用与速率限制
• 常见问题解答

OpenRouter 位于你的编程工具与其所调用的模型提供商之间。你的工具仍然负责发送请求。OpenRouter 则负责处理提供商关系、模型目录、使用情况可见性、计费和路由，所有这些都通过一个 API 密钥完成。

当你开始使用多个工具、模型或提供商时，这一点就变得至关重要。如果没有 OpenRouter，你需要为 OpenAI、Anthropic、Google 以及其他所有提供商分别管理各自的密钥、各自的计费面板和各自的配置路径。有了它，所有受支持的工具都使用同一个 sk-or-... 密钥、同一种模型 slug 格式和同一个 base URL。

只需连接一次工具，你就可以通过编辑一个字符串来切换模型，在一个地方查看所有支出，并且在某个提供商宕机时让智能体继续运行。下面是设置模式以及已经支持这种模式的工具。

三个通用设置技巧

任何支持 OpenAI Chat Completions API 的工具都能与 OpenRouter 配合使用，因为 OpenRouter 暴露的是同一套 API。你只需修改两个值——base URL 和密钥，然后选择一个模型，其余代码保持不变。这一个端点即可对接 60 多家服务商的 300 多个模型。

三步操作：

1. 获取密钥。在密钥页面创建一个即可。OpenRouter 密钥以 sk-or- 开头，工具据此识别它连接的是 OpenRouter 而非 OpenAI 本身。请将密钥存放在环境变量中，不要写进源代码。普通的 sk-... 密钥是 OpenAI 的密钥，无法路由。
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，无需设置 base 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 密钥适用于下面所有工具，因此你只需配置一次，即可为整个列表完成密钥配置。终端智能体读取配置文件或环境变量；编辑器和扩展则在设置面板中进行配置。

这份列表并不详尽。OpenRouter 同样支持 Claude Desktop、Junie CLI、OpenCode 以及 MCP 服务器。其模式始终如一：一个密钥、一个基础 URL、一个模型标识符（slug）。

路由如何让你的智能体保持“存活”

单一端点为你带来了路由能力，而这对智能体的重要性远超对一次性脚本的意义。

一次失败的 API 调用本身很容易处理。你捕获错误并重试即可。但一个执行多步骤任务的智能体则没那么宽容，因为它在多次调用之间保持着状态。中途发生的提供商故障可能导致编辑只应用了一半、工具调用从未返回结果，或者智能体将某个计划当作已完成来继续推理。当故障转移发生在底层的路由层时，智能体根本看不到这次失败。它拿到补全结果，继续运行。有两项机制承担这项工作，并且它们可以叠加使用。

自动提供商故障转移

这无需任何配置。某个模型通常由多家提供商提供服务，如果 OpenRouter 首先尝试的那家宕机或对你限流，它会将同一模型路由到另一家提供该服务的提供商。你只为成功落地的调用付费。

手动模型回退

这是你主动选择接入的一层。与备用供应商不同，你可以通过传入一个 models 数组来指定备用模型（使用 OpenAI SDK 时，放在 extra_body={"models": [...]} 中）。OpenRouter 会先尝试你的首选模型，然后按顺序依次尝试每个备用模型，并且只按实际运行的模型计费，该模型会返回在响应的 model 字段中。这覆盖了这样一种情况：某个模型背后只有一个供应商，而该供应商宕机了——正是在这种时候，供应商级别的故障转移无处可去。

如果你完全不想自己选择，Auto Router（openrouter/auto）会针对每条提示词挑选模型，把更简单的请求发给更便宜的模型，把更难的请求发给更强的模型。无论它选中哪个模型，你都按标准费率付费，不收取额外路由费用。在原型开发阶段、你还不知道哪个模型适合某项任务时，这个功能非常方便。

使用 SDK 构建你自己的智能体

如果你是在接入一个现有工具，上面的步骤就足够了。如果你要构建自己的智能体，OpenRouter 为你提供了两个 SDK。

Client 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 多个模型以 $0 价格运行，限制为每天 50 次请求、每分钟 20 次；一旦你充值 $10 积分，限额将提升至每天 1,000 次。在依赖它之前有两点需要注意。失败的尝试仍会计入每日配额，而且热门的免费模型在高峰时段可能会被上游提供商限流。即便如此，这足以让你在推理上花任何钱之前，把一个智能体端到端跑通。

在付费使用方面，OpenRouter 不对模型定价加价。你支付的每 token 费率与直接向提供商支付的相同，也就是模型目录中显示的价格。在此基础上，积分购买需支付 5.5% 的手续费，最低 $0.80。因此，你的推理成本保持在提供商的费率水平，而 OpenRouter 的收益就是这笔积分手续费。定价页面有当前数字，Activity 仪表板会实时显示每次请求的模型和费用，这是发现智能体在比任务所需更重的模型上消耗积分的最快方式。

常见问题解答

我是否需要为每个工具单独申请一个 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 base URL 的扩展。将 base URL 设置为 https://openrouter.ai/api/v1，粘贴你的密钥，然后选择一个模型即可。

OpenRouter 使用什么样的模型 slug 格式？

格式为 provider/model，例如 openai/gpt-4o 或 anthropic/claude-sonnet-4。在作者名前加上 ~ 前缀，如 ~anthropic/claude-sonnet-latest，即可始终解析到该系列中的最新版本。浏览完整列表请访问 openrouter.ai/models。

OpenRouter 会记录我的代码或提示词吗？