AI providers

Copilot runs on your own AI account. The AI Provider tab is where you add the key it uses, and where you add more keys so the assistant keeps answering when one provider stops responding.

Supported providers: OpenAI, Anthropic, Google Gemini, xAI.

Where it is

1. Open Copilot from any admin page.
2. On the welcome screen, click the gear icon in the header. The gear only appears before a conversation starts - click New conversation first if one is active.
3. Open the AI Provider tab.

The tab is visible only to roles that hold the AI Providers and Connectors permission. Because provider keys decide what the store spends on AI, this is a separate permission from the one that controls the widget's appearance. See Configure role permissions.

Keys are stored encrypted on the Copilot server, per Magento instance. They are not kept in Magento's configuration and are not part of a Magento configuration export.

Add a provider

1. Click Add a provider.

2. Fill the form:

   • Provider - OpenAI, Anthropic, Google Gemini, or xAI.
   • Name - how this key is labelled in the list. Useful when you hold two keys for the same provider. It is also the name Copilot uses when it tells you a provider could not answer.
   • API key - stored encrypted and never shown again. When editing an existing entry, leave it unchanged to keep the current key.
   • Model - the model this key runs. The first option is the recommended one; change it only if you have a reason to.
   • Enabled - clear it to keep the entry and its key but take it out of use.

3. Click Save provider.

note

For Anthropic, use a workspace-scoped key. An organisation-level key is rejected on every request.

Test a key

Test sends a probe request with that key and records the result against the entry. Use it after adding a key, after rotating one, or when Copilot has stopped answering and you want to know which key is at fault.

Each entry carries a status badge:

Badge	What it means
OK	The key answered.
UNCHECKED	Nobody has probed it yet. It is still tried - the attempt itself classifies it.
EMPTY_KEY	No key is stored for the entry.
INVALID_KEY	The provider rejected the key.
INSUFFICIENT_QUOTA	The account is out of credit or over its spending cap.
MODEL_UNAVAILABLE	The account cannot use the selected model. Pick another model.
RATE_LIMITED	The provider is throttling the account right now.
TRANSIENT_ERROR	A temporary failure at the provider's end.

Anything other than OK shows the provider's own explanation underneath, so you can act on it without leaving the tab.

EMPTY_KEY, INVALID_KEY, INSUFFICIENT_QUOTA, and MODEL_UNAVAILABLE do not clear on their own - an entry in one of them stays out of rotation until you fix it. RATE_LIMITED and TRANSIENT_ERROR clear by themselves, so those entries keep being tried.

Fallback order

The list is the fallback order. The first usable entry answers; the rest are fallbacks, tried in order when it cannot. The entry currently answering carries an in use badge.

Reorder with the arrows on each row. Disabled entries stay in the list and can be reordered like any other - the dot on the left shows whether an entry is enabled, and Copilot skips the disabled ones when it picks a provider.

One provider is enough to use Copilot. A second one from a different vendor is what makes the store resilient to one vendor's outage.

What failover looks like

When the provider that was answering stops, Copilot moves the turn to the next one and writes a short note into the conversation:

OpenAI could not answer. Switching to Anthropic the provider's own explanation

The turn continues on the new provider, keeping its history - you do not have to ask again. If no other provider is configured, the note says so instead:

OpenAI could not answer, and no other provider is configured

The outcome is also recorded against the entry in this tab, so the badge tells you afterwards which key failed and why.

Remove a provider

Remove deletes the entry and its stored key. This cannot be undone, and Copilot asks for confirmation first.

When Copilot cannot answer at all

If the store has no provider key, or none of its keys is usable, the welcome screen shows a notice in place of the usual greeting:

• You have no AI providers configured.
• All configured AI providers are unreachable.

The second line depends on the role. An admin who may manage providers is pointed at this tab; one who may not is told to ask an administrator who can. The notice clears as soon as a usable provider is saved - no page reload needed.