Troubleshooting

The app shows "Gateway Offline" when your Mac's bridge has been disconnected for more than 60 seconds.

Check the bridge is running:

# macOS
launchctl list | grep tetherclaw

# Linux
systemctl --user status tetherclaw-bridge

Check the logs for errors:

# macOS
tail -50 ~/Library/Logs/TetherClaw/bridge.log

# Linux
journalctl --user -u tetherclaw-bridge -n 50

Common causes:

• Mac is asleep or shut down — the gateway comes back online automatically when it wakes
• Bridge crashed — restart it with launchctl kickstart -k gui/$(id -u)/app.tetherclaw.bridge (macOS) or systemctl --user restart tetherclaw-bridge (Linux)
• API key is invalid — verify the key in ~/.tetherclaw/config.json matches your tetherclaw.app dashboard

"Invalid API key" in the app

• Double-check the key you entered. It should start with tc- and be a UUID format.
• Make sure you copied the full key from your tetherclaw.app dashboard.

App connects but no agents appear

• Verify your AI platform (OpenClaw, Hermes, etc.) is running on your Mac.
• Check the bridge log for errors — the bridge needs to reach your local platform to list agents.

App shows "Reconnecting" indefinitely

• Your Mac may have gone to sleep mid-session. The relay holds the session for 60 seconds. After that, it shows "Gateway Offline" — it will auto-reconnect once your Mac is active again.
• If your Mac is awake, restart the bridge (see above).

Bridge log shows "AUTH ERROR"

• Your API key has been revoked or is incorrect.
• Log in to tetherclaw.app to verify your key is active.

Chat history is loaded from Supabase when you open a conversation. If history fails to load:

• Check your internet connection on your iPhone.
• Verify the bridge is connected (gateway indicator should be green).
• If history for a specific agent is missing, it may have been sent before history logging was enabled on your account.

iOS settings:

1. 1Go to iPhone Settings → TetherClaw → Notifications
2. 2Make sure notifications are allowed

Check push registration in bridge logs:

After opening the app, you should see a line like [tc-xxx] Push token registered in the bridge log. If that line is missing, the app did not successfully register for push.

Common fixes:

• Force-quit the app and reopen it — this re-registers the push token.
• Uninstall and reinstall the app if push permissions were denied on first launch.
• Push notifications require an active TetherClaw subscription (Starter or above).

"curl: command not found"

Install curl with your package manager:

# Ubuntu/Debian
sudo apt-get install curl

# macOS — should be pre-installed; if missing:
brew install curl

"Node.js v18+ required"

Install or update Node.js from nodejs.org. On macOS with Homebrew:

brew install node

"Unsupported OS"

The installer only supports macOS and Linux. Windows is not currently supported.

Permission denied on launchctl (macOS)

Run the install command as your normal user, not with sudo. LaunchAgents must be owned by your user account.

systemd --user not available (Linux)

If you're running in a minimal Linux environment (like a Docker container or server without a user session), the systemd user service may not be available. You can run the bridge manually:

TETHERCLAW_API_KEY=tc-your-key node ~/.tetherclaw/gateway-register.mjs

Use a process manager like pm2 or supervisor to keep it running.