Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Assistants de débogage pour la sortie en streaming, en particulier lorsqu’un fournisseur mélange le raisonnement au texte normal.

​
Remplacements de débogage à l’exécution

Utilisez /debug dans le chat pour définir des remplacements de configuration uniquement à l’exécution (en mémoire, pas sur le disque). /debug est désactivé par défaut ; activez-le avec commands.debug: true. C’est pratique lorsque vous devez basculer des paramètres obscurs sans modifier openclaw.json. Exemples : 
/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug unset messages.responsePrefix
/debug reset
/debug reset efface tous les remplacements et revient à la configuration sur disque.

​
Sortie de trace de session

Utilisez /trace lorsque vous voulez voir les lignes de trace/débogage appartenant au Plugin dans une session sans activer le mode détaillé complet. Exemples : 
/trace
/trace on
/trace off
Utilisez /trace pour les diagnostics de Plugin, comme les résumés de débogage Active Memory. Continuez à utiliser /verbose pour la sortie détaillée normale d’état/outils, et continuez à utiliser /debug pour les remplacements de configuration uniquement à l’exécution.

​
Trace du cycle de vie des Plugins

Utilisez OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 lorsque les commandes de cycle de vie des Plugins semblent lentes et que vous avez besoin d’une décomposition intégrée des phases pour les métadonnées de Plugin, la découverte, le registre, le miroir d’exécution, la mutation de configuration et le travail d’actualisation. La trace est optionnelle et écrit sur stderr, de sorte que la sortie de commande JSON reste analysable. Exemple : 
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
Exemple de sortie : 
[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
Utilisez ceci pour étudier le cycle de vie des Plugins avant de recourir à un profileur CPU. Si la commande s’exécute depuis une extraction des sources, préférez mesurer l’exécution construite avec node dist/entry.js ... après pnpm build ; pnpm openclaw ... mesure aussi la surcharge du lanceur depuis les sources.

​
Profilage du démarrage et des commandes de la CLI

Utilisez le benchmark de démarrage versionné lorsqu’une commande semble lente : 
pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
Pour un profilage ponctuel via le lanceur source normal, définissez OPENCLAW_RUN_NODE_CPU_PROF_DIR : 
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
Le lanceur source ajoute les indicateurs de profil CPU Node et écrit un .cpuprofile pour la commande. Utilisez ceci avant d’ajouter une instrumentation temporaire au code de commande. Pour les blocages au démarrage qui ressemblent à du travail synchrone du système de fichiers ou du chargeur de modules, ajoutez l’indicateur de trace d’E/S synchrones de Node via le lanceur source : 
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
pnpm gateway:watch laisse cet indicateur désactivé par défaut pour l’enfant Gateway surveillé. Définissez OPENCLAW_TRACE_SYNC_IO=1 lorsque vous voulez explicitement la sortie de trace d’E/S synchrones Node en mode surveillance.

​
Mode surveillance du Gateway

Pour une itération rapide, lancez le gateway sous le surveillant de fichiers : 
pnpm gateway:watch
Par défaut, cela démarre ou redémarre une session tmux nommée openclaw-gateway-watch-main (ou une variante spécifique au profil/port telle que openclaw-gateway-watch-dev-19001) et s’y attache automatiquement depuis les terminaux interactifs. Les shells non interactifs, la CI et les appels d’exécution d’agent restent détachés et affichent plutôt les instructions d’attache. Attachez-vous manuellement si nécessaire : 
tmux attach -t openclaw-gateway-watch-main
Le volet tmux exécute le surveillant brut : 
node scripts/watch-node.mjs gateway --force
Utilisez le mode premier plan lorsque tmux n’est pas souhaité : 
pnpm gateway:watch:raw
# or
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
Désactivez l’attache automatique tout en conservant la gestion tmux : 
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
Profilez le temps CPU du Gateway surveillé lors du débogage des points chauds de démarrage/d’exécution : 
pnpm gateway:watch --benchmark
Le wrapper de surveillance consomme --benchmark avant d’invoquer le Gateway et écrit un .cpuprofile V8 par sortie d’enfant Gateway sous .artifacts/gateway-watch-profiles/. Arrêtez ou redémarrez le gateway surveillé pour vider le profil actuel, puis ouvrez-le avec Chrome DevTools ou Speedscope : 
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
Utilisez --benchmark-dir <path> lorsque vous voulez placer les profils ailleurs. Utilisez --benchmark-no-force lorsque vous voulez que l’enfant benchmarké ignore le nettoyage de port --force par défaut et échoue rapidement si le port Gateway est déjà utilisé. Le mode benchmark supprime par défaut le bruit de trace d’E/S synchrones. Définissez OPENCLAW_TRACE_SYNC_IO=1 avec --benchmark lorsque vous voulez explicitement à la fois les profils CPU et les traces de pile d’E/S synchrones Node. En mode benchmark, ces blocs de trace sont écrits dans gateway-watch-output.log sous le répertoire de benchmark et filtrés du volet de terminal ; les journaux normaux du Gateway restent visibles. Le wrapper tmux transporte dans le volet les sélecteurs d’exécution non secrets courants, tels que OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT et OPENCLAW_SKIP_CHANNELS. Placez les identifiants de fournisseur dans votre profil/configuration normale, ou utilisez le mode premier plan brut pour les secrets éphémères ponctuels. Si le Gateway surveillé quitte pendant le démarrage, le surveillant exécute openclaw doctor --fix --non-interactive une fois et redémarre l’enfant Gateway. Utilisez OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 lorsque vous voulez l’échec de démarrage initial sans la passe de réparation réservée au développement. Le volet tmux géré utilise aussi par défaut des journaux Gateway colorés pour la lisibilité ; définissez FORCE_COLOR=0 au lancement de pnpm gateway:watch pour désactiver la sortie ANSI. Le surveillant redémarre lors de changements de fichiers pertinents pour la construction sous src/, des fichiers source d’extension, des métadonnées d’extension package.json et openclaw.plugin.json, de tsconfig.json, package.json et tsdown.config.ts. Les changements de métadonnées d’extension redémarrent le gateway sans forcer une reconstruction tsdown ; les changements de source et de configuration reconstruisent toujours dist d’abord. Ajoutez tout indicateur de CLI gateway après gateway:watch et il sera transmis à chaque redémarrage. Relancer la même commande de surveillance recrée le volet tmux nommé, et le surveillant brut conserve toujours son verrou de surveillant unique afin que les parents de surveillant en double soient remplacés au lieu de s’accumuler.

​
Profil de développement + gateway de développement (—dev)

Utilisez le profil de développement pour isoler l’état et lancer une configuration sûre et jetable pour le débogage. Il existe deux indicateurs --dev :
  • --dev global (profil) : isole l’état sous ~/.openclaw-dev et définit par défaut le port du gateway sur 19001 (les ports dérivés se décalent avec lui).
  • gateway --dev : indique au Gateway de créer automatiquement une configuration + un espace de travail par défaut lorsqu’ils sont absents (et d’ignorer BOOTSTRAP.md).
Flux recommandé (profil de développement + bootstrap de développement) : 
pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui
Si vous n’avez pas encore d’installation globale, exécutez la CLI via pnpm openclaw .... Ce que cela fait :
  1. Isolation du profil (--dev global)
    • OPENCLAW_PROFILE=dev
    • OPENCLAW_STATE_DIR=~/.openclaw-dev
    • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
    • OPENCLAW_GATEWAY_PORT=19001 (browser/canvas se décalent en conséquence)
  2. Bootstrap de développement (gateway --dev)
    • Écrit une configuration minimale si elle manque (gateway.mode=local, liaison loopback).
    • Définit agent.workspace sur l’espace de travail de développement.
    • Définit agent.skipBootstrap=true (pas de BOOTSTRAP.md).
    • Amorçe les fichiers de l’espace de travail s’ils manquent : AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
    • Identité par défaut : C3-PO (droïde protocolaire).
    • Ignore les fournisseurs de canaux en mode développement (OPENCLAW_SKIP_CHANNELS=1).
Flux de réinitialisation (nouveau départ) : 
pnpm gateway:dev:reset
--dev est un indicateur de profil global et certains lanceurs le consomment. Si vous devez l’écrire explicitement, utilisez la forme avec variable d’environnement :
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
--reset efface la configuration, les identifiants, les sessions et l’espace de travail de développement (avec trash, pas rm), puis recrée la configuration de développement par défaut.
Si un gateway non développement est déjà en cours d’exécution (launchd ou systemd), arrêtez-le d’abord :
openclaw gateway stop

​
Journalisation du flux brut (OpenClaw)

OpenClaw peut journaliser le flux assistant brut avant tout filtrage/formatage. C’est la meilleure façon de voir si le raisonnement arrive sous forme de deltas de texte brut (ou sous forme de blocs de réflexion séparés). Activez-la via la CLI : 
pnpm gateway:watch --raw-stream
Remplacement optionnel du chemin : 
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
Variables d’environnement équivalentes : 
OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
Fichier par défaut : ~/.openclaw/logs/raw-stream.jsonl

​
Journalisation des fragments bruts (pi-mono)

Pour capturer les fragments bruts compatibles OpenAI avant qu’ils soient analysés en blocs, pi-mono expose un journaliseur séparé : 
PI_RAW_STREAM=1
Chemin optionnel : 
PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
Fichier par défaut : ~/.pi-mono/logs/raw-openai-completions.jsonl
Remarque : ceci n’est émis que par les processus utilisant le fournisseur openai-completions de pi-mono.

​
Notes de sécurité

  • Les journaux de flux brut peuvent inclure les prompts complets, la sortie des outils et les données utilisateur.
  • Gardez les journaux locaux et supprimez-les après le débogage.
  • Si vous partagez des journaux, nettoyez d’abord les secrets et les données personnelles.

​
Débogage dans VSCode

Les cartes source sont requises pour activer le débogage dans les IDE basés sur VSCode, car de nombreux fichiers générés se retrouvent avec des noms hachés dans le cadre du processus de construction. Les configurations launch.json incluses ciblent le service Gateway, mais peuvent être adaptées rapidement à d’autres usages :
  1. Reconstruire et déboguer Gateway - Débogue le service Gateway après avoir créé une nouvelle construction
  2. Déboguer Gateway - Débogue le service Gateway d’une construction préexistante

​
Configuration

La configuration Reconstruire et déboguer Gateway par défaut est prête à l’emploi ; elle supprimera automatiquement le dossier /dist et reconstruira le projet avec le débogage activé :
  1. Ouvrez le panneau Exécuter et déboguer depuis la barre d’activité ou appuyez sur Ctrl+Shift+D
  2. Dans l’IDE, assurez-vous que Reconstruire et déboguer Gateway est sélectionné dans la liste déroulante de configuration, puis appuyez sur le bouton Démarrer le débogage
Autrement - si vous préférez gérer manuellement les processus de construction et de débogage :
  1. Ouvrez un terminal et activez les cartes source :
    • Linux/macOS : export OUTPUT_SOURCE_MAPS=1
    • Windows (PowerShell) : $env:OUTPUT_SOURCE_MAPS="1"
    • Windows (CMD) : set OUTPUT_SOURCE_MAPS=1
  2. Dans le même terminal, reconstruisez le projet : pnpm clean:dist && pnpm build
  3. Dans l’IDE, sélectionnez l’option Déboguer Gateway dans la liste déroulante de configuration Exécuter et déboguer, puis appuyez sur le bouton Démarrer le débogage
Vous pouvez maintenant définir des points d’arrêt dans vos fichiers source TypeScript (répertoire src/) et le débogueur associera correctement les points d’arrêt au JavaScript compilé via les cartes source. Vous pourrez inspecter les variables, parcourir le code pas à pas et examiner les piles d’appels comme prévu.

​
Notes

  • Si vous utilisez l’option “Rebuild and Debug Gateway” - chaque fois que le débogueur est lancé, il supprimera complètement le dossier /dist et exécutera un pnpm build complet avec les cartes source activées avant de démarrer le Gateway
  • Si vous utilisez l’option “Debug Gateway” - les sessions de débogage peuvent être démarrées et arrêtées à tout moment sans affecter le dossier /dist, mais vous devez utiliser un processus de terminal séparé pour activer le débogage et gérer le cycle de construction
  • Modifiez les paramètres launch.json pour args afin de déboguer d’autres sections du projet
  • Si vous devez utiliser la CLI OpenClaw construite pour d’autres tâches (c.-à-d. dashboard --no-open si votre session de débogage génère un nouveau jeton d’authentification), vous pouvez l’exécuter dans un autre terminal avec node ./openclaw.mjs ou créer un alias shell comme alias openclaw-build="node $(pwd)/openclaw.mjs"

​
Connexe