---
name: node-remote-connect
description: 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](#step-2-node-operator---configure-and-connect) |
| 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

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

Remove colons to get the 64-character hex string:
```bash
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:
```bash
openclaw config get gateway.auth.token
```

If empty, check the environment variable:
```bash
echo $OPENCLAW_GATEWAY_TOKEN
```

**If both are empty**, generate or set a token:
```bash
# 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)**
```bash
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)**
```bash
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`:
```json
{
  "version": 1,
  "displayName": "My Node",
  "gateway": {
    "host": "<gateway-host>",
    "port": 18789,
    "tls": true,
    "tlsFingerprint": "<fingerprint>"
  }
}
```

Then run:
```bash
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:
```bash
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:
```bash
openclaw nodes status
```

Or list all devices (includes pending pairing):
```bash
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 方式（需要管理员权限）：**

```bash
# 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

```bash
# 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
```