Setup

Remarque : Si c’est votre première installation, commencez par Premiers pas. Pour les détails de l’assistant, consultez Assistant de configuration.

Dernière mise à jour : 2026-01-01

En bref

  • La personnalisation vit en dehors du dépôt : ~/.openclaw/workspace (espace de travail) + ~/.openclaw/openclaw.json (configuration).
  • Workflow stable : installez l’application macOS et laissez-la gérer le Gateway intégré.
  • Workflow bleeding edge : lancez le Gateway vous-même via pnpm gateway:watch, puis attachez l’application macOS en mode Local.

Prérequis (depuis les sources)

  • Node >=22
  • pnpm
  • Docker (optionnel ; uniquement pour la configuration conteneurisée ou les tests e2e — voir Docker)

Stratégie de personnalisation (pour que les mises à jour ne cassent rien)

Pour obtenir un setup « 100 % personnalisé » tout en facilitant les mises à jour, concentrez vos modifications dans :

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

Initialisez une première fois :

openclaw setup

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

openclaw setup

Si vous n’avez pas encore d’installation globale, lancez la commande via pnpm openclaw setup.

Lancer le Gateway depuis ce dépôt

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

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

Workflow stable (application macOS d’abord)

  1. Installez et lancez OpenClaw.app (barre de menus).
  2. Suivez la checklist d’onboarding et de permissions (invites TCC).
  3. Vérifiez que le Gateway est en mode Local et tourne (l’application le gère).
  4. Connectez les surfaces (exemple : WhatsApp) :
openclaw channels login
  1. Vérification de bon fonctionnement :
openclaw health

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

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

Workflow bleeding edge (Gateway en terminal)

Objectif : travailler sur le Gateway TypeScript, bénéficier du hot reload et garder l’interface macOS connectée.

0) (Optionnel) Lancer l’application macOS depuis les sources

Si vous voulez aussi l’application macOS en bleeding edge :

./scripts/restart-mac.sh

1) Démarrer le Gateway de développement

pnpm install
pnpm gateway:watch

gateway:watch lance le Gateway en mode watch et recharge automatiquement lors des modifications TypeScript.

2) Pointer l’application macOS vers votre Gateway

Dans OpenClaw.app :

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

3) Vérification

  • Le statut du Gateway dans l’application devrait afficher “Using existing gateway …”
  • Ou via la CLI :
openclaw health

Pièges courants

  • Mauvais port : le WebSocket du Gateway utilise par défaut ws://127.0.0.1:18789 ; gardez l’application et la CLI sur le même port.
  • Où se trouvent les données :
    • Identifiants : ~/.openclaw/credentials/
    • Sessions : ~/.openclaw/agents/<agentId>/sessions/
    • Logs : /tmp/openclaw/

Cartographie du stockage des identifiants

Consultez cette section pour le débogage de l’authentification ou pour décider quoi sauvegarder :

  • WhatsApp : ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Token bot Telegram : config/env ou channels.telegram.tokenFile (fichier classique uniquement ; les liens symboliques sont rejetés)
  • Token bot Discord : config/env ou SecretRef (fournisseurs env/file/exec)
  • Tokens Slack : config/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
  • Payload de secrets basé sur fichier (optionnel) : ~/.openclaw/secrets.json
  • Import OAuth legacy : ~/.openclaw/credentials/oauth.json Plus de détails : Security.

Mise à jour (sans tout casser)

  • Conservez ~/.openclaw/workspace et ~/.openclaw/ comme « vos données » ; ne mettez pas de prompts ou de configuration personnels dans le dépôt openclaw.
  • Mise à jour des sources : git pull + pnpm install (si le lockfile a changé) + 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 ou en cas d’inactivité, ce qui tue le Gateway. L’onboarding tente d’activer le lingering pour vous (peut demander sudo). Si ce n’est toujours pas actif, lancez :

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 Gateway runbook pour les notes sur systemd.

Documentation associée

arrow_back
Précédent
Session Management Compaction
Suivant
Pi Dev
arrow_forward