---
author: OOMOL
author_url: https://oomol.com/ja/about/
title: OOMOL OpenConnector セルフホスティングガイド
description: オープンソース connector service をセルフホストし、ローカル credentials を保護し、provider
  connections を設定し、MCP または HTTP で agents に actions を公開します。
lang: ja
canonical_url: https://oomol.com/ja/docs/openconnector-self-hosting/
markdown_url: https://oomol.com/ja/docs/openconnector-self-hosting.md
---

# OOMOL OpenConnector セルフホスティングガイド

[OOMOL OpenConnector](https://github.com/oomol-lab/open-connector) は、オープンソースでセルフホスト可能な connector service です。provider credentials、permissions、execution history を自分の環境内に置いたまま、agents や internal tools が実際の外部サービスを呼び出す必要がある場合に使用します。GitHub、Gmail、Notion、Hacker News、Ably、Abstract、A-Leads などのサービス向け typed actions を MCP または HTTP で公開します。

Agents には schemas、scopes、execution status、安全な account labels が見えます。raw provider tokens、action permissions、execution history は deployment boundary の内側に残ります。

## 提供されるもの

- MCP、HTTP、OpenAPI、web console を通じて provider actions を公開する runtime。
- API keys、custom credentials、OAuth2 connections、no-auth providers の credential storage。
- Agents が呼び出す前に呼び出し可能な内容を発見できる typed action schemas。
- Users と agents が action の実行 account を確認できる connection identity と scopes。
- file URLs を必要とする actions のための temporary file transit。
- redacted input summaries と provider errors を含む recent run logs。
- action 使用時にのみ読み込まれる local executors 付き provider catalog。

まず runtime の実行場所を選び、storage、access control、provider connections、agent-facing MCP または HTTP entry point を設定します。

## deployment target を選ぶ

| Target | 使う場面 | Storage |
| --- | --- | --- |
| Docker Compose | 最速の local または single-server deployment が必要な場合。 | `/app/data` に mount された Docker volume、SQLite は `/app/data/connect.sqlite`。 |
| Source runtime | OOMOL OpenConnector または provider executors を開発する場合。 | `OOMOL_CONNECT_DATA_DIR` が設定されていない限り local `./data/connect.sqlite`。 |
| Cloudflare Workers | Cloudflare-hosted runtime state と metadata deployment が必要な場合。 | runtime records は D1、temporary transit files は R2。 |

## runtime を準備する

deploy 前に以下の値を決めます。

| 値 | 重要な理由 |
| --- | --- |
| `OOMOL_CONNECT_ADMIN_TOKEN` | web console、`/api`、local API reference が自分の shell 外から到達可能な場合に保護します。 |
| `OOMOL_CONNECT_ENCRYPTION_KEY` | 保存済み provider credentials と OAuth client secrets を暗号化します。secret manager に保持してください。 |
| `OOMOL_CONNECT_ORIGIN` | OAuth callback URLs に使う public origin を設定します。browser が tunnel、domain、Worker URL 経由で runtime に到達する場合に必要です。 |
| Runtime tokens | `/v1` と `/mcp` への agent/client calls を認証します。web console の Access tab または admin API から作成します。 |
| Action policy | `/v1` と MCP で実行可能な actions を制限します。`OOMOL_CONNECT_ALLOWED_ACTIONS` と `OOMOL_CONNECT_BLOCKED_ACTIONS` を使います。 |

runtime database は sensitive として扱ってください。`OOMOL_CONNECT_ENCRYPTION_KEY` がなくても OOMOL OpenConnector は動作しますが、provider secrets は sensitive な local SQLite file に保存されます。

## Docker Compose で実行する

OOMOL OpenConnector repository を clone し、project directory に入り、runtime を起動します。

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

web console を開きます。

```text
http://localhost:3000
```

生成された API reference を開きます。

```text
http://localhost:3000/docs
```

no-auth action で runtime を確認します。

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

Docker Compose は runtime state を `connector-data` volume に保存します。container は SQLite を以下に保存します。

```text
/app/data/connect.sqlite
```

private server deployment では、少なくとも admin token と encryption key を設定してから起動します。

これらの例は Bash で実行してください。実際の認証情報は非表示の入力プロンプトでのみ入力し、シェルコマンドやコマンドログに記載しないでください。

```bash
(
  set -eu
  read -r -s -p "OOMOL_CONNECT_ADMIN_TOKEN: " OOMOL_CONNECT_ADMIN_TOKEN
  echo
  test -n "$OOMOL_CONNECT_ADMIN_TOKEN"
  export OOMOL_CONNECT_ADMIN_TOKEN
  read -r -s -p "OOMOL_CONNECT_ENCRYPTION_KEY: " OOMOL_CONNECT_ENCRYPTION_KEY
  echo
  test -n "$OOMOL_CONNECT_ENCRYPTION_KEY"
  export OOMOL_CONNECT_ENCRYPTION_KEY
  docker compose up --build
)
```

runtime を public domain または tunnel で公開する場合は、public origin も設定します。

```bash
(
  set -eu
  export OOMOL_CONNECT_ORIGIN="https://connect.example.com"
  read -r -s -p "OOMOL_CONNECT_ADMIN_TOKEN: " OOMOL_CONNECT_ADMIN_TOKEN
  echo
  test -n "$OOMOL_CONNECT_ADMIN_TOKEN"
  export OOMOL_CONNECT_ADMIN_TOKEN
  read -r -s -p "OOMOL_CONNECT_ENCRYPTION_KEY: " OOMOL_CONNECT_ENCRYPTION_KEY
  echo
  test -n "$OOMOL_CONNECT_ENCRYPTION_KEY"
  export OOMOL_CONNECT_ENCRYPTION_KEY
  read -r -s -p "OOMOL_CONNECT_RUNTIME_TOKEN: " OOMOL_CONNECT_RUNTIME_TOKEN
  echo
  test -n "$OOMOL_CONNECT_RUNTIME_TOKEN"
  export OOMOL_CONNECT_RUNTIME_TOKEN
  docker compose up --build
)
```

Docker image は container 内で `0.0.0.0` に bind します。外部アクセスは host firewall、reverse proxy、container platform で制御してください。

## admin と runtime access を保護する

Admin HTTP clients は `/api`、`/docs`、web console を次の header で呼び出します。

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

Agents と SDK-style clients 用の runtime tokens は web console の Access tab から作成します。token は 1 回だけ表示され、hash のみ保存されます。

admin API から作成することもできます。

以下の認証付きリクエストには Python 3 と [curl 7.76.0 以降](https://curl.se/docs/manpage.html#--fail-with-body)が必要です。これらの例で使用する --fail-with-body オプションは、このバージョン以降で利用できます。シークレットは非表示の入力で読み取り、標準入力から curl に渡します。認証情報はコマンドライン引数やシェル履歴に含まれません。

```bash
python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
payload = {'name': 'Claude Desktop'}
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
config += "data = " + json.dumps(json.dumps(payload)) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'POST', 'http://localhost:3000/api/runtime-tokens', '--header', 'content-type: application/json'],
    input=config, text=True, check=True,
)
PY
```

Runtime clients は `/v1` または `/mcp` を次で呼び出します。

```text
Authorization: Bearer oct_...
```

bootstrap scripts と backward compatibility のため、`OOMOL_CONNECT_RUNTIME_TOKEN` も引き続き受け付けます。

```bash
(
  set -eu
  read -r -s -p "OOMOL_CONNECT_ADMIN_TOKEN: " OOMOL_CONNECT_ADMIN_TOKEN
  echo
  test -n "$OOMOL_CONNECT_ADMIN_TOKEN"
  export OOMOL_CONNECT_ADMIN_TOKEN
  read -r -s -p "OOMOL_CONNECT_RUNTIME_TOKEN: " OOMOL_CONNECT_RUNTIME_TOKEN
  echo
  test -n "$OOMOL_CONNECT_RUNTIME_TOKEN"
  export OOMOL_CONNECT_RUNTIME_TOKEN
  docker compose up --build
)
```

Agents が実行できる actions を制限します。

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

広い allowlist に含まれる場合でも、特定 actions を block できます。

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

## API-key provider を接続する

GitHub は personal access token を使えるため、簡潔な API-key example です。

provider contract を確認します。

```bash
python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'GET', 'http://localhost:3000/api/providers/github'],
    input=config, text=True, check=True,
)
PY
```

default GitHub connection を保存します。

```bash
python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
payload = {'authType': 'api_key', 'values': {'apiKey': None}}
payload["values"]["apiKey"] = getpass.getpass("GitHub API key: ")
if not payload["values"]["apiKey"]:
    raise SystemExit("An API key is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
config += "data = " + json.dumps(json.dumps(payload)) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'PUT', 'http://localhost:3000/api/connections/github', '--header', 'content-type: application/json'],
    input=config, text=True, check=True,
)
PY
```

runtime 経由で GitHub を呼び出します。

```bash
python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("Runtime token: ")
if not token:
    raise SystemExit("A token is required")
payload = {'input': {}}
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
config += "data = " + json.dumps(json.dumps(payload)) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'POST', 'http://localhost:3000/v1/actions/github.get_current_user', '--header', 'content-type: application/json'],
    input=config, text=True, check=True,
)
PY
```

設定済み connections と agents に公開される safe account identity を確認します。

```bash
python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'GET', 'http://localhost:3000/api/connections'],
    input=config, text=True, check=True,
)
PY
```

### 名前付き接続

同じ provider に複数 accounts が必要な場合は `connectionName` を追加します。

```bash
python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
payload = {'authType': 'api_key', 'connectionName': 'work', 'values': {'apiKey': None}}
payload["values"]["apiKey"] = getpass.getpass("GitHub API key: ")
if not payload["values"]["apiKey"]:
    raise SystemExit("An API key is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
config += "data = " + json.dumps(json.dumps(payload)) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'PUT', 'http://localhost:3000/api/connections/github', '--header', 'content-type: application/json'],
    input=config, text=True, check=True,
)
PY
```

実行時にその account を選択します。

```bash
python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("Runtime token: ")
if not token:
    raise SystemExit("A token is required")
payload = {'input': {}}
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
config += "data = " + json.dumps(json.dumps(payload)) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'POST', 'http://localhost:3000/v1/actions/github.get_current_user', '--header', 'x-oo-connector-alias: work', '--header', 'content-type: application/json'],
    input=config, text=True, check=True,
)
PY
```

`alias` query parameter も使用できます。

## OAuth provider を接続する

OAuth providers は自分の provider OAuth app を使用します。まず OAuth-capable providers を一覧表示し、service の `expectedRedirectUri` をコピーします。

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

default port では、GitHub はこの callback URL を使います。

```text
http://localhost:3000/oauth/callback
```

`/api/oauth/configs` が返した正確な callback URL を provider OAuth app に貼り付けます。`PORT`、`HOST` を変更した場合、または別 origin で runtime を公開した場合は、runtime 起動前に `OOMOL_CONNECT_ORIGIN` を設定し、callback URL を再度読み取ってください。

OAuth client を local に保存します。

```bash
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 を開始します。

```bash
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` を browser で開きます。provider が callback URL に redirect した後、OOMOL OpenConnector は OAuth credential を default connection として保存します。

OAuth result を named connection として保存するには、`connectionName` を含めます。

```bash
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 に tools を渡す

MCP-capable clients では client を次に向けます。

```text
http://localhost:3000/mcp
```

MCP server は discovery-oriented tools を公開します。

- `list_apps`
- `search_actions`
- `get_action_guide`
- `execute_action`

MCP tool metadata を preview します。

```bash
python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("Runtime token: ")
if not token:
    raise SystemExit("A token is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'GET', 'http://localhost:3000/mcp/tools'],
    input=config, text=True, check=True,
)
PY
```

HTTP clients では `/v1` runtime API を使います。

```bash
python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("Runtime token: ")
if not token:
    raise SystemExit("A token is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'GET', 'http://localhost:3000/v1/actions'],
    input=config, text=True, check=True,
)
PY
```

各 action には、input schema、scopes、provider permissions、current connection identity、request examples を含むローカル Markdown ガイドがあります。

```bash
python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'GET', 'http://localhost:3000/api/actions/github.get_current_user/agent.md'],
    input=config, text=True, check=True,
)
PY
```

web console から各 action の cURL、TypeScript、agent prompt examples もコピーできます。

## source から実行する

OOMOL OpenConnector または provider executors を開発する場合は source workflow を使います。Node.js 22 以上を使用してください。

```bash
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` は、missing または stale な local generated files を作成します。

source から実行する場合、runtime state は次に保存されます。

```text
./data/connect.sqlite
```

別の data directory を使う場合:

```bash
OOMOL_CONNECT_DATA_DIR=/path/to/data npm run dev
```

上記と同じ admin、encryption、origin、runtime token、action policy の environment variables を設定します。

## Cloudflare Workers に deploy する

Cloudflare Workers は metadata と runtime-state deployment target としてサポートされています。

repository を clone し、Cloudflare resources を作成して deploy します。

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

deploy 前に、Cloudflare が返した D1 `database_id` を ignored `wrangler.local.jsonc` file に設定します。

初期設定中は Worker を非公開にしてください。ローカルの Wrangler 設定で workers_dev と preview_urls を false にし、公開ルートやカスタムドメインを設定しないでください。以下の3つの secret をすべて設定するまで公開アクセスを許可しないでください。

```bash
npx wrangler d1 migrations apply oomol-connect --remote --config wrangler.local.jsonc
npm run deploy:cloudflare
```

Wrangler で secrets を設定します。

```bash
npx wrangler secret put OOMOL_CONNECT_ADMIN_TOKEN --config wrangler.local.jsonc
npx wrangler secret put OOMOL_CONNECT_RUNTIME_TOKEN --config wrangler.local.jsonc
npx wrangler secret put OOMOL_CONNECT_ENCRYPTION_KEY --config wrangler.local.jsonc
```

3つの secret を設定した後、ローカル設定で必要な公開ルートを有効にして再デプロイしてください。

Cloudflare は origin、auth tokens、action policy、transit file limits、credential encryption に同じ environment variable names を使います。`PORT`、`HOST`、`OOMOL_CONNECT_DATA_DIR` は local Node-only settings です。

Worker runtime は catalog metadata、`/api` と `/v1` metadata endpoints、connections、runtime tokens、OAuth config と state、R2-backed transit files、生成された provider action executor registry を提供します。未読の期限切れ transit files を自動削除したい場合は、transit bucket に R2 lifecycle rule を設定してください。

## deployment を運用する

support と recovery のため、以下の records を利用できる状態にしてください。

| Record | Where to find it |
| --- | --- |
| Runtime database | Docker volume、local `OOMOL_CONNECT_DATA_DIR`、または Cloudflare D1。 |
| Temporary transit files | local runtime では `OOMOL_CONNECT_DATA_DIR/files`、または Cloudflare R2。 |
| Admin token and encryption key | secret manager。OOMOL OpenConnector は encryption key を保存しません。 |
| Runtime token prefix | web console Access tab または `/api/runtime-tokens`。full runtime tokens は 1 回だけ表示されます。 |
| Execution history | web console recent runs または `GET /api/runs`。 |

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` で調整します。

## トラブルシューティング

| 症状 | 確認すること |
| --- | --- |
| web console または `/api` が unauthorized を返す。 | `Authorization: Bearer <admin-token>` を送信し、`OOMOL_CONNECT_ADMIN_TOKEN` が実行中 environment と一致することを確認します。 |
| `/v1` または `/mcp` が unauthorized を返す。 | Access tab または `POST /api/runtime-tokens` で作成した runtime token を使います。admin tokens は admin surfaces 用であり、runtime clients 用ではありません。 |
| OAuth が誤った host に redirect する。 | `OOMOL_CONNECT_ORIGIN` を users が browser で開く origin に設定し、runtime を再起動してから `/api/oauth/configs` から新しい `expectedRedirectUri` をコピーします。 |
| action が credentials を見つけられない。 | `/api/connections`、選択した `x-oo-connector-alias`、connection がまだ available かを確認します。 |
| action が block される。 | `OOMOL_CONNECT_ALLOWED_ACTIONS` と `OOMOL_CONNECT_BLOCKED_ACTIONS` を確認します。blocked actions は広い allowlists より優先されます。 |
| provider credentials が以前は動作していたのに失敗する。 | token が期限切れで refresh token がない場合は provider を再接続するか、encryption key が保存済み records と一致していることを確認します。 |