Passer au contenu principal
models.providers.<id>.localService permet à OpenClaw de démarrer à la demande un serveur de modèles local détenu par le fournisseur. Il s’agit d’une configuration au niveau du fournisseur : lorsque le modèle sélectionné appartient à ce fournisseur, OpenClaw sonde le service, démarre le processus si le point de terminaison est indisponible, attend qu’il soit prêt, puis envoie la requête au modèle. Utilisez-la pour les serveurs locaux coûteux à laisser tourner toute la journée, ou pour les configurations manuelles où la sélection du modèle doit suffire à démarrer le backend.

​
Fonctionnement

  1. Une requête de modèle est résolue vers un fournisseur configuré.
  2. Si ce fournisseur a localService, OpenClaw sonde healthUrl.
  3. Si la sonde réussit, OpenClaw utilise le serveur existant.
  4. Si la sonde échoue, OpenClaw démarre command avec args.
  5. OpenClaw interroge l’état de préparation jusqu’à l’expiration de readyTimeoutMs.
  6. La requête de modèle est envoyée via le transport normal du fournisseur.
  7. Si OpenClaw a démarré le processus et que idleStopMs est positif, le processus est arrêté après que la dernière requête en cours est restée inactive pendant cette durée.
OpenClaw n’installe pas launchd, systemd, Docker ni de daemon pour cela. Le serveur est un processus enfant du processus OpenClaw qui en a eu besoin en premier.

​
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,
          },
        ],
      },
    },
  },
}

​
Champs

  • command : chemin absolu de l’exécutable. La recherche par shell n’est pas utilisée.
  • args : arguments du processus. Aucune expansion shell, aucun pipe, globbing ni règle de guillemets n’est appliqué.
  • cwd : répertoire de travail facultatif pour le processus.
  • env : variables d’environnement facultatives fusionnées avec l’environnement du processus OpenClaw.
  • healthUrl : URL de préparation. Si elle est omise, OpenClaw ajoute /models à baseUrl, donc http://127.0.0.1:8000/v1 devient http://127.0.0.1:8000/v1/models.
  • readyTimeoutMs : délai limite de préparation au démarrage. Valeur par défaut : 120000.
  • idleStopMs : délai d’arrêt après inactivité pour les processus démarrés par OpenClaw. 0 ou une valeur omise laisse le processus actif jusqu’à la sortie d’OpenClaw.

​
Exemple Inferrs

Inferrs est un backend /v1 personnalisé compatible OpenAI ; la même API de service local fonctionne donc avec l’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.

​
Exemple ds4

Pour la configuration complète, les conseils de dimensionnement du contexte et les commandes de vérification, consultez 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: [],
      },
    },
  },
}

​
Notes opérationnelles

  • Un processus OpenClaw gère l’enfant qu’il a démarré. Un autre processus OpenClaw qui voit la même URL de santé déjà active la réutilisera sans l’adopter.
  • Le démarrage est sérialisé par commande de fournisseur et ensemble d’arguments, afin que des requêtes concurrentes ne lancent pas de serveurs en double pour la même configuration.
  • Les réponses en streaming actives détiennent un bail ; l’arrêt après inactivité attend que le traitement du corps de réponse soit terminé.
  • Utilisez timeoutSeconds sur les fournisseurs locaux lents afin que les démarrages à froid et les longues générations n’atteignent pas le délai d’expiration par défaut des requêtes de modèle.
  • Utilisez une valeur explicite pour healthUrl si votre serveur expose son état de préparation ailleurs que sur /v1/models.

​
Connexe

Local models

Configuration des modèles locaux, choix de fournisseurs et conseils de sécurité.

Inferrs

Exécutez OpenClaw via le serveur local compatible OpenAI d’inferrs.