Onboard

`openclaw onboard`

Onboarding guidé complet pour la configuration locale ou distante du Gateway. Utilisez ceci lorsque vous voulez qu’OpenClaw parcourt l’authentification du modèle, l’espace de travail, la passerelle, les canaux, les compétences et l’état de santé en un seul flux.

Guides associés

CLICentre d'onboarding CLI

Procédure pas à pas du flux interactif de la CLI.

Aperçu de l'onboarding

Comment l’onboarding OpenClaw s’articule.

CLIRéférence de la configuration CLI

Sorties, fonctionnement interne et comportement par étape.

CLIAutomatisation CLI

Indicateurs non interactifs et configurations scriptées.

macOSOnboarding de l'application macOS

Flux d’onboarding pour l’application de la barre de menus macOS.

Exemples

openclaw onboard
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789

--flow importOpenClaw utilise des fournisseurs de migration appartenant aux plugins tels que Hermes. Il ne s’exécute que sur une nouvelle installation OpenClaw ; si des fichiers de configuration, d’identifiants, de sessions ou de mémoire/espace de travail existent, réinitialisez ou choisissez une nouvelle installation avant d’importer.

--modern lance l’aperçu de l’onboarding conversationnel Crestodian. Sans --modern, openclaw onboard conserve le flux d’onboarding classique.

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

Paramètres régionaux

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

OPENCLAW_LOCALE
LC_ALL
LC_MESSAGES
LANG
Retour à l’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 les formes de suffixe underscore ou POSIX telles que zh_CN.UTF-8. Les noms de produits, les noms de commandes, les clés de configuration, les URL, les ID de fournisseur, les ID de modèle et les étiquettes de plugin/channel restent en clair.

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 ID de modèles de vision courants comme compatibles avec les images. Passez --custom-image-input pour les ID de vision personnalisés inconnus, ou --custom-text-input pour forcer les métadonnées texte uniquement.

LM Studio prend également en charge un indicateur de clé spécifique 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

Non-interactif Ollama :

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 est 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 ID de modèles cloud tels que kimi-k2.5:cloud fonctionnent également ici.

Stocker les clés de fournisseur sous forme de références au lieu de 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 basées sur l’environnement au lieu des valeurs de clé en clair. Pour les fournisseurs basés sur un profil 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 de mode non interactif ref :

Définissez la variable d’environnement du provider dans l’environnement du processus d’onboarding (par exemple OPENAI_API_KEY).
Ne transmettez pas de drapeaux de clé en ligne (par exemple --openai-api-key) à moins que cette variable d’environnement ne soit également définie.
Si un drapeau de clé en ligne est transmis sans la variable d’environnement requise, l’onboarding échoue rapidement avec des instructions.

Options de jeton du Gateway en mode non interactif :

--gateway-auth token --gateway-token <token> stocke un jeton en texte brut.
--gateway-auth token --gateway-token-ref-env <name> stocke gateway.auth.token en tant qu’env SecretRef.
--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’onboarding.
Avec --install-daemon, lorsque l’authentification par jeton nécessite un jeton, les jetons de gateway gérés par SecretRef sont validés mais ne sont pas persistés sous forme de texte brut résolu dans les métadonnées de l’environnement du service de superviseur.
Avec --install-daemon, si le mode de jeton nécessite un jeton et que le SecretRef du jeton configuré est non résolu, l’onboarding échoue de manière fermée avec des conseils de correction.
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’onboarding bloque l’installation jusqu’à ce que le mode soit défini explicitement.
L’onboarding local écrit gateway.mode="local" dans la configuration. Si un fichier de configuration ultérieur manque gateway.mode, considérez cela comme une dommage de configuration ou une modification manuelle incomplète, et non comme un raccourci valide en mode local.
L’onboarding local installe les plugins téléchargeables sélectionnés lorsque le chemin d’installation choisi les nécessite.
L’onboarding distant écrit uniquement les informations de connexion pour le Gateway distant et n’installe pas les packages de plugins locaux.
--allow-unconfigured est une porte de dérogation d’exécution de gateway distincte. Cela ne signifie pas que l’onboarding 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

Santé de la gateway locale non interactive :

Sauf si vous transmettez --skip-health, l’onboarding attend une gateway locale accessible avant de se terminer avec succès.
--install-daemon lance d’abord le chemin d’installation de la passerelle gérée. Sans cela, vous devez déjà avoir une passerelle locale en cours d’exécution, par exemple openclaw gateway run.
Si vous souhaitez uniquement des écritures de configuration/espace de travail/amorçage en automatisation, utilisez --skip-health.
Si vous gérez vous-même les fichiers de l’espace de travail, passez --skip-bootstrap pour définir agents.defaults.skipBootstrap: true et ignorer 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 revient à un élément de connexion par dossier de Démarrage par utilisateur si la création de tâche est refusée.

Comportement de l’onboarding interactif avec le mode de référence :

Choisissez Use secret reference lorsqu’on vous le demande.
Ensuite, choisissez l’une des deux options :
- Variable d’environnement
- Provider de secrets configuré (file ou exec)
L’onboarding effectue une validation préalable rapide avant d’enregistrer la référence.
- Si la validation échoue, l’onboarding affiche l’erreur et vous permet de réessayer.

Choix de point de terminaison Z.AI non interactif

# Promptless endpoint selection
openclaw 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 non interactif Mistral :

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

Notes de flux

Types de flux

quickstart : invites minimales, génère automatiquement un jeton de passerelle.
manual : invites complètes pour le port, la liaison et l’authentification (alias de advanced).
import : exécute un provider de migration détecté, prévisualise le plan, puis applique après confirmation.

Préfiltrage du fournisseur

Lorsqu’un choix d’authentification implique un fournisseur préféré, l’intégration préfiltre les sélecteurs de modèle par défaut et de liste d’autorisation pour ce fournisseur. Pour Volcengine et BytePlus, cela correspond également aux variantes de plan de codage (volcengine-plan/*, byteplus-plan/*).

Si le filtre de fournisseur préféré ne donne encore aucun modèle chargé, l’intégration revient au catalogue non filtré au lieu de laisser le sélecteur vide.

Suites de recherche Web

Certains fournisseurs de recherche Web déclenchent des invites de suivi spécifiques au fournisseur :

Grok peut offrir une configuration x_search facultative avec le même XAI_API_KEY et un choix de modèle x_searchMoonshotAPI.
Kimi peut demander la région de l’API Moonshot (api.moonshot.ai vs api.moonshot.cn) et le modèle de recherche Web Kimi par défaut.

Autres comportements

Comportement de la portée DM d’intégration locale : Référence de configuration CLI.
Premier chat le plus rapide : openclaw dashboardOpenAIAnthropic (Interface utilisateur de contrôle, aucune configuration de canal).
Fournisseur personnalisé : connectez n’importe quel point de terminaison compatible OpenAI ou Anthropic, y compris les fournisseurs hébergés non répertoriés. Utilisez Inconnu pour la détection automatique.
Si un état Hermes est détecté, l’intégration propose un flux de migration. Utilisez Migrate pour les plans à blanc, le mode de sur écriture, les rapports et les mappages exacts.

Commandes de suivi courantes

openclaw channels add
openclaw configure
openclaw agents add <name>

Utilisez plutôt openclaw setup lorsque vous avez uniquement besoin de la configuration de base/de l’espace de travail. Utilisez openclaw configure plus tard pour des modifications ciblées et openclaw channels add pour une configuration de canal uniquement.