Complete Guide to OpenClaw Telegram Integration

Pairing codes expire after 1 hour.

Allowlist Mode

{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [123456789, "@trusted_user"]
    }
  }
}

Open Mode

{
  channels: {
    telegram: {
      dmPolicy: "open"
    }
  }
}

Group Chat Support

Enable Group Access

Add group IDs to the groups object. Use "*" to allow all groups:

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {},           // specific group with defaults
        "-1009876543210": {             // specific group with overrides
          groupPolicy: "open",
          requireMention: false,
          systemPrompt: "You are a helpful coding assistant."
        }
      }
    }
  }
}

Or allow all groups:

{
  channels: {
    telegram: {
      groups: "*"
    }
  }
}

Group Policy

Control who can interact with the bot within groups:

| Setting | Description | |---------|-------------| | groupPolicy: "open" | Any group member can message the bot | | groupPolicy: "allowlist" | Only senders in groupAllowFrom can interact | | groupPolicy: "disabled" | Bot ignores all group messages |

{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: [123456789, "@allowed_user"]
    }
  }
}

Mention Requirement

By default, the bot requires an @mention in groups. You can change this per-group:

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false   // bot responds to all messages
        }
      }
    }
  }
}

Or use the session-only command /activation always in the group chat.

Per-Group Overrides

Each group entry supports these fields:

| Field | Description | |-------|-------------| | groupPolicy | Override the global group policy | | requireMention | Whether @mention is required | | skills | Skills available in this group | | allowFrom | Sender allowlist for this group | | systemPrompt | Custom system prompt for this group | | enabled | Enable/disable for this specific group |

Message Format & Chunking

HTML Parse Mode

OpenClaw sends messages using Telegram's HTML parse mode (not Markdown). Markdown from the LLM is automatically converted to HTML-safe tags. If Telegram rejects the HTML, the message is retried as plain text.

Text Chunking

Long messages are split into multiple Telegram messages:

{
  channels: {
    telegram: {
      textChunkLimit: 4000,    // max chars per message (default: 4000)
      chunkMode: "newline"     // "length" (default) or "newline"
    }
  }
}

• "length" — splits at the character limit
• "newline" — splits at paragraph boundaries before applying the length limit

Media Handling

Media Size Limit

{
  channels: {
    telegram: {
      mediaMaxMb: 5    // max file size in MB (default: 5)
    }
  }
}

Stickers

• Static stickers (WEBP) are processed through vision and described to the LLM
• Animated / video stickers are skipped
• Sticker descriptions are cached in ~/.openclaw/telegram/sticker-cache.json to avoid redundant vision calls

To enable the bot to send stickers:

{
  channels: {
    telegram: {
      actions: {
        sticker: true    // default: false
      }
    }
  }
}

History & Context

{
  channels: {
    telegram: {
      historyLimit: 50,        // group context (default: 50)
      dmHistoryLimit: 100      // DM context
    }
  }
}

Per-user DM override:

{
  channels: {
    telegram: {
      dms: {
        "123456789": {
          historyLimit: 200
        }
      }
    }
  }
}

Set to 0 to disable history.

Streaming

OpenClaw supports draft-based streaming in private chats (with forum topics enabled):

| Setting | Description | |---------|-------------| | streamMode: "off" | Streaming disabled (default) | | streamMode: "partial" | Continuous updates to a draft message | | streamMode: "block" | Chunked updates to a draft message |

Block mode settings:

{
  channels: {
    telegram: {
      streamMode: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"
      }
    }
  }
}

Webhook Mode (Production)

For production deployments, use webhooks instead of long-polling:

{
  channels: {
    telegram: {
      webhookUrl: "https://your-domain.com/telegram-webhook",
      webhookSecret: "your-random-secret-string",
      webhookPath: "/telegram-webhook"    // local path, default: /telegram-webhook
    }
  }
}

The webhook listener binds to 0.0.0.0:8787 . When webhookUrl is set, OpenClaw automatically switches from polling to webhook mode.

Commands

Native Commands

OpenClaw registers these commands with Telegram's bot menu on startup:

| Command | Description | |---------|-------------| | /start | Welcome message | | /status | Show bot status | | /reset | Reset conversation | | /model | Show / switch model |

Custom Commands

Add menu entries via config (menu-only — they don't execute unless handled elsewhere):

{
  channels: {
    telegram: {
      customCommands: [
        { command: "weather", description: "Get weather forecast" },
        { command: "translate", description: "Translate text" }
      ]
    }
  }
}

Command names must be lowercase a-z0-9_ , 1–32 characters. Leading / is stripped automatically. Cannot override native commands.

Inline Buttons

Control inline button availability:

| Setting | Scope | |---------|-------| | capabilities.inlineButtons: "off" | Disabled | | capabilities.inlineButtons: "dm" | DMs only | | capabilities.inlineButtons: "group" | Groups only | | capabilities.inlineButtons: "all" | Both DMs and groups | | capabilities.inlineButtons: "allowlist" | Both + sender filtering (default) |

Network & Proxy

{
  channels: {
    telegram: {
      timeoutSeconds: 500,        // Bot API request timeout (default: 500)
      network: {
        autoSelectFamily: false   // disable Happy Eyeballs (default on Node 22)
      },
      proxy: "socks5://127.0.0.1:1080"   // SOCKS/HTTP proxy for Bot API
    }
  }
}

Troubleshooting

Bot Not Responding

1. Verify token is correct:

curl "https://api.telegram.org/bot/getMe"

2. Check OpenClaw logs:

openclaw logs --follow

Messages Not Reaching in Groups

• Privacy mode must be disabled ( /setprivacy → Disable) or bot must be admin
• Test with /activation always (session-only); persist via requireMention: false in config

IPv6 Routing Failures

The bot may silently stop responding if IPv6 routing fails. Check DNS for api.telegram.org :

dig api.telegram.org AAAA

Fix by enabling IPv6 egress or forcing IPv4:

# Add to /etc/hosts
149.154.167.220  api.telegram.org

Or use the network config:

{
  channels: {
    telegram: {
      network: {
        autoSelectFamily: false
      }
    }
  }
}

Long-Polling Aborts (Node 22+)

Node 22 is stricter with AbortSignal instances. Upgrade OpenClaw to the latest version or downgrade to Node 20.

setMyCommands Failures

Outbound HTTPS/DNS to api.telegram.org may be blocked. Check your firewall rules.

Security Best Practices

1. Never share your bot token — revoke immediately via BotFather if compromised
2. Use pairing or allowlist for DM access control
3. Set group policies to control who can interact in groups
4. Find user IDs safely via openclaw logs --follow or the Bot API getUpdates endpoint — avoid third-party ID bots
5. Use webhooks with a secret for production deployments

Next Steps

• WhatsApp integration guide
• Discord integration guide
• Official Telegram channel docs