openclaw infer é a superfície headless canônica para workflows de inferência com suporte de provedores.
Ele expõe intencionalmente famílias de capacidades, não nomes brutos de RPC do Gateway nem ids brutos de ferramentas de agente.
Transforme infer em uma skill
Copie e cole isto em um agente:- mapear intenções comuns do usuário para o subcomando infer correto
- incluir alguns exemplos canônicos de infer para os workflows que ela cobre
- preferir
openclaw infer ...em exemplos e sugestões - evitar documentar novamente toda a superfície do infer dentro do corpo da skill
openclaw infer model runopenclaw infer image generateopenclaw infer audio transcribeopenclaw infer tts convertopenclaw infer web searchopenclaw infer embedding create
Por que usar infer
openclaw infer fornece uma CLI consistente para tarefas de inferência com suporte de provedores dentro do OpenClaw.
Benefícios:
- Use os provedores e modelos já configurados no OpenClaw em vez de conectar wrappers pontuais para cada backend.
- Mantenha workflows de modelo, imagem, transcrição de áudio, TTS, vídeo, web e embeddings em uma única árvore de comandos.
- Use um formato de saída estável com
--jsonpara scripts, automação e workflows orientados por agentes. - Prefira uma superfície primária do OpenClaw quando a tarefa for fundamentalmente “executar inferência”.
- Use o caminho local normal sem exigir o Gateway para a maioria dos comandos infer.
openclaw infer ... depois que testes de provedor de nível mais baixo estiverem verdes. Ele exercita a CLI entregue, o carregamento de configuração, a resolução de agente padrão, a ativação de Plugin empacotado e o runtime de capacidades compartilhado antes de a solicitação ao provedor ser feita.
Árvore de comandos
Tarefas comuns
Esta tabela mapeia tarefas comuns de inferência para o comando infer correspondente.| Tarefa | Comando | Observações |
|---|---|---|
| Executar um prompt de texto/modelo | openclaw infer model run --prompt "..." --json | Usa o caminho local normal por padrão |
| Executar um prompt de modelo em imagens | openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model | Repita --file para várias entradas de imagem |
| Gerar uma imagem | openclaw infer image generate --prompt "..." --json | Use image edit ao começar de um arquivo existente |
| Descrever um arquivo de imagem ou URL | openclaw infer image describe --file ./image.png --prompt "..." --json | --model deve ser um <provider/model> com suporte a imagem |
| Transcrever áudio | openclaw infer audio transcribe --file ./memo.m4a --json | --model deve ser <provider/model> |
| Sintetizar fala | openclaw infer tts convert --text "..." --output ./speech.mp3 --json | tts status é orientado ao Gateway |
| Gerar um vídeo | openclaw infer video generate --prompt "..." --json | Oferece suporte a dicas de provedor, como --resolution |
| Descrever um arquivo de vídeo | openclaw infer video describe --file ./clip.mp4 --json | --model deve ser <provider/model> |
| Pesquisar na web | openclaw infer web search --query "..." --json | |
| Buscar uma página da web | openclaw infer web fetch --url https://example.com --json | |
| Criar embeddings | openclaw infer embedding create --text "..." --json |
Comportamento
openclaw infer ...é a superfície principal da CLI para estes workflows.- Use
--jsonquando a saída for consumida por outro comando ou script. - Use
--providerou--model provider/modelquando um backend específico for necessário. - Use
model run --thinking <level>para passar um nível pontual de thinking/raciocínio (off,minimal,low,medium,high,adaptive,xhighoumax) mantendo a execução bruta. - Para
image describe,audio transcribeevideo describe,--modeldeve usar o formato<provider/model>. - Para
image describe,--fileaceita caminhos locais e URLs de imagem HTTP(S). URLs remotas usam a política normal de SSRF para busca de mídia. - Para
image describe, um--modelexplícito executa primeiro esse provedor/modelo e, em seguida, tenta osagents.defaults.imageModel.fallbacksconfigurados quando a chamada de modelo falha. Erros de preparação da entrada, como arquivos ausentes ou URLs sem suporte, falham antes das tentativas de fallback. O modelo deve ter suporte a imagem no catálogo de modelos ou na configuração do provedor.codex/<model>executa um turno limitado de entendimento de imagem do servidor de app do Codex;openai/<model>usa o caminho do provedor OpenAI com autenticação por chave de API ou OAuth do ChatGPT/Codex. - Comandos de execução sem estado usam local por padrão.
- Comandos de estado gerenciado pelo Gateway usam Gateway por padrão.
- O caminho local normal não exige que o Gateway esteja em execução.
model runlocal é uma conclusão de provedor pontual e enxuta. Ele resolve o modelo e a autenticação do agente configurado, mas não inicia um turno de agente de chat, carrega ferramentas nem abre servidores MCP empacotados.model run --fileaceita arquivos de imagem, detecta o tipo MIME deles e os envia com o prompt fornecido para o modelo selecionado. Repita--filepara várias imagens.model run --filerejeita entradas que não sejam imagens. Useinfer audio transcribepara arquivos de áudio einfer video describepara arquivos de vídeo.model run --gatewayexercita o roteamento do Gateway, a autenticação salva, a seleção de provedor e o runtime incorporado, mas ainda executa como uma sondagem bruta de modelo: ele envia o prompt fornecido e quaisquer anexos de imagem sem transcrição de sessão anterior, contexto bootstrap/AGENTS, montagem do mecanismo de contexto, ferramentas ou servidores MCP empacotados.model run --gateway --model <provider/model>exige uma credencial confiável de Gateway de operador porque a solicitação pede ao Gateway para executar uma substituição pontual de provedor/modelo.model run --thinkinglocal usa o caminho enxuto de conclusão de provedor; níveis específicos de provedor, comoadaptiveemax, são mapeados para o nível portátil mais próximo de conclusão simples.
Modelo
Usemodel para inferência de texto com suporte de provedores e inspeção de modelo/provedor.
<provider/model> para testar rapidamente um provedor específico sem iniciar o Gateway nem carregar toda a superfície de ferramentas do agente:
model runlocal é o smoke test de CLI mais restrito para saúde de provedor/modelo/autenticação porque, para provedores que não sejam Codex, ele envia apenas o prompt fornecido ao modelo selecionado.model run --model <provider/model>local pode usar linhas exatas do catálogo estático empacotado demodels list --allantes que esse provedor seja gravado na configuração. A autenticação do provedor ainda é necessária; credenciais ausentes falham como erros de autenticação, não comoUnknown model.- Para sondagens de raciocínio do Mistral Medium 3.5, deixe a temperatura não definida/padrão. O Mistral rejeita
reasoning_effort="high"maistemperature: 0; usemistral/mistral-medium-3-5com a temperatura padrão ou um valor de modo de raciocínio diferente de zero, como0.7. - Sondagens locais do Codex Responses são a exceção restrita: o OpenClaw adiciona uma instrução mínima de sistema para que o transporte possa preencher seu campo
instructionsobrigatório, sem adicionar contexto completo de agente, ferramentas, memória ou transcrição de sessão. model run --filelocal mantém esse caminho enxuto e anexa conteúdo de imagem diretamente à única mensagem do usuário. Arquivos de imagem comuns, como PNG, JPEG e WebP, funcionam quando o tipo MIME é detectado comoimage/*; arquivos sem suporte ou não reconhecidos falham antes que o provedor seja chamado.model run --fileé melhor quando você quer testar diretamente o modelo de texto multimodal selecionado. Useinfer image describequando quiser a seleção de provedor de entendimento de imagem do OpenClaw e o roteamento padrão de modelo de imagem.- O modelo selecionado deve oferecer suporte a entrada de imagem; modelos somente texto podem rejeitar a solicitação na camada do provedor.
model run --promptdeve conter texto que não seja apenas espaço em branco; prompts vazios são rejeitados antes que provedores locais ou o Gateway sejam chamados.model runlocal sai com código diferente de zero quando o provedor não retorna saída de texto, portanto provedores locais inacessíveis e conclusões vazias não parecem sondagens bem-sucedidas.- Use
model run --gatewayquando precisar testar roteamento do Gateway, configuração do runtime de agente ou estado de provedor gerenciado pelo Gateway mantendo a entrada do modelo bruta. Useopenclaw agentou superfícies de chat quando quiser o contexto completo do agente, ferramentas, memória e transcrição de sessão. model auth login,model auth logoutemodel auth statusgerenciam o estado salvo de autenticação do provedor.
Imagem
Useimage para geração, edição e descrição.
-
Use
image editao começar a partir de arquivos de entrada existentes. -
Use
--size,--aspect-ratioou--resolutioncomimage editpara provedores/modelos que aceitam dicas de geometria em edições de imagem de referência. -
Use
--output-format png --background transparentcom--model openai/gpt-image-1.5para saída PNG da OpenAI com fundo transparente;--openai-backgroundcontinua disponível como um alias específico da OpenAI. Provedores que não declaram suporte a fundo relatam a dica como uma substituição ignorada. -
Use
--quality low|medium|high|autopara provedores que aceitam dicas de qualidade de imagem, incluindo a OpenAI. A OpenAI também aceita--openai-moderation low|autopara a dica de moderação específica do provedor. -
Use
image providers --jsonpara verificar quais provedores de imagem incluídos são detectáveis, configurados, selecionados, e quais capacidades de geração/edição cada provedor expõe. -
Use
image generate --model <provider/model> --jsoncomo o smoke test de CLI ao vivo mais restrito para alterações de geração de imagem. Exemplo:A resposta JSON relataok,provider,model,attemptse caminhos de saída gravados. Quando--outputé definido, a extensão final pode seguir o tipo MIME retornado pelo provedor. -
Para
image describeeimage describe-many, use--promptpara dar ao modelo de visão uma instrução específica da tarefa, como OCR, comparação, inspeção de UI ou legendagem concisa. -
Use
--timeout-mscom modelos de visão locais lentos ou inicializações frias do Ollama. -
Para
image describe,--modeldeve ser um<provider/model>compatível com imagem. Quando definido, o OpenClaw tenta esse modelo explícito primeiro e depois fallbacks de modelo de imagem configurados se a chamada ao modelo falhar. -
Para modelos de visão locais do Ollama, baixe o modelo primeiro e defina
OLLAMA_API_KEYcomo qualquer valor de placeholder, por exemploollama-local. Consulte Ollama.
Áudio
Useaudio para transcrição de arquivo.
audio transcribeé para transcrição de arquivo, não gerenciamento de sessão em tempo real.--modeldeve ser<provider/model>.
TTS
Usetts para síntese de fala e estado do provedor de TTS.
tts statususa Gateway por padrão porque reflete o estado de TTS gerenciado pelo Gateway.- Use
tts providers,tts voicesetts set-providerpara inspecionar e configurar o comportamento de TTS.
Vídeo
Usevideo para geração e descrição.
video generateaceita--size,--aspect-ratio,--resolution,--duration,--audio,--watermarke--timeout-ms, e os encaminha ao runtime de geração de vídeo.--modeldeve ser<provider/model>paravideo describe.
Web
Useweb para fluxos de trabalho de busca e obtenção.
- Use
web providerspara inspecionar provedores disponíveis, configurados e selecionados.
Incorporação
Useembedding para criação de vetores e inspeção de provedores de embedding.
Saída JSON
Comandos Infer normalizam a saída JSON sob um envelope compartilhado:okcapabilitytransportprovidermodelattemptsoutputserror
outputs contém arquivos gravados pelo OpenClaw. Use
path, mimeType, size e quaisquer dimensões específicas da mídia nesse array
para automação em vez de analisar stdout legível por humanos.
Armadilhas comuns
Observações
openclaw capability ...é um alias paraopenclaw infer ....