Site icon Efficient Coder

OpenClaw Gateway Deployment Guide: Fix WebSocket Errors & Secure Device Pairing

高效码农

OpenClaw Gateway: A Complete Deployment Guide — Startup, Device Pairing, and Background Execution

This guide is based on real operational logs from an OpenClaw 2026.3.2 deployment. It walks through the full workflow: reading startup output, diagnosing WebSocket errors, managing device pairing, resolving file edit conflicts, and running the gateway as a persistent background process. Written for developers and sysadmins with working knowledge of Linux.

Table of Contents

What Is OpenClaw?

OpenClaw is an automation gateway tool — version 2026.3.2, build 85377a2 — designed to manage controlled connections between a host system and remote client devices. Its core capabilities include:

  • Exposing a WebSocket interface for client connections
  • Enforcing a device pairing and permission model (roles and scopes)
  • Running supporting services: browser control, heartbeat monitoring, and health checks
  • Token-based authentication to control which devices are allowed to connect

The short version: OpenClaw is an automation control gateway with a built-in device identity and authorization system. No device connects freely — every client must complete a pairing handshake before it can operate.

Reading the Gateway Startup Log

Start the gateway by running:

OPENCLAW_GATEWAY_TOKEN=your_token openclaw gateway

A healthy startup produces output like this:

[canvas]         host mounted at http://127.0.0.1:18789/__openclaw__/canvas/
[heartbeat]      started
[health-monitor] started (interval: 300s, startup-grace: 60s, channel-connect-grace: 120s)
[gateway]        agent model: bailian/qwen3.5-plus
[gateway]        listening on ws://127.0.0.1:18789, ws://[::1]:18789 (PID 2817088)
[gateway]        log file: /tmp/openclaw/openclaw-2026-03-12.log

Here is what each line means:

Log Entry What It Tells You
canvas host mounted The visual canvas UI is available at the listed local URL
heartbeat started The gateway’s internal liveness check is running
health-monitor started System health is checked every 300 seconds; a 60-second startup grace period applies
agent model The embedded AI agent is running on bailian/qwen3.5-plus
listening on ws://... The WebSocket server is ready on both IPv4 and IPv6 interfaces
log file Daily log files are written to /tmp/openclaw/

When all six services initialize without error, the gateway itself is healthy. Any connection failures you see after this point originate from the client side, not the gateway.

WebSocket Connection Failures

Shortly after startup, the logs showed repeated failures from the same IP address (111.123.86.0):

[ws] closed before connect ... code=4008 reason=connect failed
[ws] closed before connect ... code=1008 reason=pairing required
[ws] closed before connect ... code=1008 reason=pairing required

What Each Error Code Means

4008 — connect failed

This was the first connection attempt. The WebSocket handshake failed before it could be established. Likely causes include a missing or invalid token, incomplete connection parameters, or a network initialization issue on the client side.

1008 — pairing required

1008 is the WebSocket protocol’s “policy violation” status code. The client reached the gateway successfully, but the gateway refused to open a session because the device has not yet completed the pairing process.

A useful analogy: imagine showing up to an apartment building where the front desk can see you, but you have no key card and haven’t registered — you’re turned away at the door, not because the building has a problem, but because you haven’t gone through check-in.

Should You Be Concerned About the External IP?

The connection attempts came from:

  • IP: 111.123.86.0
  • Origin header: lx.fyqmfs.com

If this IP and domain are not from a device you are expecting to connect, do not approve its pairing request until you have verified the source.

Device Management

Running openclaw devices list outputs the current state of all known devices, split into two groups.

Pending Devices (Awaiting Approval)

┌──────────────────────────────────────┬───────────...┬──────────┬──────────────┬──────────┬────────┐
│ Request                              │ Device    ...│ Role     │ IP           │ Age      │ Flags  │
├──────────────────────────────────────┼───────────...┼──────────┼──────────────┼──────────┼────────┤
│ ea691760-d969-4c1c-a749-00b4916c6758 │ d10a96d1..  │ operator │              │ just now │ repair │
│ 0ead53e8-306d-475d-b6a1-6636585a6a6e │ 183e5fad..  │ operator │ 111.123.86.0 │ just now │        │
└──────────────────────────────────────┴───────────...┴──────────┴──────────────┴──────────┴────────┘

Key differences between the two pending devices:

Attribute Device 1 (ea691760) Device 2 (0ead53e8)
Source IP None (local/internal) 111.123.86.0 (external)
Flag repair None
Risk level Low — likely a local device reconnecting Requires verification before approval

What does the repair flag mean?

It indicates that this device was previously paired but has fallen into an abnormal state and needs to go through the pairing process again. It is not an error — it is a status flag indicating a re-authorization is needed.

Paired Devices (Already Approved)

│ d10a96d14a0c...  │ operator  │ operator.read  │ operator  │ (no IP) │

This device is fully paired with operator.read scope, but it is currently offline (no IP). Notice that its device hash matches the one in the Pending list with the repair flag — confirming that this device was previously authorized and is now requesting re-pairing.

Approving a Device

The Error

openclaw devices approve d10a96d14a0c74602441112fead85c6ab0fcf58597ba38929ebab0a2b96b102e
# Output: unknown requestId

Why It Failed

The approve command expects a Request ID, not a Device Hash. Both look like long strings of characters, which makes them easy to confuse.

How to tell them apart:

  • Request ID — UUID format, with hyphens: ea691760-d969-4c1c-a749-00b4916c6758
  • Device Hash — Continuous hex string, no hyphens: d10a96d14a0c74602...

The approve command always takes a value from the Request column of devices list output, not the Device column.

Correct Commands

To approve the local device with the repair flag:

openclaw devices approve ea691760-d969-4c1c-a749-00b4916c6758

To approve the external device at 111.123.86.0 (only after confirming it is trusted):

openclaw devices approve 0ead53e8-306d-475d-b6a1-6636585a6a6e

Before you approve: Both pending devices are requesting the operator role. That role carries real operational permissions. Verify the identity of any external device before granting it access.

File Edit Conflicts

During this deployment session, two classic vim warnings appeared when editing pending.json. Both are worth understanding.

Warning 1: File Modified by Another Process

WARNING: The file has been changed since reading it!!!
Do you really want to write to it (y/n)?

Why does this happen?

OpenClaw’s gateway process continuously updates pending.json to track device pairing requests. If you open the file in vim while the gateway is running, the file on disk may change between the time you opened it and the time you try to save. When vim detects this mismatch, it stops and asks for confirmation.

What should you do?

  • Type n — abort the write, go back to vim, and reload the file to see the latest content before making any changes
  • Type y — force-overwrite with your version, which will discard whatever the gateway wrote in the meantime

In most cases involving a live gateway process, choose n. Then inspect the current file state:

cat pending.json | python3 -m json.tool

Warning 2: E37 — Unsaved Changes on Exit

E37: No write since last change (add ! to override)

This is vim’s built-in safeguard. You modified the file but tried to quit without saving, and vim is refusing to close until you decide what to do with those changes.

Your options:

:q!    " Force quit — discards all changes (recommended for gateway-managed files)
:wq!   " Force save and quit — use only when you are sure you want to overwrite
:w     " Save without quitting

For pending.json specifically: Since this file is managed by the gateway at runtime, the safest choice is :q!. Use the openclaw devices CLI for all device management tasks instead of editing JSON directly.

Running the Gateway in the Background

By default, the gateway runs in the foreground. Closing the terminal stops it. For a server environment, you need it to keep running persistently.

Option 1: nohup (Simplest)

nohup env OPENCLAW_GATEWAY_TOKEN=your_token openclaw gateway \
  &> /tmp/openclaw/gateway.log &
echo "PID: $!"

How to manage it:

# Follow the log in real time
tail -f /tmp/openclaw/gateway.log

# Stop the process
kill <PID>

Option 2: screen (Good for Interactive Debugging)

# Start in a detached screen session
screen -dmS openclaw openclaw gateway

# Reattach to view live output
screen -r openclaw

# Detach without stopping: Ctrl+A, then D

Option 3: tmux (Most Flexible)

# Start in a detached tmux session
tmux new-session -d -s openclaw 'openclaw gateway'

# Reattach to view live output
tmux attach -t openclaw

# Detach without stopping: Ctrl+B, then D

Comparison at a Glance

Method Requires Install Log Access Interactive Best For
nohup No tail -f No Production background runs
screen Yes Reattach to session Yes Debugging while running
tmux Yes Reattach to session Full Multi-service management

Note: None of these three methods survive a server reboot. If you need the gateway to restart automatically after a reboot, register it as a systemd service.

Security Considerations

One issue from the deployment session deserves direct attention.

The gateway was started with the token exposed inline in the command:

OPENCLAW_GATEWAY_TOKEN=99e9cc5b8520e714f44269decfab5e8efbf48b3e7e291369 openclaw gateway

If this token appears in a screenshot, log file, chat history, or version-controlled repository, it should be treated as compromised. The response steps are:

  1. Stop the current gateway process
  2. Rotate the token (follow OpenClaw’s token regeneration procedure)
  3. Restart the gateway with the new token
  4. Review the paired devices list for any unauthorized entries that may have slipped through

A safer way to pass credentials is through an environment file:

# Write token to a protected file
echo "OPENCLAW_GATEWAY_TOKEN=your_token" > /etc/openclaw.env
chmod 600 /etc/openclaw.env

# Load and launch
source /etc/openclaw.env && \
  nohup openclaw gateway &> /tmp/openclaw/gateway.log &

This keeps the token out of shell history and process listings.

FAQ

Q: My client keeps getting pairing required errors even though the gateway is running. Is something misconfigured?

A: No — this is expected behavior. The error means the client reached the gateway but has not yet been approved. An administrator needs to run openclaw devices approve <requestId> to authorize it. Once approved, the client can establish a full session.

Q: The approve command returns unknown requestId. What am I doing wrong?

A: You are likely passing a Device Hash instead of a Request ID. Run openclaw devices list and look at the first column, labeled “Request”. The value there is a UUID with hyphens — that is the correct argument for approve.

Q: Is it safe to manually edit pending.json?

A: Technically possible, but not recommended. The gateway maintains this file at runtime. Manual edits risk data conflicts, which is exactly what the vim warning is flagging. Use the openclaw devices command-line interface instead.

Q: How do I force-quit vim when it won’t let me exit?

A: Run :q! to exit and discard your changes. If you want to save first, use :wq!.

Q: Where are the gateway logs stored by default?

A: Based on startup output, logs are written to /tmp/openclaw/openclaw-YYYY-MM-DD.log, with one file created per day.

Q: The repair flag showed up on a device. Is that a security issue?

A: Not by itself. The repair flag means the device was previously paired and needs re-authorization. Before approving, confirm that the device hash belongs to a machine you manage.

Q: Will the gateway restart automatically if the server reboots?

A: No. nohup, screen, and tmux all keep processes running through terminal disconnects, but none of them survive a server reboot. For persistent startup, configure the gateway as a systemd service.

Summary

The full OpenClaw deployment workflow breaks down into a clear sequence:

  1. Start the gateway — confirm canvas, heartbeat, and health-monitor all initialize cleanly
  2. Interpret connection errors — distinguish between 4008 (failed handshake) and 1008 (pairing not yet completed)
  3. Audit pending devices — verify the identity of each device before approving, especially those connecting from external IPs
  4. Use the right ID — approve takes a Request ID (UUID with hyphens), not a Device Hash
  5. Avoid direct file edits — use the CLI for device management; do not hand-edit gateway-managed JSON files while the process is live
  6. Choose a background method — nohup for simplicity, screen or tmux when you need to reattach
  7. Protect your credentials — never expose the gateway token in plain text; rotate it immediately if it leaks

Following these steps in order handles the most common issues you are likely to encounter in a real OpenClaw deployment.

Exit mobile version