FERAL FLEET • GSTACK • OPENCLAW • HERMES • GROK

Telegram Channel Implementations
Across Agent Runtimes

A deep comparison of the official Anthropic Claude Code Telegram plugin vs. how OpenClaw and Hermes consume/adapt it, plus a native design recommendation for Grok.

View Grok Native Plan Jump to Feature Matrix
Claude Code Official
anthropic/claude-plugins-official • telegram

The reference implementation. Mature, extremely careful security model, battle-tested zombie defense, pairing flow, and permission relay via Telegram DMs.

server.ts + grammy + MCP
State: ~/.claude/channels/telegram-*
Skills: /telegram:access + /telegram:configure
OpenClaw
Full independent Telegram implementation

OpenClaw ships its own complete Telegram channel implementation in extensions/telegram/. It has a dedicated bot runtime, ingress spool, outbound delivery, threading, approvals, media handling, polling/webhook monitors, native commands, and deep plugin-sdk integration. Not a reuse of Claude's code.

Core: extensions/telegram/src/bot*.ts + channel.ts
Strong focus on agent runtime integration, threading, and native command surface.
UI management in ui/src/ui/views/channels.telegram.ts
Hermes
Custom gateway platform (Nous Research)

Hermes has a first-class gateway/platforms/telegram.py + telegram_network.py. Built on python-telegram-bot with heavy emphasis on delivery reliability (text batching, noise filtering, forum support, conflict handling, DoH-based IP fallbacks for censored networks, advanced media handling).

Architecture: Gateway platform adapter model
Network resilience is a first-class concern (see telegram_network.py)
Extensive test coverage for real-world Telegram edge cases

Feature & Architecture Matrix

How the core Telegram channel capabilities are implemented or adapted across the three systems.

Capability Claude Official OpenClaw (via gstack) Hermes (via gstack) Grok (current / planned)
Core Implementation ✓ Full grammy + MCP server.ts (Claude channel model) Independent full implementation (extensions/telegram + plugin-sdk) Independent gateway platform (gateway/platforms/telegram.py + network layer) Currently reuses Claude cache; native fork planned
State Directory ~/.claude/channels/telegram-* Can be pointed via env + skill rewrites Rewritten paths in skills Planned: ~/.grok/channels/telegram-*
Pairing + Access Control Excellent (access.json, pairing codes, dmPolicy, allowFrom) Same (skill adapts) Same (skill adapts) Planned to keep verbatim + Grok paths
Permission Relay (DM approvals) Full inline keyboard + y/n reply flow Available if Claude-style notifications emitted Available if emitted Optional / less central (Grok prefers flags)
Zombie / PID Defense Outstanding (PID file + SIGHUP + orphan watchdog + 409 retry) Inherited from server Inherited Keep verbatim in native port
Skills UX /telegram:access + /telegram:configure Rewritten paths + tool names via host Rewritten (terminal, patch, etc.) Native Grok skills + /telegram:*
Attachment / Vision Handling download_attachment tool + image_path Depends on host vision Depends on host Will need Grok vision alignment
Multi-bot Support TELEGRAM_STATE_DIR per bot Via env Via env Planned identical
Plugin / Distribution Model claude-plugins-official marketplace + --channels flag gstack skill adaptation layer gstack skill adaptation layer Native grok plugin or first-class channel (planned)

Architecture Deep Dive

Official Claude Telegram (MCP Server)

  • • Grammy polling loop with sophisticated PID/zombie defense (one of the best in the ecosystem).
  • • Full MCP server exposing reply / react / edit_message / download_attachment.
  • • Declares 'claude/channel' and 'claude/channel/permission' capabilities.
  • • Emits notifications/claude/channel with rich metadata (chat_id, message_id, attachments, images via local paths).
  • • Sophisticated access.json + pairing code system with rate limiting and DM-only commands.
  • • Optional remote permission relay (inline keyboards in DMs for tool approval).

OpenClaw & Hermes (Independent Implementations)

Both projects have built substantial, independent Telegram channel/gateway code rather than just wrapping the Claude one.

  • OpenClaw: Full bot runtime in extensions/telegram/ with its own ingress, outbound, threading, approvals, media, polling, and deep integration with OpenClaw's plugin-sdk and conversation model.
  • Hermes: Mature gateway platform (gateway/platforms/telegram.py) with exceptional focus on delivery quality (batching, noise filtering, forum threads, network fallbacks via DoH, etc.).
  • Both are architecturally distinct from Claude's grammy+MCP channel approach.

Security & Robustness Model

The official Claude implementation is one of the most carefully engineered channel bridges in the agent space. Key invariants that should be preserved:

Key difference for Grok/OpenClaw/Hermes: The remote permission relay (DM approvals) is less central because these runtimes lean more heavily on CLI flags, allowlists, and timeouts. The relay can be kept for compatibility but should be optional.

Recommended Design for Grok Telegram Integration

Based on feral-cc-bots/grok/telegram-channel/ analysis + this comparison

Phase 1 (MVP — ship quickly)
  • Fork the server.ts into grok/telegram-channel/server.ts
  • Change default STATE_DIR to ~/.grok/channels/telegram
  • Update all branding and comments
  • Make permission relay conditional (TELEGRAM_ENABLE_PERMISSION_RELAY)
  • Port the two skills with Grok paths and frontmatter
  • Document grok mcp add + env var launch pattern
Phase 2+ (Native experience)
  • Proper Grok plugin packaging (with .mcp.json + skills)
  • grok telegram configure <token> one-command setup
  • Native grok --channel telegram or equivalent launch helper
  • Migration tool from existing .claude state
  • Consider bundling the server into the Grok binary long-term (or make it a first-class channel)
  • Align image/attachment contract with Grok vision pipeline
Preserve at all costs: The PID/zombie defense logic, the access.json schema and pairing flow, the security gates, and the chunking + UX niceties (typing indicators, reactions). These are the parts that make the Claude implementation production-grade.