English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Tools

Strumento di esecuzione

Esegui comandi shell nell'area di lavoro. Supporta l'esecuzione in primo piano + in background tramite process. Se process non è consentito, exec viene eseguito in modo sincrono e ignora yieldMs/background. Le sessioni in background sono limitate per agente; process vede solo le sessioni dello stesso agente.

Parametri

commandstringrequired

Comando shell da eseguire.

workdirstring

Directory di lavoro per il comando.

envobject

Override dell'ambiente chiave/valore uniti sopra l'ambiente ereditato.

yieldMsnumber

Metti automaticamente il comando in background dopo questo ritardo (ms).

backgroundboolean

Metti subito il comando in background invece di attendere yieldMs.

timeoutnumber

Sostituisci il timeout exec configurato per questa chiamata. Imposta timeout: 0 solo quando il comando deve essere eseguito senza il timeout del processo exec.

ptyboolean

Esegui in uno pseudo-terminale quando disponibile. Usa per CLI solo TTY, agenti di coding e UI da terminale.

host'auto' | 'sandbox' | 'gateway' | 'node'

Dove eseguire. auto si risolve in sandbox quando è attivo un runtime sandbox e in gateway altrimenti.

security'deny' | 'allowlist' | 'full'

Modalità di applicazione per l'esecuzione gateway / node.

ask'off' | 'on-miss' | 'always'

Comportamento della richiesta di approvazione per l'esecuzione gateway / node.

nodestring

ID/nome del Node quando host=node.

elevatedboolean

Richiedi la modalità elevata — esci dalla sandbox verso il percorso host configurato. security=full è forzato solo quando elevated 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 singola chiamata è consentito da auto; host=gateway per singola 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 attiva significa che resta nella sandbox.
  • elevated esce dalla sandbox verso il 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 system.run del Node. Se omesso, OpenClaw usa tools.exec.timeoutSec; timeout: 0 esplicito disabilita il timeout del processo exec per quella chiamata.
  • Su 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 non esiste nessuno dei due.
  • Su 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 impedire il dirottamento dei binari o l'iniezione di codice.
  • OpenClaw imposta OPENCLAW_SHELL=exec nell'ambiente del comando generato (incluse l'esecuzione PTY e sandbox) così le regole shell/profile possono rilevare il contesto dello strumento exec.
  • openclaw channels login è bloccato da exec perché è un flusso interattivo di autenticazione canale; eseguilo in un terminale sull'host gateway, oppure usa lo strumento di login nativo del canale dalla chat quando ne esiste uno.
  • Importante: il sandboxing è disattivato per impostazione predefinita. Se il sandboxing è disattivato, host=auto implicito si risolve in gateway. host=sandbox esplicito fallisce comunque in modo chiuso invece di eseguire silenziosamente sull'host gateway. Abilita il sandboxing o usa host=gateway con le approvazioni.
  • I controlli preliminari 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 controllo preliminare 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 intervento; 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 di 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 singola chiamata lo sostituisce; timeout: 0 per singola 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 un comportamento con approvazioni/lista di consentiti, rendi più restrittivi sia tools.exec.* sia il file 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 o usa /exec host=....
  • In modalità security=full più ask=off, l'exec host segue direttamente la policy configurata; non c'è alcun filtro euristico aggiuntivo di offuscamento dei comandi né livello di rifiuto del controllo preliminare degli script.
  • tools.exec.node (predefinito: non impostato)
  • tools.exec.strictInlineEval (predefinito: false): quando true, le forme di eval inline 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 mantenere invocazioni benigne di interpreti/script, ma le forme inline-eval richiedono comunque conferma ogni volta.
  • 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 esplicite nella lista di consentiti. 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 automaticamente attendibili. 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 di PATH

  • host=gateway: unisce il PATH della tua shell di login nell'ambiente exec. Gli override di 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); anche tools.exec.pathPrepend si applica qui.
  • host=node: solo gli override env non bloccati che passi vengono inviati al Node. Gli override di env.PATH sono rifiutati per l'esecuzione host e ignorati dagli host Node. Se ti servono voci PATH aggiuntive su un Node, configura l'ambiente del servizio host Node (systemd/launchd) o installa gli strumenti in posizioni standard.

Associazione Node per agente (usa l'indice dell'elenco agenti 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 "Associazione 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 completamente exec, negalo tramite la policy degli strumenti (tools.deny: ["exec"] o per agente). 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 agenti in sandbox possono richiedere approvazione per richiesta prima che exec venga eseguito sul gateway o sull'host Node. Vedi Approvazioni exec per la policy, la lista di consentiti e il flusso UI.

Quando le approvazioni sono richieste, lo strumento exec restituisce immediatamente status: "approval-pending" e un ID di approvazione. Dopo l'approvazione (o il rifiuto / timeout), 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'agente 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.

Lista di consentiti + binari sicuri

L'applicazione manuale della lista di consentiti 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 ./rg o /tmp/rg. Quando security=allowlist, i comandi shell sono consentiti automaticamente solo se ogni segmento della pipeline è nella lista di consentiti o è un binario sicuro. Concatenamenti (;, &&, ||) e redirezioni sono rifiutati in modalità allowlist a meno che ogni segmento di primo livello soddisfi la lista di consentiti (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 è uguale alle voci manuali della lista di consentiti dei percorsi. Per una fiducia esplicita rigorosa, mantieni autoAllowSkills disabilitato.

Usa i due controlli per compiti diversi:

  • tools.exec.safeBins: piccoli filtri di stream solo stdin.
  • tools.exec.safeBinTrustedDirs: directory attendibili extra esplicite per i percorsi degli eseguibili dei binari sicuri.
  • tools.exec.safeBinProfiles: policy argv esplicita per binari sicuri personalizzati.
  • allowlist: fiducia esplicita per percorsi eseguibili.

Non trattare safeBins come una allowlist generica e non aggiungere binari di interpreti/runtime (ad esempio python3, node, ruby, bash). Se ti servono, usa voci di 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ò generare voci personalizzate safeBinProfiles mancanti. openclaw security audit e openclaw doctor avvisano anche quando aggiungi esplicitamente di nuovo in safeBins binari con comportamento ampio, come jq. Se inserisci esplicitamente interpreti nella allowlist, abilita tools.exec.strictInlineEval affinché le forme di valutazione inline del codice richiedano comunque una nuova approvazione.

Per dettagli completi sulla policy ed esempi, consulta Approvazioni exec e Safe bins rispetto ad allowlist.

Esempi

In primo piano:

{ "tool": "exec", "command": "ls -la" }

Background + 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.

Invia 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"]}

Invia (solo CR):

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

Incolla (tra parentesi 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 tramite 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