---
author: OOMOL
author_url: https://oomol.com/zh-cn/about/
title: 核心概念
description: 分清三个 Connector 产品共享的概念，以及各自使用的身份、权限与运行模型。
lang: zh-CN
canonical_url: https://oomol.com/zh-cn/docs/core-concepts/
markdown_url: https://oomol.com/zh-cn/docs/core-concepts.md
---

# 核心概念

三个 Connector 产品共享 providers、actions 和 schemas，但使用不同的账号隔离与权限模型。先确认当前使用的产品，再理解其中的 connection、connected account、Team 或 Project。

| 产品 | 账号与隔离模型 | 运行位置 |
| --- | --- | --- |
| OOMOL Connector（托管） | 个人或 Team 中的 connections | OOMOL 托管 |
| Connector for SaaS | Project、external user 和 connected accounts | OOMOL 托管 |
| OpenConnector | 由部署方管理的 runtime 与 connections | 自己的基础设施 |

## 三个产品共享的概念

### Apps 与 providers

**App** 是用户看到并选择连接的服务，例如 Gmail、GitHub 或 Slack。

**Provider** 或 **service** 是 Connector 中对应的技术集成。它定义认证方式、actions、schemas，以及如何请求上游 API。App 与 provider 的名称通常一致，但一个是用户看到的服务，一个是 Connector 的实现边界。

### Actions 与 tools

**Action** 是 provider 暴露的一个可调用操作。Action ID 通常由 service 和操作名组成，例如 `gmail.search_threads`。每个 action 都有输入 schema，并定义调用后返回的数据。

**Tool** 是 action 在 Agent、CLI 或 MCP 中呈现给模型的调用入口。SDK 通常直接执行 action；Agent 则把可用 actions 作为 tools 发现和调用。

执行前应确认：

- action 会使用哪个账号；
- 将提交哪些参数；
- 操作会读取、写入还是删除数据；
- 当前身份是否被允许使用对应的账号资源。

### Agents 与 Skills

**Agent** 负责选择 tool、提供参数，并根据返回结果继续任务。OOMOL 为 Agent 提供经过授权的 App 能力，不替代 Agent 本身。

**Skill** 是一组可复用的任务指令。它告诉 Agent 使用哪些 tools、按什么顺序调用、保留哪些约束，以及如何整理结果。执行时沿用 Agent 的身份和可用 tools，App 凭据由 Connector 保存。

## OOMOL Connector（托管）

### Connection

**Connection** 是一个 App 账号在个人或 Team 范围内的一次连接实例。它包含独立的 connection name 和 ID，并关联账号授权、状态与权限配置。

同一个 App 账号可以连接多次。每个 connection 都可以单独设置：

- **接口调用范围**：这个 connection 允许调用哪些 actions；
- **成员权限**：在 Team 中，哪些成员可以使用这个 connection。

成员可以调用的 actions，是其所有可访问 connections 所允许 actions 的合集。

### Team

**Team** 是托管 Connector 的团队租户范围。当前 Team 决定调用方可以看到哪些 connections，以及可以使用其中哪些 actions。

CLI、MCP 和 SDK 应明确选择 Team，避免默认 Team 变化后调用到错误的 connection。团队版按席位计费，具体信息在 [Console 账单页面](https://console.oomol.com/billing)查看。

### 有效权限

一次调用能否执行，由以下范围共同决定：

```text
Provider 授权范围
  ∩ connection 的接口调用范围
  ∩ Team 中的成员权限
  ∩ CLI、MCP 或 SDK 的调用身份
  = 最终可调用的 actions
```

完整配置方式见[权限控制](/zh-cn/docs/access-control/)和[团队管理](/zh-cn/docs/team-management/)。

### 托管 Connector 调用链路

```text
用户连接 App
  → 创建 connection
  → Agent 或可信后端选择 action 和 connection
  → OOMOL 托管 Connector 校验权限并加载凭据
  → Provider API
  → 返回结果与执行 metadata
```

## Connector for SaaS

Connector for SaaS 用于你的产品用户连接自己的第三方账号。它使用独立的多租户资源模型：

| 资源 | 用途 |
| --- | --- |
| **Project** | 隔离一个产品集成的配置、keys、connected accounts、执行记录与用量 |
| **Provider config** | 定义 Project 中某个 provider 的认证配置 |
| **External user ID** | 将 OOMOL 资源映射到你的产品用户 |
| **Connected account** | 表示某个 external user 授权的 provider 账号 |
| **Project API key** | 鉴权来自可信后端的 Project 请求 |

**Connected account** 表示 Project 中某个 external user 授权的 provider 账号。后端通过它为对应的产品用户选择账号并执行 action。

### SaaS 调用链路

```text
产品用户完成 Provider 授权
  → connected account 关联 external user ID
  → 你的后端使用 Project API key
  → ProjectConnector 选择用户、connected account 和 action
  → OOMOL 托管 Connector 执行调用
  → Provider API
```

你的产品负责鉴权自己的用户，并维护稳定且不可猜测的 external user ID 映射。详细资源和接入流程见 [Connector for SaaS](/zh-cn/docs/saas/)。

## OpenConnector

**OpenConnector** 是部署在你自己基础设施中的开源 runtime / gateway。

- **Runtime** 加载 providers、管理 connections、选择凭据、执行策略并调用 Provider API。
- **Gateway** 是 runtime 提供给 MCP、HTTP、OpenAPI 和 SDK client 的访问入口。
- **Runtime token** 控制 client 是否可以访问该 runtime 及其能力。

OpenConnector 把 runtime、connections 与访问策略放在你管理的基础设施中。调用方通过 runtime 提供的 MCP、HTTP、OpenAPI 或 SDK 接口使用 actions。

### OpenConnector 调用链路

```text
你配置 Provider 和 connection
  → Agent 或应用选择 action 和 connection
  → OpenConnector runtime 校验 token 与策略
  → runtime 加载凭据并调用 Provider API
  → 返回结果
```

部署方负责凭据加密、tokens、存储、网络、日志、备份和升级。详细边界见 [OpenConnector](/zh-cn/docs/openconnector/)。

## 凭据边界

Provider 的原始 OAuth token、API key 或自定义凭据不应暴露给 Agent、Skill、浏览器客户端或产品用户：

- OOMOL Connector 与 Connector for SaaS 由 OOMOL 在托管边界中存储和刷新凭据；
- OpenConnector 由部署方在自己的基础设施中保护凭据；
- Connector 在执行 action 或受支持的 proxy 请求时加载凭据，并只向调用方返回执行结果。

## 选择正确的术语

| 场景 | 应使用的术语 |
| --- | --- |
| 个人或团队连接一个 App 账号 | connection |
| SaaS 产品用户连接自己的账号 | connected account + external user |
| SaaS 产品的隔离边界 | Project |
| 同一 Team 中限制账号与 actions 的使用范围 | connection 的成员权限与接口调用范围 |
| Agent 看到的可调用入口 | tool |
| Connector 中定义的操作 | action |
| 自己部署的执行服务 | OpenConnector runtime / gateway |

确认产品后，继续阅读对应产品的概览与接入指南。具体 SDK 方法和类型见 [TypeScript SDK 参考](/zh-cn/docs/connector-sdk/)。