Les équipes qui font tourner OpenClaw comme passerelle 24/7 sur un Mac distant loué ont besoin d’une observabilité actionnable sans alourdir la machine partagée : sondes HTTP documentées, séries temporelles compatibles Prometheus, pont possible vers OpenTelemetry, puis alertes à seuils reliées aux journaux. Ce HowTo condense un chemin minimal reproductible. Pour le socle conteneurisé et le dépannage, enchaînez avec notre guide Docker : durcissement et dépannage sur Mac loué ; pour l’exposition réseau et la rotation des secrets, croisez Tailscale, Funnel/ACL et rotation des jetons ; pour les politiques de sortie des compétences, voyez le runbook sandbox et allowlist sortante.
Frictions typiques sur capacité louée
Trois écueils reviennent lorsque la passerelle « semble » répondre alors que le service est dégradé :
- Absence de frontière liveness / readiness — un processus vivant peut refuser du travail utile ; sans
/readyzvous découvrez la défaillance via les utilisateurs. - Bruit métrologique — scrapes trop fréquents ou labels trop riches sur un hôte multi-locataire consomment du CPU et gonflent la cardinalité des séries.
- Conflit sécurité / observabilité — coller un jeton dans une URL de scrape ou oublier d’autoriser l’export OTLP vers votre SaaS crée soit une fuite, soit une panne apparente de « métriques à zéro » alors que le pare-feu fait son travail.
Matrice : signal, outil, usage
Le modèle tiré par Prometheus interroge HTTP à intervalle fixe ; OpenTelemetry pousse souvent vers OTLP, mais un collector peut scraper les mêmes URL et ré-exposer ou forwarder. Le tableau suivant fixe le vocabulaire commun des runbooks.
| Signal | Chemin Prometheus | Esprit OpenTelemetry |
|---|---|---|
| Disponibilité HTTP minimale | Scrape direct ou blackbox_exporter sur /healthz et /readyz |
Récepteur prometheus dans le collector, puis export OTLP vers le backend |
| Compteurs / histogrammes RED | Page /metrics texte si exposée, ou sidecar proxy |
Instrumentation native + pipelines processors |
| Causalité incident | Métriques dérivées depuis journaux (Loki/Elastic) | Traces corrélées via trace_id partagé |
Étapes reproductibles (cinq blocs)
1. Endpoints de santé de la passerelle
Sur l’hôte loué, vérifiez d’abord en local le port usuel 18789 :
curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyzDepuis votre poste, reproduisez via ssh -L 18789:127.0.0.1:18789 lorsque la liaison reste en loopback. Documentez le code HTTP attendu et le corps stable : si healthz passe mais pas readyz, traitez l’incident comme dégradation (disque plein, sous-processus bloqué, amont API).
2. Intervalle de scrape et job Prometheus
Choisissez 15 s pour un plan de contrôle impatient, 30 s comme défaut équilibré, 60 s si le Mac est saturé ou si le scrape traverse un tailnet lent. Alignez evaluation_interval avec la fenêtre des règles. Exemple esquisse blackbox (adaptez l’adresse du module) :
scrape_configs:
- job_name: openclaw_gateway_health
scrape_interval: 30s
metrics_path: /probe
params:
module: [http_2xx]
static_configs:
- targets:
- http://127.0.0.1:18789/healthz
- http://127.0.0.1:18789/readyz3. Exemples de règles d’alerte (style PromQL)
En supposant des séries probe_success et probe_duration_seconds issues du blackbox :
groups:
- name: openclaw_gateway
interval: 30s
rules:
- alert: OpenClawHealthzDown
expr: probe_success{job="openclaw_gateway_health"} == 0
for: 2m
labels:
severity: page
- alert: OpenClawProbeSlow
expr: probe_duration_seconds > 2
for: 5m
labels:
severity: warningAjoutez une règle ciblant explicitement readyz avec une fenêtre plus longue si les dépendances amont sont volatiles.
4. Champs de journaux OpenClaw à stabiliser
Les métriques indiquent quand ; les journaux structurent pourquoi. Exigez au minimum : timestamp RFC3339, level (info/warn/error), request_id ou trace_id, channel ou session, tool ou paquet de compétences, upstream (fournisseur modèle ou hôte HTTP), duration_ms, et error_class (timeout, 429, auth, refus sandbox). Les mêmes étiquettes env et instance que dans Prometheus accélèrent le pivot Grafana ou Loki.
5. Production : jetons et restrictions de sortie
Stockez OPENCLAW_GATEWAY_TOKEN (ou équivalent) dans un fichier launchd sécurisé, un secret Docker ou un coffre ; faites-le tourner comme vos clés Tailscale. N’accrochez jamais ces secrets aux URL de scrape. Pour la sortie, les Mac d’agents appliquent souvent une allowlist de domaines : ajoutez explicitement vos endpoints OTLP, remote_write ou SaaS d’observabilité, sinon une coupure réseau ressemblera à une panne passerelle. Limitez la cardinalité des labels et le niveau debug en production pour préserver le budget CPU des locataires.
Repères opérateur (à copier dans le runbook)
- Port d’écoute documenté le plus souvent : 18789 (validez sur votre build).
- Granularité de scrape usuelle : 15–60 s selon SLO et charge hôte.
- Gardez
evaluation_interval≤ fenêtre d’alerte la plus fine que vous promettez en astreinte.
FAQ
Faut-il évaluer les alertes sur le Mac loué lui-même ? Préférez un Prometheus managé ou un service cloud : si l’hôte meurt, une sonde locale ne peut pas vous réveiller. Un script watchdog reste un filet de dernier recours.
Je n’ai que des journaux aujourd’hui ? Dérivez des compteurs d’erreurs côté stack logs, puis ajoutez les sondes HTTP lorsque le chemin réseau est stable — le workflow d’incident reste le même.
Synthèse
Un Mac loué porteur d’OpenClaw devient opérable lorsque /healthz et /readyz sont intégrés à un job de scrape documenté, que les intervalles reflètent votre tolérance au risque, que des règles type PromQL encodent l’indisponibilité et la lenteur, et que les journaux structurés ferment la boucle. Les jetons et l’allowlist de sortie doivent rester alignés pour que l’observabilité ne devienne ni une fuite ni un tunnel de contournement.