#Node and extension relay

1 messages · Page 1 of 1 (latest)

gilded martenBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> âś… Mark Solution

devout radishBOT
#

To make a VPS Gateway drive your desktop Chrome, the “known-good” setup is:

  1. Desktop runs a node host (so the Gateway can proxy browser + exec to your desktop)
  2. Desktop Chrome runs the Browser Relay extension (attached per-tab via the toolbar button)
  3. Desktop runs the local relay server on 127.0.0.1:18792 (this is why the node host must be on the same machine as Chrome)

Docs (worth having open while you do it):

A) Get the desktop node connected to the VPS Gateway

#

Step 0: versions (important)

Run on both machines and make sure they’re current / compatible:

openclaw --version

Step 1: make the VPS Gateway WebSocket reachable from the desktop

You have two common options:

Option 1 (easiest, no gateway rebind): SSH tunnel

# On your desktop (keep running):
ssh -N -L 18790:127.0.0.1:18789 user@your-vps

Now your desktop can reach the VPS gateway WS at 127.0.0.1:18790.

Option 2: Tailnet (Tailscale)

#

Put both machines on the same tailnet and connect to the VPS via its tailnet IP/hostname.

Step 2: start the node host on the desktop

On the VPS, get the gateway token (don’t paste it publicly):

openclaw config get gateway.auth.token

On the desktop, set the token and run the node host:

If using the SSH tunnel (recommended first try):

export OPENCLAW_GATEWAY_TOKEN="…token-from-vps…"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Desktop Node"

If using tailnet direct:

# 
export OPENCLAW_GATEWAY_TOKEN="…token-from-vps…"
openclaw node run --host <vps-tailnet-ip-or-hostname> --port 18789 --display-name "Desktop Node"

Step 3: approve pairing on the VPS

On the VPS:

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

You want the node to show as connected/paired.

B) Install + use the Chrome “Browser Relay” extension (on the desktop)

#

Step 1: install the unpacked extension to a stable path

On the desktop:

openclaw browser extension install
openclaw browser extension path

Then in Chrome:

  • Go to chrome://extensions
  • Enable Developer mode
  • Load unpacked → select the folder printed by openclaw browser extension path
  • Pin the extension

Step 2: set extension Options (token + port)

Open the extension Options and set:

  • Port: 18792 (default)
  • Gateway token: same value as gateway.auth.token / OPENCLAW_GATEWAY_TOKEN
#

Badge meanings:

  • ON = attached and ready
  • ! = relay not reachable or token wrong (most common: node host not running, or token mismatch)

Step 3: attach a tab

Open the tab you want controlled → click the extension icon → badge should go ON.

Step 4: quick test from CLI

On the machine where your CLI points at the VPS Gateway:

openclaw browser --browser-profile chrome tabs

Common failure modes (the usual culprits)

#
  • Extension shows !: node host isn’t running on the desktop, or the token in extension Options doesn’t match gateway.auth.token.
  • Gateway can’t see/approve the node: the desktop can’t reach the VPS WebSocket (SSH tunnel down, wrong port, tailnet routing).
  • Browser calls go to the “wrong” node (if you have multiple nodes): you may need to pin which node handles browser proxying (docs mention gateway.nodes.browser.node / gateway.nodes.browser.mode).
  • Sandboxed agent sessions: extension takeover needs host browser control; if your agent is sandboxed you may need agents.defaults.sandbox.browser.allowHostControl: true (see chrome extension doc).

If you paste 3 things here, I can tell you exactly where it’s failing

(Please redact tokens)

  1. Desktop: the exact output/error from running openclaw node run ...
  2. VPS: openclaw devices list + openclaw nodes status
  3. What the Chrome extension badge shows (!, …, or never goes ON) and any message shown in extension Options validation
devout radishBOT
#

Two fast checks will tell us exactly what’s wrong here. Right now there are only 2 realistic possibilities:

  1. /opt/homebrew/bin/openclaw does not actually exist (npm didn’t create the binlink), or
  2. it exists, but your current shell PATH isn’t what you think (or you’re using a different node/npm than the one that wrote to /opt/homebrew).

Run these on the Mac and paste the output (they’re safe; redact nothing except tokens if any appear, but these shouldn’t):

# 1) Does the binary exist?
ls -la /opt/homebrew/bin/openclaw
ls -la /opt/homebrew/bin | egrep -i 'openclaw|clawdbot' || true

# 2) If it exists, can it run directly?
/opt/homebrew/bin/openclaw --version

# 3) Is /opt/homebrew/bin in *this* shell's PATH, and does zsh resolve it?
# 
echo "$PATH" | tr ':' '\n' | nl -ba | sed -n '1,25p'
hash -r
command -v openclaw
type -a openclaw || true

# 4) Confirm which node/npm you used for the install (nvm vs brew mismatch is common)
which -a node
which -a npm
npm prefix -g
npm bin -g

While we debug, here’s the “make progress right now” workaround

If ls -la /opt/homebrew/bin/openclaw shows the file exists, you can immediately proceed with node setup by using the full path:

# 
/opt/homebrew/bin/openclaw node run ...
/opt/homebrew/bin/openclaw browser extension install

Most common outcomes + fixes

  • If ls says “No such file” → it didn’t actually install the binlink into /opt/homebrew/bin (often because the install happened under a different npm/prefix). The which node/npm + npm prefix -g output will pinpoint this.
  • If direct /opt/homebrew/bin/openclaw --version works but command -v openclaw is empty → your current PATH dump will show where /opt/homebrew/bin is missing/overridden (often .zprofile/frameworks resetting PATH after your export).

Paste the outputs and I’ll tell you the exact fix in one shot.

devout radishBOT
#

In v2026.2.21-2 there is no openclaw browser serve (and no standalone “start relay” command).

The thing that serves http://127.0.0.1:18792 is the Chrome extension relay server, and it’s started automatically by:

  • the Gateway (when the Gateway runs on the same machine as Chrome), or
  • a headless node host on the Chrome machine (when the Gateway is remote)

So for a remote Gateway-on-VPS setup, the “correct command” on your Mac is:

# on the Mac (same machine as Chrome)
export OPENCLAW_GATEWAY_TOKEN="<<the VPS gateway.auth.token>>"
openclaw node run --host <gateway-host-or-local-tunnel-host> --port <gateway-ws-port>

A couple of gotchas that match your symptom (red ! / “Relay not reachable/authenticated”):

#
  1. Make sure this node is actually the headless node host (CLI) and has browser capability.
    Run on the VPS:
openclaw nodes describe --node "My Desktop"

You should see it advertising a browser capability (look for caps including browser and/or command browser.proxy). If it’s just the macOS app node, you may not have the browser proxy/relay.

  1. The relay server needs the token on the Mac too (it authenticates with the same gateway.auth.token).
    It will use OPENCLAW_GATEWAY_TOKEN (recommended) or gateway.auth.token from the Mac’s ~/.openclaw/openclaw.json. If the node host can connect but the relay can’t start/auth, this is usually why.

  2. The relay may not spin up until the first browser-proxy call hits the node.
    After the node host is running, trigger it once from the VPS (or any client connected to the VPS gateway) with something like:

openclaw browser profiles
# or
openclaw browser --browser-profile chrome status
#

That output is the smoking gun: you ran openclaw nodes describe … on your Mac, and your CLI is trying to talk to a local gateway (Gateway target: ws://127.0…, Bind: loopback, config under /Users/.../.openclaw/openclaw.json). Since there’s no gateway WS there (or it’s not reachable), the socket dies with 1006.

Fix: point the CLI at the VPS Gateway (or at your SSH tunnel to it)

nodes describe is a gateway RPC, so it must hit the VPS gateway WS.

If you have an SSH tunnel from the Mac to the VPS gateway WS port:

# Terminal A (keep running)
ssh -N -L 18790:127.0.0.1:18789 user@<your-vps>

# Terminal B
openclaw nodes describe \
--url ws://127.0.0.1:18790 \
--token "<gateway.auth.token>" \
--node "My Desktop"
#

Or, if the VPS gateway WS is directly reachable on your tailnet:

openclaw nodes describe \
--url ws://<vps-tailnet-hostname>:18789 \
--token "<gateway.auth.token>" \
--node "My Desktop"

(Those flags are real for nodes in this version: openclaw nodes describe --help shows --url and --token.)

Why this matters for the Chrome relay

Your extension error is local (http://127.0.0.1:18792), but the relay usually only comes up when the browser machine’s node host receives a browser-proxy call from the VPS gateway. If your CLI isn’t actually connected to the VPS gateway, you’re never triggering that path.

Next thing to check (once nodes describe works)

Paste the non-sensitive parts of the VPS-side:

#
  • openclaw nodes describe --node "My Desktop" --url … --token …

Specifically: does it show the node advertising browser capability (caps including browser / command like browser.proxy)?
If not, you’re probably connected via the macOS app node, but you still need a headless node host (openclaw node run …) on the Mac for extension relay/browser proxy.

(And quick local sanity check on the Mac: curl http://127.0.0.1:18792/extension/status — if it’s “connection refused”, the relay server truly isn’t running.)