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

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-connectorOpenConnector 是一个开源认证网关通过 HTTP API 与 OpenAPI 将 1000 SaaS 服务商连接给 AI Agent。本文详解如何用最少的配置让你的自定义客户端快速接入发现 Action、鉴权、执行请求并借助 OpenAPI 文档生成类型安全客户端。 五大接入通道一览OpenConnector 对外暴露 5 种访问方式HTTP Runtime API/v1/*和 OpenAPI/openapi.json是自定义客户端接入的核心通道端点适用场景MCPPOST /mcp支持 MCP 的 Agent 宿主HTTP Runtime API/v1/*SDK 风格客户端、脚本、直接执行 ActionOpenAPIGET /openapi.json导入 Postman/Scalar生成强类型客户端Action 指南GET /api/actions/:actionId/agent.mdAgent 可读的 Markdown 说明书Web ConsoleGET /浏览器管理凭据、调试 Action当配置了运行时鉴权后/v1/*与/mcp调用方需携带 Bearer TokenAuthorization: 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管理端点用。第二步发现可用的 Actioncurl -s http://localhost:3000/v1/actions # 全部 Action curl -s http://localhost:3000/v1/actions?servicegithub # 按服务商过滤 curl -s http://localhost:3000/v1/actions/github.get_current_user第三步执行 Actioncurl -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本次执行的稳定 IDmeta.actionId被执行的 Actionmeta.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/:serviceNode 运行时还可在配置了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?aliaswork \ -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_progresskey 全局唯一命名空间请用足够随机的值输入嵌套不得超过 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?actionIdgithub.get_current_user三种典型用法导入 API 工具把/openapi.json直接导入 Postman、Scalar 等获得可交互调试面板代码生成用 openapi-generator、orval 等工具生成强类型客户端输入输出结构自动对齐单一 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 端点速查端点说明GET /v1/health健康检查GET /v1/providers/GET /v1/apps服务商 / 已配置应用发现GET /v1/actions/searchAction 关键词搜索GET /v1/apps/authenticated校验指定服务商中哪些已认证POST /v1/proxy/:service透传一次服务商 API 请求需代理授权POST /api/files上传临时中转文件返回downloadUrlGET /api/runs执行审计日志支持service、actionId、caller、ok过滤代理透传请求体示例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?actionIdxxx生成下游强类型契约至此你的自定义客户端已经可以直接通过 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考