Configuration

Note

Si vous configurez pour la première fois, commencez par

Getting Started

. Pour les détails d’intégration, consultez

Onboarding (CLI)

.

TL;DR

Choisissez un workflow de configuration en fonction de la fréquence à laquelle vous souhaitez des mises à jour et de votre volonté d’exécuter le Gateway vous-même :

• L’adaptation vit en dehors du dépôt : gardez votre configuration et votre espace de travail dans ~/.openclaw/openclaw.json et ~/.openclaw/workspace/ pour que les mises à jour du dépôt ne les touchent pas.
• Workflow stable (recommandé pour la plupart) : installez l’application macOS et laissez-la exécuter le Gateway intégré.
• Flux de travail de pointe (dev) : exécutez le Gateway vous-même via pnpm gateway:watch, puis laissez l’application macOS s’attacher en mode Local.

Prérequis (à partir du code source)

• Node 24 recommandé (Node 22 LTS, actuellement 22.19+, toujours pris en charge)
• pnpm requis pour les extractions de source. OpenClaw charge les plugins groupés à partir des packages de l’espace de travail pnpm extensions/* en mode dev, donc le npm install racine ne prépare pas l’intégralité de l’arborescence des sources.
• Docker (optionnel ; uniquement pour la configuration/e2e conteneurisés - voir Docker)

Stratégie d’adaptation (pour que les mises à jour ne fassent pas mal)

Si vous souhaitez “100% adapté à moi” et des mises à jour faciles, gardez votre personnalisation dans :

• Configuration : ~/.openclaw/openclaw.json (style JSON/JSON5)
• Espace de travail : ~/.openclaw/workspace (compétences, invites, mémoires ; faites-en un dépôt git privé)

Amorçage une seule fois :

openclaw setup

Depuis l’intérieur de ce dépôt, utilisez l’entrée locale CLI :

openclaw setup

Si vous n’avez pas encore d’installation globale, exécutez-la via pnpm openclaw setup.

Exécuter le Gateway depuis ce dépôt

Après pnpm build, vous pouvez exécuter le CLI packagé directement :

node openclaw.mjs gateway --port 18789 --verbose

Flux de travail stable (application macOS d’abord)

1. Installez et lancez OpenClaw.app (barre de menus).
2. Remplissez la liste de contrôle d’onboarding/autorisations (invites TCC).
3. Assurez-vous que le Gateway est en mode Local et en cours d’exécution (l’application le gère).
4. Liez les surfaces (exemple : WhatsApp) :

openclaw channels login

5. Vérification de bon sens :

openclaw health

Si l’onboarding n’est pas disponible dans votre version :

• Exécutez openclaw setup, puis openclaw channels login, puis démarrez le Gateway manuellement (openclaw gateway).

Flux de travail « bleeding edge » (Gateway dans un terminal)

Objectif : travailler sur le Gateway TypeScript, obtenir le rechargement à chaud (hot reload), garder l’interface de l’application macOS connectée.

0) (Optionnel) Exécuter l’application macOS depuis le code source également

Si vous voulez aussi l’application macOS à la pointe :

./scripts/restart-mac.sh

1) Démarrer le Gateway de développement

pnpm install
# First run only (or after resetting local OpenClaw config/workspace)
pnpm openclaw setup
pnpm gateway:watch

gateway:watch démarre ou redémarre le processus de surveillance du Gateway dans une session tmux nommée et s’attache automatiquement depuis les terminaux interactifs. Les shells non interactifs restent détachés et impriment tmux attach -t openclaw-gateway-watch-main ; utilisez OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch pour garder une exécution interactive détachée, ou pnpm gateway:watch:raw pour le mode de surveillance au premier plan. L’observateur se recharge lors des modifications pertinentes de la source, de la configuration et des métadonnées des plugins groupés. Si le Gateway surveillé quitte lors du démarrage, gateway:watch exécute openclaw doctor --fix --non-interactive une fois et réessaie ; définissez OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 pour désactiver cette passe de réparation réservée au développement. pnpm openclaw setup est l’étape d’initialisation unique de la configuration/espace de travail local pour un nouveau checkout. pnpm gateway:watch ne reconstruit pas dist/control-ui, donc relancez pnpm ui:build après les modifications ui/ ou utilisez pnpm ui:dev lors du développement de l’interface utilisateur de contrôle.

2) Pointer l’application macOS vers votre Gateway en cours d’exécution

Dans OpenClaw.app :

• Mode de connexion : Local L’application s’attachera à la passerelle en cours d’exécution sur le port configuré.

3) Vérifier

• Le statut du Gateway dans l’application doit indiquer “Utilisation de la passerelle existante…”
• Ou via CLI :

openclaw health

Pièges courants

• Mauvais port : Le WS du Gateway est par défaut sur ws://127.0.0.1:18789 ; gardez l’application et le CLI sur le même port.
• Où réside l’état :
  • État du canal/fournisseur : ~/.openclaw/credentials/
  • Profils d’authentification de modèle : ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Sessions : ~/.openclaw/agents/<agentId>/sessions/
  • Journaux : /tmp/openclaw/

Carte du stockage des informations d’identification

Utilisez ceci lors du débogage de l’authentification ou pour décider ce qu’il faut sauvegarder :

• WhatsApp : ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Jeton de bot Telegram : config/env ou channels.telegram.tokenFile (fichier régulier uniquement ; les liens symboliques sont rejetés)
• Jeton de bot Discord : config/env ou SecretRef (fournisseurs env/file/exec)
• Jeton Slack : config/env (Slackchannels.slack.*)
• Listes d’autorisation d’appariement :
  • ~/.openclaw/credentials/<channel>-allowFrom.json (compte par défaut)
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (comptes non par défaut)
• Profils d’authentification de modèle : ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Payload de secrets sauvegardés dans un fichier (facultatif) : ~/.openclaw/secrets.json
• Importation OAuth héritée : OAuth~/.openclaw/credentials/oauth.json Plus de détails : Sécurité.

Mise à jour (sans casser votre configuration)

• Gardez ~/.openclaw/workspace et ~/.openclaw/ comme « vos trucs » ; ne mettez pas de invites/configurations personnelles dans le dépôt openclaw.
• Mise à jour de la source : git pull + pnpm install + continuer à utiliser pnpm gateway:watch.

Linux (service utilisateur systemd)

Les installations Linux utilisent un service utilisateur systemd. Par défaut, systemd arrête les services utilisateur lors de la déconnexion/inactivité, ce qui tue le Gateway. L’intégration (Onboarding) tente d’activer la persistance pour vous (peut demander sudo). Si elle est toujours désactivée, exécutez :

sudo loginctl enable-linger $USER

Pour des serveurs toujours actifs ou multi-utilisateurs, envisagez un service système au lieu d’un service utilisateur (aucune persistance nécessaire). Consultez le runbook du Gateway pour les notes systemd.

Documentation connexe

• Runbook du Gateway (indicateurs, supervision, ports)
• Configuration du Gateway (schéma de configuration + exemples)
• Discord et Telegram (balises de réponse + paramètres replyToMode)
• Configuration de l’assistant OpenClaw
• Application macOS (cycle de vie du gateway)