Zero6992/chatGPT-discord-bot: a self-hosted multi-provider bot for Discord

What the bot does that a plain API wrapper does not

A single Discord server usually contains several conversations that should not bleed into each other. This project treats history as scoped: each user gets a separate record in each server, channel and thread, with private and public conversations kept apart. That scoping is the actual product. Anyone can call an LLM API from a script; keeping per-user, per-channel state alive across restarts, and letting a user switch models mid-thread without losing the thread, is the part that takes work.

The audience is narrow and specific. It is for people who administer a Discord server and are willing to run a long-lived process: a Python service, or the Docker image, with credentials they own. It is not for someone who wants to invite a bot and start chatting. The README's quick start begins with creating an application in the Discord Developer Portal and obtaining its token, which tells you the intended user is the server owner, not a guest.

The feature set has grown well past ChatGPT. Version 4.0.0 supports OpenAI, Anthropic Claude, Google Gemini, xAI Grok, DeepSeek, any OpenAI-compatible local server, and isolated CLI backends for Codex, Claude Code and Grok Build. Model aliases live in TOML, and the README states that new aliases do not require Python changes. That is the design decision worth noting: provider breadth is configuration, not code.

How routing, persistence and failure handling fit together

The architecture separates credentials from behaviour. Secrets go in .env. Model aliases, access rules, context size, retention and concurrency go in config.toml. A backend is selected by alias, and each alias declares its own capabilities; chat, image search and media generation are separate aliases rather than flags on one model entry. The stated consequence is that unsupported settings fail explicitly instead of being ignored.

That strictness extends to failure. The README says provider failures never silently select another model or billing mode. If your OpenAI key expires mid-conversation, the request fails rather than quietly rerouting to your local Ollama instance. For an operator paying per token, that is the right default. It also means a misconfigured alias produces a visible error rather than a degraded answer, which is easier to debug and harder to ignore.

Persistence uses SQLite through aiosqlite, one of only four runtime dependencies listed in pyproject.toml. Conversations survive restarts, and users can reset or delete their history from Discord. Docker deployments mount ./data into the container, which is where that database lives, so the volume is the thing to back up. The bot is a single process: configuration changes require restarting it, per the README, and there is no hot reload.

Installing chatGPT-discord-bot and sending a first message

You need Python 3.12 to 3.14, a Discord bot token, and either an API key or a running local model server. The README advises Windows users to use WSL; Linux, WSL and macOS support the API and local backends. CLI backends have additional requirements in docs/cli.md.

Clone the repository, create a virtual environment, install the pinned requirements, and copy both example configuration files:

git clone https://github.com/Zero6992/chatGPT-discord-bot.git
cd chatGPT-discord-bot
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env
cp config.example.toml config.toml

After those commands you have a .env and a config.toml to edit. Put your Discord token and an OpenAI key in .env:

DISCORD_BOT_TOKEN=your_discord_bot_token
OPENAI_API_KEY=your_openai_api_key

Then edit the existing [bot] section of config.toml. The README's example sets the default alias to openai and leaves the allow-list empty, which is the documented default in every mode:

[bot]
default_model = "openai"
allowed_user_ids = [] # Everyone can chat; this is the default in every mode.

Start the bot with python main.py. The README says it connects to Discord and synchronizes its slash commands, so the commands may take a moment to appear. The documented first session is /chat with a message, /models to list configured models and their capabilities, /provider to switch, /chat again to confirm the conversation continued, and /reset to clear it. Replies start private; /public makes future slash replies visible in the channel and /private returns you to your own conversation.

If you prefer containers, the repository includes a Dockerfile and a docker-compose.yml that builds the image, reads .env, mounts config.toml read-only and ./data read-write, runs the container read-only with all capabilities dropped, and restarts unless stopped. The compose file sets BOT_CONFIG to /app/config.toml inside the container.

Where this bot is the wrong choice

Text only is the hard boundary. The README states plainly that text chat accepts text only, and that vision, audio, streaming and general agent tools are not exposed. If your server expects a bot that listens in a voice channel, transcribes speech, or streams tokens into a message as they arrive, this project does not do those things. The related searches around voice and VC have no answer in this repository.

Backend maturity is uneven, and the README says so. Adapters have offline contract coverage, with live checks for OpenAI, Anthropic and xAI chat, native CLI account text, and xAI video. Other paths have outstanding live verification or provider errors. In practice that means a path like Gemini video generation may be documented and still fail on the provider side. The README itself tells you to consult the capability reference and the CLI and media limitations before enabling a backend, which is an admission rather than a reassurance.

There is also an operational cost the README does not hide. Configuration changes require a restart. Long replies arrive as a text attachment to preserve formatting, which is a workaround for Discord's message limits and will look odd in a busy channel. CLI backends run through an isolated runtime with their own login flow, and the README points to docs/cli.md for requirements, so that mode is not a drop-in.

Finally, the licence is GPL-2.0-only. If you intend to modify the bot and distribute it, or embed it in a product, that copyleft obligation is part of the decision. This is a description of the licence field, not legal advice.

How it differs from writing your own discord.py handler

The obvious alternative is a few hundred lines of your own: discord.py, an HTTP client, and a dictionary mapping channel IDs to message lists. That approach is genuinely simpler for one provider and one server. The difference shows up in what you would have to rebuild: per-user history scoped by server, channel and thread; separate private and public conversations; persistence across restarts; an allow-list; per-alias capability declarations so that a model without image support rejects an image request instead of failing obscurely; and the rule that provider errors never silently fall back to another billing mode.

That last point is where a hand-rolled bot usually diverges. A fallback chain is easy to write and easy to regret, because a silent switch from a paid API to a local model changes answer quality without telling anyone. This project's stated behaviour is the opposite: fail loudly. If you disagree with that trade-off, you are better served by your own code, since overriding it means working against the adapter contract.

The other structural difference is the CLI backend mode. Rather than calling an HTTP API, the bot can drive Codex, Claude Code or Grok Build through an isolated runtime with explicit session resumption, using either an API key or a native account login. That is a meaningfully different integration path from the API adapters, and it is the reason the runtime and cli_accounts entry points exist in the project layout.

Maintenance, upgrades and what the repository tells you

The last push to main was on 2026-09-12, and version 4.0.0 was released on 2026-09-08. The repository is not archived. The release cadence visible in the tag list is slow and uneven: 2.1.2 in May 2024, 3.0.0 in July 2025, 4.0.0 in September 2026. That pattern suggests a project that ships when provider APIs or internal structure force it, not on a schedule. Plan upgrades as events rather than a routine.

Upgrade cost is concentrated in configuration. The README tells existing installations to follow docs/migration.md before replacing configuration or dependencies, which implies that a 3.x config.toml is not guaranteed to load unchanged in 4.0.0. The pinned requirements.txt is generated by uv from pyproject.toml, so dependency versions move as a set rather than individually. The runtime dependency list is short: discord.py, python-dotenv, httpx and aiosqlite. There is no ORM, no web framework and no broker, which keeps the surface small.

Development tooling is present in the optional dev extra: pytest, ruff, mypy, build and pip-audit, with mypy configured to disallow untyped definitions across src, utils and main.py. Tests default to excluding a live marker, and the marker description notes that live provider tests may incur charges. That is the honest version of a test suite for a project whose behaviour depends on paid third-party endpoints.

Access control and the settings that actually matter

The default is open. The README states that all backend modes allow everyone to chat by default, and that you should leave bot.allowed_user_ids empty or omit it, setting Discord user IDs there only when you want to limit access. For a small private server that is convenient. For a public server where members can invoke paid models, it is a billing exposure you have to close deliberately, and the README does not treat that as a warning.

Slash commands work without the Message Content Intent. The README says to enable that intent only for automatic channel replies, which is a useful split: a minimal deployment needs fewer privileged permissions than a bot that reacts to ordinary messages. The required Discord permissions are listed as View Channels, Send Messages, Embed Links and Attach Files, plus Send Messages in Threads if you use threads.

The remaining controls are context size, retention and concurrency, all configured in TOML alongside the aliases. The README does not specify their default values, so read config.example.toml rather than assuming. Remote endpoints require HTTPS, and endpoints are controlled by the administrator, which means the bot will not accept a plaintext remote URL from a user. CLI owner_id is separate from the chat allow-list and governs account login, status, logout and cancellation.

Editorial conclusion

Adopt this if you run your own Discord server, want one bot that can point at several providers and local models, and are comfortable editing .env and config.toml and restarting the process after every change. Skip it if you need voice, streaming, vision or audio input, since the README states text chat accepts text only, or if you want a hosted dashboard rather than a process you maintain. Before committing, verify three things: that your Python version is inside 3.12 to 3.14, that the backend you intend to use has passed live verification rather than only offline contract coverage, and that you have read docs/migration.md if you are upgrading from version 3.0.0 to 4.0.0.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. Zero6992/chatGPT-discord-bot on GitHub