How kyleparisi/ganclaw works
ganclaw is a self-hosted gateway from Telegram and local automation clients to coding-agent CLIs. Its main workflow accepts a chat or API request, routes an agent turn, runs it through the configured provider fallback chain, and returns or delivers the reply; chat sessions persist in SQLite. Separate branches cover Telegram media and voice transcription, MCP tools, health alerts, and OpenClaw compatibility. Edges cite README-level architecture or shown source references; some subsystem internals are unsampled, so their links are documented rather than inferred from names.
Main entry points: router.go Conversation router · server.go Local API · bot.go Telegram bot · client.go CLI commands
Components 25
Entry points
- Telegram bot
internal/telegram/bot.go - CLI commands
cmd/ganclaw/client.go - OpenClaw compatibility
cmd/ganclaw/compat.go
Gateway runtime
- Local API
internal/api/server.go - Gateway dispatch
internal/gateway/gateway.go - Conversation router
internal/router/router.go - Configuration
internal/config/config.go
Agent execution
- Agent workspace
internal/agent/agent.go - Provider fallback
internal/provider/chain.go - Codex provider
internal/provider/codex/codex.go - Claude provider
internal/provider/claude/claude.go - Agent MCP tools
internal/agenttools/agenttools.go
Chat and media
- Media transfer
internal/telegram/files.go - Attachment storage
internal/attachments/attachments.go - Voice transcription
internal/transcribe/transcribe.go
State and operations
- SQLite state
internal/store/store.go - Health monitor
internal/monitor/monitor.go - Health checks
cmd/ganclaw/check.go - CLI updater
internal/updater/updater.go
Other components
- Telegram user
- Schedulers and scripts
- External MCP servers
- Telegram service
- ffmpeg and whisper.cpp
- Agent CLI processes
Connections 28
- Telegram user → Telegram bot: sends messages
- Telegram bot → Conversation router: submits turns
- Schedulers and scripts → CLI commands: invokes commands
- CLI commands → Local API: calls over socket
- OpenClaw compatibility → Local API: uses local API
cmd/ganclaw/compat.go - Local API → Gateway dispatch: dispatches requests
internal/gateway/gateway.go - Gateway dispatch → Conversation router: submits turns
internal/gateway/gateway.go - Conversation router → Agent workspace: loads workspace
internal/router/router.go - Conversation router → Provider fallback: runs turn
- Provider fallback → Codex provider: tries provider
internal/provider/chain.go - Provider fallback → Claude provider: falls back
internal/provider/chain.go - Codex provider → Agent CLI processes: drives app-server
- Claude provider → Agent CLI processes: runs per turn
- Agent CLI processes → External MCP servers: accesses configured tools
- Conversation router → SQLite state: loads and saves sessions
internal/router/router.go - Local API → SQLite state: claims idempotency keys
internal/api/server.go - Telegram bot → Telegram service: polls and replies
- Telegram bot → Media transfer: handles attachments
- Media transfer → Attachment storage: stores files
internal/telegram/files.go - Conversation router → Voice transcription: transcribes voice notes
- Voice transcription → ffmpeg and whisper.cpp: runs local tools
internal/transcribe/transcribe.go - Conversation router → Agent MCP tools: offers agent tools
- Health checks → Local API: checks gateway
cmd/ganclaw/check.go - Health checks → Health monitor: evaluates alerts
cmd/ganclaw/check.go - Health monitor → Telegram service: sends alerts
- Configuration → Gateway dispatch: configures runtime
- CLI commands → CLI updater: requests CLI updates
- CLI updater → Agent CLI processes: updates binaries