Run Shell Commands with OpenClaw Exec Tool

Ever felt the frustration of an AI agent that can’t actually do anything in your workspace? You give it a task, and it just hallucinates code instead of running it. We’ve all been there, stuck between wanting automation and worrying about system safety.

The Exec tool is the answer. It lets you run shell commands directly in your workspace, supporting both foreground and background execution. If you’re looking to bridge the gap between AI reasoning and actual terminal action, this is how you do it.

Parameters

The exec tool is flexible. Here is what you can pass to it:

• 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 (auto | 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): request elevated mode (gateway host); security=full is only forced when elevated resolves to full

Notes:

• host defaults to auto: sandbox when sandbox runtime is active for the session, otherwise gateway.
• elevated forces host=gateway; it is only available when elevated access is enabled for the current session/provider.
• gateway/node approvals are controlled by ~/.openclaw/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.
• exec host=node is the only shell-execution path for nodes; the legacy nodes.run wrapper has been removed.
• On non-Windows hosts, exec uses SHELL when set; if SHELL is fish, it prefers bash (or sh) from PATH to avoid fish-incompatible scripts, then falls back to SHELL if neither exists.
• On Windows hosts, exec prefers PowerShell 7 (pwsh) discovery (Program Files, ProgramW6432, then PATH), then falls back to Windows PowerShell 5.1.
• Host execution (gateway/node) rejects env.PATH and loader overrides (LD_*/DYLD_*) to prevent binary hijacking or injected code.
• OpenClaw sets OPENCLAW_SHELL=exec

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

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

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

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

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