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.
- 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:
# RequiredBOT_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
# DatabasePOSTGRESQL_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.
