---
author: OOMOL
author_url: https://oomol.com/zh-cn/about/
title: 使用 SDK 调用已连接的 Apps
description: 通过托管 Connector client，让可信 TypeScript 后端调用你在 OOMOL 账号中连接的 Apps。
lang: zh-CN
canonical_url: https://oomol.com/zh-cn/docs/connector-client/
markdown_url: https://oomol.com/zh-cn/docs/connector-client.md
---

# 使用 SDK 调用已连接的 Apps

当后端代码需要调用你在 OOMOL 账号中连接的 Apps 时，使用 `Connector`。这条路径调用 OOMOL 托管的 Connector 网关，并使用形如 `api_…` 的个人 API key。

## 安装 SDK

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

SDK 需要 Node 18 或更高版本。其他提供标准 `fetch` 与 `AbortController` API 的环境也可以使用，但个人 API key 必须留在可信后端环境中。

## 创建个人 API key

在 [OOMOL Console](https://console.oomol.com/api-key) 创建 key，然后保存为后端密钥：

```sh
export OOMOL_API_KEY=api_...
```

不要把这个 key 放进浏览器 bundle、移动客户端、公开代码仓库、提示词或客户端日志。

## 执行第一个 action

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

const oomol = new Connector({ apiKey: process.env.OOMOL_API_KEY! });

const result = await oomol.execute("gmail.search_threads", {
  query: "is:unread",
});
```

Namespace 写法会执行同一个 action：

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

需要在日志或支持工单中保存 `executionId`、`actionId` 和响应消息时，使用 `executeRaw`。

## 选择已连接账号

同一个 provider 有多个 connection 时，通过 `connectionName` 选择账号：

```ts
await oomol.execute(
  "gmail.search_threads",
  { query: "from:ceo" },
  { connectionName: "work" },
);
```

使用 `oomol.apps.list()` 查看当前 OOMOL 账号可用的 connections。Connection 的创建与移除仍在 OOMOL Console 中完成。

## 查找 actions

通过 catalog 查看 providers、actions 与运行时 schemas：

```ts
const providers = await oomol.catalog.providers({ q: "mail" });
const actions = await oomol.catalog.actions("gmail");
const action = await oomol.catalog.action("gmail.search_threads");
```

上游 endpoint 还没有对应 action 时，可以使用 `proxy` 通过所选 connection 调用。

## 继续查阅参考

[TypeScript SDK 参考](/zh-cn/docs/connector-sdk/)包含精确 action 类型、配置优先级、重试、超时、取消、proxy 行为、错误处理和完整 `Connector` API。

如果产品里的每个用户都要连接独立账号，请改用 [ProjectConnector](/zh-cn/docs/project-connector/)。