OpenClaw 3.31 Update Broke Your Tools? Here's the Fix.

If you updated to OpenClaw v2026.3.31 and your tools stopped working, you're not alone. The r/openclaw thread on this hit hundreds of upvotes within days. The update rewrote the node/exec architecture — and while the intention was to make sub-agent workflows more reliable, it broke standard tool access for a lot of existing setups.

What Broke

• Tools that worked before the update now return errors or silently fail
• Exec commands time out or hang indefinitely
• Access to workspace files behaves differently than before
• Sub-agent workflows that relied on exec no longer function
• Everything worked fine before running npm update

What Changed in 3.31

The 3.31 release introduced a significant internal restructuring of how OpenClaw routes commands between the main agent process, node processes, and exec sessions. Specifically:

• The exec security model changed. Commands that previously ran in a trusted local context now pass through a new permission layer. If your exec-approvals.json isn't configured correctly for the new architecture, commands get silently blocked.
• Node/gateway separation tightened. The boundary between node-hosted and gateway-hosted execution changed. Tools that relied on implicit node context need explicit routing now.
• Legacy config values are no longer auto-repaired. Prior versions would silently fix known bad config patterns on startup. 3.31 removed that safety net — bad configs now just fail.

Fix Option 1 — Install the Beta (Recommended)

The beta that "almost fixes the whole issue" according to multiple r/openclaw reports:

# Backup first — always
cp -r ~/.openclaw ~/.openclaw-backup-$(date +%Y%m%d)

# Install the current beta
npm install -g openclaw@beta

# Restart OpenClaw
openclaw restart

After installing, verify your tools are working again with a simple test — ask your agent to read a file or run a basic command. Most users report normal behavior returns immediately after the beta install.

Fix Option 2 — Patch Your exec-approvals.json

If you'd rather stay on stable or the beta doesn't resolve your issue, the most common root cause is a misconfigured exec-approvals.json. Check and fix it:

# Check what's in your approvals file
cat ~/.openclaw/exec-approvals.json

# If it's missing or malformed, reset it
openclaw exec-approvals --reset

Then open the file and verify the structure matches what 3.31 expects — the new format requires explicit security and host fields that older configs didn't include.

Fix Option 3 — Run openclaw doctor

The built-in diagnostic tool catches most 3.31 migration issues automatically:

openclaw doctor

Look for warnings about exec.security, node.routing, or legacy config. Each warning includes a suggested fix command. Run them in order, then restart.

Fix Option 4 — Roll Back to 3.28

If you need things working right now and can't debug, rolling back is the safest option:

# Roll back to the last stable version before 3.31
npm install -g openclaw@2026.3.28

# Restore your backup config
cp -r ~/.openclaw-backup-[date]/* ~/.openclaw/

# Restart
openclaw restart

Note: 3.28 contains the CVE-2026-33579 patch, so rolling back here is safe from a security standpoint. Don't roll back further than 3.28.

Preventing This Next Time

• Always back up before updating. cp -r ~/.openclaw ~/.openclaw-backup-$(date +%Y%m%d) — one command, 30 seconds.
• Read the full changelog before running npm update. 3.31's breaking changes were documented — the architecture changes were flagged. It's easy to miss if you're skimming.
• Test immediately after updating. Send one message, run one exec command. Catch breakage before you need the agent for something real.