Telegram Frontend for task-api CLI Execution
Forward Telegram messages to your local task-api, execute on the real CLI, send results back.
A thin Telegram bridge that drives Claude Code, Codex CLI, and Gemini CLI through task-api / openclaw-tunnel — keeping full CLI execution on the machine that owns the files and credentials.
English | 简体中文
A Telegram frontend for task-api. Not a standalone backend.
It depends on a working task-api / openclaw-tunnel setup. Without that, this repository is close to useless. The bridge accepts Telegram messages, forwards tasks to task-api endpoints, polls for results, and sends responses back.
Core rule: One bot = one CLI = one task-api route.
| telegram-ai-bridge | telegram-cli-bridge (this) | |
|---|---|---|
| Execution model | SDK-first (in-process adapter) | CLI-first (via task-api worker) |
| Backend dependency | None — self-contained | Requires task-api / openclaw-tunnel |
| Architecture | Unified bridge process | Three separate bot scripts |
| Best for | Direct SDK integration | Full local CLI execution behind a worker |
Choose this repo when you already have task-api running and want Telegram to drive full local CLI execution instead of SDK wrappers.
| Feature | Description |
|---|---|
| Three CLI bots | bridge.js (Claude), codex-bridge.js (Codex), gemini-bridge.js (Gemini) |
| Media forwarding | Files, photos, and voice input forwarded to task-api |
| Result delivery | Polling + callback style |
| Session continuity | Per-chat, owner-only, in-memory |
| Thin bridge | All execution delegated to openclaw-tunnel |
git clone https://github.com/AliceLJY/telegram-cli-bridge.git
cd telegram-cli-bridge
bun installPrepare environment files:
| File | Bot |
|---|---|
.env |
bridge.js (Claude) |
.env.codex |
codex-bridge.js (Codex) |
.env.gemini |
gemini-bridge.js (Gemini) |
Required variables:
TELEGRAM_BOT_TOKEN=...
OWNER_TELEGRAM_ID=...
TASK_API_URL=http://localhost:3456
TASK_API_TOKEN=...
# Optional: HTTPS_PROXY=...bun bridge.js # Claude
bun run start:codex # Codex
bun run start:gemini # GeminiRun them as separate processes, not one combined bridge.
Backend Differences
- Claude (
bridge.js) —sessionId-style continuation via/claudeendpoint - Codex (
codex-bridge.js) —sessionId-style, with local fallback history atcodex-sessions.json - Gemini (
gemini-bridge.js) — usesresumeLatestinstead of UUID session restore (Gemini CLI limitation)
These are similar scripts, not a unified adapter abstraction.
Prerequisites & Environment
Required:
- Bun
- A working
task-api/openclaw-tunnelbackend - Local installs of Claude Code, Codex CLI, and/or Gemini CLI on the backend machine
- One Telegram bot token per CLI bridge
- Owner Telegram account
Local path assumptions:
- Downloaded files:
~/Projects/telegram-cli-bridge/files - Codex history fallback:
~/Projects/telegram-cli-bridge/codex-sessions.json TASK_API_URLdefaults tohttp://localhost:3456
Compatibility:
- Tested only on the author's macOS + task-api workflow
- Some local paths are hardcoded and may need adjustment
- Not the recommended primary path for Claude/Codex (use
telegram-ai-bridgefor SDK-first)
Known Limits
- This is a task-api frontend, not a standalone backend
- Session maps are in-memory — lost on bridge restart
- Gemini session restore is not equivalent to Claude/Codex
- Three scripts are manually split, not a unified adapter
- Reliability depends on worker-side task execution
Built by 小试AI (@AliceLJY) for the WeChat public account 我的AI小木屋.
MIT