Passer au contenu principal

​
Référence d’onboarding

Voici la référence complète de openclaw onboard. Pour une vue d’ensemble de haut niveau, consultez Onboarding (CLI).

​
Détails du flux (mode local)

1

Détection de la configuration existante

  • Si ~/.openclaw/openclaw.json existe, choisissez Conserver / Modifier / Réinitialiser.
  • Relancer l’onboarding n’efface rien à moins que vous choisissiez explicitement Réinitialiser (ou que vous passiez --reset).
  • Le drapeau CLI --reset utilise par défaut config+creds+sessions ; utilisez --reset-scope full pour supprimer également l’espace de travail.
  • Si la configuration est invalide ou contient des clés héritées, l’assistant s’arrête et vous demande d’exécuter openclaw doctor avant de continuer.
  • La réinitialisation utilise trash (jamais rm) et propose les portées suivantes :
    • Configuration uniquement
    • Configuration + identifiants + sessions
    • Réinitialisation complète (supprime aussi l’espace de travail)
2

Modèle/Auth

  • Clé API Anthropic : utilise ANTHROPIC_API_KEY si présent ou demande une clé, puis l’enregistre pour l’utilisation du daemon.
  • Clé API Anthropic : choix d’assistant Anthropic privilégié dans l’onboarding/configuration.
  • Jeton de configuration Anthropic : toujours disponible dans l’onboarding/configuration, bien qu’OpenClaw préfère désormais la réutilisation de Claude CLI lorsqu’elle est disponible.
  • Abonnement OpenAI Code (Codex) (Codex CLI) : si ~/.codex/auth.json existe, l’onboarding peut le réutiliser. Les identifiants Codex CLI réutilisés restent gérés par Codex CLI ; à l’expiration, OpenClaw relit d’abord cette source et, lorsque le fournisseur peut les actualiser, écrit l’identifiant actualisé dans le stockage Codex au lieu d’en prendre lui-même la gestion.
  • Abonnement OpenAI Code (Codex) (OAuth) : flux navigateur ; collez le code#state.
    • Définit agents.defaults.model sur openai-codex/gpt-5.4 lorsque le modèle n’est pas défini ou vaut openai/*.
  • Clé API OpenAI : utilise OPENAI_API_KEY si présent ou demande une clé, puis la stocke dans les profils d’authentification.
    • Définit agents.defaults.model sur openai/gpt-5.4 lorsque le modèle n’est pas défini, vaut openai/* ou openai-codex/*.
  • Clé API xAI (Grok) : demande XAI_API_KEY et configure xAI comme fournisseur de modèle.
  • OpenCode : demande OPENCODE_API_KEY (ou OPENCODE_ZEN_API_KEY, à obtenir sur https://opencode.ai/auth) et vous permet de choisir le catalogue Zen ou Go.
  • Ollama : propose d’abord Cloud + Local, Cloud only ou Local only. Cloud only demande OLLAMA_API_KEY et utilise https://ollama.com ; les modes adossés à l’hôte demandent l’URL de base Ollama, détectent les modèles disponibles et récupèrent automatiquement le modèle local sélectionné si nécessaire ; Cloud + Local vérifie aussi si cet hôte Ollama est connecté pour l’accès cloud.
  • Plus de détails : Ollama
  • Clé API : stocke la clé pour vous.
  • Vercel AI Gateway (proxy multi-modèles) : demande AI_GATEWAY_API_KEY.
  • Plus de détails : Vercel AI Gateway
  • Cloudflare AI Gateway : demande l’ID de compte, l’ID Gateway et CLOUDFLARE_AI_GATEWAY_API_KEY.
  • Plus de détails : Cloudflare AI Gateway
  • MiniMax : la configuration est écrite automatiquement ; le modèle hébergé par défaut est MiniMax-M2.7. La configuration par clé API utilise minimax/..., et la configuration OAuth utilise minimax-portal/....
  • Plus de détails : MiniMax
  • StepFun : la configuration est écrite automatiquement pour StepFun standard ou Step Plan sur les points de terminaison Chine ou globaux.
  • La version standard inclut actuellement step-3.5-flash, et Step Plan inclut également step-3.5-flash-2603.
  • Plus de détails : StepFun
  • Synthetic (compatible Anthropic) : demande SYNTHETIC_API_KEY.
  • Plus de détails : Synthetic
  • Moonshot (Kimi K2) : la configuration est écrite automatiquement.
  • Kimi Coding : la configuration est écrite automatiquement.
  • Plus de détails : Moonshot AI (Kimi + Kimi Coding)
  • Ignorer : aucune authentification n’est encore configurée.
  • Choisissez un modèle par défaut parmi les options détectées (ou saisissez manuellement provider/model). Pour une qualité optimale et un risque plus faible d’injection de prompt, choisissez le modèle le plus puissant et de dernière génération disponible dans votre pile de fournisseurs.
  • L’onboarding exécute une vérification du modèle et affiche un avertissement si le modèle configuré est inconnu ou si l’authentification manque.
  • Le mode de stockage des clés API utilise par défaut des valeurs de profils d’authentification en texte brut. Utilisez --secret-input-mode ref pour stocker à la place des références adossées à l’environnement (par exemple keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }).
  • Les profils d’authentification se trouvent dans ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (clés API + OAuth). ~/.openclaw/credentials/oauth.json est un mécanisme hérité réservé à l’importation.
  • Plus de détails : /concepts/oauth
Astuce pour les environnements headless/serveur : terminez OAuth sur une machine disposant d’un navigateur, puis copiez le auth-profiles.json de cet agent (par exemple ~/.openclaw/agents/<agentId>/agent/auth-profiles.json, ou le chemin correspondant sous $OPENCLAW_STATE_DIR/...) vers l’hôte Gateway. credentials/oauth.json n’est qu’une source d’importation héritée.
3

Espace de travail

  • Valeur par défaut : ~/.openclaw/workspace (configurable).
  • Initialise les fichiers d’espace de travail nécessaires au rituel de bootstrap de l’agent.
  • Disposition complète de l’espace de travail + guide de sauvegarde : Espace de travail de l’agent
4

Gateway

  • Port, bind, mode d’authentification, exposition Tailscale.
  • Recommandation d’authentification : conservez Token même pour loopback afin que les clients WS locaux doivent s’authentifier.
  • En mode token, la configuration interactive propose :
    • Générer/stocker un token en texte brut (par défaut)
    • Utiliser SecretRef (optionnel)
    • Quickstart réutilise les SecretRef gateway.auth.token existants sur les fournisseurs env, file et exec pour le bootstrap de la sonde d’onboarding/du tableau de bord.
    • Si ce SecretRef est configuré mais ne peut pas être résolu, l’onboarding échoue tôt avec un message de correction clair au lieu de dégrader silencieusement l’authentification à l’exécution.
  • En mode mot de passe, la configuration interactive prend également en charge le stockage en texte brut ou via SecretRef.
  • Chemin SecretRef de token non interactif : --gateway-token-ref-env <ENV_VAR>.
    • Nécessite une variable d’environnement non vide dans l’environnement du processus d’onboarding.
    • Ne peut pas être combiné avec --gateway-token.
  • Désactivez l’authentification uniquement si vous faites entièrement confiance à chaque processus local.
  • Les binds non loopback exigent toujours une authentification.
5

Canaux

  • WhatsApp : connexion par QR facultative.
  • Telegram : token de bot.
  • Discord : token de bot.
  • Google Chat : JSON de compte de service + audience Webhook.
  • Mattermost (Plugin) : token de bot + URL de base.
  • Signal : installation facultative de signal-cli + configuration du compte.
  • BlueBubbles : recommandé pour iMessage ; URL du serveur + mot de passe + webhook.
  • iMessage : chemin CLI imsg hérité + accès à la base de données.
  • Sécurité des DM : l’appairage est le mode par défaut. Le premier DM envoie un code ; approuvez-le via openclaw pairing approve <channel> <code> ou utilisez des listes d’autorisation.
6

Recherche web

  • Choisissez un fournisseur pris en charge comme Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG ou Tavily (ou ignorez cette étape).
  • Les fournisseurs adossés à une API peuvent utiliser des variables d’environnement ou une configuration existante pour une configuration rapide ; les fournisseurs sans clé utilisent à la place leurs prérequis spécifiques.
  • Ignorez avec --skip-search.
  • Configurez plus tard : openclaw configure --section web.
7

Installation du daemon

  • macOS : LaunchAgent
    • Nécessite une session utilisateur connectée ; pour un environnement headless, utilisez un LaunchDaemon personnalisé (non fourni).
  • Linux (et Windows via WSL2) : unité utilisateur systemd
    • L’onboarding tente d’activer le lingering via loginctl enable-linger <user> afin que la Gateway reste active 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/Telegram). Bun est déconseillé.
  • Si l’authentification par token exige un token et que gateway.auth.token est géré par SecretRef, l’installation du daemon le valide mais ne persiste pas les valeurs de token en texte brut résolues dans les métadonnées d’environnement du service superviseur.
  • Si l’authentification par token exige un token et que le SecretRef de token configuré n’est pas résolu, l’installation du daemon est bloquée avec des instructions exploitables.
  • Si gateway.auth.token et gateway.auth.password sont tous deux configurés et que gateway.auth.mode n’est pas défini, l’installation du daemon est bloquée jusqu’à ce que le mode soit explicitement défini.
8

Vérification de l’état de santé

  • Démarre la Gateway (si nécessaire) et exécute openclaw health.
  • Astuce : openclaw status --deep ajoute la sonde d’état de santé de la Gateway en direct à la sortie d’état, y compris les sondes de canaux lorsque prises en charge (nécessite une Gateway accessible).
9

Skills (recommandé)

  • Lit les Skills disponibles et vérifie les prérequis.
  • Vous permet de choisir un gestionnaire Node : npm / pnpm (bun est déconseillé).
  • Installe les dépendances facultatives (certaines utilisent Homebrew sur macOS).
10

Fin

  • Résumé + prochaines étapes, y compris les applications iOS/Android/macOS pour des fonctionnalités supplémentaires.
Si aucune interface graphique n’est détectée, l’onboarding affiche des instructions de redirection de port SSH pour l’interface de contrôle au lieu d’ouvrir un navigateur. Si les ressources de l’interface de contrôle sont absentes, l’onboarding tente de les construire ; la solution de repli est pnpm ui:build (installe automatiquement les dépendances de l’interface).

​
Mode non interactif

Utilisez --non-interactive pour automatiser ou scriptiser l’onboarding : 
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills
Ajoutez --json pour obtenir un résumé lisible par machine. Token Gateway SecretRef en mode non interactif : 
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN
--gateway-token et --gateway-token-ref-env s’excluent mutuellement.
--json n’implique pas le mode non interactif. Utilisez --non-interactive (et --workspace) pour les scripts.
Des exemples de commandes spécifiques aux fournisseurs se trouvent dans Automatisation CLI. Utilisez cette page de référence pour la sémantique des drapeaux et l’ordre des étapes.

​
Ajouter un agent (mode non interactif)

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.4 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

​
RPC de l’assistant Gateway

La Gateway expose le flux d’onboarding via RPC (wizard.start, wizard.next, wizard.cancel, wizard.status). Les clients (application macOS, interface de contrôle) peuvent afficher les étapes sans réimplémenter la logique d’onboarding.

​
Configuration de Signal (signal-cli)

L’onboarding peut installer signal-cli depuis les releases GitHub :
  • Télécharge la ressource de release appropriée.
  • La stocke sous ~/.openclaw/tools/signal-cli/<version>/.
  • Écrit channels.signal.cliPath dans votre configuration.
Remarques :
  • Les builds JVM nécessitent Java 21.
  • Les builds natives sont utilisées lorsqu’elles sont disponibles.
  • Windows utilise WSL2 ; l’installation de signal-cli suit le flux Linux à l’intérieur de WSL.

​
Ce que l’assistant écrit

Champs typiques dans ~/.openclaw/openclaw.json :
  • agents.defaults.workspace
  • agents.defaults.model / models.providers (si MiniMax est choisi)
  • tools.profile (l’onboarding local utilise par défaut "coding" lorsqu’il n’est pas défini ; les valeurs explicites existantes sont conservées)
  • gateway.* (mode, bind, auth, tailscale)
  • session.dmScope (détails du comportement : Référence de configuration CLI)
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
  • Listes d’autorisation de canaux (Slack/Discord/Matrix/Microsoft Teams) lorsque vous activez cette option pendant les invites (les noms sont résolus en ID lorsque c’est possible).
  • skills.install.nodeManager
    • setup --node-manager accepte npm, pnpm ou bun.
    • La configuration manuelle peut toujours utiliser yarn en définissant directement skills.install.nodeManager.
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode
openclaw agents add écrit dans agents.list[] et bindings en option. Les identifiants WhatsApp sont stockés sous ~/.openclaw/credentials/whatsapp/<accountId>/. Les sessions sont stockées sous ~/.openclaw/agents/<agentId>/sessions/. Certains canaux sont fournis sous forme de plugins. Lorsque vous en choisissez un pendant la configuration, l’onboarding vous invitera à l’installer (npm ou un chemin local) avant qu’il puisse être configuré.

​
Documentation associée