# Exec Tool Documentation

## Overview

The Exec Tool allows agents to execute shell commands in a workspace, supporting both foreground and background execution modes through the `process` parameter.

## Key Parameters

The tool accepts several configuration options:

- **command** (required): The shell command to execute
- **workdir**: Working directory (defaults to current)
- **env**: Environment variable overrides
- **yieldMs**: auto-background after delay (default 10000ms)
- **background**: Immediate background execution option
- **timeout**: Command termination threshold (default 1800 seconds)
- **pty**: Pseudo-terminal mode for TTY-dependent applications
- **host**: Execution location—sandbox, gateway, or node
- **security**: Enforcement mode with deny, allowlist, or full options
- **ask**: Approval prompts controlled via on-miss, always, or off settings

## Execution Hosts

The tool supports three execution contexts:

1. **Sandbox** (default): Container-based execution
2. **Gateway**: Host machine execution with approval controls
3. **Node**: Remote paired device execution

## Important Security Notes

Sandboxing is **off by default** and `host=sandbox` runs directly on the gateway host (no container) and **does not require approvals**.

To enforce approval requirements, configure `host=gateway` with appropriate security policies via `~/.openclaw/exec-approvals.json`.

## Session Management

The `/exec` command sets per-session defaults for host, security, approval mode, and node binding without writing permanent configuration changes.
