English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Guides

Référence de configuration de la CLI

Cette page est la référence complète pour openclaw onboard. Pour le guide court, consultez Intégration (CLI).

Ce que fait l’assistant

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

  • La configuration du modèle et de l’authentification (OAuth d’abonnement OpenAI Code, CLI Anthropic Claude ou clé API, ainsi que les options MiniMax, GLM, Ollama, Moonshot, StepFun et AI Gateway)
  • L’emplacement de l’espace de travail et les fichiers d’amorçage
  • Les paramètres du Gateway (port, liaison, authentification, Tailscale)
  • Les canaux et fournisseurs (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, iMessage et autres Plugins de canal groupés)
  • L’installation du daemon (LaunchAgent, unité utilisateur systemd ou tâche planifiée Windows native avec repli sur le dossier de démarrage)
  • Le contrôle de santé
  • La configuration des Skills

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

Détails du flux local

  • Détection de la configuration existante

    • Si ~/.openclaw/openclaw.json existe, choisissez Conserver, Modifier ou Réinitialiser.
    • Relancer l’assistant n’efface rien, sauf si vous choisissez explicitement Réinitialiser (ou passez --reset).
    • CLI --reset utilise config+creds+sessions par défaut ; utilisez --reset-scope full pour supprimer aussi 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 et propose les périmètres suivants :
      • Configuration uniquement
      • Configuration + identifiants + sessions
      • Réinitialisation complète (supprime aussi l’espace de travail)

  • Modèle et authentification

  • Espace de travail

    • ~/.openclaw/workspace par défaut (configurable).
    • Ajoute les fichiers d’espace de travail nécessaires au rituel d’amorçage de première exécution.
    • Organisation de l’espace de travail : Espace de travail de l’agent.

  • Gateway

    • Demande le port, la liaison, le mode d’authentification et l’exposition Tailscale.
    • Recommandé : conserver l’authentification par jeton activée, même pour la boucle locale, afin que les clients WS locaux doivent s’authentifier.
    • En mode jeton, la configuration interactive propose :
      • Générer/stocker un jeton en texte clair (par défaut)
      • Utiliser SecretRef (optionnel)
    • En mode mot de passe, la configuration interactive prend aussi en charge le stockage en texte clair ou SecretRef.
    • Chemin SecretRef de jeton non interactif : --gateway-token-ref-env <ENV_VAR>.
      • Nécessite une variable d’environnement non vide dans l’environnement du processus d’intégration.
      • Ne peut pas être combiné avec --gateway-token.
    • Désactivez l’authentification uniquement si vous faites entièrement confiance à chaque processus local.
    • Les liaisons hors boucle locale exigent toujours une authentification.

  • Canaux

    • WhatsApp : connexion QR optionnelle
    • Telegram : jeton de bot
    • Discord : jeton de bot
    • Google Chat : JSON de compte de service + audience Webhook
    • Mattermost : jeton de bot + URL de base
    • Signal : installation optionnelle de signal-cli + configuration du compte
    • iMessage : chemin CLI imsg + accès à la base de données Messages ; utilisez un wrapper SSH lorsque le Gateway s’exécute hors Mac
    • Sécurité des MP : l’association est utilisée par défaut. Le premier MP envoie un code ; approuvez avec openclaw pairing approve <channel> <code> ou utilisez des listes d’autorisation.

  • Installation du daemon

    • macOS : LaunchAgent
      • Nécessite une session utilisateur ouverte ; pour le mode sans interface, utilisez un LaunchDaemon personnalisé (non fourni).
    • Linux et Windows via WSL2 : unité utilisateur systemd
      • L’assistant tente loginctl enable-linger <user> afin que le Gateway reste actif après la déconnexion.
      • Peut demander sudo (écrit dans /var/lib/systemd/linger) ; il essaie d’abord sans sudo.
    • Windows natif : tâche planifiée en premier
      • Si la création de la tâche est refusée, OpenClaw se replie sur un élément de connexion dans le dossier de démarrage propre à l’utilisateur et démarre immédiatement le Gateway.
      • Les tâches planifiées restent préférées, car elles fournissent un meilleur statut de supervision.
    • Sélection du runtime : Node (recommandé ; requis pour WhatsApp et Telegram). Bun n’est pas recommandé.

  • Contrôle de santé

    • Démarre le Gateway (si nécessaire) et exécute openclaw health.
    • openclaw status --deep ajoute la sonde de santé du Gateway en direct à la sortie de statut, y compris les sondes de canal lorsqu’elles sont prises en charge.

  • Skills

    • Lit les Skills disponibles et vérifie les exigences.
    • Vous permet de choisir le gestionnaire Node : npm, pnpm ou bun.
    • Installe les dépendances optionnelles pour les Skills groupés de confiance lorsque l’installateur requis est disponible.
    • Ignore les installateurs Homebrew, uv et Go indisponibles, puis regroupe les Skills affectés avec des consignes de configuration manuelle. Exécutez openclaw doctor après avoir installé les prérequis manquants.

  • Terminer

    • Résumé et prochaines étapes, y compris les options d’app iOS, Android et macOS.

    • Détails du mode distant

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

    Ce que vous définissez :

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

    Options d’authentification et de modèle

    Clé API Anthropic

    Utilise ANTHROPIC_API_KEY si elle est présente ou demande une clé, puis l’enregistre pour l’utilisation par le daemon.

    Abonnement OpenAI Code (OAuth)

    Flux navigateur ; collez code#state.

    Définit agents.defaults.model sur openai/gpt-5.5 via le runtime Codex lorsque le modèle n’est pas défini ou appartient déjà à la famille OpenAI.

    Abonnement OpenAI Code (association d’appareil)

    Flux d’association navigateur avec un code d’appareil de courte durée.

    Définit agents.defaults.model sur openai/gpt-5.5 via le runtime Codex lorsque le modèle n’est pas défini ou appartient déjà à la famille OpenAI.

    Clé API OpenAI

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

    Définit agents.defaults.model sur openai/gpt-5.5 lorsque le modèle n’est pas défini, vaut openai/* ou correspond à des références de modèles Codex héritées.

    OAuth xAI (Grok)

    Connexion navigateur pour les comptes SuperGrok ou X Premium éligibles. C’est le chemin xAI recommandé pour la plupart des utilisateurs. OpenClaw stocke le profil d’authentification obtenu pour les modèles Grok, Grok web_search, x_search et code_execution.

    Code d’appareil xAI (Grok)

    Connexion navigateur adaptée au distant avec un code court au lieu d’un rappel localhost. Utilisez-la depuis SSH, Docker ou des hôtes VPS.

    Clé API xAI (Grok)

    Demande XAI_API_KEY et configure xAI comme fournisseur de modèles. Utilisez ceci lorsque vous voulez une clé API xAI Console au lieu de l’OAuth d’abonnement.

    OpenCode

    Demande OPENCODE_API_KEY (ou OPENCODE_ZEN_API_KEY) et vous permet de choisir le catalogue Zen ou Go. URL de configuration : opencode.ai/auth.

    Clé API (générique)

    Stocke la clé pour vous.

    Vercel AI Gateway

    Demande AI_GATEWAY_API_KEY. Plus de détails : Vercel AI Gateway.

    Cloudflare AI Gateway

    Demande l’ID de compte, l’ID de Gateway et CLOUDFLARE_AI_GATEWAY_API_KEY. Plus de détails : Cloudflare AI Gateway.

    MiniMax

    La configuration est écrite automatiquement. La valeur par défaut hébergée est MiniMax-M3 ; 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 mondiaux. Le mode standard inclut actuellement step-3.5-flash, et Step Plan inclut aussi step-3.5-flash-2603. Plus de détails : StepFun.

    Synthetic (compatible Anthropic)

    Demande SYNTHETIC_API_KEY. Plus de détails : Synthetic.

    Ollama (modèles ouverts Cloud et locaux)

    Demande d’abord Cloud + Local, Cloud only ou Local only. Cloud only utilise OLLAMA_API_KEY avec https://ollama.com. Les modes adossés à un hôte demandent l’URL de base (par défaut http://127.0.0.1:11434), découvrent les modèles disponibles et suggèrent des valeurs par défaut. Cloud + Local vérifie aussi si cet hôte Ollama est connecté pour l’accès au Cloud. Plus de détails : Ollama.

    Moonshot et Kimi Coding

    Les configurations Moonshot (Kimi K2) et Kimi Coding sont écrites automatiquement. Plus de détails : Moonshot AI (Kimi + Kimi Coding).

    Fournisseur personnalisé

    Fonctionne avec les points de terminaison compatibles OpenAI et compatibles Anthropic.

    L’intégration interactive prend en charge les mêmes choix de stockage de clé API que les autres flux de clé API de fournisseur :

    • Coller la clé API maintenant (texte clair)
    • Utiliser une référence secrète (référence env ou référence de fournisseur configurée, avec validation préalable)

    Indicateurs non interactifs :

    • --auth-choice custom-api-key
    • --custom-base-url
    • --custom-model-id
    • --custom-api-key (optionnel ; se replie sur CUSTOM_API_KEY)
    • --custom-provider-id (optionnel)
    • --custom-compatibility <openai|openai-responses|anthropic> (optionnel ; par défaut openai)
    • --custom-image-input / --custom-text-input (optionnel ; remplace la capacité d’entrée du modèle inférée)
    Ignorer

    Laisse l’authentification non configurée.

    Comportement du modèle :

    • Choisissez le modèle par défaut parmi les options détectées, ou saisissez manuellement le fournisseur et le modèle.
    • L’intégration d’un fournisseur personnalisé déduit la prise en charge des images pour les ID de modèles courants et ne demande une confirmation que lorsque le nom du modèle est inconnu.
    • Lorsque l’intégration démarre depuis un choix d’authentification de fournisseur, le sélecteur de modèle privilégie automatiquement ce fournisseur. Pour Volcengine et BytePlus, la même préférence correspond aussi à leurs variantes de plan de codage (volcengine-plan/*, byteplus-plan/*).
    • Si ce filtre de fournisseur préféré produisait une liste vide, le sélecteur se replie sur le catalogue complet au lieu de n’afficher aucun modèle.
    • L’assistant exécute une vérification du modèle et avertit si le modèle configuré est inconnu ou si l’authentification manque.

    Chemins des identifiants et profils :

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

    Mode de stockage des identifiants :

    • Le comportement de configuration initiale par défaut conserve les clés d’API sous forme de valeurs en clair dans les profils d’authentification.
    • --secret-input-mode ref active le mode référence au lieu du stockage de clés en clair. Dans la configuration interactive, vous pouvez choisir l’un des deux :
      • référence de variable d’environnement (par exemple keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
      • référence de fournisseur configuré (file ou exec) avec alias de fournisseur + id
    • Le mode référence interactif exécute une validation préalable rapide avant l’enregistrement.
      • Références d’environnement : valide le nom de la variable + une valeur non vide dans l’environnement de configuration initiale actuel.
      • Références de fournisseur : valide la configuration du fournisseur et résout l’id demandé.
      • Si la validation préalable échoue, la configuration initiale affiche l’erreur et vous permet de réessayer.
    • En mode non interactif, --secret-input-mode ref s’appuie uniquement sur l’environnement.
      • Définissez la variable d’environnement du fournisseur dans l’environnement du processus de configuration initiale.
      • Les indicateurs de clé intégrés (par exemple --openai-api-key) exigent que cette variable d’environnement soit définie ; sinon, la configuration initiale échoue rapidement.
      • Pour les fournisseurs personnalisés, le mode non interactif ref 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éfini ; sinon, la configuration initiale échoue rapidement.
    • Les identifiants d’authentification du Gateway prennent en charge les choix en clair et SecretRef dans la configuration interactive :
      • Mode jeton : Générer/stocker un jeton en clair (par défaut) ou Utiliser SecretRef.
      • Mode mot de passe : texte clair ou SecretRef.
    • Chemin SecretRef de jeton non interactif : --gateway-token-ref-env &lt;ENV_VAR&gt;.
    • Les configurations existantes en clair continuent de fonctionner sans changement.

    Sorties et éléments internes

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

    • agents.defaults.workspace
    • agents.defaults.skipBootstrap lorsque --skip-bootstrap est passé
    • agents.defaults.model / models.providers (si Minimax est choisi)
    • tools.profile (la configuration initiale locale utilise par défaut "coding" lorsqu’il n’est pas défini ; les valeurs explicites existantes sont conservées)
    • gateway.* (mode, liaison, auth, tailscale)
    • session.dmScope (la configuration initiale locale définit par défaut cette valeur sur per-channel-peer lorsqu’elle n’est pas définie ; les valeurs explicites existantes sont conservées)
    • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
    • Listes d’autorisation de canaux (Slack, Discord, Matrix, Microsoft Teams) lorsque vous les activez pendant les invites (les noms sont résolus en ID lorsque possible)
    • skills.install.nodeManager
      • L’indicateur setup --node-manager accepte npm, pnpm ou bun.
      • La configuration manuelle peut toujours définir skills.install.nodeManager: "yarn" ultérieurement.
    • wizard.lastRunAt
    • wizard.lastRunVersion
    • wizard.lastRunCommit
    • wizard.lastRunCommand
    • wizard.lastRunMode
    • wizard.securityAcknowledgedAt

    openclaw agents add écrit agents.list[] et les bindings facultatifs.

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

    RPC de l’assistant 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 de configuration initiale.

    Comportement de configuration de Signal :

    • Télécharge l’artefact de version approprié
    • Le stocke sous ~/.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 lorsqu’ils sont disponibles
    • Windows utilise WSL2 et suit le flux Linux signal-cli dans WSL

    Docs associées

    Was this useful?
    On this page

    On this page