A simple Discord bot with multi-provider AI commands (OpenAI / Claude / Gemini) and server administration tools.
This bot serves as a starting point (template) for building other bots.
- Features
- Prerequisites
- Installation
- Configuration
- Commands
- Development and Testing
- Credits
- License
- Support
- Multi-provider AI commands (OpenAI / Anthropic Claude / Google Gemini) with optional web search
- Guild Wars 2 API integration (accounts, WvW, sessions, wiki)
- Server administration and moderation tools
- Custom commands, profanity filtering, and text-to-speech
- Persistent embed pagination that survives bot restarts
- PostgreSQL database with Alembic migrations
- Docker deployment with automatic database migrations
- Docker and Docker Compose
- A Discord Bot Token
- (Optional) An OpenAI API Key for
gpt/gptwebcommands - (Optional) An Anthropic API Key for
claude/claudewebcommands - (Optional) A Google AI Studio Key for
gemini/geminiwebcommands (free tier available) - (Optional) A Guild Wars 2 API Key for GW2 commands
git clone https://github.com/ddc/DiscordBot.git
cd DiscordBotcp .env.example .envEdit the .env file and set the required values:
# Required
BOT_TOKEN=your_discord_bot_token
# Optional — any of the AI providers (you can configure one, two, or all three)
BOT_OPENAI_API_KEY=your_openai_api_key
BOT_ANTHROPIC_API_KEY=your_anthropic_api_key
BOT_GEMINI_API_KEY=your_google_ai_studio_key
# Database
POSTGRESQL_HOST=postgres
POSTGRESQL_PORT=5432
POSTGRESQL_USER=postgres
POSTGRESQL_PASSWORD=postgres
POSTGRESQL_DATABASE=discordbotSee Configuration for all available options.
The bot expects an external PostgreSQL instance running on a Docker network named postgres_network.
If you don't have one, you can start a local database using the included compose file:
docker compose -f docker-compose-localdb.yml up -dThen start the bot:
sudo systemctl enable docker
docker compose up --build -dThis will:
- Build the Docker image
- Run database migrations automatically
- Start the bot
docker-compose logs -f discordbotFor the full installation guide, see the Wiki.
All configuration is done through environment variables in the .env file.
| Variable | Default | Description |
|---|---|---|
BOT_TOKEN |
Discord bot token (required) | |
BOT_PREFIX |
! |
Command prefix |
BOT_EMBED_COLOR |
green |
Default embed color |
BOT_EMBED_OWNER_COLOR |
dark_purple |
Owner command embed color |
BOT_ALLOWED_DM_COMMANDS |
owner,about,gw2 |
Commands allowed in DMs |
BOT_BOT_REACTION_WORDS |
stupid,noob |
Words that trigger bot reactions |
BOT_EXCLUSIVE_USERS |
Restrict bot to specific users (comma-separated IDs) | |
BOT_BG_ACTIVITY_TIMER |
0 |
Background activity rotation timer (seconds, 0 = disabled) |
Configure any subset of the three providers — commands for unconfigured providers will return an error embed and the rest will still work.
| Variable | Default | Description |
|---|---|---|
BOT_OPENAI_API_KEY |
OpenAI API key (powers gpt, gptweb) |
|
BOT_OPENAI_MODEL |
gpt-5.5 |
OpenAI model name |
BOT_ANTHROPIC_API_KEY |
Anthropic API key (powers claude, claudeweb) |
|
BOT_ANTHROPIC_MODEL |
claude-opus-4-8 |
Anthropic model name |
BOT_GEMINI_API_KEY |
Google AI Studio key (powers gemini, geminiweb) |
|
BOT_GEMINI_MODEL |
gemini-flash-latest |
Gemini model name (rolling-latest alias) |
| Variable | Default | Description |
|---|---|---|
POSTGRESQL_HOST |
postgres |
Database host |
POSTGRESQL_PORT |
5432 |
Database port |
POSTGRESQL_USER |
postgres |
Database user |
POSTGRESQL_PASSWORD |
postgres |
Database password |
POSTGRESQL_DATABASE |
discordbot |
Database name |
POSTGRESQL_SCHEMA |
public |
Database schema |
| Variable | Default | Description |
|---|---|---|
LOG_LEVEL |
INFO |
Log level |
LOG_TIMEZONE |
UTC |
Log timezone |
LOG_DIRECTORY |
/app/DiscordBot |
Log file directory |
LOG_DAYS_TO_KEEP |
30 |
Log retention in days |
See .env.example for the complete list of configuration options including cooldowns, SSL, connection pooling, and retry settings.
Six commands across three providers. The *web variants enable the provider's built-in web search (OpenAI web_search, Anthropic web_search, Google Search grounding) for current/factual questions. The plain variants answer from training only — faster, cheaper, no live data.
All AI commands are channel-only (they cannot be invoked in DMs).
| Command | Provider | Web search |
|---|---|---|
gpt <message> |
OpenAI | no |
gptweb <message> |
OpenAI | yes |
claude <message> |
Anthropic Claude | no |
claudeweb <message> |
Anthropic Claude | yes |
gemini <message> |
Google Gemini | no |
geminiweb <message> |
Google Gemini | yes |
| Command | Description |
|---|---|
admin botgame <new game> |
Change game that bot is playing |
| Command | Description |
|---|---|
admin config list |
List all bot configurations |
admin config joinmessage [on, off] |
Toggle message when a user joins the server |
admin config leavemessage [on, off] |
Toggle message when a user leaves the server |
admin config servermessage [on, off] |
Toggle message when a server gets updated |
admin config membermessage [on, off] |
Toggle message when someone updates profile |
admin config blockinvisible [on, off] |
Block messages from invisible members |
admin config botreactions [on, off] |
Toggle bot reactions to member words |
admin config pfilter [on, off] <channel> |
Configure profanity filter per channel |
| Command | Description |
|---|---|
admin cc add <command> <text> |
Add a new custom command |
admin cc edit <command> <text> |
Edit an existing custom command |
admin cc remove <command> |
Remove a custom command |
admin cc removeall |
Remove all custom commands |
admin cc list |
List all custom commands |
| Command | Description |
|---|---|
about |
Display bot info |
echo <message> |
Show your message again |
ping |
Test latency |
pepe |
Post a random Pepe image |
tts <message> |
Send text-to-speech as .mp3 to channel |
serverinfo |
Show server information |
userinfo <member> |
Show Discord user information |
lmgtfy <search> |
Create a LMGTFY link |
invites |
List active invite links for the server |
| Command | Description |
|---|---|
roll |
Roll a die (defaults to 100) |
roll <size> |
Roll a die with specified size |
roll results |
Display all dice rolls from the server |
roll reset |
Delete all dice rolls (admin only) |
| Command | Description |
|---|---|
owner servers |
Display all servers in database |
owner prefix <new prefix> |
Change bot prefix for commands |
owner botdescription <new description> |
Update bot description |
| Command | Description |
|---|---|
gw2 account |
Display your GW2 account information |
gw2 characters |
Display your GW2 characters information |
gw2 session |
Display your last game session data |
gw2 worlds na |
List all NA worlds with WvW tier |
gw2 worlds eu |
List all EU worlds with WvW tier |
gw2 wiki <search> |
Search the Guild Wars 2 wiki |
gw2 info <search> |
Information about a given name/skill/rune |
| Command | Description |
|---|---|
gw2 config list |
List all GW2 configurations |
gw2 config session [on, off] |
Toggle recording of user sessions |
| Command | Description |
|---|---|
gw2 key add [api_key] |
Add your first GW2 API key |
gw2 key update [api_key] |
Update your existing API key |
gw2 key remove |
Remove your GW2 API key |
gw2 key info |
Show your API key information |
| Command | Description |
|---|---|
gw2 wvw info [world] |
Info about a WvW world |
gw2 wvw match [world] |
WvW match scores |
gw2 wvw kdr [world] |
WvW kill/death ratios |
Requires UV to be installed.
uv lock --upgrade && uv sync --all-extras --all-groups# Unit tests
poe test
# Integration tests (requires Docker for testcontainers)
poe test-integration
# All tests (unit + integration + hadolint + docker)
poe tests# Run linter (ruff)
poe linter
# Update all dev dependencies
poe updatedev
# Run database migrations
poe migration
# Profile unit tests
poe profile
# Profile integration tests
poe profile-integrationReleased under the MIT License
If you find this project helpful, consider supporting development.
