Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Si vous configurez OpenClaw pour la première fois, commencez par Bien démarrer. Pour les détails d’intégration, consultez Intégration (CLI).

​
TL;DR

Choisissez un flux de configuration selon la fréquence à laquelle vous voulez recevoir les mises à jour et selon que vous voulez exécuter le Gateway vous-même :
  • La personnalisation vit hors du dépôt : gardez 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 cas) : installez l’application macOS et laissez-la exécuter le Gateway inclus.
  • Flux de pointe (dev) : exécutez vous-même le Gateway via pnpm gateway:watch, puis laissez l’application macOS s’y attacher en mode local.

​
Prérequis (depuis les sources)

  • Node 24 recommandé (Node 22 LTS, actuellement 22.16+, toujours pris en charge)
  • pnpm est requis pour les extractions des sources. OpenClaw charge les plugins inclus depuis les paquets d’espace de travail pnpm extensions/* en mode dev ; un npm install à la racine ne prépare donc 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 faciles, gardez votre personnalisation dans :
  • Configuration : ~/.openclaw/openclaw.json (JSON/à peu près JSON5)
  • Espace de travail : ~/.openclaw/workspace (skills, prompts, mémoires ; 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. Terminez la liste de contrôle d’intégration/autorisations (invites TCC).
  3. Vérifiez que le Gateway est en mode Local et en cours d’exécution (l’application le gère).
  4. Liez des surfaces (exemple : WhatsApp) :
openclaw channels login
  1. Vérification de cohérence :
openclaw health
Si l’intégration 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, bénéficier du rechargement à chaud, et garder l’interface de l’application macOS attachée.

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

Si vous voulez également l’application macOS en version de pointe : 
./scripts/restart-mac.sh

​
1) Démarrer le Gateway de dev

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’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 surveillant recharge lors des changements pertinents de sources, de configuration et de métadonnées de plugins inclus. 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 locale et de l’espace de travail pour une extraction fraîche. pnpm gateway:watch ne reconstruit pas dist/control-ui ; relancez 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 s’attachera 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 : Gateway WS utilise ws://127.0.0.1:18789 par défaut ; gardez l’application et la CLI sur le même port.
  • Emplacement de l’état :
    • État des canaux/fournisseurs : ~/.openclaw/credentials/
    • Profils d’authentification des modèles : ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • Sessions : ~/.openclaw/agents/<agentId>/sessions/
    • Journaux : /tmp/openclaw/

​
Carte du stockage des identifiants

Utilisez ceci pour déboguer l’authentification ou 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 (fournisseurs 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 des modèles : ~/.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)

  • Gardez ~/.openclaw/workspace et ~/.openclaw/ comme « vos données » ; ne placez pas de prompts/configuration personnels dans le dépôt openclaw.
  • Mise à jour des sources : 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 à la déconnexion/inactivité, ce qui tue le Gateway. L’intégration 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 plutôt un service système qu’un service utilisateur (pas besoin de persistance). Consultez le runbook Gateway pour les notes systemd.

​
Docs associées