---
title: 使用 OpenConnector SDK 呼叫自部署 runtime
description: 透過 OpenConnector TypeScript client 呼叫自部署 runtime 的 actions、catalog
  與 connections。
lang: zh-TW
canonical_url: https://oomol.com/zh-tw/docs/openconnector-sdk/
markdown_url: https://oomol.com/zh-tw/docs/openconnector-sdk.md
---

# 使用 OpenConnector SDK 呼叫自部署 runtime

當 TypeScript 程式碼需要呼叫由你維運的 OpenConnector runtime 時，使用 `OpenConnector`。這個 client 透過 `baseUrl` 指向你的伺服器。

請先完成伺服器部署與存取保護。[OpenConnector 自部署指南](/zh-tw/docs/openconnector-self-hosting/)包含 Docker Compose、原始碼執行和 Cloudflare Workers 三種部署方式。

## 安裝 SDK

```sh
npm install @oomol-lab/connector
```

## 呼叫本機 runtime

全新的本機 runtime 預設執行於 `http://localhost:3000`。設定 runtime token 前可以直接呼叫，但這種無 token 設定只能用於 localhost 或其他私有網路：

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

const open = new OpenConnector();

const stories = await open.execute("hackernews.get_top_stories", {});
```

Namespace 寫法使用相同的 action registry：

```ts
const threads = await open.gmail.search_threads({ query: "is:unread" });
```

## 指向你的伺服器

`baseUrl` 使用伺服器 origin，API path 由 client 自動加入。公開 runtime 前，先在它僅能從可信網路存取時建立 runtime token，再要求所有 client 攜帶該 token：

```ts
const open = new OpenConnector({
  baseUrl: "https://connect.internal.example.com",
  runtimeToken: process.env.OOMOL_CONNECT_RUNTIME_TOKEN!,
  connectionName: "work",
});
```

Runtime 建立 token 後，伺服器會要求有效的 `oct_…` token。請根據部署策略，將它保存在呼叫方後端或 Agent 環境中。不要透過公開網域或 tunnel 暴露無 token 的 runtime。

## 檢查 runtime

```ts
await open.health();
await open.catalog.services();
await open.catalog.search("send email", { limit: 5 });
await open.apps.listByService("github");
await open.apps.authenticated(["github", "notion"]);
```

透過 client 預設值或單次呼叫的 `connectionName` 選擇已設定帳號。兩者都沒有時，runtime 使用預設 connection。

## 在 Web 控制台中管理設定

SDK 只消費 runtime 設定。建立 connection、設定 OAuth client、產生 runtime token 和管理 action policy 都在 OpenConnector Web 控制台中完成。

[TypeScript SDK 參考](/zh-tw/docs/connector-sdk/)包含精確 action 類型、proxy 差異、逾時、重試、錯誤處理和完整 `OpenConnector` API。