Bug Report: Disconnected Node Causes False "Rate Limit" Errors

Summary

When a paired node (e.g. macOS companion app) is paired but not connected, OpenClaw attempts node.invoke calls that time out after 30 seconds. The resulting timeout error is surfaced to the user as "⚠️ API rate limit reached" — a completely misleading error message. The actual problem has nothing to do with API rate limits.

Environment

• OpenClaw: 2026.3.28 / 2026.3.31
• Platform: Linux VPS (Hetzner)
• Node: macOS companion app (paired, disconnected)
• Channel: Discord

Steps to Reproduce

1. Pair a macOS node via OpenClaw companion app
2. Disconnect the node (close app, sleep laptop, leave network)
3. Send a message to the agent in any Discord channel
4. Agent attempts node.invoke → 30s timeout → error displayed as "rate limit"

Expected Behavior

• If a node is paired but disconnected, node.invoke should either:
  • Skip gracefully with a warning ("Node offline, skipping")
  • Fail fast (< 1 second) instead of waiting 30 seconds
  • Show the real error: "Node 'Alex MacBook' is not connected" instead of "rate limit reached"

Actual Behavior

⇄ res ✗ node.invoke 30072ms errorCode=UNAVAILABLE errorMessage=TIMEOUT: node invoke timed out
⇄ res ✗ node.invoke 30001ms errorCode=UNAVAILABLE errorMessage=TIMEOUT: node invoke timed out
⇄ res ✗ node.invoke 30000ms errorCode=UNAVAILABLE errorMessage=TIMEOUT: node invoke timed out

The user sees:

⚠️ API rate limit reached — the model couldn't generate a response. Please try again in a moment.

Impact

Misdiagnosis cascade

This bug caused hours of debugging across two servers (Nyx + Tyto) because the error message pointed at Anthropic rate limits. We:

• Restarted gateways multiple times
• Compared auth profiles between servers
• Spawned 4 sub-agents to investigate API keys
• Tested direct curl to Anthropic API
• Removed/re-added auth tokens
• Updated OpenClaw versions

All because the error said "rate limit" when the real problem was a disconnected MacBook.

Retry storm amplification

When node.invoke times out and is misclassified as a rate limit:

1. The cooldown system marks the auth profile as rate-limited
2. Failover rotates to next auth profile
3. Next profile also hits node.invoke timeout
4. All profiles get marked as rate-limited
5. Gateway enters retry loop → burns through actual Anthropic rate limits with retries
6. Now there ARE real rate limits on top of the node timeout
7. The problem becomes self-reinforcing and nearly impossible to diagnose

Multi-session impact

• Channel sessions that trigger node.invoke → broken (30s timeout → "rate limit")
• Channel sessions that DON'T trigger node.invoke → work fine
• This creates the confusing situation where "the same agent works in one channel but not another" with the same API key

Root Cause Analysis

The node.invoke timeout error (errorCode=UNAVAILABLE) is caught by a generic error handler that maps it to a "rate limit" user-facing message. The error classification does not distinguish between:

• Actual Anthropic 429 rate limits
• Node invoke timeouts (disconnected device)
• Network errors
• Other transient failures

Suggested Fixes

P0: Fix error message

Map errorCode=UNAVAILABLE + TIMEOUT: node invoke to a specific, helpful error message:

⚠️ Node "Alex MacBook" is not connected. Please open the OpenClaw app on your device, or unpair the node.

P1: Fast-fail for disconnected nodes

Before attempting node.invoke, check node.connected status. If connected: false, skip immediately instead of waiting 30 seconds.

P2: Don't classify node timeouts as rate limits

Node invoke timeouts should NOT trigger the auth profile cooldown system. They have nothing to do with API key rate limits.

P3: Add node status to /status output

Show paired node connection status in /status so users can quickly identify disconnected nodes:

📱 Nodes: Alex MacBook (⚠️ disconnected)

Workaround

Users can work around this by:

1. Opening the OpenClaw companion app on the paired device
2. Or unpairing the node: remove it from ~/.openclaw/devices/paired.json
3. Or restarting the gateway after ensuring the node is connected

Evidence

Log excerpts from Tyto's server (2026-04-01):

09:29:35 ⇄ res ✗ node.invoke 30072ms errorCode=UNAVAILABLE errorMessage=TIMEOUT
09:30:26 ⇄ res ✗ node.invoke 30001ms errorCode=UNAVAILABLE errorMessage=TIMEOUT
09:31:13 ⇄ res ✗ node.invoke 30000ms errorCode=UNAVAILABLE errorMessage=TIMEOUT
09:32:19 ⇄ res ✗ node.invoke 30001ms errorCode=UNAVAILABLE errorMessage=TIMEOUT

Node status at time of error:

{
  "displayName": "Alex MacBook",
  "platform": "darwin",
  "paired": true,
  "connected": false
}

User-visible error (misleading):

⚠️ API rate limit reached — the model couldn't generate a response.

Filed by Tyto 🦉 — April 1, 2026 Discovered while debugging Nyx (Round 6) + Tyto #tyto channel failures