Module 2: Connecting Your Apps

Why this matters

Right now your agent only works through the CLI. In this module, you connect it to a real messaging app so you can chat with it from your phone — just like texting a friend.

Why Telegram first

Telegram is the fastest channel to set up:

• No phone number pairing required
• Official Bot API (free, stable)
• Works on any device
• Takes about 2 minutes

You can add WhatsApp, Slack, Discord, and more later. See the Channels guide for all supported platforms.

Step 1: Create your bot

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Choose a display name (e.g., "My OpenClaw")
4. Choose a username ending in bot (e.g., my_openclaw_bot)
5. Copy the bot token BotFather gives you

Keep this token private — anyone with it can control your bot.

Step 2: Add the channel config

In your Terminal, open your OpenClaw configuration file:

openclaw config edit

This opens ~/.openclaw/openclaw.json in your default text editor (usually VS Code, nano, or Notepad).

The file already has content from the onboarding wizard. It looks something like this:

{
  "model": "gpt-4o",
  "provider": "openai",
  "apiKey": "sk-..."
}

Add the channels section inside the outer {} brackets, after the last line, separated by a comma:

{
  "model": "gpt-4o",
  "provider": "openai",
  "apiKey": "sk-...",
  "channels": {
    "telegram": {
      "token": "YOUR_BOT_TOKEN_HERE",
      "dmPolicy": "pairing"
    }
  }
}

Replace YOUR_BOT_TOKEN_HERE with the actual token BotFather gave you (it looks like 7391827364:AAHqk...). Then save the file (Cmd+S on macOS, Ctrl+S on Windows) and close the editor.

Step 3: Understand DM policies

The dmPolicy setting controls who can message your agent:

Start with pairing — it lets you approve yourself easily, then switch to allowlist once you know your Telegram user ID.

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

For allowlist mode:

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

Step 4: Restart and pair

Save your config file, then apply the changes in your Terminal:

openclaw gateway restart

Check that Telegram is showing as connected:

openclaw gateway status

You should see:

Gateway: running
Channels:
  ✓ telegram     connected

Now go to Telegram on your phone or computer and search for your bot by username (the one you set with BotFather, e.g. @my_openclaw_bot). Tap it and send /start.

With pairing mode, OpenClaw holds the request until you approve it. Back in your Terminal, run:

openclaw channels pair

You will see something like:

Pending pairing requests:
  1. Telegram — @yourusername (ID: 123456789)

Approve? [y/n]:

Type y and press Enter. You are now paired and connected.

Step 5: Test it

Send a message to your bot in Telegram:

Hello! What can you do?

You should get a response within a few seconds. The agent reads your SOUL.md and USER.md on each message, sends the request to your AI provider, and streams the response back.

Troubleshooting

Check logs for more detail:

openclaw logs --filter telegram

Validate your config file syntax:

openclaw config validate

Adding more channels

Once Telegram is working, you can add other channels the same way. Each channel gets its own section in the config with its own DM policy.

Each channel has a dedicated setup guide:

• Telegram — easiest to set up, official Bot API, recommended first channel
• WhatsApp — scan a QR code to link, unofficial API, works for personal use
• Slack — Socket Mode, no public URL needed, best for work contexts
• Discord — bot application, great for communities
• iMessage — Mac only, requires BlueBubbles or AirMessage bridge
• Microsoft Teams — official Teams SDK, enterprise grade
• Signal — end-to-end encrypted, privacy first
• Web Chat — embeddable widget for websites

If you hit issues connecting a channel, the troubleshooting guide covers the most common errors.