OpenClaw Gateway — Linux Fixes

Issue 1: Gateway shows "disabled" despite running

Symptom: openclaw status or openclaw gateway status shows disabled, but the service is actually running.

Root cause: The gateway process spawns systemctl --user is-enabled without XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS in its environment. Without these, systemd user bus is unreachable → "Failed to connect to bus: No medium found".

⚠️ Common wrong fix: Adding these vars to ~/.bashrc or shell environment does NOT help — the gateway daemon doesn't inherit your shell env.

Correct fix: Add the vars directly to the systemd unit file:

RUNTIME_DIR="/run/user/$(id -u)"
UNIT=~/.config/systemd/user/openclaw-gateway.service

# Append env vars after [Service] line (idempotent check first)
grep -q "XDG_RUNTIME_DIR" "$UNIT" || UNIT="$UNIT" RUNTIME="$RUNTIME_DIR" python3 -c "
import re, os
unit, runtime = os.environ['UNIT'], os.environ['RUNTIME']
content = open(unit).read()
insert = '\nEnvironment=XDG_RUNTIME_DIR=' + runtime + '\nEnvironment=DBUS_SESSION_BUS_ADDRESS=unix:path=' + runtime + '/bus'
content = re.sub(r'(\[Service\])', r'\1' + insert, content, count=1)
open(unit, 'w').write(content)
print('Unit file updated.')
"

# Reload and restart safely (see Issue 2 for post-restart status check)
systemctl --user daemon-reload
nohup bash -c 'sleep 2 && systemctl --user restart openclaw-gateway' > /tmp/gw-restart.log 2>&1 &

Expected result: Service: systemd (enabled)

Issue 2: Safe gateway restart

Problem: openclaw gateway restart and systemctl --user restart openclaw-gateway send SIGTERM to the gateway, which also kills the entire process tree — including the agent turn that triggered the restart. Any work scheduled after the restart command in the same process will never execute.

Root cause: The agent runs as a child process of the gateway. SIGTERM propagates down the tree on shutdown.

Step 1: Schedule post-restart work via cron

Since the agent dies with the gateway, any follow-up work must be pre-scheduled before the restart using openclaw cron add --at.

The cron scheduler runs inside the gateway and fires independently once the gateway comes back up (~5–7 seconds). Schedule it ~15 seconds ahead to be safe.

AT=$(date -u +"%Y-%m-%dT%H:%M:%S+00:00" --date="+15 seconds") && \
openclaw cron add \
  --name "gw-restart-notify" \
  --at "$AT" \
  --message "Gateway was restarted. Check status: systemctl --user status openclaw-gateway --no-pager | head -4 and report back." \
  --announce \
  --to <TELEGRAM_CHAT_ID> \
  --channel telegram \
  --delete-after-run \
  --session isolated

Step 2: Trigger the restart

nohup bash -c 'sleep 2 && systemctl --user restart openclaw-gateway' > /tmp/gw-restart.log 2>&1 &

sleep 2 + & detaches the restart from the current process tree before the gateway shuts down.

⚠️ Do NOT chain status checks after this command (e.g. && sleep 5 && systemctl status) — they will be killed too.

Passing context across the restart

If the agent needs to continue a task after restart, save context to a file before restarting and reference it in the cron message:

echo "Was doing X, next step is Y, params: Z" > /tmp/restart-context.txt

AT=$(date -u +"%Y-%m-%dT%H:%M:%S+00:00" --date="+15 seconds") && \
openclaw cron add \
  --name "gw-restart-continue" \
  --at "$AT" \
  --message "Continue the task. Context is in /tmp/restart-context.txt — read it and proceed." \
  --announce \
  --to <TELEGRAM_CHAT_ID> \
  --channel telegram \
  --delete-after-run \
  --session isolated

The isolated agent spawned by cron will read the file and continue from where the previous agent left off.

What does NOT work

• sleep N && systemctl status chained after restart — killed by SIGTERM
• setsid / systemd-run for post-restart notification — process survives but cannot reach Telegram (direct API access blocked in some regions; gateway is the only working path)
• curl directly to Telegram API — may time out if blocked at network level

Issue 3: openclaw gateway status shows "disabled" in SSH session

This is a separate issue from Issue 1 — the gateway itself works fine, but your shell session lacks XDG_RUNTIME_DIR.

Affected: sudo su (without -), non-login shells, cron, sudo openclaw.

Fix: Add to ~/.bashrc and /etc/profile.d/openclaw-env.sh:

export XDG_RUNTIME_DIR=/run/user/$(id -u)
export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u)/bus

Shell escalation cheatsheet:

Issue 4: Service not persisting after reboot

OpenClaw runs as a user-scope systemd service (~/.config/systemd/user/), not system-scope. Without linger, user services stop when the last session closes.

loginctl enable-linger $(whoami)   # persist after logout
systemctl --user enable openclaw-gateway  # auto-start on boot

See references/diagnosis.md for a full diagnostic checklist.