DEV Community

Brian Love
Brian Love

Posted on • Originally published at brianflove.com

OpenClaw Setup, Configuration, and Key Takeaways

#ai #tooling #devops

I set up OpenClaw on macOS with Telegram as my primary channel. The initial setup was quick, but I hit pairing and health-check failures that caused the first message to hang. This post captures what worked, what broke, and the operating policy I now use by default.

Environment

  • macOS desktop app + CLI
  • Node v22.14.0
  • OpenClaw 2026.2.19-2
  • Telegram bot channel enabled

1. Baseline setup

I started with the gateway and channel checks:

openclaw gateway probe
openclaw status --deep
Enter fullscreen mode Exit fullscreen mode

That verified:

  • Gateway reachable on ws://127.0.0.1:18789
  • Telegram configured and healthy
  • Agent session available

2. Pairing the macOS app

My first blocker was:

gateway closed (1008): pairing required
Enter fullscreen mode Exit fullscreen mode

I inspected pending and paired devices and approved the app request:

openclaw devices list --json
openclaw devices approve <request-id> --json
Enter fullscreen mode Exit fullscreen mode

This ensured the macOS app had the expected auth state and roles.

3. Debugging "health check failed" and hanging sends

After pairing, the app still showed a failed health check and initial sends hung. The logs showed repeated health RPC failures tied to role auth behavior, which degraded responsiveness under load.

What helped most:

  • Comparing app behavior with app process stopped vs running
  • Watching gateway logs during connection attempts
  • Validating roles/tokens in device state before changing anything else

Key lesson: trust the logs over UI symptoms.

4. Stabilizing and re-validating

After correcting pairing/auth behavior, I re-ran validation:

openclaw gateway restart
openclaw gateway probe
openclaw status --deep
Enter fullscreen mode Exit fullscreen mode

Final checks I care about:

  • Gateway RPC succeeds consistently
  • Telegram status is OK
  • No recurring pairing-upgrade loop
  • No repeating unauthorized health errors

Default security policy (what OpenClaw should always/never do)

This is the policy I now use as my default.

Always

  • Ask before risky actions; state what/why first.
  • Show exact files/commands changed.
  • Run relevant tests/lint before declaring done.
  • Redact secrets/tokens from output.
  • Ask clarifying questions when requirements are ambiguous.

Never (without explicit approval)

  • Destructive ops (rm -rf, git reset --hard, DB deletes, force-push).
  • Sending external messages (Telegram/email/webhooks) on my behalf.
  • Installing/updating system tools, packages, or services.
  • Accessing or exporting secrets/credentials.
  • Spending money or invoking paid APIs/services.

Key takeaways

  1. Pairing roles must match real app behavior, not just initial connect success.
  2. openclaw devices list --json is the fastest way to spot role mismatches.
  3. Health checks are a real signal; if they fail, message send paths can stall.
  4. Re-verify after every change with gateway probe and status --deep.
  5. Strong boundaries reduce accidental risk while still keeping automation useful.

Top comments (0)