Skip to main content
openclaw infer è l’interfaccia headless canonica per l’inferenza supportata dai provider. Espone famiglie di funzionalità (model, image, audio, tts, video, web, embedding), non nomi RPC grezzi del Gateway o ID degli strumenti dell’agente. openclaw capability ... è un alias per la stessa struttura di comandi. Motivi per preferirlo a un wrapper specifico per un singolo provider:
  • Riutilizza provider e modelli già configurati in OpenClaw.
  • Fornisce un formato stabile --json per script e automazioni gestite da agenti (vedi Output JSON).
  • Per la maggior parte dei sottocomandi, esegue il normale percorso locale senza il Gateway.
  • Per le verifiche end-to-end dei provider, utilizza la CLI distribuita, il caricamento della configurazione, la risoluzione dell’agente predefinito, l’attivazione dei plugin inclusi e il runtime condiviso delle funzionalità prima di inviare la richiesta al provider.

​
Trasformare infer in una skill

Copia e incolla questo testo in un agente:
Una buona skill basata su infer associa le intenzioni comuni degli utenti al sottocomando corretto, include alcuni esempi canonici per ogni flusso di lavoro, preferisce openclaw infer ... alle alternative di livello inferiore e non documenta nuovamente l’intera interfaccia di infer nel corpo della skill.

​
Struttura dei comandi

infer list / infer inspect --name <capability> mostrano questa struttura sotto forma di dati (ID della funzionalità, trasporti, descrizione).

​
Attività comuni

​
Comportamento

  • Usa --json quando l’output viene passato a un altro comando o script; altrimenti usa l’output testuale.
  • Usa --provider o --model provider/model per fissare un backend specifico.
  • Usa model run --thinking <level> per sostituire una tantum il livello di pensiero/ragionamento: off, minimal, low, medium, high, adaptive, xhigh o max.
  • Per image describe, audio transcribe e video describe, --model deve usare il formato <provider/model>.
  • Per image describe, --file accetta percorsi locali e URL HTTP(S); gli URL remoti passano attraverso la normale politica SSRF per il recupero dei contenuti multimediali.
  • I comandi di esecuzione senza stato (model run, image *, audio *, video *, web *, embedding *) utilizzano il percorso locale per impostazione predefinita. I comandi di stato gestiti dal Gateway (tts status) utilizzano il Gateway per impostazione predefinita.
  • Il percorso locale non richiede mai che il Gateway sia in esecuzione.
  • Il comando locale model run esegue un completamento del provider essenziale e una tantum: risolve il modello e l’autenticazione dell’agente configurato, ma non avvia un turno dell’agente di chat, non carica strumenti e non apre i server MCP inclusi.
  • model run --file allega i file immagine al prompt (con rilevamento automatico del tipo MIME); ripeti --file per più immagini. I file che non sono immagini vengono rifiutati: usa invece infer audio transcribe o infer video describe.
  • model run --gateway verifica l’instradamento del Gateway, l’autenticazione salvata, la selezione del provider e il runtime incorporato, ma rimane una verifica diretta del modello: nessuna trascrizione della sessione precedente, nessun contesto bootstrap/AGENTS, nessuno strumento e nessun server MCP incluso.
  • model run --gateway --model <provider/model> richiede una credenziale del Gateway per un operatore attendibile, poiché chiede al Gateway di eseguire una sostituzione una tantum di provider/modello.

​
Modello

Inferenza testuale e ispezione di modelli/provider.
Usa riferimenti completi <provider/model> con --local per eseguire uno smoke test di un provider senza avviare il Gateway o caricare l’interfaccia degli strumenti dell’agente:
Note:
  • Il comando locale model run è lo smoke test CLI più mirato per verificare lo stato di provider/modello/autenticazione: per i provider diversi da ChatGPT-Codex invia solo il prompt specificato.
  • Il comando locale model run --model <provider/model> può risolvere righe esatte del catalogo statico incluso, le stesse mostrate da openclaw models list --all, prima che il provider venga scritto nella configurazione. L’autenticazione del provider è comunque necessaria; le credenziali mancanti generano errori di autenticazione, non Unknown model.
  • Per le verifiche di ragionamento con Mistral Medium 3.5, lascia la temperatura non impostata/predefinita. Mistral rifiuta reasoning_effort="high" con temperature: 0; usa la temperatura predefinita o un valore diverso da zero, ad esempio 0.7.
  • Le verifiche locali con OAuth OpenAI ChatGPT/Codex (API openai-chatgpt-responses) aggiungono un’istruzione di sistema minima affinché il trasporto possa valorizzare il campo obbligatorio instructions: nessun contesto completo dell’agente, strumento, memoria o trascrizione della sessione.
  • model run --file allega direttamente il contenuto dell’immagine al singolo messaggio dell’utente. I formati comuni (PNG, JPEG, WebP) funzionano quando il tipo MIME viene rilevato come image/*; i file non supportati o non riconosciuti generano un errore prima della chiamata al provider. Usa invece infer image describe quando vuoi l’instradamento e i fallback dei modelli di immagini di OpenClaw anziché una verifica diretta di un modello multimodale.
  • Il modello selezionato deve supportare l’input di immagini; i modelli solo testuali potrebbero rifiutare la richiesta a livello del provider.
  • model run --prompt deve contenere testo diverso da soli spazi; i prompt vuoti vengono rifiutati prima di qualsiasi chiamata al provider o al Gateway.
  • Il comando locale model run termina con un codice diverso da zero quando il provider non restituisce output testuale, così provider non raggiungibili e completamenti vuoti non appaiono come verifiche riuscite.
  • Usa model run --gateway per verificare l’instradamento del Gateway o la configurazione del runtime dell’agente mantenendo invariato l’input del modello. Usa openclaw agent o un’interfaccia di chat per ottenere il contesto completo dell’agente, gli strumenti, la memoria e la trascrizione della sessione.
  • --thinking adaptive corrisponde al livello medium del runtime di completamento; --thinking max corrisponde a max per i modelli OpenAI che supportano nativamente lo sforzo massimo, altrimenti a xhigh.
  • model auth login, model auth logout e model auth status gestiscono lo stato di autenticazione salvato del provider.

​
Immagine

Generazione, modifica e descrizione.
Note:
  • Usa image edit quando parti da file di input esistenti; --size, --aspect-ratio o --resolution aggiungono indicazioni geometriche per i provider/modelli che le supportano.
  • --output-format png --background transparent con --model openai/gpt-image-1.5 produce un’immagine PNG OpenAI con sfondo trasparente; --openai-background è un alias specifico di OpenAI per la stessa indicazione. I provider che non dichiarano il supporto per lo sfondo la segnalano come opzione ignorata (vedi ignoredOverrides nell’involucro JSON).
  • --quality low|medium|high|auto funziona con i provider che supportano le indicazioni sulla qualità delle immagini, incluso OpenAI. OpenAI accetta anche --openai-moderation low|auto.
  • image providers --json elenca quali provider di immagini inclusi sono rilevabili, configurati e selezionati, nonché le funzionalità di generazione/modifica esposte da ciascuno.
  • image generate --model <provider/model> --json è il test rapido in ambiente reale più mirato per le modifiche alla generazione di immagini:
    La risposta riporta ok, provider, model, attempts e i percorsi degli output scritti. Quando è impostato --output, l’estensione finale può seguire il tipo MIME restituito dal provider.
  • Per image describe e image describe-many, usa --prompt per un’istruzione specifica per l’attività (OCR, confronto, ispezione dell’interfaccia utente, didascalia concisa).
  • Usa --timeout-ms per modelli di visione locali lenti o per gli avvii a freddo di Ollama.
  • Per image describe, un --model esplicito (deve essere un <provider/model> con supporto per le immagini) viene eseguito per primo, quindi, se la chiamata non riesce, vengono provati i fallback configurati in agents.defaults.imageModel.fallbacks. Gli errori di preparazione dell’input (file mancante, URL non supportato) causano un errore prima di qualsiasi tentativo di fallback e il modello deve supportare le immagini nel catalogo dei modelli o nella configurazione del provider.
  • Per i modelli di visione Ollama locali, scarica prima il modello e imposta OLLAMA_API_KEY su un valore segnaposto qualsiasi, ad esempio ollama-local. Vedi Ollama.

​
Audio

Trascrizione di file (non gestione di sessioni in tempo reale).
--model deve essere <provider/model>.

​
TTS

Sintesi vocale e stato del provider/persona TTS.
Note:
  • tts status supporta solo --gateway (riflette lo stato TTS gestito dal Gateway).
  • Usa tts providers, tts voices, tts personas, tts set-provider e tts set-persona per esaminare e configurare il comportamento TTS.

​
Video

Generazione e descrizione.
Note:
  • video generate accetta --size, --aspect-ratio, --resolution, --duration, --audio, --watermark e --timeout-ms, inoltrati al runtime di generazione video.
  • Per video describe, --model deve essere <provider/model>.

​
Web

Ricerca e recupero.
web providers elenca i provider disponibili, configurati e selezionati per la ricerca e il recupero.

​
Incorporamento

Creazione di vettori e ispezione dei provider di incorporamento.

​
Output JSON

I comandi Infer normalizzano l’output JSON in un involucro condiviso:
Campi di primo livello stabili:
  • ok
  • capability
  • transport
  • provider
  • model
  • attempts
  • inputs (allegati immagine inviati con la richiesta, quando applicabile)
  • outputs
  • ignoredOverrides (chiavi delle indicazioni non supportate da un provider, quando applicabile)
  • error
Per i comandi di generazione di contenuti multimediali, outputs contiene i file scritti da OpenClaw. Per l’automazione, usa path, mimeType, size e le eventuali dimensioni specifiche del contenuto multimediale presenti nell’array, anziché analizzare lo stdout leggibile dall’utente.

​
Errori comuni

​
Contenuti correlati