Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
openclaw agent

Esegui un turno dell’agente tramite il Gateway (usa --local per l’esecuzione incorporata). Usa --agent <id> per indirizzare direttamente un agente configurato. Passa almeno un selettore di sessione:
  • --to <dest>
  • --session-id <id>
  • --agent <id>
Correlato:

​
Opzioni

  • -m, --message <text>: corpo del messaggio obbligatorio
  • -t, --to <dest>: destinatario usato per derivare la chiave di sessione
  • --session-id <id>: id sessione esplicito
  • --agent <id>: id agente; sovrascrive i binding di instradamento
  • --model <id>: override del modello per questa esecuzione (provider/model o id modello)
  • --thinking <level>: livello di ragionamento dell’agente (off, minimal, low, medium, high, più livelli personalizzati supportati dal provider come xhigh, adaptive o max)
  • --verbose <on|off>: persiste il livello verboso per la sessione
  • --channel <channel>: canale di consegna; ometti per usare il canale principale della sessione
  • --reply-to <target>: override della destinazione di consegna
  • --reply-channel <channel>: override del canale di consegna
  • --reply-account <id>: override dell’account di consegna
  • --local: esegue direttamente l’agente incorporato (dopo il precaricamento del registro Plugin)
  • --deliver: invia la risposta al canale/destinazione selezionati
  • --timeout <seconds>: override del timeout dell’agente (predefinito 600 o valore di configurazione)
  • --json: output JSON

​
Esempi

openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Summarize logs"
openclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
openclaw agent --agent ops --message "Run locally" --local

​
Note

  • La modalità Gateway ripiega sull’agente incorporato quando la richiesta al Gateway non riesce. Usa --local per forzare subito l’esecuzione incorporata.
  • --local precarica comunque prima il registro Plugin, quindi provider, strumenti e canali forniti dai Plugin restano disponibili durante le esecuzioni incorporate.
  • --local e le esecuzioni di fallback incorporato sono trattate come esecuzioni singole. Le risorse MCP loopback in bundle e le sessioni stdio Claude calde aperte per quel processo locale vengono ritirate dopo la risposta, quindi le invocazioni da script non mantengono in vita processi figli locali.
  • Le esecuzioni supportate dal Gateway lasciano le risorse MCP loopback di proprietà del Gateway sotto il processo Gateway in esecuzione; i client meno recenti possono ancora inviare il flag storico di pulizia, ma il Gateway lo accetta come no-op di compatibilità.
  • --channel, --reply-channel e --reply-account influenzano la consegna della risposta, non l’instradamento della sessione.
  • --json mantiene stdout riservato alla risposta JSON. Le diagnostiche del Gateway, dei Plugin e del fallback incorporato vengono instradate a stderr, così gli script possono analizzare direttamente stdout.
  • Il JSON del fallback incorporato include meta.transport: "embedded" e meta.fallbackFrom: "gateway" così gli script possono distinguere le esecuzioni di fallback dalle esecuzioni Gateway.
  • Se il Gateway accetta un’esecuzione agente ma la CLI va in timeout in attesa della risposta finale, il fallback incorporato usa un nuovo id sessione/esecuzione esplicito gateway-fallback-* e riporta meta.fallbackReason: "gateway_timeout" più i campi della sessione di fallback. Questo evita corse sul lock della trascrizione di proprietà del Gateway o la sostituzione silenziosa della sessione di conversazione instradata originale.
  • Quando questo comando attiva la rigenerazione di models.json, le credenziali provider gestite da SecretRef vengono persistite come marcatori non segreti (per esempio nomi di variabili d’ambiente, secretref-env:ENV_VAR_NAME o secretref-managed), non come testo segreto risolto.
  • Le scritture dei marcatori sono autorevoli rispetto alla sorgente: OpenClaw persiste i marcatori dallo snapshot della configurazione sorgente attiva, non dai valori segreti di runtime risolti.

​
Stato di consegna JSON

Quando si usa --json --deliver, la risposta JSON della CLI può includere deliveryStatus di primo livello, così gli script possono distinguere invii consegnati, soppressi, parziali e non riusciti: 
{
  "payloads": [{ "text": "Report ready", "mediaUrl": null }],
  "meta": { "durationMs": 1200 },
  "deliveryStatus": {
    "requested": true,
    "attempted": true,
    "status": "sent",
    "succeeded": true,
    "resultCount": 1
  }
}
deliveryStatus.status è uno tra sent, suppressed, partial_failed o failed. suppressed significa che la consegna non è stata inviata intenzionalmente, per esempio perché un hook di invio messaggi l’ha annullata o perché non c’era alcun risultato visibile; è comunque un esito terminale senza nuovo tentativo. partial_failed significa che almeno un payload è stato inviato prima che un payload successivo non riuscisse. failed significa che nessun invio durevole è stato completato oppure che il preflight della consegna non è riuscito. Anche le risposte CLI supportate dal Gateway preservano la forma grezza del risultato del Gateway, dove lo stesso oggetto è disponibile in result.deliveryStatus. Campi comuni:
  • requested: sempre true quando l’oggetto è presente.
  • attempted: true dopo l’esecuzione del percorso di invio durevole; false per errori di preflight o assenza di payload visibili.
  • succeeded: true, false o "partial"; "partial" si abbina a status: "partial_failed".
  • reason: un motivo in snake-case minuscolo proveniente dalla consegna durevole o dalla validazione di preflight. I motivi noti includono cancelled_by_message_sending_hook, no_visible_payload, no_visible_result, channel_resolved_to_internal, unknown_channel, invalid_delivery_target e no_delivery_target; gli invii durevoli non riusciti possono anche riportare la fase non riuscita. Tratta i valori sconosciuti come opachi perché l’insieme può espandersi.
  • resultCount: numero di risultati di invio del canale quando disponibile.
  • sentBeforeError: true quando un errore parziale ha inviato almeno un payload prima dell’errore.
  • error: booleano true per invii non riusciti o parzialmente non riusciti.
  • errorMessage: incluso solo quando viene acquisito un messaggio di errore di consegna sottostante. Gli errori di preflight contengono error e reason ma nessun errorMessage.
  • payloadOutcomes: risultati opzionali per payload con index, status, reason, resultCount, error, stage, sentBeforeError o metadati dell’hook quando disponibili.

​
Correlati