OpenClaw channels add: Pair New Messaging Platforms in One Command

Your agent is running. Your gateway is healthy. But it can't receive messages from anywhere until you pair a channel. That's exactly what openclaw channels add solves — it creates the routing link between a messaging platform and your agent in a single command. Done right, the first message arrives within seconds of running it.

What openclaw channels add Actually Does

When you run openclaw channels add, three things happen in sequence. First, the CLI sends your platform credentials to the gateway for validation. Second, the gateway registers a routing rule that maps incoming messages from that platform to your target agent. Third, for webhook-based platforms, the gateway sends a registration request to the platform's API to subscribe to incoming events.

This is not a configuration file edit. The gateway stores channel registrations in its own state — meaning you don't need to restart anything after running the command. The channel is live the moment the command completes successfully.

Each channel gets a unique name you assign with --name. That name is how you reference the channel in every subsequent command — pairing, removing, routing rules. Pick something descriptive. telegram-support is far more maintainable than channel-1.

Full Command Syntax and Flags

The base command structure is straightforward:

openclaw channels add \
  --type [platform] \
  --token [your-api-token] \
  --name [channel-name] \
  --agent [agent-id]

Here's every flag and what it controls:

Platform-Specific Examples

Each platform has slightly different requirements. Let's go through the ones you're most likely to use.

Telegram

Get your bot token from @BotFather. Then run:

openclaw channels add \
  --type telegram \
  --token 7412938475:AAFkdj8s9f7sd8f7s9d8f7sd9f \
  --name telegram-support \
  --agent support-agent-01

Telegram uses long-polling by default — your gateway polls Telegram's servers for new messages. No public URL required. This makes Telegram the easiest channel to add on a local or VPN-only setup.

Discord

Create a Discord application and bot in the Discord Developer Portal. Copy the bot token, not the application ID. Then run:

openclaw channels add \
  --type discord \
  --token MTI4OTQ3NTgzMTY3NDc2MzI2NA.G_token_example \
  --name discord-community \
  --agent community-agent-01

Discord requires your gateway to have websocket access. If you're behind a restrictive firewall, confirm outbound websocket traffic to Discord's gateway endpoints is allowed.

Webhook (Custom)

For custom integrations or platforms not natively supported, use the webhook type:

openclaw channels add \
  --type webhook \
  --name custom-crm \
  --agent crm-agent-01 \
  --webhook-url https://your-gateway.example.com/hook/custom-crm

The webhook URL is the endpoint on your gateway that receives POST requests from the external system. The command registers a handler at that path and returns a secret signing key you should configure in the external system to authenticate its payloads.

Verifying the Connection

Run the pairing list immediately after adding a channel:

openclaw pairing list

You're looking for two things. First, your new channel should appear in the list. Second, its status should show connected. A status of pending means the platform hasn't confirmed the registration yet — this is normal for webhook platforms that require a handshake. Wait 10–15 seconds and run the command again.

If the status stays pending after 30 seconds, check the gateway logs:

openclaw logs --tail 50 --filter channel

The log will show exactly where the registration failed — invalid token, unreachable webhook URL, or a platform API error with a specific error code you can look up.

Common Mistakes When Adding Channels

• Wrong token type — Telegram bot tokens look like 1234567890:ABCdef.... If yours doesn't match this format, you copied the wrong value from BotFather. Discord tokens are much longer. Using an application ID instead of a bot token is a frequent error.
• Using localhost as the webhook URL — Platforms can't reach your machine's localhost from the internet. Always use a public domain or an ngrok tunnel for development.
• Duplicate channel names — Running the command twice with the same --name will fail. Check the pairing list before re-running if you're not sure whether a previous attempt succeeded.
• Wrong agent ID — The --agent value must match an agent that's currently registered with the gateway. If the agent isn't running, the channel adds successfully but messages queue rather than process — which can look like a channel problem when it's actually an agent problem.
• Missing gateway permissions — Some enterprise gateway configurations restrict which platforms can be registered. If you get a 403 during channel add, check your gateway's allowed_channel_types config.

Frequently Asked Questions

What does openclaw channels add do?

The command registers a new messaging platform — Telegram, WhatsApp, Signal, Discord, or a custom webhook — with the OpenClaw gateway. Once registered, messages sent to that platform are routed directly to your agent for processing.

What flags does openclaw channels add support?

The main flags are --type to specify the platform, --token for the bot token or API key, --name to assign a unique label, and --agent to link the channel to a specific agent. Webhook-based platforms also use --webhook-url.

Can I add multiple channels to one agent?

Yes. Run openclaw channels add once for each platform. The agent handles all channels simultaneously — a Telegram message and a Discord message are both routed to the same agent and processed in parallel by default.

Why does my channel fail to connect after running channels add?

The most common cause is an invalid bot token or API key. Verify the token against the platform's developer portal. Also confirm your gateway is reachable from the internet if using webhook-based platforms — platforms can't deliver events to a localhost endpoint.

How do I verify a channel was added successfully?

Run openclaw pairing list after adding the channel. A status of connected confirms success. If it shows pending, the platform hasn't confirmed the handshake yet — check gateway logs for the specific error message.

Can I remove a channel after adding it?

Yes. Use openclaw channels remove --name [channel-name] to deregister. This removes the routing rule from the gateway and stops the agent from receiving messages from that platform. The platform bot itself is not deleted — manage that from the platform's own portal.