Stopping the OpenClaw Gateway cleanly matters because the process holds open WebSocket channels, active agent sessions, and session state files under ~/.openclaw. Killing it the wrong way can leave orphaned subagents, drop queued webhooks, or leave the listener port bound until you intervene manually.
Stop a managed Gateway service
If the Gateway was installed as a background service through openclaw gateway install, it runs under launchd on macOS, a systemd user unit on Linux, or a Scheduled Task on Windows. The CLI wraps all three behind a single command.
Step 1: Open a terminal on the host where the Gateway is running. Remote-mode setups require you to run the command on the actual Gateway host, not the client machine, because the service lives there.
Step 2: Run the stop command. This asks the service manager to terminate the Gateway process and returns when the service reports stopped.
openclaw gateway stop
Step 3: Confirm it actually stopped. Use openclaw gateway status to check both the service state and whether the WebSocket RPC port still answers. A stopped Gateway should show the service as inactive and the RPC probe as unreachable.
openclaw gateway status
For scripting, add --json to either command. The lifecycle commands (start, stop, restart, uninstall) all accept --json. See the Gateway CLI reference for the full option list.
Stop a foreground Gateway process
When you start the Gateway directly with openclaw gateway or openclaw gateway run, it runs in the foreground and is bound to that terminal. The service-manager path will not help here because there is no managed service to stop.
Step 1: Focus the terminal running the Gateway. If you wrapped it in a TUI or raw-mode input layer, be aware that SIGINT and SIGTERM do not restore custom terminal state on their own.
Step 2: Send SIGINT with Ctrl+C. The Gateway catches SIGINT and SIGTERM and shuts down the process. SIGTERM from kill <pid> works the same way if the process is detached from your current TTY.
# From another terminal, if needed:
kill $(pgrep -f "openclaw gateway")
Avoid kill -9 unless the process is truly wedged. A SIGKILL bypasses the graceful shutdown path, which can leave channel connections and session files in an inconsistent state.
Stop via the service manager directly
If the openclaw CLI is not installed on the host but the Gateway service keeps running, talk to the service manager yourself. The default identifiers depend on your OS and whether you used a profile (--profile or OPENCLAW_PROFILE).
| Platform | Default identifier | Stop command |
|---|---|---|
| macOS (launchd) | ai.openclaw.gateway |
launchctl bootout gui/$UID/ai.openclaw.gateway |
| Linux (systemd user) | openclaw-gateway.service |
systemctl --user stop openclaw-gateway.service |
| Windows (Scheduled Task) | OpenClaw Gateway |
schtasks /End /TN "OpenClaw Gateway" |
If you used a profile, the identifiers become ai.openclaw.<profile>, openclaw-gateway-<profile>.service, or OpenClaw Gateway (<profile>) respectively. Legacy macOS installs may still carry com.openclaw.* labels.
Verify the Gateway is actually stopped
A stopped process should satisfy two conditions: the service manager reports it inactive, and the RPC endpoint no longer answers. Check both to avoid the common case where one Gateway process dies but a second one is still listening on the port.
openclaw gateway status --deep
The --deep flag scans for extra launchd, systemd, and schtasks installs. If multiple Gateway-like services appear, the output prints cleanup hints. Most setups should run exactly one Gateway per machine; multiple are only expected when you intentionally use isolated profiles or ports.
You can also probe the WebSocket endpoint directly. A healthy stopped Gateway should refuse the connection.
openclaw gateway probe
If Reachable: yes still appears after a stop, another listener is bound to the port (typically 18789). Use --deep status output to locate and remove the duplicate service.
What to do if stop hangs or fails
The /stop slash command in a chat channel is a different thing from openclaw gateway stop. The slash command ends the current agent session; the CLI command stops the Gateway process. Mixing them up is a common source of confusion when a run appears to hang.
Inside the TUI, press Esc or use /abort to cancel the active run without touching the Gateway. If /stop is ignored by the Gateway, check that commands.allowFrom includes your sender ID; commands from senders outside the allowlist are dropped. For long-running subagent work, list them with /subagents list before retrying a stop.
If the Gateway process itself refuses to terminate and openclaw gateway stop returns without effect, fall back to the service manager commands in the table above, then as a last resort send SIGKILL to the PID. Expect to check for stale session locks in ~/.openclaw afterwards.
Stop as part of an uninstall
When you plan to remove OpenClaw entirely, stop the Gateway first so the uninstaller can remove the service definition cleanly. The official uninstall flow runs these in order.
openclaw gateway stop
openclaw gateway uninstall
After gateway uninstall, the launchd/systemd/schtasks entry is removed, but the state directory at ~/.openclaw and any workspace files remain until you delete them yourself. If you used profiles, repeat the sequence for each profile's state directory.
Note: SIGUSR1 triggers an in-process restart when commands.restart is enabled (the default). Setting commands.restart: false blocks manual restarts while still allowing config and tool updates to apply — useful on production hosts where you want stop and start to be explicit, operator-driven actions.