ChatGPT-Telegram-Workers: a Telegram ChatGPT bot that runs on Cloudflare Workers

What ChatGPT-Telegram-Workers solves, and for whom

Running a Telegram bot normally means renting a small VPS, keeping Node alive, and handling restarts. ChatGPT-Telegram-Workers removes that machine from the picture. The README describes it as "the simplest and fastest way to deploy your own ChatGPT Telegram bot", built around Cloudflare Workers, with the older pitch being a single file you copy and paste with no dependencies, no local development environment and no domain name.

The audience is narrow and clear. You already have a Telegram bot token from BotFather and an API key for at least one supported provider. You want a personal or small-group assistant rather than a product with an operations team. The repository's feature list names OpenAI, Cloudflare AI, Cohere, Anthropic, Mistral, DeepSeek and Groq as adapted providers, so the project assumes you are calling a hosted model rather than running weights yourself.

It is not a framework for building a bespoke bot from scratch. The plugin system documented in doc/en/PLUGINS.md is the extension point, and custom commands are described as a way to switch models or robot presets quickly. If your bot logic is mostly custom, you will spend your time inside that plugin boundary rather than writing a Telegram client.

How the Worker, the KV store and the admin panel fit together

The architecture follows the Workers execution model. Telegram sends an update to the Worker's HTTP endpoint, the Worker resolves configuration, calls the selected AI provider, and streams the answer back to Telegram. The README lists streaming output as a feature, which matters because Workers have execution time limits and a streamed reply starts reaching the user before the model has finished.

Configuration is stored in KV rather than in code. The README calls this "simple KV-based configuration", and the one-click deploy flow is described as cloning the repo, creating the KV namespace, asking for your bot token and deploying. That ordering is the important part: the KV namespace is a deployment prerequisite, not an optional extra. Without it there is nowhere for the runtime configuration to live.

A web admin panel, delivered as a Telegram Mini App, manages AI providers and settings. This is the part that changed the project's shape. Instead of editing a config file and redeploying, you open the panel inside Telegram and change providers or settings there. The trade-off is that the panel becomes part of your trust boundary: whoever can open it can change where your prompts go.

The repository is a pnpm workspace. The package.json defines per-package build scripts such as build:server, build:core, build:plugins, build:ai, build:telegram and build:web, and the top-level build runs pnpm -r run build across them. So the single-file story from the early README is now the output of a monorepo build, not the source you edit.

Installing ChatGPT-Telegram-Workers: one-click deploy and a Docker fallback

The README's primary path is the Cloudflare deploy button. The documentation states that Cloudflare clones the repo, creates the KV namespace, asks for your bot token and deploys. You do not run a build command on your own machine for this route; the platform does it.

If you would rather run it yourself, the repository ships a Dockerfile and a docker-compose.yaml. The compose file mounts two files read-only: config.json at /app/config.json and wrangler.jsonc at /app/wrangler.jsonc. Both paths must exist on your host before you start the container.

services:
    chatgpt-telegram-workers:
        build: .
        ports:
            - '8787:8787'
        volumes:
            - ./config.json:/app/config.json:ro
            - ./wrangler.jsonc:/app/wrangler.jsonc:ro

The image listens on port 8787, which the Dockerfile exposes and the compose file maps. The final stage runs node /app/dist/node.js. There is no documented startup command other than that, so if the container exits immediately, the first thing to check is whether both mounted files are present and readable.

Building the image is heavier than the one-click route. The Dockerfile installs pnpm 12.4.1 explicitly because, as a comment in the file puts it, Node >=25 no longer bundles corepack. It then runs pnpm install --frozen-lockfile and pnpm run build:server. The production stage installs the server dependencies with a temporary python3, make and g++ toolchain, purges it afterwards, and copies dist/node.js and dist/vercel.js into the image. Expect a multi-stage build, not a quick pull.

For local development the repository includes .dev.vars.example, which is the conventional place for the secrets and variables Wrangler reads. The README does not spell out the contents, so treat that file as the source of truth rather than guessing key names.

Where ChatGPT-Telegram-Workers is the wrong tool

The serverless model is the limitation, not an implementation detail. A Worker is not a long-running process. Anything that needs to hold state in memory between updates, poll an external service on a schedule, or keep a socket open for minutes does not fit the execution model the README describes. If your bot's job is to watch a queue, this is the wrong starting point.

Provider coverage is broad on paper and shallow in practice. The README lists OpenAI, Cloudflare AI, Cohere, Anthropic, Mistral, DeepSeek and Groq, but the repository does not document per-provider feature parity. Text-to-image generation is listed as a feature without a stated provider matrix, so assume that capability depends on the provider you configure rather than being universal. Verify against doc/en/CONFIG.md before you promise image generation to anyone.

The Docker route has its own sharp edges. The compose file sets network_mode: 'host' with a comment about accessing a proxy port on the host. That is a deliberate choice for proxy users, and it also means the container shares the host network namespace, which is not what everyone wants. The mount paths are also fixed at /app/config.json and /app/wrangler.jsonc; the compose comment tells you to change the left-hand side, not the right.

Finally, the admin panel is a convenience with a cost. A Mini App that edits provider settings means configuration changes do not go through code review or version control. For a personal bot that is fine. For a shared deployment it is a governance question the README does not address.

How it compares with a self-hosted bot framework

The obvious alternative is a self-hosted Telegram bot framework in Node or Python, where you write the handler, run a process, and own the machine. The difference is not the language. It is where state and configuration live.

In a self-hosted framework, configuration is a file in your repository and secrets are environment variables on the host. In ChatGPT-Telegram-Workers, configuration lives in a KV namespace and is edited through a Mini App. That makes changes instant and removes redeploys, and it also means your configuration is not in git unless you keep it there separately.

A second difference is the deployment unit. A self-hosted bot is one long-lived process; you can attach a database, a scheduler or a background worker to it. ChatGPT-Telegram-Workers is a request handler. The repository does ship a Dockerfile that runs a Node server, so you are not forced onto Workers, but the code is shaped around short-lived requests and streaming responses either way.

The third difference is provider abstraction. A self-hosted bot typically talks to one SDK. This project adapts to several providers behind a shared interface, which is genuinely useful if you want to switch models without rewriting handlers. That abstraction is also the reason a provider-specific feature may not be reachable through the common path.

Maintenance, releases and what the MIT licence means here

The last push to the default branch was on 2026-09-14, so the repository is not dormant. The most recent release listed is 1.10.7 from 2025-02-27, with 1.10.6 on 2025-02-05 and 1.10.5 on 2025-01-17. There is a visible gap between the newest tagged release and the latest commit activity, and the README does not explain the release cadence. If you depend on tags rather than the default branch, plan around that gap.

Upgrade cost is shaped by the workspace layout. The root package.json defines build:core, build:ai, build:telegram, build:web, build:plugins and others, and the top-level build fans out across the workspace with pnpm -r run build. A change in a core package can ripple into the server and web builds, which is normal for a monorepo and also means a partial upgrade is not really supported.

The project documents a migration path from v1 to v2 in doc/en/MIGRATION.md. That file's existence is the clearest signal that upgrading across major versions is not automatic. Read it before moving an existing deployment.

The licence is MIT, stated in both the README and package.json. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice are kept. That is a summary of the licence text, not legal advice. Your own obligations come from the AI providers you configure and from Telegram's terms, neither of which this repository governs.

Editorial conclusion

Adopt it if you want a Telegram ChatGPT bot with no server to maintain and you are comfortable editing a KV-stored config or using the Mini App admin panel. Do not adopt it if you need a long-running process, a local model, or a deployment target that cannot hold a KV namespace. Before you commit, verify which AI providers your config actually reaches, check that your chosen runtime can mount the config files the Docker image expects, and read doc/en/MIGRATION.md if you are coming from v1.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tbxark/ChatGPT-Telegram-Workers on GitHub