What does telegram-doctor diagnose?

It checks environment, API credentials, session, authentication, config file, default group, and data directory for Telegram integration.

Will telegram-doctor modify any files?

No. It only diagnoses issues and provides manual fixes.

What should I do after fixes?

Run telegram-init to reconfigure and then telegram-sync to test connectivity.

telegram-doctor

npx machina-cli add skill lycfyi/community-agent-plugin/telegram-doctor --openclaw

Files (1)

SKILL.md

2.1 KB

Telegram Doctor

Diagnose configuration and connectivity issues with Telegram integration.

When to Use

User says "Telegram not working" or "diagnose Telegram"
User reports connection or authentication errors
User says "check Telegram setup" or "troubleshoot Telegram"
Before asking for help with Telegram issues
When sync or other Telegram commands fail unexpectedly

How to Execute

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_doctor.py

What It Checks

Environment file - .env exists in cwd
API ID - TELEGRAM_API_ID is set and numeric
API hash - TELEGRAM_API_HASH is set
Session string - TELEGRAM_SESSION is set and valid length
Authentication - Credentials can connect to Telegram API
Config file - config/agents.yaml exists and is valid YAML
Group configured - A default group is selected
Data directory - data/ is writable

Output

Displays results with:

✓ for passed checks
✗ for failed checks

For each failure, provides a suggested fix that the user can run manually.

Important: This tool only diagnoses issues - it does not modify any files.

Example Output

telegram-doctor results:

  ✓ Environment file (.env found)
  ✓ API ID (12345678)
  ✓ API hash (abc123...xyz9)
  ✗ Session string (Session appears too short)
  ✗ Config file (config/agents.yaml not found)
  ✗ Group configured (No default group set)
  ✓ Data directory (./data)

Some checks failed. Suggested fixes:

  • Session string:
    Generate a fresh session: python scripts/generate_session.py

  • Config file:
    Run telegram-init to create the config file

  • Group configured:
    Run telegram-init to select a group

(Run these steps manually - doctor does not modify files)

Next Steps

After fixing issues:

Run telegram-init to reconfigure if needed
Run telegram-sync to test connectivity

Source

git clone https://github.com/lycfyi/community-agent-plugin/blob/main/plugins/telegram-connector/skills/telegram-doctor/SKILL.md

View on GitHub

Overview

Telegram Doctor is a diagnostic tool for the Telegram integration. It identifies configuration and connectivity problems that disrupt sync or cause connection errors, guiding you to manual fixes.

How This Skill Works

The tool runs a Python script to perform a sequence of checks: environment file presence, API ID and API hash values, a valid session string, authentication to Telegram, a valid config YAML, a selected default group, and writable data directory. It prints a pass/fail report using checkmarks and offers suggested fixes for each failure; it does not modify any files.

When to Use It

User says 'Telegram not working' or 'diagnose Telegram'
User reports connection or authentication errors
User says 'check Telegram setup' or 'troubleshoot Telegram'
Before asking for help with Telegram issues
When sync or other Telegram commands fail unexpectedly

Quick Start

Step 1: Run python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_doctor.py
Step 2: Review the results and note any failed checks with suggested fixes
Step 3: Apply fixes (e.g., regenerate session, fix config, select a default group) and re-run connectivity tests

Best Practices

Run telegram-doctor as the first step when Telegram issues are reported
Verify essential credentials: TELEGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION
Ensure config/agents.yaml exists and is valid YAML
Confirm a default group is configured and data directory is writable
Review the suggested fixes and re-test with telegram-sync after fixes

Example Use Cases

telegram-doctor results: ✓ Environment file (.env found) · ✓ API ID (12345678) · ✓ API hash (abc123...xyz9) · ✗ Session string (Session appears too short) · ✗ Config file (config/agents.yaml not found) · ✗ Group configured (No default group set) · ✓ Data directory (./data)
Some checks failed. Suggested fixes: • Session string: Generate a fresh session: python scripts/generate_session.py
• Config file: Run telegram-init to create the config file
• Group configured: Run telegram-init to select a group
(Run these steps manually - doctor does not modify files)

Frequently Asked Questions

Add this skill to your agents