How to add or remove provider models
Configure which concrete model IDs an existing provider exposes to Buffaly users, then verify provider catalog, selector, session selection, and a safe completion round trip.
Quick answer
Model availability is provider-catalog data, not a prompt convention. Buffaly validates provider, transport, model, and reasoning selections against the provider catalog before applying them to a session.
Do not add a model by merely telling the Buffaly agent to use a new model name in chat. Add or remove it where the provider catalog source gets its model list.
Provider, model, transport, and reasoning
| Concept | Meaning |
|---|---|
| Provider | AI family token such as openai, anthropic, xai, or gemini. |
| Transport | Request path such as codex_backend, responses_api, or provider_native. |
| Model | Provider-specific model name exposed in the catalog for one transport. |
| Reasoning level | Optional model-supported token such as low, medium, or high; not every model supports reasoning controls. |
| Default model | The provider row default model name, or a model marked as default when the provider source uses that pattern. |
Selection validation is strict: the catalog service resolves provider, transport, model, and reasoning level in order. If the requested model is not present for the selected provider transport, selection should fail instead of silently falling back.
Where model lists live
OpenAI/Codex-backed models
The OpenAI catalog source builds catalog rows from Codex model metadata returned by the Buffaly service. It creates model rows for codex_backend and responses_api transports.
OpenAI model availability is normally controlled by the Codex model metadata or backend configuration, not by adding arbitrary rows to a wiki page or unrelated provider settings.
Provider-native models
For provider-native modules, the module catalog source owns the provider row and model list. Anthropic-style settings may include model names, supported reasoning levels, default reasoning level, base URL, API version, and max tokens.
Treat the exact settings shape as provider-specific. Verify the provider module source before changing production settings.
Before you add a model
- Provider support: confirm the provider is installed and appears in the provider catalog.
- Transport: confirm the model belongs under the right transport, such as
provider_native,codex_backend, orresponses_api. - External availability: verify the provider supports the exact model name for the target account, region, and API version.
- Reasoning metadata: verify whether the model supports reasoning levels and which tokens are valid.
- Default selection: decide whether the new model should be default or simply available.
- Credentials: confirm credentials are configured separately from model metadata.
How to add, remove, or deprecate a model
Provider-native add
- Locate the provider module source or catalog documentation.
- Find where it builds catalog model rows.
- Add the model to provider-specific settings or the catalog source.
- Update default model and reasoning metadata only to supported values.
- Reload the target instance if settings or catalog cache require it.
- Verify catalog row, session selection, and a safe smoke prompt.
OpenAI/Codex add
- Check the Codex model metadata endpoint used by the Buffaly service.
- If changing fallback/default behavior, check the Codex backend default model setting.
- Do not hard-code an OpenAI model into provider-native settings.
- Verify the model appears under the intended OpenAI transport.
- Validate session selection through the catalog service or UI selector.
Remove or deprecate
- Stop making the old model default first.
- Verify the replacement catalog selection and smoke test.
- Communicate the replacement when users know the old name.
- Remove it from the authoritative catalog source or settings.
- Confirm stale selection fails clearly and selecting the replacement succeeds.
- Avoid silent aliases unless an external boundary explicitly requires a mapper.
How to ask Buffaly to do it
Add: Add claude-sonnet-4-5 to the Anthropic provider model list for this Buffaly instance. Inspect the provider catalog source and provider feature settings first, do not put secrets in source, update only authoritative model metadata, verify the catalog and a safe session smoke test, and commit only intentional changes.
Remove: Remove deprecated model old-model-name from provider anthropic. First change the provider default to a supported replacement, verify no catalog default points at the old model, then remove it from provider-native catalog source/settings and test that stale selection fails clearly.
Diagnose: Diagnose why model gpt-x does not appear for provider openai. Check the Codex model metadata path, provider catalog endpoint, transport rows, and UI selector source before changing anything.
Verification checklist
- The provider catalog endpoint returns the expected provider row.
- The model appears only under the intended transport.
- The default model points to an available model for the default transport.
- Reasoning metadata uses valid tokens and includes the default reasoning level when controls exist.
- The UI provider/model selector reflects the catalog after reload.
- Provider selection accepts the new model and rejects removed models.
- A safe session prompt completes with the selected provider, transport, and model.
- Logs show no provider module load failures, missing feature rows, invalid settings, or unsupported model errors.
API verification
Use the provider catalog endpoint to inspect the authoritative runtime catalog.
POST /api/buffaly.agent.host/provider-catalog-service/get-provider-catalogInspect provider, default transport, default model name, transport rows, model names, model transports, default reasoning level, supported reasoning levels, default selection, and any top-level error.
Then set a test session selection using the documented provider-selection endpoint and run a safe completion prompt such as Reply with exactly: provider model smoke ok.
Common mistakes
Adding a model in the wrong place. Model rows are transport- and provider-specific; do not add provider-native models to OpenAI/Codex configuration or OpenAI models to provider-native feature rows.
Forgetting the default model. If the default model points to a removed model, default model resolution can fail for that provider and transport.
Using unsupported reasoning levels. Reasoning is model metadata, and selected reasoning must be supported by the selected model.
Expecting removed models to keep working. Removed models should fail selection clearly instead of silently falling back.
Treating examples as production settings. Verify provider module source and the target installation before editing live settings.