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
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

Universal fix: openclaw doctor --deep --yes

BlueBubbles

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

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.

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
}

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 workspace-local PIM wrapper scripts that set config environment variables. Check that the wrappers exist and point to the correct config:

ls ~/.openclaw/agents/<agent-id>/workspace/bin/

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