KNOWLEDGE · 12 PAGES · 9:16
第 01 章 · 引子
OPENROUTER
300+
一把 Key，
接住 300+ 模型
OpenRouter · 60+ Provider · 1 个端点
工具可以换，Key 不用换
OpenRouter × Coding Agents · 拆解
@knowledge-visual-cartographer
01 / 12
PAIN
第 02 章 · 痛点
多工具多模型的
「钥匙噩梦」
工具一多,光配环境就耗掉半天。
01
钥匙散落
Claude 一把、OpenAI 一把、Gemini 又一把。每个供应商各一套。
02
计费迷宫
四个 Dashboard,四张账单,谁花的算不清。
03
配置碎片
环境变量、配置文件、设置面板各一套。每接一个工具重写一次。
02 / 12
DEFINE
第 03 章 · 界定
OpenRouter 是什么 /
不是什么
先把"是什么 vs 不是什么"拆清楚。
+
是 · 统一 API 路由层
夹在「你的工具」与「模型供应商」之间,一个端点分发到 60+ Provider。
+
是 · OpenAI Chat Completions 兼容
官方 OpenAI SDK 换 base_url 即可直连,业务代码零改动。
-
不是 · 模型本身
它不训模型也不持有权重,只是把请求转给上游。
-
不是 · 加价中间商
按 token 原价计费(0% inference 加价),只收 5.5% 信用费。
03 / 12
VALUE
第 04 章 · 价值
一把钥匙
一个 URL
一个 Slug
配置一次,切模型只改一个字符串。
01
Key
sk-or-... 一把,所有工具通用
02
URL
https://openrouter.ai/api/v1
03
Slug
openai/gpt-4o ·
anthropic/claude-sonnet-4
→ 换模型 = 改一个字符串
04 / 12
SETUP
第 05 章 · 三步配置
三步接好 OpenRouter
任何工具都跑同一套流程。
01
去 openrouter.ai/keys 生成 sk-or-... Key
# 把 Key 放到环境变量,别写进源码
export OPENROUTER_API_KEY=sk-or-v1-...
02
base URL 指向统一端点
# Python · OpenAI SDK
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
)
03
用 provider/model 格式挑一个 Slug
# 切模型 = 改一个字符串
model = "anthropic/claude-sonnet-4"
# ↑ 改成 openai/gpt-4o / google/gemini-... 都可以
⚠ Key 放环境变量,别写进源码 · 推送到 git 之前先 gitignore
05 / 12
CODE
第 06 章 · 同一调用 三种写法
curl / Python / TypeScript
官方 OpenAI SDK 直接复用,业务代码零改动。
curl
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."}] }'
Python
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."}],
)
TypeScript
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(openrouter / @openrouter/sdk)
06 / 12
TOOLS
第 07 章 · 落地工具
一把 Key 通吃的
工具地图
终端 Agent / 编辑器 / 扩展 / 前端 / 协议层,全部用同一把 Key。
终端 Agent
Claude Code环境变量 · Anthropic 兼容端点
Codex CLI~/.codex/config.toml
OpenClaw~/.openclaw/openclaw.json · 或 OPENROUTER_API_KEY
Hermes~/.hermes/config.yaml · ~/.hermes/.env
编辑器 / IDE
Cursor应用内设置 · 自定义 OpenAI base URL
VS Code 扩展
Cline扩展设置 · OpenRouter provider
Kilo Code扩展设置 · OpenRouter provider
前端 / 协议层
SillyTavern连接设置 · OpenRouter API
Claude DesktopAnthropic 兼容端点
Junie · OpenCode · MCP serversOpenRouter cookbook 接入
07 / 12
ROUTING
第 08 章 · 路由
让 Agent 永不掉线
一次失败请求 Agent 还好接住,多步任务里 Provider 抖一下就半路断电 - 路由双保险就是为这个准备的。
第一层 · 自动 provider failover
同一模型,多 Provider 自动切换
- 挂了或被限流 → 自动路由到另一家 Provider
- 零配置,开箱即用
- 你只为成功的那一次付费
第二层 · 手动 model fallback
主备模型按序试
- 传 models 数组(OpenAI SDK 走 extra_body={"models":[...]})
- 覆盖「模型只有一家 provider」的盲区
- 响应里 model 字段告诉你最终跑了哪个
兜底 · Auto Router
openrouter/auto
- 按 prompt 难度自动选模型
- 简单的派给便宜模型,难的派给强模型
- 不加收 routing 费 · 原价计费
08 / 12
SDK
第 09 章 · SDK 选型
Client SDK vs
Agent SDK
接现有工具用 OpenAI SDK 就行,自建 Agent 才需要 Agent SDK。
Client SDK · 轻量
薄封装 REST + 类型推导
- Python · openrouter 包
- TypeScript · @openrouter/sdk
- 适用:已有 OpenAI SDK 经验,需要可控 HTTP
Agent SDK · 重量
替你跑循环
- 多轮对话 + 工具执行 + 状态管理 · 一站式
- 关键能力:同一 loop 内不同 turn 切不同模型
- 读文件用便宜模型,生成代码用强模型
- callModel 原语 · 一个调用跑完整个工具循环
09 / 12
COST
第 10 章 · 成本
三档成本地图
0% inference 加价 · 只在充钱时收一笔小额信用费。
免费档
$0
20+ 模型永久免费 · 50 次/天 → 充 $10 提到 1000 次/天
够跑通端到端,生产慎用 · 失败请求也算配额
付费档
0%
inference 加价 · 按 token 原价计费 · 不抽成
模型目录价 = 你付的价
信用费
5.5%
充钱时一次性收 · 最低 $0.80
详见 openrouter.ai/pricing · 实时账单看 Activity dashboard
10 / 12
FAQ
第 11 章 · FAQ
你最常踩的 5 个坑
一次讲完,别再回头翻文档。
Q · 每个工具要单独 Key 吗?
A · 不。一把 sk-or-... 全通,Claude Code / Codex / Cursor 都能复用。
Q · OpenAI SDK 能直接用吗?
A · 能。base_url 指向 https://openrouter.ai/api/v1 即可,业务代码零改动。
Q · 免费档稳定吗?
A · 够跑通端到端原型。生产慎用 - 高峰期上游可能限流,失败请求也算配额。
Q · Slug 格式是什么?
A · provider/model,例如 openai/gpt-4o。加 ~ 前缀可锁家族最新版(~anthropic/claude-sonnet-latest)。
Q · 会上传我的代码 / 提示吗?
A · 默认不上,即使请求报错也保留本地。需要日志换折扣?需手动 opt-in,见 Privacy Policy。
11 / 12
END
第 12 章 · 收束
FIN
∞
一个端点
一把钥匙
一份账单
模型是日用品，路由才是基础设施。
今天的 Claude → 明天的 GPT → 后天的 Gemini
— 都走同一根管。
@knowledge-visual-cartographer
DONE · 12 / 12
12 / 12