18 KiB
18 KiB
| read_when | sidebarTitle | summary | title | x-i18n | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
CLI reference | Référence complète du flux de configuration de la CLI, de la configuration d’authentification/modèle, des sorties et des éléments internes | Référence de configuration de la CLI |
|
Référence de configuration de la CLI
Cette page est la référence complète pour openclaw onboard.
Pour le guide rapide, voir Onboarding (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 de l’abonnement OpenAI Code, Anthropic Claude CLI 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’initialisation
- les paramètres du Gateway (port, bind, authentification, tailscale)
- les canaux et fournisseurs (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles et autres Plugins de canal intégrés)
- l’installation du daemon (LaunchAgent, unité utilisateur systemd ou tâche planifiée Windows native avec solution de repli via le dossier Startup)
- la vérification de santé
- la configuration des Skills
Le mode distant configure cette machine pour qu’elle se connecte à un Gateway situé ailleurs. Il n’installe ni ne modifie quoi que ce soit sur l’hôte distant.
Détails du flux local
- 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`). - L’option CLI `--reset` utilise par défaut `config+creds+sessions` ; 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 portées suivantes : - Configuration uniquement - Configuration + informations d’authentification + sessions - Réinitialisation complète (supprime aussi l’espace de travail) - La matrice complète des options se trouve dans [Options d’authentification et de modèle](#options-dauthentification-et-de-modèle). - Par défaut `~/.openclaw/workspace` (configurable). - Initialise les fichiers d’espace de travail nécessaires au rituel de bootstrap du premier lancement. - Structure de l’espace de travail : [Espace de travail de l’agent](/fr/concepts/agent-workspace). - Demande le port, le bind, le mode d’authentification et l’exposition tailscale. - Recommandé : conserver l’authentification par jeton activée même pour le loopback afin que les clients WS locaux doivent s’authentifier. - En mode jeton, la configuration interactive propose : - **Générer/stocker un jeton en clair** (par défaut) - **Utiliser SecretRef** (optionnel) - En mode mot de passe, la configuration interactive prend également en charge le stockage en clair ou SecretRef. - Chemin SecretRef non interactif pour le jeton : `--gateway-token-ref-env `. - 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 à tous les processus locaux. - Les binds non loopback exigent toujours une authentification. - [WhatsApp](/fr/channels/whatsapp) : connexion QR facultative - [Telegram](/fr/channels/telegram) : jeton de bot - [Discord](/fr/channels/discord) : jeton de bot - [Google Chat](/fr/channels/googlechat) : JSON de compte de service + audience du Webhook - [Mattermost](/fr/channels/mattermost) : jeton de bot + URL de base - [Signal](/fr/channels/signal) : installation facultative de `signal-cli` + configuration du compte - [BlueBubbles](/fr/channels/bluebubbles) : recommandé pour iMessage ; URL du serveur + mot de passe + Webhook - [iMessage](/fr/channels/imessage) : chemin CLI `imsg` hérité + accès à la base de données - Sécurité des messages privés : le mode par défaut est l’appairage. Le premier message privé envoie un code ; approuvez-le via `openclaw pairing approve` ou utilisez des listes d’autorisation.
- macOS : LaunchAgent
- Nécessite une session utilisateur connectée ; pour un mode headless, utilisez un LaunchDaemon personnalisé (non fourni).
- Linux et Windows via WSL2 : unité utilisateur systemd
- L’assistant tente `loginctl enable-linger ` 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 priorité
- Si la création de la tâche est refusée, OpenClaw revient à un élément de connexion par utilisateur dans le dossier Startup et démarre immédiatement le Gateway.
- Les tâches planifiées restent préférées car elles offrent un meilleur statut de supervision.
- Sélection de l’environnement d’exécution : Node (recommandé ; requis pour WhatsApp et Telegram). Bun n’est pas recommandé.
- 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 d’état, y compris les sondes de canal lorsqu’elles sont prises en charge.
- Lit les Skills disponibles et vérifie les prérequis.
- Vous permet de choisir le gestionnaire Node : npm, pnpm ou bun.
- Installe les dépendances facultatives (certaines utilisent Homebrew sur macOS).
- Résumé et étapes suivantes, y compris les options d’application iOS, Android et macOS.
Si aucune interface graphique n’est détectée, l’assistant affiche des instructions de redirection de port SSH pour l’UI de contrôle au lieu d’ouvrir un navigateur.
Si les ressources de l’UI de contrôle sont absentes, l’assistant tente de les construire ; la solution de repli est `pnpm ui:build` (installe automatiquement les dépendances UI).
Détails du mode distant
Le mode distant configure cette machine pour qu’elle se connecte à un Gateway situé ailleurs.
Le mode distant n’installe ni ne modifie quoi que ce soit sur l’hôte distant.
Ce que vous configurez :
- URL du Gateway distant (
ws://...)
- Jeton si l’authentification du Gateway distant est requise (recommandé)
- Si le Gateway n’est accessible qu’en loopback, utilisez un tunnel SSH ou un tailnet.
- Indications de découverte :
- macOS : Bonjour (`dns-sd`)
- Linux : Avahi (`avahi-browse`)
Options d’authentification et de modèle
Utilise `ANTHROPIC_API_KEY` si elle est présente ou demande une clé, puis l’enregistre pour l’utilisation par le daemon.
Si `~/.codex/auth.json` existe, l’assistant peut le réutiliser.
Les identifiants Codex CLI réutilisés restent gérés par Codex CLI ; à expiration, OpenClaw
relit d’abord cette source et, lorsque le fournisseur peut la rafraîchir, écrit
l’identifiant rafraîchi dans le stockage Codex au lieu d’en prendre lui-même la gestion.
Flux navigateur ; collez `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/*`.
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.4` lorsque le modèle n’est pas défini, vaut `openai/*` ou `openai-codex/*`.
Demande `XAI_API_KEY` et configure xAI comme fournisseur de modèle.
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](https://opencode.ai/auth).
Stocke la clé pour vous.
Demande `AI_GATEWAY_API_KEY`.
Plus de détails : [Vercel AI Gateway](/fr/providers/vercel-ai-gateway).
Demande l’ID de compte, l’ID de Gateway et `CLOUDFLARE_AI_GATEWAY_API_KEY`.
Plus de détails : [Cloudflare AI Gateway](/fr/providers/cloudflare-ai-gateway).
La configuration est écrite automatiquement. La valeur hébergée 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](/fr/providers/minimax).
La configuration est écrite automatiquement pour StepFun standard ou Step Plan sur des 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](/fr/providers/stepfun).
Demande `SYNTHETIC_API_KEY`.
Plus de détails : [Synthetic](/fr/providers/synthetic).
Demande d’abord `Cloud + Local`, `Cloud only` ou `Local only`.
`Cloud only` utilise `OLLAMA_API_KEY` avec `https://ollama.com`.
Les modes adossés à l’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 également si cet hôte Ollama est connecté pour l’accès cloud.
Plus de détails : [Ollama](/fr/providers/ollama).
Les configurations Moonshot (Kimi K2) et Kimi Coding sont écrites automatiquement.
Plus de détails : [Moonshot AI (Kimi + Kimi Coding)](/fr/providers/moonshot).
Fonctionne avec les points de terminaison compatibles OpenAI et compatibles Anthropic.
L’onboarding interactif prend en charge les mêmes choix de stockage de clé API que les autres flux de clé API de fournisseur :
- **Coller une clé API maintenant** (en clair)
- **Utiliser une référence de secret** (référence env ou référence de fournisseur configuré, avec validation préliminaire)
Indicateurs non interactifs :
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (optionnel ; revient à `CUSTOM_API_KEY`)
- `--custom-provider-id` (optionnel)
- `--custom-compatibility <openai|anthropic>` (optionnel ; `openai` par défaut)
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.
- Lorsque l’onboarding démarre à partir d’un choix d’authentification de fournisseur, le sélecteur de modèle privilégie
automatiquement ce fournisseur. Pour Volcengine et BytePlus, cette 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é serait vide, le sélecteur revient
au 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 des 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 par défaut de l’onboarding conserve les clés API comme valeurs en clair dans les profils d’authentification.
--secret-input-mode ref active le mode référence au lieu du stockage en clair des clés.
Dans la configuration interactive, vous pouvez choisir l’une des options suivantes :
- 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éliminaire rapide avant l’enregistrement.
- Références env : valide le nom de la variable + une valeur non vide dans l’environnement actuel d’onboarding.
- Références fournisseur : valide la configuration du fournisseur et résout l’id demandé.
- Si la validation préliminaire échoue, l’onboarding affiche l’erreur et vous permet de réessayer.
- En mode non interactif,
--secret-input-mode ref est uniquement adossé aux variables d’environnement.
- Définissez la variable d’environnement du fournisseur dans l’environnement du processus d’onboarding.
- Les indicateurs de clé inline (par exemple
--openai-api-key) exigent que cette variable d’environnement soit définie ; sinon l’onboarding échoue immédiatement.
- Pour les fournisseurs personnalisés, le mode
ref non interactif stocke models.providers.<id>.apiKey comme { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
- Dans ce cas de fournisseur personnalisé,
--custom-api-key exige que CUSTOM_API_KEY soit définie ; sinon l’onboarding échoue immédiatement.
- 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 : en clair ou SecretRef.
- Chemin SecretRef non interactif pour le jeton :
--gateway-token-ref-env <ENV_VAR>.
- Les configurations existantes en clair continuent de fonctionner sans changement.
Conseil pour les environnements headless et serveur : terminez OAuth sur une machine équipée d’un navigateur, puis copiez le `auth-profiles.json` de cet agent (par exemple
`~/.openclaw/agents//agent/auth-profiles.json`, ou le chemin correspondant
`$OPENCLAW_STATE_DIR/...`) vers l’hôte Gateway. `credentials/oauth.json`
n’est qu’une source d’importation héritée.
Sorties et éléments internes
Champs typiques dans ~/.openclaw/openclaw.json :
agents.defaults.workspaceagents.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 (l’onboarding local utilise par défaut per-channel-peer lorsqu’il n’est pas défini ; 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 choisissez cette option pendant les invites (les noms sont résolus en ID lorsque c’est possible)
skills.install.nodeManager
- L’indicateur
setup --node-manager accepte npm, pnpm ou bun.
- Une configuration manuelle peut toujours définir ensuite
skills.install.nodeManager: "yarn".
wizard.lastRunAtwizard.lastRunVersionwizard.lastRunCommitwizard.lastRunCommandwizard.lastRunMode
openclaw agents add écrit dans agents.list[] et dans bindings si nécessaire.
Les identifiants WhatsApp sont placés sous ~/.openclaw/credentials/whatsapp/<accountId>/.
Les sessions sont stockées sous ~/.openclaw/agents/<agentId>/sessions/.
Certains canaux sont fournis sous forme de plugins. Lorsqu’ils sont sélectionnés pendant la configuration, l’assistant
demande d’installer le plugin (npm ou chemin local) avant la configuration du canal.
RPC de l’assistant Gateway :
wizard.startwizard.nextwizard.cancelwizard.status
Les clients (application macOS et UI de contrôle) peuvent afficher les étapes sans réimplémenter la logique d’onboarding.
Comportement de la configuration de Signal :
- Télécharge la ressource de version appropriée
- La 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 à l’intérieur de WSL
Documentation associée
- Hub d’onboarding : Onboarding (CLI)
- Automatisation et scripts : Automatisation de la CLI
- Référence de commande :
openclaw onboard