Four OpenClaw Bugs That Cost Us Hours

OpenClaw is useful. It also has bugs that are not documented anywhere. These are the four we hit, what they look like when they happen, and how to work around them.

BUG-S: Config Set Crashes the Process

The openclaw config set command crashes the daemon on certain key paths. The config said yes. The runtime said no.

Symptom: Running openclaw config set <key> <value> exits cleanly (exit code 0) but the daemon process terminates silently. Subsequent commands return connection refused or daemon not running.

Affected keys: Nested config paths using dot notation when the parent key doesn't yet exist. For example:

openclaw config set services.gateway.timeout 30
# Daemon exits. No error output.

Workaround:

1. Edit the config file directly instead of using config set
2. Find the config path: openclaw config path
3. Open the file, add the nested key manually with correct JSON/YAML structure
4. Restart the daemon: openclaw start

Do not use config set for any nested key until this is patched. Flat keys (no dots) appear unaffected.

BUG-R: Gateway Stop Destroys the LaunchAgent

openclaw gateway stop is supposed to stop the gateway process. On macOS, it also deletes the LaunchAgent plist.

Symptom: After running openclaw gateway stop, the gateway does not restart on login. The plist at ~/Library/LaunchAgents/com.openclaw.gateway.plist is gone.

What happened: The stop command calls an internal cleanup routine that was intended only for uninstall. It removes the LaunchAgent registration as a side effect.

Workaround:

Before running openclaw gateway stop, back up the plist:

cp ~/Library/LaunchAgents/com.openclaw.gateway.plist \
   ~/Library/LaunchAgents/com.openclaw.gateway.plist.bak

After stopping, restore it:

cp ~/Library/LaunchAgents/com.openclaw.gateway.plist.bak \
   ~/Library/LaunchAgents/com.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

Alternatively, use openclaw gateway restart instead of stop + start. The restart path does not trigger the cleanup routine.

BUG-F: File Watch Misses Events on Network Volumes

The file watcher used by OpenClaw's sync service relies on FSEvents. On network-mounted volumes (SMB, AFP, NFS), FSEvents does not fire reliably.

Symptom: Changes to files on a network drive are not detected. Sync does not trigger. The watcher reports active with no errors.

The runtime said it was watching. It wasn't.

Workaround:

Set the watch mode to polling in the config file:

sync:
  watch_mode: poll
  poll_interval_ms: 2000

Polling is less efficient but reliable. For local volumes, keep FSEvents. For network volumes, polling is the only working option.

The OpenClaw UI shows "File sync active" regardless of whether events are being received. Do not trust the status indicator on network volumes.

BUG-C: Channels Login Prohibition Blocks Re-Auth

After logging out of a channel and attempting to log back in, OpenClaw throws a prohibition error:

Error: Channel login prohibited for existing session token

The session token from the previous login is not cleared on logout. The re-auth flow detects an existing (invalid) token and refuses to proceed.

Symptom: openclaw channels login <channel> fails immediately after openclaw channels logout <channel>.

Workaround:

Manually clear the token from the keychain or credential store:

# macOS Keychain
security delete-generic-password -s "openclaw-channel-<channel-name>"

Then retry the login. The re-auth flow succeeds once the stale token is removed.

Check that the channel name matches exactly — the keychain entry uses the internal channel identifier, which may differ from the display name. Run openclaw channels list --verbose to get the internal identifiers.

Pattern Across All Four

Three of the four bugs involve state that isn't cleaned up: stale config parent keys, LaunchAgent registration surviving a stop command, orphaned session tokens. One involves a silent capability mismatch (FSEvents on network volumes).

None of these produce helpful error messages. All four look like user error until you trace the actual behavior.

The fix in each case was to bypass the broken command and manipulate the underlying state directly.