📱 Channels Overview

📡 How channels work

Every channel is a bridge between a messaging platform and your OpenClaw gateway. Messages flow like this:

You (phone/desktop)
  → Messaging App (Telegram, WhatsApp, etc.)
    → OpenClaw Gateway (ws://127.0.0.1:18789)
      → AI Model (Claude, GPT, etc.)
        → Response back through the same path

Key facts:

• Same assistant everywhere — your agent's personality, memory, and skills work identically across all channels
• Run multiple simultaneously — Telegram + Discord + iMessage all at once, routed through one gateway
• Per-channel security — each channel gets its own dmPolicy, allowFrom, and groupPolicy
• Session isolation — each user on each channel gets their own isolated conversation context

CLI basics

# List all configured channels
openclaw channels list

# Check connection status
openclaw channels status --probe

# Interactive channel setup
openclaw channels login

# Add a specific channel
openclaw channels add --channel telegram --token $TOK

📊 Side-by-side comparison

🤔 Which channel to pick first

Decision guide

Setup

1. Open Telegram → search @BotFather → send /newbot
2. Follow the prompts, choose a name and username
3. Copy the bot token (looks like 123456:ABC-DEF...)
4. Add it to OpenClaw:

openclaw channels add --channel telegram --token YOUR_BOT_TOKEN

Or paste the token during openclaw onboard. Telegram uses token-based auth — it does not use channels login (that’s for WhatsApp QR pairing).

Manual config

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-your-token-here",
      "dmPolicy": "pairing",
      "allowFrom": ["your_telegram_user_id"]
    }
  }
}

Why it's the best starter

• No public IP needed — uses long-polling, not webhooks
• Voice notes work — speak to your agent, get voice back
• Survives reboots — reconnects automatically
• Works everywhere — phone, tablet, desktop, web
• Groups supported — add the bot to group chats with mention gating

📖 Full Telegram Setup Guide →

Setup

openclaw channels login whatsapp

This displays a QR code in your terminal. Scan it with WhatsApp on your phone (Settings → Linked Devices → Link a Device).

Config

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"],
      "groupPolicy": "allowlist"
    }
  }
}

Gotchas

• QR scan required on reboot — WhatsApp Web sessions can expire; you may need to re-scan periodically
• Uses your phone number — the bot sends messages from your WhatsApp account (or a dedicated SIM)
• Rate limits — WhatsApp has stricter anti-spam than Telegram; don't send too many automated messages
• Less stable — WhatsApp changes their Web protocol occasionally, which can break the bridge

📖 Full WhatsApp Setup Guide →

Setup

1. Go to Discord Developer Portal → New Application
2. Go to Bot tab → create bot → copy token
3. Under OAuth2, generate an invite URL with bot + applications.commands scopes
4. Invite the bot to your server
5. Add the token to OpenClaw:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "dmPolicy": "pairing",
      "allowFrom": ["your_discord_user_id"]
    }
  }
}

Discord-specific features

• Thread support — conversations in threads keep channels clean
• autoArchiveDuration (v2026.3.11) — set thread archiving to 1h (60), 1d (1440), 3d (4320), or 1 week (10080) instead of the 1h default
• Mention gating — requireMention: true so the bot only responds when @mentioned
• Slash commands — OpenClaw skills auto-register as Discord slash commands
• Rich embeds — formatted responses with color, fields, and images

📖 Full Discord Setup Guide →

Setup

openclaw channels add imessage

The wizard walks you through granting permissions. You'll need to allow OpenClaw access to Messages via macOS Privacy settings.

Two approaches

Gotchas

• Mac must run 24/7 — if the Mac sleeps or reboots, iMessage goes offline
• Apple updates break things — macOS updates occasionally change the Messages framework
• Permissions — macOS requires granting Automation, Notifications, and sometimes Accessibility access
• No Android — only works for people messaging from Apple devices

📖 Full iMessage Setup Guide →

Setup

1. Go to api.slack.com → Create New App → From Manifest
2. Add required scopes (chat:write, app_mentions:read, im:read, im:write, etc.)
3. Enable Socket Mode (avoids public URL requirement)
4. Install the app to your workspace
5. Copy Bot Token + App Token + Signing Secret

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "signingSecret": "...",
      "dmPolicy": "pairing"
    }
  }
}

Best for

• Work assistant that lives in your Slack workspace
• Team-shared agent with per-user session isolation
• Thread-based conversations that don't clutter channels
• Integration with existing Slack workflows

📖 Full Slack Setup Guide →

Setup

# Install signal-cli (requires Java)
brew install signal-cli

# Register a phone number
signal-cli -u +15551234567 register

# Verify with SMS code
signal-cli -u +15551234567 verify 123-456

# Configure in OpenClaw
openclaw channels add signal

Why it's hard

• Java dependency — signal-cli requires a JRE
• Dedicated phone number — can't use your main Signal account
• Frequent breakage — Signal updates their protocol regularly, which breaks signal-cli
• No official bot API — this is a workaround, not an officially supported integration

WebChat is always available — it's the Control UI's built-in chat interface. There's nothing to configure. Just open your browser and go.

When to use WebChat

• Testing — verify your SOUL.md tone, USER.md context, and skill behavior before connecting a real channel
• Debugging — see raw model responses, tool calls, and context usage
• Desktop workflow — if your agent is primarily a coding/productivity assistant and you're always at your computer

Limitations

• Only accessible from your local machine (or via SSH tunnel/Tailscale)
• No push notifications — you have to check it manually
• No mobile access unless you set up remote access
• Not practical as your primary daily channel

🔌 Other supported channels

OpenClaw supports many more channels beyond the major ones above:

All channels follow the same config pattern in openclaw.json. Check docs.openclaw.ai for each channel's specific setup requirements.

🔀 Running multiple channels

One of OpenClaw's strengths — run as many channels as you want simultaneously through a single gateway.

Example: personal + work setup

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "...",
      "dmPolicy": "pairing"
    },
    "discord": {
      "enabled": true,
      "token": "...",
      "dmPolicy": "allowlist",
      "allowFrom": ["your_id"]
    },
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "dmPolicy": "pairing"
    }
  }
}

OpenClaw routes messages automatically per chat. Your agent's memory, personality, and skills are shared across all channels — the same assistant, different surfaces.

Channel-specific MESSAGING.md tone

You can set different tone rules per channel in your workspace files:

# MESSAGING.md

## Channel Tone
- iMessage: casual, brief, emoji ok
- Slack: professional, no emoji, thread-aware
- Telegram: conversational, medium length
- Discord: friendly, can use formatting/embeds

🔧 Channel troubleshooting

Universal steps

# Check all channel connections
openclaw channels status --probe

# Channel-specific logs (e.g. Telegram)
openclaw channels logs --channel telegram

# Watch live logs for channel errors
openclaw logs --follow

# Full diagnostic
openclaw doctor --deep --yes

Common issues