---
author: OOMOL
author_url: https://oomol.com/zh-cn/about/
title: 使用 OpenConnector SDK 调用自部署 runtime
description: 通过 OpenConnector TypeScript client 调用自部署 runtime 的 actions、catalog
  与 connections。
lang: zh-CN
canonical_url: https://oomol.com/zh-cn/docs/openconnector-sdk/
markdown_url: https://oomol.com/zh-cn/docs/openconnector-sdk.md
---

# 使用 OpenConnector SDK 调用自部署 runtime

当 TypeScript 代码需要调用由你运维的 OpenConnector runtime 时，使用 `OpenConnector`。这个 client 通过 `baseUrl` 指向你的服务器。

请先完成服务器部署与访问保护。[OpenConnector 自部署指南](/zh-cn/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-cn/docs/connector-sdk/)包含精确 action 类型、proxy 差异、超时、重试、错误处理和完整 `OpenConnector` API。