🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Openclaw Gateway Fd Fix
πŸ¦€ ClawHub

Openclaw Gateway Fd Fix

by @thomaszhang2661

Fix OpenClaw Gateway "spawn EBADF" / "RPC probe failed" / "EMFILE too many open files" errors caused by file descriptor exhaustion from too many files in wor...

Versionv1.0.0
Downloads1,255
#writing#legal
TERMINAL
clawhub install openclaw-gateway-fd-fix

πŸ“– About This Skill

name: openclaw-gateway-fd-fix description: > Fix OpenClaw Gateway "spawn EBADF" / "RPC probe failed" / "EMFILE too many open files" errors caused by file descriptor exhaustion from too many files in workspace. One-click detection and repair for the most common OpenClaw crash issue. version: 1.0.0 author: thomas-jian-zhang license: MIT tags: - openclaw - gateway - troubleshooting - fd-exhaustion - emfile - spawn-ebadf - maintenance

OpenClaw Gateway File Descriptor Exhaustion Fix

Problem

OpenClaw Gateway crashes or hangs with these errors:
  • spawn EBADF when running exec commands
  • RPC probe failed / gateway timeout
  • Logs show EMFILE: too many open files, watch
  • Gateway process is running but unresponsive

    • Root Cause

    The Gateway automatically watches all files under ~/.openclaw/workspace/ for changes. If you place virtual environments (.venv), node_modules, large datasets, or tens of thousands of small files inside workspace, the file watcher will exceed macOS's default file descriptor limit (256), causing the process to hang.

    Usage

    Auto-Fix (Recommended)

    Run the one-click repair script: 
    bash fix.sh
    What it does: 1. Detects workspace file count 2. Finds and removes unnecessary dependency directories (.venv, node_modules) inside workspace 3. Backs up your existing LaunchAgent plist 4. Updates LaunchAgent to set file descriptor limit to 524,288 5. Restarts the Gateway service 6. Verifies service health

    Manual Fix Steps

    If you prefer to fix manually: 1. Remove large directories from workspace: 
       # Never put these inside ~/.openclaw/workspace/:
   rm -rf ~/.openclaw/workspace/*/.venv
   rm -rf ~/.openclaw/workspace/*/node_modules
   # Move datasets/models/venvs to ~/Downloads/ or /tmp/
    2. Update LaunchAgent resource limits: Edit ~/Library/LaunchAgents/ai.openclaw.gateway.plist and add inside the root : 
       HardResourceLimits
   
     NumberOfFiles
     524288
   
   SoftResourceLimits
   
     NumberOfFiles
     524288
    3. Restart Gateway: 
       launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
   sleep 10 && openclaw gateway status

    Permanent Rule (NEVER BREAK)

    βœ… Do NOT put these inside ~/.openclaw/workspace/:
  • Python virtual environments (.venv, venv)
  • Node.js node_modules directories
  • Large datasets (>1000 files)
  • AI model weights (.pt, .bin, .pth files)
  • Cache directories with thousands of small files

    • βœ… Put these outside workspace: /tmp/, ~/Downloads/, or any directory outside ~/.openclaw/workspace/

    Verification

    After fix, run: 
    openclaw gateway status
    You should see RPC probe: ok in the output.

    Troubleshooting

    If fix fails: 1. Check logs: tail -50 ~/.openclaw/logs/gateway.err.log 2. Verify no large directories remain in workspace: find ~/.openclaw/workspace -type f | wc -l (should be < 1000) 3. Manually restart Gateway: openclaw gateway stop && openclaw gateway install

    πŸ’‘ Examples

    Auto-Fix (Recommended)

    Run the one-click repair script: 
    bash fix.sh
    What it does: 1. Detects workspace file count 2. Finds and removes unnecessary dependency directories (.venv, node_modules) inside workspace 3. Backs up your existing LaunchAgent plist 4. Updates LaunchAgent to set file descriptor limit to 524,288 5. Restarts the Gateway service 6. Verifies service health

    Manual Fix Steps

    If you prefer to fix manually: 1. Remove large directories from workspace: 
       # Never put these inside ~/.openclaw/workspace/:
   rm -rf ~/.openclaw/workspace/*/.venv
   rm -rf ~/.openclaw/workspace/*/node_modules
   # Move datasets/models/venvs to ~/Downloads/ or /tmp/
    2. Update LaunchAgent resource limits: Edit ~/Library/LaunchAgents/ai.openclaw.gateway.plist and add inside the root : 
       HardResourceLimits
   
     NumberOfFiles
     524288
   
   SoftResourceLimits
   
     NumberOfFiles
     524288
    3. Restart Gateway: 
       launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
   sleep 10 && openclaw gateway status

    πŸ“‹ Tips & Best Practices

    If fix fails: 1. Check logs: tail -50 ~/.openclaw/logs/gateway.err.log 2. Verify no large directories remain in workspace: find ~/.openclaw/workspace -type f | wc -l (should be < 1000) 3. Manually restart Gateway: openclaw gateway stop && openclaw gateway install