openclaw onboard

Configuration initiale guidée complète pour une configuration de Gateway locale ou distante. Utilisez-la lorsque vous voulez qu’OpenClaw vous guide dans un seul flux pour l’authentification du modèle, l’espace de travail, le Gateway, les canaux, les Skills et l’état de santé.

Guides associés

Exemples

openclaw onboardopenclaw onboard --modernopenclaw onboard --flow quickstartopenclaw onboard --flow manualopenclaw onboard --flow importopenclaw onboard --import-from hermes --import-source ~/.hermesopenclaw onboard --skip-bootstrapopenclaw onboard --mode remote --remote-url wss://gateway-host:18789

--flow import utilise des fournisseurs de migration appartenant aux plugins, comme Hermes. Il ne s’exécute que sur une configuration OpenClaw neuve ; si une configuration, des identifiants, des sessions ou des fichiers de mémoire/identité d’espace de travail existent déjà, réinitialisez-les ou choisissez une configuration neuve avant l’importation.

--modern lance l’aperçu d’intégration conversationnelle Crestodian. Sans --modern, openclaw onboard conserve le flux d’intégration classique.

Dans un terminal interactif, openclaw seul (sans sous-commande) choisit la route selon l’état de la configuration :

• Si le fichier de configuration actif est absent ou ne contient aucun paramètre rédigé (vide ou uniquement des métadonnées), ce flux d’intégration classique démarre.
• Si le fichier de configuration existe mais échoue à la validation, il lance Crestodian pour réparation.
• Si le fichier de configuration est valide, il ouvre le TUI d’agent normal, soit localement, soit connecté à un Gateway configuré joignable. Sur une installation configurée, accédez à Crestodian avec /crestodian dans le TUI ou openclaw crestodian.

Le texte en clair ws:// est accepté pour les URL de Gateway en local loopback, les littéraux d’IP privée, .local et les Tailnet *.ts.net. Pour les autres noms DNS privés de confiance, définissez OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 dans l’environnement du processus d’intégration.

Paramètres régionaux

L’intégration interactive utilise les paramètres régionaux de l’assistant CLI pour les textes fixes de configuration. L’ordre de résolution est :

1. OPENCLAW_LOCALE
2. LC_ALL
3. LC_MESSAGES
4. LANG
5. Repli en anglais

Les paramètres régionaux pris en charge par l’assistant sont en, zh-CN et zh-TW. Les valeurs de paramètres régionaux peuvent utiliser le trait de soulignement ou des suffixes POSIX, comme zh_CN.UTF-8. Les noms de produits, noms de commandes, clés de configuration, URL, identifiants de fournisseurs, identifiants de modèles et libellés de plugins/canaux restent littéraux.

Exemple :

OPENCLAW_LOCALE=zh-CN openclaw onboard

Fournisseur personnalisé non interactif :

openclaw onboard --non-interactive \  --auth-choice custom-api-key \  --custom-base-url "https://llm.example.com/v1" \  --custom-model-id "foo-large" \  --custom-api-key "$CUSTOM_API_KEY" \  --secret-input-mode plaintext \  --custom-compatibility openai \  --custom-image-input

--custom-api-key est facultatif en mode non interactif. S’il est omis, l’intégration vérifie CUSTOM_API_KEY. OpenClaw marque automatiquement les identifiants courants de modèles de vision comme compatibles avec l’image. Passez --custom-image-input pour les identifiants de vision personnalisés inconnus, ou --custom-text-input pour forcer des métadonnées texte uniquement. Utilisez --custom-compatibility openai-responses pour les points de terminaison compatibles OpenAI qui prennent en charge /v1/responses, mais pas /v1/chat/completions.

LM Studio prend aussi en charge une option de clé propre au fournisseur en mode non interactif :

openclaw onboard --non-interactive \  --auth-choice lmstudio \  --custom-base-url "http://localhost:1234/v1" \  --custom-model-id "qwen/qwen3.5-9b" \  --lmstudio-api-key "$LM_API_TOKEN" \  --accept-risk

Ollama non interactif :

openclaw onboard --non-interactive \  --auth-choice ollama \  --custom-base-url "http://ollama-host:11434" \  --custom-model-id "qwen3.5:27b" \  --accept-risk

--custom-base-url vaut par défaut http://127.0.0.1:11434. --custom-model-id est facultatif ; s’il est omis, l’intégration utilise les valeurs par défaut suggérées par Ollama. Les identifiants de modèles cloud comme kimi-k2.5:cloud fonctionnent aussi ici.

Stocker les clés de fournisseur sous forme de références plutôt qu’en texte en clair :

openclaw onboard --non-interactive \  --auth-choice openai-api-key \  --secret-input-mode ref \  --accept-risk

Avec --secret-input-mode ref, l’intégration écrit des références adossées à l’environnement au lieu de valeurs de clé en texte en clair. Pour les fournisseurs adossés à des profils d’authentification, cela écrit des entrées keyRef ; pour les fournisseurs personnalisés, cela écrit models.providers.<id>.apiKey comme référence d’environnement (par exemple { source: "env", provider: "default", id: "CUSTOM_API_KEY" }).

Contrat du mode non interactif ref :

• Définissez la variable d’environnement du fournisseur dans l’environnement du processus d’intégration (par exemple OPENAI_API_KEY).
• Ne passez pas d’options de clé en ligne (par exemple --openai-api-key), sauf si cette variable d’environnement est aussi définie.
• Si une option de clé en ligne est passée sans la variable d’environnement requise, l’intégration échoue rapidement avec des instructions.

Options de jeton Gateway en mode non interactif :

• --gateway-auth token --gateway-token <token> stocke un jeton en texte en clair.
• --gateway-auth token --gateway-token-ref-env <name> stocke gateway.auth.token comme SecretRef d’environnement.
• --gateway-token et --gateway-token-ref-env sont mutuellement exclusifs.
• --gateway-token-ref-env nécessite une variable d’environnement non vide dans l’environnement du processus d’intégration.
• Avec --install-daemon, lorsque l’authentification par jeton nécessite un jeton, les jetons Gateway gérés par SecretRef sont validés, mais ne sont pas conservés comme texte en clair résolu dans les métadonnées d’environnement du service superviseur.
• Avec --install-daemon, si le mode jeton nécessite un jeton et que le SecretRef de jeton configuré n’est pas résolu, l’intégration échoue fermée avec des instructions de remédiation.
• Avec --install-daemon, si gateway.auth.token et gateway.auth.password sont tous deux configurés et que gateway.auth.mode n’est pas défini, l’intégration bloque l’installation jusqu’à ce que le mode soit défini explicitement.
• L’intégration locale écrit gateway.mode="local" dans la configuration. Si un fichier de configuration ultérieur ne contient pas gateway.mode, traitez cela comme une configuration endommagée ou une modification manuelle incomplète, pas comme un raccourci valide vers le mode local.
• L’intégration locale installe les plugins téléchargeables sélectionnés lorsque le chemin de configuration choisi les exige.
• L’intégration distante écrit uniquement les informations de connexion au Gateway distant et n’installe pas de paquets de plugin locaux.
• --allow-unconfigured est une échappatoire d’exécution Gateway distincte. Cela ne signifie pas que l’intégration peut omettre gateway.mode.

Exemple :

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 \  --accept-risk

État de santé du Gateway local non interactif :

• Sauf si vous passez --skip-health, l’intégration attend qu’un Gateway local joignable soit disponible avant de se terminer avec succès.
• --install-daemon démarre d’abord le chemin d’installation du Gateway géré. Sans cette option, vous devez déjà avoir un Gateway local en cours d’exécution, par exemple openclaw gateway run.
• Si vous voulez seulement écrire la configuration, l’espace de travail et le bootstrap dans l’automatisation, utilisez --skip-health.
• Si vous gérez vous-même les fichiers d’espace de travail, passez --skip-bootstrap pour définir agents.defaults.skipBootstrap: true et éviter la création de AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md et BOOTSTRAP.md.
• Sur Windows natif, --install-daemon essaie d’abord les tâches planifiées et se rabat sur un élément de connexion dans le dossier de démarrage par utilisateur si la création de tâche est refusée.

Comportement de l’intégration interactive avec le mode référence :

• Choisissez Utiliser une référence de secret lorsque l’invite apparaît.
• Puis choisissez l’un des deux éléments suivants :
  • Variable d’environnement
  • Fournisseur de secrets configuré (file ou exec)
• L’intégration effectue une validation préliminaire rapide avant d’enregistrer la référence.
  • Si la validation échoue, l’intégration affiche l’erreur et vous permet de réessayer.

Choix de points de terminaison Z.AI non interactifs

# Promptless endpoint selectionopenclaw onboard --non-interactive \  --auth-choice zai-coding-global \  --zai-api-key "$ZAI_API_KEY" # Other Z.AI endpoint choices:# --auth-choice zai-coding-cn# --auth-choice zai-global# --auth-choice zai-cn

Exemple Mistral non interactif :

openclaw onboard --non-interactive \  --auth-choice mistral-api-key \  --mistral-api-key "$MISTRAL_API_KEY"

Options non interactives supplémentaires

Authentification de modèle basée sur jeton (non interactive ; utilisée avec --auth-choice token) :

• --token-provider <id> — Identifiant du fournisseur de jetons. Identifie le fournisseur qui émet le jeton.
• --token <token> — Valeur du jeton pour l’authentification du modèle.
• --token-profile-id <id> — Identifiant du profil d’authentification. Le stockage de jeton générique vaut par défaut <provider>:manual ; les flux de configuration appartenant au fournisseur peuvent utiliser leur propre valeur par défaut, comme anthropic:default.
• --token-expires-in <duration> — Durée facultative d’expiration du jeton (par exemple 365d, 12h).

Cloudflare AI Gateway (non interactif) :

• --cloudflare-ai-gateway-account-id <id> — ID de compte Cloudflare pour le routage via Cloudflare AI Gateway.
• --cloudflare-ai-gateway-gateway-id <id> — ID Cloudflare AI Gateway.

Contrôle de l’installation du daemon :

• --no-install-daemon — Ignorer explicitement l’installation du service Gateway.
• --skip-daemon — Alias de --no-install-daemon.

Contrôle de la configuration de l’UI et des hooks :

• --skip-ui — Ignorer les invites Control UI / TUI pendant l’intégration.
• --skip-hooks — Ignorer les invites de configuration de webhook / hook pendant l’intégration.

Suppression de sortie :

• --suppress-gateway-token-output — Supprimer la sortie Gateway/UI contenant des jetons (indices de jeton, URL de connexion automatique avec jeton intégré et lancement automatique de Control UI). Utile dans les environnements de terminal partagé et de CI.

Notes sur les flux

Commandes de suivi courantes

openclaw channels addopenclaw configureopenclaw agents add <name>

Utilisez openclaw setup comme le même point d’entrée d’intégration guidée. Utilisez openclaw setup --baseline lorsque vous n’avez besoin que de la config/de l’espace de travail de base, openclaw configure plus tard pour des changements ciblés, et openclaw channels add pour la configuration limitée aux canaux.