开源AI工作流

Prerequisites

• Node.js 20+ — download
• OpenCode — install from opencode.ai or GitHub
• Telegram Bot — you'll create one during setup (takes 1 minute)

3. Install & Run

The fastest way — run directly with npx:

npx @grinev/opencode-telegram-bot@latest

Note: This README tracks the main branch, which may include unreleased changes. The latest npm release may not include every feature described here yet. See recent commits on main.

Quick start is for npm usage. You do not need to clone this repository. If you run this command from the source directory (repository root), it may fail with opencode-telegram: not found. To run from sources, use the Development section.

On first launch, an interactive wizard will guide you through the configuration — it asks for interface language first, then your bot token, user ID, OpenCode API URL, and optional OpenCode server credentials (username/password). After that, you're ready to go. Open your bot in Telegram and start sending tasks.

Alternative: Global Install

npm install -g @grinev/opencode-telegram-bot
opencode-telegram start

start runs in the foreground by default. This is the recommended mode for systemd, Docker, local debugging, and other external process managers.

To run the bot in the built-in background mode instead:

opencode-telegram start --daemon
opencode-telegram status
opencode-telegram stop

Built-in daemon mode is intended for standalone npm installs without an external supervisor. For systemd, pm2, or Docker, keep using opencode-telegram start without --daemon.

For Linux systemd setup, see docs/LINUX_SYSTEMD_SETUP.md.

To reconfigure at any time:

opencode-telegram config

Quick Start

Configuration

Environment Variables

When installed via npm, the configuration wizard handles the initial setup. The .env file is stored in your platform's app data directory:

• macOS: ~/Library/Application Support/opencode-telegram-bot/.env
• Windows: %APPDATA%\opencode-telegram-bot\.env
• Linux: ~/.config/opencode-telegram-bot/.env

Keep your .env file private. It contains your bot token. Never commit it to version control.

Logs are written to ./logs when running from sources and to the runtime config directory logs/ folder in installed mode. Log rotation depends on runtime mode: sources creates one file per bot launch, while installed appends to one file per day. Old log files are removed according to LOG_RETENTION.

Reverse Proxy (Optional)

For environments that block api.telegram.org but allow your own HTTPS endpoint (corporate networks, restricted regions), you can route Bot API traffic through a reverse proxy you control. This is an alternative to the SOCKS/HTTP forward proxy configured with TELEGRAM_PROXY_URL.

Set TELEGRAM_API_ROOT to your reverse-proxy URL — both Bot API calls and file downloads (including voice/audio files) will use it. Optionally set TELEGRAM_PROXY_SECRET so the bot sends an X-Proxy-Secret header your proxy can use to authorize callers.

.env:

TELEGRAM_API_ROOT=https://tg-proxy.yourdomain.com
TELEGRAM_PROXY_SECRET=some-long-random-string

Example nginx config:

server {
    listen 443 ssl http2;
    server_name tg-proxy.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/tg-proxy.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tg-proxy.yourdomain.com/privkey.pem;

    access_log off;  # the bot token appears in URL paths
    client_max_body_size 50m;

    if ($http_x_proxy_secret != "some-long-random-string") { return 403; }

    location / {
        proxy_pass https://api.telegram.org;
        proxy_ssl_server_name on;
        proxy_set_header Host api.telegram.org;
    }
}

TELEGRAM_API_ROOT and TELEGRAM_PROXY_URL are alternative connectivity modes — the former picks the URL the bot connects to (a reverse proxy on your side), while the latter tunnels TCP through a forward proxy. Configure only one of them; the bot rejects using both at startup.

Force IPv4 for Telegram (Optional)

If the bot fails during startup with errors such as Network request for 'setMyCommands' failed or Network request for 'getWebhookInfo' failed, and the same machine has broken outbound IPv6 connectivity, force direct Telegram requests to use IPv4:

TELEGRAM_FORCE_IPV4=true

This affects direct Bot API calls and Telegram file downloads. It is not a replacement for TELEGRAM_PROXY_URL or TELEGRAM_API_ROOT when Telegram is blocked by the network.

Voice and Audio Transcription (Optional)

If STT_API_URL and STT_API_KEY are set, the bot will:

1. Accept voice and audio Telegram messages
2. Transcribe them via POST {STT_API_URL}/audio/transcriptions
3. Show recognized text in chat
4. Send the recognized text to OpenCode as a normal prompt

If STT_NOTE_PROMPT is set to a non-empty value other than false or 0, the bot prepends [Note: ...] to the transcription before sending it to the LLM. The recognized text shown in Telegram stays unchanged.

If TTS credentials are configured, you can toggle spoken replies globally with /tts. The preference is stored in settings.json and persists across restarts.

OpenAI-compatible TTS configuration example:

TTS_PROVIDER=openai
TTS_API_URL=https://api.openai.com/v1
TTS_API_KEY=your-tts-api-key
TTS_MODEL=gpt-4o-mini-tts
TTS_VOICE=alloy

Google Cloud TTS configuration example:

TTS_PROVIDER=google
TTS_VOICE=en-US-Studio-O
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Supported provider examples (Whisper-compatible):

• OpenAI
• STT_API_URL=https://api.openai.com/v1
• STT_MODEL=whisper-1
• Groq
• STT_API_URL=https://api.groq.com/openai/v1
• STT_MODEL=whisper-large-v3-turbo
• Together
• STT_API_URL=https://api.together.xyz/v1
• STT_MODEL=openai/whisper-large-v3

If STT variables are not set, voice/audio transcription is disabled and the bot will ask you to configure STT.

Model Configuration

The model picker uses OpenCode local model state (favorite + recent):

• Favorites are shown first, then recent
• Models already in favorites are not duplicated in recent
• Current model is marked with ✅
• Default model from OPENCODE_MODEL_PROVIDER + OPENCODE_MODEL_ID is always included in favorites

To add a model to favorites, open OpenCode TUI (opencode), go to model selection, and press Cmd+F/Ctrl+F on the model.

Edit .env with your bot token, user ID, and model settings

Build and run:

Troubleshooting

Bot doesn't respond to messages

• Make sure TELEGRAM_ALLOWED_USER_ID matches your actual Telegram user ID (check with @userinfobot)
• Verify the bot token is correct

"OpenCode server is not available"

• Ensure an OpenCode server is running at the configured OPENCODE_API_URL (default: http://localhost:4096)
• For a local setup, you can start it with opencode serve or use /opencode_start in Telegram
• For VPS/systemd setups with scheduled tasks, enable OPENCODE_AUTO_RESTART_ENABLED=true to let the bot restart a local OpenCode server when health-checks fail
• If OPENCODE_API_URL points to a remote server, verify that the address is reachable from the bot machine and that the remote server is healthy

No models in model picker

• Add models to your OpenCode favorites: open OpenCode TUI, go to model selection, press Ctrl+F on desired models
• Verify OPENCODE_MODEL_PROVIDER and OPENCODE_MODEL_ID point to an available model in your setup

Linux: permission denied errors

• Make sure the CLI binary has execute permission: chmod +x $(which opencode-telegram)
• Check that the config directory is writable: ~/.config/opencode-telegram-bot/