OpenConnector 使用指南

一、平台介绍

OpenConnector 是一款开源的 AI Agent 连接器网关，可视为 Composio 的优秀替代方案。其核心特性如下：

• 海量连接能力：一次绑定第三方账号，即可给 Agent 开放超过 1000+ 服务商、10000+ 预置工具动作。
• 凭据安全隔离：敏感凭证加密存储于网关内部，不直接暴露给 Agent 进程。
• 生态兼容性强：开源版与 OOMOL 商业 SaaS 共用一套动作契约（Schema），支持本地/云端多部署模式。

二、核心功能详解

1. 海量连接器库

覆盖主流开发平台及工具，例如 GitHub、Gmail、Notion、Slack、Airtable、BigQuery 等；完整支持以下三类服务商接入方式：

• API Key 授权
• OAuth2 标准认证
• 免鉴权服务

2. 多接入通道

提供多样化的集成接口与客户端，适配不同使用场景：

• SDK (TS)：轻量级 TypeScript 客户端，完美适配自托管或 OOMOL 托管环境。
• oo CLI：命令行工具，供本地 Agent 直接调用中继服务。
• MCP：原生对接 MCP（Model Context Protocol）标准 Agent 宿主。
• HTTP / OpenAPI：提供标准的 /v1/actions 接口文档，支持直接发起 HTTP 请求调用动作。

3. 安全运行管控

内置企业级安全防护机制，包括凭据加密存储、权限 Scope 隔离、运行时 Token 管理以及日志脱敏处理等策略；同时具备临时文件中转站功能。

4. 可视化控制台

提供本地 Web 面板（默认端口 http://localhost:3000），支持以下操作：

• 服务商管理与凭据配置
• 实时监控运行时的 Token 状态
• 动作调试与调用统计查询
• 失败记录追踪与分析

5. 多部署方案

灵活适配不同资源环境，无需被云厂商绑定：

• 本地模式：Docker / Node.js 直接安装。
• 云原生模式：Fly.io、Cloudflare Workers (配合 D1/R2)。
• 托管服务：直接使用 OOMOL Runtime 托管平台。

6. 配套桌面端 Wanta

• 拥有独立连接器库，无需部署网关服务器即可使用。
• 支持自然语言驱动跨工具操作，开箱即用体验好。

三、适用人群与场景

1. 个人 / 独立开发者：构建本地 Agent 或 AI 工具开发时，不希望将第三方密钥直接交给 Agent 进程处理。
2. AI 产品团队：需要给自家大模型应用快速打通各类 SaaS 平台，统一鉴权层，并支持私有化部署需求。
3. 创业 / 中小企业：缺乏自研连接器开发成本预算，需快速接入 OAuth 服务的场景。
4. 隐私敏感型组织：团队有严格合规要求，必须将第三方凭据保留在自有服务器内（自托管）。
5. MCP 生态使用者：希望利用标准化协议打通各类线上工具赋能本地 Agent 的团队或个人。

四、免费 & 付费模式说明

💰 方案 A：开源自托管 (永久免费)

• 授权许可：Apache 2.0，无功能阉割版源码开放。
• 包含内容：全部连接器库、动作接口、Web 控制台、SDK/MCP/HTTP 能力均完全解锁。
• 成本构成：仅需承担服务器及云资源费用，无任何软件授权费。

💳 方案 B：OOMOL 托管商业 SaaS (按需付费)

• 核心价值：免除自建运维压力（无需维护数据库、SSL、Node），提供现成 OAuth 鉴权通道以加速产品上线。
• 迁移优势：与开源版接口完全兼容，后期可随时平滑迁移至私有化部署。
• 团队协作：配套 Wanta 桌面端使用托管服务时，支持团队多人共享连接权限。
• 咨询方式：官方文档暂无独立定价 URL，建议直接联系 OOMOL 官网客服获取报价。

📊 成本总结对比

维度自托管 (开源)商业托管 (SaaS)适用对象个人 / 技术团队 / 有运维能力的企业无运维团队 / 追求快速上线的产品组软件费用零元（仅硬件成本）付费订阅/按量

注：自托管意味着您需要自行维护服务器环境；若使用 Cloudflare 免费版需注意其调用和存储限额，重度场景建议扩容。

五、快速上手步骤指南

🚀 方式 1：Docker 本地启动 (新手推荐)

适用于大多数个人开发者和测试环境。

Step 1: 拉取镜像并启动

bash

# 简单启动（使用默认配置文件）
docker compose up

# 若需源码构建，请使用以下命令
docker compose -f docker-compose.yml -f docker-compose.build.yml up --build
# 简单启动（使用默认配置文件）
docker compose up

# 若需源码构建，请使用以下命令
docker compose -f docker-compose.yml -f docker-compose.build.yml up --build

Step 2: 访问控制台与文档

• Web 面板：http://localhost:3000
• API 文档：http://localhost:3000/docs

Step 3: 测试无鉴权动作 (以 HackerNews 为例)

bash

curl -s -X POST http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'
curl -s -X POST http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

Step 4: 绑定服务商 (以 GitHub API Key 为例) 请先准备好您的 GitHub Personal Access Token。

bash

curl -s -X PUT http://localhost:3000/api/connections/github \
  -H 'content-type: application/json' \
  -d '{"authType":"api_key","values":{"apiKey":"你的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"}}'

Step 5: 调用已绑定的工具动作 (获取当前用户信息)

bash

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

☁️ 方式 2：云端部署方案

• Cloudflare Workers：通过 Wrangler 配置 + D1 数据库迁移，执行 npm run deploy:cloudflare。
• Fly.io：基于 Docker 镜像推送至平台并绑定持久化 SQLite 卷即可运行。
• OOMOL 托管服务：直接在注册平台获取 API Key，无需运维服务器节点。

💻 方式 3：无代码体验 Wanta (桌面端)

1. 下载 Wanta 桌面客户端。
2. 登录 OOMOL 官方账号并绑定各类 SaaS（如 Slack, Notion）。
3. 直接开始操作：无需部署网关，通过自然语言指令跨工具进行任务管理。

六、注意事项与避坑指南

在开发过程中请重点关注以下风险点与建议：

🔒 1. 安全风险管控

• 凭据隔离原则：API Key 及 OAuth 密钥仅存储于 Runtime 内部，严禁前端代码或 Agent 直接持有原始服务商凭据。
• 生产环境限制：必须配置 Action 黑白名单策略，严格限制高危操作（如删除文件、退款等）。
• 开发规范：禁止将密钥硬编码在代码仓库中提交至 Git，务必使用环境变量管理。

💸 2. 部署与成本考量

• 运维责任：选择自托管模式需自行解决数据库维护、SSL 证书更新及系统升级问题。
• 云资源限制：若选 Cloudflare 免费版搭建，请注意其免费配额；超出部分必须付费扩容。

📜 3. 品牌与合规

• 标识使用：内置服务商的 Logo 和名称仅用于识别功能用途，不代表官方授权。若在商用产品展示中使用相关商标，请务必查阅第三方协议合规性。
• 日志脱敏：务必开启日志脱敏配置（Masking），避免明文留存用户隐私数据，以满足 GDPR/个人信息保护法等要求。

🌐 4. 网络与环境限制

• 跨境鉴权延迟：部分海外服务商的 OAuth 流程在国内直连可能超时，建议优化内网代理或使用国内替代连接器方案。
• 版本锁定：生产环境发布时请固定 Docker Image Tag（如 1.0.2），避免使用 latest 标签以防破坏性更新导致服务中断。

🔌 5. MCP与迁移适配

• MCP 本地接入：默认地址为 http://localhost:3000/mcp，部分第三方 Agent 宿主若报错超时，请手动调整 Socket Timeout 参数。
• Schema 兼容性：开源版与托管版共用 Schema，但在重新创建 OAuth Client Config（OAuth 客户端配置）时请注意版本差异。