跳至正文

文档

OpenConnector 客户端：SDK、CLI、HTTP 与 MCP

使用 TypeScript SDK、oo CLI、HTTP 或 MCP 调用 OpenConnector，从公开的 Hacker News Action 开始。

由 OOMOL 维护·

源码核对日期：2026-09-09. 示例已按链接中的源码版本核对，不代表通过了真实上游 API 验证；你部署的版本可能有所不同。

何时使用 OpenConnector

当 AI Agent 需要通过已授权账号调用第三方服务，或你需要在自有基础设施中控制凭据与执行策略时，使用 OpenConnector。

如何开始

选择自托管或 OOMOL 托管运行时，连接账号，发现 Action，检查输入 schema 和权限，再进行一次小范围的只读调用并检查结果。

运行时与 API 边界

本域名提供项目信息和文档，不承载可直接调用的连接器 API 或 MCP 服务。请向所选运行时发送请求。自托管时，在该运行时查看 /openapi.json 和 /docs。需要让自己的用户连接账号的 SaaS 产品，应遵循独立的 OOMOL 产品集成指南。

产品集成指南 ↗

安装官方 oo CLI

按照官方安装指南安装 oo，再使用 oo connector 发现和调用 Action。根据所选部署配置运行时地址、运行时令牌和账号连接。

安装官方 oo CLI ↗

官方 TypeScript SDK

从 npm 安装 @oomol-lab/connector。使用 OpenConnector 客户端连接自有运行时；托管个人账号或 SaaS 最终用户账号连接请遵循 OOMOL SDK 指南。

npm
npm install @oomol-lab/connector
npm: @oomol-lab/connector ↗

运行时 OpenAPI 参考规范

下载基于固定运行时版本生成的参考规范。使用前将 runtimeUrl 设置为自己的部署地址。各服务的具体 Action schema 来自该运行时的目录。本网站不执行 API 调用。

运行时 OpenAPI 参考规范 →运行时源码· 72de05b ↗

TypeScript

先安装 @oomol-lab/connector。此示例在 Node.js 中调用已启动的本地 OpenConnector。

TypeScript
import { OpenConnector } from "@oomol-lab/connector";

const connector = new OpenConnector({
  baseUrl: "http://localhost:3000",
  runtimeToken: process.env.OOMOL_CONNECT_RUNTIME_TOKEN,
});

const stories = await connector.hackernews.get_top_stories({});
console.log(stories);

CLI

安装 oo CLI 后，将 connector 命令指向本地运行环境。启用认证的部署还需要运行时令牌。

CLI
oo connector login http://localhost:3000
oo connector search "Hacker News"
oo connector schema hackernews.get_top_stories
oo connector run hackernews --action get_top_stories --data '{}'

HTTP

对本地运行环境调用这个只读、无需服务授权的 Action。若已启用运行时认证，需附带 Bearer 令牌。

HTTP
curl -s -X POST \
  http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

MCP

在兼容的 Agent 客户端中配置此 HTTP MCP 地址。客户端认证与可用工具见运行时 API 文档。

MCP
http://localhost:3000/mcp

理解调用结果

HTTP 运行时响应包含 success、message、data 和 meta。请检查 success 及 Action 输出 Schema，不要只看 HTTP 状态码。执行元数据包含 executionId 时，可据此定位脱敏运行日志。下面仅展示响应结构，并非真实 API 调用结果。

示意响应
{
  "success": true,
  "message": "OK",
  "data": {},
  "meta": {}
}

调用失败时如何排查

  • 认证失败时，先核对接口和凭证类型：管理端凭证用于 /api，运行时 Bearer 令牌用于 /v1 和 /mcp。服务提供方的 API Key 不能替代运行时令牌。
  • 权限被拒绝时，检查 Action 所需 scopes、运行时 Action 规则和连接授权。令牌有效也不代表有权使用所选账号。
  • 结果为空或资源缺失时，检查连接账号及其对目标资源的访问权限。完成授权不代表能访问所有工作区、频道或文档。
  • 重试前先检查错误与运行日志。对于会修改服务数据的 Action，先确认操作是否已经完成，不要盲目重复请求。
阅读 Markdown