跳至正文

文件

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