OpenConnector：给 AI Agent 造一个「一次授权，通吃百家」的连接器网关

图：OpenConnector 官方横幅（来自项目仓库 assets/openconnector-readme-banner.png）

一、一个具体的场景

你要做一个「AI 助理帮老板处理邮件和日程」的产品。技术难点很快出现：接 Gmail 要走 OAuth，接 Google Calendar 要另一套 scope，接 Slack 是 Bot Token，接 Notion 要 API Key……每个平台一套认证、一套 token 刷新、一套错误处理，然后把这些密钥塞进 Agent 进程。

结果就是：Agent 进程里躺着一堆第三方密钥，任何 prompt injection 都能把它们全部骗走。

OOMOL Lab 开源的 OpenConnector 就是来解决这件事的——一个开源的连接器网关，把「应用授权」和「Agent 执行」这两件事在物理上分开。

二、它是什么

官方定位很直接："Open-source connector gateway for AI agents and an alternative to Pipedream/Composio."

一句话概括：Connect Once. Use Everywhere. 连接用户应用账号一次，然后把一个包含 1000+ Provider、10000+ 预置 Action 的共享目录暴露给 Agent 和应用。

架构上一条链路讲清楚：

AI Agent / App --SDK/CLI/MCP/HTTP--> OpenConnector Gateway
                                      ├─ Credential & OAuth 边界
                                      ├─ Provider Catalog
                                      ├─ 开源 Action 执行器
                                      ├─ Token / Scope / Allow-Block 策略
                                      └─ Run Logs（脱敏）

关键在于那句："Provider secrets stay behind the runtime boundary; agents receive the metadata, safe account labels, and execution results needed for the run." Agent 拿到的是元数据、安全的账号标签和执行结果，密钥从不越过网关边界。

三、一个类比：公司的「印章与档案室」

想象一家公司的印章管理制度：员工要盖章，得填用印申请，说明用途，档案室用章并留下记录。用印的人从不接触印章本身。

OpenConnector 就是这套制度的技术化：Agent 是「用印申请人」，网关是「档案室」，第三方密钥是「印章」。申请里写清楚要调哪个 API、什么参数，档案室审核 scope、检查策略、盖章、留痕。

这与「把 API Key 直接塞进 .env 交给 Agent」的区别，类似于「用印制度」与「把公章放在桌上让人随便盖」的区别。

四、核心能力

连接器目录

覆盖 GitHub、Gmail、Notion、BigQuery、Google Analytics、Supabase、Airtable、Slack 等 1000+ 服务，10000+ 预置 Action。目录不是静态列表——每个 Action 都带可检查的契约：请求/响应 Schema、所需 scope、懒加载的执行器源码。

凭证体系

支持 API Key、OAuth2、自定义凭证、无需认证的 Provider 四类。OAuth 应用配置由你在网关侧管理，Agent 无需参与。

运行控制

连接身份（connection alias）、scope 范围、runtime token、Action 的 allow/block 策略、临时文件 transit、脱敏运行日志——全部在网关内可审计。

四种接入方式

工具	用途
Connector SDK	轻量 TypeScript HTTP 客户端，托管版与自托管版同一套 API
oo CLI	本地 Agent 中继，oo connector 可搜索、检视并执行 Action
MCP	通过 http://localhost:3000/mcp 把应用 Action 暴露给支持 MCP 的 Agent 宿主
HTTP / OpenAPI	直接调 /v1/actions/*，或查看生成的 /openapi.json

部署自由度

• 本地 Docker 或 Node.js：SQLite 或 PostgreSQL 状态，本地或 S3 兼容 transit 存储
• OOMOL 托管运行时：开箱即用，无需自己配 OAuth 应用
• 其他托管平台：Cloudflare Workers + D1 + R2、Fly.io、RepoCloud、nibrun、NEXUS AI、Pethost 等

这里有个对团队很关键的设计承诺："Use the same provider ids, Action ids, schemas, and contracts across open-source and commercial SaaS deployments." 开源自托管和商业 SaaS 用同一套 ID 和契约，意味着迁移时不用改 Agent 代码。

Web Console

自带管理控制台：浏览连接器目录、配置凭证、创建 runtime token、查看运行概况（可用 Provider、可执行 Action、近期失败、工具调用趋势、最近调用）。

五、上手门槛

Docker 一条命令：

docker compose up -d

compose 默认拉取 ghcr.io/oomol-lab/open-connector:latest 预构建镜像，暴露 3000 端口，状态存于 connector-data 卷。若要从源码构建，加一层 overlay：

docker compose -f docker-compose.yml -f docker-compose.build.yml up --build

（构建使用 docker/Dockerfile，带 entrypoint.sh。）

关键环境变量：OOMOL_CONNECT_DATA_DIR、OOMOL_CONNECT_DATABASE_URL、OOMOL_CONNECT_ORIGIN、OOMOL_CONNECT_ENCRYPTION_KEY（加密密钥必须自己设定）、OOMOL_CONNECT_ADMIN_TOKEN。

也可以不用 Docker，直接用 Node.js 22+ 跑（仓库有 Bun 相关配置 .bun-version 与 bun 脚本）。Cloudflare 部署走 wrangler 配置。

硬件要求不高：CPU 1 核起、内存 1-2GB、磁盘 1GB，不需要 GPU（它是网关不是推理服务）。

Web UI：有，web/ 目录是独立的 Vite + React 管理控制台。

六、争议与局限

规模数字需要打折看。 「1000+ Providers / 10000+ Actions」是目录规模，但每个 Action 的实际质量、执行器成熟度并不均衡，实际接入时仍要逐个验证。

开源与商业版的边界需实测。 虽然官方承诺 ID、Schema、契约一致，但自托管版本在托管版具备的某些能力（如更完整的 OAuth 应用托管）上可能有差距，迁移前建议逐项核对。

OAuth 应用配置仍是门槛。 自托管模式下，Provider 的 OAuth 应用需要你自己申请、配置 redirect URI 并填进网关——这是接入 1000 个服务中最耗时的一环，只是被集中到了一处而非消除。

Node.js 22+ 是硬要求。 且仓库混用 Bun 脚本与 Node 依赖，跨环境（尤其沙箱 Agent 环境）部署时容易踩到工具链差异。

加密密钥与管理员 Token 由你保管。 OOMOL_CONNECT_ENCRYPTION_KEY 丢失意味着已存凭证无法解密；OOMOL_CONNECT_ADMIN_TOKEN 泄漏等于网关沦陷。

中文文档有但覆盖不全。 README 提供简中、繁中、日、韩、俄、法、西多语版本，但深度技术文档仍以英文为主。

七、行业意义

Composio、Pipedream 这类「Agent 连接器」服务在 2025-2026 年被证明是 AI Agent 落地的关键一环——但它们是闭源 SaaS，凭证托管在第三方，数据主权和合规成为企业采购的实质障碍。

OpenConnector 的价值在于提供了开源 + 自托管 + 契约兼容这条路径：企业可以自己持有凭证，自己决定数据流向，同时保留随时切到托管版的选择。这在金融、政企、医疗等对数据主权敏感的行业是决定性的。

它的技术路径也代表了一个共识：Agent 不应该直接持有第三方密钥。这与 Nasiko 的「Agent 只拿一小时身份 token」是同一个安全哲学在不同层面的落地——一个管模型供应商密钥，一个管应用 OAuth 凭证。

Apache-2.0 协议、TypeScript + Vite + React 技术栈、GHCR 预构建镜像、多平台部署选项（Cloudflare Workers / Fly.io / Docker / Node.js）——工程完成度在同类开源项目里属上游水平。

对团队的现实价值：把「接 20 个 SaaS 要写 20 套认证逻辑」压缩成一次网关部署；对产品：多租户 OAuth 与策略审计有了现成底座。