/v1/embeddings vérifiable sur Mac distant, pré-tirage RAG aligné CI, chaîne openclaw doctor → daemon → alertes à retries bornés. Doc : onboard, doctor. Contexte : durcissement passerelle, cache modèles à niveaux, matrice registre CI.
Goulots d’étranglement que ce runbook élimine
- Démarrage à froid des embeddings : la première requête télécharge des poids ou appelle une API jamais testée sous l’utilisateur du daemon — la CI reste verte pendant que la passerelle renvoie 500.
- Auth « cérébrale partagée » :
openclaw onboardécrit un jeton dans un profil shell, maislaunchdcharge un autre fichier —curlinteractif réussit et l’automation échoue. - CI silencieuse : les pipelines passent même lorsque les index vectoriels manquent, faute de POST JSON structuré vers votre file d’alertes avec backoff plafonné.
Matrice : où calculer les embeddings
| Mode | Quand le choisir | Compromis |
|---|---|---|
| API hébergée (compatible OpenAI) | Sortie stable, peu de RAM sur le Mac | Quotas, rotation de clés, liste blanche sortante |
| GGUF local via runtime intégré | Coût prévisible ou réseau restreint | Empreinte APFS ; caches à préchauffer |
| Ollama ou sidecar loopback | Itération rapide pour petites équipes | Un daemon de plus à mettre à jour et surveiller |
Installation npm globale, onboard et --install-daemon
Figez Node 22 LTS (nvm, fnm ou paquet officiel). Installez la CLI globalement avec le même utilisateur Unix qui possèdera la passerelle — pas en root :
Lancez l’onboarding en mode non interactif lorsque votre politique le permet ; incluez --install-daemon pour qu’macOS enregistre un service façon LaunchAgent qui survive aux déconnexions SSH. Exemple représentatif (adaptez les drapeaux fournisseur) :
Jeton passerelle : préférez --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN avec --install-daemon (voir doc onboard). Secrets dans ~/.openclaw/.env.gateway en 600, plist EnvironmentVariables — pas les journaux CI. Reconnectez la session daemon pour aligner PATH et npm global avec launchd.
Activer la recherche mémoire et sonder /v1/embeddings
Renseignez agents.defaults.memorySearch dans openclaw.json (fournisseur, modèle, dimensions). Utilisez une clé API moindre privilège distincte du jeton Bearer de la passerelle. Liez la passerelle en loopback (par ex. 127.0.0.1:18765) et terminez le TLS dans un proxy inverse si vous exposez l’hôte. Sonde locale :
Attendez HTTP 200 et un corps JSON avec data[0].embedding. En cas de 401, comparez le jeton shell et celui injecté dans launchd, supprimez les retours ligne parasites, rechargez le daemon, puis seulement après examinez le fournisseur.
openclaw doctor, état passerelle et journaux
Exécutez openclaw doctor après chaque mise à jour, puis openclaw gateway status --deep (ou l’équivalent de votre build). Redirigez StandardOutPath et StandardErrorPath du plist vers des fichiers datés et recherchez 401, EADDRINUSE ou erreurs fournisseur.
CI sur le même Mac distant : pré-tirer les vecteurs, puis alerter
Préflight CI sur le même pool : mêmes HF_HOME et chemins cache que le plist ; préchargez poids et index hors release.
Échec : POST JSON vers observabilité, pauses 2 s / 4 s / 8 s, max trois essais ; 401 répétés → incident, pas boucle.
Symptômes fréquents et premiers réflexes
| Symptôme | Vérifications prioritaires |
|---|---|
EADDRINUSE sur le port passerelle |
lsof -nP -iTCP:18765 -sTCP:LISTEN ; arrêtez les processus node obsolètes ; alignez openclaw.json avec l’amont du proxy. |
HTTP 401 sur /v1/embeddings |
Diff jeton shell vs launchd ; chmod 600 ; rechargement daemon ; horloge synchronisée. |
| HTTP 429 fournisseur | Réduisez le parallélisme du pré-tirage CI ; respectez Retry-After ; séparez pré-tirage et tests interactifs. |
ENOSPC pendant le tirage modèle |
df -h et df -i sur la cible du lien ; déplacez le tier chaud ou évincez les fragments temporaires. |
- Fichier Bearer en
600; rotation des jetons liée aux départs et à la rotation CI. - Échelle de retry 2 s / 4 s / 8 s pour les POST ; arrêt après trois échecs.
- Seuil disque : alerte avant 80 % d’utilisation sur le volume rapide.
FAQ
Faut-il une clé séparée pour les embeddings ?
Oui lorsque le fournisseur le permet : limitez la portée aux modèles d’embedding, stockez-la à côté du fichier d’environnement passerelle et n’exposez pas les clés console administrateur dans l’automation.
Pourquoi pré-tirer en CI si la passerelle télécharge déjà ?
La CI valide les mêmes chemins que le daemon, révèle les bugs de permissions entre utilisateurs, et déplace les gros téléchargements hors du chemin critique du build.
Synthèse, achat et centre d’aide
En résumé : des embeddings reproductibles sur passerelle Mac distant exigent npm install -g, onboard --install-daemon, une configuration memorySearch explicite, une sonde /v1/embeddings réussie, doctor plus statut passerelle approfondi, et des jobs CI qui pré-tirent dans des caches partagés avant de bloquer les releases. Les webhooks d’alerte avec retries bornés remontent les échecs là où les opérateurs regardent déjà.
Pour louer une capacité dédiée : page achat, tarifs, centre d’aide, accueil et liste du blog — consultables sans compte.
Un Apple Silicon loué en nœud dédié garde les caches d’embedding chauds sans voisins bruyants.