Telegram Bot Setup

Set up a Telegram bot to interact with OpenClaw via Telegram.

Create Telegram Bot

Open Telegram and message @BotFather
Send /newbot
Set bot name (e.g., "My OpenClaw Bot")
Set username (e.g., "my_openclaw_bot")
Copy the bot token: 1234567890:ABCdef...

Add Token to Configuration

Option 1: Store in credentials file (Recommended)

mkdir -p ~/.openclaw/credentials
echo "YOUR_BOT_TOKEN" > ~/.openclaw/credentials/telegram-token.txt

Option 2: Add to config file

Update ~/.openclaw/openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "allowlist",
      "botToken": "1234567890:ABCdef...",
      "allowFrom": ["YOUR_USER_ID"]
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}

Use "allowlist" policy in production. Never use "open" with ["*"] - this allows anyone to control your agent!

Get Your Telegram User ID

Message @userinfobot
Send /start
Bot replies with your user ID (e.g., 6193457473)

Start gateway: cd ~/openclaw-armoriq && pnpm dev gateway
Send any message to your bot

Check logs:

grep senderId /tmp/openclaw/openclaw-*.log
# Look for: senderId=6193457473

Add your user ID to the config:

{
  "channels": {
    "telegram": {
      "allowFrom": ["6193457473"]
    }
  },
  "plugins": {
    "entries": {
      "armoriq": {
        "policyUpdateAllowList": [
          "6193457473",
          "@your_username",
          "telegram:6193457473"
        ]
      }
    }
  }
}

Configuration Options

Field	Description	Default
`enabled`	Enable Telegram channel	`true`
`dmPolicy`	Access control: `allowlist`, `pairing`, `open`, `disabled`	`pairing`
`botToken`	Bot token from BotFather	-
`tokenFile`	Path to file containing token	`~/.openclaw/credentials/telegram-token.txt`
`allowFrom`	User IDs allowed to interact	`[]`
`groupPolicy`	Group chat policy: `allowlist`, `open`, `disabled`	`allowlist`
`streamMode`	Response streaming: `partial`, `full`, `off`	`partial`

Security Best Practices

Use Allowlist Policy

SAFE - Only specific users can interact:

{
  "channels": {
    "telegram": {
      "dmPolicy": "allowlist",
      "allowFrom": ["6193457473", "1234567890"]
    }
  }
}

❌ DANGEROUS - Anyone who finds your bot can control it:

{
  "channels": {
    "telegram": {
      "dmPolicy": "open",
      "allowFrom": ["*"]  // NEVER DO THIS IN PRODUCTION!
    }
  }
}

Token Storage

Best practice: Store token in credentials file

~/.openclaw/credentials/telegram-token.txt

Alternative: Use environment variable

export TELEGRAM_BOT_TOKEN="1234567890:ABCdef..."

Then reference in config:

{
  "channels": {
    "telegram": {
      "botToken": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

Verify Setup

Check Configuration

# Validate JSON syntax
cat ~/.openclaw/openclaw.json | jq '.channels.telegram'

Test Bot

Start gateway:

cd /path/to/aiq-openclaw
node scripts/run-node.mjs gateway

Expected log output:

[telegram] [default] starting provider (@your_bot)

Send test message:
- Find your bot in Telegram
- Click "Start"
- Send: Hello!
- Bot should respond

Troubleshooting

Bot doesn't respond

Check:

Bot token is correct (no extra spaces)
"enabled": true for telegram channel
Your user ID is in allowFrom list
Gateway is running: look for [telegram] starting provider

Solution:

# Restart gateway
# Check logs
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep telegram

Token validation error

Error: Telegram bot token invalid

Fix:

Go to @BotFather
Send /mybots → Select your bot → "API Token"
Copy the fresh token
Update config or credentials file

Pairing required

If using "pairing" mode, check terminal for pairing code:

[telegram] Pairing required from 6193457473
[telegram] Pairing code: ABC123

Send the code to your bot to complete pairing.

Next Steps

Telegram configured!

Configure additional channels:

Telegram Setup