一把密钥接通所有编程智能体：OpenRouter 通用接入模式与八款工具配置对照

星海拾光AI 前沿📡 觉醒AI2026-09-181010 阅读💛 91 收藏

一句话结论

OpenRouter 通用接入模式

OpenRouter 暴露与 OpenAI Chat Completions 完全兼容的单一端点，任何支持自定义基础 URL 的 AI 工具只需两处改动即可接入：基础 URL 改为 https://openrouter.ai/api/v1，密钥换成 sk-or- 开头的 OpenRouter 密钥。接入后一把密钥调度 70+ 供应商的 300+ 模型，换模型只改一个字符串，全部消费集中在一张账单，供应商故障时智能体会话不中断。本文覆盖通用接入三步、八款主流工具的配置位置、双层故障转移原理和自建智能体的 SDK 路径。

通用三步接入法

任何能对接 OpenAI Chat Completions API 的工具都能配合 OpenRouter 工作，因为 OpenRouter 暴露的就是同一套 API。改两个值——基础 URL 和密钥——再选一个模型，其余代码原样保留。这一个端点背后是 70+ 供应商的 300+ 模型。

三步操作如下。

第一步，获取密钥。在密钥页面创建，OpenRouter 密钥以 sk-or- 开头，工具据此识别对端是 OpenRouter 而非 OpenAI。密钥存环境变量，不要进源码；sk- 开头的普通密钥是 OpenAI 密钥，不会被路由。

第二步，把基础 URL 指向 https://openrouter.ai/api/v1。因为 API 兼容 OpenAI，官方 OpenAI SDK 换这一个值就能用。

第三步，选模型 slug，格式为 供应商/模型，如 openai/gpt-4o 或 anthropic/claude-sonnet-4。切换模型时唯一要改的就是这个字符串。完整目录在 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，多数项目已预装。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 排行榜上显示；对请求能否成功不是必需项。

八款工具的配置对照

同一把密钥在下列所有工具通用，配置一次即完成全部工具的供给。终端智能体读配置文件或环境变量，编辑器和扩展在设置面板里配置。

工具	连接方式	配置位置
Claude Code（Anthropic 终端智能体）	环境变量，走 OpenRouter 的 Anthropic 兼容端点	官方指南
Codex CLI（OpenAI 开源终端智能体）	`~/.codex/config.toml` 设 `model_provider = "openrouter"`	官方指南
OpenClaw（开源智能体）	`~/.openclaw/openclaw.json` 或 `OPENROUTER_API_KEY`	官方指南
Hermes Agent（开源 CLI 智能体）	`~/.hermes/config.yaml`，密钥放 `~/.hermes/.env`	官方指南
Cursor（AI 代码编辑器）	应用内设置自定义 OpenAI 基础 URL 加密钥	官方指南
Cline（VS Code 智能体扩展）	扩展设置选 OpenRouter 供应商	官方页面
Kilo Code（VS Code 智能体扩展）	扩展设置选 OpenRouter 供应商	官方页面
SillyTavern（本地聊天前端）	连接设置选 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+ 模型零费用，限制每日 50 次、每分钟 20 次，充值 10 美元后升至每日 1000 次。依赖免费档前注意两点：失败尝试同样计入每日配额；热门免费模型在高峰期可能被上游供应商限流。即便如此，在花一分推理费之前把一个智能体完整跑通一遍是够用的。

付费侧 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 美元升至每日 1000 次。

在 VS Code 里能用吗？能。用暴露 OpenRouter 供应商的智能体扩展（如 Cline、Kilo Code），或任何允许自定义 OpenAI 基础 URL 的扩展，设好 URL、粘贴密钥、选模型即可。

模型 slug 是什么格式？供应商/模型，例如 openai/gpt-4o、anthropic/claude-sonnet-4。作者前缀加 ~（如 ~anthropic/claude-sonnet-latest）始终解析到家族最新版本。

OpenRouter 会记录我的代码或提示词吗？默认不会，即使请求出错也不记录，除非显式开启。有一个可选设置用少量用量折扣换取日志记录，条款见隐私政策。

原文信息

作者：OpenRouter
发布时间：2026-06-16
原文标题：How to Use OpenRouter With Any Coding Agent or AI Tool

原文地址：

#AI前沿资讯

文章评论（0）

暂无评论，快来抢沙发～

← 返回文章列表