La surface HTTP compatible OpenAI ajoute une porte d'entrée familière pour les outils qui parlent déjà /v1/chat/completions et /v1/models, mais elle ne remplace pas le canal CLI ni les RPC internes : ce sont trois chemins qui partagent souvent les mêmes secrets tout en empruntant des middlewares différents. Ce runbook impose une validation croisée : requêtes HTTP minimales, sortie openclaw gateway status --require-rpc et comparaison ligne à ligne avec ce que la CLI injecte dans les en-têtes. Pour un socle réseau sans exposition publique directe (tailnet, jetons, Compose), reportez-vous à
OpenClaw dans le cloud avec Docker et Tailscale, sans exposition publique
; pour l'alignement SecretRef, coffres et doctor quand Homebrew, npm et Docker coexistent, voyez
OpenClaw SecretRef, backup et doctor : installations mixtes brew/npm/Docker.
GET /v1/models (pas de streaming), puis seulement POST /v1/chat/completions ; tenez status --require-rpc comme preuve que le plan de contrôle RPC voit la même identité que vos en-têtes HTTP. Toute divergence doit être capturée dans un ticket avec les trois sorties collées.1. Trois plans : HTTP « OpenAI-like », RPC et CLI
Le client HTTP croit parler à un serveur OpenAI ; la passerelle traduit vers ses propres modèles et politiques. Le canal CLI ajoute des métadonnées (contexte workspace, version d'outil) que le chemin HTTP n'emporte pas toujours. Les RPC exposent l'état interne (pairing, plugins, file d'attente). Quand vous débugguez un 401, demandez-vous quel plan a réellement refusé : middleware HTTP, garde RPC ou divergence de jeton côté plugin.
2. /v1/models comme sonde sans streaming
Appelez /v1/models avec les mêmes en-têtes que vos jobs de production : Authorization (préfixe exact attendu), éventuels en-têtes spécifiques OpenClaw, et schéma https cohérent avec le reverse proxy. Une liste vide ou un modèle manquant indique souvent un décalage de configuration plutôt qu'un secret faux — corrigez d'abord l'URL de base et le préfixe de chemin avant de regénérer des jetons.
3. /v1/chat/completions : aligner corps JSON, température et drapeau stream
Rejouez une charge minimale non streamée, puis activez stream: true et observez la tenue de la connexion. Les timeouts côté client (read idle sur SSE) et côté passerelle (temps alloué au producteur) se cumulent : un proxy intermédiaire peut tronquer silencieusement le flux alors que le modèle continue. Fixez des timeouts explicites dans votre client et comparez à une requête directe loopback pour isoler la couche réseau.
4. En-têtes d'authentification et gateway.auth
Listez les en-têtes réellement envoyés par votre outil (SDK, curl, gateway intermédiaire). Vérifiez qu'il n'y a ni espace parasite, ni caractère BOM dans les fichiers d'environnement, ni double préfixe Bearer. Si gateway.auth impose un mode, toute exception pour les sondes doit être nommée ; sinon vous obtiendrez des 401 « aléatoires » selon l'ordre d'évaluation des middlewares.
5. Recoupement obligatoire : openclaw gateway status --require-rpc
Cette commande force une preuve RPC : si elle échoue alors que curl HTTP réussit, vous avez un décalage de jeton ou de binding entre plans. Capturez la sortie complète, l'URL d'écoute réelle et la révision du binaire. Ne mettez pas en production un nouvel outil HTTP tant que --require-rpc n'est pas vert sur le même hôte et le même utilisateur que le démon.
6. 401 reproductibles : grille de causes
Construisez une table à trois colonnes : HTTP seul, HTTP + proxy, CLI avec RPC. Variez une seule chose entre chaque ligne (secret, base URL, en-tête). Les causes fréquentes : secret lu depuis le mauvais trousseau, rotation partielle, proxy qui retire un en-tête personnalisé, ou client qui mélange environnements dev/prod. Archivez les captures curl -v sans coller de secret en clair.
/v1/modelsOK en loopback mais401derrière TLS : inspectez SNI, certificat intermédiaire et en-têtes ajoutés par le terminateur.- HTTP OK, RPC rouge : jeton service manquant ou URL publique utilisée là où le loopback est requis.
- CLI OK, HTTP rouge : schéma d'authentification différent (clé API vs jeton bearer) ou préfixe de chemin absent.
7. Timeouts de streaming : scénario reproductible
Baseline : réponse non streamée stable. Puis augmentez progressivement la fenêtre de tokens et la durée de génération. Mesurez où la connexion se ferme : client, proxy ou passerelle. Sur un Mac distant haute mémoire, une charge agent lourde peut retarder le producteur SSE sans pour autant invalider l'auth — évitez d'attribuer à tort un 401 réseau à un simple dépassement de délai mémoire.
8. Points d'exploitation 2026.5.x après upgrade npm ou plugins
Les versions 2026.5.x resserrent souvent la surface des plugins et des binaires npm : refaites la séquence doctor, status --require-rpc, puis /v1/models après chaque upgrade. Si un plugin réinjecte une ancienne valeur d'URL ou d'en-tête, vous verrez un HTTP vert immédiatement après boot puis des 401 dès que le plugin se réactive — corrélez avec les journaux d'amorçage.
Pourquoi un Mac mini haute mémoire stabilise cette pile HTTP + RPC
La passerelle et les clients « OpenAI-like » profitent d'une mémoire unifiée large, d'un NVMe rapide pour les journaux et d'une pile réseau macOS prévisible. Le Mac mini combine faible consommation au repos, silence, launchd pour la résilience, Gatekeeper, SIP et FileVault — moins de surprises qu'un PC générique derrière la même URL. Pour des charges agent + passerelle résidente, la bande passante RAM compte autant que le CPU ; le Mac mini M4 avec mémoire étendue reste un socle rentable pour isoler les timeouts de flux des problèmes d'authentification.
Si vous voulez héberger ce runbook sur un nœud distant aligné Macstripe, ouvrez la page d'accueil Macstripe pour choisir région et profil RAM ; le Mac mini M4 reste le point d'entrée le plus simple avant d'industrialiser vos sondes /v1/models et --require-rpc.
