如何用 OpenRouter 接入任意编码代理或 AI 工具
阅读原文· openrouter.ai如果你在 Cursor、Claude Code 和自定义代理之间来回切 API 密钥,这篇 OpenRouter 官方教程把设置统一成一个模式,读完就能把三四个工具连到同一个路由后端。
OpenRouter 提供统一 API 键(sk-or- 开头),兼容 OpenAI Chat API,可接入 300+ 模型和 60+ 供应商。用户只需将 base URL 改为 https://openrouter.ai/api/v1,设置 API 键,并指定模型 slug(如 openai/gpt-4o 或 anthropic/claude-sonnet-4)即可。同一键可直接用于 Claude Code、Codex CLI、Cursor、Cline 等编码代理与工具。其路由机制在供应商故障时自动切换,代理无需感知失败即可继续多步骤任务。OpenRouter 也提供 Python 和 TypeScript 原生 SDK。
如何在任何编程智能体或 AI 工具中使用 OpenRouter
OpenRouter · 2026 年 6 月 16 日
- 三种通用设置方法
- 哪些编程智能体和 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 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 会记录我的代码或提示词吗?
不会,默认情况下不会记录,即使请求出错也不会,除非你明确选择加入。有一个可选加入的设置,用记录日志换取小幅度的使用折扣。详情请查看隐私政策。