If openclaw gateway status already shows Runtime: running but Telegram never replies, the Chrome extension Relay badge stays gray, and logs occasionally show 409 Conflict, you are hitting the most common post-deploy triad in 2026: the control plane looks healthy while business channels never close the loop. This guide is for operators who finished install and need 7×24 production acceptance—not another blind reinstall. You get a four-probe ladder, a symptom routing table, a six-step acceptance runbook, and FAQ answers. It pairs with our half-install recovery, channels probe, and gateway not ready articles so you fix the right layer at the right time.
Many teams equate “install succeeded” with “ready for customers.” In the 2026 OpenClaw architecture, the Gateway process, the channel subsystem (Telegram, WhatsApp, and peers), and the browser Relay are three independent chains. Gateway only proves RPC and the control plane are up. Channels still depend on bot tokens, webhook versus polling mode, pairing policy, and whether another host is consuming the same token. Relay depends on the WebSocket URL baked into the extension, reverse-proxy upgrade headers, and whether your topology changed after 2026.3.x relay driver adjustments.
The triad is painful because every layer has its own green signal. Dashboard loads, gateway status prints running, and doctor may pass schema checks—while Telegram shows zero inbound lines and the extension never attaches a tab. That mismatch sends teams into the wrong playbook: editing model keys, reopening firewall rules, or reinstalling Node when the real blocker is a second long-polling consumer or a stale webhook. If any two of the six checkpoints below match, follow this article instead of rebuilding the host.
Separate three mental models before you touch configuration. Layer one is process health: something listens, survives logout, and answers probes. Layer two is channel delivery: Telegram API traffic reaches your Gateway exactly once per token. Layer three is browser automation: Relay must reach the same published address your Gateway actually uses, including wss:// when TLS terminates at a proxy. Mixing layers causes the classic midnight page: “Gateway is fine” in Slack while users see a dead bot. Document which layer each engineer already changed so you do not stack conflicting fixes.
Post-deploy incidents also correlate with host shape. A laptop that sleeps will drop long-polling silently; a shared Mac may run a coworker’s debug Gateway against your production bot token; a VPS behind Cloudflare may break WebSocket upgrades while HTTP health checks still pass. Note OS version, whether launchd or systemd supervises the process, and whether the bot token ever lived on another machine. That inventory shortens triage when 409 appears intermittently—often two processes alternating ownership of the same token.
Telegram completely silent: the bot looks online, you send a message, and Gateway logs show no inbound. Common causes are 409 Conflict (two instances long-polling the same token) or a leftover webhook blocking polling mode.
Logs show 409 Conflict: the same BOT_TOKEN is held by a second Gateway, an old Docker stack, or a developer laptop still running a debug process.
Chrome Relay badge on, no tab control: the extension points at the wrong host or port, or Nginx omits Upgrade: websocket. Some 2026.3.22+ builds changed relay drivers; cross-host setups must read release notes.
channels probe fails while gateway status is fine: pairing not approved or dmPolicy blocking direct messages—not a missing Gateway. See the channels probe article.
Remote CLI returns Unauthorized: configuration moved from gateway.token to gateway.auth.token. Run openclaw doctor --generate-gateway-token and restart before blaming Telegram.
18789 EADDRINUSE: status may claim running while a stale PID holds the port. Clear the listener, then gateway restart—do not rewrite channel settings first.
Capture log excerpts and probe output before mutating config. Incident reviewers need proof the control plane was healthy while channels were not. That discipline prevents “fix the model” churn when the token is still contested. If your change template has a Gateway section, add a checkbox for “four-probe bundle attached” so triad recoveries cannot close without channel-level evidence.
Use this matrix during handoff between platform engineering and bot owners. Each row is one question you can paste into a ticket. “This article” means the post-deploy triad path—Gateway already running, channels or Relay still broken. When the answer in the third column is a link, read that article first; return here only after the prerequisite layer is healthy. Routing wrong wastes hours: pairing tweaks cannot fix 409, and auth key migration cannot fix a sleeping laptop that drops polling.
The first row catches install script success without a listening Gateway—that is half-install territory, not triad. The second row catches OOM, Docker memory limits, and genuine not ready states. The third row is the core scope of this page: runtime running plus Telegram silence or 409. The fourth row covers Relay disconnects while Gateway probes succeed. The fifth row splits token-key drift (partially here) from full model provider auth failures (dedicated auth article). Present raw command output in reviews; paraphrased “seems fine” approvals caused most 2026 production channel outages we tracked in community threads.
| What you see | Start here (post-deploy triad) | Hand off to |
|---|---|---|
| install.sh OK, no Gateway | No | Half-install recovery |
| gateway status: not ready / OOM | No | Gateway not ready |
| running + Telegram 409 / no replies | Yes | Pairing overlay: channels probe |
| running + Relay disconnect | Yes | Public exposure: Gateway security / Tailscale topics |
| models Unauthorized | Partial (token keys) | Auth troubleshooting |
A green Gateway probe only proves the control plane is alive—channels and browser Relay still need their own acceptance before you call deployment done.
Run the table top to bottom in under five minutes during every channel go-live. If two rows match, execute prerequisites first, then return to Section 3. False routing is expensive: teams that edit openclaw.json in a loop while 409 persists often end up with split-brain config that doctor --fix must unwind later.
Order is fixed: prove only one Gateway consumes the Telegram token, then handle pairing and Relay URLs. Do not hammer openclaw gateway restart while 409 is active—you will only scramble logs. Each step has an exit criterion. Step 1 ends when you have saved output from all four probes plus a live logs --follow window. Step 2 ends when getMe succeeds and webhook mode is cleared if you intend polling. Step 3 ends when no other process can claim the token. Step 4 ends when channels status --probe reflects approved pairing and an intentional dmPolicy. Step 5 ends when the extension WebSocket matches the published Gateway address. Step 6 ends when post-restart probes pass on the same host that will run 7×24.
Automation-friendly teams can wrap the bash block below in a Makefile target that fails CI if any command returns non-zero. Manual operators should keep a second terminal on logs while restarting so the first real error is visible. Between steps 3 and 5, keep Gateway on loopback; widening bind addresses for “quick tests” is how tokens leak into scanner logs. Production exposure belongs in a separate change after channel acceptance passes.
Telegram-specific nuance: Bot API long-polling in 2026 still allows only one active consumer per token. Webhook mode and polling mode are mutually exclusive operational choices—if you once registered a webhook for experiments, polling on Gateway will look broken until deleteWebhook runs. Relay-specific nuance: browser extensions do not inherit your SSH tunnel automatically. If Gateway listens on 127.0.0.1:18789 on a remote Mac, the extension on your laptop must target the forwarded endpoint, not localhost on the wrong machine. Document the exact URL in the extension options field; screenshots help future you.
Four-probe ladder (~5 minutes): openclaw status → openclaw gateway status --deep → openclaw channels status --probe → openclaw doctor --deep; in another terminal openclaw logs --follow and send a test Telegram message to watch for inbound.
Telegram token health: curl "https://api.telegram.org/bot<TOKEN>/getMe" to confirm the bot is valid. If you ever set a webhook, run deleteWebhook before expecting polling inbound.
Eliminate 409: stop every other Gateway, debug CLI, or old Docker stack using the same bot token. Exactly one process worldwide may long-poll that token.
Pairing and dmPolicy: openclaw pairing approve telegram <CODE>. If probe still fails, adjust dmPolicy per the channels article—do not bind Gateway to 0.0.0.0 as a shortcut.
Chrome Relay: extension Gateway URL must match the real listener (often ws://127.0.0.1:18789 locally; wss:// behind TLS with Upgrade headers). Cross-host deployments must verify 2026.3+ relay driver notes for your topology.
Restart and re-probe: openclaw doctor --fix → openclaw gateway restart → openclaw channels status --probe again. macOS persistence: launchd on a remote Mac. Linux VPS: Ubuntu systemd deployment.
# Post-deploy four-probe ladder + Telegram webhook cleanup openclaw status openclaw gateway status --deep openclaw channels status --probe openclaw doctor --deep curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe" curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/deleteWebhook" openclaw pairing approve telegram YOUR_CODE openclaw gateway restart
Tip: if Gateway is not actually listening, read half-install recovery first, then return here. Otherwise you may wipe valid configuration while the real issue is still “daemon never installed.”
Note: binding Gateway to 0.0.0.0 for troubleshooting is high risk in production. Keep loopback plus Tailscale or a tunnel; rotate tokens per the auth troubleshooting article if exposure was accidental.
After step 6, send one end-to-end message through Telegram and confirm both inbound log lines and an agent reply. For Relay, open a controlled tab and verify the extension lists the expected target. Archive probe output in the same retention bucket as other SRE signals so regressions after OS patches are obvious. Weekly spot checks catch token drift when someone spins up a staging bot against production credentials.
gateway.auth.token. Upgrades that only touch the legacy key produce “doctor passes locally, remote CLI 401” confusion.Connection: upgrade at the proxy often shows as “extension lit, no tab.”These bullets are safe for architecture reviews because they describe documented 2026 interface behavior, not undisclosed roadmap items. They also explain why “Gateway green” dashboards still fail acceptance: each bullet is a separate acceptance gate in your runbook, not an optional nice-to-have.
Hosting choices amplify the triad. A MacBook that sleeps drops long-polling without a clean error code. A shared development machine lets two engineers install different OpenClaw builds and fight over one bot token. Container hosts without persistent volumes lose pairing state on redeploy. Neither pattern gives you the stable supervision boundary production agents expect.
An exclusive, always-on macOS node fits 7×24 channels and Relay better than intermittent personal hardware. Dedicated cloud Mac capacity lets you pin Node 24 once, bake the four-probe ladder into golden images, and supervise Gateway with the same discipline you use for Linux VPS fleets—while keeping Apple-only tooling available for browser Relay workflows.
If you want VPS-like provisioning speed for SSH-maintainable Macs where the acceptance script ships in your image, NodeMini Mac Mini cloud rental is usually the better fit than juggling home Gateway sleep schedules and office bots competing for the same token. The same operational model covers OpenClaw remote mode, on-host CI, and audited channel go-live: one host, one token owner, one runbook. That consistency matters when triad recovery is already stressful—you should not also fight coworker debug processes or missing admin rights on a laptop.
Document the four-probe bundle in your internal wiki and attach command output to every production channel ticket. The habit converts “it worked on my machine” threads into auditable evidence and shortens handoffs when pairing or auth work starts on a host that is already process-healthy.
Follow Section 3: run channels status --probe, then check 409 conflicts, deleteWebhook, and pairing approve. For node sizing and always-on hosts, see Mac Mini cloud rental rates.
The channels article focuses on pairing and dmPolicy. This article covers Gateway up but channels silent, plus Chrome Relay and 409 combined failures. Read both in sequence when Telegram is your primary channel.
Some builds adjusted extension relay drivers; cross-host setups must verify release notes and WebSocket paths. For access and image issues on cloud Macs, use the help center.