---
name: openclaw-runtime
description: "OpenClaw on shadow runs as two manual tmux processes (gateway + crestodian CLI); no systemd, must restart by hand on reboot"
metadata:
node_type: memory
type: project
originSessionId: 71d40fa2-b151-4c81-9821-f0dfeb7a0f66
---

OpenClaw on shadow needs **two long-running processes** in tmux session
`ai-agents`:

1. **Gateway** — `node openclaw.mjs gateway run` (in `~/workspace/ai-agents/openclaw`)
- Listens on `127.0.0.1:18789` (WebSocket gateway) and `127.0.0.1:18791`
(browser control, token-auth)
- Hosts 9 plugins: acpx, browser, canvas, device-pair, **discord**,
file-transfer, memory-core, phone-control, talk-voice
- Bot identity: `@ppp` (Discord), Gmail watcher integrated
2. **Crestodian CLI** — `node openclaw.mjs` (default subcommand opens
the Crestodian agent TUI). Connects to the gateway over the WebSocket
on 18789. Used for human-in-the-loop ops (`restart gateway`, etc.).

`openclaw gateway status` reports `Service: systemd user (disabled)` but
**no actual systemd unit is installed** — the "disabled" label is misleading.
`openclaw gateway install` would create the unit; this has not been done
on shadow as of 2026-05-15. Practical consequence: **OpenClaw does not
auto-restart on host reboot**. After every reboot, manually:

```sh
tmux new-window -t ai-agents -n gateway 'cd ~/workspace/ai-agents/openclaw && node openclaw.mjs gateway run'
tmux new-window -t ai-agents -n crestodian 'cd ~/workspace/ai-agents/openclaw && node openclaw.mjs'
```

(or attach to tmux and start them by hand).

**Why:** This is just how it was set up — no one ran `gateway install`.
The user has not yet decided whether to systemd-ize it; raising the
question is fine, but don't `gateway install` without approval, since
that changes auth/bind defaults via the unit file.

**How to apply:** When the user says "openclaw is down" or Discord bot
`@ppp` stops responding, check `ss -tlnp | grep 18789` first. If empty,
the gateway tmux window is gone and needs the manual restart above.
Never kill an `openclaw` process whose ppid traces back to tmux session
`ai-agents` — see [[check-tmux-before-killing]].

**Auto-restart:** Two layers as of 2026-05-15:

1. **Gateway is now a systemd user unit** at
`~/.config/systemd/user/openclaw-gateway.service`
(created by `openclaw gateway install --force`). Runs
`/usr/bin/node /home/ubuntu/workspace/ai-agents/openclaw/dist/index.js
gateway --port 18789`, has `Restart=always`, lingers via
`loginctl enable-linger ubuntu`. Manage with
`systemctl --user {start,stop,status,restart} openclaw-gateway`.
Logs in journal: `journalctl --user -u openclaw-gateway -f`.
Note: `gateway install --force` killed the previously-running tmux
gateway process to take over the port — that's expected behavior.

2. **`@reboot` cron** still runs
`/home/ubuntu/workspace/ai-agents/openclaw-autostart.sh` (after 30 s).
It now defers to systemd for the gateway (`systemctl --user start
openclaw-gateway` if enabled, fallback to manual `gateway run` only
if no unit) and starts crestodian in tmux if no `crestodian*` window
exists. Idempotent — re-running it is safe.

Process identity gotcha: the crestodian binary rewrites its own
`process.title` to `openclaw`, so `pgrep` against `openclaw.mjs` does
not work. Use the tmux window name (`crestodian*`) to detect it
instead. Logs at `/home/ubuntu/workspace/ai-agents/openclaw-autostart.log`.