Руководство по самостоятельному размещению OOMOL OpenConnector

OOMOL OpenConnector — это open-source connector service, который можно self-host. Используйте его, когда агентам или внутренним инструментам нужно вызывать реальные внешние сервисы, а provider credentials, permissions и execution history должны оставаться в вашей среде. Он предоставляет типизированные actions для сервисов GitHub, Gmail, Notion, Hacker News, Ably, Abstract, A-Leads и других через MCP или HTTP.

Агенты видят schemas, scopes, execution status и безопасные account labels; raw provider tokens, action permissions и execution history остаются внутри вашей deployment boundary.

Что это даёт

• Runtime, который предоставляет provider actions через MCP, HTTP, OpenAPI и web console.
• Credential storage для API keys, custom credentials, OAuth2 connections и no-auth providers.
• Typed action schemas, чтобы агенты могли понять, что они могут вызвать, до вызова.
• Connection identity и scopes, чтобы users и agents видели, от имени какого account будет выполняться action.
• Temporary file transit для actions, которым нужны file URLs.
• Recent run logs с редактированными summaries входа и provider errors.
• Provider catalog с local executors, которые загружаются только при использовании action.

Начните с выбора места запуска runtime, затем настройте storage, access control, provider connections и agent-facing MCP или HTTP entry point.

Выберите deployment target

Подготовьте runtime

Перед deployment определите эти значения:

Считайте runtime database чувствительной. Без OOMOL_CONNECT_ENCRYPTION_KEY OOMOL OpenConnector всё равно работает, но provider secrets хранятся в чувствительном local SQLite file.

Запуск с Docker Compose

Клонируйте репозиторий OOMOL OpenConnector, перейдите в каталог проекта и запустите runtime:

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

Откройте web console:

http://localhost:3000

Откройте сгенерированную API reference:

http://localhost:3000/docs

Проверьте runtime no-auth action:

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

Docker Compose хранит runtime state в volume connector-data. Container хранит SQLite здесь:

/app/data/connect.sqlite

Для private server deployment задайте как минимум 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 доступен через public domain или tunnel, задайте также public 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 image внутри container привязывается к 0.0.0.0. Контролируйте внешний доступ через host firewall, reverse proxy или container platform.

Защитите admin и runtime access

Admin HTTP clients вызывают /api, /docs или web console с:

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

Создавайте runtime tokens для agents и SDK-style clients на вкладке Access web console. Token показывается один раз; хранится только hash.

Его также можно создать через admin 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 clients затем вызывают /v1 или /mcp с:

Authorization: Bearer oct_...

Для bootstrap scripts и backward compatibility 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

Ограничьте actions, которые агенты могут выполнять:

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

Блокируйте конкретные actions, даже если более широкая allowlist включает их:

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 contract:

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

Сохраните default GitHub connection:

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_..."}}'

Вызовите GitHub через runtime:

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

Проверьте настроенные connections и safe account identity, видимую агентам:

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

Именованные подключения

Добавьте connectionName, когда одному provider нужно несколько accounts:

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_..."}}'

Выберите этот account при execution:

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":{}}'

Query parameter alias также принимается.

Подключите OAuth provider

OAuth providers используют ваше собственное provider OAuth app. Сначала перечислите providers с поддержкой OAuth и скопируйте expectedRedirectUri для service:

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

С портом по умолчанию GitHub использует этот callback URL:

http://localhost:3000/oauth/callback

Вставьте точный callback URL, возвращённый /api/oauth/configs, в provider OAuth app. Если вы меняете PORT, HOST или открываете runtime через другой origin, задайте 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":"..."}'

Запустите authorization:

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 в браузере. После redirect provider на callback URL OOMOL OpenConnector сохранит OAuth credential как default connection.

Чтобы сохранить OAuth result как named connection, включите 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"}'

Передайте tools агенту

Для MCP-capable clients укажите client:

http://localhost:3000/mcp

MCP server предоставляет discovery-oriented tools:

• list_apps
• search_actions
• get_action_guide
• execute_action

Просмотрите MCP tool metadata:

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

Для HTTP clients используйте /v1 runtime API:

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

У каждого action есть локальное Markdown-руководство с input schema, scopes, provider permissions, current connection identity и request examples:

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

Web console также может копировать примеры cURL, TypeScript и agent prompt для каждого action.

Запуск из source

Используйте source workflow, когда разрабатываете OOMOL OpenConnector или provider executors. Используйте 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 создают локальные generated files, когда они отсутствуют или устарели.

При запуске из source runtime state хранится в:

./data/connect.sqlite

Используйте другой data directory с:

OOMOL_CONNECT_DATA_DIR=/path/to/data npm run dev

Задайте те же environment variables admin, encryption, origin, runtime token и action policy, которые описаны выше.

Deploy в Cloudflare Workers

Cloudflare Workers поддерживается как deployment target для metadata и runtime-state.

Клонируйте repository, создайте ресурсы Cloudflare и deploy:

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

Перед deploy обновите игнорируемый файл wrangler.local.jsonc, указав D1 database_id, возвращённый Cloudflare.

Задайте secrets через Wrangler:

npx wrangler secret put OOMOL_CONNECT_ADMIN_TOKEN
npx wrangler secret put OOMOL_CONNECT_ENCRYPTION_KEY

Cloudflare использует те же имена environment variables для origin, auth tokens, action policy, transit file limits и credential encryption. PORT, HOST и OOMOL_CONNECT_DATA_DIR применяются только к local Node.

Worker runtime обслуживает catalog metadata, metadata endpoints /api и /v1, connections, runtime tokens, OAuth config и state, transit files на R2 и generated provider action executor registry. Настройте R2 lifecycle rule для transit bucket, если хотите автоматически очищать непрочитанные expired transit files.

Эксплуатация deployment

Держите эти records доступными для support и recovery:

Для file-upload actions local transit files хранятся в OOMOL_CONNECT_DATA_DIR/files и очищаются по age. Настройте lifetime и upload size через OOMOL_CONNECT_TRANSIT_FILE_TTL_SECONDS и OOMOL_CONNECT_TRANSIT_FILE_MAX_BYTES.

Устранение неполадок