« Les agents Agno accélèrent dès que les outils sont à portée de main — et c’est précisément lorsqu’un Mac distant devient un risque sans frontière de confiance nette. » Ce guide HowTo place OpenClaw en avant-garde : une liste blanche d’outils au niveau passerelle, des timeouts imbriqués qui sautent avant le blocage du processus, un disjoncteur qui stoppe les rafales de retries, et un objet JSON de résumé d’échec que votre orchestration peut interpréter sans parser des journaux opaques.

Sur cette page : Frictions · Matrice des responsabilités · Inspection doctor · Fragments JSON · Étapes reproductibles · Dépannage · Jalons · FAQ

Matrice Agno vs OpenAI Agents SDK M4, Strands derrière OpenClaw, PydanticAI à la passerelle. Public : aide, tarifs, achat.

Frictions que ce runbook retire

1. Outils fantômes. Les développeurs enregistrent des helpers en local pendant que la passerelle de production reste en retard : certains appels contournent la politique que vous croyiez universelle.

2. Blocages ambigus. Un seul délai HTTP masque si le modèle, la validation de schéma ou une API amont a calé ; l’équipe redémarre à l’aveugle.

3. Amplification des retries. Sans disjoncteur, validateur instable ou erreurs amont en boucle montent la pression mémoire sur le même hôte loué que vos tests de charge.

Où vit chaque couche

Couche Côté Agno Côté passerelle OpenClaw
Surface d’outils Callables Python, docstrings, mise en forme des arguments pour le modèle. Noms de routes allowlistés, auth transport, enregistrement JSON Schema par route.
Budgets temps Deadline client HTTP quelques secondes au-dessus des fusibles passerelle. Mur de validation, plafond d’exécution, attente en file, refroidissement disjoncteur.
Expérience d’échec Branchement sur enveloppe structurée, tentatives de réparation bornées sur les champs. Émission d’identifiant de corrélation, étape, code, pointeur JSON optionnel, texte de remédiation redacté.

Inspection préalable avec openclaw doctor

Avant l’URL de base en boucle locale, openclaw doctor --json est un portail obligatoire : archivez la sortie avec la version OpenClaw épinglée, corrigez chemins, permissions jetons et dépendances optionnelles du routage. Croisez SSH et VNC avec le centre d’aide public. Après mineure macOS, Homebrew ou rebuild Python sur le Mac distant, tout écart doctor versus manifeste de routes doit faire échouer le déploiement.

Fragments JSON passerelle (sans secret en Git)

Jetons hors dépôt (chmod 600 ou secret manager), variables d’environnement sur l’hôte uniquement. Forme illustrative ci-dessous.

Outils allowlistés et références de schéma

{ "version": 1, "tools": [ { "name": "read_repo_file", "argsSchemaRef": "schemas/read_repo_file.json" }, { "name": "append_audit_log", "argsSchemaRef": "schemas/append_audit_log.json" } ], "denyUnknownToolNames": true }

Fuse timeout et politique de disjoncteur

{ "validateTimeoutMs": 8000, "executeTimeoutMs": 52000, "clientHintTimeoutMs": 60000, "breaker": { "openAfterFailures": 3, "cooldownSeconds": 30 } }

Enveloppe de résumé d’échec renvoyée à Agno

{ "ok": false, "correlationId": "req_01hzzexample", "stage": "validate", "code": "schema_timeout", "pointer": "/items/0/title", "hint": "Réduire la taille de la charge ou fractionner le lot d’outils." }

Étapes reproductibles

  1. Runtimes. Node 22 LTS OpenClaw, venv Agno, chemins dans launchd, scratch SSD.
  2. Pré-vol. Build épinglée, openclaw doctor --json, puis openclaw gateway listen sur 127.0.0.1, jeton hors dépôt.
  3. Surface réseau. SSH -R ou maillage privé, pas d’ingress public, jetons dashboard hors repo Agno.
  4. Allowlist. Même manifeste JSON des deux côtés ; nom manquant → quitter avant trafic.
  5. Client Agno. Base OpenAI-compatible vers le tunnel, timeout client > executeTimeoutMs, JSONL structuré.
  6. Enveloppes. Transport, validate, disjoncteur, amont → JSON compact pour retry ou escalade déterministe.
  7. Fumée. Happy path, violation schéma, amont lent — fusibles, compteurs disjoncteur, champs logs.

Dépannage

  • Disjoncteur ouvert pendant que le modèle stream encore. Les charges structurées invalides comptent comme échecs : élargir le schéma ou resserrer les prompts ; ne désactivez pas la validation passerelle en production.
  • Doctor passe mais les outils disparaissent après upgrade. Diff votre manifeste de routes contre les valeurs par défaut de la nouvelle OpenClaw et confirmez que les drapeaux de session ou de visibilité ne se sont pas resserrés silencieusement.
  • Tunnel qui tombe la nuit. Activer les keepalive TCP côté client et serveur SSH, désigner un responsable astreinte, alerter sur la même sonde santé que celle empruntée par Agno.

Jalons citables

  • Garder validateTimeoutMs à huit mille millisecondes ou moins lorsque les clients externes avoisinent la minute.
  • Ouvrir le disjoncteur après trois échecs consécutifs et imposer trente secondes de refroidissement avant sondes demi-ouvertes.
  • Rotation hebdomadaire des JSONL et compression des fragments au-delà de deux cents mégaoctets pour des I/O prévisibles sous rafales.

FAQ

Agno doit-il aussi valider les arguments localement ? Utile pour la vélocité en boucle interne, mais la passerelle demeure autoritaire : un seul contrat partagé par tous les appelants.

Où placer des retries bornés ? Après réouverture du disjoncteur, laisser Agno tenter au plus une ou deux réparations sur champs structurés ; laisser à OpenClaw le backoff sensible au transport.

Blog, accueil ; tarifs et achat sans compte — forfait M4, région, débit, puis bascule Agno recette → prod.

Synthèse : doctor avant bascule, manifeste JSON minimal miroité sur OpenClaw, timeouts de validation et d’exécution imbriqués sous le budget client Agno, disjoncteur sur séries de fautes, résumés d’échec redactés — les agents sur Mac distant restent auditables.