---
title: 核心概念
description: 分清三個 Connector 產品共享的概念，以及各自使用的身分、權限與執行模型。
lang: zh-TW
canonical_url: https://oomol.com/zh-tw/docs/core-concepts/
markdown_url: https://oomol.com/zh-tw/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-tw/docs/access-control/)和[團隊管理](/zh-tw/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-tw/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-tw/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-tw/docs/connector-sdk/)。