---
author: OOMOL
author_url: https://oomol.com/fr/about/
title: Guide d'auto-hébergement OOMOL OpenConnector
description: Auto-hébergez le service connector open-source, protégez les
  identifiants locaux, configurez les connexions provider et exposez des actions
  aux agents via MCP ou HTTP.
lang: fr
canonical_url: https://oomol.com/fr/docs/openconnector-self-hosting/
markdown_url: https://oomol.com/fr/docs/openconnector-self-hosting.md
---

# Guide d'auto-hébergement OOMOL OpenConnector

[OOMOL OpenConnector](https://github.com/oomol-lab/open-connector) est un service connector open-source et auto-hébergeable. Utilisez-le lorsque des agents ou outils internes doivent appeler de vrais services externes tout en gardant les identifiants provider, permissions et historique d'exécution dans votre propre environnement. Il expose des actions typées pour des services comme GitHub, Gmail, Notion, Hacker News, Ably, Abstract et A-Leads via MCP ou HTTP.

Les agents voient les schémas, scopes, statuts d'exécution et libellés de compte sûrs ; les tokens provider bruts, permissions d'action et historiques d'exécution restent dans votre frontière de déploiement.

## Ce que cela fournit

- Un runtime qui expose les actions provider via MCP, HTTP, OpenAPI et une console web.
- Un stockage des identifiants pour clés API, identifiants personnalisés, connexions OAuth2 et providers sans auth.
- Des schémas d'action typés pour que les agents découvrent ce qu'ils peuvent appeler avant de l'appeler.
- L'identité de connexion et les scopes pour que les utilisateurs et agents voient sous quel compte une action s'exécutera.
- Un transit temporaire de fichiers pour les actions qui nécessitent des URL de fichiers.
- Des logs d'exécution récents avec résumés d'entrée expurgés et erreurs provider.
- Un catalogue de providers avec des exécutors locaux qui se chargent uniquement lorsqu'une action est utilisée.

Commencez par choisir où exécuter le runtime, puis configurez le stockage, le contrôle d'accès, les connexions provider et le point d'entrée MCP ou HTTP exposé aux agents.

## Choisir une cible de déploiement

| Cible | À utiliser quand | Stockage |
| --- | --- | --- |
| Docker Compose | Vous voulez le déploiement local ou mono-serveur le plus rapide. | Volume Docker monté sur `/app/data`, avec SQLite dans `/app/data/connect.sqlite`. |
| Runtime source | Vous développez OOMOL OpenConnector ou des provider executors. | `./data/connect.sqlite` local sauf si `OOMOL_CONNECT_DATA_DIR` est défini. |
| Cloudflare Workers | Vous voulez un déploiement d'état runtime et de métadonnées hébergé sur Cloudflare. | D1 pour les enregistrements runtime et R2 pour les fichiers de transit temporaires. |

## Préparer le runtime

Avant de déployer, choisissez ces valeurs :

| Valeur | Pourquoi c'est important |
| --- | --- |
| `OOMOL_CONNECT_ADMIN_TOKEN` | Protège la console web, `/api` et la référence API locale lorsqu'ils sont accessibles hors de votre shell. |
| `OOMOL_CONNECT_ENCRYPTION_KEY` | Chiffre les identifiants provider stockés et les secrets de clients OAuth. Gardez-la dans votre gestionnaire de secrets. |
| `OOMOL_CONNECT_ORIGIN` | Définit l'origine publique utilisée pour les URLs de callback OAuth. Requis lorsque le navigateur atteint le runtime via un tunnel, domaine ou URL Worker. |
| Runtime tokens | Authentifient les appels d'agents et de clients vers `/v1` et `/mcp`. Créez-les depuis l'onglet Access de la console web ou l'admin API. |
| Action policy | Limite les actions exécutables via `/v1` et MCP. Utilisez `OOMOL_CONNECT_ALLOWED_ACTIONS` et `OOMOL_CONNECT_BLOCKED_ACTIONS`. |

Traitez la base de données runtime comme sensible. Sans `OOMOL_CONNECT_ENCRYPTION_KEY`, OOMOL OpenConnector fonctionne encore, mais les secrets provider sont stockés dans un fichier SQLite local sensible.

## Exécuter avec Docker Compose

Clonez le dépôt OOMOL OpenConnector, entrez dans le répertoire du projet et démarrez le runtime :

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

Ouvrez la console web :

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

Ouvrez la référence API générée :

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

Vérifiez le runtime avec une action sans auth :

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

Docker Compose stocke l'état runtime dans le volume `connector-data`. Le conteneur stocke SQLite ici :

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

Pour un déploiement serveur privé, définissez au minimum le token admin et la clé de chiffrement avant de démarrer :

Exécutez ces exemples dans Bash. Saisissez les identifiants réels uniquement dans les invites masquées ; ne les insérez pas dans les commandes shell ni dans les journaux.

```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
)
```

Lorsque le runtime est exposé via un domaine public ou un tunnel, définissez aussi l'origine publique :

```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
)
```

L'image Docker écoute sur `0.0.0.0` dans le conteneur. Contrôlez l'accès externe avec le firewall hôte, un reverse proxy ou votre plateforme de conteneurs.

## Protéger l'accès admin et runtime

Les clients HTTP admin appellent `/api`, `/docs` ou la console web avec :

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

Créez des runtime tokens pour les agents et clients de type SDK depuis l'onglet Access de la console web. Le token est affiché une seule fois ; seul un hash est stocké.

Vous pouvez aussi en créer un via l'admin API :

Les exemples de requêtes authentifiées nécessitent Python 3 et [curl 7.76.0 ou une version ultérieure](https://curl.se/docs/manpage.html#--fail-with-body), qui prend en charge l’option --fail-with-body utilisée dans tous ces exemples. Les secrets sont saisis dans des invites masquées puis transmis à curl par l’entrée standard, sans apparaître dans les arguments de commande ni l’historique du shell.

```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
```

Les clients runtime appellent ensuite `/v1` ou `/mcp` avec :

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

Pour les scripts de bootstrap et la compatibilité ascendante, `OOMOL_CONNECT_RUNTIME_TOKEN` reste accepté :

```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
)
```

Limitez les actions que les agents peuvent exécuter :

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

Bloquez des actions précises même lorsqu'une allowlist plus large les inclut :

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

## Connecter un provider par clé API

GitHub est un exemple compact de clé API, car il peut utiliser un personal access token.

Inspectez le contrat du provider :

```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
```

Stockez la connexion GitHub par défaut :

```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
```

Appelez GitHub via le runtime :

```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
```

Vérifiez les connexions configurées et l'identité de compte sûre exposée aux agents :

```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
```

### Connexions nommées

Ajoutez `connectionName` lorsque le même provider nécessite plusieurs comptes :

```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
```

Sélectionnez ce compte pendant l'exécution :

```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
```

Le paramètre de requête `alias` est aussi accepté.

## Connecter un provider OAuth

Les providers OAuth utilisent votre propre app OAuth provider. Listez d'abord les providers compatibles OAuth et copiez l'`expectedRedirectUri` du service :

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

Avec le port par défaut, GitHub utilise cette URL de callback :

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

Collez l'URL de callback exacte retournée par `/api/oauth/configs` dans l'app OAuth provider. Si vous changez `PORT`, `HOST` ou exposez le runtime via une autre origine, définissez `OOMOL_CONNECT_ORIGIN` avant de démarrer le runtime et relisez l'URL de callback.

Stockez le client OAuth localement :

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

Démarrez l'autorisation :

```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"}'
```

Ouvrez l'`authorizationUrl` retournée dans un navigateur. Après la redirection du provider vers l'URL de callback, OOMOL OpenConnector stocke le credential OAuth comme connexion par défaut.

Pour stocker le résultat OAuth comme connexion nommée, incluez `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"}'
```

## Donner les outils à un agent

Pour les clients compatibles MCP, pointez le client vers :

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

Le serveur MCP expose des outils orientés découverte :

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

Prévisualisez les métadonnées d'outils MCP :

```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
```

Pour les clients HTTP, utilisez l'API runtime `/v1` :

```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
```

Chaque action a un guide Markdown local avec le schéma d'entrée, les scopes, les permissions provider, l'identité de connexion courante et des exemples de requêtes :

```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
```

La console web peut aussi copier des exemples cURL, TypeScript et prompts d'agent pour chaque action.

## Exécuter depuis les sources

Utilisez le workflow source lorsque vous développez OOMOL OpenConnector ou des provider executors. Utilisez Node.js 22 ou plus récent.

```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` et `npm run dev` créent les fichiers générés locaux lorsqu'ils manquent ou sont obsolètes.

Lorsque vous exécutez depuis les sources, l'état runtime est stocké dans :

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

Utilisez un autre répertoire de données avec :

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

Définissez les mêmes variables d'environnement admin, chiffrement, origine, runtime token et action policy que ci-dessus.

## Déployer sur Cloudflare Workers

Cloudflare Workers est pris en charge comme cible de déploiement pour les métadonnées et l'état runtime.

Clonez le dépôt, créez les ressources Cloudflare et déployez :

```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
```

Avant le déploiement, mettez à jour le fichier ignoré `wrangler.local.jsonc` avec le D1 `database_id` retourné par Cloudflare.

Gardez le Worker privé pendant la configuration initiale : dans la configuration Wrangler locale, définissez workers_dev et preview_urls sur false et ne configurez ni routes publiques ni domaines personnalisés. N’autorisez aucun accès public avant d’avoir défini les trois secrets ci-dessous.

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

Définissez les secrets avec Wrangler :

```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
```

Après avoir défini les trois secrets, activez la route publique souhaitée dans la configuration locale et redéployez.

Cloudflare utilise les mêmes noms de variables d'environnement pour l'origine, les auth tokens, l'action policy, les limites de fichiers de transit et le chiffrement des credentials. `PORT`, `HOST` et `OOMOL_CONNECT_DATA_DIR` sont des réglages locaux propres à Node.

Le runtime Worker sert les métadonnées du catalogue, les endpoints de métadonnées `/api` et `/v1`, les connexions, runtime tokens, config et état OAuth, les fichiers de transit sur R2 et le registre généré des provider action executors. Configurez une règle de cycle de vie R2 pour le bucket de transit si vous voulez nettoyer automatiquement les fichiers de transit expirés non lus.

## Exploiter le déploiement

Gardez ces enregistrements disponibles pour le support et la reprise :

| Enregistrement | Où le trouver |
| --- | --- |
| Base de données runtime | Volume Docker, `OOMOL_CONNECT_DATA_DIR` local ou Cloudflare D1. |
| Fichiers de transit temporaires | `OOMOL_CONNECT_DATA_DIR/files` pour le runtime local, ou Cloudflare R2. |
| Token admin et clé de chiffrement | Votre gestionnaire de secrets. OOMOL OpenConnector ne stocke pas la clé de chiffrement pour vous. |
| Préfixe du runtime token | Onglet Access de la console web ou `/api/runtime-tokens`. Les runtime tokens complets sont affichés une seule fois. |
| Historique d'exécution | Exécutions récentes dans la console web ou `GET /api/runs`. |

Pour les actions d'upload de fichier, les fichiers de transit locaux sont stockés sous `OOMOL_CONNECT_DATA_DIR/files` et nettoyés par âge. Ajustez la durée de vie et la taille d'upload avec `OOMOL_CONNECT_TRANSIT_FILE_TTL_SECONDS` et `OOMOL_CONNECT_TRANSIT_FILE_MAX_BYTES`.

## Dépannage

| Symptôme | À vérifier |
| --- | --- |
| La console web ou `/api` retourne unauthorized. | Envoyez `Authorization: Bearer <admin-token>` et confirmez que `OOMOL_CONNECT_ADMIN_TOKEN` correspond à l'environnement en cours. |
| `/v1` ou `/mcp` retourne unauthorized. | Utilisez un runtime token créé depuis l'onglet Access ou `POST /api/runtime-tokens`. Les tokens admin sont pour les surfaces admin, pas les clients runtime. |
| OAuth redirige vers le mauvais hôte. | Définissez `OOMOL_CONNECT_ORIGIN` sur l'origine que les utilisateurs ouvrent dans le navigateur, redémarrez le runtime, puis copiez le nouvel `expectedRedirectUri` depuis `/api/oauth/configs`. |
| Une action ne trouve pas de credentials. | Vérifiez `/api/connections`, le `x-oo-connector-alias` sélectionné et si la connexion est encore disponible. |
| Une action est bloquée. | Vérifiez `OOMOL_CONNECT_ALLOWED_ACTIONS` et `OOMOL_CONNECT_BLOCKED_ACTIONS`. Les actions bloquées l'emportent sur les allowlists plus larges. |
| Les credentials provider échouent après avoir fonctionné. | Reconnectez le provider si le token a expiré et qu'aucun refresh token n'est disponible, ou vérifiez que la clé de chiffrement correspond toujours aux enregistrements stockés. |