Connect Your First Channel

By the end of this page, you'll be able to send your agent a message on Telegram and get a reply.

Time: ~15 minutes

Why Telegram first

OpenClaw supports many channels — WhatsApp, iMessage, Slack, Discord, and more. For your first channel, Telegram is the right choice:

• No phone number pairing required
• Official Bot API — no unofficial libraries, no workarounds
• Works on any device (phone, desktop, web)
• Free and fast to set up

Step 1 — Create a Telegram bot

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Enter a name for your bot (e.g. "My OpenClaw Agent")
4. Enter a username — must end in bot (e.g. my_openclaw_bot)
5. BotFather will reply with your bot token — a string like 123456789:ABCdef...

Copy that token. You'll need it in the next step.

Step 2 — Add the channel to your config

Open ~/.openclaw/openclaw.json in a text editor. On macOS, the quickest way is:

open -e ~/.openclaw/openclaw.json

That opens it in TextEdit. Alternatively, use VS Code (code ~/.openclaw/openclaw.json) or any other editor you're comfortable with. On Windows (WSL2), run explorer.exe . from inside WSL to browse to the file in Explorer.

Your openclaw.json already has content from the setup wizard (your API key, workspace path, etc.). You need to add a channels key into the existing JSON object — don't replace the whole file.

Here's what the relevant part should look like after editing:

{
  "provider": "...",
  "channels": {
    "telegram": {
      "token": "YOUR_BOT_TOKEN_HERE",
      "dmPolicy": "pairing"
    }
  }
}

The provider line represents whatever config the wizard already created. You're only adding the "channels" block. If your file already has a "channels" key, add "telegram" inside it.

Replace YOUR_BOT_TOKEN_HERE with the token from BotFather.

After saving, validate the file isn't broken:

openclaw config validate

If it reports an error, you have a JSON syntax problem — usually a missing comma or extra bracket. Common editors show JSON errors inline.

What dmPolicy does:

• "pairing" (default) — Someone must be approved before they can message your agent. You'll approve yourself on first contact.
• "allowlist" — Only specific numeric user IDs can message the agent (use allowedUsers)
• "open" — Anyone who finds the bot can message it

"pairing" is the right default while you're getting started. To switch to an allowlist later, add allowedUsers with numeric IDs:

{
  "channels": {
    "telegram": {
      "token": "YOUR_BOT_TOKEN_HERE",
      "dmPolicy": "allowlist",
      "allowedUsers": [123456789]
    }
  }
}

To find your Telegram user ID, message @userinfobot on Telegram — it replies with your numeric ID.

Step 3 — Restart the Gateway

openclaw gateway restart

Then verify it loaded the channel:

openclaw gateway status

You should see telegram: connected in the output.

Step 4 — Pair your account

1. Open Telegram on your phone or desktop
2. Search for your bot by username (e.g. @my_openclaw_bot)
3. Send /start

Once you send /start, a pairing request is created. The easiest way to approve it:

openclaw channels pair

This shows a list of pending requests — select yours to approve it. Your bot will send you a confirmation message in Telegram once approved.

Alternatively, if you know the pairing code (shown in openclaw logs --filter telegram):

# Replace 1234 with the actual code from the logs
openclaw pairing approve telegram 1234

From now on, your account is trusted and you can message the bot freely.

Step 5 — Send a message

Go back to Telegram and send your agent a message. It should respond within a few seconds.

Try: "What can you do?"

What just happened

The flow from your Telegram message to the response:

1. Telegram sends your message to OpenClaw's webhook
2. The Gateway receives it and checks your pairing status
3. Loads your SOUL.md and USER.md for context
4. Sends the conversation to your AI provider's API
5. Streams the reply back through Telegram

Your agent is now reachable from anywhere you have Telegram.

Troubleshooting