request_id), et des points d’accroche qui se marient avec les synthèses de build CI. Ce billet est un runbook compact : quoi vérifier en premier, comment enchaîner les contrôles côté passerelle, et comment renvoyer des extraits d’échec vers les pipelines sans divulguer de secrets. Pour aller plus loin sans compte : passerelle /v1/embeddings et pré-tirage RAG, routage multi-endpoints et résumés CI, durcissement passerelle.
Prérequis
Uniformisez le runtime sur Node.js 22 LTS (ou plus récent) pour les builds OpenClaw que vous figez en production, puis installez la passerelle avec openclaw onboard --install-daemon lorsque vos notes de version le recommandent. Après chaque rotation de secret, capturez la sortie de openclaw doctor et conservez les clés fournisseur hors Git avec des permissions strictes (chmod 600), comme dans le schéma décrit dans le guide sécurité & secrets.
Le TLS doit correspondre au nom d’hôte utilisé dans votre table de routage des modèles : une fracture DNS entre VPN bureau et runners datacenter explique souvent le scénario « carte verte, chat rouge ». Prévoyez de l’espace disque pour des journaux structurés (lignes JSON lorsque la build le permet) afin de conserver plusieurs jours d’historique tool_result sans surprise de rotation logrotate sur APFS.
Côté automatisation, choisissez si la CI consommera les synthèses via annotations du forge, webhooks génériques ou les deux ; listez les URL sortantes sur une liste blanche avant d’autoriser les rappels depuis le Mac distant.
Étapes de dépannage (checklist reproductible)
Parcourez la liste dans l’ordre ; chaque étape suppose que la précédente est restée propre. Mémo passerelle — trois angles à recouper sans ambiguïté :
- Journaux : même créneau horaire pour
model_auth_probe, lignestool_invocation/tool_resultet toute occurrenceinvalid_api_keyouwww-authenticate. - Sonde fusionnée : une seule sortie booléenne = « HTTP
/health(ougateway status) OK » et « appel modèle minimal authentifié OK ». - Webhook CI : JSON avec placeholders
<CI_PIPELINE_ID>,<GIT_SHA_SHORT>,<model_auth_snapshot>,<LAST_20_LOG_LINES_REDACTED>(voir ci-dessous).
Ouvrez le tableau de bord et vérifiez que chaque amont affiche l’état attendu : portées valides, pas seulement « joignable ». Faites correspondre les étiquettes fournisseur aux mêmes entrées que votre table de routage utilise pour /v1/chat/completions et les embeddings. Si un alias a été renommé dans Git mais pas dans la configuration live, la carte peut rester verte alors que les requêtes se heurtent à une 404 silencieuse.
Exécutez des grep bornés (redactez avant partage) pour isoler les familles d’erreurs que les builds OpenClaw récentes rendent plus explicites :
model_auth_probe,invalid_api_key,insufficient_quota— incohérences d’identifiants ou de plan.tool_invocation,tool_result,permission_denied— politiques d’outil et capacités.rate_limit,retry_after,upstream_timeout— saturation réseau ou fournisseur.
Associez chaque ligne au request_id émis à côté des segments chat et outil pour aligner la frise du tableau avec les horodatages CI.
Plutôt que trois tâches launchd disjointes, regroupez : HTTP 200 sur /health ou openclaw gateway status --json, plus un appel authentifié minimal vers un modèle léger fixe. Faites échouer le script si une des deux branches tombe, pour que l’agent reflète ce que vivent les utilisateurs interactifs — en cohérence avec le guide LaunchAgent et healthcheck passerelle.
Activez des synthèses structurées pour arguments et résultats sans dump de secrets : redaction des jetons, aperçu court des corps, conservation de la latence par outil. Si l’automatisation flake, vérifiez qu’une ligne unique relie tool_name, durée et classe de sortie — sinon vous noyez l’équipe sous des transcriptions brutes difficiles à corréler.
Rejouez la commande d’outil en échec dans une session SSH avec le même utilisateur et le même fichier d’environnement que le daemon. Les écarts sur HOME, trousseau ou profils de bac à sable produisent des refus d’outils intermittents qu’on confond parfois avec des pannes « modèle ».
Exemple d’intégration avec la CI Mac distant
Chaînage build → synthèse : la passerelle ne remplace pas le forge, elle fournit des extraits corrélés (statut d’auth, erreur d’outil, request_id) pour annoter la PR ou le flux de notification.
Une fois la régression isolée sur la passerelle, reflétez un extrait compact dans la CI pour que les demandes de fusion transportent la preuve. Schéma courant : enveloppe shell qui échoue si la sonde fusionnée casse ou si la dernière erreur d’outil dépasse un seuil, puis émission JSON vers une cible webhook autorisée avec 2 s / 4 s / 8 s de backoff — comme dans les playbooks Harbor et Jenkins déjà publiés sur ce blog.
Placeholders du modèle JSON (remplacez les jetons entre chevrons dans votre YAML ou script) :
{
"source": "openclaw-gateway",
"pipeline_id": "<CI_PIPELINE_ID>",
"commit": "<GIT_SHA_SHORT>",
"gateway_host": "<GATEWAY_PUBLIC_HOSTNAME>",
"model_auth_snapshot": "<OK|DEGRADED|FAIL>",
"last_tool_error_excerpt": "<LAST_20_LOG_LINES_REDACTED>",
"request_id": "<CORRELATION_REQUEST_ID>",
"ts_unix": "<UNIX_TIMESTAMP>"
}
Sous GitHub Actions vous pouvez encore ajouter du texte lisible à $GITHUB_STEP_SUMMARY ; ailleurs, POSTez le JSON vers votre routeur interne qui redistribue vers chat ou ticketing. Gardez des budgets curl --max-time serrés pour que les retries de webhook ne bloquent pas le runner. Lorsque l’échec est environnemental plutôt que logique, reliez les étapes de récupération depuis reprise après échec et retry afin d’éviter de redécouvrir les contrôles disque ou sortie réseau.
FAQ — erreurs fréquentes
Décalage d’horloge, rechargement partiel de config, ou jeton canary qu’un seul processus a ingéré. Redémarrez le daemon passerelle comme unité, vérifiez NTP, et assurez-vous que le tableau de bord lit le même chemin de fichier que le worker.
Comparez les fichiers d’environnement : l’automatisation n’a souvent ni agent SSH, ni déverrouillage trousseau, ni accès disque complet. Déplacez les secrets longs dans des fichiers lisibles uniquement par l’utilisateur dédié de la passerelle, pas dans des exports inline de CI.
Oui, volontairement. Montez la verbosité d’abord sur une passerelle de préproduction ; en production, restez court pour protéger les jetons. Joignez systématiquement request_id pour que l’équipe récupère l’entrée structurée complète dans le stockage de logs.
Le tableau peut refléter une dernière sonde réussie sur un hôte tandis que le trafic interactif cible un autre endpoint ou une autre version d’API. Alignez les URL de base entre la carte, le routage des modèles et openclaw doctor ; recherchez dans les journaux, sur le même intervalle, les couples www-authenticate et invalid_api_key.
La règle de redaction peut classer les arguments d’outil comme sensibles. Sur préproduction uniquement, assouplissez le filtre, gardez des flux request_id séparés et vérifiez que tool_result émet encore une synthèse de traçage sans exposer les secrets.
Écart classique entre IPv4/IPv6, chemins TLS/QUIC, ou exécution sous un autre utilisateur que le daemon launchd. Lancez la même sonde fusionnée avec le même UID, le même HOME et le même fichier d’environnement que le service passerelle.
En synthèse
Traitez la carte Model Auth, la télémétrie des appels d’outils et le relais de synthèse CI comme une boucle d’observabilité unique sur votre passerelle Mac distant : prouvez la santé des identifiants, filtrez avec intention, fusionnez les sondes, puis ne poussez vers l’amont que des extraits redactés.
Explorez l’accueil MacPull, comparez les tarifs, ouvrez la page achat pour une capacité Apple Silicon dédiée, parcourez le centre d’aide et revenez au blog technique pour d’autres guides OpenClaw — sans connexion.
Poursuivre sur MacPull (sans compte)
Accueil, tarifs, achat et aide restent publics — pratique pour calibrer un runner macOS avant de durcir la passerelle OpenClaw.
Articles liés : embeddings & RAG · CI Conan 2