Using the OpenClaw Exec Tool

The exec tool is one of OpenClaw's most powerful capabilities, allowing you to run shell commands directly within your workspace or on connected systems. It bridges the gap between conversational AI and actual system operations, enabling true automation from within your agent workflows.

What exec Does

At its core, exec executes shell commands. Whether you need to list files, run build scripts, deploy applications, or interact with system services, exec gives you direct access to the command line from within OpenClaw. This transforms your AI assistant from a passive responder into an active operator capable of making changes and taking actions.

Basic Usage

The simplest form of exec requires only a command:

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

This runs ls -la in the current working directory and returns the output. The command executes synchronously by default, meaning OpenClaw waits for it to complete before proceeding.

Background Execution

For longer-running processes, you can run commands in the background:

{"tool": "exec", "command": "npm run build", "yieldMs": 1000}

Setting yieldMs tells OpenClaw to wait 1000ms (1 second) before backgrounding the process. Once backgrounded, you can monitor it using the process tool:

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

Process Control

When you have a background process running, several control options are available:

• Poll status: Check if the process is still running
• Send keys: Send keyboard input (e.g., {"keys":["C-c"]} to send Ctrl+C)
• Submit: Send a carriage return (Enter)
• Paste: Insert text into the process input
• Kill: Terminate the process

Security Model

Security is paramount when executing system commands. OpenClaw implements multiple layers of protection:

• Sandboxing: By default, exec runs in a restricted environment
• Host execution: For gateway or node access, explicit approvals may be required
• Allowlists: Commands can be restricted to an approved list of binaries
• Path validation: Only resolved binary paths are allowed in restricted modes

The security model prevents dangerous operations like binary hijacking through PATH manipulation or loading injected code via environment variables.

Advanced Features

Pseudo-Terminal (PTY)

Some command-line applications require an interactive terminal. Set pty: true to run in a pseudo-terminal:

{"tool": "exec", "command": "vim", "pty": true}

This enables full terminal UI applications to run and be controlled programmatically.

Environment Variables

You can pass custom environment variables:

{"tool": "exec", "command": "echo $MY_VAR", "env": {"MY_VAR": "hello"}}

Note that for security reasons, certain environment variables (like PATH overrides and dynamic loader settings) are rejected when executing on the host system.

Working Directory

Change the execution context with workdir:

{"tool": "exec", "command": "pwd", "workdir": "/tmp"}

Common Use Cases

1. Development workflows: Run tests, builds, and deployments
2. System monitoring: Check service status, disk space, or network conditions
3. Automation scripts: Execute custom scripts for repetitive tasks
4. Data processing: Run data transformation pipelines
5. CI/CD integration: Trigger deployment workflows

Best Practices

• Start with simple commands to understand the execution context
• Use background execution for anything that might take more than a few seconds
• Monitor long-running processes with process poll
• Test commands in your shell first, then translate to exec format
• Be cautious with destructive commands (rm, mv, etc.) - consider using trash instead of rm
• Use the allowlist model in production environments to restrict executable binaries

The exec tool transforms OpenClaw from a conversational interface into a full system automation platform. With proper security controls in place, it enables powerful workflows that bridge the gap between natural language instructions and system-level actions.