@openrouter/devtools 是 OpenRouter 官方提供的开发专用调试工具包（pre-release 阶段）。通过一行 hooks: createOpenRouterDevtools() 接入 @openrouter/sdk，即可自动采集所有 SDK 请求的遥测数据——模型名、请求/响应内容、token 用量、耗时和错误信息——并通过本地 Web 界面（端口 4983）实时展示。遥测捕获完全异步、不阻塞 SDK 调用，且生产环境下会主动报错防止误上线。支持自定义存储路径和服务端口。

Pre-release：DevTools 处于预发布阶段，仅供开发环境使用，禁止在生产环境部署。

@openrouter/devtools 让你在开发阶段对 OpenRouter SDK 的每一次调用都了如指掌——请求/响应内容、token 消耗、耗时、错误信息一目了然。

安装

npm install @openrouter/devtools --save-dev

只作为 dev dependency 安装，生产环境下调用 createOpenRouterDevtools() 会直接抛错。

快速接入

基本用法

在创建 OpenRouter 实例时传入 hooks：

import { createOpenRouterDevtools } from '@openrouter/devtools';
import { OpenRouter } from '@openrouter/sdk';

const sdk = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  hooks: createOpenRouterDevtools()
});

// 之后所有 SDK 操作都会被自动采集
const response = await sdk.chat.send({
  model: "openai/gpt-5",
  messages: [
    { role: "user", content: "Explain quantum computing" }
  ]
});

自定义配置

const sdk = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  hooks: createOpenRouterDevtools({
    storagePath: '.custom-path/generations.json', // 默认: '.devtools/openrouter-generations.json'
    serverUrl: 'http://localhost:5000/api/notify', // 默认: 'http://localhost:4983/api/notify'
  })
});

启动 DevTools Viewer

openrouter devtools

在本地 4983 端口启动 Web 界面，可查看：

• 所有 SDK 运行记录（时间戳 + 状态）
• 每步请求/响应详情
• Token 用量和费用
• 错误信息和堆栈
• 耗时统计

工作原理

1. SDK hooks 在请求发出前拦截
2. 遥测数据异步采集（不阻塞 SDK 操作）
3. 数据写入 .devtools/openrouter-generations.json
4. 通知发送到本地 DevTools server（如果正在运行）
5. Viewer 实时更新

配置项

选项	类型	默认值	说明
storagePath	string	'.devtools/openrouter-generations.json'	遥测数据存储路径
serverUrl	string	'http://localhost:4983/api/notify'	DevTools server 通知端点

采集的 SDK 操作

• chat.send() — Chat completions
• chat.createResponses() — Responses API
• embeddings.create() — Embeddings

安全使用

防止上生产

const hooks = process.env.NODE_ENV === 'development'
  ? createOpenRouterDevtools()
  : undefined;

const sdk = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  hooks
});

DevTools 如果在 NODE_ENV === 'production' 下初始化会直接报错，这是有意设计的保护机制。

故障排查

端口被占用

如果 4983 端口已被占用，在 ~/.openrouter/claude-code-proxy.json 中配置：

{
  "DEVTOOLS_PORT": 5000
}

同时更新 hooks 配置：

hooks: createOpenRouterDevtools({
  serverUrl: 'http://localhost:5000/api/notify'
})

Viewer 不刷新

1. 确认 DevTools server 正在运行（openrouter devtools）
2. 检查 serverUrl 与 server 端口一致
3. 确认 .devtools/ 目录下有遥测文件

常见问题

Q: DevTools 会影响 SDK 请求的速度吗？

A: 不会。遥测采集完全异步，不阻塞 SDK 调用。即使 DevTools 内部发生错误，也不会抛到你的代码层。

Q: 遥测数据存在哪里，会上传吗？

A: 全部存储在本地 .devtools/openrouter-generations.json 文件中，不会上传到任何服务器。

Q: 生产环境部署时要怎么处理？

A: 用环境变量条件判断，开发环境传 createOpenRouterDevtools()，其他环境传 undefined。DevTools 会在 NODE_ENV === 'production' 时主动报错提醒你。