Strumento exec

​

Parametri

• 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.
• tools.exec.mode è la manopola di policy normalizzata. I valori sono deny, allowlist, ask, auto e full. auto esegue direttamente le corrispondenze deterministiche allowlist/safe-bin e instrada ogni caso restante di approvazione exec attraverso l’auto reviewer nativo di OpenClaw prima di chiedere a un essere umano. ask / ask=always continua a chiedere a un essere umano ogni volta.
• 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 dal file delle approvazioni dell’host.
• 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 la discovery di PowerShell 7 (pwsh) (Program Files, ProgramW6432, poi PATH), poi ripiega su Windows PowerShell 5.1.
• Sugli host gateway non Windows, i comandi exec bash e zsh usano uno snapshot di avvio. OpenClaw acquisisce alias/funzioni sorgentabili e un piccolo insieme sicuro di ambiente dai file di avvio della shell in $OPENCLAW_STATE_DIR/cache/shell-snapshots/, poi carica quello snapshot prima di ogni comando exec. Le variabili che sembrano segreti sono escluse; sandbox e node exec non usano questo snapshot. Imposta OPENCLAW_EXEC_SHELL_SNAPSHOT=0 nell’ambiente del processo Gateway per disabilitare questo percorso snapshot.
• L’esecuzione host (gateway/node) rifiuta env.PATH e le sostituzioni del loader (LD_*/DYLD_*) per impedire dirottamenti di binari o codice iniettato.
• OpenClaw imposta OPENCLAW_SHELL=exec nell’ambiente del comando avviato (incluse l’esecuzione PTY e sandbox) così le regole shell/profile possono rilevare il contesto dello strumento exec.
• Per le esecuzioni originate da canale, OpenClaw espone anche un payload JSON ristretto con identità mittente/chat in OPENCLAW_CHANNEL_CONTEXT quando il canale ha fornito quegli ID.
• 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 esiste.
• 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 essere eseguito silenziosamente sull’host gateway. Abilita il sandboxing o usa host=gateway con approvazioni.
• I controlli preflight degli script (per comuni errori di sintassi shell Python/Node) ispezionano solo i file dentro il confine effettivo di workdir. Se un percorso script si risolve fuori da workdir, il preflight viene saltato per quel file.
• Per lavoro a lunga durata che parte ora, avvialo 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 schedulazione con cicli sleep, cicli timeout o polling ripetuto.
• Per lavoro che deve avvenire più tardi o secondo una pianificazione, usa cron invece di pattern sleep/delay con exec.

​

Configurazione

• tools.exec.notifyOnExit (predefinito: true): quando true, le sessioni exec mandate 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 resta in esecuzione più a lungo di questo valore (0 disabilita).
• tools.exec.timeoutSec (predefinito: 1800): timeout exec predefinito per comando in secondi. timeout per chiamata lo sovrascrive; 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 comportamento con approvazioni/allowlist, irrigidisci sia tools.exec.* sia il file delle approvazioni dell’host; vedi Approvazioni exec.
• YOLO deriva dai valori predefiniti della policy dell’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’è un ulteriore livello euristico di prefiltro per offuscamento del comando o rifiuto preflight degli script.
• tools.exec.node (predefinito: non impostato)
• tools.exec.strictInlineEval (predefinito: false): quando true, le forme eval inline degli interpreti come python -c, node -e, ruby -e, perl -e, php -r, lua -e e osascript -e richiedono reviewer o approvazione esplicita. In mode=auto, il normale percorso di approvazione exec può consentire all’auto reviewer nativo di permettere un comando una tantum chiaramente a basso rischio; le chiamate dirette system.run su host node richiedono comunque un’approvazione esplicita perché non possono consegnare il comando a un percorso di approvazione umano. Se il reviewer lo chiede, la richiesta va a un essere umano. allow-always può comunque rendere persistenti invocazioni benigne di interpreti/script, ma le forme inline-eval non diventano regole allow durevoli.
• tools.exec.commandHighlighting (predefinito: false): quando true, i prompt di approvazione possono evidenziare nel testo del comando gli intervalli di comando derivati dal parser. Impostalo a true globalmente o per agent per abilitare l’evidenziazione del testo del comando senza cambiare 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 di 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 safe bin (minPositional, maxPositional, allowedValueFlags, deniedFlags).

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

​

Gestione di PATH

• host=gateway: unisce il PATH della tua login-shell nell’ambiente exec. Le sostituzioni env.PATH sono rifiutate 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
    • Per impedire alla configurazione shell dell’utente (come ~/.zshenv o /etc/zshenv) di sovrascrivere percorsi prioritari durante l’avvio, le voci tools.exec.pathPrepend vengono anteposte in modo sicuro al PATH finale dentro il comando shell subito prima dell’esecuzione.
• host=sandbox: esegue sh -lc (login shell) 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 le sostituzioni env non bloccate che passi vengono inviate al node. Le sostituzioni env.PATH sono rifiutate per l’esecuzione host e ignorate 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.

openclaw config get agents.list
openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"

​

Sostituzioni di sessione (/exec)

/exec host=auto security=allowlist ask=on-miss node=mac-1

​

Modello di autorizzazione

​

Approvazioni exec (app companion / host Node)

​

Allowlist + bin sicuri

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

​

Esempi

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

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

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

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

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​

apply_patch

{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
    },
  },
}

• Disponibile solo per 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

• Approvazioni exec — gate di approvazione per comandi shell
• Sandboxing — esecuzione di comandi in ambienti in sandbox
• Processo in background — exec a lunga esecuzione e strumento process
• Sicurezza — policy degli strumenti e accesso elevato