OpenClaw Gateway and Operations

Prerequisites

• ✓The `openclaw` CLI installed and available on your PATH so you can run `openclaw gateway` commands.
• ✓Access to a machine where you can bind to TCP ports like `18789` and manage services (launchd, systemd, or Windows Scheduled Tasks).
• ✓Gateway configuration and auth settings prepared so `gateway.auth.token` / `gateway.auth.password` (or `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`) are defined when you bind beyond loopback.

Steps

1. 1

   Start the Gateway locally

   Bring up the Gateway process so it listens for WebSocket control, HTTP APIs, and the OpenAI-compatible endpoints on a single port. Start with the default port, add `--verbose` when you need more logs, and use `--force` when a stale listener blocks startup.

   bashCopy

   openclaw gateway --port 18789
   # debug/trace mirrored to stdio
   openclaw gateway --port 18789 --verbose
   # force-kill listener on selected port, then start
   openclaw gateway --force

2. 2

   Verify gateway health and logs

   Once the gateway is running, confirm it is actually healthy instead of assuming the process stayed up. Use the status commands to check runtime state and follow logs so you can catch auth issues, port conflicts, or config reload problems early.

   bashCopy

   openclaw gateway status
   openclaw status
   openclaw logs --follow

3. 3

   Validate channel readiness

   Check that your configured channels are reachable and ready, not just that the gateway process is alive. This probe runs live per-account checks when the gateway is reachable and falls back to config-only summaries when it is not, which helps you distinguish network issues from misconfiguration.

   bashCopy

   openclaw channels status --probe

4. 4

   Expose and use OpenAI-compatible endpoints

   Use the gateway’s OpenAI-compatible HTTP surface so existing tools like Open WebUI, LobeChat, and LibreChat can talk to your agents. All of these endpoints run on the main gateway port and share the same auth boundary, so you only need to wire clients to that single address.

   textCopy

   GET /v1/models
   GET /v1/models/{id}
   POST /v1/embeddings
   POST /v1/chat/completions
   POST /v1/responses

5. 5

   Control port, bind mode, and hot reload behavior

   Configure how the gateway binds to the network and how it reloads configuration so you avoid surprises in production. mode` lets you choose between no reloads, hot-only changes, restart-on-change, or the default hybrid behavior.

   textCopy

   Gateway port: --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
   Bind mode: CLI/override → gateway.bind → loopback
   
   gateway.reload.mode values:
   - off
   - hot
   - restart
   - hybrid

6. 6

   Install the gateway as a supervised service

   Move from ad-hoc runs to supervised service management so the gateway restarts automatically and survives logouts or reboots. Use the built-in install command and the appropriate systemd or launchd wiring, or drop in the provided unit file when you need a custom binary path.

   bashCopy

   openclaw gateway install
   openclaw gateway status
   openclaw gateway restart
   openclaw gateway stop
   
   openclaw gateway install
   systemctl --user enable --now openclaw-gateway[-<profile>].service
   openclaw gateway status
   
   sudo loginctl enable-linger <user>
   
   [Unit]
   Description=OpenClaw Gateway
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   ExecStart=/usr/local/bin/openclaw gateway --port 18789
   Restart=always
   RestartSec=5
   TimeoutStopSec=30
   TimeoutStartSec=30
   SuccessExitStatus=0 143
   KillMode=control-group
   
   [Install]
   WantedBy=default.target
   
   openclaw gateway install
   openclaw gateway status --json
   openclaw gateway restart
   openclaw gateway stop
   
   sudo systemctl daemon-reload
   sudo systemctl enable --now openclaw-gateway[-<profile>].service

7. 7

   Run operational checks for liveness and readiness

   Use the documented liveness and readiness checks so you can wire the gateway into monitoring or Kubernetes-style probes. Liveness focuses on the WebSocket protocol handshake, while readiness checks combine gateway status, channel probes, and health snapshots.

   bashCopy

   openclaw gateway status
   openclaw channels status --probe
   openclaw health

8. 8

   Run multiple gateways on one host when you need isolation

   If you need strict isolation or a rescue profile, run multiple gateways on the same machine with separate ports and state. Make sure each instance has unique config and state directories so they do not trample each other’s files.

   bashCopy

   OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
   OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

9. 9

   Use the dev profile for an isolated test gateway

   Spin up a development-only gateway profile when you want to experiment without touching your main config and state. The dev profile uses its own state/config and a base port of 19001, which keeps it safely separate from production-like runs.

   bashCopy

   openclaw --dev setup
   openclaw --dev gateway --allow-unconfigured
   openclaw --dev status

10. 10

    Access the gateway remotely over SSH

    When you run the gateway on a remote host, use an SSH tunnel if you do not have VPN in place. The tunnel exposes the remote gateway on your localhost, but it does not bypass gateway auth, so clients still need valid tokens or passwords.

    bashCopy

    ssh -N -L 18789:127.0.0.1:18789 user@host

Configuration

Troubleshooting

openclaw gateway --force

openclaw gateway status --deep
openclaw gateway probe

Frequently asked questions