Do not configure Telegram, Discord, Slack, and WhatsApp in one pass. Choose the route whose identity and deployment model you can own, keep its first access boundary closed, and call it connected only after one authorized sender receives one visible reply in the same conversation.
| Start with | Identity and transport you own | First safe boundary |
|---|---|---|
| Telegram | A BotFather bot over Telegram's Bot API; Telegram is currently a core OpenClaw channel | Pair one DM sender; allowlist a group only after the private test |
| Discord | A Discord application and bot over the Discord Gateway; the OpenClaw channel is a separate plugin | Pair DMs; allowlist the intended server and channel; keep mention gating on |
| Slack | A Slack app using Socket Mode or HTTP Events; the OpenClaw channel is a separate plugin | Pair DMs; allowlist the intended channel; start with the smallest event and scope set |
| A linked WhatsApp account with a QR-authenticated Baileys session; the OpenClaw channel is a separate plugin | Pair one sender; allowlist groups later; prefer a dedicated number when practical |
This core/plugin split reflects the official OpenClaw channel documentation checked on July 13, 2026; packaging and platform permission labels can change. It is not a ranking. Pick the route that matches the identity, deployment, and administrative boundary you can actually maintain.
Use the same fail-closed baseline on the first route: DM pairing, group allowlists, and mention-gated group replies. Do not switch a DM policy to open with a wildcard just to make a test pass, and never paste a real bot token, app token, signing secret, or linked-session data into a public issue, screenshot, or article.
A channel is commissioned only when its account resolves, one intended message reaches the Gateway, the agent or model completes, and the reply appears back in the same conversation. Record the probe, the relevant log window, and the visible reply.
Stop here: do not add optional scopes, more groups, more users, public access, or a second channel until that exact path passes. Expand one boundary, then rerun the same test.
Prove the baseline before adding a channel
Do not debug a new channel on top of an unproven Gateway. A Telegram token cannot repair a provider-authentication failure, and a Slack scope cannot make an unreachable Gateway healthy. First prove that the expected OpenClaw installation, Gateway, and model route can complete a normal turn outside the new messaging channel.
Start with read-only observations:
hljs bashopenclaw status openclaw gateway probe openclaw doctor openclaw channels list --all openclaw channels status --probe
These commands answer different questions. openclaw status identifies the active installation and broad runtime state. gateway probe asks whether the Gateway is reachable. Plain doctor reports configuration and migration issues without making doctor --fix part of the setup recipe. The current channels CLI reference defines channels list --all, which separates installed, configured, enabled, and installable channels. channels status --probe uses the live Gateway when reachable; if the Gateway is down, its fallback can only summarize configuration, not prove a provider connection.
The baseline passes when:
- the intended OpenClaw binary and version are the ones the Gateway service actually runs;
- the Gateway probe succeeds;
- a model-backed turn completes through an already working local or web surface;
- the selected channel appears as core, installed, or installable rather than as an invented config key;
- no unrelated repair is required to begin the channel setup.
If the CLI, prerequisites, install path, or Gateway cannot pass that baseline, stop at the OpenClaw installation error guide. Fixing the installation first preserves a clean distinction: the channel work begins only after the runtime beneath it is known to work.
Choose your first channel by contract
Pick the identity and deployment contract you can own. āWhich channel is best?ā is too broad because each choice assigns a different platform identity, secret, transport, administrator, and recovery path.
| Choose | Good first fit | You must be prepared to own | Do not choose it first when |
|---|---|---|---|
| Telegram | A dedicated bot for one operator or a small group, with outbound long polling acceptable | BotFather identity, bot token, numeric user and group IDs, privacy and mention behavior | You actually need a workspace app, server roles, or a phone identity |
| Discord | A private server or community where a bot application and explicit channel permissions fit | Developer application, privileged intents, invite permissions, guild and channel IDs | You cannot administer the server or review the bot's effective permissions |
| Slack | A workspace where app installation and transport ownership are already understood | Workspace app, Socket or HTTP deployment, tokens or signing secret, scopes and events | You cannot install an app or provide the required network shape |
| A phone-number identity is the required entry point | Linked device, QR session, number ownership, phone allowlists, Gateway-held session state | You cannot keep the linked session private and operational |
The current channel configuration reference places Telegram in the core openclaw package. The other three are official plugin channels, and a flag-driven openclaw channels add --channel <name> can install an installable catalog channel from its current default source. That is safer than copying a stale package name from an old tutorial. Run openclaw channels add --help to see the live flags for the selected channel.
Choose one account as well as one platform. Adding two Telegram bots, two Slack workspaces, or a personal and work WhatsApp identity before proving the default account introduces the same ambiguity as configuring four platforms at once.
Record the five-part commissioning contract
Every channel needs five owners to agree. A saved credential covers only one of them.
| Part | Question to answer before setup | Evidence to keep |
|---|---|---|
| Identity | Which bot, app, workspace, server, or phone account will users see? Who can administer it? | Platform identity and stable IDs, without secrets |
| Transport | Is the route core or a plugin? Does it use long polling, a Gateway connection, Socket Mode, HTTP Events, or a QR-linked session? | Installed channel, selected mode, reachable runtime |
| Secret or session | Which token, app token, signing secret, or linked-device state authenticates that route? | Secret reference or protected host location, never the value |
| Access | Which sender, DM, group, channel, guild, mention, and command boundaries are allowed? | Pairing approval and explicit ID-based allowlists |
| Proof | What exact message will demonstrate inbound, model, outbound, and visible delivery? | Probe result, bounded logs, and visible reply |
Write these five lines down before touching a second platform. The exercise exposes ownership gaps early. For example, āSlackā is not a transport decision until you choose Socket Mode or HTTP Request URLs. āWhatsAppā is not an identity decision until you decide which number will own the linked session. āDiscord bot onlineā is not proof until an authorized user in the intended DM or channel receives a reply.
Keep secrets out of the working conversation
A token-looking placeholder still teaches people where to paste a real token. Prefer environment-backed or file-backed secret references on the Gateway host, and make publishable configuration examples describe the secret rather than contain it.
For example, the current Discord channel accepts an environment SecretRef:
hljs json5{ channels: { discord: { enabled: true, token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" } } } }
The value of DISCORD_BOT_TOKEN belongs in the protected service environment, not in that file, a chat prompt, terminal screenshot, support bundle, or Git repository. Apply the same rule to Telegram bot tokens, Slack bot and app tokens, Slack signing secrets, and WhatsApp authentication directories.
Commission Telegram
Telegram is the core, dedicated-bot route. The current OpenClaw Telegram guide uses a bot created by the exact @BotFather account, with long polling as the default transport and webhook mode optional. It does not use openclaw channels login telegram; configure its token, start the Gateway, then approve the first DM.
1. Create and protect the bot identity
In Telegram, open @BotFather, run /newbot, and complete the bot name and username prompts. Store the returned token on the Gateway host. For the default account, TELEGRAM_BOT_TOKEN is the environment fallback; named accounts need their own configured botToken or tokenFile.
Use the channel wizard or an environment-backed add instead of placing the token on a command line that may be saved in shell history:
hljs bashopenclaw channels add --channel telegram --use-env openclaw gateway
2. Pair one DM before adding a group
Send the bot one direct message. With the default dmPolicy: "pairing", an unknown sender receives a one-time code. Approve only the code you just triggered:
hljs bashopenclaw pairing list telegram openclaw pairing approve telegram <CODE>
Pairing codes currently expire after one hour. Approval authorizes that DM identity; it does not automatically authorize every group or every group command.
3. Separate user IDs from group IDs
Telegram group access needs two different identifiers:
- a positive numeric Telegram user ID for
allowFromorgroupAllowFrom; - a negative group or supergroup chat ID, often beginning with
-100, as the key underchannels.telegram.groups.
Do not put the negative group chat ID into groupAllowFrom; that field filters people inside an allowed group. Read the IDs from openclaw logs --follow while sending a controlled test, then keep requireMention: true for the first group. Telegram Privacy Mode also affects which group messages reach the bot. Do not disable it or make the bot an administrator merely to avoid understanding the mention and allowlist boundary.
Telegram passes when the probe resolves the intended bot, the paired DM appears inbound, the model completes, and the reply lands in the same DM. Only then add one group ID and test an explicit @botusername mention.
Commission Discord
Discord starts with an application, a private server, and explicit intents. The current OpenClaw Discord guide connects as a bot over Discord's official Gateway, but the bot's online indicator only proves part of the transport.
1. Create the application and enable only the needed intents
In the Discord Developer Portal, create an application and bot. Enable:
- Message Content Intent ā required for the normal text route;
- Server Members Intent ā recommended, and required when role allowlists, name-to-ID matching, or channel-audience access groups depend on member data;
- Presence Intent ā optional, only if presence updates are part of the job.
Generate the invite with the bot and applications.commands scopes. For a first text-channel test, grant View Channels, Send Messages, Read Message History, Embed Links, and Attach Files; Add Reactions is optional. Add Send Messages in Threads only if the first job actually uses threads.
This minimum is intentionally smaller than a feature-complete bot. Voice, moderation, presence, role management, and broad administrative permissions are separate expansions.
2. Store the token, then pair a DM
Set DISCORD_BOT_TOKEN on the Gateway host and use the current channel add/config path. A non-interactive channels add can install the catalog plugin when needed:
hljs bashopenclaw channels add --channel discord --use-env openclaw channels status --channel discord --probe
Start with a DM if Discord privacy settings allow it. The DM pairing flow is:
hljs bashopenclaw pairing list discord openclaw pairing approve discord <CODE>
For a server test, use a private server and one channel. Keep groupPolicy: "allowlist", record numeric server and user IDs, and leave requireMention: true:
hljs json5{ channels: { discord: { groupPolicy: "allowlist", guilds: { "YOUR_SERVER_ID": { requireMention: true, users: ["YOUR_USER_ID"] } } } } }
Discord passes when the probe confirms the bot identity and required intents, the intended user can trigger one message in the intended DM or allowlisted channel, and the visible reply returns there. If the bot is online but guild text is absent, check Message Content Intent, the guild/channel allowlist, user restrictions, and mention behavior before granting more permissions.
Commission Slack
Slack starts with a transport decision, not a scope list. Install the official plugin, then use the current OpenClaw Slack guide to choose Socket Mode or HTTP Request URLs from the Gateway deployment shape:
hljs bashopenclaw plugins install @openclaw/slack
| Deployment fact | Socket Mode | HTTP Request URLs |
|---|---|---|
| Public inbound Gateway URL | Not required | Required, with DNS, TLS, and a reachable event path |
| Connection | Outbound WebSocket to Slack | Inbound signed HTTPS requests |
| Credentials | Bot token plus App-Level Token with connections:write | Bot token plus signing secret |
| Natural first fit | One Gateway, developer host, or network behind a firewall | Replicated Gateways or an existing public webhook deployment |
The two modes have messaging and interaction feature parity; choose by network and scaling ownership. Do not configure both credential sets as if they were redundant backups. A Socket app token and bot token must belong to the same Slack app and workspace. HTTP mode must verify each request with the matching signing secret.
Start from the smallest useful manifest
The official Slack channel page owns the current minimal and recommended manifests. Use the minimal form for the first DM or mention and add file, reaction, history, App Home, slash-command, or interactive scopes only when the next verified job needs them. Copying an old āenable every history and write scopeā bundle makes later audits difficult and can hide which permission actually unlocked the feature.
Slack DMs default to pairing:
hljs bashopenclaw pairing list slack openclaw pairing approve slack <CODE>
For a channel, allowlist by stable Slack channel ID such as C..., not #channel-name. Under an allowlist policy, name-based keys can be ignored and make a correctly connected app look silent. Channel messages are mention-gated by default, which is a useful first-test boundary.
Slack passes when the probe can resolve the correct app credentials and transport, one paired DM or mention enters from the intended workspace and channel, and the reply appears in the same DM or thread. A configured_unavailable secret status, token mismatch, missing scope, or failed request signature belongs to credential/transport repairānot to a wider access grant.
Commission WhatsApp
WhatsApp links a phone identity through a Gateway-owned QR session. The current OpenClaw WhatsApp guide uses the official external plugin over WhatsApp Web/Baileys; it is not a separate Twilio channel.
The interactive channel paths can offer the plugin install when it is missing. The current manual source is:
hljs bashopenclaw plugins install clawhub:@openclaw/whatsapp
1. Decide which number owns the route
A dedicated number is recommended because it creates a clearer OpenClaw identity and cleaner allowlists. A personal number with self-chat is supported, but it adds an identity edge case: sender and linked account can be the same person. Decide that before scanning the QR, and record who can unlink or relink the device.
Use an E.164-style placeholder in documentation and keep the initial group policy closed:
hljs json5{ channels: { whatsapp: { dmPolicy: "pairing", allowFrom: ["<YOUR_NUMBER_E164>"], groupPolicy: "allowlist", groupAllowFrom: ["<YOUR_NUMBER_E164>"] } } }
2. Link the account interactively
hljs bashopenclaw channels login --channel whatsapp
Login is QR-only. Run it from a terminal that can display a live QR to the phone; an image relayed slowly through a screenshot or chat attachment may expire before it is scanned. Treat the resulting authentication directory as a credential. The Gateway owns the socket and reconnect loop, so copying that directory between hosts without an explicit account-migration plan creates competing owners.
After the first sender triggers pairing:
hljs bashopenclaw pairing list whatsapp openclaw pairing approve whatsapp <CODE> openclaw channels status --channel whatsapp --probe
WhatsApp passes when the intended linked account is live, the approved number's message enters the Gateway, and the reply returns to that same chat. Do not add group access, more phone numbers, or a second linked account until that proof is stable.
Prove the complete reply path
Now prove the path, not the configuration. A token can be valid while its sender is blocked. A socket can be connected while events are not authorized. A model can complete while the reply fails to reach the original thread.
Open the evidence surfaces before sending the test:
hljs bashopenclaw channels status --probe --json openclaw channels logs --channel all openclaw logs --follow
Then send one short, unique message from the intended sender, for example: Reply exactly: CHANNEL-OK-714. Record the local time and the exact DM, group, server channel, workspace channel, or WhatsApp chat used.
| Checkpoint | Passing evidence | If it fails first |
|---|---|---|
| Identity | Probe resolves the expected bot, app, workspace, or linked number | Wrong account, wrong credential, unresolved secret, or stale linked session |
| Transport | Core/plugin runtime is active and provider connection is healthy | Plugin install, Gateway network, Socket/HTTP mode, Discord Gateway, Telegram polling, or WhatsApp session |
| Access | Intended sender and destination match pairing and allowlist rules | Pairing, sender ID, group/channel ID, guild/workspace, mention, or command authorization |
| Inbound | The unique message appears in the bounded log window | Platform event, intent, subscription, privacy mode, or routing |
| Model | The routed agent/model completes that turn | Provider authentication, model availability, rate, timeout, or agent routing |
| Outbound | Delivery is attempted for the original route and destination | Platform permission, signing/session state, thread target, or send failure |
| Visible reply | The authorized sender sees the exact reply in the same place | Destination/thread mismatch, client visibility, or outbound delivery |
The channel is commissioned only when all seven checkpoints pass. Save a redacted record containing the account label, destination ID or hashed identifier, probe result, timestamps, relevant error lines, and visible reply. Remove token values, signing secrets, session files, QR data, private message content, and unrelated logs.
Expand one boundary at a time
Every new boundary gets its own test. The safest sequence starts with a private sender and increases authorization or operational complexity in isolated steps.
| Expansion | What changes | Rerun before the next step |
|---|---|---|
| Pair one DM | One sender can reach the bot privately | Same-sender inbound, completion, and visible reply |
| Add one explicit allowlist | Authorization moves from temporary pairing to durable identity | Probe plus same DM test |
| Add one group/channel | A shared destination and its stable ID enter scope | Mentioned message from one authorized user |
| Add one optional feature | New scope, event, intent, media, file, command, or interaction | Feature-specific action plus the original text reply |
| Add more users | More people can invoke the route | Authorized and unauthorized sender tests |
| Add a second account or channel | New identity, secret, transport, routing, and failure owner | Full seven-checkpoint acceptance for the new route |
āOpenā is not the next logical step after āpairing.ā It is a different operating model. An open DM policy requires an explicit wildcard and allows any account that can find the bot to reach it. Use that only for an intentionally public bot with restricted tools, clear abuse controls, and an owner who accepts the exposure.
Command authorization deserves separate review. Pairing a DM sender does not automatically make that identity the owner of every group or sensitive command. Keep commands.ownerAllowFrom, channel allowlists, group sender rules, and tool approval policies aligned with the actual operators.
Route failures without mixing owners
A failed acceptance test should narrow the repair owner, not restart the whole setup.
| Symptom | Likely owner | Next bounded action |
|---|---|---|
Channel is absent from channels list --all | Catalog, plugin, or installation | Use the current channel page and channels add --channel <name>; do not invent a config block |
| Gateway probe fails | OpenClaw runtime or service | Stop channel work and repair the installation/Gateway owner |
| Probe reports invalid or unavailable credentials | Secret resolution or platform identity | Verify the selected account and rotate only the affected secret if necessary |
| Provider is connected but no inbound event appears | Pairing, allowlist, mention, event subscription, intent, or platform privacy | Compare the intended sender and destination against the selected channel contract |
| Inbound appears but no model completion occurs | Agent/model/provider route | Test that route independently; do not broaden channel permissions |
| Model completes but no visible reply returns | Outbound permission, destination/thread, session, or platform send | Inspect the outbound log and effective destination |
| Bot is online but remains silent after setup | Commissioned route runtime | Follow the OpenClaw no-reply diagnostic and stop at the first missing proof |
| A secret or linked session was exposed | Platform credential owner and incident response | Revoke or rotate that one credential, unlink the session when applicable, audit access, then recommission |
Do not combine a plugin reinstall, token rotation, Gateway restart, group-policy change, and model change into one attempt. One change preserves causality. After each repair, rerun the exact message that failed and confirm the reply in the original destination.
Frequently asked questions
Which OpenClaw messaging channel should I connect first?
Choose the identity and deployment boundary you can administer. Telegram fits a dedicated BotFather bot and a private-first route. Discord fits a private server or community with explicit bot intents and channel permissions. Slack fits a workspace with an owned Socket or HTTP app deployment. WhatsApp fits a phone-number identity and a Gateway-owned linked session. There is no universal winner.
Why does OpenClaw say a channel or plugin is unavailable?
Run openclaw channels list --all. Telegram ships in core; Discord, Slack, and WhatsApp currently install as plugins. Use openclaw channels add --channel <name> or the current official install instruction so OpenClaw resolves the catalog source. Do not assume an old package spec is still correct.
Does Telegram use openclaw channels login telegram?
No. Create the bot with the exact @BotFather account, configure its token through a protected config or environment route, and start the Gateway. Interactive channels login is used by QR/session channels such as WhatsApp, not Telegram.
Is DM pairing enough to authorize a group?
No. Pairing approves a DM identity. Group or server access still depends on the platform's group, guild, workspace, channel, sender, and mention rules. Add one destination ID explicitly and test an authorized mention before expanding further.
What are the minimum Discord permissions for a first text test?
Enable Message Content Intent. Invite the bot with bot and applications.commands, then grant View Channels, Send Messages, Read Message History, Embed Links, and Attach Files for the intended channel. Server Members Intent is recommended and becomes necessary for role/audience controls. Reactions, threads, voice, moderation, and presence are optional expansions.
Should I use Slack Socket Mode or HTTP Request URLs?
Use Socket Mode for a single Gateway or a host that can reach Slack outbound but cannot accept public HTTPS. Use HTTP Request URLs for replicated Gateways or an existing public webhook deployment. Socket Mode needs the bot token and an App-Level Token; HTTP needs the bot token and signing secret.
Where should I store channel tokens and sessions?
On the Gateway host, through a protected environment, file, or current SecretRef mechanism. Keep token values, Slack signing secrets, WhatsApp auth directories, QR data, and session material out of chat prompts, screenshots, issue reports, and repositories.
What if the bot is online but sends no reply?
Online status proves only part of the transport. Run openclaw channels status --probe and follow logs while sending one unique message. Find whether the first missing evidence is identity, access, inbound receipt, model completion, outbound delivery, or the visible reply. Use the dedicated no-reply runbook instead of adding permissions at random.
When should I connect a second channel?
After the first route passes the full acceptance path for one intended sender and remains healthy after one bounded access expansion. A second channel creates a new identity, plugin or transport, credential, policy, routing decision, and failure owner, so it deserves its own commissioning record.
Do I need a separate WhatsApp number?
It is recommended because it makes identity and allowlists clearer, but a personal-number/self-chat setup is supported. Whichever route you choose, document who owns the number and linked session, keep the authentication directory private, and prove one approved chat before enabling groups.
One protected, verified route is the finish line. Select the next boundary only after you can name what changes, who owns it, and which same-path test will prove it.
