Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Bug]: Custom node ID via `openclaw run node --node-id` not honored [2 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#61569•Fetched 2026-04-08 02:57:13
View on GitHub
Comments
0
Participants
1
Timeline
6
Reactions
0
Author
erhhungerhhung
Participants
erhhungerhhung
Timeline (top)
cross-referenced ×2labeled ×2referenced ×1renamed ×1

After clearing all paired and pending nodes and devices on the gateway (deleting ~/.openclaw/devices/* and ~/.openclaw/nodes/*), and re-pairing my Mac companion app and independently launched node started by running:

$ openclaw node run --help

🦞 OpenClaw 2026.4.2 (d74a122) — Your AI assistant, now without the $3,499 headset.

Usage: openclaw node run [options]

Run the headless node host (foreground)

Options:
  --display-name <name>       Override node display name
  -h, --help                  Display help for command
  --host <host>               Gateway host
  --node-id <id>              Override node id (clears pairing token)
  --port <port>               Gateway port
  --tls                       Use TLS for the gateway connection (default: false)
  --tls-fingerprint <sha256>  Expected TLS certificate fingerprint (sha256)

$ openclaw node run --node-id my-mac-node --host openclaw.example.local --port 443 --tls

I see that the assigned node ID is not being honored--only the long, generated device UUID is shown--despite the CLI help output clearly stating that it would override the (generated) node ID.

$ openclaw nodes describe --node my-mac-node

🦞 OpenClaw 2026.4.2 (d74a122) — If something's on fire, I can't extinguish it—but I can write a beautiful postmortem.

│
◇
nodes describe failed: Error: unknown node: my-mac-node (known: Homelab MBP)

Error Message

$ openclaw nodes describe --node my-mac-node

🦞 OpenClaw 2026.4.2 (d74a122) — If something's on fire, I can't extinguish it—but I can write a beautiful postmortem.

│ ◇ nodes describe failed: Error: unknown node: my-mac-node (known: Homelab MBP)

Root Cause

After clearing all paired and pending nodes and devices on the gateway (deleting ~/.openclaw/devices/* and ~/.openclaw/nodes/*), and re-pairing my Mac companion app and independently launched node started by running:

$ openclaw node run --help

🦞 OpenClaw 2026.4.2 (d74a122) — Your AI assistant, now without the $3,499 headset.

Usage: openclaw node run [options]

Run the headless node host (foreground)

Options:
  --display-name <name>       Override node display name
  -h, --help                  Display help for command
  --host <host>               Gateway host
  --node-id <id>              Override node id (clears pairing token)
  --port <port>               Gateway port
  --tls                       Use TLS for the gateway connection (default: false)
  --tls-fingerprint <sha256>  Expected TLS certificate fingerprint (sha256)

$ openclaw node run --node-id my-mac-node --host openclaw.example.local --port 443 --tls

I see that the assigned node ID is not being honored--only the long, generated device UUID is shown--despite the CLI help output clearly stating that it would override the (generated) node ID.

$ openclaw nodes describe --node my-mac-node

🦞 OpenClaw 2026.4.2 (d74a122) — If something's on fire, I can't extinguish it—but I can write a beautiful postmortem.

│
◇
nodes describe failed: Error: unknown node: my-mac-node (known: Homelab MBP)

Fix Action

Fixed

PR fix notes

PR #61587: fix(gateway): honor --node-id CLI option in NodeRegistry

Description (problem / solution / changelog)

Summary

NodeRegistry.register() ignores connect.client.instanceId when determining the node ID, always falling back to connect.device?.id ?? connect.client.id. This means openclaw node run --node-id my-node has no effect — the custom ID is correctly sent to the gateway via instanceId but discarded during node registration.

Root Cause

Line 47 of src/gateway/node-registry.ts:

// Before (bug):
const nodeId = connect.device?.id ?? connect.client.id;

// After (fix):
const nodeId = connect.client.instanceId ?? connect.device?.id ?? connect.client.id;

The --node-id option flows through:

  1. CLI → runNodeHost() → GatewayClient({ instanceId }) → ConnectParams.client.instanceId
  2. Gateway receives it but NodeRegistry.register() never reads instanceId

Changes

  • src/gateway/node-registry.ts: Prefer connect.client.instanceId as the node ID when present
  • src/gateway/node-registry.test.ts: Add unit tests covering instanceId priority, device fallback, and client ID fallback

Test Plan

  • New unit tests: instanceId preferred over device/client ID
  • Existing fallback behavior preserved (device ID → client ID)
  • CI passes

Fixes #61569

🤖 Generated with Claude Code

Changed files

  • src/gateway/node-registry.test.ts (added, +61/-0)
  • src/gateway/node-registry.ts (modified, +1/-1)
  • src/gateway/server-methods/nodes.handlers.invoke-result.ts (modified, +1/-1)
  • src/gateway/server-methods/nodes.ts (modified, +3/-3)

PR #61719: Fix: honor --node-id in NodeRegistry.register (Resolves #61569)

Description (problem / solution / changelog)

Fixes #61569.

NodeRegistry.register() resolved the node ID from connect.device?.id ?? connect.client.id, completely ignoring connect.client.instanceId — the field that carries the --node-id CLI flag.

This patch adds instanceId as the highest-priority source in the resolution chain so that an explicit --node-id override is honored. When instanceId is absent or empty, the existing fallback (device ID → client ID) is preserved.

Adds unit tests covering the full resolution priority and edge cases (empty string, whitespace-only).

Changed files

  • src/gateway/node-registry.test.ts (added, +104/-0)
  • src/gateway/node-registry.ts (modified, +3/-1)

Code Example

$ openclaw node run --help

🦞 OpenClaw 2026.4.2 (d74a122) — Your AI assistant, now without the $3,499 headset.

Usage: openclaw node run [options]

Run the headless node host (foreground)

Options:
  --display-name <name>       Override node display name
  -h, --help                  Display help for command
  --host <host>               Gateway host
  --node-id <id>              Override node id (clears pairing token)
  --port <port>               Gateway port
  --tls                       Use TLS for the gateway connection (default: false)
  --tls-fingerprint <sha256>  Expected TLS certificate fingerprint (sha256)

$ openclaw node run --node-id my-mac-node --host openclaw.example.local --port 443 --tls

---

$ openclaw nodes describe --node my-mac-node

🦞 OpenClaw 2026.4.2 (d74a122) — If something's on fire, I can't extinguish it—but I can write a beautiful postmortem.

│
◇
nodes describe failed: Error: unknown node: my-mac-node (known: Homelab MBP)

---
RAW_BUFFERClick to expand / collapse

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

After clearing all paired and pending nodes and devices on the gateway (deleting ~/.openclaw/devices/* and ~/.openclaw/nodes/*), and re-pairing my Mac companion app and independently launched node started by running:

$ openclaw node run --help

🦞 OpenClaw 2026.4.2 (d74a122) — Your AI assistant, now without the $3,499 headset.

Usage: openclaw node run [options]

Run the headless node host (foreground)

Options:
  --display-name <name>       Override node display name
  -h, --help                  Display help for command
  --host <host>               Gateway host
  --node-id <id>              Override node id (clears pairing token)
  --port <port>               Gateway port
  --tls                       Use TLS for the gateway connection (default: false)
  --tls-fingerprint <sha256>  Expected TLS certificate fingerprint (sha256)

$ openclaw node run --node-id my-mac-node --host openclaw.example.local --port 443 --tls

I see that the assigned node ID is not being honored--only the long, generated device UUID is shown--despite the CLI help output clearly stating that it would override the (generated) node ID.

$ openclaw nodes describe --node my-mac-node

🦞 OpenClaw 2026.4.2 (d74a122) — If something's on fire, I can't extinguish it—but I can write a beautiful postmortem.

│
◇
nodes describe failed: Error: unknown node: my-mac-node (known: Homelab MBP)

Steps to reproduce

  1. Remove all previously registered/paired (and pending) nodes/devices.
  2. Connect Mac node to remote gateway via CLI: openclaw node run --node-id
  3. Approve new device pairing request and then node pairing request.
  4. Assigned custom node ID is not visible anywhere nor recognized.

Expected behavior

I should be able to assign a custom node ID when running a node process gived the --node-id option as presented by the CLI help.

I should then be able to use this custom node ID in the tools.exec.node config setting.

Actual behavior

The node ID I provided via --node-id CLI option is nowhere to be seen (openclaw nodes list) and openclaw nodes describe --node says my custom ID is not known.

OpenClaw version

2026.4.2

Operating system

macOS 15.7.4

Install method

npm global on macOS with remote gateway on Kubernetes

Model

n/a

Provider / routing chain

n/a

Additional provider/model setup details

No response

Logs, screenshots, and evidence

Impact and severity

No response

Additional information

No response

extent analysis

TL;DR

The custom node ID assigned via the --node-id CLI option is not being honored, and instead, the generated device UUID is used.

Guidance

  • Verify that the --node-id option is correctly passed to the openclaw node run command and that the command is executed successfully.
  • Check the output of openclaw nodes list to see if the custom node ID is listed, and if not, try using the --node-id option with a different value to rule out any naming conflicts.
  • Review the documentation for openclaw node run to ensure that the --node-id option is supported and correctly configured.
  • Use the openclaw nodes describe command with the generated device UUID to see if the custom node ID is stored anywhere in the node's configuration.

Example

No code snippet is provided as the issue seems to be related to the configuration and usage of the openclaw command-line tool.

Notes

The issue might be related to a bug or a misconfiguration in the openclaw tool, and further investigation is needed to determine the root cause.

Recommendation

Apply workaround: Try using a different value for the --node-id option or check if there are any other configuration options that can be used to assign a custom node ID.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

I should be able to assign a custom node ID when running a node process gived the --node-id option as presented by the CLI help.

I should then be able to use this custom node ID in the tools.exec.node config setting.

#callback error#memory management#API rate limit#retriever error#indexing error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING