核心概念

Open Connector 围绕几个关键实体构建。理解它们之间的关系是高效使用系统的基础。

实体模型

组织（Organization）
  └─ 项目（Project）
       ├─ Agent API Key（x-api-key）
       ├─ 认证配置（Auth Config）
       │    └─ OAuth 应用凭证（Client ID + Secret）
       └─ 连接（Connection）
            └─ 加密 Token（属于某个用户）

组织（Organization）

组织是顶层的多租户隔离单元。每个注册用户都可以创建一个或多个组织。一个组织可以包含多个项目，并可以邀请多个团队成员。

组织级别的数据（如账单、成员角色）与项目级别的运营数据（连接、凭证）相互隔离。Agent API Key 仅能访问其所属项目的数据，无法跨组织访问其他任何内容。

项目（Project）

项目是一个逻辑命名空间，用于将某个 Agent 工作流或产品功能所需的所有内容分组管理：

一组 认证配置（您注册的 OAuth 应用）
一组连接（已授权的用户账户）
一组 Agent API Key（供 Agent 使用的凭证）

项目之间相互隔离。属于项目 A 的 Agent Key 无法读取项目 B 的连接。这使得您可以为不同的 Agent 工作流（例如"客户支持机器人"和"代码审查助手"）维护独立的权限边界。

认证配置（Auth Config）

认证配置存储用于某个特定服务的 您的 OAuth 应用凭证（Client ID 和 Client Secret），以及相应的配置参数（请求的 Scope、回调 URL 等）。

认证配置是静态配置 — 它代表一个 OAuth 应用注册，可以为多个用户的连接服务。可以将它理解为"我的项目使用这些凭证对接 GitHub"。

{
  "id": "ac_01j9abc123",
  "connectorId": "github",
  "displayName": "GitHub OAuth（生产环境）",
  "config": {
    "clientId": "Iv1.xxxxxxxxxxxxxxxx",
    "scopes": ["repo", "read:user", "user:email"]
  }
}

Client Secret 经过加密存储，永远不会通过 API 返回。认证配置创建后，只能更新它，而无法读取 Secret 本身。

连接（Connection）

连接代表一个特定用户对某个认证配置完成授权后的结果。它包含经过 AES-256-GCM 加密存储的 OAuth Access Token 和 Refresh Token。

每个连接都关联：

一个来自您系统的 userUuid（用于标识哪个用户完成了授权）
一个 authConfigId（代表所使用的 OAuth 应用）
加密存储的 Token（Agent 永远看不到）
一个状态（详见下表）

连接内部使用以下原生（native）状态值（另有一个独立的 disabled 标志）：

原生状态	含义
`pending`	OAuth 流程已发起，用户尚未授权
`active`	已获取并存储 Token；可用于工具调用
`error`	连接尝试失败
`expired`	Token 已过期且刷新失败（用户需重新授权）
`dropped`	连接已被丢弃，不再可用
`revoked`	被用户或管理员显式断开

兼容 Composio 的 API 面将这些状态映射为线路（wire）状态（大写）— 这正是 SDK 和 HTTP 响应中显示的内容：

原生	线路
`pending`	`INITIATED`
`active`	`ACTIVE`
`error`	`FAILED`
`expired` / `dropped`	`EXPIRED`
`revoked`	`REVOKED`
（`disabled = true`）	`INACTIVE`
（其他 / 未知）	`INITIALIZING`

当 Agent 调用工具时，它在请求中传递 connectionId。Open Connector 解密 Token，将其注入到对第三方 API 的出站请求中，然后将响应代理返回。

工具调用（Tool Call）

工具调用是由 Agent 通过代理端点发起的一次命名动作执行请求。每次工具调用均经过以下处理：

认证：验证 x-api-key，解析项目和组织的作用范围
授权：确认请求的连接确实属于该项目
凭证注入：从保险库解密 Token 并注入到出站请求的请求头中
代理执行：向第三方 API 发送请求（例如 POST https://api.github.com/repos/.../issues）
审计记录：将包含连接 ID、动作名称、时间戳以及前一条审计记录哈希值的结构化事件写入审计日志

Agent 只能看到 API 响应结果，永远看不到原始凭证。

数据流全览

以下是一次完整的工具调用请求从 Agent 到第三方 API 的完整数据流：

Agent（AI 推理过程）
  │
  │  POST /composio/api/v3.1/tools/execute/GITHUB_CREATE_AN_ISSUE
  │  Header: x-api-key: oc_a1b2c3d4e5...
  │  Body: { connected_account_id, arguments: { owner, repo, title } }
  │
  ▼
Open Connector API 服务器
  ├─ 1. 解析 API Key → projectId + orgId
  ├─ 2. 从数据库加载连接（验证 projectId 匹配）
  ├─ 3. 从加密保险库解密 OAuth Token
  ├─ 4. 调用 GitHub API（注入 "Authorization: Bearer <token>"）
  ├─ 5. 写入审计日志（哈希链）
  └─ 6. 将 GitHub 响应代理返回给 Agent
  │
  ▼
GitHub API
  └─ 返回创建的 Issue 数据
  │
  ▼
Agent（收到 Issue 信息，从未接触过 Token）

实体关系速查

实体	作用范围	数量关系
组织	顶层多租户隔离	每个用户可有多个
项目	组织内的工作空间	每个组织可有多个
Agent API Key	项目范围的认证凭证	每个项目可有多个
认证配置	某服务的 OAuth 应用注册	每个项目每个服务可有多个
连接	某用户对某认证配置的授权	每个认证配置可有多个（一个用户一个）
工具调用	代理到第三方 API 的一次动作执行	每个连接可有无限次

On this page