Openclaw Telegram Config

Setting up OpenClaw with Telegram lets you control your AI agent from anywhere using a familiar messaging app. Whether you're building a personal assistant or deploying an agent for your team, Telegram provides a reliable channel that works on every device without custom apps or complex infrastructure.

This guide walks through every step of configuring OpenClaw with Telegram, from creating your bot with BotFather to securing it for production use. You'll learn which settings matter most, how to avoid common mistakes, and how to optimize your setup based on real-world usage patterns.

Quick Answer

OpenClaw Telegram configuration requires creating a bot through Telegram's BotFather, copying the bot token, and adding it to your OpenClaw config file under channels.telegram.botToken. You must also choose a dmPolicy (pairing, allowlist, or open) to control who can interact with your bot, and decide between polling mode (simpler) or webhook mode (more efficient for production).

What Is OpenClaw Telegram Configuration and Why Does It Matter?

OpenClaw is an open source AI agent framework that connects large language models to various communication channels. Telegram is one of the built-in channels, meaning it's included in the core OpenClaw installation rather than added as a separate plugin.

Configuring OpenClaw with Telegram turns your agent into a bot that people can message just like any other Telegram contact. This makes your AI agent accessible from any device where Telegram runs, without building custom interfaces or managing user authentication yourself.

The configuration process establishes a secure connection between your OpenClaw instance and Telegram's servers. You control who can access the bot, how it responds in different contexts, and whether it uses polling or webhooks to receive messages.

Getting this configuration right matters because mistakes can expose your agent to unauthorized users or cause your bot to silently fail. A properly configured OpenClaw Telegram bot responds reliably, protects your API quotas from abuse, and scales as your usage grows.

How Do You Create a Telegram Bot for OpenClaw Using BotFather?

Creating a Telegram bot starts with BotFather, Telegram's official bot creation tool. Every Telegram bot, including those powered by OpenClaw, originates from this single source.

Open Telegram and search for @BotFather. This is the only legitimate bot creation tool—don't use any third-party services claiming to create Telegram bots. Start a chat with BotFather and send the /newbot command.

BotFather will ask for two things. First, enter a display name for your bot. This is what users see in their chat list, so choose something descriptive like "My OpenClaw Assistant" or "Team AI Helper." The display name can include spaces and doesn't need to be unique.

Next, enter a username for your bot. This must end with "bot" or "_bot" and must be globally unique across Telegram. For example, mycompany_openclaw_bot works, but mycompany_assistant doesn't. If your first choice is taken, try adding numbers or underscores.

When you successfully create the bot, BotFather responds with a bot token. This token looks like 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz. Copy this token immediately and store it securely—you'll need it for the OpenClaw configuration.

Treat your bot token like a password. Anyone with this token has complete control over your bot. Never commit it to version control systems, share it in public forums, or paste it into screenshots. If the token is ever compromised, return to BotFather and use the /token command to generate a new one.

What Are the Required Configuration Settings for OpenClaw Telegram?

OpenClaw stores its configuration in a JSON file, typically named openclaw.json. The Telegram channel configuration lives under the channels.telegram section. Understanding each setting helps you make informed choices rather than copying examples blindly.

The most critical setting is botToken. This is the token you received from BotFather. You can paste it directly into the config file, but a better practice uses environment variables. Set botToken: "${TELEGRAM_BOT_TOKEN}" in your config, then define TELEGRAM_BOT_TOKEN as an environment variable on your system.

The enabled flag must be set to true for OpenClaw to activate the Telegram channel. This seems obvious, but it's a common oversight when troubleshooting why a bot isn't responding.

The dmPolicy setting controls who can send direct messages to your bot. Three options exist: pairing, allowlist, and open. Pairing mode (recommended for most users) shows new users a six-digit code that you must approve before they can interact with your bot. Allowlist mode only accepts messages from specific user IDs you define in advance. Open mode lets anyone message your bot immediately, which risks rapid API quota consumption unless you've carefully constrained your bot's capabilities.

Here's a basic configuration that works for most OpenClaw Telegram setups:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "pairing"
    }
  }
}

For group chat support, you'll need additional settings. The groupPolicy setting works like dmPolicy but applies to group conversations. The requireMention flag determines whether users must @mention your bot in groups for it to respond.

Some deployments need polling: false when using webhook mode, but polling is the default and works well for most situations. We'll explore when to switch to webhooks later in this guide.

Should You Use Polling or Webhook Mode for Your OpenClaw Telegram Bot?

OpenClaw supports two methods for receiving Telegram messages: polling and webhooks. Each has distinct advantages, and the right choice depends on your deployment environment and scale.

Polling is OpenClaw's default mode. In polling mode, your OpenClaw instance regularly asks Telegram's servers "do you have any new messages for me?" This happens several times per second, creating a responsive experience while requiring no special network configuration.

Polling works great for development environments, self-hosted setups behind NAT or firewalls, and small to medium deployments. It requires zero external infrastructure—just start OpenClaw with a valid bot token and it immediately begins polling for messages. If your server's IP address changes or you're running on a laptop, polling continues working without any configuration updates.

Webhook mode reverses this relationship. Instead of OpenClaw asking for messages, Telegram pushes messages directly to your server the moment they arrive. This eliminates polling overhead and reduces latency between when a user sends a message and when your bot responds.

However, webhooks require a publicly accessible HTTPS endpoint. Telegram only delivers webhooks to URLs using valid SSL certificates—self-signed certificates are rejected. You'll need a domain name, a reverse proxy like nginx or Caddy, and proper SSL certificate management.

Here's when to choose each approach:

Consideration	Polling Mode	Webhook Mode
Setup complexity	Very simple	Moderate to complex
Network requirements	None (works behind NAT)	Public HTTPS endpoint required
Best for	Development, self-hosted, VPS	Production, cloud deployments
Latency	Slight delay (milliseconds)	Instant delivery
Server load	Regular polling requests	Only receives when messages arrive
Cost efficiency	Good for low volume	Better for high volume

To enable webhook mode, add these settings to your Telegram configuration:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "polling": false,
      "webhookUrl": "https://yourdomain.com/webhook/telegram",
      "webhookSecret": "${TELEGRAM_WEBHOOK_SECRET}",
      "webhookPort": 8787
    }
  }
}

The webhookUrl must be your publicly accessible HTTPS URL. The webhookSecret prevents unauthorized POST requests from reaching your bot. OpenClaw listens on webhookPort (default 8787) for incoming webhook payloads from Telegram.

Most OpenClaw users should start with polling mode. It works immediately without infrastructure complexity. Switch to webhooks later if you're processing hundreds of messages per hour or running in a production cloud environment where public HTTPS endpoints are standard.

How Do You Secure Your OpenClaw Telegram Bot with dmPolicy and Pairing?

Security is the most important aspect of OpenClaw Telegram configuration that newcomers often overlook. An improperly secured bot can drain your API budget in hours or give strangers access to your agent's capabilities.

The dmPolicy setting is your first line of defense. It determines who can send direct messages to your bot and have them processed by OpenClaw. Three modes exist, each with different security profiles.

Pairing mode is the recommended default for most users. When someone sends your bot a direct message for the first time, they receive a six-digit pairing code. Your bot doesn't process their message until you approve that specific code using the command openclaw pairing approve telegram <code>.

This approval process adds that user to a persistent allowlist stored in OpenClaw's credentials directory. Future messages from that user are processed automatically without requiring new pairing codes. Pairing codes expire after one hour, preventing someone from approving themselves if they briefly access your terminal.

Allowlist mode is more restrictive. You must explicitly add user IDs to the allowlist before those users can interact with your bot at all. Messages from users not on the allowlist are silently ignored—they don't even receive a pairing code or error message.

To use allowlist mode, add user IDs to your configuration:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "allowlist",
      "allowFrom": [123456789, 987654321]
    }
  }
}

Always use numeric user IDs, not @usernames. Usernames can change, but user IDs are permanent. Get your Telegram user ID from bots like @userinfobot or from OpenClaw's logs when you send a message.

Open mode removes all access restrictions. Anyone who finds your bot can immediately start conversations with it. Only use open mode if you're intentionally running a public bot with carefully constrained tools and capabilities. Even then, implement rate limiting to protect your API budget.

Understanding your API costs becomes critical when running an OpenClaw Telegram bot, especially in open mode where usage is unpredictable.

Group chats have their own security layer through groupPolicy. The same pairing, allowlist, and open modes apply, but they work at the group level rather than the individual user level. When someone adds your bot to a group, OpenClaw logs a pairing request for that group's chat ID. Approve it using the same openclaw pairing approve telegram <code> command.

One crucial detail: group sender authentication doesn't inherit direct message approvals. If you've approved Alice for direct messages and she adds your bot to a group, the group itself needs separate approval. This prevents Alice from giving unauthorized users access to your bot by adding it to groups they control.

The requireMention setting adds another security layer for groups. When enabled, your bot only responds to messages that @mention it by username. This prevents your bot from processing every message in busy groups, reducing both your API costs and the risk of inappropriate responses.

How Do You Configure OpenClaw to Work in Telegram Group Chats?

Group chats introduce complexity that direct messages don't have. Multiple participants send messages simultaneously, conversations branch into different topics, and you need to decide when your bot should participate versus staying silent.

The first decision is whether your bot responds to every message or only to @mentions. The requireMention setting controls this behavior. When set to true, users must include your bot's @username anywhere in their message for it to respond.

Here's what this looks like in practice:

@mybot_openclaw what's the weather? — Bot responds
Hey @mybot_openclaw, can you summarize this thread? — Bot responds
Let me check with @mybot_openclaw about this — Bot responds
What's the weather? — Bot ignores (no @mention)

Replies to your bot's messages count as continuations. If your bot responds to a user's question, that user can reply to the bot's message without using @mention again. This creates natural multi-turn conversations without cluttering the group with repeated mentions.

If you set requireMention: false, your bot sees and can respond to every message in the group. This requires changing Telegram's privacy mode through BotFather. Send /setprivacy to BotFather, select your bot, then choose "Disable" to let your bot see all messages.

Keep in mind that seeing all messages means your bot processes every message through OpenClaw's routing logic, potentially calling your LLM provider for each one. Choosing between local LLMs and cloud APIs matters significantly when your bot participates in active group conversations.

Group-specific configuration lives under groups in your Telegram channel settings:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "groupPolicy": "pairing",
      "requireMention": true,
      "groups": {
        "-1001234567890": {
          "requireMention": false
        }
      }
    }
  }
}

The group ID is always negative for group chats and supergroups. Find your group's ID by adding your bot to the group, sending a message, then checking OpenClaw's logs with openclaw logs --follow. Look for entries showing chat.id values.

This configuration allows per-group overrides. In the example above, all groups require @mentions by default, but the specific group -1001234567890 has mentions disabled. This flexibility lets you tune behavior based on each group's size and activity level.

Commands work differently in groups than in direct messages. Built-in commands like /status, /reset, and /new are available in both contexts. When someone uses a command in a group, only the person who invoked it sees the response (Telegram shows it as an ephemeral message).

One common mistake is adding a bot to multiple groups and forgetting that each needs approval. If your bot works in direct messages but stays silent in groups, check whether you've approved that specific group's pairing code.

What Are the Most Common OpenClaw Telegram Configuration Errors and How Do You Fix Them?

Certain configuration mistakes appear repeatedly across OpenClaw Telegram deployments. Knowing these patterns helps you troubleshoot faster when your bot doesn't behave as expected.

401 Unauthorized errors mean your bot token is wrong or expired. This usually happens when you copy the token incorrectly, include extra spaces, or generate a new token without updating your configuration. Get a fresh token from BotFather using /token, update your config or environment variable, and restart OpenClaw.

Bot connects but doesn't respond to messages is the most frustrating issue because everything appears to work. The bot shows as online, no errors appear in logs, but messages vanish into silence. This almost always traces to allowFrom configuration problems.

If you specified usernames like @alice instead of numeric IDs like 123456789, OpenClaw tries to resolve the username when it starts. This resolution fails if the username changed, is misspelled, or the bot has never seen that user before. The fix: always use numeric user IDs from @userinfobot or OpenClaw's logs.

"Telegram plugin not available" errors happen when you put configuration in the wrong place. Telegram is a built-in channel, not a plugin. Your config should have channels.telegram, not plugins.telegram. This seems obvious but catches people who learned OpenClaw before the channel/plugin distinction clarified.

Group messages being ignored usually means one of three things. First, you haven't approved the group's pairing code yet. Second, users aren't @mentioning the bot when requireMention: true. Third, Telegram privacy mode prevents your bot from seeing messages when requireMention: false. Check all three before looking elsewhere.

"Message thread not found" errors occur in groups with Topics/Forum mode. When you disable forum mode after using it, OpenClaw continues including thread IDs in its API calls. Telegram rejects these as invalid. The fix involves resetting the conversation state or upgrading to a newer OpenClaw version that handles this automatically.

Configuration file syntax errors break OpenClaw startup. JSON is picky about commas, quotes, and brackets. The most common mistakes include trailing commas after the last item in an object or array (JavaScript allows this, but standard JSON doesn't), missing quotes around keys or string values, and mismatched brackets.

Run openclaw config validate to check your syntax before starting the gateway. This catches most configuration errors before they cause runtime failures.

For issues that aren't immediately obvious, follow this diagnostic sequence:

Run openclaw doctor to get a complete health check
Check openclaw status to see channel connection states
View logs with openclaw logs --follow while testing
Verify your bot token works by testing it with Telegram's API directly
Confirm user IDs and group IDs match what's in your configuration

Most configuration problems become obvious within the first few minutes of checking logs. Look for "401" anywhere (authentication failures), "chat_id" or "user_id" values that don't match your expectations, and any mention of "pairing" or "allowlist" rejections.

How Do You Optimize Your OpenClaw Telegram Bot for Production Use?

Moving from a working prototype to a production-ready OpenClaw Telegram bot requires thinking through reliability, security, and cost management. A bot that works fine for personal use can fail spectacularly when opened to a team or public audience.

Switch to webhook mode once you're running on stable infrastructure with a domain name. Webhooks reduce server load by eliminating constant polling and decrease response latency for users. Set up your reverse proxy to handle SSL termination, route /webhook/telegram to your OpenClaw instance, and configure the webhook settings in your OpenClaw config.

Never leave dmPolicy: "open" in production unless you've implemented strict rate limiting. Even well-intentioned users can trigger expensive API calls by asking complex questions or requesting long summaries. LLM routing gateways help control costs by directing simple questions to cheaper models while reserving expensive models for complex tasks.

Use environment variables for all sensitive configuration. At minimum, set TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET as environment variables rather than hardcoding them in config files. This prevents accidental token exposure through version control or log files.

Monitor your bot's usage patterns to understand typical message volumes and peak times. Many OpenClaw deployments see spikes when team members join in the morning or when scheduled reports trigger. Knowing these patterns helps you provision resources appropriately.

Set up health monitoring that alerts you when your bot becomes unresponsive. A simple approach checks whether your bot responds to a /status command from a test account every few minutes. More sophisticated setups monitor OpenClaw's own health endpoints.

Consider implementing command shortcuts for frequent tasks. If your team constantly asks for the same reports or information, create custom commands that trigger those workflows directly. This reduces message lengths, speeds up responses, and lowers costs per interaction.

For group chats with many participants, keep requireMention: true to avoid processing every message. Even with fast, cheap models, processing hundreds of messages per day adds up. Let users explicitly invoke your bot when they need it.

Document your bot's capabilities somewhere your users can find it. People waste messages experimenting with commands or asking what the bot can do. A simple onboarding message with examples and a link to full documentation prevents confusion.

Implement backup and recovery procedures for your OpenClaw configuration and pairing allowlists. These files live in ~/.openclaw/ by default. Losing them means reconfiguring everything and re-approving all users.

Plan for API provider failures by testing what happens when your LLM provider is down. Should your bot return an error message, queue the request, or fail silently? Having a strategy prevents user frustration during outages.

Comparing model costs for your typical workload helps you choose the right balance between quality and cost. Some OpenClaw deployments save 80% by routing simple greetings and commands to fast, cheap models while reserving advanced models for complex reasoning.

Comparison: Polling vs Webhook Mode

Feature	Polling Mode	Webhook Mode
Setup Difficulty	Simple, works immediately	Requires domain, SSL, reverse proxy
Network Requirements	None, works behind firewalls	Public HTTPS endpoint mandatory
Message Latency	100-500ms typical	Near-instant (< 50ms)
Server Resource Usage	Constant polling overhead	Only processes incoming messages
Best Use Cases	Development, personal use, VPS behind NAT	Production, cloud deployments, high volume
Reliability	Self-recovering, no external dependencies	Depends on webhook delivery
Configuration Complexity	3 settings (enabled, botToken, dmPolicy)	7+ settings (webhookUrl, port, secret, etc.)
Cost Efficiency	Good for < 100 messages/hour	Better for > 100 messages/hour

Frequently Asked Questions

Q: Do I need a domain name to run OpenClaw with Telegram?

No, polling mode works without a domain name. You only need a domain if you want to use webhook mode for production deployments. Most personal and small team setups work fine with polling.

Q: Can multiple people use the same OpenClaw Telegram bot?

Yes. Use dmPolicy: "pairing" or dmPolicy: "allowlist" to control who can access your bot. Approve each user through the pairing system or add their user IDs to the allowlist in your configuration.

Q: What happens if someone adds my bot to a group without permission?

If you're using groupPolicy: "pairing", the bot won't respond until you approve that group's pairing code. Messages from unapproved groups are ignored. This protects your API quota from unauthorized use.

Q: Why does my bot work in direct messages but not in groups?

Each group requires separate approval, even if you've approved individual users for direct messages. Check OpenClaw's logs for the group's pairing code and approve it with openclaw pairing approve telegram <code>.

Q: How do I get my Telegram user ID?

Message the bot @userinfobot on Telegram. It will immediately reply with your user ID, username, and other details. Use the numeric user ID (not the username) in OpenClaw's allowlist configuration.

Q: Can I change my bot's name after creating it?

Yes. Contact @BotFather, send /setname, select your bot, and enter the new name. This changes the display name but not the username. Usernames can't be changed, but you can create a new bot if needed.

Configuring OpenClaw with Telegram opens up powerful possibilities for accessing your AI agent from anywhere. By following the setup steps carefully, choosing appropriate security settings, and optimizing for your specific use case, you'll have a reliable bot that serves your needs without surprises.

The key is starting simple with polling mode and pairing security, then adjusting as you understand your usage patterns. Most configuration mistakes happen when people try to implement every option at once rather than building up complexity gradually.

How to Configure OpenClaw with Telegram: Complete Setup Guide for Your AI Bot