OpenConnector 实战:把本地 Action 目录转换为 OpenAI Function Tools 并跑通工具调用闭环
OpenConnector 实战:把本地 Action 目录转换为 OpenAI Function Tools 并跑通工具调用闭环
OpenConnector 是一个开源认证网关,将 1500+ SaaS 服务商封装为可执行的 Action 目录(catalog),并通过 HTTP、MCP、SDK 等多种方式暴露给 AI Agent。本篇以 examples/openai-tools/README.md 及配套示例脚本为核心,讲解如何把本地运行时暴露的 Action 目录转换成了 OpenAI function calling 工具,并用 OpenAI Responses API 跑通"模型发起工具调用 → 本地运行时执行 → 结果回填模型"的完整闭环。读完本文,你可以复制并运行仓库中的两个示例脚本,理解目录结构到工具 schema 的映射规则,以及 function_call / function_call_output 之间的调用链路。
1. 整体流程:从 Action 目录到 Function Calling 闭环
这两个示例的共同前提是把 OpenConnector 的本地运行时跑起来,其核心脉络可以概括为:
- 通过
GET http://localhost:3000/api/actions拉取本地运行时的全部 Action 目录,每个 Action 带有id、description、inputSchema三个关键信息; - 将目录映射为 OpenAI 要求的 function tool 结构:
{ type: "function", name, description, parameters },其中parameters直接复用目录中的 JSON Schema(inputSchema); - 将工具列表提交给 OpenAI Responses API(
POST https://api.openai.com/v1/responses),由模型自主决定调用哪个工具、传什么参数(tool_choice: "auto"); - 对模型返回的每个
function_call,向本地运行时POST http://localhost:3000/v1/actions/{actionId}执行对应 Action,并把执行结果以function_call_output回填到对话输入; - 再次调用 Responses API,让模型基于执行结果产出最终自然语言回答。
第一个示例只做第 1、2 步(打印工具定义);第二个示例完成全部 5 步(以 Hacker News 为场景的完整闭环)。
2. 启动本地运行时与环境变量准备
2.1 使用 npm run dev 启动
按照 examples/openai-tools/README.md 的说明,先启动本地运行时:
npm run dev
从 scripts/dev-local.ts 的实现看,这个命令做了三件事:
- 先同步执行
node scripts/ensure-generated.ts,确保生成物(如目录资产)就绪; - 以 watch 模式启动 API 运行时(
node --watch src/server/index.ts),监听端口取PORT环境变量,默认3000; - 启动 Web 控制台(Vite dev server),运行在
http://localhost:5173。
启动后终端会打印 API runtime: http://localhost:3000 与 Web console: http://localhost:5173。两个示例脚本均硬编码访问 http://localhost:3000,因此 PORT 保持默认即可。
2.2 两个 Bearer Token 环境变量
README 指出:如果服务器要求 bearer token,列出 /api Action 时设置 OOMOL_CONNECT_ADMIN_TOKEN,通过 /v1 执行 Action 调用时设置 OOMOL_CONNECT_RUNTIME_TOKEN。
这一约定落实到 examples/local-http/client.ts 中,两个辅助函数分别读取对应环境变量:
export function adminHeaders(headers: HeadersInit = {}): HeadersInit {
return bearerHeaders(process.env.OOMOL_CONNECT_ADMIN_TOKEN, headers);
}
export function runtimeHeaders(headers: HeadersInit = {}): HeadersInit {
return bearerHeaders(process.env.OOMOL_CONNECT_RUNTIME_TOKEN, headers);
}
从源码结构看,bearerHeaders 在 token 缺省时原样返回输入 headers,即本地开发未启用认证时脚本无需额外配置即可运行;一旦设置了 token,则统一注入 authorization: Bearer <token> 头。这与 OpenConnector 的管理端(/api)与运行时端(/v1)双令牌模型一致。
2.3 关于直接用 node 运行 .ts 文件
两个示例的启动命令都是 node examples/openai-tools/xxx.ts,直接用 Node 运行 TypeScript 源码。这要求使用支持原生 TypeScript type stripping 的 Node.js 版本(如 Node 23+ 或启用相应实验能力的 Node 22.6+)。examples/tsconfig.json 仅继承公共 Node 配置,示例脚本本身不经过额外构建步骤,属于 Node 原生 TS 支持下的零构建运行方式。
3. 示例一:list-tools.ts 打印发给 OpenAI 的工具定义
list-tools.ts 的全部逻辑只有几十行,是理解"目录 → 工具"映射规则的最短路径:
const actions = await fetchJson<CatalogAction[]>("http://localhost:3000/api/actions", {
headers: adminHeaders(),
});
const tools: OpenAiFunctionTool[] = actions.map((action) => ({
type: "function",
name: toOpenAiToolName(action.id),
description: action.description,
parameters: action.inputSchema,
}));
console.log(`Converted ${tools.length} connector actions into OpenAI function tools.`);
for (const tool of tools.slice(0, 10)) {
console.log(`- ${tool.name}: ${tool.description}`);
}
function toOpenAiToolName(actionId: string): string {
return actionId.replaceAll(".", "__");
}
运行方式(来自 README):
node examples/openai-tools/list-tools.ts
输出首先是转换总数,例如 Converted N connector actions into OpenAI function tools.,随后逐条打印前 10 个工具的名称与描述。
映射规则值得逐条拆解:
- name:OpenAI function 的
name不允许包含.,因此脚本把 Action ID 中的点全部替换为双下划线,如hackernews.top_stories变为hackernews__top_stories。这个转换函数在两个示例中保持完全一致,是后续"工具名 → Action ID"反查的基础; - description:直接取目录中的 Action 描述,模型据此判断何时调用该工具;
- parameters:直接透传目录中的
inputSchema(JSON Schema)。OpenConnector 的目录本身就是按 JSON Schema 描述输入输出的,因此无需二次翻译即可作为 function calling 的parameters。
GET /api/actions 是运行时 OpenAPI 中 "Catalog" 组下的端点(见 src/server/api/openapi.ts 中 /api/actions 的定义 "List all catalog actions."),响应即完整目录数组。
4. 示例二:run-hackernews.ts 跑通工具调用闭环
run-hackernews.ts 演示了完整的 function calling 流程,场景限定为无需任何凭证的 Hacker News 服务商。
4.1 运行前置条件
按 README 的说明运行:
OPENAI_API_KEY=sk-... OPENAI_MODEL=gpt-... node examples/openai-tools/run-hackernews.ts
脚本开头对两个环境变量做硬性检查,缺失时打印提示并直接退出(process.exit(0)),不会发起任何请求:
const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) {
console.log("Set OPENAI_API_KEY to run this example.");
process.exit(0);
}
const model = process.env.OPENAI_MODEL;
if (!model) {
console.log("Set OPENAI_MODEL to run this example.");
process.exit(0);
}
选择 Hacker News 作为演示场景的原因在 src/providers/hackernews/definition.ts 中可以看到:该 provider 的 authTypes 为 ["no_auth"],底层调用 Hacker News 公开的 Firebase 与 Algolia API,因此整条链路不需要配置任何第三方凭证,本地启动即可运行。
4.2 目录过滤与工具名反查表
脚本拉取全量目录后,只保留 hackernews. 前缀的 Action:
const actions = (
await fetchJson<CatalogAction[]>("http://localhost:3000/api/actions", {
headers: adminHeaders(),
})
).filter((action) => action.id.startsWith("hackernews."));
const toolNameToActionId = new Map(actions.map((action) => [toOpenAiToolName(action.id), action.id]));
toolNameToActionId 是关键数据结构:模型返回的工具名是转换后的 hackernews__xxx,而本地执行端点需要的是原始 Action ID hackernews.xxx,这张 Map 承担双向映射中的"反查"职责。工具列表随后按 3 节所述同样的规则构造。
4.3 第一轮请求:让模型自主发起工具调用
初始输入是一条用户消息,刻意给出"找当前 HN 热门文章 ID"这类需要外部数据才能回答的任务:
let input: unknown[] = [
{
role: "user",
content: "Find the current top Hacker News story ids, then summarize what tool you used.",
},
];
let response = await createResponse(model, tools, input);
createResponse 封装了对 Responses API 的调用:
async function createResponse(model: string, tools: OpenAiFunctionTool[], input: unknown[]): Promise<OpenAiResponse> {
const response = await fetch("https://api.openai.com/v1/responses", {
method: "POST",
headers: {
authorization: `Bearer ${apiKey}`,
"content-type": "application/json",
},
body: JSON.stringify({
model,
tools,
input,
tool_choice: "auto",
}),
});
if (!response.ok) {
throw new Error(`OpenAI request failed: ${response.status} ${await response.text()}`);
}
return (await response.json()) as OpenAiResponse;
}
请求体四个字段各有一层含义:model 决定模型,tools 携带完整工具 schema,input 是 Responses API 的输入项数组,tool_choice: "auto" 让模型自行判断是否调用工具。请求失败时脚本把状态码与响应体一起抛出,便于定位是鉴权、限流还是参数问题。
4.4 执行工具调用并回填结果
模型若决定调用工具,output 中会出现 type: "function_call" 的项,携带 call_id、name 和 JSON 字符串形式的 arguments。脚本对每个调用做三件事:
const toolCalls = response.output?.filter(isFunctionCall) ?? [];
for (const toolCall of toolCalls) {
const actionId = toolNameToActionId.get(toolCall.name);
if (!actionId) {
throw new Error(`Unknown tool call: ${toolCall.name}`);
}
const executionResult = await fetchJson(`http://localhost:3000/v1/actions/${actionId}`, {
method: "POST",
headers: runtimeHeaders({ "content-type": "application/json" }),
body: JSON.stringify({ input: JSON.parse(toolCall.arguments || "{}") }),
});
input.push(toolCall);
input.push({
type: "function_call_output",
call_id: toolCall.call_id,
output: JSON.stringify(executionResult),
});
}
- 路由:模型给出的
name通过反查表还原为 Action ID;查不到直接抛错,说明模型生成了目录之外的工具名(例如幻觉); - 执行:向
POST /v1/actions/{actionId}发送请求,请求体形如{ "input": { ...模型参数... } },并附OOMOL_CONNECT_RUNTIME_TOKEN(如已配置)。模型产出的arguments是字符串,脚本先JSON.parse成对象再包进input字段——这正是 OpenConnector/v1执行端点的输入契约; - 回填:把原始的
toolCall项和新的function_call_output项依次追加到input数组。Responses API 要求function_call_output与先前输入中出现的call_id一一对应,且顺序紧随其对应的function_call之后,这里的push顺序保证了这一点。
4.5 第二轮请求:拿到最终文本
回填完成后,只要本轮出现过工具调用,就再发一次请求,此时模型的输出通常不再是 function_call 而是文本:
if (toolCalls.length > 0) {
response = await createResponse(model, tools, input);
}
console.log(response.output_text ?? JSON.stringify(response.output, null, 2));
脚本优先打印 output_text(模型对"找到的热门 ID + 使用了什么工具"的总结),拿不到时降级打印完整 output 结构的 JSON。这个两阶段结构——先执行工具、再总结——是 function calling 在 Responses API 下的最小完整形态。
5. 支撑闭环的运行时端点与 Provider 实现
两个示例脚本只是客户端,真正让闭环成立的是本地运行时的两端能力。
5.1 目录端点 /api/actions
GET /api/actions 返回所有 provider 的 Action 目录。以 Hacker News 为例,src/providers/hackernews/actions.ts 中每个 Action 的输入输出均通过项目内 schema 工具(s.object、s.array 等)声明为 JSON Schema,例如 top_stories 类 Action 的输出 schema 形如 { story_ids: number[] }。这意味着 inputSchema 不是手写文本而是从类型化声明推导而来,模型收到的参数约束(字段名、类型、取值范围)与运行时实际执行的校验是同一份定义,天然保证"模型能调的"和"运行时能跑的"一致。
5.2 执行端点 /v1/actions/{actionId}
POST /v1/actions/{actionId} 接收 { input } 请求体并执行对应 Action。Hacker News provider 声明为 no_auth(见 src/providers/hackernews/definition.ts),所以这类 Action 对任何持有运行时访问权的客户端都可直接执行;其他 provider(如 GitHub、Gmail)的 Action 则要求先建立对应连接与凭证,执行时由运行时注入。
5.3 令牌与错误处理
从 examples/local-http/client.ts 的 fetchJson 实现看,所有非 2xx 响应都会抛错并携带 HTTP 状态码与响应体文本:
if (!response.ok) {
throw new Error(`${init.method ?? "GET"} ${url} failed with HTTP ${response.status}: ${text}`);
}
因此排障时可以直接从错误信息判断是 /api 管理端 401/403(admin token 问题)还是 /v1 执行端 401/403(runtime token 或连接授权问题),无需额外抓包。
6. 扩展思路与适用边界
基于这两个示例的结构,有几种自然的改法(以下均是对现有脚本逻辑的合理延伸):
- 换 provider:把
.filter((action) => action.id.startsWith("hackernews."))改为其他前缀(如github.)即可切换场景;但注意非no_authprovider 需要先按 docs/credentials.md 完成连接配置,且 runtime token 需具备相应连接权限; - 多轮循环:当前示例是"一轮工具调用 + 一轮总结"的固定流程。若模型在第二轮仍返回
function_call,可将 4.4 节的外层逻辑包进循环,直到output中不再出现function_call为止; - 结果裁剪:
function_call_output.output是整个执行结果的 JSON 字符串原样回填,Action 返回体较大时会占用较多上下文,实践中可对结果做截断或摘要后再回填; - 并发调用:Responses API 允许一条输出中携带多个
function_call,当前脚本以顺序for循环逐个执行,如需提速可并行化,但回填时仍须保持call_id对应关系。
适用前提与限制总结:
| 事项 | 说明 |
|---|---|
| Node 版本 | 需支持原生运行 .ts 的 Node.js(type stripping) |
| 本地运行时 | npm run dev 启动,API 端口默认 3000,脚本硬编码 localhost:3000 |
| 环境变量 | OPENAI_API_KEY、OPENAI_MODEL 必填;OOMOL_CONNECT_ADMIN_TOKEN / OOMOL_CONNECT_RUNTIME_TOKEN 仅在服务器启用 bearer 认证时需要 |
| 网络出口 | 脚本需直接访问 api.openai.com,运行时需访问各 provider 的 API |
| 认证模型 | /api 用 admin token,/v1 用 runtime token,两者职责分离 |
7. 小结
examples/openai-tools 目录下的两个脚本完整演示了 OpenConnector 对接 OpenAI function calling 的标准姿势:目录中每个 Action 的 id / description / inputSchema 三元组与 OpenAI function tool 的 name / description / parameters 一一对应,中间的 . → __ 命名转换及反查表是双向映射的关键;GET /api/actions 负责"告诉模型有什么工具",POST /v1/actions/{actionId} 负责"让模型真正用上工具",而 function_call / function_call_output 的回填协议则把两者串成闭环。理解了这套转换与调用约定后,把 OpenConnector 接入任意使用 function calling 的模型 API(或把其他工具目录接入 OpenConnector 运行时)都只是同构问题。