Skip to content

Node host on macOS connects but never announces caps/commands (file-transfer plugin) #87604

Closed

Description

@simonfunk

Summary

A freshly paired macOS node (node-host/node) connects successfully to a remote gateway over Tailscale, but the gateway never sees any caps or commands from the node — even though the file-transfer plugin is enabled in the node's local config. As a result, file.fetch, dir.list, dir.fetch, and file.write are all unusable end-to-end.

The same plugin is registered and enabled on the gateway side, and gateway.nodes.allowCommands plus plugins.entries.file-transfer.config.nodes.<node>.allowReadPaths are configured. Calling any file-transfer tool returns:

node command not allowed: the node did not declare any supported commands

Environment

  • Gateway host: macOS 26.5 (arm64), OpenClaw 2026.5.22 → 2026.5.26 (Mac mini, Tailscale Serve)
  • Node host: macOS 26.3.1 (arm64), OpenClaw 2026.5.26 (MacBook Pro M-series)
  • Transport: Tailscale Funnel wss://<gateway>.ts.net → 127.0.0.1:18789
  • Node service: LaunchAgent, openclaw node run --host <gateway>.ts.net --port 443 --tls
  • Node version reported in describe: ui v2026.5.26 (note: device family is Mac, clientId is node-host, clientMode is node)

Reproduction

  1. Fresh pair a macOS machine as a node (openclaw node install --host <gateway> --port 443 --tls).
  2. Approve the new pairing request on the gateway (openclaw devices approve <requestId>).
  3. Approve the subsequent role-upgrade request that the node-host raises (openclaw devices approve <requestId> again).
  4. On the node, ensure the file-transfer plugin is enabled:
    openclaw plugins enable file-transfer
    openclaw config set plugins.allow '["file-transfer","anthropic","telegram","whatsapp","memory-core","google"]'
    openclaw node restart
  5. On the gateway, confirm:
    openclaw nodes describe --node "<node display name>"

Expected

Caps lists at least file, Commands includes file.fetch, dir.list, dir.fetch, file.write.

Actual

Caps     │
Commands │ - (none reported)

nodes invoke confirms the gateway thinks the node hasn't declared anything:

node command not allowed: the node did not declare any supported commands

What was already verified

  • plugins list on the node confirms file-transfer as enabled, stock stock:file-transfer/index.js, version 2026.5.26.
  • The local config has both plugins.allow and plugins.entries.file-transfer.enabled = true.
  • Node identity is correctly written (identity/device.json, device-auth.json) with both operator and node tokens.
  • The gateway-side file-transfer plugin entry has the node's display name configured under plugins.entries.file-transfer.config.nodes.<name>.allowReadPaths.
  • The gateway's gateway.nodes.allowCommands is open for the relevant commands.
  • Re-pairing from scratch (deleting ~/.openclaw/identity + node.json, fresh openclaw qr setup code, approving both the initial pairing and the role upgrade) produces the same end state.

Additional weirdness

  • Running openclaw node run --host <gateway> --port 443 --tls interactively prints only the OpenClaw banner and then sits silent indefinitely — no plugin-loading output, no connection log, no errors. ~/Library/Logs/openclaw/node.log contains only the config-warning banner from CLI invocations, not anything from the long-running daemon.
  • Despite plugins.allow containing anthropic, telegram, whatsapp etc., every CLI invocation prints:
    plugins.entries.anthropic: plugin disabled (not in allowlist) but config is present
    plugins.entries.telegram: plugin disabled (not in allowlist) but config is present
    plugins.entries.whatsapp: plugin disabled (not in allowlist) but config is present
    
    even after writing plugins.allow with openclaw config set. Suggests plugins.allow is being normalized/ignored somewhere in the node-host code path even though resolveEffectivePluginIds in dist/effective-plugin-ids-*.js reads it correctly.

Hypothesis

ensurePluginRegistryLoaded({ scope: 'all' }) in dist/node-cli-Cheoxwxv.js (the node-host plugin loader) may be picking up a different config than the gateway/CLI path — possibly the bundled/default plugin set only, ignoring user-defined plugins.allow. That would explain why nodeHostCommands from file-transfer is never registered on the node side even though the plugin is on disk and marked enabled.

Impact

Without working file-transfer commands, paired macOS nodes can't be used for any of the typical agent flows (fetching screenshots, reading files in user directories, writing artifacts back). This breaks the documented Mac node use case end-to-end on 2026.5.26.

Asks

  • Confirm whether plugins.allow is supposed to be honoured by openclaw node run, or whether the node-host has its own activation list.
  • Provide a way to log nodeHostCommands registration when the daemon starts (env var? --log-level debug?) so users can self-diagnose.
  • Fix openclaw node run so it logs to ~/Library/Logs/openclaw/node.log (currently empty for foreground daemons; only CLI banner output ends up there).

Activity

  1. clawsweeper commented on May 28, 2026

    @clawsweeper
    Contributor

    Thanks for the context here. I did a careful shell check against current main, and this is already implemented.

    Close: current main now handles the commandless connected-node state by surfacing pending reapproval, pending declared caps/commands, and the exact approval command while preserving the command approval boundary.

    I found the merged PR that appears to have closed this: #92547: fix(nodes): surface pending reapproval diagnostics.

    So I’m closing this as already implemented rather than keeping a duplicate issue open.

    Review details

    Best possible solution:

    Keep the current pending-reapproval diagnostics and approval flow; investigate only if a current-main node still lacks file-transfer commands after the shown pending reapproval is approved.

    Do we have a high-confidence way to reproduce the issue?

    Yes for the central commandless-node symptom: a maintainer reproduced the related state where effective caps/commands were empty while the pending request held the real declared surface. The exact macOS file-transfer setup was not separately live-reproduced in this read-only review.

    Is this the best way to solve the issue?

    Yes. Showing pending declared caps/commands and the exact reapproval command is the narrowest safe fix because it preserves the node command approval boundary instead of auto-enabling dangerous file-transfer commands.

    Security review:

    Security review: No patch security review applies; the implemented fix keeps pending file-transfer commands non-effective until explicit node reapproval.

    AGENTS.md: found and applied where relevant.

    What I checked:

    • Issue context: The report describes a paired macOS node whose effective Caps/Commands were empty and whose file-transfer invocations failed with the no-declared-commands error.
    • Node-host declaration path remains present: Current main loads the node-host plugin registry and sends plugin-derived caps and commands in the GatewayClient connect payload. (src/node-host/runner.ts:253, 663fabbe30eb)
    • File-transfer commands are still declared: The file-transfer plugin declares file.fetch, dir.list, dir.fetch, and file.write as node-host commands with the file capability. (extensions/file-transfer/index.ts:42, 663fabbe30eb)
    • Current-main diagnostics expose pending surfaces: The node catalog now reports approvalState, pendingRequestId, pendingDeclaredCaps, pendingDeclaredCommands, and pendingDeclaredPermissions separately from effective commands. (src/gateway/node-catalog.ts:230, 663fabbe30eb)
    • CLI now tells operators what to approve: nodes describe now renders Pending caps, Reapprove, and Pending commands so operators can see that a changed command surface is awaiting approval rather than absent. (src/cli/nodes-cli/register.status.ts:470, 663fabbe30eb)
    • Fix provenance: Merged pull request fix(nodes): surface pending reapproval diagnostics #92547 is the canonical fix; its merge commit is titled fix(nodes): surface pending reapproval diagnostics. (65b460f2345a)

    Likely related people:

    • fuller-stack-dev: Authored the merged pending-reapproval diagnostics work that makes commandless connected nodes actionable without making pending commands executable. (role: implemented fix; confidence: high; commits: 65b460f2345a, 05c3c60f2f8e; files: src/gateway/node-catalog.ts, src/cli/nodes-cli/register.status.ts, src/shared/node-list-types.ts)
    • steipete: Provided maintainer verification on the diagnostics PR and coauthored the reapproval race/cleanup follow-up commits in the same node pairing area. (role: coauthor and recent adjacent owner; confidence: high; commits: 65b460f2345a, d7b4dfad6ddd, f6317fb747f5; files: src/gateway/node-connect-reconcile.ts, src/infra/node-pairing.ts, src/gateway/node-catalog.ts)
    • omarshahine: Authored the original bundled file-transfer plugin work that introduced the file-transfer node-host command surface later carried by the replacement PR. (role: file-transfer feature author; confidence: high; commits: a25d59ccbe61; files: extensions/file-transfer/index.ts, extensions/file-transfer/src/node-host/dir-list.ts, extensions/file-transfer/src/shared/node-invoke-policy.ts)

    Codex review notes: model internal, reasoning high; reviewed against 663fabbe30eb; fix evidence: merged PR #92547, commit 65b460f2345a, main fix timestamp 2026-06-13T18:40:18-06:00.

  2. added
    P2Normal backlog priority with limited blast radius.
    impact:session-stateSession, memory, transcript, context, or agent state can drift or corrupt.
    issue-rating: 🐚 platinum hermitGood issue quality with a plausible reproduction path needing some confirmation.
    clawsweeper:needs-live-reproClawSweeper needs live local, crabbox, or manual validation to confirm this issue.
    on May 28, 2026
  3. locked as resolved and limited conversation to collaborators on Jun 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Normal backlog priority with limited blast radius.clawsweeper:needs-live-reproClawSweeper needs live local, crabbox, or manual validation to confirm this issue.impact:session-stateSession, memory, transcript, context, or agent state can drift or corrupt.issue-rating: 🐚 platinum hermitGood issue quality with a plausible reproduction path needing some confirmation.

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions