Add a model via a custom provider
Everyone · Build the agent team
Steps at a glance
1. Decide whether you actually need a custom provider
The built-in harness options cover the mainstream models. You need this route when you want a model that is not otherwise offered — a cheaper model for high-volume low-stakes work, a specific open model, or something only available through an aggregator such as OpenRouter.
The trade-off is that this path is fiddly and mostly cannot be delegated to an agent: the values have to be pasted exactly, and an agent can tell you what to paste but cannot paste it for you.
2. Get an API key from the provider
Create an account with the provider and generate an API key. Note the base URL the provider documents for OpenAI-compatible access — you will need it verbatim.
Store the key in your password manager, not in a note or a channel message.
3. Create a Buzz agent and choose the OpenAI-compatible provider
Create a new agent, choose the bundled Buzz agent as the harness, then set the LLM provider to the OpenAI compatible option.
4. Enter the key and the base URL
Paste the API key into the key field.
Then open the advanced settings and paste the base URL into the base URL field, exactly as the provider gives it — no trailing slash added or removed, no version path guessed.
Warning
This is where this task earns its difficulty. A wrong base URL fails in a way that looks like the agent is broken rather than misconfigured.
5. Set thinking effort and pick the model
Set thinking effort to inherit the agent default unless you have a reason to override it, then choose the model from the list that becomes available.
The effort dropdown for OpenAI-compatible providers no longer offers max. This is not a restriction, it is the removal of a lie: the request path had always clamped max down to xhigh on the wire, so the option did nothing except mislead. If a note somewhere in your team's material says to set max effort on a custom provider, xhigh is what it was getting.
Since v0.5.15 the model labels, thinking modes, supported effort levels and wire routes all come from one manifest read by both sides of the app, replacing two hand-maintained tables that had drifted apart. The practical effect is that what the dropdown offers should now match what the request actually does — worth knowing if you previously learned to distrust the labels.
Test with a small request before you rely on it. See Delegate work to agents in a channel.
Note
Field names and their locations have moved between releases. If a field is not where this page says, look through the agent's settings and advanced settings in your build.
Verified against Buzz v0.5.20 · Updated 2 Sep 2026