Configuration

En bref

Choisissez un flux de configuration selon la fréquence à laquelle vous voulez recevoir les mises à jour et selon que vous souhaitez exécuter le Gateway vous-même :

• La personnalisation vit hors du dépôt : conservez votre configuration et votre espace de travail dans ~/.openclaw/openclaw.json et ~/.openclaw/workspace/ afin que les mises à jour du dépôt ne les modifient pas.
• Flux stable (recommandé pour la plupart des utilisateurs) : installez l’application macOS et laissez-la exécuter le Gateway intégré.
• Flux de pointe (dev) : exécutez le Gateway vous-même via pnpm gateway:watch, puis laissez l’application macOS s’y connecter en mode Local.

Prérequis (depuis les sources)

• Node 24 recommandé (Node 22 LTS, actuellement 22.19+, reste pris en charge)
• pnpm est requis pour les extractions depuis les sources. OpenClaw charge les plugins intégrés depuis les packages d’espace de travail pnpm extensions/* en mode dev ; donc npm install à la racine ne prépare pas l’arborescence source complète.
• Docker (facultatif ; uniquement pour la configuration/e2e conteneurisée - voir Docker)

Stratégie de personnalisation (pour que les mises à jour ne posent pas problème)

Si vous voulez une configuration « 100 % adaptée à moi » et des mises à jour simples, conservez votre personnalisation dans :

• Configuration : ~/.openclaw/openclaw.json (JSON/JSON5-ish)
• Espace de travail : ~/.openclaw/workspace (skills, prompts, memories ; faites-en un dépôt git privé)

Initialisez une fois :

openclaw setup

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

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 directement la CLI empaquetée :

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

Flux stable (application macOS d’abord)

1. Installez et lancez OpenClaw.app (barre de menus).
2. Complétez la checklist 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. Associez les surfaces (exemple : WhatsApp) :

openclaw channels login

5. Vérification rapide :

openclaw health

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

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

Flux de pointe (Gateway dans un terminal)

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

0) (Facultatif) Exécuter aussi l’application macOS depuis les sources

Si vous voulez également l’application macOS sur la version de pointe :

./scripts/restart-mac.sh

1) Démarrer le Gateway de développement

pnpm install# Première exécution uniquement (ou après réinitialisation de la configuration/de l’espace de travail OpenClaw local)pnpm openclaw setuppnpm gateway:watch

gateway:watch démarre ou redémarre le processus de surveillance du Gateway dans une session tmux nommée et s’y attache automatiquement depuis les terminaux interactifs. Les shells non interactifs restent détachés et affichent 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. Le watcher recharge lors des changements pertinents de sources, de configuration et de métadonnées de plugins intégrés. Si le Gateway surveillé quitte pendant le démarrage, gateway:watch exécute openclaw doctor --fix --non-interactive une fois, puis réessaie ; définissez OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 pour désactiver cette passe de réparation réservée au dev. pnpm openclaw setup est l’étape unique d’initialisation de la configuration/de l’espace de travail local pour une extraction fraîche. pnpm gateway:watch ne reconstruit pas dist/control-ui ; réexécutez donc pnpm ui:build après des changements dans ui/, ou utilisez pnpm ui:dev pendant le développement de la Control UI.

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

Dans OpenClaw.app :

• Mode de connexion : Local L’application se connectera au gateway en cours d’exécution sur le port configuré.

3) Vérifier

• Le statut Gateway dans l’application doit indiquer « Using existing gateway … »
• Ou via la CLI :

openclaw health

Pièges courants

• Mauvais port : le WS du Gateway utilise par défaut ws://127.0.0.1:18789 ; gardez l’application et la CLI sur le même port.
• Emplacement de l’état :
  • État des channels/providers : ~/.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 identifiants

Utilisez ceci lors du débogage de l’authentification ou pour décider quoi sauvegarder :

• WhatsApp : ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Jeton de bot Telegram : configuration/env ou channels.telegram.tokenFile (fichier normal uniquement ; liens symboliques rejetés)
• Jeton de bot Discord : configuration/env ou SecretRef (providers env/file/exec)
• Jetons Slack : configuration/env (channels.slack.*)
• Listes d’autorisation d’appairage :
  • ~/.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
• Charge utile de secrets adossée à un fichier (facultatif) : ~/.openclaw/secrets.json
• Import OAuth hérité : ~/.openclaw/credentials/oauth.json Plus de détails : Sécurité.

Mise à jour (sans casser votre configuration)

• Considérez ~/.openclaw/workspace et ~/.openclaw/ comme « vos données » ; ne mettez pas vos prompts/configurations personnels dans le dépôt openclaw.
• Mise à jour des sources : git pull + pnpm install + continuez à 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 à la déconnexion/inactivité, ce qui tue le Gateway. L’onboarding tente d’activer le lingering pour vous (peut demander sudo). S’il est toujours désactivé, exécutez :

sudo loginctl enable-linger $USER

Pour les serveurs toujours actifs ou multi-utilisateurs, envisagez un service système plutôt qu’un service utilisateur (pas besoin de lingering). Consultez le runbook Gateway pour les notes systemd.

Docs associées

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