OOMOL OpenConnector 自部署指南

OOMOL OpenConnector 是开源、可自部署的应用连接服务。适合需要让 Agent 或内部工具调用真实外部服务，同时把 provider 凭据、权限和执行记录留在自己环境里的场景。它通过 MCP、HTTP 暴露 GitHub、Gmail、Notion、Hacker News、Ably、Abstract、A-Leads 等服务的类型化 action。

Agent 只能看到 schema、scope、执行状态和安全的账号标签；原始 provider token、action 权限和执行记录由你的部署边界管理。

它提供什么

• 一个 runtime，通过 MCP、HTTP、OpenAPI 和 Web 控制台暴露 provider actions。
• 凭据存储，支持 API key、自定义凭据、OAuth2 连接和无需认证的 provider。
• 类型化 action schema，让 Agent 在调用前先知道自己能调用什么。
• 连接身份和 scope，让用户和 Agent 都能看到 action 会以哪个账号执行。
• 临时文件中转，供需要文件 URL 的 action 使用。
• 最近运行记录，包含脱敏后的输入摘要和 provider 错误。
• provider catalog 和本地 executor；executor 只在 action 被使用时才加载。

先选择 runtime 的运行位置，再配置存储、访问控制、provider 连接，以及提供给 Agent 使用的 MCP 或 HTTP 入口。

选择部署方式

准备 runtime

部署前先确定这些值：

Runtime 数据库需要按敏感文件处理。未设置 OOMOL_CONNECT_ENCRYPTION_KEY 时，OOMOL OpenConnector 仍可运行，但 provider secret 会存放在敏感的本地 SQLite 文件中。

使用 Docker Compose 运行

先克隆 OOMOL OpenConnector 仓库，进入项目目录，再启动 runtime：

git clone https://github.com/oomol-lab/open-connector.git
cd open-connector
docker compose up --build

打开 Web 控制台：

http://localhost:3000

打开生成的 API 文档：

http://localhost:3000/docs

用一个无需认证的 action 验证 runtime：

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

Docker Compose 会把运行时状态保存到 connector-data volume。容器内的 SQLite 路径是：

/app/data/connect.sqlite

私有服务器部署时，至少在启动前设置 admin token 和 encryption key：

OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_ENCRYPTION_KEY="replace-with-a-long-random-secret" \
docker compose up --build

如果 runtime 通过公开域名或 tunnel 暴露，还要设置公开 origin：

OOMOL_CONNECT_ORIGIN="https://connect.example.com" \
OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_ENCRYPTION_KEY="replace-with-a-long-random-secret" \
docker compose up --build

Docker 镜像会在容器内绑定 0.0.0.0。外部访问范围由宿主机防火墙、反向代理或容器平台控制。

保护管理面和运行面

管理端 HTTP client 调用 /api、/docs 或 Web 控制台时发送：

Authorization: Bearer replace-with-an-admin-token

在 Web 控制台 Access 页面为 Agent 和 SDK 类 client 创建 runtime token。token 只显示一次，SQLite 中只保存 hash。

也可以通过管理 API 创建：

curl -s -X POST http://localhost:3000/api/runtime-tokens \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"name":"Claude Desktop"}'

之后 runtime client 调用 /v1 或 /mcp 时发送：

Authorization: Bearer oct_...

为了启动脚本和向后兼容，仍然可以使用 OOMOL_CONNECT_RUNTIME_TOKEN：

OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_RUNTIME_TOKEN="replace-with-a-runtime-token" \
docker compose up --build

限制 Agent 可以执行的 actions：

OOMOL_CONNECT_ALLOWED_ACTIONS="hackernews.*,github.get_current_user" docker compose up --build

即使较大的 allowlist 包含某些 actions，也可以单独阻止它们：

OOMOL_CONNECT_ALLOWED_ACTIONS="github.*" \
OOMOL_CONNECT_BLOCKED_ACTIONS="github.delete_repository" \
docker compose up --build

连接 API-key provider

GitHub 是一个简单的 API-key 示例，因为它可以使用 personal access token。

查看 provider 契约：

curl -s http://localhost:3000/api/providers/github \
  -H 'authorization: Bearer replace-with-an-admin-token'

保存默认 GitHub 连接：

curl -s -X PUT http://localhost:3000/api/connections/github \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"authType":"api_key","values":{"apiKey":"github_pat_..."}}'

通过 runtime 调用 GitHub：

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

查看已配置的连接，以及会暴露给 Agent 的安全账号身份：

curl -s http://localhost:3000/api/connections \
  -H 'authorization: Bearer replace-with-an-admin-token'

命名连接

同一个 provider 需要多个账号时，添加 connectionName：

curl -s -X PUT http://localhost:3000/api/connections/github \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"authType":"api_key","connectionName":"work","values":{"apiKey":"github_pat_..."}}'

执行时选择该账号：

curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \
  -H 'authorization: Bearer oct_...' \
  -H 'x-oo-connector-alias: work' \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

也可以使用 alias query 参数。

连接 OAuth provider

OAuth provider 使用你自己的 provider OAuth app。先列出支持 OAuth 的 provider，并复制目标服务的 expectedRedirectUri：

curl -s http://localhost:3000/api/oauth/configs \
  -H 'authorization: Bearer replace-with-an-admin-token'

使用默认端口时，GitHub 使用这个 callback URL：

http://localhost:3000/oauth/callback

把 /api/oauth/configs 返回的准确 callback URL 填入 provider OAuth app。如果修改了 PORT、HOST，或通过其他 origin 暴露 runtime，请先设置 OOMOL_CONNECT_ORIGIN，重启 runtime 后重新读取 callback URL。

在本地保存 OAuth client：

curl -s -X PUT http://localhost:3000/api/oauth/configs/github \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"clientId":"...","clientSecret":"..."}'

开始授权：

curl -s -X POST http://localhost:3000/api/oauth/authorizations \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"service":"github"}'

在浏览器中打开返回的 authorizationUrl。Provider 重定向回 callback URL 后，OOMOL OpenConnector 会把 OAuth 凭据保存为默认连接。

如需把 OAuth 结果保存为命名连接，传入 connectionName：

curl -s -X POST http://localhost:3000/api/oauth/authorizations \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"service":"github","connectionName":"work"}'

给 Agent 使用工具

支持 MCP 的 client 可以连接到：

http://localhost:3000/mcp

MCP server 暴露一组面向发现流程的工具：

• list_apps
• search_actions
• get_action_guide
• execute_action

预览 MCP tool metadata：

curl -s http://localhost:3000/mcp/tools \
  -H 'authorization: Bearer oct_...'

HTTP client 使用 /v1 runtime API：

curl -s http://localhost:3000/v1/actions \
  -H 'authorization: Bearer oct_...'

每个 action 都有一份本地 Markdown guide，包含输入 schema、scope、provider 权限、当前连接身份和请求示例：

curl -s http://localhost:3000/api/actions/github.get_current_user/agent.md \
  -H 'authorization: Bearer replace-with-an-admin-token'

Web 控制台也可以为每个 action 复制 cURL、TypeScript 和 agent prompt 示例。

从源码运行

开发 OOMOL OpenConnector 或 provider executor 时使用源码工作流。请使用 Node.js 22 或更新版本。

git clone https://github.com/oomol-lab/open-connector.git
cd open-connector
npm install
npm run build:web
npm run dev

npm install 和 npm run dev 会在生成文件缺失或过期时创建本地文件。

源码运行时，运行时状态保存在：

./data/connect.sqlite

使用其他数据目录：

OOMOL_CONNECT_DATA_DIR=/path/to/data npm run dev

Admin token、encryption key、origin、runtime token 和 action policy 这些环境变量与前面相同。

部署到 Cloudflare Workers

Cloudflare Workers 支持作为 metadata 和 runtime state 的部署目标。

先克隆仓库，再创建 Cloudflare 资源并部署：

git clone https://github.com/oomol-lab/open-connector.git
cd open-connector
cp wrangler.example.jsonc wrangler.local.jsonc
npm run generate:catalog
npm run build:web
npx wrangler d1 create oomol-connect
npx wrangler r2 bucket create oomol-connect-transit-files
npx wrangler d1 migrations apply oomol-connect --remote
npm run deploy:cloudflare

部署前，把 Cloudflare 返回的 D1 database_id 填入被忽略的 wrangler.local.jsonc。

使用 Wrangler 设置 secrets：

npx wrangler secret put OOMOL_CONNECT_ADMIN_TOKEN
npx wrangler secret put OOMOL_CONNECT_ENCRYPTION_KEY

Cloudflare 使用相同的环境变量名配置 origin、auth tokens、action policy、中转文件限制和凭据加密。PORT、HOST 和 OOMOL_CONNECT_DATA_DIR 只适用于本地 Node runtime。

Worker runtime 会提供 catalog metadata、/api 和 /v1 metadata endpoints、连接、runtime tokens、OAuth config/state、基于 R2 的中转文件，以及生成版 provider action executor registry。如果希望自动清理未读取的过期中转文件，请为 transit bucket 配置 R2 lifecycle rule。

运维部署

为支持和恢复保留这些记录：

对于文件上传类 action，本地中转文件保存在 OOMOL_CONNECT_DATA_DIR/files 并按时间清理。使用 OOMOL_CONNECT_TRANSIT_FILE_TTL_SECONDS 和 OOMOL_CONNECT_TRANSIT_FILE_MAX_BYTES 调整生命周期和上传大小。

排查建议