OpenClaw · /v1/models · compatible OpenAI · monorepo · Mac distant · 2026

2026 OpenClaw front-end pratique :
Passerelle /v1/models alignée pour clients compatibles OpenAI — checklist de fumée monorepo sur Mac distant

20.04.2026 OpenClaw / passerelle API 9 min de lecture

Public : équipes OpenClaw avec clients type OpenAI. Ce guide aligne /v1/models sur un Mac distant, mappe les diffs monorepo à une fumée reproductible et aux portes PR — sans hooks d’hébergeur. Liens : index blog, résumé PR OpenClaw, release front.

01 Pourquoi /v1/models casse sans bruit

1) Cache client au démarrage : chat OK mais data vide ⇒ écran vert jusqu’au sélecteur de modèles.

2) Proxys qui mangent des préfixes : on teste /v1/chat/completions et on oublie /v1/models sur la même base.

3) Alias divergents entre paquets : identifiants exposés ≠ outils internes après refactor.

02 Attente client et comportement passerelle

Les clients « compatibles OpenAI » attendent une forme stable ; la matrice ci-dessous évite de promouvoir une build qui passe le chat mais casse les sélecteurs de modèles.

Sujet Client compatible OpenAI Responsabilité passerelle
Point de terminaison GET /v1/models sur le même baseURL que le chat. Exposer la route derrière TLS et middleware d’auth identiques pour que curl et SDK concordent.
Authentification Envoie Authorization: Bearer … sauf désactivation explicite. Répondre tôt en 401 si le secret manque ; éviter les boucles de redirection qui transforment POST en GET.
Forme Attend { "object": "list", "data": [ { "id", "object", "created", "owned_by" } ] }. Conserver les champs filtrés par les clients ; documenter toute extension optionnelle.
Alias Les utilisateurs choisissent des libellés mappés vers les identifiants fournisseur. Versionner les cartes d’alias à côté de la config passerelle pour qu’un renommage ne bifurque pas en silence.

Si la matrice échoue, corrigez d’abord le routage et les alias ; les quotas fournisseur viennent après.

03 HowTo : installation, route, alias, carte monorepo

  1. Installer. Monorepo + lockfile ; passerelle avec la même version Node/Bun que la CI.
  2. Exporter. GATEWAY_BASE, OPENAI_API_KEY, secrets PROVIDER_* OpenClaw.
  3. Route. GET /v1/models enregistré avant télémétrie optionnelle ; ordre des handlers stable derrière LB.
  4. Alias. Un module partagé CLI + service pour propagations atomiques.
  5. Carte fumée. packages/gateway, apps/proxy, middleware auth ⇒ sonde modèles complète ; docs seules ⇒ pas de fumée runtime.
  6. Artefacts. models_smoke.json : statut, durée, ids triés pour diff PR.

04 Sondes exécutables et paramètres

Exécutez ces commandes sur le Mac distant : les sorties sont attachables à la PR et comparables commit à commit.

  • ▸GET : curl -sS -H "Authorization: Bearer $OPENAI_API_KEY" "$GATEWAY_BASE/v1/models" -o models_smoke.json ; jq '.data[].id' models_smoke.json | sort.
  • ▸Sans jeton : curl -sSI "$GATEWAY_BASE/v1/models" ⇒ 401, pas redirections.
  • ▸Diff ids : git diff --no-index prior_models.txt current_models.txt (fichiers par SHA).
  • ▸Refactor : rg "v1/models" packages apps -n pour détecter des montages HTTP obsolètes.
  • ▸Optionnel : une requête chat minimale avec la même base et le même Bearer confirme que la session n’est pas « verte » uniquement sur GET.

N’appelez « flaky » le fournisseur qu’après un curl direct amont qui reproduit le même corps JSON que la passerelle.

05 Enchaînement avec le flux PR

Publiez models_smoke.json en artefact CI, rendez obligatoire la vérification gateway-models, et postez sur la PR la liste d’identifiants triés lorsque le diff est non vide. Étiquetez area:models dès qu’un fichier d’alias change.

Pour un middleware partagé, exécutez la même sonde sur un runner Mac distant dont les variables d’environnement reflètent la production. Joignez le résumé JSON ou NDJSON au ticket avec une clé d’idempotence afin que les relances n’inondent pas le fil — le tout reste orthogonal aux pipelines de build statique ou aux hooks d’hébergeur.

06 Faits opposables

Parité de base URL

Le base URL du SDK doit se terminer à la racine passerelle sans segment de chemin qui duplique /v1.

Identifiants triés

Exportez les identifiants de modèles par ordre lexicographique ; un réordonnancement inattendu signale souvent des configurations fusionnées en double.

Périmètre monorepo

Les changements passerelle ou auth exigent la fumée modèles ; la documentation pure ou les assets marketing ne l’exigent pas sauf si les exemples d’environnement changent.

07 FAQ

Pourquoi mon client voit HTTP 401 sur /v1/models ?

Même Bearer que le chat : réexport sur la session Mac distant, pas de retour ligne dans l’en-tête, secret via coffre — pas .env versionné.

Pourquoi data est vide alors que HTTP 200 revient ?

Sync amont ou filtres : logs passerelle + curl direct fournisseur avec les mêmes creds.

Comment les edits monorepo fixent-ils la portée de fumée ?

Un paquet ⇒ un jeu de sondes ; middleware partagé ⇒ modèles + chat minimal ; docs seules ⇒ pas de fumée runtime.

08 Prochaines étapes

Mac distant pour rejouer les sondes : accueil, tarifs, aide, achat ou location.

Mac distant · OpenClaw · parité API

Un Mac dédié pour la QA passerelle ?

OpenClaw sur Apple Silicon réel : accueil, aide, tarifs, achat ou location.

/v1/models Fumée monorepo Mac distant
Tarifs Aide Accueil
Mac distant — QA passerelle /v1/models