How to Use the Exec Tool in Openclaw: A Complete Guide
The exec tool is one of Openclaw's most powerful features, allowing your AI agents to execute shell commands directly on the host system. Whether you need to run build scripts, check system status, or automate workflows, mastering the exec tool unlocks the full potential of your self-hosted AI gateway.
For developers looking to enhance their Openclaw setup, you might also want to explore Elevated Mode Openclaw for advanced permissions, or learn about Exec Approvals Openclaw to add security layers to your command execution.
Key Tool Parameters
When the agent calls the exec tool, it can pass several parameters to control execution:
- command (required): The shell command to execute.
- workdir: The working directory (defaults to the agent's current workspace).
- env: An array of key/value pairs to override environment variables.
- pty: Set to true to run the command in a pseudo-terminal (useful for TTY-only CLIs or terminal UIs).
- timeout: Time in seconds before the process is killed (defaults to 1800).
Standard Foreground Run
The most common use case is executing a command and waiting for the result:
{ "tool": "exec", "command": "ls -la" }
This runs the command synchronously and returns the output to the agent.
Background Run and Poll
For long-running tasks, use background execution with polling:
{"tool":"exec", "command":"npm run build", "yieldMs":1000}
Then poll for status:
{"tool":"process", "action":"poll", "sessionId":"<id>"}
Interactive Prompts
Send keys or paste text into running processes:
{"tool":"process", "action":"send-keys", "sessionId":"<id>", "keys":["Enter"]}
Or paste multiple lines:
{"tool":"process", "action":"paste", "sessionId":"<id>", "text":"line1\nline2\n"}
Best Practices and Troubleshooting
- Always set timeouts for commands that might hang.
- Use workdir to ensure commands run in the correct directory.
- Enable pty only when needed for interactive applications.
- Review command output before acting on it—AI can misinterpret results.
- Combine with exec approvals for sensitive operations.
The exec tool transforms Openclaw from a passive chat interface into an active system administrator. Use it wisely, and your AI agents will handle complex DevOps tasks with minimal supervision.
