Exec tool

Run shell commands in the workspace. Supports foreground + background execution via process. If process is disallowed, exec runs synchronously and ignores yieldMs/background. Background sessions are scoped per agent; process only sees sessions from the same agent.

Parameters

command (required)
workdir (defaults to cwd)
env (key/value overrides)
yieldMs (default 10000): auto-background after delay
background (bool): background immediately
timeout (seconds, default 1800): kill on expiry
pty (bool): run in a pseudo-terminal when available (TTY-only CLIs, coding agents, terminal UIs)
host (sandbox | gateway | node): where to execute
security (deny | allowlist | full): enforcement mode for gateway/node
ask (off | on-miss | always): approval prompts for gateway/node
node (string): node id/name for host=node
elevated (bool): alias for host=gateway + security=full when sandboxed and allowed

Notes:

host defaults to sandbox.
elevated is ignored when sandboxing is off (exec already runs on the host).
gateway/node approvals are controlled by ~/.clawdbot/exec-approvals.json.
node requires a paired node (companion app or headless node host).
If multiple nodes are available, set exec.node or tools.exec.node to select one.

Config

tools.exec.notifyOnExit (default: true): when true, backgrounded exec sessions enqueue a system event and request a heartbeat on exit.
tools.exec.host (default: sandbox)
tools.exec.security (default: deny)
tools.exec.ask (default: on-miss)
tools.exec.node (default: unset)

Per-agent node binding (use the agent list index in config):

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

Session overrides (`/exec`)

Use /exec to set per-session defaults for host, security, ask, and node. Send /exec with no arguments to show the current values.

Example:

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

Exec approvals (companion app / node host)

Sandboxed agents can require per-request approval before exec runs on the gateway or node host. See Exec approvals for the policy, allowlist, and UI flow.

Examples

Foreground:

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

Background + poll:

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

Send keys (tmux-style):

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

Submit (send CR only):

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

Paste (bracketed by default):

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

apply_patch (experimental)

apply_patch is a subtool of exec for structured multi-file edits. Enable it explicitly:

{
  tools: {
    exec: {
      applyPatch: { enabled: true, allowModels: ["gpt-5.2"] }
    }
  }
}