Telegram transports

Default is long polling. For webhook mode, set channels.telegram.webhookUrl and channels.telegram.webhookSecret; optional webhookPath (default /telegram-webhook) and webhookCertPath (self-signed cert PEM for direct-IP or no-domain setups).

The Gateway reserves /health, /healthz, /ready, /readyz, /startup, and /startupz for checks, including query variants. The /api/channels namespace also requires Gateway authentication, including encoded forms, and cannot receive direct Telegram callbacks. Choose /telegram-webhook or another route for Gateway ingress. The exact /healthz path remains reserved for the legacy listener's health check and cannot be a Telegram webhook path. Other Gateway-reserved paths can continue receiving callbacks through an explicit legacyWebhook endpoint while you update webhookPath, webhookUrl, and the reverse proxy mapping. Without an explicit endpoint, a reserved path produces an actionable startup error. Verify that hot reload applied the route change with openclaw channels status --probe.

In long-polling mode, OpenClaw saves its restart position after an update is committed to the durable ingress queue. A failed handler remains retryable from that queue.

Webhook routes are available on the Gateway HTTP port (default 18789). Point public HTTPS ingress at that port and webhookPath. OpenClaw registers the configured webhookUrl unchanged on every webhook startup, including after a restart. A configured gateway.publicOrigin does not replace an operator-managed callback or reverse-proxy mapping. Telegram's secret header remains the authentication boundary, so this route does not require a Gateway bearer token.

New installs open no legacy forwarding port. During an upgrade, Doctor preserves an existing implicit 127.0.0.1:8787 endpoint as an explicit legacyWebhook pin unless webhookUrl matches the configured gateway.publicOrigin plus that account's usable webhookPath. The comparison includes the path and query; OpenClaw cannot infer a Gateway destination from an arbitrary existing callback URL. To retire a pin, expose a usable Gateway webhook route, set webhookUrl to its public URL, and remove legacyWebhook; OpenClaw registers that URL before releasing the old listener. Alternatively, move the existing callback's reverse-proxy upstream to the Gateway port, verify incoming messages, and set legacyWebhook: false to preserve its public URL. Deleting the setting never restores an implicit listener.

During an in-process account reload, the Gateway keeps the previous listener retryable until Telegram accepts setWebhook for the replacement URL. Receiving an update does not complete that cutover. A full Gateway restart closes the old process's sockets; Telegram retries pending deliveries while the replacement starts and registers its route.

Doctor saves the pin and its meta.migrations.webhookListeners completion record together. Keep that record when removing the pin so later Doctor runs and updates leave it removed. See webhook migrations for included and read-only config sources.

The legacy port preserves its unauthenticated /healthz response (200, plain ok) and account-local failed-secret rate limit. Health matching is exact: query strings, trailing slashes, case changes, and encoded variants are not health checks. HEAD returns the same status without a body. The canonical Gateway port keeps its own check and response-header behavior.

After upgrading, run openclaw doctor --fix. Doctor backs up the config and migrates old webhookPort and webhookHost settings to legacyWebhook: { port, host }, preserving a host-only setting with port 8787. An explicit endpoint object overrides the default; an omitted object host uses 127.0.0.1. Existing legacyWebhook: false settings remain disabled during migration.

Named accounts inherit the channel's legacyWebhook setting. An account-level false disables that account's legacy endpoint even when the channel config specifies an endpoint. An explicit account endpoint overrides an inherited false. A shared legacy socket stays open while another account still uses that endpoint. Both ports use the same Gateway route handler and Telegram secret verification.

Separately installed Telegram plugins require OpenClaw 2026.9.8 or newer, whose Doctor can preserve omitted endpoints before the new runtime starts. Upgrade OpenClaw before manually replacing the plugin. Older hosts reject the incompatible package and retain their current plugin. Gateway owns every explicitly configured forwarding listener; Telegram no longer opens a separate account-owned server.

Accounts may share a Gateway route when their webhook secrets differ. Requests matching more than one account are rejected; assign distinct secrets or paths before moving traffic to the Gateway port. Migrated legacy endpoints preserve account selection for accounts that previously shared a secret and path on separate explicit ports.

Webhook mode validates request guards, the Telegram secret token, and the JSON body, then commits the update to its durable ingress queue before returning an empty 200. Successful durable adoption includes x-openclaw-delivery-accepted: durable; health, routing, authentication, validation, and storage-error responses omit this header. Reverse proxies and host controllers can require the header to distinguish OpenClaw adoption from a generic empty 200 without inferring acceptance from response timing.

After the durable write, OpenClaw claims and processes updates through the core channel-ingress drain (per-chat/per-topic lanes, complete at turn adoption, pre-adoption stall timeout). Slow agent turns do not hold Telegram's delivery ACK.