How to roll back an OpenClaw config change when you can’t get back in

TL;DR

If your agent is still responding: paste the commands in the blockquotes below into your OpenClaw chat. Your agent will do the recovery work for you. If the gateway is unreachable: you need a terminal. SSH (a secure way to open a command window on a remote server from your own computer) into your server and run openclaw backup restore to replace your broken config with the last known good snapshot. If you have no backup: open ~/.openclaw/openclaw.json in a text editor, find the setting you changed, revert it, and restart. All three paths, including what to do when the gateway is down and you have no backup at all, are covered below with exact steps.

START HERE: which situation are you in?

Open your OpenClaw chat and try sending any message.

Your agent replies: go to Your agent is still responding. You can fix this from the chat window without touching a terminal.

Nothing comes back (timeout, error, blank): go to Gateway is unreachable. You will need terminal access.

Chat connects but you still cannot reach the agent from a browser or mobile: skip to The gateway is running but unreachable. The process is up but something is blocking the connection.

Before you use the terminal paths: A terminal is a text window where you type commands directly. On a VPS (a remote server you rent), use SSH to open a terminal on it from your own machine. On a local machine, open Terminal on macOS, the WSL2 terminal on Windows, or any terminal emulator on Linux. In Docker, run docker exec -it <container-name> /bin/bash to get a terminal inside the container.

Windows: WSL2 (Windows Subsystem for Linux 2) gives you a Linux terminal inside Windows. All paths in this article that start with ~/.openclaw/ refer to the WSL2 filesystem, not your Windows C: drive. Open the WSL2 terminal (not PowerShell or CMD) before running any commands. If you installed OpenClaw natively on Windows (not inside WSL2), your config is at %APPDATA%\openclaw\openclaw.json instead. Open it with notepad %APPDATA%\openclaw\openclaw.json in CMD.

macOS (Apple Silicon / Homebrew): If the openclaw command is not found, run eval "$(/opt/homebrew/bin/brew shellenv)" in your terminal to add Homebrew’s bin directory to your PATH for this session. To make it permanent, add that line to your ~/.zshrc.

Step 1: Find out what changed

Terminal path: Run cat ~/.openclaw/openclaw.json to print the full config. If you have git set up, run git -C ~/.openclaw diff HEAD openclaw.json to see exactly what changed since the last commit.

Windows native (CMD): type %APPDATA%\openclaw\openclaw.json
Windows native (PowerShell): Get-Content "$env:APPDATA\openclaw\openclaw.json"

If your openclaw.json lives in a workspace subdirectory rather than ~/.openclaw/ directly, run find ~ -name "openclaw.json" -not -path "*/backups/*" 2>/dev/null to locate it.

Step 2: Revert a specific setting

If you changed the model: After the gateway restarts, your current chat session will still use the old model. OpenClaw caches the active model per session. Run /new or /reset in the chat to start a fresh session, then ask: “Which model are you using?” to confirm.

Terminal path: openclaw config set agents.defaults.model deepseek/deepseek-chat (replace with your field and value). Then openclaw config validate. Then openclaw gateway restart. A successful restart returns no error output and status shows “running” within seconds.

If restart returns EADDRINUSE: “EADDRINUSE” means another process is already using the port the gateway wants. Wait 5 seconds and try again. If it persists, check: ss -tlnp | grep 18789 (Linux) or lsof -i :18789 (macOS), replacing 18789 with your port. Kill the stale process, then restart.

Step 3: Run openclaw doctor

Terminal path: openclaw doctor. The base command is read-only and changes nothing. For automatic repair, openclaw doctor --fix writes corrections to disk. Run it without --fix first and read the output, then decide if auto-repair is appropriate.

What doctor –fix actually repairs: It restores flagged fields to OpenClaw’s built-in defaults, not to the values you had before. If you deliberately set a non-default value (like a custom contextTokens limit) and doctor flags it as invalid, --fix will reset it to the default. Review the report before running --fix and re-apply any intentional non-default values after. After any fix, run openclaw config validate before restarting.

Step 4: OpenClaw rollback config change via backup restore

Terminal path: openclaw backup list prints a dated list of available backups. If your version of OpenClaw does not have this command, use ls -lt ~/.openclaw/backups/ to see raw files sorted by time. Backups are named with timestamps: openclaw-backup-20260322-143015.tar.gz. If the directory is empty, no automatic backups were created. Skip to Step 5.

If backups are not at ~/.openclaw/backups/: Run find ~ -name "openclaw-backup-*.tar.gz" 2>/dev/null to locate them. Some installs place backups under the workspace directory instead.

Backup restore replaces API keys too. API keys are the long strings your agent uses to call AI providers like Anthropic or DeepSeek. If you recently generated new keys, restoring will revert to the old values. After any restore, re-apply any intentional key changes.

Terminal path: Stop the gateway first: openclaw gateway stop (or sudo systemctl stop openclaw-gateway if you use systemd (Linux’s built-in service manager that automatically restarts crashed processes) with auto-restart). Status shows “stopped” when done. Then: openclaw backup restore ~/.openclaw/backups/openclaw-backup-YYYYMMDD-HHMMSS.tar.gz. Then: openclaw config validate. Then: openclaw gateway restart. Successful restart shows no error output.

Step 5: Validate before restarting

Terminal path: openclaw config validate. If you skip this and restart with a broken config, the gateway fails to start and you are in a full terminal lockout. Fix any errors before running openclaw gateway restart.

Terminal path:
Linux (systemd): journalctl -u openclaw-gateway --lines=50 --no-pager
macOS (launchd): log show --predicate 'process == "openclaw"' --last 10m --style compact
Docker: docker logs --tail 50 <container-name>
Fallback (any platform): Check ~/.openclaw/logs/gateway.log

You are in the terminal path. The OpenClaw chat connects through the gateway. If the gateway is down, the chat is down. That is why you cannot paste commands into the chat to fix this. You need to reach your server directly: SSH for remote machines, a local terminal for local installs. The commands below go into that terminal window, not the OpenClaw chat.

Step 1: Confirm the gateway process state

Run: openclaw gateway status

The command prints a single-line status such as “Gateway: running (pid 12345)” or “Gateway: stopped.” The pid number is the process ID, a number the system uses to track the running process. You do not need to do anything with it. Look for the word “running” or “stopped.”

“running”: the process is up. The problem is a network block. Jump to the “gateway is running but unreachable” subsection below.

“stopped” or “failed”: the gateway crashed or could not start. The config is the problem. Continue with Step 2.

In Docker: docker ps | grep openclaw to check if the container is running. If it is not listed, it is stopped: docker logs <container-name> --tail 30 to see why.

Using systemd: Cross-check with sudo systemctl status openclaw-gateway if the openclaw command gives inconsistent results.

Step 2: Run openclaw doctor

Run: openclaw doctor

The base command is read-only and changes nothing. Output lists checks with PASS or FAIL. FAIL lines include the field name and what it should be.

In Docker: docker exec -it <container-name> openclaw doctor

Before using doctor –fix: openclaw doctor --fix restores flagged fields to OpenClaw’s built-in defaults, not your previous values. If you deliberately set a non-default value that doctor considers invalid, --fix will reset it to the default. Read the report output first, then decide. After any fix, run openclaw config validate before restarting.

Step 3: Read the startup error

Linux (systemd): journalctl -u openclaw-gateway -n 30 --no-pager
macOS (launchd): log show --predicate 'process == "openclaw"' --last 5m --style compact
Docker: docker logs --tail 30 <container-name>
Manual start (any OS): Run openclaw gateway start and errors print directly to the terminal.

What the errors mean:

“SyntaxError: Unexpected token”: the config file has invalid JSON structure (missing comma, broken bracket). The gateway cannot read it at all. Go to Step 5 (manual edit).

“EADDRINUSE” / “address already in use”: the port is taken by another program. Change your gateway port or stop the conflicting process. If this appears right after a restart attempt, wait 5 seconds and try again before assuming a conflict.

“Model not found” / “Unknown provider”: the model name is wrong or formatted incorrectly. Revert the model field to a known working value.

“Plugin failed to load”: a plugin config is malformed or missing a dependency. Check the plugins.entries section of your config.

Step 4: Restore from backup (fastest path)

Stop the gateway before restoring. Restoring while the gateway is running can corrupt the config. Run openclaw gateway stop first. If you use systemd with Restart=always, use sudo systemctl stop openclaw-gateway instead. (sudo runs the command with administrator-level permissions, required for managing system services.) Otherwise systemd restarts the process immediately. Save a copy of your current config before restoring: cp ~/.openclaw/openclaw.json ~/openclaw-json-before-restore.json

Backup restore replaces API keys too. If you recently generated new API keys, restoring will revert to the old values. After any restore, re-apply any intentional key changes.

List backups: openclaw backup list or ls -lt ~/.openclaw/backups/. Pick the newest file that predates your bad change. Running the restore command below will restore openclaw.json to that snapshot. If the directory is empty, go to Step 5.

Restore:
openclaw gateway stop
openclaw backup restore ~/.openclaw/backups/openclaw-backup-YYYYMMDD-HHMMSS.tar.gz
openclaw config validate
openclaw gateway restart

Successful restart: no error output, openclaw gateway status returns a line containing “running.”

Step 5: Manual config edit (no backup available)

openclaw.json is JSON format. One missing comma, one extra brace, one unescaped quote breaks the file entirely. After any edit, run openclaw config validate before restarting. If validate fails, fix the syntax error before restarting.

Preferred: use openclaw config set
openclaw config set agents.defaults.model deepseek/deepseek-chat
openclaw config set gateway.port 18789

No output on success. Run openclaw config validate after to confirm.

Direct file edit (only if config set cannot help):
Linux/macOS/WSL2: nano ~/.openclaw/openclaw.json
nano is a text editor that runs in the terminal. Use Ctrl+W to search for a field name. Ctrl+O to save. Ctrl+X to exit. If nano is not installed (common in minimal Docker/Alpine images), use vi ~/.openclaw/openclaw.json instead. Or install nano: apt install nano (Debian/Ubuntu) or apk add nano (Alpine).
Windows native: notepad %APPDATA%\openclaw\openclaw.json

Common fields to check:
gateway.bind: if set to 127.0.0.1, the gateway only accepts connections from the same machine. Change to 0.0.0.0 for external access, or keep at 127.0.0.1 and use SSH tunneling.
gateway.port: if changed to a blocked or taken port, revert to 18789.
agents.defaults.model: format is provider/model-name, for example, deepseek/deepseek-chat.
models.providers.X.apiKey: must be the correct, current API key for that provider.

After any edit: openclaw config validate

Fix any errors first. When validate shows “Config valid.”: openclaw gateway restart

Step 6: Git rollback (only if you set up git tracking)

See what changed:
git -C ~/.openclaw diff HEAD openclaw.json

Lines with - are the old values. Lines with + are the new (broken) values.

If your openclaw.json lives in a workspace subdirectory: replace ~/.openclaw with that path. Run find ~ -name "openclaw.json" -not -path "*/backups/*" 2>/dev/null to find it.

Restore the last good version:
git -C ~/.openclaw checkout HEAD -- openclaw.json

This touches only openclaw.json. Nothing else changes. Success is silent: no output means it worked. Then:
openclaw config validate && openclaw gateway restart

To go back further: git -C ~/.openclaw log --oneline -- openclaw.json to see the history, then git -C ~/.openclaw checkout <commit-hash> -- openclaw.json

Check what the gateway is listening on:
Linux: ss -tlnp | grep openclaw
macOS: lsof -iTCP -sTCP:LISTEN | grep openclaw
Either (cross-platform): netstat -an | grep 18789 (replace 18789 with your port)

127.0.0.1:18789 = loopback only. That is why remote connections fail.
0.0.0.0:18789 = all interfaces. The problem is elsewhere (firewall, network).

Note: ss is Linux-only. On macOS, use lsof. On Windows WSL2, ss works inside the WSL2 terminal but shows the WSL2 network stack, not the Windows host network. If OpenClaw is running on the Windows host (not inside WSL2), check with netstat -an | findstr 18789 in CMD instead.

Security note before changing gateway.bind: Setting gateway.bind to 0.0.0.0 makes your agent reachable by anyone who finds your server’s IP. There is no login page or password on the gateway. On a public-facing server, put a reverse proxy (a program like Nginx or Caddy that sits between the internet and your gateway, adding authentication and HTTPS before passing traffic through) or a firewall rule in front of it first, or use SSH tunneling instead. SSH tunneling lets you reach a loopback-only gateway remotely without exposing it. See the linked article at the end.

Fix bind (if you have a firewall or are on a private network):
openclaw config set gateway.bind 0.0.0.0
openclaw config validate
openclaw gateway restart

After restart, the gateway accepts external connections. Paired mobile nodes reconnect automatically because node pairing uses a URL that includes hostname and port, not the bind address. As long as the URL and port are unchanged, nodes reconnect on their next attempt.

IPv6 note: 0.0.0.0 only binds IPv4. For IPv6 access, set gateway.bind to :: instead. Some Linux systems (Ubuntu 22.04+) have IPv6 enabled by default. If your server has a public IPv6 address and you set 0.0.0.0, IPv6 connections will still be blocked until you switch to ::.

Check your firewall: A firewall blocks or allows connections on specific ports. Even with gateway.bind at 0.0.0.0, a firewall can block inbound connections silently with no error message on either side.

Linux Ubuntu/Debian (UFW is the built-in firewall manager): sudo ufw status. If the gateway port is not listed as ALLOW: sudo ufw allow YOUR_PORT/tcp.
Linux RHEL/Fedora (firewalld is the built-in firewall manager): sudo firewall-cmd --list-ports. If not listed: sudo firewall-cmd --add-port=YOUR_PORT/tcp --permanent && sudo firewall-cmd --reload.
macOS: System Settings > Network > Firewall. Add OpenClaw or disable the firewall temporarily to test.
Cloud VPS (DigitalOcean, Hetzner, AWS, etc.): Check the cloud firewall or security group rules in your provider dashboard. Cloud firewalls are separate from the OS firewall and are the most commonly missed cause of this problem.
Windows (WSL2): If OpenClaw runs inside WSL2, the Windows firewall may block incoming connections to the WSL2 network interface. Check Windows Defender Firewall > Advanced Settings > Inbound Rules for the gateway port.

You changed the model and the agent will not respond

Start a fresh session after any model change. Run /new in the chat. The current session caches the old model even after a gateway restart. Then ask “Which model are you using?” to confirm.

Terminal path: openclaw config set agents.defaults.model deepseek/deepseek-chat then openclaw gateway restart. Model name format: provider/model-name for API models, ollama/model-name for local models.

If you changed to an Ollama local model: Ollama runs AI models on your own machine. Format: ollama/llama3.1:8b. Check the model is downloaded: ollama list. If it is not there, download it: ollama pull model-name. Confirm Ollama is running: curl http://127.0.0.1:11434/api/tags should return a list of models. If it returns “connection refused,” Ollama is not running. Start it with: ollama serve.

macOS Apple Silicon / Homebrew: If ollama is not found, run eval "$(/opt/homebrew/bin/brew shellenv)" in your terminal.

Windows WSL2: Ollama installed on the Windows host is not automatically visible from inside WSL2. Either install Ollama inside WSL2 separately, or point OpenClaw to the Windows host IP ($(cat /etc/resolv.conf | grep nameserver | awk '{print $2}') from WSL2) instead of 127.0.0.1 when configuring the Ollama endpoint.

You changed gateway.bind or gateway.port and lost access

Terminal path (bind): openclaw config set gateway.bind 0.0.0.0 then openclaw config validate then openclaw gateway restart.

Terminal path (port conflict): Check what is using which ports: ss -tlnp | grep LISTEN (Linux) or lsof -iTCP -sTCP:LISTEN (macOS) or netstat -ano | findstr LISTENING (Windows CMD). Change your port to a free one or stop the conflicting process, then restart.

After fixing bind: If you set 0.0.0.0 without a firewall in place, your agent is now reachable by anyone. Set a firewall rule or revert to 127.0.0.1 and use SSH tunneling for remote access.

Paired mobile nodes: Node pairing uses a URL (hostname + port). Changing bind alone does not break it. But if you also changed gateway.port, those nodes have the old port and will fail to reconnect.

You changed an API key and all tool calls fail

Terminal path: API key fields are under models.providers.PROVIDER_NAME.apiKey. Set the correct key: openclaw config set models.providers.deepseek.apiKey YOUR_KEY_HERE.

Check for duplicate key locations: Some plugins store their own API keys separately, for example under plugins.entries.PLUGIN_NAME.config.llm.apiKey. If you changed the key in one place but not the other, one subsystem works and the other fails. Search the entire config for the provider name to find all locations.

You changed a plugin config and the agent is broken

Terminal path: Run openclaw config validate first. Plugin errors often appear here. If validate passes but the plugin is still broken, check the log:
Linux: journalctl -u openclaw-gateway --lines=100 --no-pager | grep -i plugin
macOS: log show --predicate 'process == "openclaw"' --last 10m | grep -i plugin
Docker: docker logs --tail 100 <container-name> 2>&1 | grep -i plugin

Fastest fix: disable the plugin temporarily. Ask your agent: “Set plugins.entries.PLUGIN_NAME.disabled to true, validate, and restart.” The gateway runs without that plugin and everything else works normally. Debug the plugin config in a separate session once you are back in.

Create a backup before every config change

Terminal path: openclaw backup create. The command prints the path to the backup file. Your original config is unchanged.

Manual copy (Linux/macOS/WSL2): cp ~/.openclaw/openclaw.json ~/openclaw-config-backup-$(date +%Y%m%d-%H%M%S).json
Windows PowerShell: Copy-Item "$env:APPDATA\openclaw\openclaw.json" "$HOME\openclaw-config-backup-$(Get-Date -Format 'yyyyMMdd-HHmmss').json"

Always validate before restarting

Terminal path: openclaw config validate. “Config valid.” with no further output means it passed. Any other output means errors to fix before restarting.

Put your config in git

Terminal path: Check first: git -C ~/.openclaw status. If it returns “not a git repository”:

git init ~/.openclaw (creates a .git/ folder, does not touch any existing files)

Before your first commit, create a .gitignore to avoid tracking large binary files, session data, and logs that live alongside your config:
printf "*.db\n*.log\nlogs/\nsessions/\nsessions-archive/\nnode_modules/\n" > ~/.openclaw/.gitignore

Then commit only the config:
git -C ~/.openclaw add openclaw.json .gitignore
git -C ~/.openclaw commit -m "initial config commit"

After this, commit after every intentional change:
git -C ~/.openclaw add openclaw.json && git -C ~/.openclaw commit -m "config change: [what you changed]"

If your openclaw.json is in a workspace subdirectory, replace ~/.openclaw with that path.

Do not push openclaw.json to a public repository. Your config contains API keys in plain text. Pushing to a public GitHub repo exposes every key immediately. Automated bots scan for exposed credentials constantly. If you have already pushed it, see the linked article at the end for incident response steps including how to rotate every exposed key.

The safe change pattern

The pattern: (1) Backup. (2) Change via openclaw config set or config patch. (3) Validate. (4) Restart. (5) Test: send a message and confirm the agent responds correctly. (6) If it works, git commit. If not, restore the backup from step 1.

BRAND NEW CLAW

The complete hardening kit for OpenClaw operators

Every config, every security setting, every backup and recovery procedure you need. Covers gateway hardening, model routing, exec permissions, memory scoping, and more. Designed for operators who want their setup stable and auditable from day one.

Get Brand New Claw: $37

My agent responded to the rollback command but the gateway still shows the old config. Did it work?

I do not know what I changed. How do I find the cause?

Is it safe to run openclaw backup restore while the gateway is running?

My openclaw.json has no syntax errors but openclaw config validate still fails. What is happening?

I have dozens of backups. How do I know which one to restore?

Linux (GNU tar): tar -xzf ~/.openclaw/backups/openclaw-backup-YYYYMMDD-HHMMSS.tar.gz -O openclaw.json

macOS (BSD tar): tar -xzf ~/.openclaw/backups/openclaw-backup-YYYYMMDD-HHMMSS.tar.gz --to-stdout openclaw.json

Both print the openclaw.json from inside the backup without extracting anything. If you get no output, run tar -tzf ~/.openclaw/backups/FILE.tar.gz to list what is inside and find the correct path.

The gateway restarted but I cannot tell if everything is working. How do I test it?

I changed the exec security setting and now my agent cannot run any commands. Am I locked out?

Terminal path: openclaw config set agents.defaults.tools.exec.security full then openclaw gateway restart. Valid values: full (unrestricted), allowlist (only listed commands), deny (no terminal commands at all).

I am running OpenClaw in Docker and none of these commands work.

docker exec -it openclaw-gateway openclaw gateway status
docker exec -it openclaw-gateway openclaw config validate
docker exec -it openclaw-gateway openclaw doctor

Find your container name: docker ps | grep openclaw. If stopped, start it: docker start <container-name>, then check logs: docker logs <container-name> --tail 50.

The config file inside the container is at /home/node/.openclaw/openclaw.json. If you mounted it as a volume (a shared folder between container and host), you can edit it from the host at the mount path. Edits via volume mount do not take effect until the gateway restarts inside the container.

Minimal images (Alpine-based): nano is not installed. Use vi /home/node/.openclaw/openclaw.json or install nano: apk add nano.

I am on macOS and journalctl is not found.

log show --predicate 'process == "openclaw"' --last 10m --style compact

If no results: check ~/.openclaw/logs/gateway.log or run find ~/.openclaw -name "*.log" -type f to find log files.

I am on Windows and the paths in this article do not work.

I initialized git in ~/.openclaw. Will it track files I do not want?

printf "*.db\n*.log\nlogs/\nsessions/\nsessions-archive/\nnode_modules/\n" > ~/.openclaw/.gitignore
git -C ~/.openclaw add .gitignore
git -C ~/.openclaw commit -m "add gitignore"

Then always use git -C ~/.openclaw add openclaw.json specifically rather than git add -A to commit only what you intend.

Gateway: The background process that runs your OpenClaw agent. It starts when you launch OpenClaw and keeps running. When you open the chat, you are connecting to the gateway.

Config file (openclaw.json): The text file that controls how OpenClaw behaves: which AI model to use, what port the gateway listens on, which plugins are enabled, where API keys are stored. Located at ~/.openclaw/openclaw.json (Linux/macOS/WSL2) or %APPDATA%\openclaw\openclaw.json (Windows native).

Port: A numbered channel on your server. The gateway listens on a specific port (default: 18789) for incoming connections.

Bind address / gateway.bind: Controls which network interfaces accept connections. 127.0.0.1 = loopback only (same machine). 0.0.0.0 = all interfaces (any machine that can reach your server).

Loopback (127.0.0.1): Traffic sent to this address never leaves the machine. If the gateway is loopback-only, only a browser running on the same computer can connect.

API key: A long string of characters proving you are an authorized user of an AI provider (Anthropic, DeepSeek, OpenAI, etc.). Stored in openclaw.json.

Rotate (credentials): Generate a new API key and replace the old one. Done when a key may have been exposed.

SSH: A way to open a terminal on a remote server from your own computer over an encrypted connection.

VPS (Virtual Private Server): A remote server you rent from a hosting company. Common providers: DigitalOcean, Hetzner, AWS, Vultr.

Firewall: Software or a network device that blocks or allows connections on specific ports. Can block access silently with no error message.

Reverse proxy: A server (Nginx, Caddy) that sits in front of the gateway, handles connections on its behalf, and can add authentication or HTTPS.

systemd: The service manager on most Linux systems. Starts, stops, and restarts background services. Can restart them automatically if they crash.

launchd: The service manager on macOS. Same role as systemd.

JSON: The file format used by openclaw.json. Uses curly braces, colons, and commas. One missing comma or extra brace breaks the entire file.

Schema: The ruleset defining which fields are allowed in openclaw.json, what type each must be, and which are required.

WSL2 (Windows Subsystem for Linux 2): A feature in Windows 10/11 that runs a Linux environment inside Windows. Gives you a Linux terminal and filesystem on a Windows machine.

git: Version control software. Keeps a timestamped history of file changes. Lets you roll back any file to any previous saved state.

Security

I accidentally pushed my openclaw.json to GitHub

If your config ended up in a public repository, the first step is credential rotation. This walks the full incident response: what to rotate, in what order, and how to verify nothing was used.

Security

How to set up SSH tunneling so OpenClaw never touches the public internet

If you want gateway.bind on 127.0.0.1 for security but still need remote access, SSH tunneling is how. Keeps the gateway off the public internet entirely while still letting you reach it from anywhere.