Logs et monitoring OpenClaw

Introduction

Un dispositif OpenClaw logs monitoring doit répondre à trois questions : le Gateway est-il disponible, les canaux livrent-ils les messages, et les runs restent-ils sains ? Il est utile dès qu’OpenClaw fonctionne sans terminal surveillé en permanence. Il est inutile de commencer par une stack Grafana complexe si un seul Gateway de test suffit : la CLI et les fichiers JSONL couvrent déjà le premier niveau. Ce guide présente les chemins réels, les commandes actuelles, la redaction, les probes, les diagnostics ciblés et l’export OpenTelemetry. Il remplace les faux tracebacks Python, variables LOG_FORMAT et endpoints Prometheus supposés.

Résumé rapide

• Suivre le journal applicatif avec openclaw logs --follow.
• Vérifier Gateway et canaux avec status --all et channels status --probe.
• Garder info par défaut et activer le debug de façon ciblée.
• Exporter métriques, traces et logs via le plugin diagnostics-otel.
• Alerter sur disponibilité, erreurs, files, latence, coûts et saturation disque.

Comprendre les surfaces d’observabilité

OpenClaw possède deux surfaces de logs principales. Le Gateway écrit des lignes JSON structurées dans un fichier journal et produit une sortie console adaptée au terminal. Le Control UI et openclaw logs lisent le même journal applicatif. Par défaut sur Linux, le chemin historique est /tmp/openclaw/openclaw-YYYY-MM-DD.log; un profil nommé ajoute son nom au fichier. Windows utilise un répertoire temporaire propre à l’utilisateur.

Chaque fichier change avec la date locale du serveur et tourne lorsqu’il atteint la limite configurée, 100 Mo par défaut. OpenClaw conserve plusieurs archives numérotées puis élague les fichiers datés. Un logging.file explicite remplace le chemin. Ces mécanismes rendent inutile un faux volume /app/logs lorsque l’on n’a pas volontairement modifié la destination.

Les logs décrivent des événements ; les diagnostics structurés alimentent métriques et traces. Le plugin officiel diagnostics-otel exporte en OTLP/HTTP protobuf vers un collecteur compatible. Il peut transmettre traces, métriques et logs, ou écrire des logs JSONL sur stdout pour une plateforme de conteneurs. OpenClaw n’annonce pas un endpoint Prometheus à scraper automatiquement : Prometheus ou Grafana interviennent derrière un collecteur ou backend OpenTelemetry selon votre architecture.

Enfin, l’état de santé ne se réduit pas au processus. gateway status décrit le service et le Gateway ; status --all ajoute notamment sécurité, plugins et mémoire ; channels status --probe contacte les comptes lorsque le plugin sait le faire. Une santé de cycle de vie OK sans probe n’est pas la preuve qu’un message traverse réellement le canal.

Construire un monitoring OpenClaw fiable

1. Lire le journal en direct

La commande recommandée utilise le RPC du Gateway :

openclaw logs --follow

Pour une collecte ou un traitement automatique :

openclaw logs --limit 500 --json
openclaw logs --follow --plain --utc

Les modes non TTY restent lisibles et le mode JSON émet des objets typés pour les métadonnées, entrées, avis de rotation et erreurs. Si vous fournissez un --url explicite, ajoutez explicitement --token; la CLI refuse de réutiliser silencieusement des credentials implicites pour une URL remplacée.

Pour un canal :

openclaw channels logs --channel telegram
openclaw channels logs --channel all --json

Dans Docker, combinez ce journal applicatif avec docker compose logs -f openclaw-gateway. Le premier donne les événements structurés OpenClaw ; le second aide à voir le cycle de vie du conteneur et les erreurs avant initialisation du RPC.

2. Configurer les niveaux sans masquer l’essentiel

La configuration vit sous logging dans ~/.openclaw/openclaw.json :

{
  logging: {
    level: "info",
    file: "/var/log/openclaw/gateway.jsonl",
    consoleLevel: "info",
    consoleStyle: "pretty"
  }
}

Les niveaux valides sont silent, fatal, error, warn, info, debug et trace. logging.level concerne le fichier JSONL ; logging.consoleLevel concerne la console. Pour un diagnostic ponctuel :

OPENCLAW_LOG_LEVEL=debug openclaw gateway run
openclaw --log-level debug gateway run

La seconde forme a la priorité pour cette commande. --verbose augmente la sortie console et les détails WebSocket, mais ne change pas le niveau du fichier. Après investigation, revenez à info afin de réduire le bruit et le risque de capturer du contexte inutile.

3. Exploiter les champs de corrélation

Les lignes JSONL contiennent, lorsqu’ils sont disponibles, hostname, message, agent_id, session_id et channel. Un contexte de trace valide ajoute traceId, spanId, parentSpanId et traceFlags. Ces clés permettent de relier un message entrant, un run agent, un appel modèle et un outil sans enregistrer le prompt intégral.

Dans un incident, partez d’un identifiant stable et d’une fenêtre temporelle. Vérifiez ensuite le canal, le run, le modèle et l’outil. Une recherche par mot ERROR seule produit du bruit et perd le chemin causal. Pour les longues préparations de réponse, recherchez les jalons de timing et les avertissements de liveness ; ils séparent retard de préparation, démarrage modèle et exécution d’outil.

4. Protéger les données sensibles

La redaction des valeurs sensibles est toujours active, mais elle reste une défense best-effort. Vous pouvez remplacer l’ensemble de motifs de journaux avec logging.redactPatterns; testez-les, car une expression trop large peut rendre le diagnostic inutilisable. Les tool events du Control UI conservent en plus les protections intégrées.

N’activez pas durablement les captures de payload. OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted peut encore contenir prompts et messages malgré le masquage des secrets. Préférez summary ou tools, puis supprimez l’override après l’incident. Ne copiez pas un journal brut dans un ticket public.

5. Vérifier la disponibilité et la readiness

Le Gateway expose une liveness /healthz et une readiness /readyz sur son serveur HTTP. Ces routes sont documentées pour les sondes de l’infrastructure ; n’inventez pas /health, /api/health ou un payload de version. La CLI reste le contrôle riche :

openclaw gateway health
openclaw gateway status --deep --json
openclaw status --all --json
openclaw doctor --lint --json

/healthz indique que le serveur peut répondre. /readyz reste rouge pendant que plugins, canaux ou hooks configurés se stabilisent. Un service actif mais non ready ne doit pas être déclaré pleinement opérationnel.

6. Sonder les canaux et les files

Utilisez :

openclaw channels status --probe
openclaw status --deep

Les probes peuvent signaler transport, échec ou audit de compte. status --deep et --all remontent aussi les avertissements de files : messages en attente, réclamés ou bloqués, même lorsque le canal lui-même semble connecté. Complétez ce contrôle par un message synthétique depuis un expéditeur de test autorisé, car seule une vérification bout en bout prouve la livraison et la réponse.

7. Exporter avec OpenTelemetry

Installez puis activez le plugin officiel :

openclaw plugins install clawhub:@openclaw/diagnostics-otel
openclaw plugins enable diagnostics-otel

Configurez l’export :

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: { "diagnostics-otel": { enabled: true } }
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      protocol: "http/protobuf",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2,
      flushIntervalMs: 60000,
      captureContent: false
    }
  }
}

Adaptez l’adresse à votre réseau interne. Gardez captureContent: false sauf justification forte. Les métriques couvrent notamment tokens, coût, durée de run, failover, skills, messages, files, sessions, outils, exec, mémoire et liveness. Les traces suivent les appels modèle, tools et flux de messages. Un backend Grafana, Prometheus compatible OTEL ou autre plateforme peut ensuite recevoir ces signaux.

8. Définir des alertes actionnables

Commencez avec peu de règles : Gateway non ready, redémarrages répétés, échecs de canal, croissance d’une file bloquée, saturation disque et taux d’erreur durable. Ajoutez latence modèle, durée de run et coût seulement après avoir observé une baseline. Les seuils universels inventés sont moins utiles qu’une comparaison avec votre trafic réel.

Chaque alerte doit inclure le service, l’agent ou canal, la fenêtre, l’identifiant corrélable et le lien vers la bonne vue. Testez la chaîne de notification. Une alerte qui n’a jamais été déclenchée volontairement ne constitue pas une procédure vérifiée.

Checklist de monitoring

• Les logs sont accessibles par CLI et tournent sans saturer le disque.
• Les secrets et contenus sensibles sont absents des journaux.
• Liveness, readiness et état du service sont distingués.
• Les canaux ont une probe et un test bout en bout.
• Les alertes ont un propriétaire et une action documentée.
• L’export OTEL est lui-même visible dans status --all.

Exemple concret : diagnostiquer un Telegram lent

Un Gateway sur VPS répond tardivement sur Telegram. L’opérateur commence par borner l’incident et vérifier les couches :

openclaw gateway status --deep --json
openclaw channels status --probe
openclaw logs --follow --plain --utc

Le service est actif et le canal passe sa probe. Il cherche ensuite les jalons de timing du run concerné grâce à l’heure, au canal et à l’identifiant de session, sans activer tout le niveau trace. Il active temporairement le diagnostic de transport modèle :

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway run

Sur un service géré, il applique cet override par la méthode d’environnement prévue par son superviseur plutôt que de lancer un second Gateway sur le même port. Les événements permettent de distinguer attente avant appel, temps au premier octet et durée totale. Il désactive ensuite le flag et vérifie qu’aucun payload n’a été capturé.

Enfin, il ajoute une alerte OTEL sur la latence p95 du modèle et une autre sur session.stalled, puis simule un appel lent en staging. Le résultat attendu n’est pas une ligne précise copiée ici : c’est la réception de l’alerte, reliée à la trace et aux logs du même run. Cette procédure prouve la chaîne diagnostic-action sans exposer le contenu du message.

Bonnes pratiques

Conservez les horloges des hôtes synchronisées et choisissez UTC dans les exports centraux. Sans cohérence temporelle, la corrélation entre canal, modèle et conteneur devient fragile. Ajoutez des identifiants stables aux intégrations maison plutôt que de dépendre du texte des messages.

N’utilisez debug et trace que pendant une fenêtre annoncée, avec une date de retour à info. Protégez l’accès aux dashboards comme le Gateway lui-même : les métadonnées de sessions, noms de canaux et coûts révèlent déjà des informations opérationnelles.

Surveillez aussi l’observabilité : absence soudaine de logs, exporter OTEL en échec, volume anormalement faible ou alerte non livrée. Le guide de production OpenClaw doit contenir la procédure de reprise, tandis que le monitoring doit dire quand l’appliquer.

Questions fréquentes

Où sont stockés les logs OpenClaw ?

Par défaut sur Linux, le Gateway écrit un fichier JSONL daté sous /tmp/openclaw. Les profils nommés utilisent un nom qualifié. Windows utilise un répertoire temporaire utilisateur. Vous pouvez définir logging.file dans ~/.openclaw/openclaw.json. Utilisez openclaw logs --follow plutôt que de supposer le chemin dans vos scripts.

Comment activer OpenClaw debug ?

Utilisez temporairement OPENCLAW_LOG_LEVEL=debug ou l’option globale --log-level debug. Pour un problème fournisseur, préférez les flags ciblés de transport ou SSE. --verbose ne change que la console et les logs WebSocket. Revenez à info après diagnostic et vérifiez qu’aucun contenu sensible n’a été conservé.

Prometheus et Grafana sont-ils obligatoires ?

Non. La CLI, les logs JSONL et les probes suffisent pour une petite instance. À plus grande échelle, activez diagnostics-otel et envoyez les signaux OTLP/HTTP à un collecteur ou backend. Grafana peut visualiser ces données et Prometheus participer à la couche métriques, mais OpenClaw ne nécessite pas cette stack pour fonctionner.

Quelle différence entre healthz et readyz ?

/healthz est une sonde de liveness : le serveur répond. /readyz indique que les composants nécessaires, comme plugins, canaux ou hooks configurés, ont fini de se préparer. Pour l’exploitation, combinez readiness, gateway status, probes de canaux et test synthétique ; un seul HTTP 200 ne prouve pas un parcours complet.

Comment éviter les secrets dans les logs agents OpenClaw ?

Laissez la redaction intégrée active, utilisez des SecretRefs, évitez les captures de payload et ajoutez des motifs propres à votre organisation si nécessaire. Limitez l’accès et la rétention des journaux. Testez avec des secrets factices reconnaissables avant production, puis confirmez qu’ils sont masqués dans le fichier, l’UI et l’export OTEL.

Articles liés

Commencez par les journaux et les probes natifs, puis ajoutez OpenTelemetry lorsque les tendances et la corrélation justifient son coût. Un bon monitoring reste petit, testé et relié à une procédure d’intervention claire.

• Mettre OpenClaw en production
• Sécuriser OpenClaw
• Déployer OpenClaw avec Docker
• Héberger OpenClaw sur un VPS
• Configurer OpenClaw
• Comprendre les agents OpenClaw