romtuck/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e5c904b50f
openclaw/PR-PREP-GRAMJS-PHASE1.md

9.2 KiB
Raw Blame History

PR Preparation: GramJS Phase 1 - Telegram User Account Adapter

Status: ✅ Ready for PR submission
Branch: fix/cron-systemevents-autonomous-execution
Commit: 84c1ab4d5
Target: openclaw/openclaw main branch

Summary

Implements Telegram user account support via GramJS/MTProto, allowing openclaw agents to access personal Telegram accounts (DMs, groups, channels) without requiring a bot.

Closes: #937 (Phase 1)

What's Included

✅ Complete Implementation

  • 18 files added/modified
  • 3,825 lines of new code
  • 2 test files with comprehensive coverage
  • 14KB documentation with setup guide, examples, troubleshooting

Core Features

  • ✅ Interactive auth flow (phone → SMS → 2FA)
  • ✅ Session persistence via encrypted StringSession
  • ✅ DM message send/receive
  • ✅ Group message send/receive
  • ✅ Reply context preservation
  • ✅ Multi-account configuration
  • ✅ Security policies (pairing, allowlist, dmPolicy, groupPolicy)
  • ✅ Command detection (/start, /help, etc.)

Test Coverage

  • ✅ Auth flow tests (mocked readline and client)
  • ✅ Message conversion tests (DM, group, reply)
  • ✅ Phone validation tests
  • ✅ Session verification tests
  • ✅ Edge case handling (empty messages, special chars, long text)

Documentation

  • ✅ Complete setup guide (docs/channels/telegram-gramjs.md)
  • ✅ Getting API credentials walkthrough
  • ✅ Configuration examples (single/multi-account)
  • ✅ Security best practices
  • ✅ Troubleshooting guide
  • ✅ Migration from Bot API guide

Files Changed

Core Implementation (src/telegram-gramjs/)

auth.ts             - Interactive auth flow (142 lines)
auth.test.ts        - Auth tests with mocks (245 lines)
client.ts           - GramJS client wrapper (244 lines)
config.ts           - Config adapter (218 lines)
gateway.ts          - Gateway adapter (240 lines)
handlers.ts         - Message handlers (206 lines)
handlers.test.ts    - Handler tests (367 lines)
setup.ts            - CLI setup wizard (199 lines)
types.ts            - Type definitions (47 lines)
index.ts            - Module exports (33 lines)

Configuration

src/config/types.telegram-gramjs.ts  - Config schema (237 lines)

Plugin Extension

extensions/telegram-gramjs/index.ts              - Plugin registration (20 lines)
extensions/telegram-gramjs/src/channel.ts        - Channel plugin (275 lines)
extensions/telegram-gramjs/openclaw.plugin.json  - Manifest (8 lines)
extensions/telegram-gramjs/package.json          - Dependencies (9 lines)

Documentation

docs/channels/telegram-gramjs.md    - Complete setup guide (14KB, 535 lines)
GRAMJS-PHASE1-SUMMARY.md            - Implementation summary (1.8KB)

Registry

src/channels/registry.ts  - Added telegram-gramjs to CHAT_CHANNEL_ORDER

Breaking Changes

None. This is a new feature that runs alongside existing channels.

  • Existing telegram (Bot API) adapter unchanged
  • Can run both telegram and telegram-gramjs simultaneously
  • No config migration required
  • Opt-in feature (disabled by default)

Testing Checklist

Unit Tests ✅

  • Auth flow with phone/SMS/2FA (mocked)
  • Phone number validation
  • Session verification
  • Message conversion (DM, group, reply)
  • Session key routing
  • Command extraction
  • Edge cases (empty messages, special chars, long text)

Integration Tests ⏳

  • End-to-end auth flow (requires real Telegram account)
  • Message send/receive (requires real Telegram account)
  • Multi-account setup (requires multiple accounts)
  • Gateway daemon integration (needs openclaw built)

Note: Integration tests require real Telegram credentials and are best done by maintainers.

Dependencies

New Dependencies

  • telegram@^2.24.15 - GramJS library (MTProto client)

Peer Dependencies (already in openclaw)

  • Node.js 18+
  • TypeScript 5+
  • vitest (for tests)

Documentation Quality

Setup Guide (docs/channels/telegram-gramjs.md)

  • 📋 Quick setup (4 steps)
  • 📊 Feature comparison (GramJS vs Bot API)
  • ⚙️ Configuration examples (single/multi-account)
  • 🔐 Security best practices
  • 🛠️ Troubleshooting (8 common issues)
  • 📖 API reference (all config options)
  • 💡 Real-world examples (personal/team/family setups)

Code Documentation

  • All public functions have JSDoc comments
  • Type definitions for all interfaces
  • Inline comments for complex logic
  • Error messages are clear and actionable

Known Limitations (Phase 1)

Not Yet Implemented

  • ⏳ Media support (photos, videos, files) - Phase 2
  • ⏳ Voice messages - Phase 2
  • ⏳ Stickers and GIFs - Phase 2
  • ⏳ Reactions - Phase 2
  • ⏳ Message editing/deletion - Phase 2
  • ⏳ Channel messages - Phase 3
  • ⏳ Secret chats - Phase 3
  • ⏳ Mention detection in groups (placeholder exists)

Workarounds

  • Groups: requireMention: true is in config but not enforced (all messages processed)
  • Media: Skipped for now (text-only)
  • Channels: Explicitly filtered out

Migration Path

For New Users

  1. Go to https://my.telegram.org/apps
  2. Get api_id and api_hash
  3. Run openclaw setup telegram-gramjs
  4. Follow prompts (phone → SMS → 2FA)
  5. Done!

For Existing Bot API Users

Can run both simultaneously:

{
  channels: {
    telegram: {          // Existing Bot API
      enabled: true,
      botToken: "..."
    },
    telegramGramjs: {    // New user account
      enabled: true,
      apiId: 123456,
      apiHash: "..."
    }
  }
}

No conflicts - separate accounts, separate sessions.

Security Considerations

✅ Implemented

  • Session string encryption (via gateway encryption key)
  • DM pairing (default policy)
  • Allowlist support
  • Group policy enforcement
  • Security checks before queueing messages

⚠️ User Responsibilities

  • Keep session strings private (like passwords)
  • Use strong 2FA on Telegram account
  • Regularly review active sessions
  • Use allowFrom in sensitive contexts
  • Don't share API credentials publicly

📝 Documented

  • Security best practices section in docs
  • Session management guide
  • Credential handling instructions
  • Compromise recovery steps

Rate Limits

Telegram Limits (Documented)

  • ~20 messages/minute per chat
  • ~40-50 messages/minute globally
  • Flood wait errors trigger cooldown

GramJS Handling

  • Auto-retry on FLOOD_WAIT errors
  • Exponential backoff
  • Configurable floodSleepThreshold

Documentation

  • Rate limit table in docs
  • Best practices section
  • Comparison with Bot API limits

PR Checklist

  • Code follows openclaw patterns (studied existing telegram/whatsapp adapters)
  • TypeScript types complete and strict
  • JSDoc comments on public APIs
  • Unit tests with good coverage
  • Documentation comprehensive
  • No breaking changes
  • Git commit message follows convention
  • Files organized logically
  • Error handling robust
  • Logging via subsystem logger
  • Config validation in place
  • Integration tests (requires real credentials - maintainer task)
  • Performance testing (requires production scale - maintainer task)

Commit Message

feat(telegram-gramjs): Phase 1 - User account adapter with tests and docs

Implements Telegram user account support via GramJS/MTProto (#937).

[Full commit message in git log]

Next Steps (After Merge)

Phase 2 (Media Support)

  • Image/video upload and download
  • Voice messages
  • Stickers and GIFs
  • File attachments
  • Reactions

Phase 3 (Advanced Features)

  • Channel messages
  • Secret chats
  • Poll creation
  • Inline queries
  • Custom entity parsing (mentions, hashtags, URLs)

Future Improvements

  • Webhook support (like Bot API)
  • Better mention detection
  • Flood limit auto-throttling
  • Session file encryption options
  • Multi-device session sync

Maintainer Notes

Review Focus Areas

  1. Security: Session string handling, encryption, allowlists
  2. Architecture: Plugin structure, gateway integration, session routing
  3. Config Schema: Backward compatibility, validation
  4. Error Handling: User-facing messages, retry logic
  5. Documentation: Clarity, completeness, examples

Testing Recommendations

  1. Test auth flow with real Telegram account
  2. Test DM send/receive
  3. Test group message handling
  4. Test multi-account setup
  5. Test session persistence across restarts
  6. Test flood limit handling
  7. Test error recovery

Integration Points

  • Gateway daemon (message polling)
  • Config system (multi-account)
  • Session storage (encryption)
  • Logging (subsystem logger)
  • Registry (channel discovery)

Questions for Reviewers

  1. Session encryption: Should we add option for separate encryption passphrase (vs using gateway key)?
  2. Mention detection: Implement now or defer to Phase 2?
  3. Channel messages: Support in Phase 1 or keep for Phase 3?
  4. Integration tests: Add to CI or keep manual-only (requires Telegram credentials)?

Contact

Implementer: Spotter (subagent of Clawd)
Human: Jakub (@oogway_defi)
Issue: https://github.com/openclaw/openclaw/issues/937
Repo: https://github.com/openclaw/openclaw

Ready for PR submission! 🚀