企业官网建设流程全解析

OpenConnector架构深度解析：网关如何隔离凭据并执行1000+ Provider Action

【免费下载链接】open-connectorOpen-source auth gateway connecting 1000+ SaaS providers to AI agents through SDK, CLI, MCP, HTTP, and OpenAPI.项目地址: https://gitcode.com/gh_mirrors/op/open-connector

OpenConnector 是一个开源连接器网关（Auth Gateway），让 AI Agent 通过 SDK、CLI、MCP、HTTP 和 OpenAPI 五种方式安全接入 1000+ SaaS 服务商的 10,000+ 预构建 Action。它的核心价值在于凭据隔离：服务商的 API Key 和 OAuth Token 永远留在网关内部，Agent 只拿到元数据、安全的账户标签和执行结果——既能让 Agent 真正"用上"用户的 Gmail、GitHub、Notion 等应用，又不必把敏感凭据交给 Agent 进程。

全景图：一条请求要穿过哪几层？

理解这个架构，先记住一句话：Agent 不直接碰服务商，一切经过网关。一次 Action 调用的链路如下：

AI Agent / 应用 │ SDK / CLI / MCP / HTTP ▼ OpenConnector 网关 ├─ ① 目录查找：Action 是否存在？ ├─ ② 策略检查：该调用方被允许执行吗？ ├─ ③ 连接解析：选用哪个用户连接？（凭据在此解锁，不离开网关） ├─ ④ 懒加载执行器：按需加载对应 Provider 的执行代码 ├─ ⑤ 守卫网络请求：防 SSRF、防凭据外泄 └─ ⑥ 审计日志：记录脱敏的运行摘要 ▼ 1,000+ Provider（Gmail、GitHub、Notion …）

对应的模块划分非常清晰：

仓库中实际收录了1452 个 Provider 目录，每个目录结构统一：definition.ts（服务商元数据与认证方式）、actions.ts（Action 契约）、executors.ts（执行逻辑），这种一致性正是"1000+ Provider"可维护性的来源。

凭据隔离：API Key 和 OAuth Token 如何不泄漏

这是整个架构最关键的设计，靠三个机制配合完成。

1. 存储层：AES-256-GCM 加密落库

凭据从不以明文躺在磁盘上。网关使用scrypt派生密钥、AES-256-GCM 加密每一条凭据记录，密文带enc:v1:前缀自识别，解密时先校验认证标签——实现见 secret-codec.ts。配置方式很简单，设置环境变量OOMOL_CONNECT_ENCRYPTION_KEY即可启用（详见 docs/credentials.md）：

未配置密钥时，运行时会打印启动警告并以明文模式工作——这是留给本地开发的"逃生通道"，生产环境必须关闭。

支持四种认证形态：no_auth（免认证，如 HackerNews）、api_key、custom_credential（任意自定义字段）、oauth2（完整授权码流程 + 自动令牌刷新，实现在 src/oauth/oauth-credential-refresh-service.ts）。字段契约由每个 Provider 的auth元数据声明，未知字段直接拒绝而非静默存储，保证凭据表单与定义"漂移即失败"。

2. 运行层：凭据只以回调形式注入

注意 action-runner.ts 中构建执行上下文的细节：传给 Provider 执行器的不是一个"凭据对象"，而是一个getCredential回调函数。也就是说，执行器需要凭据时才在网关进程内惰性解锁，凭据值从头到尾不出网关边界，Agent 侧只能看到"连接别名 + 安全账户标签"（如 Gmail 账号名），拿不到任何 Token。

3. 网络层：守卫请求拦截凭据外泄

即使执行器逻辑有漏洞，src/core/guarded-fetch.ts 也会在出网前兜底：

• 防 SSRF：请求前校验 DNS 解析地址，拦截回环、内网（RFC 1918）、链路本地与云元数据地址，防止恶意 URL 把凭据导向内网；
• 防凭据外泄：当 3xx 重定向跨源时，自动剥离 40+ 种凭据头（Authorization、X-Api-Key、各服务商私有认证头等），跨源跳转无法"顺走"服务商凭据；
• 重定向限跳：最多 20 跳，与 fetch 规范默认行为对齐。

同样的守卫思路也覆盖了 WebSocket（guarded-websocket.ts）与 IP 分类（request.ts）。

Action 执行管线：从调用到审计的完整闭环

所有调用方（HTTP、MCP、未来本地调用）共用同一个执行边界ActionRunner，流程保证任何入口行为一致：

1. 查目录：Action 不存在直接拒绝，并记unknown_action警告；
2. 策略判定：先执行 Action 级 allow/block 策略，再做连接级判定——策略服务见 src/core/action-policy.ts；
3. 连接解析：选定连接后，若 Action 不可本地执行或属于 Marketplace 托管类型，走对应分支，否则懒加载执行器（providerLoader.loadActionExecutor）——1452 个 Provider 的代码按需载入，冷启动不背全量包袱；
4. 输入校验 + 执行：src/core/execution.ts 先用 JSON Schema 校验输入，再调用执行器；
5. 审计落库：每次运行生成脱敏摘要（summarizeForRunLog）写入 Run Log，包含执行 ID、耗时、策略判定、输入/输出摘要，Web 控制台可直接复核最近运行。

运行时令牌：给 Agent 发"有限权限的钥匙"

网关通过运行时令牌（Runtime Token）把权限收紧到调用方粒度：每个令牌可以限定可执行的 Action 范围与可用的连接范围。生产部署中，建议给每个 Agent/应用单独签发令牌，而不是共用一个全权限凭据——控制台即可创建，配套端点文档在 docs/runtime-api.md。

多种接入方式，同一份契约

同一个 Action 契约（ID、Schema、所需 Scope）在所有接入方式中保持一致：

• SDK：TypeScript 薄 HTTP 客户端，适合应用代码直连；
• oo CLI：本地 Agent 中继，可搜索、查看并执行 Action；
• MCP：/mcp端点暴露给支持 MCP 的 Agent 宿主；
• HTTP / OpenAPI：直接调/v1/actions/*，或查看自动生成的/openapi.json。

部署形态同样灵活：本地 Docker/Node（SQLite 或 PostgreSQL）、Fly.io、Cloudflare（Workers + D1 + R2），或托管运行时。同一套契约意味着从开源自建到商业托管可以平滑迁移，Cloudflare 部署的完整步骤见 docs/cloudflare.md。

验证你的网关：看运行概览

部署完成后，Overview 页面是验证架构各层是否健康的最快方式：运行时就绪状态、可用 Provider 数、可执行 Action 数、最近失败、工具调用趋势一览无余——目录层、执行层、审计层是否正常工作，一张图就能判断。

想读源码？从这 5 个文件开始

总结：为什么说它是"凭据隔离"而不只是"API 聚合"

很多连接器项目本质是 API 转发器，而 OpenConnector 架构真正的差异化在于边界感：凭据边界（加密存储 + 回调注入 + 出网守卫三层防御）、权限边界（运行时令牌 + Action/连接级策略）、审计边界（每次执行必留脱敏日志）。对新手而言，记住这张心智图即可——Agent 拿着"有限权限的钥匙"来敲门，网关验明正身、按需开锁、看着它干活、记好台账，而真正的钥匙串从不离开钥匙柜。

这套设计让团队可以放心地把 Gmail、GitHub、Notion 等应用交给 AI Agent 使用，同时把敏感凭据留在可审计的运行时之内。

【免费下载链接】open-connectorOpen-source auth gateway connecting 1000+ SaaS providers to AI agents through SDK, CLI, MCP, HTTP, and OpenAPI.项目地址: https://gitcode.com/gh_mirrors/op/open-connector