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。先在 provider OAuth app 中设置 callback URL。这个 callback URL 是 OpenConnector origin 加上 /oauth/callback。

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

http://localhost:3000/oauth/callback

如果 runtime 通过其他 origin 暴露，请先设置 OOMOL_CONNECT_ORIGIN，再启动 runtime，然后用该 origin 拼出 callback URL：

https://connect.example.com/oauth/callback

把准确 callback URL 填入 provider OAuth app。

在 Web 控制台中保存 OAuth client：

1. 打开 http://localhost:3000。
2. 打开 provider 页面，例如 GitHub。
3. 点击 Configure OAuth Client 或 Edit OAuth Client。
4. 粘贴 provider app 的 Client ID 和 Client Secret。
5. 点击 Save OAuth Client。

如果 provider 需要额外 client config 字段，请在同一个 OAuth client 表单中填写。继续配置前，请使用能展示该 provider 所需字段的 OpenConnector 控制台版本。

保存 OAuth client 后，在 provider 页面点击 Connect。在 provider 授权页批准授权。Provider 跳回 OpenConnector 后，确认 provider 页面显示账号已连接。

给 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 调整生命周期和上传大小。

排查建议