oomol-lab/open-connector · 上手攻略

• 仓库：oomol-lab/open-connector
• 链接：https://github.com/oomol-lab/open-connector
• 分类：ai
• 作者：Jay
• 更新：2026-07-12

🎯 是什么

OpenConnector 是一个开源的 AI Agent 认证网关（Auth Gateway），用来把 AI Agent 安全地连接到用户的 1000+ 第三方 SaaS 账号（如 GitHub、Gmail、Notion、Slack 等），而不需要把 Provider 的凭证直接交给 Agent。

它本质上是一个中间层：凭证存在网关里，Agent 通过 SDK / CLI / MCP / HTTP / OpenAPI 调用标准化的 Action，由网关负责身份验证、执行请求和日志审计。

类比一下：相当于给 AI Agent 造了一把「万能钥匙」，但这把钥匙不会直接拿到用户的原始密码，而是每次由网关代为授权。

🔍 解决什么问题

AI Agent 普遍面临一个现实问题：它需要访问用户的各种工具（发 GitHub PR、查 Gmail、整理 Notion 数据），但把 API Key 或 OAuth Token 直接塞给 Agent 存在巨大安全隐患：

• Agent 可以随意操作账号
• 无法审计每次调用
• 凭证无法精细化控制（权限范围、有效时间）
• 无法统一管理多个用户的不同连接

OpenConnector 解决的就是这个「凭证边界」问题——Provider 凭证永远在网关后面，网关负责执行策略、控制范围、记录日志，Agent 只调用标准化的 Action。

⚡ 快速安装

最快方式：Docker Compose（一行启动）

# 克隆仓库
git clone https://github.com/oomol-lab/open-connector.git
cd open-connector

# 一键启动（自动拉取最新镜像）
docker compose up

启动后两个地址： - Web 控制台：http://localhost:3000（浏览连接器、配置凭证、查看日志） - API 文档：http://localhost:3000/docs

本地开发（Node.js 22+）

npm install
npm run dev
# API: http://localhost:3000
# 控制台: http://localhost:5173（Vite 开发服务器，代理 API 到 3000）

其他部署方式

⚠️ 版本说明：本文基于 2026-07-12 日采集信息撰写。Docker 镜像标签 latest 对应最新发布版；生产环境建议锁定具体版本号（如 v1.0.0），而非直接用 latest。

📦 核心用法

1. 通过 MCP 接入（推荐给 Agent 用）

OpenConnector 原生支持 MCP 协议，Agent 通过 http://localhost:3000/mcp 访问：

# 在 Claude Code / Cursor 等支持 MCP 的 Agent 客户端中配置
# 以 Claude Code 为例：
claude mcp add open-connector \
  --transport http \
  http://localhost:3000/mcp

调用方无需知道具体 Provider 的认证信息，只管调用 Action。

2. 通过 HTTP API 调用

直接调 REST 接口，不依赖 SDK：

# 列出所有可用 Action
curl http://localhost:3000/v1/actions

# 调用 Hacker News（无需认证）
curl -s -X POST http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

# 查看某个 Provider 支持的 Action
curl "http://localhost:3000/v1/actions?service=github"

3. 连接 GitHub（API Key 方式）

# 存储 GitHub PAT
curl -s -X PUT http://localhost:3000/api/connections/github \
  -H 'content-type: application/json' \
  -d '{"authType":"api_key","values":{"apiKey":"github_pat_xxxxx"}}'

# 执行 Action
curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

4. 连接 Gmail（OAuth2 方式）

# 查看 OAuth 配置信息（含回调 URL）
curl -s http://localhost:3000/api/oauth/configs

# 在 GitHub OAuth App 设置中填入回调：
# http://localhost:3000/oauth/callback

# 存储 OAuth 客户端信息
curl -s -X PUT http://localhost:3000/api/oauth/configs/gmail \
  -H 'content-type: application/json' \
  -d '{"clientId":"xxx","clientSecret":"yyy"}'

# 启动授权流程
curl -s -X POST http://localhost:3000/api/oauth/authorizations \
  -H 'content-type: application/json' \
  -d '{"service":"gmail"}'
# 返回 authorizationUrl，在浏览器打开完成授权

5. 通过 SDK（TypeScript / Node.js）

// 使用 Connector SDK
import { Connector } from '@oomol-lab/connector-sdk';

const connector = new Connector({
  baseUrl: 'http://localhost:3000',
  // runtimeToken: 'your-runtime-token'  // 从控制台生成
});

// 列出可用 Action
const actions = await connector.listActions({ service: 'github' });

// 执行 Action
const result = await connector.execute({
  action: 'github.create_issue',
  input: { title: 'Bug report', body: 'Details...' }
});

🏷️ 典型适用场景

1. Agent 应用需要跨工具操作 用户说「帮我把 GitHub 上这个 Issue 标记为已解决，然后在 Slack 通知团队」，Agent 背后需要同时操作 GitHub API 和 Slack API，OpenConnector 提供统一的 Action 抽象。

2. 多租户 SaaS 连接管理 你的 Agent 产品服务多个用户，每个用户有不同的 Google Workspace / Notion 账号。OpenConnector 负责隔离不同用户的凭证，用 connectionName（如 user_alice_work、user_bob_personal）区分。

3. 企业安全合规 企业要求所有 API 操作必须可审计。OpenConnector 记录每次 Action 的执行日志，支持 token 级别的权限控制，支持只允许特定 Action（如 github.get_current_user，禁止写操作）。

4. 快速验证 Agent + SaaS 集成 不想自己写每个 Provider 的 OAuth 流程？直接连 OpenConnector，10 分钟搞定 Gmail + GitHub + Notion 的 Agent 集成。

⚠️ 坑与注意

1. 自托管运维成本 Docker Compose 方式简单，但生产环境需要考虑：高可用（多副本）、数据备份（SQLite 文件或 D1）、凭证加密（OOMOL_CONNECT_ENCRYPTION_KEY）。如果团队没有 DevOps 能力，直接用 OOMOL 托管版更省心。

2. OAuth 回调需要公网可达 本地开发时，GitHub OAuth 回调需要从公网访问 localhost:3000。开发文档推荐使用 ngrok 或 Cloudflare Tunnel 将本地端口暴露到公网，或使用 GitHub PAT 方式绕过 OAuth 流程。

3. Action 覆盖范围有限 不是所有 1000+ Provider 都支持所有操作。具体某个 Provider 支持哪些 Action，需要 curl http://localhost:3000/v1/actions?service=<provider> 查看。

4. 安全配置要主动开启 默认不加密凭证、不强制 Token 鉴权。生产部署务必设置：

OOMOL_CONNECT_ENCRYPTION_KEY="一个足够长的随机密钥"
OOMOL_CONNECT_ADMIN_TOKEN="admin-token"
OOMOL_CONNECT_ALLOWED_ACTIONS="hackernews.*,github.get_current_user"  # 白名单模式

5. Provider 凭证的所有权 每个 Provider（GitHub、Google 等）的 OAuth App 需要自行注册，不能直接使用 OOMOL 官方注册的 App（涉及商业授权和品牌使用规范）。

🔄 与同类对比

总结：如果你需要开源自托管、凭证不放给 Agent、多租户隔离，OpenConnector 是很好的选择。对标 Composio 的功能集，但代码开源、可自行部署。缺点是目前生态还比较新，企业级支持主要靠社区。

💡 一句话推荐结论

如果你的 AI Agent 需要安全地操作用户的各类 SaaS 账号（GitHub、Notion、Gmail 等），又不想把 API 密钥直接交给 Agent，OpenConnector 是目前最值得评估的开源方案——功能对标闭源的 Composio，可完全自托管。

📚 参考来源

• GitHub README：https://github.com/oomol-lab/open-connector
• Quickstart 文档：https://github.com/oomol-lab/open-connector/blob/main/docs/quickstart.md
• Docker GHCR 文档：https://github.com/oomol-lab/open-connector/blob/main/docs/docker-ghcr.md
• Credentials 文档：https://github.com/oomol-lab/open-connector/blob/main/docs/credentials.md
• Cloudflare 部署文档：https://github.com/oomol-lab/open-connector/blob/main/docs/cloudflare.md
• Fly.io 部署文档：https://github.com/oomol-lab/open-connector/blob/main/docs/fly-io.md
• 云官网：https://oomol.com