CLI di inferenza

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:

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

 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.

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 <level> 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 <provider/model>.
• 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/<model> esegue un turno limitato di comprensione immagini del server app Codex; openai/<model> 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 <provider/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.

openclaw infer model run --prompt "Reply with exactly: smoke-ok" --jsonopenclaw infer model run --prompt "Summarize this changelog entry" --model openai/gpt-5.4 --jsonopenclaw infer model run --prompt "Describe this image in one sentence" --file ./photo.jpg --model google/gemini-2.5-flash --jsonopenclaw infer model run --prompt "Use more reasoning here" --thinking high --jsonopenclaw infer model providers --jsonopenclaw infer model inspect --name gpt-5.5 --json

Usa riferimenti completi <provider/model> per fare smoke test di un provider specifico senza avviare il Gateway o caricare l'intera superficie degli strumenti agente:

openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model cerebras/zai-glm-4.7 --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model google/gemini-2.5-flash --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model groq/llama-3.1-8b-instant --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model mistral/mistral-medium-3-5 --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model mistral/mistral-small-latest --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model openai/gpt-5.5 --prompt "Reply with exactly: pong" --jsonopenclaw 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 <provider/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.

openclaw infer image generate --prompt "friendly lobster illustration" --jsonopenclaw infer image generate --prompt "cinematic product photo of headphones" --jsonopenclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --jsonopenclaw infer image generate --model openai/gpt-image-2 --quality low --openai-moderation low --prompt "low-cost draft poster" --jsonopenclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --jsonopenclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --jsonopenclaw infer image edit --file ./poster.png --prompt "make this a vertical story ad" --size 2160x3840 --aspect-ratio 9:16 --resolution 4K --jsonopenclaw infer image describe --file ./photo.jpg --jsonopenclaw infer image describe --file https://example.com/photo.png --jsonopenclaw infer image describe --file ./receipt.jpg --prompt "Extract the merchant, date, and total" --jsonopenclaw infer image describe-many --file ./before.png --file ./after.png --prompt "Compare the screenshots and list visible UI changes" --jsonopenclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-5.4-mini --jsonopenclaw 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 <provider/model> --json come smoke test CLI live più mirato per modifiche alla generazione di immagini. Esempio:

  openclaw infer image providers --jsonopenclaw 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 <provider/model> 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.

Audio

Usa audio per la trascrizione di file.

openclaw infer audio transcribe --file ./memo.m4a --jsonopenclaw infer audio transcribe --file ./team-sync.m4a --language en --prompt "Focus on names and action items" --jsonopenclaw 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 <provider/model>.

TTS

Usa tts per la sintesi vocale e lo stato del provider TTS.

openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --jsonopenclaw infer tts convert --text "Your build is complete" --output ./build-complete.mp3 --jsonopenclaw infer tts providers --jsonopenclaw 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.

openclaw infer video generate --prompt "cinematic sunset over the ocean" --jsonopenclaw infer video generate --prompt "slow drone shot over a forest lake" --resolution 768P --duration 6 --jsonopenclaw infer video describe --file ./clip.mp4 --jsonopenclaw 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 <provider/model> per video describe.

Web

Usa web per flussi di lavoro di ricerca e recupero.

openclaw infer web search --query "OpenClaw docs" --jsonopenclaw infer web search --query "OpenClaw infer web providers" --jsonopenclaw infer web fetch --url https://docs.openclaw.ai/cli/infer --jsonopenclaw 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.

openclaw infer embedding create --text "friendly lobster" --jsonopenclaw infer embedding create --text "customer support ticket: delayed shipment" --model openai/text-embedding-3-large --jsonopenclaw infer embedding providers --json

Output JSON

I comandi Infer normalizzano l'output JSON in un contenitore condiviso:

{  "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

# Badopenclaw infer media image generate --prompt "friendly lobster" # Goodopenclaw infer image generate --prompt "friendly lobster"

# Badopenclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json # Goodopenclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

Note

• openclaw capability ... è un alias di openclaw infer ....

Correlati

• Riferimento CLI
• Modelli