327 lines
9.3 KiB
Markdown
327 lines
9.3 KiB
Markdown
---
|
||
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
|
||
```
|