Skip to main content

AI Companion — Setup

This page walks you through turning the AI Companion on for your server. For what the Companion is and how it behaves, read the AI Companion concept first.

There are three steps:

  1. Create an API key with an AI provider (you bring your own).
  2. Add that key to dzbot under Settings.
  3. Give the right people the access right.

Step 1 — Get an API key from a provider​

The Companion is bring-your-own-key: you choose one provider, create an account there, set up payment, and generate an API key. The provider bills your account directly for usage — dzbot never charges you for the AI itself.

You only need one provider. Pick whichever you already have an account with, or whichever you prefer. dzbot supports three:

ProviderModel dzbot uses
OpenAIGPT-5 mini
AnthropicClaude Haiku 4.5
GoogleGemini 2.5 Flash

These are fast, low-cost models that are more than capable for the Companion's work. You do not choose the model yourself — dzbot uses the right one for the provider you pick.

Cost

The Companion's tasks are small (a few lookups, then some drafting), and these are inexpensive models, so day-to-day cost is typically very low. You control spending entirely through your provider account — set a budget or spend limit there if you want a hard ceiling.

OpenAI​

  1. Create an account at platform.openai.com.
  2. Open the Billing settings and add a payment method, then add some credit (OpenAI works on a prepaid balance — start with a small top-up).
  3. Go to the API keys section and create a new secret key.
  4. Copy the key immediately — it is shown only once. It starts with sk-.

Anthropic​

  1. Create an account at console.anthropic.com.
  2. Open Billing (Plans & Billing) and purchase credits (Anthropic also works on a prepaid balance — a small amount is enough to start).
  3. Go to API keys and create a new key.
  4. Copy the key immediately — it is shown only once. It starts with sk-ant-.

Google (Gemini)​

  1. Sign in to Google AI Studio (aistudio.google.com) with a Google account.
  2. Use Get API key to create a key. The key is created inside a Google Cloud project (AI Studio sets one up for you if needed).
  3. For more than light testing, enable billing on that Google Cloud project so you are on the paid tier with proper rate limits. Google offers a free tier, but it has tight limits and is best treated as a trial.
  4. Copy the generated key.
Keep your key private

An API key is a secret tied to your billing. Don't share it, post it in Discord, or commit it anywhere. If a key leaks, revoke it in the provider's dashboard and create a new one.

Step 2 — Add the key in dzbot​

Navigation path:

  • Server Admin -> Settings -> Integrations

Find the AI Companion credentials field and:

  1. Choose your provider from the dropdown (OpenAI, Anthropic, or Google).
  2. Paste your API key into the key field.
  3. Click Save.

After saving, the key is masked — you only ever see a few characters at the start and end (for example sk-••••abcd), never the full value again. To change it later, use Replace key, paste a new one, and save. Changing the provider does not require re-pasting the key unless you actually want to replace it.

Configuring the key requires the admin.settings.edit access right.

Step 3 — Enable the access right​

The Companion only shows up for users who have the AI Companion access right (it lives in the Tickets group of admin rights, as tickets.ai_companion). Grant it to the groups whose members should be able to use the Companion:

  • Server Admin -> Groups -> select a group -> enable AI Companion.

Anyone in a group with this right will see the AI Companion button in the admin header (the sparkles icon, top right) once a key is configured. Users without the right never see it.

For how access rights and groups work in general, see Access control.

Verifying it works​

Once a key is saved and you have the access right:

  1. Reload the admin panel.
  2. Look for the AI Companion button (sparkles icon) in the top-right header.
  3. Open it, start a New session, and ask something simple like "search for player <name>".

If you get a sensible answer back, you're set. Head to AI Companion usage to learn what it can do.

Troubleshooting​

If a session fails, the chat shows a short message describing why:

MessageWhat it meansWhat to do
Not configuredNo provider/key is set for this serverAdd a key (Step 2)
API key rejectedThe stored key is invalid or revokedA server admin should replace it in Settings
Usage or billing limitThe provider reported a quota or billing limitTop up credit or raise the limit in the provider's dashboard
Provider unavailableA temporary outage at the providerWait a moment and try again
Maximum steps reachedThe task ran long without finishingStart a new session and break the task into smaller asks