--- read_when: - Vous souhaitez configurer l’inférence, puis terminer la configuration avec Crestodian summary: Référence de la CLI pour `openclaw onboard` (intégration interactive) title: Intégration x-i18n: generated_at: "2026-07-12T02:43:42Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 6e9dad7efda492e0d9ef01ef08a1fd8c81272a0d9b3aa3b945917b6878159a06 source_path: cli/onboard.md workflow: 16 --- # `openclaw onboard` Configuration guidée qui établit d’abord l’inférence : elle détecte les accès existants à l’IA, exige une complétion en direct, ne conserve que la route fonctionnelle, puis démarre Crestodian pour configurer le reste. `openclaw setup` est le même point d’entrée ; `openclaw setup --baseline` écrit uniquement la configuration et l’espace de travail de référence. Présentation détaillée du flux interactif de la CLI. Fonctionnement global de l’intégration d’OpenClaw. Sorties, fonctionnement interne et comportement de chaque étape. Options non interactives et configurations par script. Flux d’intégration de l’application de barre des menus macOS. ## Exemples ```bash openclaw onboard openclaw onboard --classic 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 ``` - `--classic` : ouvre l’assistant complet étape par étape. Cette option ne peut pas être combinée avec `--non-interactive` ; omettez `--classic` pour une configuration automatisée. - `--flow quickstart` : ouvre l’assistant classique avec un minimum d’invites et génère automatiquement un jeton de Gateway. - `--flow manual` (alias `advanced`) : ouvre l’assistant classique avec toutes les invites pour le port, l’adresse d’écoute et l’authentification. - `--flow import` : exécute un fournisseur de migration détecté (par exemple Hermes via `--import-from hermes`), affiche un aperçu du plan, puis l’applique après confirmation. L’importation ne s’exécute que sur une nouvelle configuration d’OpenClaw : réinitialisez d’abord la configuration, les identifiants, les sessions et l’état de l’espace de travail s’ils existent. Utilisez [`openclaw migrate`](/fr/cli/migrate) pour les plans de simulation, le mode d’écrasement, les rapports et les correspondances exactes. - `--modern` est un alias de compatibilité pour l’assistant de configuration conversationnel Crestodian. Il utilise le même contrôle d’inférence en direct que `openclaw crestodian` et accepte uniquement `--workspace`, `--accept-risk`, `--non-interactive` et `--json`. Les autres options de configuration sont rejetées au lieu d’être ignorées silencieusement. ## Flux guidé La commande simple `openclaw onboard` lance le flux guidé. Elle affiche l’avis de sécurité, détecte les accès à l’IA déjà disponibles via les modèles configurés, les variables d’environnement de clés d’API et les CLI locales prises en charge, puis teste le candidat recommandé avec une véritable complétion. Si ce candidat échoue, l’intégration affiche la raison et essaie automatiquement le candidat utilisable suivant. Si la détection automatique ne trouve plus de candidat, choisissez un autre candidat détecté ou saisissez une clé d’API de fournisseur dans une invite masquée. Une clé saisie manuellement est testée par le même mécanisme de complétion en direct. L’intégration guidée ne propose ni Crestodian ni de sortie permettant d’ignorer l’IA avant qu’un candidat ne réussisse. OpenClaw ne conserve la route du modèle vérifiée et son identifiant qu’après la réussite du test ; un candidat ayant échoué ne remplace pas le modèle configuré et n’enregistre pas l’identifiant essayé. La configuration de l’espace de travail et du Gateway reste inchangée jusqu’au démarrage de Crestodian. En mode guidé, `--workspace ` fournit l’espace de travail proposé à Crestodian ainsi que le contexte d’inférence isolé. Il n’est pas conservé tant que vous n’avez pas approuvé la proposition de configuration de Crestodian. Les intégrations classique et non interactive conservent leur espace de travail via leur flux de configuration habituel. Une fois l’inférence réussie, l’intégration guidée démarre immédiatement Crestodian avec le modèle vérifié. Crestodian peut ensuite configurer l’espace de travail, le Gateway, les canaux, les agents, les plugins et les autres fonctionnalités facultatives. Dans Crestodian, utilisez `open channel wizard for ` pour confier la collecte des identifiants du canal à un assistant de terminal masqué. Pour changer le fournisseur du modèle ou son authentification, quittez Crestodian et exécutez `openclaw onboard` ; Crestodian n’ouvre pas les flux guidés ou classiques des fournisseurs. Sur une installation configurée, une nouvelle exécution de `openclaw onboard` vérifie d’abord le modèle par défaut actuel ; le même flux sert donc de passe de vérification et de réparation. Si cette vérification échoue, le modèle configuré n’est jamais remplacé automatiquement : l’intégration s’arrête et demande comment continuer. La vérification s’exécute en dehors de votre espace de travail ; un modèle fourni par un plugin de l’espace de travail peut donc échouer ici tout en fonctionnant dans l’agent. Utilisez `openclaw onboard --classic` pour l’authentification propre à un fournisseur, les canaux, les Skills, la configuration d’un Gateway distant, les importations ou les contrôles complets du Gateway. Pour une configuration et une réparation conversationnelles sans rapport avec l’inférence, exécutez `openclaw crestodian` ; `openclaw onboard --modern` est un alias de compatibilité utilisant le même contrôle d’inférence. L’assistant classique peut éventuellement vérifier le modèle par défaut avec une complétion en direct, mais Crestodian ne démarrera pas tant que sa propre vérification d’inférence en direct n’aura pas réussi. Dans un terminal interactif, la commande simple `openclaw` (sans sous-commande) choisit le flux selon l’état de la configuration : - Si le fichier de configuration actif est absent ou ne contient aucun réglage défini par l’utilisateur (vide ou contenant uniquement des métadonnées), elle lance l’intégration guidée. - Si le fichier de configuration existe mais échoue à la validation, elle lance le parcours d’intégration classique avec des indications de `openclaw doctor`. Crestodian nécessite une inférence fonctionnelle et n’est pas utilisé pour réparer cet état préalable à l’inférence. - Si le fichier de configuration est valide, elle ouvre la TUI normale de l’agent. Un Gateway configuré et accessible disposant d’un agent et d’un modèle mène directement à cette interface sans intégration ni Crestodian. Sur une installation configurée, accédez à Crestodian avec `/crestodian` dans la TUI ou `openclaw crestodian`. Le protocole non chiffré `ws://` est accepté pour local loopback, les adresses IP privées littérales, `.local` et les URL de Gateway 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. ## Réinitialisation ```bash openclaw onboard --reset openclaw onboard --reset --reset-scope full ``` `--reset` efface l’état avant d’exécuter la configuration. `--reset-scope` contrôle l’étendue : `config` (configuration uniquement), `config+creds+sessions` (valeur par défaut lorsque `--reset` est fourni sans étendue) ou `full` (réinitialise également l’espace de travail). L’espace de travail n’est réinitialisé qu’avec `--reset-scope full`. ## Paramètres régionaux L’intégration interactive utilise les paramètres régionaux de l’assistant CLI pour les textes de configuration fixes. Ordre de résolution : 1. `OPENCLAW_LOCALE` 2. `LC_ALL` 3. `LC_MESSAGES` 4. `LANG` 5. Repli sur l’anglais Les paramètres régionaux pris en charge par l’assistant sont `en`, `zh-CN` et `zh-TW`. Les valeurs peuvent utiliser un 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 ou de canaux restent littéraux. ```bash OPENCLAW_LOCALE=zh-CN openclaw onboard ``` ## Configuration non interactive `--non-interactive` exige `--accept-risk` (reconnaît que les agents sont puissants et qu’un accès complet au système présente des risques). La valeur par défaut de `--mode` est `local`. ```bash 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 ; s’il est omis, l’intégration recherche `CUSTOM_API_KEY` dans l’environnement. OpenClaw marque automatiquement comme compatibles avec les images les identifiants de modèles de vision courants (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral et similaires). Fournissez `--custom-image-input` pour les identifiants personnalisés de vision inconnus, ou `--custom-text-input` pour imposer des métadonnées indiquant une prise en charge du texte uniquement. Utilisez `--custom-compatibility openai-responses` pour les points de terminaison compatibles avec OpenAI qui prennent en charge `/v1/responses`, mais pas `/v1/chat/completions` ; les valeurs valides sont `openai` (par défaut), `openai-responses` et `anthropic`. LM Studio dispose également d’une option de clé propre au fournisseur : ```bash 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 : ```bash openclaw onboard --non-interactive \ --auth-choice ollama \ --custom-base-url "http://ollama-host:11434" \ --custom-model-id "qwen3.5:27b" \ --accept-risk ``` La valeur par défaut de `--custom-base-url` est `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 tels que `kimi-k2.5:cloud` fonctionnent également ici. Stockez les clés des fournisseurs sous forme de références plutôt qu’en texte brut : ```bash 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 reposant sur l’environnement plutôt que des valeurs de clés en texte brut : pour les fournisseurs reposant sur un profil d’authentification, elle écrit `keyRef: { source: "env", provider: "default", id: }` ; pour les fournisseurs personnalisés, elle écrit `models.providers..apiKey` de la même manière (par exemple `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`). Contrat : définissez la variable d’environnement du fournisseur dans l’environnement du processus d’intégration (par exemple `OPENAI_API_KEY`) et ne fournissez pas également une option de clé en ligne sauf si cette variable d’environnement est définie ; une valeur d’option sans la variable d’environnement correspondante provoque un échec immédiat accompagné d’indications. ### Authentification du Gateway (mode non interactif) - `--gateway-auth token --gateway-token ` stocke un jeton en texte brut. `token` est le mode d’authentification par défaut. - `--gateway-auth token --gateway-token-ref-env ` stocke `gateway.auth.token` sous forme de SecretRef d’environnement. Nécessite une variable d’environnement non vide portant ce nom dans l’environnement du processus d’intégration. - `--gateway-token` et `--gateway-token-ref-env` sont mutuellement exclusifs. - Avec `--install-daemon` : un `gateway.auth.token` géré par SecretRef est validé, mais sa valeur résolue en texte brut n’est pas conservée dans les métadonnées d’environnement du service de supervision ; si la référence ne peut pas être résolue, l’installation échoue de manière sécurisée avec des indications de correction. 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 est bloquée jusqu’à ce que le mode soit explicitement défini. - L’intégration locale écrit `gateway.mode="local"` dans la configuration. Un fichier de configuration ultérieur dépourvu de `gateway.mode` indique une configuration endommagée ou une modification manuelle incomplète, et non un raccourci valide vers le mode local. - L’intégration locale installe les plugins téléchargeables nécessaires au parcours de configuration choisi (par exemple un plugin d’environnement d’exécution Codex ou Copilot pour ces choix d’authentification). L’intégration distante écrit uniquement les informations de connexion du Gateway distant : elle n’installe jamais de paquets de plugins locaux. - `--allow-unconfigured` est une échappatoire distincte de `openclaw gateway run` ; elle ne permet pas à l’intégration d’ignorer `gateway.mode`. ```bash export OPENAI_API_KEY="your-provider-key" export OPENCLAW_GATEWAY_TOKEN="your-token" openclaw onboard --non-interactive \ --mode local \ --auth-choice openai-api-key \ --secret-input-mode ref \ --gateway-auth token \ --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \ --accept-risk ``` ### État du Gateway local - Sauf si vous fournissez `--skip-health`, l’intégration attend qu’un Gateway local soit accessible avant de se terminer avec succès. - `--install-daemon` lance d’abord le parcours d’installation du Gateway géré. Sans cette option, un Gateway local doit déjà être en cours d’exécution (par exemple `openclaw gateway run`). - `--skip-health` ignore l’attente si vous souhaitez uniquement écrire la configuration, l’espace de travail et les fichiers d’amorçage dans le cadre d’une automatisation. - `--skip-bootstrap` définit `agents.defaults.skipBootstrap: true` et ignore la création de `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` et `BOOTSTRAP.md`. - Sous Windows natif, `--install-daemon` essaie d’abord les tâches planifiées, puis utilise en repli un élément de connexion propre à l’utilisateur dans le dossier de démarrage si la création de la tâche est refusée. ### Mode de référence interactif - Choisissez **Use secret reference** lorsque cela vous est demandé, puis **Environment variable** ou un fournisseur de secrets configuré (`file` ou `exec`). - L’intégration effectue une validation préalable rapide avant d’enregistrer la référence et vous permet de réessayer en cas d’échec. ### Choix de points de terminaison Z.AI `--auth-choice zai-api-key` détecte automatiquement le meilleur point de terminaison et le meilleur modèle Z.AI pour votre clé : les points de terminaison Coding Plan privilégient `zai/glm-5.2` (avec repli sur `glm-5.1` s’il n’est pas disponible) ; les points de terminaison de l’API générale utilisent par défaut `zai/glm-5.1`. Pour imposer un point de terminaison Coding Plan, choisissez directement `zai-coding-global` ou `zai-coding-cn`. ```bash # Sélection du point de terminaison sans invite openclaw onboard --non-interactive \ --auth-choice zai-coding-global \ --zai-api-key "$ZAI_API_KEY" # Autres choix de points de terminaison Z.AI : zai-coding-cn, zai-global, zai-cn ``` Mistral : ```bash openclaw onboard --non-interactive \ --auth-choice mistral-api-key \ --mistral-api-key "$MISTRAL_API_KEY" ``` ## Indicateurs non interactifs supplémentaires Authentification du modèle par jeton (utilisée avec `--auth-choice token`) : | Indicateur | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--token-provider ` | Identifiant du fournisseur de jetons qui émet le jeton | | `--token ` | Valeur du jeton pour l’authentification du modèle | | `--token-profile-id ` | Identifiant du profil d’authentification (`:manual` par défaut ; certains flux propres au fournisseur utilisent leur propre valeur par défaut, comme `anthropic:default`) | | `--token-expires-in ` | Durée d’expiration facultative du jeton (par exemple `365d`, `12h`) | Cloudflare AI Gateway : `--cloudflare-ai-gateway-account-id `, `--cloudflare-ai-gateway-gateway-id `. Contrôle de l’installation du démon : `--no-install-daemon` / `--skip-daemon` (alias ; ignorent l’installation du service Gateway), `--daemon-runtime `. Skills : `--node-manager ` (`npm` par défaut), `--skip-skills`. Configuration de l’interface utilisateur et des hooks : `--skip-ui` (ignore les invites de la Control UI/TUI), `--skip-hooks` (ignore la configuration des Webhooks/hooks), `--skip-channels`, `--skip-search`. Sortie : `--suppress-gateway-token-output` masque les sorties du Gateway/de l’interface utilisateur contenant des jetons (indications de jeton, URL de connexion automatique avec jeton intégré et lancement automatique de la Control UI) — utile dans les terminaux partagés et en CI. `--json` n’implique pas le mode non interactif dans l’intégration guidée ou classique. Avec `--modern`, JSON fournit une vue d’ensemble ponctuelle de Crestodian, puis se ferme après cet unique résultat. Utilisez `--non-interactive` pour les autres scripts. ## Préfiltrage des fournisseurs Lorsqu’un choix d’authentification implique un fournisseur privilégié, l’intégration préfiltre les sélecteurs du modèle par défaut et de la liste d’autorisation afin de n’afficher que les modèles de ce fournisseur. Le filtre correspond également aux autres fournisseurs appartenant au même Plugin, ce qui couvre les variantes de forfait de codage telles que `volcengine`/`volcengine-plan` et `byteplus`/`byteplus-plan`. Si le filtre du fournisseur privilégié ne renvoie aucun modèle chargé, l’intégration revient au catalogue non filtré au lieu de laisser le sélecteur vide. ## Questions complémentaires pour la recherche sur le Web Certains fournisseurs de recherche sur le Web déclenchent des invites complémentaires propres au fournisseur pendant l’intégration : - **Grok** peut proposer une configuration facultative de `x_search` avec la même authentification xAI et le choix d’un modèle `x_search`. - **Kimi** peut demander la région de l’API Moonshot (`api.moonshot.ai` ou `api.moonshot.cn`) et le modèle de recherche sur le Web Kimi par défaut. ## Autres comportements - Comportement de la portée des messages privés lors de l’intégration locale : [référence de configuration de la CLI](/fr/start/wizard-cli-reference#outputs-and-internals). - Premier échange le plus rapide : `openclaw dashboard` (Control UI, sans configuration de canal). - Fournisseur personnalisé : connectez n’importe quel point de terminaison compatible avec OpenAI ou Anthropic, y compris des fournisseurs hébergés non répertoriés. Utilisez la compatibilité **Unknown** pour effectuer une détection automatique au moyen d’une sonde en direct. - Si un état Hermes est détecté, l’intégration propose un flux de migration (voir `--flow import` ci-dessus). ## Commandes complémentaires courantes Utilisez ultérieurement `openclaw configure` pour des modifications ciblées sans inférence et `openclaw channels add` pour configurer uniquement les canaux. Pour modifier le fournisseur de modèles ou la voie d’authentification, exécutez plutôt `openclaw onboard`. ```bash openclaw channels add openclaw configure openclaw agents add ```