English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Providers

Infere

inferrs pode servir modelos locais por trás de uma API /v1 compatível com OpenAI. OpenClaw funciona com inferrs pelo caminho genérico openai-completions.

Propriedade Valor
ID do provedor inferrs (personalizado; configure em models.providers.inferrs)
Plugin nenhum — inferrs não é um provider plugin OpenClaw empacotado
Variável env. auth Opcional. Qualquer valor funciona se o servidor inferrs não tiver autenticação
API compatível com OpenAI (openai-completions)
URL base sugerida http://127.0.0.1:8080/v1 (ou onde quer que seu servidor inferrs esteja)

Primeiros passos

  • Inicie o inferrs com um modelo

    inferrs serve google/gemma-4-E2B-it \
  --host 127.0.0.1 \
  --port 8080 \
  --device metal

  • Verifique se o servidor está acessível

    curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/models

  • Adicione uma entrada de provedor OpenClaw

    Adicione uma entrada de provedor explícita e aponte seu modelo padrão para ela. Veja o exemplo completo de configuração abaixo.

    • Exemplo completo de configuração

    Este exemplo usa Gemma 4 em um servidor inferrs local.

    {
  agents: {
    defaults: {
      model: { primary: "inferrs/google/gemma-4-E2B-it" },
      models: {
        "inferrs/google/gemma-4-E2B-it": {
          alias: "Gemma 4 (inferrs)",
        },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      inferrs: {
        baseUrl: "http://127.0.0.1:8080/v1",
        apiKey: "inferrs-local",
        api: "openai-completions",
        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,
            },
          },
        ],
      },
    },
  },
}

    Configuração avançada

    Por que requiresStringContent é importante

    Algumas rotas de Chat Completions do inferrs aceitam apenas messages[].content em string, não arrays estruturados de partes de conteúdo.

    compat: {
  requiresStringContent: true
}

    O OpenClaw achatará partes de conteúdo de texto puro em strings simples antes de enviar a solicitação.

    Observação sobre Gemma e esquema de ferramentas

    Algumas combinações atuais de inferrs + Gemma aceitam solicitações diretas pequenas de /v1/chat/completions, mas ainda falham em turnos completos do agent-runtime do OpenClaw.

    Se isso acontecer, tente isto primeiro:

    compat: {
  requiresStringContent: true,
  supportsTools: false
}

    Isso desativa a superfície de esquema de ferramentas do OpenClaw para o modelo e pode reduzir a pressão de prompt em backends locais mais rigorosos.

    Se solicitações diretas pequenas ainda funcionarem, mas turnos normais de agente do OpenClaw continuarem travando dentro do inferrs, o problema restante geralmente é comportamento upstream do modelo/servidor, e não a camada de transporte do OpenClaw.

    Teste de fumaça manual

    Depois de configurado, teste as duas camadas:

    curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"google/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}'

    openclaw infer model run \
  --model inferrs/google/gemma-4-E2B-it \
  --prompt "What is 2 + 2? Reply with one short sentence." \
  --json

    Se o primeiro comando funcionar, mas o segundo falhar, consulte a seção de solução de problemas abaixo.

    Comportamento em estilo proxy

    inferrs é tratado como um backend /v1 compatível com OpenAI em estilo proxy, não como um endpoint OpenAI nativo.

    • A modelagem de solicitações exclusiva da OpenAI nativa não se aplica aqui
    • Sem service_tier, sem Responses store, sem dicas de cache de prompt e sem modelagem de payload de compatibilidade de raciocínio da OpenAI
    • Cabeçalhos ocultos de atribuição do OpenClaw (originator, version, User-Agent) não são injetados em URLs base personalizadas do inferrs

    Solução de problemas

    curl /v1/models falha

    inferrs não está em execução, não está acessível ou não está vinculado ao host/porta esperados. Verifique se o servidor foi iniciado e está escutando no endereço que você configurou.

    messages[].content esperava uma string

    Defina compat.requiresStringContent: true na entrada do modelo. Consulte a seção requiresStringContent acima para obter detalhes.

    Chamadas diretas de /v1/chat/completions passam, mas openclaw infer model run falha

    Tente definir compat.supportsTools: false para desativar a superfície de esquema de ferramentas. Consulte a observação sobre esquema de ferramentas do Gemma acima.

    inferrs ainda trava em turnos de agente maiores

    Se o OpenClaw não receber mais erros de esquema, mas o inferrs ainda travar em turnos maiores de agente, trate isso como uma limitação upstream do inferrs ou do modelo. Reduza a pressão do prompt ou mude para outro backend ou modelo local.

    Relacionados

    Modelos locais

    Executando o OpenClaw com servidores de modelos locais.
    Solução de problemas do Gateway

    Depurando backends locais compatíveis com OpenAI que passam em verificações, mas falham em execuções de agente.
    Seleção de modelos

    Visão geral de todos os provedores, referências de modelo e comportamento de failover.