Services de modèles locaux

models.providers.<id>.localService démarre à la demande un serveur de modèles local géré par le fournisseur. Lorsqu’une requête de modèle ou d’embedding sélectionne ce fournisseur, OpenClaw sonde le point de terminaison de santé, démarre le processus s’il est arrêté, attend qu’il soit prêt, puis envoie la requête. Utilisez cette fonctionnalité pour éviter de laisser tourner toute la journée des serveurs locaux coûteux en ressources.

Fonctionnement

1. Une requête de modèle ou d’embedding est résolue vers un fournisseur configuré.
2. Si ce fournisseur possède localService, OpenClaw sonde healthUrl.
3. Si la sonde réussit, OpenClaw utilise le serveur déjà en cours d’exécution.
4. Si la sonde échoue, OpenClaw lance command avec args.
5. OpenClaw interroge le point de terminaison de santé jusqu’à l’expiration de readyTimeoutMs.
6. La requête passe par le transport habituel de modèle ou d’embedding.
7. Si OpenClaw a démarré le processus et que idleStopMs est défini, il arrête le processus une fois que la dernière requête en cours est restée inactive pendant cette durée.

OpenClaw n’installe ni launchd, ni systemd, ni Docker, ni aucun démon à cette fin. Le serveur est un simple processus enfant du processus OpenClaw qui en a eu besoin en premier.

Le démarrage est sérialisé pour chaque fournisseur configuré et chaque ensemble de commande, d’arguments et de variables d’environnement. Ainsi, des requêtes simultanées de conversation et d’embedding destinées au même service ne lancent pas de serveurs en double. Chaque requête conserve son propre bail jusqu’à la fin du traitement de la réponse ; l’arrêt pour inactivité attend donc la fin de toutes les requêtes de modèle et d’embedding en cours. Les alias de fournisseurs configurés restent distincts : deux alias peuvent désigner des hôtes GPU différents sans être fusionnés sous le même identifiant d’adaptateur Ollama, LM Studio ou compatible OpenAI.

Si un autre processus OpenClaw dispose déjà d’un serveur opérationnel à la même healthUrl, ce processus le réutilise sans en prendre la gestion (chaque processus ne gère que l’enfant qu’il a lui-même démarré). Les journaux de démarrage et d’arrêt incluent des extraits finaux limités et expurgés de la sortie du processus enfant, ainsi que les durées et les détails de sortie ; les valeurs d’environnement configurées ne sont jamais consignées.

Structure de configuration

{  models: {    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "local-model",        api: "openai-completions",        timeoutSeconds: 300,        localService: {          command: "/absolute/path/to/server",          args: ["--host", "127.0.0.1", "--port", "8000"],          cwd: "/absolute/path/to/working-dir",          env: { LOCAL_MODEL_CACHE: "/absolute/path/to/cache" },          healthUrl: "http://127.0.0.1:8000/v1/models",          readyTimeoutMs: 180000,          idleStopMs: 0,        },        models: [          {            id: "my-local-model",            name: "My Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 131072,            maxTokens: 8192,          },        ],      },    },  },}

Définissez timeoutSeconds dans l’entrée du fournisseur (et non dans localService) afin que les démarrages à froid lents et les longues générations n’atteignent pas le délai d’expiration par défaut des requêtes de modèle. Définissez explicitement healthUrl chaque fois que votre serveur expose son état de préparation ailleurs que sur /models dans l’URL de base.

Champs

Exemple avec Inferrs

Inferrs est un backend /v1 personnalisé compatible avec OpenAI ; la même API localService fonctionne donc avec une entrée de fournisseur inferrs :

{  agents: {    defaults: {      model: { primary: "inferrs/google/gemma-4-E2B-it" },    },  },  models: {    mode: "merge",    providers: {      inferrs: {        baseUrl: "http://127.0.0.1:8080/v1",        apiKey: "inferrs-local",        api: "openai-completions",        timeoutSeconds: 300,        localService: {          command: "/opt/homebrew/bin/inferrs",          args: [            "serve",            "google/gemma-4-E2B-it",            "--host",            "127.0.0.1",            "--port",            "8080",            "--device",            "metal",          ],          healthUrl: "http://127.0.0.1:8080/v1/models",          readyTimeoutMs: 180000,          idleStopMs: 0,        },        models: [          {            id: "google/gemma-4-E2B-it",            name: "Gemma 4 E2B (inferrs)",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 131072,            maxTokens: 4096,            compat: { requiresStringContent: true },          },        ],      },    },  },}

Remplacez command par le résultat de which inferrs sur la machine qui exécute OpenClaw. Configuration complète d’inferrs : Inferrs.

Exemple avec ds4

{  models: {    providers: {      ds4: {        baseUrl: "http://127.0.0.1:18000/v1",        apiKey: "ds4-local",        api: "openai-completions",        timeoutSeconds: 300,        localService: {          command: "<DS4_DIR>/ds4-server",          args: [            "--model",            "<DS4_DIR>/ds4flash.gguf",            "--host",            "127.0.0.1",            "--port",            "18000",            "--ctx",            "32768",            "--tokens",            "128",          ],          cwd: "<DS4_DIR>",          healthUrl: "http://127.0.0.1:18000/v1/models",          readyTimeoutMs: 300000,          idleStopMs: 0,        },        models: [],      },    },  },}

Configuration complète, dimensionnement du contexte et commandes de vérification : ds4.

Voir aussi