1. OpenClaw Gateway Operations Manual

The Gateway is a resident process within the OpenClaw ecosystem: it is responsible for maintaining connections across various messaging channels, hosting the control and event planes, and serving as the unified entry point for session, routing, and channel state data. Simply put: whether you can "connect to OpenClaw," whether the console opens correctly, and whether incoming messages are received often depend entirely on whether the Gateway is running normally.

1. When You Need to Pay Attention to the Gateway

In most cases, you simply need to ensure it runs stably; you only need to specifically inspect or learn about the Gateway in the following scenarios:

• You frequently encounter errors when opening the console via a browser on a Jetson device, and you are planning to switch to using the TUI or remote access.
• You have modified the configuration but "feel like the changes haven't taken effect," leading you to suspect that a hot reload or restart was not triggered.
• You wish to expose the console to your local area network (LAN) or access it remotely via SSH or Tailscale.
• You intend to implement multi-instance isolation (e.g., for a "rescue bot" or redundancy purposes).
• You encounter port conflicts, the process fails to start, or the service "appears to be installed but isn't running."

2. The Quickest Way to Start (Locally)

Execute the following command on the Gateway host (e.g., a Jetson device):

xxxxxxxxxx
openclaw gateway

Common Parameters:

​x
# Print more comprehensive debugging/tracing information to the current terminal (useful for troubleshooting).
openclaw gateway --port 18789 --verbose
​
# If the port is already in use, attempt to terminate the listener currently occupying the port and force the Gateway to start.
openclaw gateway --port 18789 --force

Port Priority (from highest to lowest): --port > OPENCLAW_GATEWAY_PORT > gateway.port > Default (18789).

3. What "External Interfaces" Does the Gateway Provide?

A single port (default: 18789) simultaneously provides both the WebSocket control plane and HTTP services (including the control interface, hooks, A2UI, etc.); this configuration is referred to as "single-port multiplexing." Key endpoints you will frequently use:

• Local Console: http://127.0.0.1:18789/
• OpenAI Chat Completions Compatible API: /v1/chat/completions
• OpenResponses API: /v1/responses
• Tool Invocation API: /tools/invoke

Additionally, the gateway defaults to launching a Canvas static file service (default port: 18793) to serve editable HTML/A2UI resources (served by default from ~/.openclaw/workspace/canvas). To disable this, you can set canvasHost.enabled=false or OPENCLAW_SKIP_CANVAS_HOST=1.

4. Hot Reloading and "Restart Required" Changes

The gateway monitors ~/.openclaw/openclaw.json (or the path specified by OPENCLAW_CONFIG_PATH); configuration updates are typically applied automatically. The default reload mode is gateway.reload.mode="hybrid": safe changes are applied via hot reload, while critical changes will trigger a restart.

You can explicitly configure the reload behavior:

xxxxxxxxxx
{
  "gateway": {
    "reload": { "mode": "hybrid", "debounceMs": 300 }
  }
}

Practical Tips:

• Changes to business-related configurations—such as models, agents, routes, etc.—usually do not require you to manually restart the gateway.
• Changes to gateway.* settings (port, binding, authentication, TLS, HTTP, etc.) are considered infrastructure-level changes and are more likely to trigger a restart.

5. Authentication and Remote Access (Common Pitfalls)

5.1 Gateway Authentication (Token/Password)

Gateway authentication is enabled by default: you can set gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN) or gateway.auth.password. When connecting, clients must include the token or password within connect.params.auth.token/password.

If you use the setup wizard, a token will typically be generated by default (even if the gateway is bound only to the loopback interface).

5.2 Recommended Method for Remote Access: Tunnel First, Then Access

Most Recommended: Tailscale / VPN. Second Best: SSH Tunneling. Example (mapping remote port 18789 to local port 18789):

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

You can then access the service locally via:

• Web: http://127.0.0.1:18789/
• WS: ws://127.0.0.1:18789

Note: Even when using a tunnel, if the gateway is configured to require a token, the client must still provide the token in order to establish a connection.

5.3 Console Fails to Open via Pure HTTP ("device identity required")

If you attempt to open the console over a local area network (LAN) using http://<lan-ip>:18789/, your browser may be operating within an "insecure context." This restricts WebCrypto functionality, preventing the generation of a device identity and resulting in device identity required or connect failed errors. [^gateway_troubleshooting]

Recommended solutions (in order of preference):

• Access locally: http://127.0.0.1:18789/
• For remote access scenarios, use Tailscale Serve to provide HTTPS.
• If you must use HTTP, enable gateway.controlUi.allowInsecureAuth: true and use a gateway token (this utilizes "token-only" mode, bypassing the device identity/pairing process). [^gateway_troubleshooting]

6. Multiple Instances and "Rescue Bot" Mode

Attempt this operation only when necessary.

Typically, running a single gateway instance per host is sufficient. Running multiple gateway instances is recommended only when redundancy or strong isolation (e.g., for a "rescue bot") is required. The core principle of multi-instance operation is "total isolation + no conflicts":

• A distinct gateway.port
• A distinct OPENCLAW_CONFIG_PATH
• A distinct OPENCLAW_STATE_DIR
• A distinct workspace (agents.defaults.workspace)

Using the dev configuration profile, you can quickly launch a fully isolated development instance without affecting your main environment:

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

7. Troubleshooting Steps: Pinpointing Most Issues

7.1 First, Check the Status

Execute the following commands in order: [^gateway_troubleshooting]

xxxxxxxxxx
openclaw status
openclaw status --all
openclaw status --deep

Common supplementary commands:

xxxxxxxxxx
openclaw gateway probe
openclaw channels status --probe
openclaw gateway status
openclaw logs --follow
openclaw doctor

7.2 Gateway Fails to Start: Configuration Validation Failure

OpenClaw configurations undergo strict schema validation: unknown keys, type mismatches, or invalid values ​​can all cause the gateway to refuse to start.

When validation fails, typically only diagnostic commands remain available (e.g., openclaw doctor / logs / health / status). It is recommended to proceed directly with:

xxxxxxxxxx
openclaw doctor

7.3 Common Symptom: Service Installed but Not Actually Running

If you have installed the gateway as a system service using tools like systemd, launchd, or schtasks, a status indicating "loaded" or "installed" does not necessarily mean the actual process is currently running. Prioritize checking the following: [^gateway_troubleshooting]

openclaw gateway status
openclaw logs --follow