Référence CLI d’onboarding

Cette page constitue la référence complète de openclaw onboard. Pour le guide abrégé, consultez Assistant de configuration (CLI).

Ce que fait l’assistant

Le mode local (par défaut) vous guide à travers :

• Configuration du modèle et de l’authentification (abonnement OpenAI Code OAuth, clé API Anthropic ou setup token, plus les options MiniMax, GLM, Ollama, Moonshot et AI Gateway)
• Emplacement de l’espace de travail et fichiers bootstrap
• Paramètres du Gateway (port, liaison, authentification, Tailscale)
• Canaux et fournisseurs (Telegram, WhatsApp, Discord, Google Chat, plugin Mattermost, Signal)
• Installation du daemon (LaunchAgent ou unité utilisateur systemd)
• Vérification de santé
• Configuration des skills

Le mode distant configure cette machine pour se connecter à un Gateway situé ailleurs. Il n’installe ni ne modifie rien sur l’hôte distant.

Détails du flux local

Étape 1 : Détection de la configuration existante

- Si `~/.openclaw/openclaw.json` existe, choisissez Conserver, Modifier ou Réinitialiser.
- Relancer l'assistant ne supprime rien sauf si vous choisissez explicitement Réinitialiser (ou passez `--reset`).
- Le `--reset` CLI s'applique par défaut à `config+creds+sessions` ; utilisez `--reset-scope full` pour supprimer aussi l'espace de travail.
- Si la configuration est invalide ou contient des clés legacy, l'assistant s'arrête et vous demande d'exécuter `openclaw doctor` avant de continuer.
- La réinitialisation utilise `trash` et propose plusieurs portées :
  - Configuration uniquement
  - Configuration + identifiants + sessions
  - Réinitialisation complète (supprime aussi l'espace de travail)

Étape 2 : Modèle et authentification

- La matrice complète des options se trouve dans [Options d'authentification et de modèle](#options-dauthentification-et-de-modèle).

Étape 3 : Espace de travail

- Par défaut `~/.openclaw/workspace` (configurable).
- Génère les fichiers d'espace de travail nécessaires au rituel d'initialisation au premier lancement.
- Organisation de l'espace de travail : [Agent workspace](/docs/concepts/agent-workspace).

Étape 4 : Gateway

- Demande le port, la liaison, le mode d'authentification et l'exposition Tailscale.
- Recommandé : gardez l'authentification par token activée même en loopback pour que les clients WS locaux doivent s'authentifier.
- En mode token, l'onboarding interactif propose :
  - **Générer/stocker un token en clair** (par défaut)
  - **Utiliser SecretRef** (opt-in)
- En mode mot de passe, l'onboarding interactif prend aussi en charge le stockage en clair ou SecretRef.
- Chemin non interactif pour le SecretRef du token : `--gateway-token-ref-env <ENV_VAR>`.
  - Nécessite une variable d'environnement non vide dans l'environnement du processus d'onboarding.
  - Non combinable avec `--gateway-token`.
- Ne désactivez l'authentification que si vous faites pleinement confiance à tous les processus locaux.
- Les liaisons non-loopback exigent toujours une authentification.

Étape 5 : Canaux

- [WhatsApp](/docs/channels/whatsapp) : connexion QR optionnelle
- [Telegram](/docs/channels/telegram) : token bot
- [Discord](/docs/channels/discord) : token bot
- [Google Chat](/docs/channels/googlechat) : JSON du compte de service + audience webhook
- [Mattermost](/docs/channels/mattermost) plugin : token bot + URL de base
- [Signal](/docs/channels/signal) : installation optionnelle de `signal-cli` + configuration du compte
- [BlueBubbles](/docs/channels/bluebubbles) : recommandé pour iMessage ; URL du serveur + mot de passe + webhook
- [iMessage](/docs/channels/imessage) : chemin CLI legacy `imsg` + accès à la base de données
- Sécurité des DM : le mode par défaut est l'appairage. Le premier DM envoie un code ; approuvez via
  `openclaw pairing approve <channel> <code>` ou utilisez les listes d'autorisation.

Étape 6 : Installation du daemon

- macOS : LaunchAgent
  - Nécessite une session utilisateur connectée ; pour un fonctionnement headless, utilisez un LaunchDaemon personnalisé (non fourni).
- Linux et Windows via WSL2 : unité utilisateur systemd
  - L'assistant tente `loginctl enable-linger <user>` pour que le Gateway reste actif après la déconnexion.
  - Peut demander sudo (écriture dans `/var/lib/systemd/linger`) ; il essaie d'abord sans sudo.
- Sélection du runtime : Node (recommandé ; requis pour WhatsApp et Telegram). Bun n'est pas recommandé.

Étape 7 : Vérification de santé

- Démarre le Gateway (si nécessaire) et exécute `openclaw health`.
- `openclaw status --deep` ajoute les sondes de santé du Gateway à la sortie du statut.

Étape 8 : Skills

- Lit les skills disponibles et vérifie les prérequis.
- Vous permet de choisir le gestionnaire de paquets : npm ou pnpm (bun déconseillé).
- Installe les dépendances optionnelles (certaines utilisent Homebrew sur macOS).

Étape 9 : Fin

- Résumé et prochaines étapes, incluant les options des applications iOS, Android et macOS.

Remarque : Si aucune interface graphique n’est détectée, l’assistant affiche les instructions de port-forward SSH pour le Control UI au lieu d’ouvrir un navigateur. Si les assets du Control UI sont manquants, l’assistant tente de les compiler ; en cas d’échec, il utilise pnpm ui:build (installe automatiquement les dépendances UI).

Détails du mode distant

Le mode distant configure cette machine pour se connecter à un Gateway situé ailleurs.

Info : Le mode distant n’installe ni ne modifie rien sur l’hôte distant.

Ce que vous configurez :

• URL du Gateway distant (ws://...)
• Token si l’authentification du Gateway distant est requise (recommandé)

Remarque :

• Si le Gateway est en loopback uniquement, utilisez un tunnel SSH ou un tailnet.
• Indices de découverte :
  • macOS : Bonjour (dns-sd)
  • Linux : Avahi (avahi-browse)

Options d’authentification et de modèle

Utilise `ANTHROPIC_API_KEY` si présente ou demande une clé, puis la sauvegarde pour le daemon.

- macOS : vérifie l'élément Keychain "Claude Code-credentials"
- Linux et Windows : réutilise `~/.claude/.credentials.json` si présent

Sur macOS, choisissez "Toujours autoriser" pour que les démarrages launchd ne soient pas bloqués.

Exécutez `claude setup-token` sur n'importe quelle machine, puis collez le token.
Vous pouvez le nommer ; laissez vide pour utiliser la valeur par défaut.

Si `~/.codex/auth.json` existe, l'assistant peut le réutiliser.

Flux navigateur ; collez `code#state`.

Définit `agents.defaults.model` sur `openai-codex/gpt-5.4` lorsque le modèle n'est pas défini ou est `openai/*`.

Utilise `OPENAI_API_KEY` si présente ou demande une clé, puis stocke l'identifiant dans les profils d'authentification.

Définit `agents.defaults.model` sur `openai/gpt-5.1-codex` lorsque le modèle n'est pas défini, est `openai/*` ou `openai-codex/*`.

Demande `XAI_API_KEY` et configure xAI comme fournisseur de modèle.

Demande `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`) et vous laisse choisir le catalogue Zen ou Go.
URL de configuration : [opencode.ai/auth](https://opencode.ai/auth).

Stocke la clé pour vous.

Demande `AI_GATEWAY_API_KEY`.
Plus de détails : [Vercel AI Gateway](/docs/providers/vercel-ai-gateway).

Demande l'ID du compte, l'ID du Gateway et `CLOUDFLARE_AI_GATEWAY_API_KEY`.
Plus de détails : [Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway).

La configuration est écrite automatiquement.
Plus de détails : [MiniMax](/docs/providers/minimax).

Demande `SYNTHETIC_API_KEY`.
Plus de détails : [Synthetic](/docs/providers/synthetic).

Demande l'URL de base (par défaut `http://127.0.0.1:11434`), puis propose les modes Cloud + Local ou Local uniquement.
Découvre les modèles disponibles et suggère des valeurs par défaut.
Plus de détails : [Ollama](/docs/providers/ollama).

Les configurations Moonshot (Kimi K2) et Kimi Coding sont écrites automatiquement.
Plus de détails : [Moonshot AI (Kimi + Kimi Coding)](/docs/providers/moonshot).

Fonctionne avec les endpoints compatibles OpenAI et Anthropic.

L'onboarding interactif prend en charge les mêmes choix de stockage de clé API que les autres flux de fournisseurs :
- **Coller la clé API maintenant** (en clair)
- **Utiliser une référence secrète** (référence env ou référence de fournisseur configurée, avec validation préliminaire)

Flags non interactifs :
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (optionnel ; se rabat sur `CUSTOM_API_KEY`)
- `--custom-provider-id` (optionnel)
- `--custom-compatibility <openai|anthropic>` (optionnel ; par défaut `openai`)

Laisse l'authentification non configurée.

Comportement relatif au modèle :

• Sélectionnez le modèle par défaut parmi les options détectées, ou saisissez manuellement le fournisseur et le modèle.
• L’assistant effectue une vérification du modèle et avertit si le modèle configuré est inconnu ou manque d’authentification.

Chemins des identifiants et des profils :

• Identifiants OAuth : ~/.openclaw/credentials/oauth.json
• Profils d’authentification (clés API + OAuth) : ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Mode de stockage des identifiants :

• Par défaut, l’onboarding persiste les clés API en clair dans les profils d’authentification.
• --secret-input-mode ref active le mode référence au lieu du stockage en clair. En onboarding interactif, vous pouvez choisir entre :
  • une référence de variable d’environnement (par exemple keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • une référence de fournisseur configuré (file ou exec) avec alias de fournisseur + identifiant
• Le mode référence interactif effectue une validation préliminaire rapide avant l’enregistrement.
  • Références env : valide le nom de la variable et la présence d’une valeur non vide dans l’environnement d’onboarding courant.
  • Références fournisseur : valide la configuration du fournisseur et résout l’identifiant demandé.
  • En cas d’échec de la validation, l’onboarding affiche l’erreur et vous permet de réessayer.
• En mode non interactif, --secret-input-mode ref ne supporte que les références env.
  • Définissez la variable d’environnement du fournisseur dans l’environnement du processus d’onboarding.
  • Les flags de clé inline (par exemple --openai-api-key) exigent que cette variable soit définie ; sinon, l’onboarding échoue immédiatement.
  • Pour les fournisseurs personnalisés, le mode ref non interactif stocke models.providers.<id>.apiKey sous la forme { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • Dans ce cas de fournisseur personnalisé, --custom-api-key exige que CUSTOM_API_KEY soit définie ; sinon, l’onboarding échoue immédiatement.
• Les identifiants d’authentification du Gateway supportent les choix clair et SecretRef en onboarding interactif :
  • Mode token : Générer/stocker un token en clair (par défaut) ou Utiliser SecretRef.
  • Mode mot de passe : en clair ou SecretRef.
• Chemin non interactif pour le SecretRef du token : --gateway-token-ref-env <ENV_VAR>.
• Les configurations existantes en clair continuent de fonctionner sans modification.

Remarque : Astuce pour les serveurs headless : effectuez l’OAuth sur une machine disposant d’un navigateur, puis copiez ~/.openclaw/credentials/oauth.json (ou $OPENCLAW_STATE_DIR/credentials/oauth.json) vers l’hôte du Gateway.

Sorties et fonctionnement interne

Champs typiques dans ~/.openclaw/openclaw.json :

• agents.defaults.workspace
• agents.defaults.model / models.providers (si MiniMax choisi)
• tools.profile (l’onboarding local définit par défaut "coding" si non défini ; les valeurs explicites existantes sont conservées)
• gateway.* (mode, liaison, authentification, Tailscale)
• session.dmScope (l’onboarding local définit par défaut per-channel-peer si non défini ; les valeurs explicites existantes sont conservées)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Listes d’autorisation des canaux (Slack, Discord, Matrix, Microsoft Teams) lorsque vous optez in pendant les invites (les noms sont résolus en identifiants lorsque possible)
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add écrit agents.list[] et optionnellement bindings.

Les identifiants WhatsApp sont stockés dans ~/.openclaw/credentials/whatsapp/<accountId>/. Les sessions sont stockées dans ~/.openclaw/agents/<agentId>/sessions/.

Remarque : Certains canaux sont livrés sous forme de plugins. Lorsqu’ils sont sélectionnés pendant l’onboarding, l’assistant propose d’installer le plugin (npm ou chemin local) avant la configuration du canal.

RPC de l’assistant du Gateway :

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

Les clients (application macOS et Control UI) peuvent afficher les étapes sans ré-implémenter la logique d’onboarding.

Comportement de la configuration Signal :

• Télécharge l’asset de la release appropriée
• Le stocke dans ~/.openclaw/tools/signal-cli/<version>/
• Écrit channels.signal.cliPath dans la configuration
• Les builds JVM nécessitent Java 21
• Les builds natifs sont utilisés lorsque disponibles
• Windows utilise WSL2 et suit le flux signal-cli Linux à l’intérieur de WSL

Documentation associée

• Hub d’onboarding : Assistant de configuration (CLI)
• Automatisation et scripts : Automatisation CLI
• Référence de la commande : openclaw onboard