RDK-Claw-Cloud-Device/rdk-claw/node-remote-connect/SKILL.md

name

description

node-remote-connect

Connect an OpenClaw CLI node to a remote gateway over TLS when mDNS/Bonjour discovery is unavailable. Use when gateway and node are on different networks, gateway uses self-signed TLS certificates, and node requires explicit --tls-fingerprint and token configuration. Triggers on phrases like "connect node to remote gateway", "node can't find gateway", "tls fingerprint mismatch", "node authentication failed", or "gateway token setup".

Node Remote Connect

Connect a headless CLI node to a remote gateway when both are on different networks and the gateway uses TLS with a self-signed certificate.

Overview

This skill guides two operators through a secure setup:

1. Gateway operator retrieves: gateway IP/host, port, TLS fingerprint, and auth token
2. Node operator configures the node with those credentials and establishes the connection

Who Are You?

If you...	You are the...	Start at
Control the gateway server (running openclaw gateway)	Gateway Operator	Step 1
Want to connect a node/client to a remote gateway	Node Operator	Step 2
Both are on the same machine	Local setup, use mDNS auto-discovery instead	N/A

💡 Tip: Gateway operators typically have access to the server running OpenClaw gateway. Node operators receive credentials from the gateway operator.

Prerequisites Validation

Before starting, confirm these prerequisites are met:

On Gateway side:

• Gateway is running with TLS enabled (gateway.tls.enabled: true)
• TLS certificate exists at ~/.openclaw/gateway/tls/gateway-cert.pem
• Auth token is configured (gateway.auth.token or OPENCLAW_GATEWAY_TOKEN env var)

On Node side:

• openclaw CLI is installed and accessible
• Node can reach the gateway host:port (firewall allows TCP)

If any prerequisite is missing, stop and resolve it first.

---

Step 1: Gateway Operator - Retrieve Credentials

Execute on the gateway machine.

1.1 Get TLS Fingerprint

openssl x509 -in ~/.openclaw/gateway/tls/gateway-cert.pem -fingerprint -sha256 -noout

Remove colons to get the 64-character hex string:

openssl x509 -in ~/.openclaw/gateway/tls/gateway-cert.pem -fingerprint -sha256 -noout | tr -d ':' | cut -d= -f2

Example output: 85544cd42bcfa0b15e50c3f0f6f0b274d89f4ed292119918494290fad3582ea7

1.2 Get Auth Token

Check if token exists in config:

openclaw config get gateway.auth.token

If empty, check the environment variable:

echo $OPENCLAW_GATEWAY_TOKEN

If both are empty, generate or set a token:

# Generate a secure token
openssl rand -hex 32

# Or set via openclaw config (if supported)
openclaw config set gateway.auth.token "<generated-token>"

1.3 Share with Node Operator

Provide these values:

• Gateway host/IP: the IP or hostname node will connect to
• Port: default is 18789
• TLS fingerprint: the 64-char hex string (no colons)
• Token: the auth token value

---

Step 2: Node Operator - Configure and Connect

你是 Node 操作者，请先确认已从 Gateway 操作者处获得以下信息：

2.0 接收信息检查表

在开始之前，请确认你已收到以下四项信息：

信息项	示例值	是否已收到？
Gateway 主机地址	203.0.113.50 或 gateway.example.com	☐
端口号	18789（默认）	☐
TLS 指纹	85544cd42bcfa...（64位十六进制，无冒号）	☐
认证 Token	a1b2c3d4e5f6...	☐

⚠️ 如果任何一项缺失，请联系 Gateway 操作者获取。缺少信息将导致连接失败。

2.1 选择连接方式

Method A: CLI flags (temporary, for testing)

export OPENCLAW_GATEWAY_TOKEN="<token>"
openclaw node run \
  --host <gateway-host> \
  --port 18789 \
  --tls \
  --tls-fingerprint "<fingerprint>" \
  --display-name "My Node"

Method B: Install as system service (permanent)

export OPENCLAW_GATEWAY_TOKEN="<token>"
openclaw node install \
  --host <gateway-host> \
  --port 18789 \
  --tls \
  --tls-fingerprint "<fingerprint>" \
  --display-name "My Node"

Method C: Pre-configure via ~/.openclaw/node.json (then run with no flags)

Edit ~/.openclaw/node.json:

{
  "version": 1,
  "displayName": "My Node",
  "gateway": {
    "host": "<gateway-host>",
    "port": 18789,
    "tls": true,
    "tlsFingerprint": "<fingerprint>"
  }
}

Then run:

export OPENCLAW_GATEWAY_TOKEN="<token>"
openclaw node run

2.2 Validate Required Parameters

Before running, verify each parameter:

Parameter	Where to get it	Example
gateway-host	Gateway operator	203.0.113.50 or gateway.example.com
port	Usually 18789	18789
fingerprint	From gateway cert	85544cd42bcfa0b15e50c3f0f6f0b274d89f4ed292119918494290fad3582ea7
token	From gateway config/env	a1b2c3d4e5f6...

Critical checks:

• Fingerprint is exactly 64 hex characters (no colons)
• Token is not empty
• Host is reachable: nc -zv <gateway-host> 18789 or telnet <gateway-host> 18789

---

Step 3: Verify Connection

3.1 On Node Side

Check if node process started successfully:

openclaw node status

Or view logs if running in foreground - look for:

• Connected to gateway - success
• tls fingerprint mismatch - fingerprint incorrect
• authentication failed - token incorrect
• connection refused - host:port unreachable

3.2 On Gateway Side

List connected devices:

openclaw nodes status

Or list all devices (includes pending pairing):

openclaw devices list

3.3 Pairing (First Connection Only)

If this is the first connection, the node appears as a pending pairing request.

🔐 重要：设备审批是高权限操作

如果你当前在 Channel（聊天/协作空间）中操作，建议切换到 WebUI 完成审批：

1. 打开 Gateway WebUI：https://<gateway-host>:18790（默认端口）
2. 导航到 设备管理 或 Nodes 页面
3. 找到待审批的 Node，点击 Approve / 批准

WebUI 提供更直观的设备信息展示和审批流程。

CLI 方式（需要管理员权限）：

# View pending requests
openclaw devices list

# Approve the node (replace <requestId> with actual ID)
openclaw devices approve <requestId>

# Or approve the most recent pending request
openclaw devices approve --latest

After approval, the node establishes full connection.

---

Troubleshooting

TLS Fingerprint Mismatch

Symptom: gateway tls fingerprint mismatch

Causes:

1. Fingerprint from wrong certificate
2. Fingerprint still has colons
3. Gateway restarted and regenerated cert (fingerprint changed)

Fix:

1. Re-fetch fingerprint from gateway: openssl x509 -in ~/.openclaw/gateway/tls/gateway-cert.pem -fingerprint -sha256 -noout | tr -d ':' | cut -d= -f2
2. Verify fingerprint is 64 chars with no colons
3. If cert was regenerated, share new fingerprint with node operator

Authentication Failed

Symptom: authentication failed or unauthorized

Causes:

1. Token is wrong or expired
2. Token not set (empty string)
3. Local mode ignores gateway.remote.token

Fix:

1. Verify token on gateway: openclaw config get gateway.auth.token
2. Verify token on node: echo $OPENCLAW_GATEWAY_TOKEN
3. For local mode nodes: use OPENCLAW_GATEWAY_TOKEN env var, not gateway.remote.token

Connection Refused

Symptom: ECONNREFUSED or connection refused

Causes:

1. Gateway not running on remote host
2. Firewall blocking port 18789
3. Wrong host or port

Fix:

1. Verify gateway is running on gateway machine
2. Check firewall: nc -zv <gateway-host> 18789
3. Verify host:port from gateway operator

Node Not Showing in nodes status

Symptom: Node appears to run but openclaw nodes status shows nothing

Causes:

1. Node connected but not yet paired
2. Node connected to wrong gateway
3. Token/auth worked but system.run not authorized

Fix:

1. Check openclaw devices list for pending pairing request
2. Approve with openclaw devices approve <requestId>
3. Verify node is connecting to correct gateway URL

---

Reference: Config File Locations

Purpose	File Path
Gateway TLS cert	~/.openclaw/gateway/tls/gateway-cert.pem
Gateway TLS key	~/.openclaw/gateway/tls/gateway-key.pem
Gateway config	~/.openclaw/openclaw.json
Gateway TLS fingerprint	Computed from cert via X509Certificate.fingerprint256
Node config	~/.openclaw/node.json
Node gateway creds	OPENCLAW_GATEWAY_TOKEN env var

Reference: CLI Commands

# Node run (foreground)
openclaw node run --host <host> --port <port> --tls --tls-fingerprint <fp>

# Node install (service)
openclaw node install --host <host> --port <port> --tls --tls-fingerprint <fp>

# Node status
openclaw node status

# Gateway: list devices (including pending pairing)
openclaw devices list

# Gateway: approve device
openclaw devices approve <requestId>

# Gateway: list nodes
openclaw nodes status

# Gateway: check TLS config
openclaw config get gateway.tls.enabled
openclaw config get gateway.auth.mode