File Writer Safe

File Writer

Safe file writing strategy for large files to avoid truncation issues.

When to Use

Problem Analysis

Why Files Get Truncated

Large file writes can fail due to:

1. Tool limitations - write tool may have byte limits per operation 2. Network limits - Large file transfers may be truncated during transmission 3. System limits - OpenClaw may have size limits on single operations

Safe Size Thresholds

| Operation | Safe Size | Risk Level | |-----------|------------|-------------| | write new file | < 2000 bytes | ✅ Safe | | write new file | 2000-5000 bytes | ⚠️ Moderate | | write new file | > 5000 bytes | ❌ High risk | | edit modification | < 500 bytes | ✅ Safe | | edit modification | 500-1000 bytes | ⚠️ Moderate | | edit modification | > 1000 bytes | ❌ High risk |

Safe Writing Strategy

Step 1: Read Current State

Before making changes, read the current file state:

# Read the file to understand current structure
read /path/to/file.md
For large files, read specific sections
read /path/to/file.md --offset 100 --limit 50

Purpose:

For small to medium changes, use edit tool:

Use edit tool with:
oldText: Exact text to replace (must match exactly)

newText: New text to replace with

file_path: Path to the file

Best Practices:

Step 3: Verify Results

After each modification, verify the result:

# Check file line count
wc -l /path/to/file.md
Read modified section
read /path/to/file.md --offset  --limit 
Verify file ends correctly
read /path/to/file.md --offset -10

Success Criteria:

If write tool fails for large content:

Split content into chunks:
1. Write first chunk (header + section 1)
2. Verify and append section 2
3. Verify and append section 3
4. Continue until complete

Strategy 2: Use Unique Markers

For complex modifications, use unique markers:

In source file:

[existing content]
Edit operation:
oldText: "\n[existing content]\n"
newText: "\n[new content]\n"

Strategy 3: Incremental Build

For creating new large files:

1. Create file with basic structure
2. Add sections one by one using edit
3. Verify after each addition
4. Final verification

Strategy 4: Backup and Restore

For critical file modifications:

# Create backup before modification
cp /path/to/file.md /path/to/file.md.backup
Attempt modification
... (write or edit operation)
If modification fails, restore
cp /path/to/file.md.backup /path/to/file.md

Error Recovery

Edit Tool Fails

Symptom: "Could not find exact text in file"

Causes:

1. Re-read the file to get exact content 2. Use unique markers for large sections 3. Match whitespace exactly (copy from file read) 4. Use smaller oldText` for more precise matching

Write Tool Truncates

Symptom: File ends abruptly or is incomplete

Solutions:

1. Use edit tool instead of write 2. Split content into smaller chunks 3. Write incrementally (section by section) 4. Verify file size after each operation

File Corruption

Symptom: File has syntax errors or invalid content

Solutions:

1. Restore from backup 2. Re-read and re-verify 3. Use incremental build strategy 4. Validate syntax after each modification

Examples

Example 1: Adding Section to Large File

Step 1: Read file to find insertion point
read /path/to/large-file.md --offset 50 --limit 10
Step 2: Use edit to add new section
edit:
  file_path: /path/to/large-file.md
  oldText: "## Existing Section\n\nContent here"
  newText: "## Existing Section\n\nContent here\n\n## New Section\n\nNew content"
Step 3: Verify
read /path/to/large-file.md --offset 50 --limit 20

Example 2: Creating Large New File

Step 1: Create basic structure
write:
  file_path: /path/to/new-file.md
  content: "# Title\n\n## Section 1\n\nContent 1"
Step 2: Add sections incrementally
edit:
  file_path: /path/to/new-file.md
  oldText: "Content 1"
  newText: "Content 1\n\n## Section 2\n\nContent 2"
Step 3: Verify
wc -l /path/to/new-file.md

Example 3: Replacing Large Section

Step 1: Read file to find exact text
read /path/to/file.md
Step 2: Use unique markers
edit:
  file_path: /path/to/file.md
  oldText: "\n[old content]\n"
  newText: "\n[new content]\n"
Step 3: Verify
read /path/to/file.md | grep "new content"

Best Practices

1. Always read before editing - Understand current state 2. Use edit for modifications - More precise than write 3. Keep changes small - Under 500 bytes per edit 4. Verify after each operation - Don't batch operations 5. Use unique markers - For complex modifications 6. Create backups - For critical files 7. Handle errors gracefully - Provide recovery strategies 8. Test incrementally - Verify each step

Decision Tree

Need to write/update file?
├─ New file?
│  ├─ < 2000 bytes?
│  │  └─ Use write tool
│  └─ > 2000 bytes?
│     └─ Use incremental build strategy
└─ Existing file?
   ├─ Small change (< 500 bytes)?
   │  └─ Use edit tool
   ├─ Medium change (500-1000 bytes)?
   │  └─ Use edit with unique markers
   └─ Large change (> 1000 bytes)?
      └─ Use incremental edit strategy

Quick Reference

| Task | Tool | Strategy | |------|------|----------| | Create small file | write | Direct write | | Create large file | write + edit | Incremental build | | Small modification | edit | Direct edit | | Medium modification | edit | Edit with markers | | Large modification | edit | Incremental edit | | Replace section | edit | Unique markers | | Append content | edit | Edit end of file |

Example 1: Adding Section to Large File

Step 1: Read file to find insertion point
read /path/to/large-file.md --offset 50 --limit 10
Step 2: Use edit to add new section
edit:
  file_path: /path/to/large-file.md
  oldText: "## Existing Section\n\nContent here"
  newText: "## Existing Section\n\nContent here\n\n## New Section\n\nNew content"
Step 3: Verify
read /path/to/large-file.md --offset 50 --limit 20

Example 2: Creating Large New File

Step 1: Create basic structure
write:
  file_path: /path/to/new-file.md
  content: "# Title\n\n## Section 1\n\nContent 1"
Step 2: Add sections incrementally
edit:
  file_path: /path/to/new-file.md
  oldText: "Content 1"
  newText: "Content 1\n\n## Section 2\n\nContent 2"
Step 3: Verify
wc -l /path/to/new-file.md

Example 3: Replacing Large Section

Step 1: Read file to find exact text
read /path/to/file.md
Step 2: Use unique markers
edit:
  file_path: /path/to/file.md
  oldText: "\n[old content]\n"
  newText: "\n[new content]\n"
Step 3: Verify
read /path/to/file.md | grep "new content"

1. Always read before editing - Understand current state 2. Use edit for modifications - More precise than write 3. Keep changes small - Under 500 bytes per edit 4. Verify after each operation - Don't batch operations 5. Use unique markers - For complex modifications 6. Create backups - For critical files 7. Handle errors gracefully - Provide recovery strategies 8. Test incrementally - Verify each step