--- read_when: - Aggiunta o modifica dei comandi `openclaw infer` - Progettazione di automazioni stabili per funzionalità headless summary: CLI infer-first per flussi di lavoro con provider per modelli, immagini, audio, TTS, video, web ed embedding title: CLI di inferenza x-i18n: generated_at: "2026-07-01T08:09:06Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: bb63996dd1364bffba58d4b132849ac4157fb612555c009da795c963142f9368 source_path: cli/infer.md workflow: 16 --- `openclaw infer` è la superficie headless canonica per i flussi di lavoro di inferenza supportati da provider. Espone intenzionalmente famiglie di capability, non nomi RPC grezzi del Gateway e non ID grezzi degli strumenti agente. ## Trasformare infer in una skill Copia e incolla questo in un agente: ```text Leggi https://docs.openclaw.ai/cli/infer, quindi crea una skill che instradi i miei flussi di lavoro comuni verso `openclaw infer`. Concentrati su esecuzioni di modelli, generazione di immagini, generazione di video, trascrizione audio, TTS, ricerca web ed embeddings. ``` Una buona skill basata su infer dovrebbe: - mappare gli intenti utente comuni al sottocomando infer corretto - includere alcuni esempi infer canonici per i flussi di lavoro che copre - preferire `openclaw infer ...` negli esempi e nei suggerimenti - evitare di documentare di nuovo l'intera superficie infer nel corpo della skill Copertura tipica di una skill incentrata su infer: - `openclaw infer model run` - `openclaw infer image generate` - `openclaw infer audio transcribe` - `openclaw infer tts convert` - `openclaw infer web search` - `openclaw infer embedding create` ## Perché usare infer `openclaw infer` fornisce una CLI coerente per le attività di inferenza supportate da provider all'interno di OpenClaw. Vantaggi: - Usa i provider e i modelli già configurati in OpenClaw invece di cablare wrapper una tantum per ogni backend. - Mantieni i flussi di lavoro di modelli, immagini, trascrizione audio, TTS, video, web ed embedding sotto un unico albero di comandi. - Usa una forma di output `--json` stabile per script, automazione e flussi di lavoro guidati da agenti. - Preferisci una superficie OpenClaw first-party quando l'attività è fondamentalmente "eseguire inferenza". - Usa il normale percorso locale senza richiedere il gateway per la maggior parte dei comandi infer. Per i controlli provider end-to-end, preferisci `openclaw infer ...` una volta che i test provider di livello inferiore sono verdi. Esercita la CLI distribuita, il caricamento della configurazione, la risoluzione dell'agente predefinito, l'attivazione dei Plugin in bundle e il runtime condiviso delle capability prima che venga effettuata la richiesta al provider. ## Albero dei comandi ```text openclaw infer list inspect model run list inspect providers auth login auth logout auth status image generate edit describe describe-many providers audio transcribe providers tts convert voices providers status enable disable set-provider video generate describe providers web search fetch providers embedding create providers ``` ## Attività comuni Questa tabella mappa le attività di inferenza comuni al comando infer corrispondente. | Attività | Comando | Note | | ----------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | Eseguire un prompt testo/modello | `openclaw infer model run --prompt "..." --json` | Usa il normale percorso locale per impostazione predefinita | | Eseguire un prompt modello su immagini | `openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model` | Ripeti `--file` per più input immagine | | Generare un'immagine | `openclaw infer image generate --prompt "..." --json` | Usa `image edit` quando parti da un file esistente | | Descrivere un file immagine o URL | `openclaw infer image describe --file ./image.png --prompt "..." --json` | `--model` deve essere un `` con capability immagine | | Trascrivere audio | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` deve essere `` | | Sintetizzare voce | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` è orientato al gateway | | Generare un video | `openclaw infer video generate --prompt "..." --json` | Supporta suggerimenti provider come `--resolution` | | Descrivere un file video | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` deve essere `` | | Cercare nel web | `openclaw infer web search --query "..." --json` | | | Recuperare una pagina web | `openclaw infer web fetch --url https://example.com --json` | | | Creare embeddings | `openclaw infer embedding create --text "..." --json` | | ## Comportamento - `openclaw infer ...` è la superficie CLI primaria per questi flussi di lavoro. - Usa `--json` quando l'output sarà consumato da un altro comando o script. - Usa `--provider` o `--model provider/model` quando è richiesto un backend specifico. - Usa `model run --thinking ` per passare un livello thinking/reasoning una tantum (`off`, `minimal`, `low`, `medium`, `high`, `adaptive`, `xhigh` o `max`) mantenendo l'esecuzione raw. - Per `image describe`, `audio transcribe` e `video describe`, `--model` deve usare la forma ``. - Per `image describe`, `--file` accetta percorsi locali e URL immagine HTTP(S). Gli URL remoti usano la normale policy SSRF di recupero media. - Per `image describe`, un `--model` esplicito esegue prima quel provider/modello, poi prova i `agents.defaults.imageModel.fallbacks` configurati quando la chiamata al modello fallisce. Gli errori di preparazione dell'input, come file mancanti o URL non supportati, falliscono prima dei tentativi di fallback. Il modello deve avere capability immagine nel catalogo modelli o nella configurazione provider. `codex/` esegue un turno limitato di comprensione immagini del server app Codex; `openai/` usa il percorso del provider OpenAI con autenticazione tramite API key oppure OAuth ChatGPT/Codex. - I comandi di esecuzione stateless usano local per impostazione predefinita. - I comandi di stato gestiti dal Gateway usano gateway per impostazione predefinita. - Il normale percorso locale non richiede che il gateway sia in esecuzione. - `model run` locale è una completion provider one-shot leggera. Risolve il modello agente configurato e l'autenticazione, ma non avvia un turno chat-agent, non carica strumenti e non apre server MCP in bundle. - `model run --file` accetta file immagine, ne rileva il tipo MIME e li invia con il prompt fornito al modello selezionato. Ripeti `--file` per più immagini. - `model run --file` rifiuta input non immagine. Usa `infer audio transcribe` per file audio e `infer video describe` per file video. - `model run --gateway` esercita routing Gateway, autenticazione salvata, selezione provider e runtime incorporato, ma viene comunque eseguito come probe raw del modello: invia il prompt fornito ed eventuali allegati immagine senza transcript di sessione precedente, contesto bootstrap/AGENTS, assemblaggio del motore di contesto, strumenti o server MCP in bundle. - `model run --gateway --model ` richiede una credenziale gateway operatore attendibile perché la richiesta chiede al Gateway di eseguire un override provider/modello una tantum. - `model run --thinking` locale usa il percorso leggero di completion provider; livelli specifici del provider come `adaptive` e `max` sono mappati al livello portatile di simple-completion più vicino. ## Modello Usa `model` per l'inferenza testuale supportata da provider e per l'ispezione di modelli/provider. ```bash openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json openclaw infer model run --prompt "Summarize this changelog entry" --model openai/gpt-5.4 --json openclaw infer model run --prompt "Describe this image in one sentence" --file ./photo.jpg --model google/gemini-2.5-flash --json openclaw infer model run --prompt "Use more reasoning here" --thinking high --json openclaw infer model providers --json openclaw infer model inspect --name gpt-5.5 --json ``` Usa riferimenti completi `` per fare smoke test di un provider specifico senza avviare il Gateway o caricare l'intera superficie degli strumenti agente: ```bash openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --json openclaw infer model run --local --model cerebras/zai-glm-4.7 --prompt "Reply with exactly: pong" --json openclaw infer model run --local --model google/gemini-2.5-flash --prompt "Reply with exactly: pong" --json openclaw infer model run --local --model groq/llama-3.1-8b-instant --prompt "Reply with exactly: pong" --json openclaw infer model run --local --model mistral/mistral-medium-3-5 --prompt "Reply with exactly: pong" --json openclaw infer model run --local --model mistral/mistral-small-latest --prompt "Reply with exactly: pong" --json openclaw infer model run --local --model openai/gpt-5.5 --prompt "Reply with exactly: pong" --json openclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe this image." --file ./photo.jpg --json ``` Note: - `model run` locale è lo smoke CLI più stretto per lo stato di salute di provider/modello/auth perché, per provider non Codex, invia solo il prompt fornito al modello selezionato. - `model run --model ` locale può usare righe esatte del catalogo statico in bundle da `models list --all` prima che quel provider venga scritto nella configurazione. L'autenticazione provider è comunque richiesta; credenziali mancanti falliscono come errori di autenticazione, non `Unknown model`. - Per probe di reasoning Mistral Medium 3.5, lascia la temperatura non impostata/predefinita. Mistral rifiuta `reasoning_effort="high"` più `temperature: 0`; usa `mistral/mistral-medium-3-5` con temperatura predefinita o un valore reasoning-mode diverso da zero come `0.7`. - I probe locali Codex Responses sono la stretta eccezione: OpenClaw aggiunge un'istruzione di sistema minima così il transport può popolare il suo campo `instructions` richiesto, senza aggiungere contesto agente completo, strumenti, memoria o transcript di sessione. - `model run --file` locale mantiene quel percorso leggero e allega contenuto immagine direttamente al singolo messaggio utente. File immagine comuni come PNG, JPEG e WebP funzionano quando il loro tipo MIME viene rilevato come `image/*`; file non supportati o non riconosciuti falliscono prima che venga chiamato il provider. - `model run --file` è ideale quando vuoi testare direttamente il modello testuale multimodale selezionato. Usa `infer image describe` quando vuoi la selezione provider di comprensione immagini di OpenClaw e il routing predefinito del modello immagine. - Il modello selezionato deve supportare input immagine; i modelli solo testo possono rifiutare la richiesta al livello del provider. - `model run --prompt` deve contenere testo non composto solo da spazi; i prompt vuoti vengono rifiutati prima che siano chiamati i provider locali o il Gateway. - `model run` locale esce con codice diverso da zero quando il provider non restituisce output testuale, quindi provider locali non raggiungibili e completion vuote non sembrano probe riusciti. - Usa `model run --gateway` quando devi testare routing Gateway, configurazione del runtime agente o stato provider gestito dal Gateway mantenendo raw l'input del modello. Usa `openclaw agent` o superfici chat quando vuoi il contesto agente completo, strumenti, memoria e transcript di sessione. - `model auth login`, `model auth logout` e `model auth status` gestiscono lo stato di autenticazione provider salvato. ## Immagine Usa `image` per generazione, modifica e descrizione. ```bash openclaw infer image generate --prompt "friendly lobster illustration" --json openclaw infer image generate --prompt "cinematic product photo of headphones" --json openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --json openclaw infer image generate --model openai/gpt-image-2 --quality low --openai-moderation low --prompt "low-cost draft poster" --json openclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --json openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --json openclaw infer image edit --file ./poster.png --prompt "make this a vertical story ad" --size 2160x3840 --aspect-ratio 9:16 --resolution 4K --json openclaw infer image describe --file ./photo.jpg --json openclaw infer image describe --file https://example.com/photo.png --json openclaw infer image describe --file ./receipt.jpg --prompt "Extract the merchant, date, and total" --json openclaw infer image describe-many --file ./before.png --file ./after.png --prompt "Compare the screenshots and list visible UI changes" --json openclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-5.4-mini --json openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --prompt "Describe the image in one sentence" --timeout-ms 300000 --json ``` Note: - Usa `image edit` quando parti da file di input esistenti. - Usa `--size`, `--aspect-ratio` o `--resolution` con `image edit` per provider/modelli che supportano suggerimenti geometrici nelle modifiche di immagini di riferimento. - Usa `--output-format png --background transparent` con `--model openai/gpt-image-1.5` per l'output PNG OpenAI con sfondo trasparente; `--openai-background` resta disponibile come alias specifico di OpenAI. I provider che non dichiarano il supporto dello sfondo segnalano il suggerimento come override ignorato. - Usa `--quality low|medium|high|auto` per i provider che supportano suggerimenti sulla qualità delle immagini, incluso OpenAI. OpenAI accetta anche `--openai-moderation low|auto` per il suggerimento di moderazione specifico del provider. - Usa `image providers --json` per verificare quali provider di immagini inclusi sono individuabili, configurati, selezionati e quali capacità di generazione/modifica espone ciascun provider. - Usa `image generate --model --json` come smoke test CLI live più mirato per modifiche alla generazione di immagini. Esempio: ```bash openclaw infer image providers --json openclaw infer image generate \ --model google/gemini-3.1-flash-image-preview \ --prompt "Minimal flat test image: one blue square on a white background, no text." \ --output ./openclaw-infer-image-smoke.png \ --json ``` La risposta JSON riporta `ok`, `provider`, `model`, `attempts` e i percorsi di output scritti. Quando `--output` è impostato, l'estensione finale può seguire il tipo MIME restituito dal provider. - Per `image describe` e `image describe-many`, usa `--prompt` per dare al modello vision un'istruzione specifica per il compito, come OCR, confronto, ispezione dell'interfaccia utente o didascalia concisa. - Usa `--timeout-ms` con modelli vision locali lenti o avvii a freddo di Ollama. - Per `image describe`, `--model` deve essere un `` con capacità immagine. Quando è impostato, OpenClaw prova prima quel modello esplicito e poi i fallback configurati dei modelli immagine se la chiamata al modello non riesce. - Per i modelli vision Ollama locali, scarica prima il modello e imposta `OLLAMA_API_KEY` su un valore segnaposto qualsiasi, per esempio `ollama-local`. Vedi [Ollama](/it/providers/ollama#vision-and-image-description). ## Audio Usa `audio` per la trascrizione di file. ```bash openclaw infer audio transcribe --file ./memo.m4a --json openclaw infer audio transcribe --file ./team-sync.m4a --language en --prompt "Focus on names and action items" --json openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json ``` Note: - `audio transcribe` serve per la trascrizione di file, non per la gestione di sessioni in tempo reale. - `--model` deve essere ``. ## TTS Usa `tts` per la sintesi vocale e lo stato del provider TTS. ```bash openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json openclaw infer tts convert --text "Your build is complete" --output ./build-complete.mp3 --json openclaw infer tts providers --json openclaw infer tts status --json ``` Note: - `tts status` usa gateway come impostazione predefinita perché riflette lo stato TTS gestito dal gateway. - Usa `tts providers`, `tts voices` e `tts set-provider` per ispezionare e configurare il comportamento TTS. ## Video Usa `video` per generazione e descrizione. ```bash openclaw infer video generate --prompt "cinematic sunset over the ocean" --json openclaw infer video generate --prompt "slow drone shot over a forest lake" --resolution 768P --duration 6 --json openclaw infer video describe --file ./clip.mp4 --json openclaw infer video describe --file ./clip.mp4 --model openai/gpt-5.4-mini --json ``` Note: - `video generate` accetta `--size`, `--aspect-ratio`, `--resolution`, `--duration`, `--audio`, `--watermark` e `--timeout-ms` e li inoltra al runtime di generazione video. - `--model` deve essere `` per `video describe`. ## Web Usa `web` per flussi di lavoro di ricerca e recupero. ```bash openclaw infer web search --query "OpenClaw docs" --json openclaw infer web search --query "OpenClaw infer web providers" --json openclaw infer web fetch --url https://docs.openclaw.ai/cli/infer --json openclaw infer web providers --json ``` Note: - Usa `web providers` per ispezionare i provider disponibili, configurati e selezionati. ## Embedding Usa `embedding` per la creazione di vettori e l'ispezione dei provider di embedding. ```bash openclaw infer embedding create --text "friendly lobster" --json openclaw infer embedding create --text "customer support ticket: delayed shipment" --model openai/text-embedding-3-large --json openclaw infer embedding providers --json ``` ## Output JSON I comandi Infer normalizzano l'output JSON in un contenitore condiviso: ```json { "ok": true, "capability": "image.generate", "transport": "local", "provider": "openai", "model": "gpt-image-2", "attempts": [], "outputs": [] } ``` I campi di primo livello sono stabili: - `ok` - `capability` - `transport` - `provider` - `model` - `attempts` - `outputs` - `error` Per i comandi di media generati, `outputs` contiene i file scritti da OpenClaw. Usa `path`, `mimeType`, `size` e le eventuali dimensioni specifiche dei media in quell'array per l'automazione invece di analizzare lo stdout leggibile dall'uomo. ## Errori comuni ```bash # Bad openclaw infer media image generate --prompt "friendly lobster" # Good openclaw infer image generate --prompt "friendly lobster" ``` ```bash # Bad openclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json # Good openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json ``` ## Note - `openclaw capability ...` è un alias di `openclaw infer ...`. ## Correlati - [Riferimento CLI](/it/cli) - [Modelli](/it/concepts/models)