Tools & Automation10 min readIntermediate

Full System Access

Read and write files, run shell commands, execute scripts. Full access or sandboxed—your choice

What You'll Learn

  • Core concepts and capabilities of the Exec tool
  • How to run shell commands in foreground and background
  • Three host modes: sandbox, gateway, and node
  • Security modes and approval mechanisms
  • Configuration options and session overrides
  • apply_patch experimental feature

Table of Contents

Exec Tool Overview

The Exec tool enables AI agents to run shell commands in the workspace. Supports foreground and background execution, pseudo-terminal (PTY) mode, and flexible security control. Choose full access or sandboxed execution—it's up to you.

Read & Write Files

Access and modify arbitrary files via filesystem commands

Shell Commands

Run arbitrary shell commands and scripts

Sandbox Isolation

Optional containerized isolation for security

Parameters

The Exec tool supports the following parameters:

command (required)

The shell command to execute

workdir

Working directory (defaults to cwd)

env

Environment variable overrides (key/value pairs)

yieldMs (default 10000)

Auto-background after delay

background (boolean)

Background immediately

timeout (seconds, default 1800)

Kill on expiry

pty (boolean)

Run in a pseudo-terminal when available (for 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 (boolean)

Request elevated mode (gateway host); security=full is only forced when elevated resolves to full

Configuration Options

Konfigurieren Sie das Exec-Tool-Verhalten über ~/.openclaw/openclaw.json:

~/.openclaw/openclaw.json

tools:
  exec:
    notifyOnExit: true
    approvalRunningNoticeMs: 10000
    host: "sandbox"
    security: "deny"
    ask: "on-miss"
    pathPrepend: ["~/bin", "/opt/oss/bin"]
    safeBins: ["ls", "cat", "echo"]
tools.exec.notifyOnExit (default: true)

When true, backgrounded exec sessions enqueue a system event and request a heartbeat on exit

tools.exec.approvalRunningNoticeMs (default: 10000)

Emit a single "running" notice when an approval-gated exec runs longer than this (0 disables)

tools.exec.host (default: sandbox)

Default execution host mode

tools.exec.security (default: deny for sandbox, allowlist for gateway + node when unset)

Default security mode

tools.exec.ask (default: on-miss)

Default approval behavior

tools.exec.node (default: unset)

Default node selection

tools.exec.pathPrepend

List of directories to prepend to PATH for exec runs

tools.exec.safeBins

Stdin-only safe binaries that can run without explicit allowlist entries

Host Modes

The Exec tool supports three execution locations, each with different security characteristics and use cases:

sandbox

Sandbox

Run in an isolated container with maximum security

  • •Default mode, no approvals required
  • •Filesystem access restricted
  • •Network access controlled
  • •Ideal for untrusted agents and automation tasks
gateway

Gateway

Execute directly on the Gateway host machine

  • •Requires explicit approval (unless configured with security=full)
  • •Full system access
  • •Can access all files and commands
  • •Suitable for tasks requiring complete control
node

Node

Execute on a paired node device

  • •Requires a paired node (companion app or headless node host)
  • •Supports multiple node selection
  • •Useful for remote execution and cross-device operations
  • •Security mode controlled by node configuration

Security Mechanisms

Security Modes

deny

Deny all command execution (strictest, for high security requirements)

allowlist

Only allow commands in the allowlist (balance between security and flexibility)

full

Allow all command execution (only for fully trusted agents)

Approval Mechanism

Sandboxed agents can require per-request approval before exec runs on the gateway or node host. Approvals policy stored in ~/.openclaw/exec-approvals.json.

  • When approvals are required, the exec tool returns immediately with status: "approval-pending" and an approval id
  • Once approved (or denied / timed out), the Gateway emits system events (Exec finished / Exec denied)
  • If the command runs longer than tools.exec.approvalRunningNoticeMs, a single Exec running notice is emitted
  • Manage approval lists in the companion app or node host UI

Important Note

Sandboxing is off by default. If sandboxing is off, host=sandbox runs directly on the gateway host (no container) and does not require approvals. To require approvals, run with host=gateway and configure exec approvals (or enable sandboxing).

Usage Examples

Common use cases for the Exec tool:

Foreground Execution

Run command directly and wait for completion

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

Background + Poll

Start long-running task and check status

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

Send Keys (tmux-style)

Interact with background processes

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

Send enter key

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

Paste (bracketed by default)

Paste multi-line text

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

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.

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

/exec is only honored for authorized senders (channel allowlists/pairing plus commands.useAccessGroups). It updates session state only and does not write config. To hard-disable exec, deny it via tool policy.

Apply Patch (Experimental)

Experimental Feature

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

tools:
  exec:
    applyPatch:
      enabled: true
      allowModels: ["gpt-5.2"]
Only available for OpenAI/OpenAI Codex models
Tool policy still applies; allow: ["exec"] implicitly allows apply_patch
Config lives under tools.exec.applyPatch
Useful for batch file edits and code refactoring

Continue Learning

The Exec tool is just one of OpenClaw's powerful features. Explore more tutorials and documentation:

View All TutorialsVisit Official Docs