The OpenClaw gateway is the local server that powers everything: it hosts the Control UI, manages your channel adapters (WhatsApp, Telegram, Slack, Discord, Feishu, Line), routes messages between channels and AI providers, and stores conversation state on disk. Every OpenClaw deployment has exactly one gateway running.

This reference covers the openclaw gateway CLI commands — run, start, stop, restart, status — plus how the OpenClaw Desktop App (OpenClaw Easy) manages the gateway for you and what to do when things go wrong.

The 30-second summary

Command What it does When to use
openclaw gateway run Start gateway in foreground Debugging, dev work
openclaw gateway start Start the managed background daemon Daily use after installing daemon
openclaw gateway stop Stop the running gateway Before config-file edits, port conflicts
openclaw gateway restart Restart (re-read config) After channel / agent config changes
openclaw gateway restart --deep Full process recreation After runtime upgrade, when soft restart misbehaves
openclaw gateway status Check if the gateway is running, what port Troubleshooting connection issues
openclaw onboard --install-daemon Register gateway with launchd/Service First-time setup if you want auto-start

openclaw gateway run (foreground)

openclaw gateway run starts the gateway attached to your terminal. Logs stream to stdout. The process stays alive until you press Ctrl+C or the terminal closes.

$ openclaw gateway run
[gateway] Loading config from ~/.openclaw/config.json
[gateway] Listening on http://localhost:18789
[gateway] Control UI:  http://localhost:18790
[gateway] Channels:    whatsapp, telegram, slack
[gateway] Ready

Use this mode for:

  • Debugging — you see logs in real time
  • Single-session testing — when you do not want the gateway running after you close the terminal
  • Custom port / host — pass --port 19000 or --host 0.0.0.0 for non-default networking

For day-to-day use, prefer the background daemon mode below.

Background daemon mode

The OpenClaw Desktop App installs the gateway as a system service automatically. If you are using the CLI directly, install the daemon with:

$ openclaw onboard --install-daemon

On macOS this registers a launchd plist at ~/Library/LaunchAgents/com.openclaw.gateway.plist. On Windows it installs a Scheduled Task. After this:

  • openclaw gateway start — start the managed daemon
  • openclaw gateway stop — stop it
  • openclaw gateway status — check status, port, PID

The daemon auto-starts on login. To disable auto-start, run openclaw onboard --uninstall-daemon.

OpenClaw Easy users: the desktop app installs and manages the daemon automatically — you do not normally need to run any CLI commands. The "Start", "Stop", and "Restart Assistant" entries in the tray menu correspond to openclaw gateway start / stop / restart respectively.

Restarting after config changes

The gateway reads ~/.openclaw/config.json at startup and most channel/agent settings hot-reload on file change. But some changes require a full restart:

  • Added or removed a channel adapter
  • Changed the gateway port or host
  • Upgraded the OpenClaw runtime
  • Edited auth-profiles.json for an AI provider

The default restart is fast and keeps the process alive:

$ openclaw gateway restart

If that does not pick up your change — or if the gateway is in a weird state — use the deep restart:

$ openclaw gateway restart --deep

Deep restart fully terminates the daemon process and starts a fresh one. Slower (5–10 seconds) but always works.

Troubleshooting

Port 18789 already in use

The most common error. Another OpenClaw gateway is already running, or a previous one did not shut down cleanly.

# macOS / Linux — find what's on the port
$ lsof -ti:18789
12345

# Kill it (replace 12345 with the PID)
$ kill 12345

# Then restart
$ openclaw gateway start

On Windows, use netstat -ano | findstr 18789 to find the PID, then taskkill /F /PID <pid>.

Gateway connect failed: pairing required

The Control UI cannot connect because your browser / device has not been approved yet. Fix it with two commands — see our pairing-required guide.

Daemon does not auto-start on login

On macOS: check that the plist exists with ls ~/Library/LaunchAgents/com.openclaw.gateway.plist. If missing, re-run openclaw onboard --install-daemon. If present but not loaded, run launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist.

On Windows: open Task Scheduler and look for "Openclaw Gateway". If missing, re-run the install command.

Where are the logs?

  • macOS: ~/.openclaw/logs/gateway.log (or stdout in run mode)
  • Windows: %USERPROFILE%\.openclaw\logs\gateway.log

The OpenClaw Easy desktop app also exposes a "Show Logs Folder" entry in the tray menu — opens the logs directory directly in Finder / Explorer.

openclaw dashboard --no-open

When you start the gateway and want to skip the auto-opening of the Control UI in your browser, pass --no-open to the dashboard command. This is the typical mode when running headless or when the gateway is managed by the desktop app (which has its own embedded Control UI).

$ openclaw dashboard --no-open

Gateway vs Desktop App: which manages what

If you are using the OpenClaw Easy desktop app, the app handles all gateway lifecycle commands for you:

  • First-launch wizard runs openclaw onboard --install-daemon
  • The tray menu's "Start" / "Stop" / "Restart Assistant" entries call the corresponding gateway commands
  • Logs are accessible from "Show Logs Folder" in the tray menu
  • Crashes are reported in the in-app status indicator

If you are running OpenClaw via the CLI only, the commands in this reference are how you manage the gateway directly.

Related reading