Naar hoofdinhoud gaan

​
Exec-tool

Voer shellopdrachten uit in de werkruimte. Ondersteunt uitvoering op de voorgrond en achtergrond via process. Als process niet is toegestaan, wordt exec synchroon uitgevoerd en worden yieldMs/background genegeerd. Achtergrondsessies zijn per agent afgebakend; process ziet alleen sessies van dezelfde agent.

​
Parameters

  • command (vereist)
  • workdir (standaard naar cwd)
  • env (key/value-overschrijvingen)
  • yieldMs (standaard 10000): automatisch naar achtergrond na vertraging
  • background (bool): direct naar achtergrond
  • timeout (seconden, standaard 1800): beëindigen bij verlopen
  • pty (bool): uitvoeren in een pseudo-terminal wanneer beschikbaar (TTY-only CLI’s, coding agents, terminal-UI’s)
  • host (sandbox | gateway | node): waar uitvoeren
  • security (deny | allowlist | full): afdwingingsmodus voor gateway/node
  • ask (off | on-miss | always): goedkeuringsprompts voor gateway/node
  • node (string): node-id/naam voor host=node
  • elevated (bool): verzoek om verhoogde modus (Gateway-host); security=full wordt alleen afgedwongen wanneer verhoogd oplossen resulteert in full
Notities:
  • host is standaard sandbox.
  • elevated wordt genegeerd wanneer sandboxing uit staat (exec draait al op de host).
  • Goedkeuringen voor gateway/node worden aangestuurd door ~/.openclaw/exec-approvals.json.
  • node vereist een gekoppelde node (Companion-app of headless node-host).
  • Als meerdere nodes beschikbaar zijn, stel exec.node of tools.exec.node in om er één te selecteren.
  • Op niet-Windows-hosts gebruikt exec SHELL wanneer ingesteld; als SHELL fish is, geeft het de voorkeur aan bash (of sh) uit PATH om fish-incompatibele scripts te vermijden, en valt daarna terug op SHELL als geen van beide bestaat.
  • Hostuitvoering (gateway/node) weigert env.PATH en loader-overschrijvingen (LD_*/DYLD_*) om binaire kaping of geïnjecteerde code te voorkomen.
  • Belangrijk: sandboxing staat standaard uit. Als sandboxing uit staat, wordt host=sandbox direct uitgevoerd op de Gateway-host (geen container) en vereist geen goedkeuringen. Om goedkeuringen te vereisen, voer uit met host=gateway en configureer exec-goedkeuringen (of schakel sandboxing in).

​
Configuratie

  • tools.exec.notifyOnExit (standaard: true): wanneer true, plaatsen exec-sessies in de achtergrond een systeemgebeurtenis in de wachtrij en vragen ze een heartbeat bij afsluiten.
  • tools.exec.approvalRunningNoticeMs (standaard: 10000): emitteert één enkele “running”-melding wanneer een exec met goedkeuringsvereiste langer duurt dan dit (0 schakelt uit).
  • tools.exec.host (standaard: sandbox)
  • tools.exec.security (standaard: deny voor sandbox, allowlist voor Gateway + node wanneer niet ingesteld)
  • tools.exec.ask (standaard: on-miss)
  • tools.exec.node (standaard: niet ingesteld)
  • tools.exec.pathPrepend: lijst met mappen die voorafgaand aan PATH worden toegevoegd voor exec-runs.
  • tools.exec.safeBins: stdin-only veilige binaries die zonder expliciete allowlist-items mogen draaien.
Voorbeeld: 
{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

​
PATH-afhandeling

  • host=gateway: voegt de PATH van je login-shell samen in de exec-omgeving. Overschrijvingen van env.PATH worden geweigerd bij hostuitvoering. De daemon zelf draait nog steeds met een minimale PATH:
    • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
    • Linux: /usr/local/bin, /usr/bin, /bin
  • host=sandbox: voert sh -lc (login-shell) uit binnen de container, waardoor /etc/profile PATH kan resetten. OpenClaw voegt env.PATH toe na het sourcen van profielen via een interne env-var (geen shell-interpolatie); tools.exec.pathPrepend is hier ook van toepassing.
  • host=node: alleen niet-geblokkeerde env-overschrijvingen die je doorgeeft, worden naar de node verzonden. env.PATH-overschrijvingen worden geweigerd voor hostuitvoering en genegeerd door node-hosts. Als je extra PATH-vermeldingen nodig hebt op een node, configureer dan de serviceomgeving van de node-host (systemd/launchd) of installeer tools op standaardlocaties.
Per-agent nodebinding (gebruik de agentlijst-index in de config): 
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
Besturings-UI: het tabblad Nodes bevat een klein paneel “Exec node binding” voor dezelfde instellingen.

​
Sessie-overschrijvingen (/exec)

Gebruik /exec om per sessie standaardwaarden in te stellen voor host, security, ask en node. Verzend /exec zonder argumenten om de huidige waarden te tonen. Voorbeeld: 
/exec host=gateway security=allowlist ask=on-miss node=mac-1

​
Autorisatiemodel

/exec wordt alleen gehonoreerd voor geautoriseerde afzenders (kanaal-allowlists/koppeling plus commands.useAccessGroups). Het werkt alleen de sessiestatus bij en schrijft geen config. Om exec hard uit te schakelen, weiger het via toolbeleid (tools.deny: ["exec"] of per agent). Host-goedkeuringen blijven van toepassing tenzij je expliciet security=full en ask=off instelt.

​
Exec-goedkeuringen (Companion-app / node-host)

Gesandboxde agents kunnen per verzoek goedkeuring vereisen voordat exec op de Gateway- of node-host wordt uitgevoerd. Zie Exec approvals voor het beleid, de allowlist en de UI-flow. Wanneer goedkeuringen vereist zijn, retourneert de exec-tool onmiddellijk met status: "approval-pending" en een goedkeurings-id. Zodra goedgekeurd (of geweigerd / verlopen), zendt de Gateway systeemgebeurtenissen uit (Exec finished / Exec denied). Als de opdracht nog draait na tools.exec.approvalRunningNoticeMs, wordt één enkele Exec running-melding uitgezonden.

​
Allowlist + veilige bins

Allowlist-handhaving matcht alleen opgeloste binaire paden (geen basenaam-matches). Wanneer security=allowlist, worden shellopdrachten automatisch toegestaan alleen als elk pijplijnsegment op de allowlist staat of een veilige bin is. Chaining (;, &&, ||) en redirects worden geweigerd in allowlist-modus tenzij elk topniveau-segment voldoet aan de allowlist (inclusief safe bins). Redirects blijven niet ondersteund.

​
Voorbeelden

Voorgrond: 
{ "tool": "exec", "command": "ls -la" }
Achtergrond + poll: 
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
Toetsen verzenden (tmux-stijl): 
{"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"]}
Verzenden (alleen CR verzenden): 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
Plakken (standaard bracketed): 
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​
apply_patch (experimenteel)

apply_patch is een subtool van exec voor gestructureerde bewerkingen over meerdere bestanden. Schakel het expliciet in: 
{
  tools: {
    exec: {
      applyPatch: { enabled: true, allowModels: ["gpt-5.2"] },
    },
  },
}
Notities:
  • Alleen beschikbaar voor OpenAI/OpenAI Codex-modellen.
  • Toolbeleid blijft van toepassing; allow: ["exec"] staat impliciet apply_patch toe.
  • Configuratie bevindt zich onder tools.exec.applyPatch.
  • tools.exec.applyPatch.workspaceOnly staat standaard op true (beperkt tot de workspace). Zet dit alleen op false als je er bewust voor kiest dat apply_patch buiten de workspace-directory mag schrijven/verwijderen.