How to Use OpenClaw apply_patch Tool

The apply_patch tool is the cleanest way to make structured file changes from an OpenClaw agent. It is not a shell trick and it is not a vague instruction to edit something later. The tool accepts a full patch block with add, update, delete, and move operations, which makes it a good fit when a change touches multiple files or several hunks in one file. I use it when I want the edit to be reviewable before it lands, especially in a workspace where exact-text replacements would be fragile.

30-second answer

Use apply_patch when the agent already knows the desired diff and needs to apply it deterministically. The patch must be wrapped with Begin Patch and End Patch markers, and every file operation is explicit. A simple update hunk removes the old line and adds the new line. Add File creates a new file, Delete File removes one, and Move to handles renames from inside an update block. After applying a patch, run the smallest meaningful verification step before claiming success.

Where it fits

OpenClaw exposes both exact replacement editing and patch-based editing. Exact replacement is excellent for a small unique block. apply_patch is better for multi-file work, generated files, renames, or related hunks that should succeed or fail as one unit. It also gives humans a familiar review shape: the patch itself explains what changed without requiring a long narrative.

Docs-grounded facts

• The tool accepts one input string containing the full structured patch.
• Supported operations include Add File, Update File, Delete File, and Move to.
• Patch paths may be relative to the workspace or absolute.
• tools.exec.applyPatch.workspaceOnly defaults to workspace-contained behavior.
• Configuration for apply_patch lives under tools.exec.
• The docs recommend apply_patch for multi-file or multi-hunk edits.

Set it up deliberately

Keep paths relative to the workspace unless you have a specific reason to use an absolute path. The docs say tools.exec.applyPatch.workspaceOnly defaults to true, which keeps patch writes contained. If a patch needs to cross that boundary, treat it as a deliberate policy decision, not a convenience flag. For generated changes, inspect the target file first, build a small patch, then verify with git diff, a build, a test, or direct file inspection.

Use it safely

Do not use apply_patch as a way to hide uncertainty. If the agent has not inspected the current file, a patch can delete the wrong hunk just as confidently as it can fix one. Avoid giant unrelated patches; group changes by logical purpose. Keep delete operations especially obvious. When a patch fails, re-read the current file instead of guessing at line numbers from memory.

Common mistakes

The common mistake is treating patch syntax as a loose markdown diff. It is stricter than that: the tool expects the Begin Patch and End Patch wrapper and file-operation headers. Another mistake is using patch edits for one tiny string replacement when the edit tool would be safer. The reverse mistake is worse: trying to coordinate five nearby exact replacements when one patch would show the whole intent cleanly.

Verification checklist

After the patch lands, check that the file changed exactly once, that any moved file is no longer present at the old path, and that the project-specific validation still passes. For code, that usually means a targeted test or build. For docs, it may be a link check or a direct readback. The verification should match the risk of the patch, not the size of the prompt.

Playbook angle

The OpenClaw Playbook treats patching as an operator habit: inspect, patch, verify, summarize. That rhythm keeps agents from becoming magical file mutators with no audit trail. If your team is letting OpenClaw touch production repos, make apply_patch part of the normal code-change runbook rather than an emergency-only tool.