Chapter 3: File & Code Automation

Files are the connective tissue of any automation system—every pipeline stores state between runs, passes data between components, logs activity, and accepts configuration through files. OpenClaw provides three primary file tools: read (with offset/limit for large files and image support via vision), write (creates or overwrites, auto-creates parent directories), and edit (precise surgical replacements using exact oldText/newText matching). The exec tool is where automation gets real—it runs arbitrary shell commands, chained pipelines, and scripts. For long-running commands, use background: true with yieldMs to background the process and monitor it via the process tool, which supports list, poll, log, write, send-keys, and kill actions.

Shell commands are the backbone of batch automation: finding files with find, iterating with for loops, processing CSVs with jq or Python scripts, and chaining with pipes. The security option on exec controls permissions—deny blocks, allowlist limits to approved commands, and full gives no restrictions. Running with elevated: true uses root permissions and should be reserved for specific trusted commands. The exec tool also respects the workspace as its working directory, so ls from exec lists workspace contents. For code generation, the pattern is: describe what the script should do, the agent generates it, then you make it executable with chmod +x and run it.

Batch operations unlock automation at scale—processing all markdown files modified in the last 7 days, parsing CSV data in chunks of 1000 rows, transforming JSON with jq or Python. Pipelines are built by composing these patterns: a sales report pipeline might fetch a CSV each morning via cron, run a Python script that transforms it to markdown summary, and save it to a distribution folder. The critical rule: always test pipelines manually before automating them with cron. Troubleshooting focuses on path issues ("File not found"), permission issues (chmod +x), exact whitespace matching in edit, and timeout handling for large files via background processes. Binary files (PDFs, executables) should be handled via shell commands, not the read tool.

Key Patterns

• **read/write/edit trio:** read (with offset/limit for large files), write (full overwrite), edit (precise oldText/newText replacement)
• **exec with background:** `background: true` + `yieldMs` for long commands; monitor with `process` tool
• **Security layering:** Default to `security: "allowlist"`; reserve `security: "full"` for specific trusted commands
• **Batch via shell:** `find`, `for` loops, `jq` for JSON, Python with chunked CSV reading for large datasets
• **Test before cron:** Always run the full pipeline manually before scheduling it

Related Concepts

• [[kelly-handbook-ch6-cron]] for scheduling file pipelines with cron jobs
• [[kelly-handbook-ch2-architecture]] for understanding the tool architecture and security model
• [[kelly-handbook-ch5-communication-automation]] for routing pipeline results via WhatsApp or other channels
• [[kelly-tweets-openclaw]] for practical OpenClaw shell and file patterns