Exec Tool

Type: OpenClaw shell command execution tool

Definition

The exec tool is OpenClaw's interface for running arbitrary shell commands — the most powerful and most dangerous tool in the arsenal. It runs commands in a shell context, supports chained pipelines, background execution with background: true, and respects a security setting that controls whether commands run freely, require allowlist approval, or are denied entirely. The security: "allowlist" mode is the recommended default for most automation setups, requiring explicit user approval for each shell command.

How It Works

The exec tool accepts a command string (shell command to run), optional background: true for long-running processes, optional elevated: true for root permissions, optional security mode (deny/allowlist/full), optional workdir to set working directory, and optional yieldMs to control when the process is backgrounded.

For long-running commands: use background: true with yieldMs (milliseconds before backgrounding). Monitor via the process tool which supports list, poll, log, write, send-keys, kill. This is how batch jobs, compilation, and large data processing work in OpenClaw.

For pipelines: chain commands with |, &&, || just like in a normal shell. find . -name "*.md" -mtime -7 finds files, jq transforms JSON, Python scripts process data.

The security model is critical. security: "full" gives no restrictions — any command runs. security: "allowlist" requires user confirmation for each execution. security: "deny" blocks the tool entirely. For most automation setups, default to allowlist and use full only for specific trusted commands where the overhead of approval isn't worth it.

The exec tool respects the workspace as its working directory by default — ls from exec lists workspace contents. Binary files (PDFs, executables) should be handled via exec, not the read tool.

Key Properties

  • Arbitrary shell execution — run any command, chain pipelines, invoke scripts
  • Background execution — background: true + yieldMs for long processes; monitor via process tool
  • Three security modes — deny (blocked), allowlist (confirmation required), full (no restrictions)
  • Allowlist recommended default — most setups should require approval for shell commands
  • Elevated mode — elevated: true uses root permissions; reserve for specific trusted commands
  • Workspace working directory — exec defaults to workspace root; ls lists workspace contents
  • tool-policy-gating — tool policy gating is how exec security mode is configured in openclaw.json
  • simple-pipeline — exec is the primary tool for running pipeline process steps
  • git-automation — git commands (commit, push, status) run via exec

Source Chapters