Skip to content

Commit 55a0627

Browse files
avfirsovavfirsov
committed
docs(readme): document TELEGRAM_API_ROOT / TELEGRAM_PROXY_SECRET
Per @grinev review on PR #92: * Add both env vars to the Environment Variables table, in the Telegram block right after TELEGRAM_PROXY_URL. * Add a new "Reverse Proxy (Optional)" subsection under Configuration with motivation, .env snippet, and a copy-pasteable nginx config. * Resync README.md to current main (gains /detach, /ls, /mcps, TTS provider columns, OPENCODE_AUTO_RESTART_ENABLED, etc.) so the diff is clean against main.
1 parent 46a8993 commit 55a0627

1 file changed

Lines changed: 67 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 67 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
66
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
77
[![Follow updates](https://img.shields.io/badge/-Follow%20updates-333333?logo=x)](https://x.com/grin_rus)
8+
[![Community](https://img.shields.io/badge/Community-Telegram-26A5E4?logo=telegram&logoColor=white)](https://t.me/+Fj_IyKRi6-41MGUy)
89

910
OpenCode Telegram Bot is a secure Telegram client for [OpenCode](https://opencode.ai) CLI that runs on your local machine.
1011

@@ -27,6 +28,7 @@ Languages: English (`en`), Deutsch (`de`), Español (`es`), Français (`fr`), Р
2728
- **Remote coding** — send prompts to OpenCode from anywhere, receive complete results with code sent as files
2829
- **Session management** — create new sessions or continue existing ones, just like in the TUI
2930
- **Track live session** — follow a live OpenCode CLI session; see [Track Existing Session](#track-existing-session)
31+
- **Background session notifications** — get short notifications when detached or non-current sessions in the current project/worktree reply, ask questions, or request permissions
3032
- **Live status** — pinned message with current project/worktree, model, context usage, and changed files list, updated in real time
3133
- **Model switching** — pick models from OpenCode favorites and recent history directly in the chat (favorites are shown first)
3234
- **Agent modes** — switch between Plan and Build modes on the fly
@@ -42,6 +44,7 @@ Languages: English (`en`), Deutsch (`de`), Español (`es`), Français (`fr`), Р
4244
- **Git worktree switching** — browse and switch between existing git worktrees for the current repository with `/worktree`
4345
- **Security** — strict user ID whitelist; no one else can access your bot, even if they find it
4446
- **Localization** — UI localization is supported for multiple languages (`BOT_LOCALE`)
47+
- **Interactive file browser** — use `/ls` to browse files and directories inside the current project, open subdirectories, go back, and download files by tapping them
4548

4649
Planned features currently in development are listed in [Current Task List](PRODUCT.md#current-task-list).
4750

@@ -129,14 +132,17 @@ opencode-telegram config
129132
| `/status` | Server health, current project, session, and model info |
130133
| `/new` | Create a new session |
131134
| `/abort` | Abort the current task |
135+
| `/detach` | Detach from the current session without stopping it |
132136
| `/sessions` | Browse and switch between recent sessions |
133137
| `/projects` | Switch between OpenCode projects |
134138
| `/worktree` | Switch between existing git worktrees |
135139
| `/open` | Add a project by browsing directories |
140+
| `/ls` | List directory contents, then tap to open or download |
136141
| `/tts` | Toggle audio replies |
137142
| `/rename` | Rename the current session |
138143
| `/commands` | Browse and run custom commands |
139144
| `/skills` | Browse and run OpenCode skills |
145+
| `/mcps` | Browse and toggle MCP servers |
140146
| `/task` | Create a scheduled task |
141147
| `/tasklist` | Browse and delete scheduled tasks |
142148
| `/opencode_start` | Start the local OpenCode server on the bot machine |
@@ -192,7 +198,11 @@ When installed via npm, the configuration wizard handles the initial setup. The
192198
| `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | Yes | — |
193199
| `TELEGRAM_ALLOWED_USER_ID` | Your numeric Telegram user ID | Yes | — |
194200
| `TELEGRAM_PROXY_URL` | Proxy URL for Telegram API (SOCKS5/HTTP) | No | — |
201+
| `TELEGRAM_API_ROOT` | Custom Telegram Bot API root URL (e.g. nginx reverse-proxying `api.telegram.org`); applied to API calls and file downloads | No | `https://api.telegram.org` |
202+
| `TELEGRAM_PROXY_SECRET` | Shared secret sent as `X-Proxy-Secret` header on every Bot API request and file download (used with `TELEGRAM_API_ROOT`) | No | — |
195203
| `OPENCODE_API_URL` | OpenCode server URL | No | `http://localhost:4096` |
204+
| `OPENCODE_AUTO_RESTART_ENABLED` | Automatically restart a local OpenCode server when health-checks fail | No | `false` |
205+
| `OPENCODE_MONITOR_INTERVAL_SEC` | Health monitor interval in seconds when OpenCode auto-restart is enabled | No | `300` |
196206
| `OPENCODE_SERVER_USERNAME` | Server auth username | No | `opencode` |
197207
| `OPENCODE_SERVER_PASSWORD` | Server auth password | No | — |
198208
| `OPENCODE_MODEL_PROVIDER` | Default model provider | Yes | `opencode` |
@@ -209,6 +219,7 @@ When installed via npm, the configuration wizard handles the initial setup. The
209219
| `HIDE_THINKING_MESSAGES` | Hide `💭 Thinking...` service messages | No | `false` |
210220
| `HIDE_TOOL_CALL_MESSAGES` | Hide tool-call service messages (`💻 bash ...`, `📖 read ...`, etc.) | No | `false` |
211221
| `HIDE_TOOL_FILE_MESSAGES` | Hide file edit documents sent as `.txt` attachments (`edit_*.txt`, `write_*.txt`) | No | `false` |
222+
| `TRACK_BACKGROUND_SESSIONS` | Track detached/non-current sessions in the current selected project/worktree and send short notifications | No | `true` |
212223
| `RESPONSE_STREAMING` | Stream assistant replies while they are generated across one or more Telegram messages | No | `true` |
213224
| `MESSAGE_FORMAT_MODE` | Assistant reply formatting mode: `markdown` (Telegram MarkdownV2) or `raw` | No | `markdown` |
214225
| `CODE_FILE_MAX_SIZE_KB` | Max file size (KB) to send as document | No | `100` |
@@ -217,17 +228,57 @@ When installed via npm, the configuration wizard handles the initial setup. The
217228
| `STT_MODEL` | STT model name passed to `/audio/transcriptions` | No | `whisper-large-v3-turbo` |
218229
| `STT_LANGUAGE` | Optional language hint (empty = provider auto-detect) | No | — |
219230
| `STT_NOTE_PROMPT` | Optional note prepended to the LLM prompt as `[Note: ...]` for voice transcriptions; empty / `false` / `0` disable it | No | — |
220-
| `TTS_API_URL` | TTS API base URL | No | — |
221-
| `TTS_API_KEY` | TTS API key | No | — |
222-
| `TTS_MODEL` | TTS model name passed to `/audio/speech` | No | `gpt-4o-mini-tts` |
223-
| `TTS_VOICE` | OpenAI-compatible TTS voice name | No | `alloy` |
231+
| `TTS_PROVIDER` | TTS provider: `openai` for OpenAI-compatible APIs or `google` for Google Cloud TTS | No | `openai` |
232+
| `TTS_API_URL` | OpenAI-compatible TTS API base URL | No | — |
233+
| `TTS_API_KEY` | OpenAI-compatible TTS API key | No | — |
234+
| `TTS_MODEL` | OpenAI-compatible TTS model name passed to `/audio/speech` | No | `gpt-4o-mini-tts` |
235+
| `TTS_VOICE` | TTS voice name. Defaults to `alloy` for OpenAI-compatible APIs and `en-US-Studio-O` for Google Cloud TTS | No | provider-specific |
236+
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to a Google Cloud service account JSON key file for `TTS_PROVIDER=google` | No | — |
224237
| `LOG_LEVEL` | Log level (`debug`, `info`, `warn`, `error`) | No | `info` |
225238
| `LOG_RETENTION` | Number of log files to keep: launch files in `sources`, daily files in `installed` | No | `10` |
226239

227240
> **Keep your `.env` file private.** It contains your bot token. Never commit it to version control.
228241
229242
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`.
230243

244+
### Reverse Proxy (Optional)
245+
246+
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`.
247+
248+
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.
249+
250+
`.env`:
251+
252+
```env
253+
TELEGRAM_API_ROOT=https://tg-proxy.yourdomain.com
254+
TELEGRAM_PROXY_SECRET=some-long-random-string
255+
```
256+
257+
Example nginx config:
258+
259+
```nginx
260+
server {
261+
listen 443 ssl http2;
262+
server_name tg-proxy.yourdomain.com;
263+
264+
ssl_certificate /etc/letsencrypt/live/tg-proxy.yourdomain.com/fullchain.pem;
265+
ssl_certificate_key /etc/letsencrypt/live/tg-proxy.yourdomain.com/privkey.pem;
266+
267+
access_log off; # the bot token appears in URL paths
268+
client_max_body_size 50m;
269+
270+
if ($http_x_proxy_secret != "some-long-random-string") { return 403; }
271+
272+
location / {
273+
proxy_pass https://api.telegram.org;
274+
proxy_ssl_server_name on;
275+
proxy_set_header Host api.telegram.org;
276+
}
277+
}
278+
```
279+
280+
`TELEGRAM_API_ROOT` and `TELEGRAM_PROXY_URL` are independent — the former picks the URL the bot connects to (a reverse proxy on your side), the latter tunnels TCP through a forward proxy. They can be combined, though that is unusual.
281+
231282
### Voice and Audio Transcription (Optional)
232283

233284
If `STT_API_URL` and `STT_API_KEY` are set, the bot will:
@@ -241,15 +292,24 @@ If `STT_NOTE_PROMPT` is set to a non-empty value other than `false` or `0`, the
241292

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

244-
TTS configuration example:
295+
OpenAI-compatible TTS configuration example:
245296

246297
```env
298+
TTS_PROVIDER=openai
247299
TTS_API_URL=https://api.openai.com/v1
248300
TTS_API_KEY=your-tts-api-key
249301
TTS_MODEL=gpt-4o-mini-tts
250302
TTS_VOICE=alloy
251303
```
252304

305+
Google Cloud TTS configuration example:
306+
307+
```env
308+
TTS_PROVIDER=google
309+
TTS_VOICE=en-US-Studio-O
310+
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
311+
```
312+
253313
Supported provider examples (Whisper-compatible):
254314

255315
- **OpenAI**
@@ -325,6 +385,7 @@ npm run dev
325385

326386
- Ensure an OpenCode server is running at the configured `OPENCODE_API_URL` (default: `http://localhost:4096`)
327387
- For a local setup, you can start it with `opencode serve` or use `/opencode_start` in Telegram
388+
- 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
328389
- 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
329390

330391
**No models in model picker**
@@ -343,7 +404,7 @@ Please follow commit and release note conventions in [CONTRIBUTING.md](CONTRIBUT
343404

344405
## Community
345406

346-
Have questions, want to share your experience using the bot, or have an idea for a feature? Join the conversation in [GitHub Discussions](https://github.com/grinev/opencode-telegram-bot/discussions).
407+
Have questions, want to share your experience using the bot, or have an idea for a feature? Join the [Telegram group](https://t.me/+Fj_IyKRi6-41MGUy) for announcements and discussions, or start a thread in [GitHub Discussions](https://github.com/grinev/opencode-telegram-bot/discussions).
347408

348409
## License
349410

0 commit comments

Comments
 (0)