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.

Esegui comandi shell nello spazio di lavoro. exec è una superficie shell mutante: i comandi possono creare, modificare o eliminare file ovunque l’host selezionato o il filesystem della sandbox lo consenta. Disabilitare gli strumenti filesystem di OpenClaw come write, edit o apply_patch non rende exec di sola lettura. Supporta l’esecuzione in primo piano e in background tramite process. Se process non è consentito, exec viene eseguito in modo sincrono e ignora yieldMs/background. Le sessioni in background hanno ambito per agent; process vede solo le sessioni dello stesso agent.

​
Parametri

​
command
string
obbligatorio
Comando shell da eseguire.
​
workdir
string
predefinito:"cwd"
Directory di lavoro per il comando.
​
env
object
Override di ambiente chiave/valore uniti sopra l’ambiente ereditato.
​
yieldMs
number
predefinito:"10000"
Manda automaticamente il comando in background dopo questo ritardo (ms).
​
background
boolean
predefinito:"false"
Manda subito il comando in background invece di attendere yieldMs.
​
timeout
number
predefinito:"tools.exec.timeoutSec"
Sostituisce il timeout exec configurato per questa chiamata. Imposta timeout: 0 solo quando il comando deve essere eseguito senza il timeout del processo exec.
​
pty
boolean
predefinito:"false"
Esegui in uno pseudo-terminale quando disponibile. Usa per CLI solo TTY, agent di codifica e UI terminali.
​
host
'auto' | 'sandbox' | 'gateway' | 'node'
predefinito:"auto"
Dove eseguire. auto si risolve in sandbox quando un runtime sandbox è attivo e in gateway altrimenti.
​
security
'deny' | 'allowlist' | 'full'
Ignorato per le normali chiamate agli strumenti. La sicurezza gateway / node è controllata da tools.exec.security e ~/.openclaw/exec-approvals.json; la modalità elevata può forzare security=full solo quando l’operatore concede esplicitamente l’accesso elevato.
​
ask
'off' | 'on-miss' | 'always'
Comportamento della richiesta di approvazione per l’esecuzione gateway / node.
​
node
string
ID/nome Node quando host=node.
​
elevated
boolean
predefinito:"false"
Richiedi la modalità elevata: esce dalla sandbox sul percorso host configurato. security=full viene forzato solo quando elevato si risolve in full.
Note:
  • host ha come valore predefinito auto: sandbox quando il runtime sandbox è attivo per la sessione, altrimenti Gateway.
  • host accetta solo auto, sandbox, gateway o node. Non è un selettore di hostname; i valori simili a hostname vengono rifiutati prima dell’esecuzione del comando.
  • auto è la strategia di instradamento predefinita, non un carattere jolly. host=node per chiamata è consentito da auto; host=gateway per chiamata è consentito solo quando non è attivo alcun runtime sandbox.
  • Senza configurazione aggiuntiva, host=auto continua a “funzionare e basta”: nessuna sandbox significa che si risolve in gateway; una sandbox live significa che resta nella sandbox.
  • elevated esce dalla sandbox sul percorso host configurato: gateway per impostazione predefinita, oppure node quando tools.exec.host=node (o il valore predefinito della sessione è host=node). È disponibile solo quando l’accesso elevato è abilitato per la sessione/il provider corrente.
  • Le approvazioni gateway/node sono controllate da ~/.openclaw/exec-approvals.json.
  • node richiede un Node associato (app companion o host Node headless).
  • Se sono disponibili più Node, imposta exec.node o tools.exec.node per selezionarne uno.
  • exec host=node è l’unico percorso di esecuzione shell per i Node; il wrapper legacy nodes.run è stato rimosso.
  • timeout si applica all’esecuzione in primo piano, in background, yieldMs, Gateway, sandbox e Node system.run. Se omesso, OpenClaw usa tools.exec.timeoutSec; timeout: 0 esplicito disabilita il timeout del processo exec per quella chiamata.
  • Sugli host non Windows, exec usa SHELL quando impostato; se SHELL è fish, preferisce bash (o sh) da PATH per evitare script incompatibili con fish, poi ripiega su SHELL se nessuno dei due esiste.
  • Sugli host Windows, exec preferisce il rilevamento di PowerShell 7 (pwsh) (Program Files, ProgramW6432, poi PATH), poi ripiega su Windows PowerShell 5.1.
  • L’esecuzione host (gateway/node) rifiuta env.PATH e gli override del loader (LD_*/DYLD_*) per prevenire il dirottamento di binari o codice iniettato.
  • OpenClaw imposta OPENCLAW_SHELL=exec nell’ambiente del comando generato (incluse esecuzione PTY e sandbox) in modo che le regole di shell/profilo possano rilevare il contesto dello strumento exec.
  • openclaw channels login è bloccato da exec perché è un flusso interattivo di autenticazione del canale; eseguilo in un terminale sull’host Gateway, oppure usa lo strumento di login nativo del canale dalla chat quando esiste.
  • Importante: la sandbox è disattivata per impostazione predefinita. Se la sandbox è disattivata, host=auto implicito si risolve in gateway. host=sandbox esplicito fallisce comunque in modo chiuso invece di eseguire silenziosamente sull’host Gateway. Abilita la sandbox o usa host=gateway con approvazioni.
  • I controlli preflight degli script (per errori comuni di sintassi shell Python/Node) ispezionano solo i file dentro il confine effettivo di workdir. Se il percorso di uno script si risolve fuori da workdir, il preflight viene saltato per quel file.
  • Per lavori di lunga durata che iniziano ora, avviali una sola volta e affidati al risveglio automatico al completamento quando è abilitato e il comando emette output o fallisce. Usa process per log, stato, input o interventi; non emulare la pianificazione con cicli sleep, cicli timeout o polling ripetuto.
  • Per lavori che devono avvenire più tardi o secondo una pianificazione, usa Cron invece dei pattern sleep/delay di exec.

​
Configurazione

  • tools.exec.notifyOnExit (predefinito: true): quando true, le sessioni exec messe in background accodano un evento di sistema e richiedono un Heartbeat all’uscita.
  • tools.exec.approvalRunningNoticeMs (predefinito: 10000): emette un singolo avviso “in esecuzione” quando un exec soggetto ad approvazione dura più di questo valore (0 disabilita).
  • tools.exec.timeoutSec (predefinito: 1800): timeout exec predefinito per comando in secondi. timeout per chiamata lo sostituisce; timeout: 0 per chiamata disabilita il timeout del processo exec.
  • tools.exec.host (predefinito: auto; si risolve in sandbox quando il runtime sandbox è attivo, gateway altrimenti)
  • tools.exec.security (predefinito: deny per sandbox, full per Gateway + Node quando non impostato)
  • tools.exec.ask (predefinito: off)
  • L’exec host senza approvazione è il valore predefinito per Gateway + Node. Se vuoi il comportamento con approvazioni/allowlist, rendi più restrittivi sia tools.exec.* sia l’host ~/.openclaw/exec-approvals.json; vedi Approvazioni exec.
  • YOLO deriva dai valori predefiniti della policy host (security=full, ask=off), non da host=auto. Se vuoi forzare l’instradamento Gateway o Node, imposta tools.exec.host oppure usa /exec host=....
  • In modalità security=full più ask=off, exec host segue direttamente la policy configurata; non esiste un prefiltro euristico aggiuntivo di offuscamento dei comandi né un livello di rifiuto preflight degli script.
  • tools.exec.node (predefinito: non impostato)
  • tools.exec.strictInlineEval (predefinito: false): quando true, le forme inline di eval degli interpreti come python -c, node -e, ruby -e, perl -e, php -r, lua -e e osascript -e richiedono sempre approvazione esplicita. allow-always può comunque persistere invocazioni benigne di interpreti/script, ma le forme inline-eval richiedono comunque conferma ogni volta.
  • tools.exec.commandHighlighting (predefinito: false): quando true, le richieste di approvazione possono evidenziare nel testo del comando gli span di comando derivati dal parser. Imposta su true a livello globale o per agent per abilitare l’evidenziazione del testo del comando senza modificare la policy di approvazione exec.
  • tools.exec.pathPrepend: elenco di directory da anteporre a PATH per le esecuzioni exec (solo Gateway + sandbox).
  • tools.exec.safeBins: binari sicuri solo stdin che possono essere eseguiti senza voci allowlist esplicite. Per i dettagli sul comportamento, vedi Binari sicuri.
  • tools.exec.safeBinTrustedDirs: directory esplicite aggiuntive considerate attendibili per i controlli del percorso safeBins. Le voci PATH non sono mai considerate attendibili automaticamente. I valori predefiniti integrati sono /bin e /usr/bin.
  • tools.exec.safeBinProfiles: policy argv personalizzata opzionale per binario sicuro (minPositional, maxPositional, allowedValueFlags, deniedFlags).
Esempio: 
{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

​
Gestione PATH

  • host=gateway: unisce il PATH della tua shell di login nell’ambiente exec. Gli override env.PATH sono rifiutati per l’esecuzione host. Il daemon stesso continua a essere eseguito con un PATH minimo:
    • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
    • Linux: /usr/local/bin, /usr/bin, /bin
  • host=sandbox: esegue sh -lc (shell di login) dentro il container, quindi /etc/profile può reimpostare PATH. OpenClaw antepone env.PATH dopo il sourcing del profilo tramite una variabile env interna (senza interpolazione shell); tools.exec.pathPrepend si applica anche qui.
  • host=node: solo gli override env non bloccati che passi vengono inviati al Node. Gli override env.PATH sono rifiutati per l’esecuzione host e ignorati dagli host Node. Se hai bisogno di voci PATH aggiuntive su un Node, configura l’ambiente del servizio host Node (systemd/launchd) o installa gli strumenti in posizioni standard.
Binding Node per agent (usa l’indice dell’elenco agent nella configurazione): 
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
UI di controllo: la scheda Nodes include un piccolo pannello “Binding Node exec” per le stesse impostazioni.

​
Override di sessione (/exec)

Usa /exec per impostare i valori predefiniti per sessione per host, security, ask e node. Invia /exec senza argomenti per mostrare i valori correnti. Esempio: 
/exec host=auto security=allowlist ask=on-miss node=mac-1

​
Modello di autorizzazione

/exec viene rispettato solo per mittenti autorizzati (allowlist/associazione dei canali più commands.useAccessGroups). Aggiorna solo lo stato della sessione e non scrive la configurazione. Per disabilitare forzatamente exec, negalo tramite la policy degli strumenti (tools.deny: ["exec"] o per agent). Le approvazioni host continuano ad applicarsi a meno che tu non imposti esplicitamente security=full e ask=off.

​
Approvazioni exec (app companion / host Node)

Gli agent in sandbox possono richiedere l’approvazione per richiesta prima che exec venga eseguito sul Gateway o sull’host Node. Vedi Approvazioni exec per la policy, l’allowlist e il flusso UI. Quando le approvazioni sono richieste, lo strumento exec restituisce immediatamente status: "approval-pending" e un ID di approvazione. Una volta approvato (o negato / scaduto), il Gateway emette eventi di sistema (Exec finished / Exec denied). Se il comando è ancora in esecuzione dopo tools.exec.approvalRunningNoticeMs, viene emesso un singolo avviso Exec running. Sui canali con schede/pulsanti di approvazione nativi, l’agent dovrebbe affidarsi prima a quella UI nativa e includere un comando manuale /approve solo quando il risultato dello strumento dice esplicitamente che le approvazioni via chat non sono disponibili o che l’approvazione manuale è l’unico percorso.

​
Allowlist + binari sicuri

L’applicazione manuale dell’allowlist confronta glob di percorsi binari risolti e glob di nomi comando semplici. I nomi semplici corrispondono solo ai comandi invocati tramite PATH, quindi rg può corrispondere a /opt/homebrew/bin/rg quando il comando è rg, ma non a ./rg o /tmp/rg. Quando security=allowlist, i comandi shell sono consentiti automaticamente solo se ogni segmento della pipeline è in allowlist o è un binario sicuro. Concatenazioni (;, &&, ||) e redirezioni sono rifiutate in modalità allowlist a meno che ogni segmento di primo livello soddisfi l’allowlist (inclusi i binari sicuri). Le redirezioni restano non supportate. La fiducia durevole allow-always non aggira questa regola: un comando concatenato richiede comunque che ogni segmento di primo livello corrisponda. autoAllowSkills è un percorso di comodità separato nelle approvazioni exec. Non è la stessa cosa delle voci manuali dell’allowlist dei percorsi. Per una fiducia esplicita rigorosa, mantieni autoAllowSkills disabilitato. Usa i due controlli per lavori diversi:
  • tools.exec.safeBins: piccoli filtri di flusso, solo stdin.
  • tools.exec.safeBinTrustedDirs: directory attendibili aggiuntive esplicite per i percorsi degli eseguibili safe-bin.
  • tools.exec.safeBinProfiles: policy argv esplicita per safe bin personalizzati.
  • allowlist: attendibilità esplicita per i percorsi degli eseguibili.
Non trattare safeBins come una allowlist generica e non aggiungere binari di interpreti/runtime (per esempio python3, node, ruby, bash). Se ti servono, usa voci allowlist esplicite e mantieni abilitate le richieste di approvazione. openclaw security audit avvisa quando le voci safeBins di interpreti/runtime non hanno profili espliciti, e openclaw doctor --fix può creare lo scaffold delle voci safeBinProfiles personalizzate mancanti. openclaw security audit e openclaw doctor avvisano anche quando aggiungi esplicitamente di nuovo in safeBins bin con comportamento ampio come jq. Se inserisci esplicitamente gli interpreti nella allowlist, abilita tools.exec.strictInlineEval in modo che le forme inline di valutazione del codice richiedano comunque una nuova approvazione. Per i dettagli completi della policy e gli esempi, consulta Approvazioni exec e Safe bin rispetto alla allowlist.

​
Esempi

Primo piano: 
{ "tool": "exec", "command": "ls -la" }
Sfondo + polling: 
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
Il polling serve per lo stato su richiesta, non per cicli di attesa. Se il risveglio automatico al completamento è abilitato, il comando può risvegliare la sessione quando emette output o fallisce. Inviare tasti (stile tmux): 
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}
Invio (invia solo CR): 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
Incolla (con bracketed paste per impostazione predefinita): 
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​
apply_patch

apply_patch è un sottostrumento di exec per modifiche strutturate su più file. È abilitato per impostazione predefinita per i modelli OpenAI e OpenAI Codex. Usa la configurazione solo quando vuoi disabilitarlo o limitarlo a modelli specifici: 
{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
    },
  },
}
Note:
  • Disponibile solo per i modelli OpenAI/OpenAI Codex.
  • La policy degli strumenti si applica comunque; allow: ["write"] consente implicitamente apply_patch.
  • deny: ["write"] non nega apply_patch; nega esplicitamente apply_patch oppure usa deny: ["group:fs"] quando anche le scritture delle patch devono essere bloccate.
  • La configurazione si trova sotto tools.exec.applyPatch.
  • tools.exec.applyPatch.enabled ha valore predefinito true; impostalo su false per disabilitare lo strumento per i modelli OpenAI.
  • tools.exec.applyPatch.workspaceOnly ha valore predefinito true (contenuto nell’area di lavoro). Impostalo su false solo se vuoi intenzionalmente che apply_patch scriva/elimini fuori dalla directory dell’area di lavoro.

​
Correlati