Serviços de modelos locais

models.providers.<id>.localService permite que o OpenClaw inicie sob demanda um servidor local de modelo pertencente ao provedor. É uma configuração no nível do provedor: quando o modelo selecionado pertence a esse provedor, o OpenClaw verifica o serviço, inicia o processo se o endpoint estiver indisponível, aguarda a prontidão e então envia a solicitação do modelo.

Use isso para servidores locais que são caros de manter em execução o dia todo, ou para configurações manuais em que a seleção do modelo deve bastar para colocar o backend no ar.

# Como funciona

1. Uma solicitação de modelo é resolvida para um provedor configurado.
2. Se esse provedor tiver localService, o OpenClaw verifica healthUrl.
3. Se a verificação for bem-sucedida, o OpenClaw usa o servidor existente.
4. Se a verificação falhar, o OpenClaw inicia command com args.
5. O OpenClaw consulta a prontidão até readyTimeoutMs expirar.
6. A solicitação do modelo é enviada pelo transporte normal do provedor.
7. Se o OpenClaw iniciou o processo e idleStopMs for positivo, o processo é interrompido depois que a última solicitação em andamento ficar ociosa por esse tempo.

O OpenClaw não instala launchd, systemd, Docker nem um daemon para isso. O servidor é um processo filho do processo do OpenClaw que precisou dele primeiro.

# Formato da configuração

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

# Campos

• command: caminho absoluto do executável. A busca pelo shell não é usada.
• args: argumentos do processo. Nenhuma expansão de shell, pipes, globbing ou regras de aspas são aplicadas.
• cwd: diretório de trabalho opcional para o processo.
• env: variáveis de ambiente opcionais mescladas sobre o ambiente do processo do OpenClaw.
• healthUrl: URL de prontidão. Se omitida, o OpenClaw acrescenta /models a baseUrl, então http://127.0.0.1:8000/v1 se torna http://127.0.0.1:8000/v1/models.
• readyTimeoutMs: prazo de prontidão da inicialização. Padrão: 120000.
• idleStopMs: atraso de desligamento por ociosidade para processos iniciados pelo OpenClaw. 0 ou omitido mantém o processo ativo até o OpenClaw sair.

# Exemplo do Inferrs

Inferrs é um backend /v1 personalizado compatível com OpenAI, então a mesma API de serviço local funciona com a entrada do provedor 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,
            },
          },
        ],
      },
    },
  },
}

Substitua command pelo resultado de which inferrs na máquina que executa o OpenClaw.

# Exemplo do 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: [],
      },
    },
  },
}

# Observações operacionais

• Um processo do OpenClaw gerencia o filho que ele iniciou. Outro processo do OpenClaw que vê a mesma URL de integridade já ativa a reutilizará sem adotá-la.
• A inicialização é serializada por comando e conjunto de argumentos do provedor, então solicitações concorrentes não geram servidores duplicados para a mesma configuração.
• Respostas de streaming ativas mantêm uma concessão; o desligamento por ociosidade aguarda até que o tratamento do corpo da resposta seja concluído.
• Use timeoutSeconds em provedores locais lentos para que inicializações a frio e gerações longas não atinjam o tempo limite padrão de solicitação de modelo.
• Use um healthUrl explícito se o seu servidor expõe prontidão em algum lugar diferente de /v1/models.

# Relacionados