企业官网建设流程全解析

OpenConnector HTTP API与OpenAPI详解：自定义客户端接入实战

【免费下载链接】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 是一个开源认证网关，通过 HTTP API 与 OpenAPI 将 1000+ SaaS 服务商连接给 AI Agent。本文详解如何用最少的配置，让你的自定义客户端快速接入：发现 Action、鉴权、执行请求，并借助 OpenAPI 文档生成类型安全客户端。

🧭 五大接入通道一览

OpenConnector 对外暴露 5 种访问方式，HTTP Runtime API（/v1/*）和 OpenAPI（/openapi.json）是自定义客户端接入的核心：

当配置了运行时鉴权后，/v1/*与/mcp调用方需携带 Bearer Token：

Authorization: Bearer <runtime-token-or-jwt>

完整端点清单见官方文档 docs/runtime-api.md。

🚀 最快启动：5 分钟跑通第一个 Action

第一步：克隆仓库并启动本地运行时

git clone https://gitcode.com/gh_mirrors/op/open-connector cd open-connector npm install npm run dev

服务默认监听http://localhost:3000。如果开启了鉴权，配置OOMOL_CONNECT_RUNTIME_TOKEN（执行/v1用）与OOMOL_CONNECT_ADMIN_TOKEN（管理端点用）。

第二步：发现可用的 Action

curl -s http://localhost:3000/v1/actions # 全部 Action curl -s "http://localhost:3000/v1/actions?service=github" # 按服务商过滤 curl -s http://localhost:3000/v1/actions/github.get_current_user

第三步：执行 Action

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

仓库内置的完整示例在 examples/local-http/ 目录，例如 github.ts 展示了「配置连接 → 执行 Action」的最小流程，公共工具函数（Bearer 头拼装、JSON 抓取）封装在 client.ts。

📦 统一响应包：所有 /v1 接口同一套结构

/v1所有响应都是统一 JSON 信封，客户端解析逻辑只需写一次：

{ "success": true, "message": "OK", "data": {}, "meta": {} }

执行类响应还会在meta中附带审计信息：

• meta.executionId：本次执行的稳定 ID
• meta.actionId：被执行的 Action
• meta.auditPersisted：审计记录是否落库

常见错误码：未知 Action 返回404 unknown_action，输入或幂等键不合法返回400 invalid_input，连接未被授权返回403 connection_not_allowed。

🔐 鉴权与 Runtime Token：为每个调用方发独立钥匙

在 Web Console 中可为不同调用方创建独立 Runtime Token，每个 Token 拥有独立的 Action 允许/拒绝规则、代理授权和连接范围：

• Token 创建与管理的后端接口为POST /api/runtime-tokens等管理端点
• 持久化 Token 默认allowedProxies为空，需显式授权后才能调用/v1/proxy/:service
• Node 运行时还可在配置了OOMOL_CONNECT_JWKS_URI、OOMOL_CONNECT_JWT_ISSUER、OOMOL_CONNECT_JWT_AUDIENCE三个环境变量后，接受JWT Access Token与 Runtime Token 并存

💡 实践建议：给 Agent、CI 脚本、Web 端各发一个 Token，用策略字段（allowedActions/blockedActions）做最小权限隔离。

🔀 多连接切换：一个服务商多个账号

同一服务商可以配置多个命名连接（如default与work），执行时用alias指定目标：

# 方式一：请求头 curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \ -H 'x-oo-connector-alias: work' \ -H 'content-type: application/json' \ -d '{"input":{}}' # 方式二：query 参数 curl -s -X POST "http://localhost:3000/v1/actions/github.get_current_user?alias=work" \ -H 'content-type: application/json' \ -d '{"input":{}}'

alias就是/v1中对「命名连接」的叫法；MCP 工具里同一概念叫connectionName。省略 alias 时默认走default连接——运行时不会静默回退到其他账号，找不到即报错。

🔁 幂等重试：Idempotency-Key 防重复执行

POST /v1/actions/:actionId支持可选的Idempotency-Key请求头，适合对「发邮件、建任务」这类有副作用的 Action 做安全重试：

IDEMPOTENCY_KEY=$(openssl rand -hex 16) curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \ -H "Idempotency-Key: $IDEMPOTENCY_KEY" \ -H 'content-type: application/json' \ -d '{"input":{}}'

关键行为：

• 同一 key 重放时，24 小时内返回原始 HTTP 状态码和响应体（含原executionId）
• 同 key 但 Action/输入/连接不同 →409 idempotency_key_conflict
• 原请求还在执行中 →409 idempotency_request_in_progress
• key 全局唯一命名空间，请用足够随机的值；输入嵌套不得超过 100 层

⚠️ 幂等提供的是「去重 + 响应重放」，不保证服务商侧 exactly-once。

📄 OpenAPI 详解：/openapi.json 怎么用

运行时内置 OpenAPI 3.1 文档生成器，代码位于 src/server/api/openapi.ts，路由挂载在 src/server/connect-server.ts：

# 完整文档：所有服务商、所有 Action curl -s http://localhost:3000/openapi.json # 强类型单 Action 文档（体积更小，推荐按需生成） curl -s "http://localhost:3000/openapi.json?actionId=github.get_current_user"

三种典型用法：

1. 导入 API 工具：把/openapi.json直接导入 Postman、Scalar 等，获得可交互调试面板
2. 代码生成：用 openapi-generator、orval 等工具生成强类型客户端，输入输出结构自动对齐
3. 单一 Action 契约：?actionId=参数生成只含该 Action 的紧凑文档，适合给下游系统分发

💡 生成文档中已内置幂等语义描述（重放窗口、冲突语义），代码生成出来的客户端会自动带上Idempotency-Key参数位。

浏览器调试更省事：访问/docs即可打开内置的 Scalar 交互文档页（页面标题「OOMOL Connect API Reference」），直接在线调用接口。

🤖 附赠：Agent 可读的 Action 指南

每个 Action 都有一份本地 Markdown 说明书，包含输入 Schema、所需 scopes、服务商权限、当前连接身份与请求示例：

curl -s http://localhost:3000/api/actions/github.get_current_user/agent.md

在 Web Console 的 Action 详情页，还可以一键复制 cURL、TypeScript、Agent Prompt 三种示例。

📁 更多 Runtime 端点速查

代理透传请求体示例（endpoint必须是相对路径）：

{ "endpoint": "/provider/path", "method": "GET", "query": { "limit": "10" }, "headers": { "accept": "application/json" }, "body": { "name": "example" } }

成功响应的data内含status、headers、data三段，服务商密钥始终保留在网关内，不会下发给调用方。

✅ 接入 Checklist

• 本地或自建部署已启动（Docker / Node / Cloudflare Workers 均可，Cloudflare 部署步骤见 docs/cloudflare.md）
• 通过管理端点或 Console 配置好服务商连接
• 为每个调用方创建独立 Runtime Token，按最小权限设置策略
• 客户端统一解析{success, message, data, meta}信封
• 有副作用的 Action 一律带Idempotency-Key重试
• 用/openapi.json?actionId=xxx生成下游强类型契约

至此，你的自定义客户端已经可以直接通过 HTTP API 调用 1000+ 服务商的 10000+ 预置 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