Documentation
Complete guide to installing, configuring, and using OMOTG
Overview
OMOTG is a bidirectional bridge between Telegram and OpenCode AI agent. It allows you to interact with OpenCode directly from Telegram, with support for multiple sessions, forum topics, and more.
What is OMOTG?
A Go-based service that bridges Telegram and OpenCode, enabling you to chat with AI agents from your phone. Both private chat and group forum topics are supported, with full session management and secure authentication.
Installation
Via Homebrew (Recommended)
brew tap itokun99/omotg && brew install omotgFrom Source
git clone https://github.com/itokun99/omotg.git
cd omotg
go build -o omotg .Requirements: Linux/macOS, Go 1.19+ (for source), OpenCode running locally
Configuration
Environment Variables
| Variable | Required | Description |
|---|---|---|
| TELEGRAM_BOT_TOKEN | Yes | Bot token from @BotFather |
| TELEGRAM_WEBHOOK_URL | Yes | Public HTTPS URL (e.g., https://your.domain:8443/webhook) |
| TELEGRAM_SECRET_TOKEN | Yes | Secret string to verify webhook requests |
| OPENCODE_SERVER_PASSWORD | Yes | Password for OpenCode API |
| OPENCODE_SERVER_URL | No | OpenCode serve URL (default: http://127.0.0.1:4096) |
| OMOTG_WEBHOOK_PORT | No | Webhook TLS listen port (default: 8443) |
| OMOTG_MCP_PORT | No | MCP SSE server port (default: 9090) |
Setup Example
export TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN"
export TELEGRAM_WEBHOOK_URL="https://your.domain:8443/webhook"
export TELEGRAM_SECRET_TOKEN="your-secret-token"
export OPENCODE_SERVER_PASSWORD="your-opencode-password"
export OPENCODE_SERVER_URL="http://127.0.0.1:4096"
omotgTelegram Commands
| Command | Description |
|---|---|
| /start | Welcome message |
| /help | Show available commands |
| /status | Check server status via OpenCode |
| /deploy <env> | Deploy application to environment |
| /logs [N] | Show last N lines of server logs (default: 50) |
| /session | Show current session info |
| /session new [text] | Create a new session (optionally with first prompt) |
| /session list | List all sessions |
| /session switch <id> | Switch to a different session |
| /session delete <id> | Delete a session |
| /topic new <nama> | Create a new forum topic with bound session (group only) |
| /topic close | Close the current forum topic (group only) |
| /topic delete | Permanently delete the current forum topic (group only) |
Deployment
Systemd Setup
OMOTG ships with systemd user service files. To set up as a user service:
mkdir -p ~/.config/systemd/user
cp /opt/omotg/omotg.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable omotg
systemctl --user start omotg
systemctl --user status omotgTLS Certificates: OMOTG uses TLS for webhooks. Generate self-signed certificates:
openssl req -x509 -newkey rsa:4096 -keyout webhook.key -out webhook.crt -days 365 -nodesSecurity
Key Security Features
- Secret token verification on all webhook requests
- Optional chat ID whitelist to restrict access
- TLS encryption for all communications
- Self-signed certificate support
- No data persistence beyond sessions
Best Practices
- ✓ Use strong, random secret tokens
- ✓ Restrict webhook access to Telegram IP ranges
- ✓ Keep OpenCode on localhost (not exposed to internet)
- ✓ Regularly update OMOTG via Homebrew
- ✓ Monitor logs for unauthorized access attempts
Troubleshooting
Webhook Not Receiving Messages
Check that your webhook URL is publicly accessible and your TLS certificate is valid:
curl -v https://your.domain:8443/webhookOpenCode Connection Failed
Ensure OpenCode is running and accessible:
curl http://127.0.0.1:4096/statusView Logs
Check systemd logs for errors:
journalctl --user-unit=omotg -fFAQ
Can I use OMOTG without OpenCode?
No, OMOTG is specifically designed to bridge Telegram with OpenCode. You need OpenCode running and accessible.
Is OMOTG free to use?
Yes, OMOTG is open source under CC BY-NC 4.0 license. It's free for non-commercial use.
Can I run multiple OMOTG instances?
Yes, each instance needs its own Telegram bot token and webhook URL. They can all connect to the same OpenCode instance.
What about data privacy?
OMOTG does not store any conversation data. All messages are processed and relayed in real-time without persistence.
How do I update OMOTG?
If installed via Homebrew: brew upgrade omotg. Always restart the service after updating.
Need Help?
GitHub Issues
Report bugs and request features on GitHub
GitHub Discussions
Join the community discussion and ask questions