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

- 来源：OpenRouter：Announcements（RSS）
- 发布时间：2026-06-16 23:00
- AIHOT 分数：65
- AIHOT 标记：精选
- AIHOT 链接：https://aihot.virxact.com/items/cmqitbwsh0466sl5wasknwx3f
- 原文链接：https://openrouter.ai/blog/tutorials/any-coding-agent

## 精选理由

如果你在 Cursor、Claude Code 和自定义代理之间来回切 API 密钥，这篇 OpenRouter 官方教程把设置统一成一个模式，读完就能把三四个工具连到同一个路由后端。

## AI 摘要

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 日

On this page

三种通用设置方法

哪些编程智能体和 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 会记录我的代码或提示词吗？

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