Using the Exec Tool for Command Execution in OpenClaw

The exec tool is one of OpenClaw's most powerful features, enabling agents to run shell commands directly within the workspace environment. Whether you're automating builds, processing files, or integrating with external CLIs, exec provides the low-level access needed to extend OpenClaw's capabilities beyond built-in tooling.

How exec Works

exec allows agents to execute arbitrary shell commands in the current workspace. By default, commands run synchronously, but exec also supports background execution with polling via the process tool. This makes it ideal for long-running tasks like deployments, data processing, or interactive terminal applications.

Key Parameters

• command (required): The shell command to execute.
• workdir: Sets the working directory (defaults to current directory).
• env: Pass environment variable overrides.
• yieldMs: Automatically background the process after the specified delay (default: 10,000ms).
• background: Run immediately in the background.
• timeout: Kill the process if it exceeds the specified seconds (default: 1800).
• pty: Use a pseudo-terminal (TTY) for interactive CLIs (e.g., vim, htop, coding agents).
• host: Target execution environment (sandbox, gateway, or node).
• security: Enforcement mode (deny, allowlist, full).
• ask: Approval behavior (off, on-miss, always).
• elevated: Request elevated permissions (when allowed).

Execution Context

By default, exec runs in the local sandbox environment. For security, host-level execution (gateway or node) may require approval based on your OpenClaw configuration. When approvals are enabled, the system will pause and prompt for consent before running sensitive commands.

Common Use Cases

Running Simple Commands

For quick file operations or system checks:

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

This lists all files in the current directory.

Background Processing

For long-running tasks like builds or deployments:

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

After yielding, use process to poll status:

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

Interactive Terminal Applications

To run TTY-requiring tools like text editors or REPLs, enable pty:

{
  "tool": "exec",
  "command": "vim script.js",
  "pty": true
}

Once running, you can interact using process commands like send-keys, paste, or submit.

Process Control

Use the process tool to manage backgrounded exec sessions:

• poll: Check running status and output.
• log: Retrieve full output (with offset/limit).
• send-keys: Send key sequences (e.g., ["C-c"] for Ctrl+C).
• paste: Insert text (bracketed mode by default).
• submit: Send a carriage return.
• kill: Terminate the process.

Example — Sending an interrupt:

{
  "tool": "process",
  "action": "send-keys",
  "sessionId": "<id>",
  "keys": ["C-c"]
}

Security Considerations

exec is powerful but comes with risks. OpenClaw provides several safeguards:

• Approval workflows: Host-level execution can require manual approval.
• Allowlists: Restrict which binaries can be executed.
• Safe bins: Define stdin-only tools (like cat) that don’t need explicit allowlisting.
• Sandboxing: Isolate commands in a restricted environment.

Always follow the principle of least privilege. Only grant exec access when necessary, and use allowlist mode in production environments.

Configuration

You can customize exec behavior globally or per-session:

• tools.exec.notifyOnExit: Send a system event when background processes complete (default: true).
• tools.exec.approvalRunningNoticeMs: After this delay, emit a notice if an approved exec is still running (default: 10,000ms).
• tools.exec.host: Default execution target.
• tools.exec.security: Default security mode.
• tools.exec.pathPrepend: Add directories to PATH for exec runs.

Use /exec in chat to override settings per session:

/exec host=gateway security=allowlist ask=on-miss

Best Practices

1. Prefer built-in tools when available (e.g., read, write, web_fetch).
2. Use backgrounding for anything longer than a few seconds.
3. Set timeouts to prevent hangs.
4. Log output for debugging and audit trails.
5. Test locally before deploying to production.

The exec tool turns OpenClaw into a full-stack automation platform. Used responsibly, it unlocks the ability to orchestrate complex workflows across your entire development and operations stack.

Published on ClawMakers.com — Empowering OpenClaw Builders