Agent coordination

Invio dell’agente

openclaw agent esegue un singolo turno dell'agente dalla riga di comando senza un messaggio di chat in entrata. Usalo per flussi di lavoro con script, test e consegna programmatica. Riferimento completo su flag e comportamento: Riferimento della CLI dell'agente.

Avvio rapido

Esegui un semplice turno dell'agente

bash

openclaw agent --agent main --message "What is the weather today?"

Invia il messaggio tramite il Gateway e stampa la risposta.

Invia un prompt su più righe da un file

bash

openclaw agent --agent ops --message-file ./task.md

Legge un file UTF-8 valido come corpo del messaggio dell'agente.

Specifica un agente o una sessione

bash

# Target a specific agentopenclaw agent --agent ops --message "Summarize logs" # Target a phone number (derives session key)openclaw agent --to +15555550123 --message "Status update" # Reuse an existing sessionopenclaw agent --session-id abc123 --message "Continue the task" # Target an exact session keyopenclaw agent --session-key agent:ops:incident-42 --message "Summarize status"

Consegna la risposta a un canale

bash

# Deliver to WhatsApp (default channel)openclaw agent --to +15555550123 --message "Report ready" --deliver # Deliver to Slackopenclaw agent --agent ops --message "Generate report" \  --deliver --reply-channel slack --reply-to "#reports"

Flag

Flag	Descrizione
`--message <text>`	Messaggio in linea da inviare
`--message-file <path>`	Legge il messaggio da un file UTF-8 valido
`--to <dest>`	Deriva la chiave di sessione da una destinazione (telefono, ID chat)
`--session-key <key>`	Usa una chiave di sessione esplicita
`--agent <id>`	Specifica un agente configurato (usa la sua sessione `main`)
`--session-id <id>`	Riutilizza una sessione esistente tramite ID
`--model <id>`	Sostituisce il modello per questa esecuzione (`provider/model` o ID modello)
`--local`	Forza il runtime incorporato locale (ignora il Gateway)
`--deliver`	Invia la risposta a un canale di chat
`--channel <name>`	Canale di consegna; con `--agent` + `--to`, si applica anche all'ambito dei messaggi diretti
`--reply-to <target>`	Sostituisce la destinazione di consegna
`--reply-channel <name>`	Sostituisce il canale di consegna
`--reply-account <id>`	Sostituisce l'ID dell'account di consegna
`--thinking <level>`	Imposta il livello di ragionamento per il profilo del modello selezionato
`--verbose <on\|full\|off>`	Mantiene il livello di verbosità per la sessione (`full` registra anche l'output degli strumenti)
`--timeout <seconds>`	Sostituisce il timeout dell'agente (valore predefinito: 600 o valore di configurazione)
`--json`	Produce JSON strutturato

Comportamento

Per impostazione predefinita, la CLI passa attraverso il Gateway. Aggiungi --local per forzare il runtime incorporato sulla macchina corrente.
Passa esattamente uno tra --message e --message-file. I messaggi da file conservano il contenuto su più righe dopo la rimozione di un BOM UTF-8 facoltativo.
Se la richiesta al Gateway non riesce, la CLI ripiega sull'esecuzione incorporata locale; in caso di timeout del Gateway, ripiega usando una nuova sessione anziché eseguire in parallelo con la trascrizione originale.
Selezione della sessione: --to deriva la chiave di sessione (le destinazioni di gruppo/canale mantengono l'isolamento; le chat dirette confluiscono in main). Quando --agent, --channel e --to sono usati insieme, l'instradamento segue il destinatario canonico del canale e session.dmScope. Le identità stabili utilizzate solo per l'invio usano una sessione gestita dal provider, isolata dalla sessione principale dell'agente.
--session-key seleziona una chiave esplicita. Le chiavi con prefisso dell'agente devono usare agent:<agent-id>:<session-key> e, quando sono specificati entrambi, --agent deve corrispondere a tale ID agente. Le chiavi semplici che non sono sentinelle vengono associate a --agent, se specificato; ad esempio, --agent ops --session-key incident-42 viene instradato a agent:ops:incident-42. Senza --agent, le chiavi semplici che non sono sentinelle vengono associate all'agente predefinito configurato. I valori letterali global e unknown rimangono senza ambito solo quando --agent non è specificato; il percorso di ripiego incorporato risolve tali sessioni sentinella nell'agente predefinito configurato.
--reply-channel e --reply-account influiscono solo sulla consegna.
I flag di ragionamento e verbosità vengono mantenuti nell'archivio della sessione.
Output: testo normale per impostazione predefinita oppure --json per payload strutturato e metadati.
Con --json --deliver, il JSON include lo stato di consegna per gli invii effettuati, soppressi, parziali e non riusciti. Consulta Stato di consegna JSON.

Esempi

bash

# Simple turn with JSON outputopenclaw agent --to +15555550123 --message "Trace logs" --verbose on --json # Turn with a model overrideopenclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs" # Turn with thinking levelopenclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium # Multiline prompt from a fileopenclaw agent --agent ops --message-file ./task.md # Exact session keyopenclaw agent --session-key agent:ops:incident-42 --message "Summarize status" # Legacy key scoped to an agentopenclaw agent --agent ops --session-key incident-42 --message "Summarize status" # Deliver to a different channel than the sessionopenclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"