Troubleshooting

Troubleshooting

Quick Reference

Issue	Solution
No DM reply	Check openclaw pairing list and approve pending requests
Silent in group chat	Verify mentionPatterns config — agent needs @mention
Agent can’t react/see WA group messages	Check requireMention per-group — true drops all non-@mention messages before they reach the session
Auth expired	openclaw models auth setup-token --provider anthropic
Gateway down	openclaw doctor --deep
Memory not indexing	openclaw memory index
Context full	/compact or /new
Channel disconnected	openclaw channels status --probe
Exec requires approval after update	Add tools.exec blocks to every agent in openclaw.json
Control UI blank over Tailscale	Add Tailscale hostname to controlUi.allowedOrigins
*.ts.net not resolving locally	Check /etc/resolver/ts.net exists with nameserver 100.100.100.100
Agent offline after idle (Deep Idle)	sudo pmset -a standby 0 networkoversleep 1

| Error messages spamming a chat channel | Check skills.entries for unresolved SecretRef objects — verify secrets.json has the referenced path, then openclaw secrets reload | | WA “No active WhatsApp Web listener” but channel shows connected | Apply openclaw-patch-wa-listeners, clear jiti cache if EACCES, restart gateway |

Universal fix: openclaw doctor --deep --yes

Skills SecretRef Errors

Error Messages Spamming a Chat Channel

Symptoms: Every inbound message in a channel triggers an error reply like Agent failed before reply: skills.entries.<name>.apiKey: unresolved SecretRef "file:secrets:/<path>". The error repeats on every message because web-auto-reply sends the crash message back to the originating channel.

Cause: A skills.entries entry contains a raw SecretRef object that the gateway failed to resolve to a string. The assertSecretInputResolved check throws during session initialization, before the model is even called. The model fallback chain retries all configured models, each failing identically, then web-auto-reply sends the error.

Fix:

1. Verify the secret path exists in ~/.openclaw/secrets.json (e.g., /skills/openai)
2. Reload secrets: openclaw secrets reload
3. If the secret path is missing, add it to secrets.json and reload
4. If the skill is no longer needed, remove the entry from openclaw.json → skills.entries
5. Restart the gateway: openclaw gateway restart

Prevention: Use a dedicated agent for channels with external visibility (WhatsApp, Slack) so gateway-global config regressions don’t spam error messages into those channels.

Known bug — embedded agent bypass (#49427): The WhatsApp channel’s embedded agent reads the raw config instead of the gateway’s resolved SecretRef runtime snapshot. Even when openclaw secrets reload succeeds and the main agent works fine, the WA embedded agent still hits unresolved refs. Workaround: replace file:secrets SecretRef objects with inline plaintext values in openclaw.json for any fields that the WA agent needs (e.g., tools.web.search.apiKey, talk.apiKey).

WhatsApp

No Active WhatsApp Web Listener

Symptoms: Outbound messages fail with “No active WhatsApp Web listener (account: default)” but openclaw channels status --probe reports the channel as connected.

Cause: The Baileys listener is stored in a module-scoped Map(). After a WebSocket disconnect/reconnect, the extension may reload in a new jiti VM realm with its own Map instance. The delivery code reads from the old realm’s empty Map. This is the same class of bug as the webhook route registry isolation (#50208).

Fix:

1. Apply the WA listener patch: openclaw-patch-wa-listeners
2. If the patch fails with EACCES, clear stale jiti cache: rm /tmp/jiti/plugin-sdk-thread-bindings-*.cjs
3. Restart the gateway: openclaw gateway restart
4. Verify: send a test message with --deliver and check logs for delivery failures

Prevention: Enable the channel health monitor (gateway.channelHealthCheckMinutes: 5) so stale channels auto-restart within 30 minutes.

BlueBubbles

Self-Healing Scripts

Three scripts automate BlueBubbles diagnostics and recovery. See BlueBubbles Health & Self-Healing for the full guide.

Quick reference:

# Read-only diagnosis
bash openclaw-agents/lobster/scripts/bb-healthcheck.sh

# Diagnose and auto-fix
bash openclaw-agents/lobster/scripts/bb-selfheal.sh

# Check for stuck agent runs only
bash openclaw-agents/lobster/scripts/stuck-session-watchdog.sh

Stuck Session (iMessage Not Processing)

Symptoms: Agent stops responding to all iMessage DMs and group chats. The gateway is running, BlueBubbles shows connected, but no messages are processed.

Cause: An exec tool call in a BlueBubbles session hung indefinitely, blocking the session lane.

Fix:

1. Run the stuck-session watchdog to confirm: bash openclaw-agents/lobster/scripts/stuck-session-watchdog.sh
2. If stuck runs are detected, restart the gateway: openclaw gateway restart
3. Verify agents.defaults.timeoutSeconds is set to 180 (not the old 600s default) to prevent recurrence

Messages.app AppleScript Hung

Symptoms: Agent can receive messages (webhooks arrive) but replies fail silently or time out.

Cause: Messages.app’s AppleScript interface becomes unresponsive (internal state corruption, large iCloud sync, etc.).

Fix:

# Force kill and relaunch both apps
pkill -9 Messages
pkill -9 BlueBubbles
sleep 3
open -a Messages
sleep 5
open -a BlueBubbles

Or run bb-selfheal.sh which does this automatically.

Private API Disconnected

Symptoms: Typing indicators, read receipts, and tapbacks stop working. Messages still send via AppleScript fallback.

Cause: The BlueBubbles Private API helper disconnected. This requires SIP to be disabled on the host Mac.

Fix: Open BlueBubbles settings, check the Private API section. Re-enable if needed. If SIP was re-enabled (e.g., after a macOS update), disable it again per the BlueBubbles Private API docs.

Not Receiving Messages

The BlueBubbles webhook URL must be the full URL including the gateway host, not just the path.

Check current webhook:

curl -s "http://127.0.0.1:1234/api/v1/webhook?password=YOUR_BB_PASSWORD"

If the URL is /bluebubbles-webhook instead of http://127.0.0.1:18789/bluebubbles-webhook, delete and re-register:

# Delete the bad webhook (replace ID from the response above)
curl -X DELETE "http://127.0.0.1:1234/api/v1/webhook/ID?password=YOUR_BB_PASSWORD"

# Register with full URL
curl -X POST "http://127.0.0.1:1234/api/v1/webhook?password=YOUR_BB_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"url":"http://127.0.0.1:18789/bluebubbles-webhook","events":["new-message","updated-message","group-name-change","participant-added","participant-removed","participant-left"]}'

Blocked by macOS Gatekeeper

xattr -cr /Applications/BlueBubbles.app

DMs Not Getting Responses

If dmPolicy is pairing (the default), senders need a pairing code. Switch to allowlist:

openclaw config set channels.bluebubbles.dmPolicy allowlist
openclaw config set 'channels.bluebubbles.allowFrom' '["+1XXXXXXXXXX","+1XXXXXXXXXX"]'
openclaw gateway restart

WhatsApp

Group Messages Not Reaching Agent

Symptoms: Channel health shows WhatsApp connected and linked, but group messages never appear in the agent session. No errors in gateway logs at info level.

Cause: groupAllowFrom contains a group JID (e.g., [email protected]) instead of E.164 phone numbers. The gateway matches each sender’s phone number against this list — a group JID will never match, so every message is silently blocked. The blocking is logged at verbose level only.

Fix: Replace the group JID with sender phone numbers:

"groupAllowFrom": [
  "+1XXXXXXXXXX",
  "+1XXXXXXXXXX"
]

Or use ["*"] to allow all group participants. Then restart the gateway.

Verify: openclaw channels status --probe should show the channel as connected with the correct dm: and allow: values.

WhatsApp Web Socket Cycling

Symptoms: Frequent stale-socket restarts in logs (every 30-40 minutes), occasional DNS failures for web.whatsapp.com, corrupted creds.json.

Possible causes: Network instability during Mac sleep, contested session from another WhatsApp Web device, or stale session state.

Fix: Check if another device is linked to the same WhatsApp account. Consider wacli auth status for a separate diagnostic view. Persistent cycling may require re-linking: openclaw channels login.

Tailscale

DNS / Serve Not Working

Use the Homebrew CLI (brew install tailscale), not the GUI app (brew install --cask tailscale). The GUI app is sandboxed and can’t properly configure macOS DNS or Tailscale Serve.

MagicDNS Not Resolving on the Agent Mac

Symptoms: curl https://your-agent.tailnet.ts.net fails with “Could not resolve host” on the agent Mac itself, but works from other Tailscale devices.

Cause: Homebrew-installed tailscaled creates /etc/resolver/search.tailscale but not /etc/resolver/ts.net. macOS split-DNS uses the filename as the domain — search.tailscale only handles *.search.tailscale, not *.ts.net.

Fix: Install the com.lobster.tailscale-dns LaunchDaemon (in config/):

sudo cp config/com.lobster.tailscale-dns.plist /Library/LaunchDaemons/
sudo launchctl load /Library/LaunchDaemons/com.lobster.tailscale-dns.plist

This creates /etc/resolver/ts.net with nameserver 100.100.100.100 and watches /etc/resolver/ to recreate it if wiped by Tailscale updates.

Stale Tailscale Shim

If you previously installed the Mac App Store version, a shim script at /usr/local/bin/tailscale may shadow the Homebrew binary:

sudo rm /usr/local/bin/tailscale

SSH Hangs or Timeouts

Verify Tailscale SSH is enabled:

tailscale status

If SSH isn’t shown, re-enable:

sudo tailscale up --ssh

MCP Servers

Tools Not Working

MCP servers accessed via CLI clients (like mcporter) require the exec tool to be in the agent’s alsoAllow list. Check:

"tools": {
  "profile": "minimal",
  "alsoAllow": ["exec", ...]  // exec must be here
}

Mail Agent Delegation Timeout

Symptoms: Agent says it “timed out waiting for the reply” from the mail agent, but the mail agent’s summary appears in the gateway logs shortly after.

Cause: sessions_send defaults to a 30-second timeout when timeoutSeconds is omitted. The mail agent typically needs 25–35 seconds for a search-then-read flow (7s gateway routing + two Fastmail API calls + LLM summary generation). If total wall time exceeds 30s, the caller gets "status": "timeout" even though the mail agent finishes moments later.

Fix: Always pass timeoutSeconds: 60 in sessions_send calls to the mail agent. This is documented in TOOLS.md under the mail delegation section.

{
  "sessionKey": "agent:lobster-mail:main",
  "agentId": "lobster-mail",
  "message": "Summarize the email about [topic]",
  "timeoutSeconds": 60
}

Project Config Shadowing

mcporter reads ./config/mcporter.json relative to the agent’s working directory as a “project config” that shadows the system config. If MCP calls are failing, check that the project config is empty:

mcporter config list

The system config at ~/.mcporter/mcporter.json should be the single source of truth.

Token Expired

Re-authenticate at the server’s /get-token endpoint, copy the new Bearer token, and update ~/.mcporter/mcporter.json.

Apple PIM

CLI Hangs When Called by OpenClaw

The first invocation of each PIM CLI triggers a macOS TCC permission prompt. This prompt can’t display in a non-interactive context (like when spawned by OpenClaw). Fix by running each CLI manually from Terminal first:

~/.local/bin/calendar-cli list
~/.local/bin/reminder-cli lists
~/.local/bin/contacts-cli list

Wrong Agent Seeing Wrong Calendars

Each agent has a workspace-local apple-pim/config.json that the plugin reads automatically. Check that the config exists and has the correct blocklists:

cat ~/.openclaw/agents/<agent-id>/workspace/apple-pim/config.json

OpenClaw Gateway

Gateway Won’t Start

# Check for port conflicts
lsof -i :18789

# Run diagnostics
openclaw doctor --deep

# Check logs
openclaw logs --tail 100

Sessions Not Resetting

Sessions reset daily at 4 AM and after 2 hours of inactivity. Force a reset:

# Via iMessage
/new

# Or via CLI
openclaw session reset --agent <agent-id>

Auth Error for Non-Default Agent

openclaw onboard only configures auth for the default agent. Copy the auth profile to other agents:

cp ~/.openclaw/agents/main-agent/agent/auth-profiles.json \
   ~/.openclaw/agents/other-agent/agent/auth-profiles.json

Configuration

Permissions Reset After jq Edit

jq writes to a temp file then mvs it, resetting permissions to 644. Always restore:

chmod 600 ~/.openclaw/openclaw.json

Tool Config Using Wrong Keys

OpenClaw uses profile + alsoAllow / deny, NOT allow / deny. Using allow causes agents to lose all tools beyond the minimal profile.

// CORRECT
"tools": {
  "profile": "minimal",
  "alsoAllow": ["exec", "web_search"],
  "deny": ["write", "edit"]
}

// WRONG — "allow" is not recognized
"tools": {
  "allow": ["exec", "web_search"]
}

Exec Approvals Not Working

Check that:

1. The exec-approvals.json file exists at ~/.openclaw/exec-approvals.json
2. The agent ID in the file matches the agent’s actual ID
3. The command paths in the allowlist match the actual binary locations
4. autoAllowSkills is set to false for restricted agents

All Exec Commands Require Approval After Update

Symptoms: After upgrading OpenClaw, all exec commands (even echo hello) require manual approval and time out at 120 seconds.

Cause: OpenClaw v2026.2.22+ properly resolves per-agent tools.exec config in openclaw.json. Agents without an explicit tools.exec block fall through to gateway defaults (security: "allowlist", ask: "on-miss").

Fix: Add explicit tools.exec blocks to every agent in openclaw.json:

// Main agent (allowlist with owner approval for unlisted commands)
"tools": {
  "exec": { "security": "allowlist", "ask": "on-miss" }
}

// Restricted agents (same structure, smaller allowlist in exec-approvals.json)
"tools": {
  "exec": { "security": "allowlist", "ask": "on-miss" }
}

Also add safeBinTrustedDirs — v2026.2.22+ stopped trusting PATH-derived directories:

"tools": {
  "exec": {
    "safeBinTrustedDirs": [
      "/path/to/.local/bin",
      "/opt/homebrew/bin"
    ]
  }
}

Then restart: openclaw daemon restart

Important: Setting these values in exec-approvals.json alone is NOT enough — that file controls node host exec, not gateway exec. You must configure both files. See Security Model for details.

Debug commands:

# Check gateway runtime exec config (not just local file)
openclaw approvals get --gateway

# Push local config to running gateway
openclaw approvals set --file ~/.openclaw/exec-approvals.json --gateway

Control UI Not Loading Over Tailscale

Symptoms: Tailscale Serve is running and the gateway is accessible, but the Control UI shows a blank page or “origin not allowed” errors in the browser console.

Cause: The gateway rejects WebSocket connections from origins not in the allowedOrigins list.

Fix: Add your Tailscale hostname to controlUi.allowedOrigins and enable auth.allowTailscale in openclaw.json:

"controlUi": {
  "enabled": true,
  "allowedOrigins": ["https://your-agent.your-tailnet.ts.net"]
},
"auth": {
  "mode": "token",
  "token": "${OPENCLAW_GATEWAY_TOKEN}",
  "allowTailscale": true
}

Then restart the gateway. Do NOT change bind to "tailnet" — this breaks BlueBubbles webhooks and Tailscale Serve.

If prompted for device pairing, approve via openclaw devices list and openclaw devices approve <requestId>.