openclaw-debugging

Débogage OpenClaw

Le comportement diffère entre les tests locaux, les modèles live, les fournisseurs, le mode code, la recherche d'outils, Crabbox, CI : obtenez un signal de débogage avant de deviner.

À lire en premier

• docs/logging.md : fichiers de logs, openclaw logs, indicateurs de débogage ciblés.
• docs/reference/test.md : commandes de test local.
• docs/tools/code-mode.md : règles d'exécution/attente du mode code et catalogue d'outils.
• $openclaw-testing : choix de la voie de test.
• $crabbox : preuve large, Docker, paquet, Linux, clé live, parité CI.

Boucle par défaut

1. Déclarez la frontière suspectée : configuration, construction d'outils, payload du fournisseur, fetch, stream/SSE, rejeu de transcriptions, worker/runtime, paquet/distribution, CI.
2. Ajoutez/activez le signal le plus étroit prouvant la frontière.
3. Reproduisez avec le même fournisseur/modèle/configuration. Ne changez jamais aléatoirement de modèle sauf si le modèle lui-même est la variable testée.
4. Comparez l'état configuré avec l'activation réelle de l'exécution.
5. Corrigez la cause racine.
6. Réexécutez la sonde exacte qui échouait ; élargissez uniquement si le contrat l'exige.

Logs de transport modèle

Forme de la requête modèle / timing du stream : indicateurs d'environnement ciblés plutôt que débogage global :

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted OPENCLAW_DEBUG_SSE=peek openclaw gateway

Indicateurs utiles :

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1 : début de requête, réponse fetch, en-têtes SDK, premier événement SSE, fin du stream, erreurs de transport en info.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary : résumé borné du payload.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools : tous les noms d'outils exposés au modèle.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted : payload JSON plafonné et masqué. Utiliser uniquement pendant le débogage ; les invites et le texte des messages peuvent encore apparaître.
• OPENCLAW_DEBUG_SSE=events : timing du premier événement et de la fin du stream.
• OPENCLAW_DEBUG_SSE=peek : les cinq premiers événements SSE masqués.
• OPENCLAW_DEBUG_CODE_MODE=1 : diagnostics de la surface d'outils en mode code.

Surveillez les logs :

openclaw logs --follow

Frontières courantes

• Configuration vs activation : une configuration activée peut coexister avec des outils d'exécution désactivés, une exécution brute, une liste blanche vide, un support d'outils manquant du modèle. Vérifiez les outils réellement visibles avant d'appliquer des invariants de payload du fournisseur.
• Surface d'outils : inspectez les noms d'outils finaux visibles par le modèle, pas seulement le registre/la configuration. Le mode code = exactement exec + wait uniquement après activation réelle.
• Payload du fournisseur : avant l'appel SDK, loggez les champs, l'ID du modèle, le niveau de service, le raisonnement, la taille d'entrée, les clés de métadonnées, la présence de clé de cache d'invite, les noms d'outils.
• Fetch vs SSE : la réponse fetch prouve que les en-têtes HTTP sont arrivés ; le premier événement SSE prouve la progression du corps du fournisseur. Un écart ici = problème de stream/corps/fournisseur, pas d'exécution d'outil.
• Worker/distribution : toucher aux workers, aux imports dynamiques, aux exports de paquets, aux frontières d'exécution paresseuses, aux chemins publiés → pnpm build.
• Clés live : clés fournisseur manquantes → workflow secret configuré avant de déclarer la preuve live bloquée. Les vérifications d'environnement ne font que vérifier la présence ; n'imprimez jamais de secrets.

Récupération des sessions et transcriptions

Rapport de bogue de session de chat : récupérez la transcription réelle, l'attribution de l'expéditeur, les pièces jointes comme preuves.

CLI d'abord (nécessite une installation configurée ; sans danger pour la passerelle live) :

openclaw sessions list --agent <agentId> --json
openclaw sessions tail
openclaw sessions export-trajectory

Documentation : disposition du stockage docs/reference/database-schemas.md ; CLI https://docs.openclaw.ai/cli/sessions.

Stockage brut : CLI indisponible (par ex. hôte distant via SSH) ou nécessité de détails au niveau des événements :

• Plan de données par agent : ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Schéma canonique : src/state/openclaw-agent-schema.sql.
• État hébergé/systemd : répertoire personnel de l'utilisateur du service (par ex. /home/openclaw/.openclaw/...), pas celui de root. Root peut avoir une installation égarée séparée avec des agents différents. Répertoire d'agent attendu manquant : localisez la vraie base de données avec find / -maxdepth 6 -name openclaw-agent.sqlite.
• Fragment d'ID de session d'URL de chat web : /chat/<agentId>/<slug>-<hex>. Résolvez dans session_nodes : session_key LIKE '%<hex>%' → current_session_id, display_name. Forme de la clé : agent:<agentId>:<surface>:<uuid> ; les sessions de sous-agent utilisent la surface subagent.
• Transcription : transcript_events (session_id, seq, event_json). event_json.message : role (user/assistant/toolResult) + content (chaîne ou parties de type text/toolCall/image).
• Provenance de l'expéditeur : les messages utilisateur réels portent message.__openclaw (senderId, senderName, senderIsOwner) ; les entrées synthétisées par l'exécution ne le font pas. Distinguez le texte rédigé par l'opérateur des invites injectées avec cela.
• Recherche en texte intégral dans les transcriptions : session_transcript_fts.
• Pièces jointes : media://inbound/<file> URLs → <state-dir>/media/inbound/<file>.
• Les images attachées par l'utilisateur ne sont pas des parties de contenu image. L'enveloppe du message porte les entrées message.__openclaw.media[] : url (media://inbound/<file>), contentType, kind, fileName. Un extracteur basé uniquement sur les parties manque chaque image ; grep brut event_json pour media://. Hôte distant : copiez les fichiers localement avec scp (un chemin distant par argument scp) ; lisez-y.

Les hôtes sans binaire sqlite3 ont encore Node : node:sqlite ne nécessite aucune dépendance.

node -e 'const {DatabaseSync}=require("node:sqlite");
const db=new DatabaseSync(process.argv[1],{readOnly:true});
console.log(JSON.stringify(db.prepare(
  "SELECT seq,event_json FROM transcript_events WHERE session_id=? ORDER BY seq"
).all(process.argv[2])))' <chemin-bd> <id-session>

• Ouvrez toujours les magasins live en readOnly: true ; n'écrivez jamais dans l'état de la passerelle en cours d'exécution (règles de validation AGENTS.md racine).
• Travail avec données réalistes : copiez d'abord la base de données dans le répertoire d'état de développement.

Pointeurs de code

• Payload modèle + flux Responses : src/agents/openai-transport-stream.ts
• Fetch/timing protégé : src/agents/provider-transport-fetch.ts
• Wrappers de fournisseur OpenAI/Codex : src/llm/providers/stream-wrappers/openai.ts
• Construction d'outils, recherche d'outils, activation du mode code : src/agents/embedded-agent-runner/run/attempt.ts
• Exécution en mode code et worker : src/agents/code-mode.ts src/agents/code-mode.worker.ts
• Catalogue de recherche d'outils : src/agents/tool-search.ts

Choix de la preuve

• Bogue simple d'aide/payload : Vitest local ciblé.
• Documentation/logs uniquement : pnpm check:docs + git diff --check.
• Worker/distribution/import paresseux/surface de paquet : tests ciblés + pnpm build.
• Comportement live fournisseur/modèle : même fournisseur/modèle, indicateurs de débogage, clé réelle si disponible.
• Docker/paquet/Linux/parité CI : worker Linux dédié actuel si capable ; sinon $crabbox.
• Échec CI : SHA exact, job pertinent uniquement ; logs seulement après échec/achèvement.

Habitude de sortie

Rapportez :

• frontière testée
• forme exacte de la commande/env, masquée
• signal observé, par ex. noms d'outils ou timing du premier événement SSE
• emplacement du correctif
• preuve étroite + risque résiduel