# Model providers

Flarebot resolves models through `worker/model-provider.ts`. Cloudflare Workers
AI retains its native binding. OpenRouter uses `worker/gateway-model.ts` and
`AI.gateway("default").run(...)`; Anthropic retains its direct official SDK.
Think and the Agents SDK continue to own turns, tool execution, streaming, and
conversation state.

## Enable OpenRouter

Workers AI is available by default. OpenRouter is opt-in and uses AI Gateway's
native `openrouter` provider. Flarebot does not create or manage an AI Gateway
custom-provider route.

1. In **Settings → Model and provider**, select **OpenRouter**, then **Enable
   OpenRouter**. The ownership-checked control-plane flow delivers a short-lived,
   purpose-separated signed receipt to the customer runtime.
2. Save a new OpenRouter API key. It remains encrypted in customer-owned Durable
   Object storage and is never sent to the control plane. Saving confirms storage,
   not upstream authentication.
3. Ensure the OpenRouter account has billing or credits available, save the
   model, and send a request.

The receipt uses `PROVIDER_PURPOSE`, pins issuer, runtime audience, owner, and
installation, and records state `openrouter` in `flarebot_enabled_providers`.
It cannot create a browser session. Delivery is idempotent, and setup succeeds
only after the runtime acknowledges persistence. Selection, key writes, and
inference reject OpenRouter until enabled; key removal remains available.

OpenRouter requests use provider `openrouter` and the fixed endpoint
`https://openrouter.ai/api/v1/chat/completions`. They send the OpenRouter key as
Bearer authentication and do not send an `x-opencode-session` header. The initial
curated catalog contains only `openai/gpt-5-mini` using Chat Completions. There is
no automatic provider fallback. OpenRouter billing and model availability apply
to interactive and scheduled requests.

Flarebot skips gateway response caching and disables gateway request/response log
collection. This does not change OpenRouter's retention policy. Content-free
diagnostics retain provider/model identity and timing. Failed attempts emit one
`flarebot.model-error` record with bounded safe fields such as HTTP status,
failure stage, category, numeric gateway error code, and validated `cfRay`.
Messages, bodies, headers, keys, and prompts are not logged.

## Credentials and migration

Provider credentials are encrypted per provider in
`flarebot_provider_credentials` using the installation session-secret-derived
AES-GCM key. Only configured/missing flags reach the UI. The existing Anthropic
legacy-column migration remains unchanged.

OpenCode Go is retired. On upgrade, a selected OpenCode model is reset to the
Workers AI default. Retired OpenCode encrypted credentials and enablement rows are
deleted, not converted to OpenRouter. Users must separately enable OpenRouter,
enter a new OpenRouter key, and have billing or credits available.

## Add another provider

Add a trusted registry entry in `shared/model-providers.ts` with its display name,
credential requirement, fixed model IDs, protocol, native gateway provider, and
fixed upstream endpoint. Extend signed runtime enablement when the provider is
opt-in. No setting accepts an arbitrary endpoint, header set, model ID, or gateway
URL. Exercise representative streaming text, tool calls, failures, and
cancellation through the production model factory.

## References

- [OpenRouter API documentation](https://openrouter.ai/docs/api/reference/overview)
- [Cloudflare AI Gateway binding integration](https://github.com/cloudflare/ai/tree/main/packages/ai-gateway-provider#cloudflare-ai-binding-example)