Services de modèles locaux

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 de modèle.

Utilisez-la pour les serveurs locaux qu’il est coûteux de maintenir en cours d’exécution 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 la 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 via le shell n’est pas utilisée.
• args : arguments du processus. Aucune expansion shell, aucun tube, globbing ni règle de citation n’est appliqué.
• cwd : répertoire de travail facultatif pour le processus.
• env : variables d’environnement facultatives fusionnées par-dessus l’environnement du processus OpenClaw.
• healthUrl : URL de disponibilité. 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 disponibilité au démarrage. Valeur par défaut : 120000.
• idleStopMs : délai d’arrêt sur inactivité pour les processus démarrés par OpenClaw. 0 ou une omission maintient le processus en vie jusqu’à la fermeture 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 exécutant OpenClaw.

# Exemple ds4

{
  models: {
    providers: {
      ds4: {
        baseUrl: "http://127.0.0.1:18000/v1",
        apiKey: "ds4-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "/Users/you/Projects/oss/ds4/ds4-server",
          args: [
            "--model",
            "/Users/you/Projects/oss/ds4/ds4flash.gguf",
            "--host",
            "127.0.0.1",
            "--port",
            "18000",
            "--ctx",
            "393216",
          ],
          cwd: "/Users/you/Projects/oss/ds4",
          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, de sorte que les requêtes concurrentes ne lancent pas de serveurs en double pour la même configuration.
• Les réponses en streaming actives conservent un bail ; l’arrêt sur inactivité attend que la gestion du corps de la réponse soit terminée.
• 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 un healthUrl explicite si votre serveur expose sa disponibilité ailleurs que sur /v1/models.

# Connexe