Provider Integrations

Provider integrations are the backend connections Anyy can use for model requests. A provider entry says how to reach a model service, how to authenticate, which wire protocol to use, and which model ids are available.

This is the main page for provider setup and provider configuration. For the model-selection workflow, including main model, auxiliary models, and fallback routing, use Configuring Models. For the compact field table, use Provider Config Reference.

Mental Model

Keep these concepts separate:

Provider entry: a configured connection under providers.
Main model: the provider/model pair used for ordinary chat and tool turns.
Auxiliary model: an optional model used for media-specific work.
Fallback chain: ordered backup models for main-model provider failures.

Provider entries do not make Anyy identify as that provider. The assistant identity remains Anyy.

Setup Flow

Use the setup wizard for normal provider setup:

anyy setup model

The wizard asks for a provider template, authentication, and model id. It writes a provider entry plus synchronized main-model fields.

Check the resolved state with:

anyy config

The dashboard Models page uses the same underlying provider configuration. It can set the global main model, reconfigure provider auth/base URL/model, test a connection, and show configured fallback and auxiliary entries.

Config Shape

A typical API-key provider looks like this:

providers:
  - id: openrouter
    profile: openrouter
    credential_ref: env:OPENROUTER_API_KEY
    default_model: anthropic/claude-sonnet-4

main_model:
  provider_id: openrouter
  model: anthropic/claude-sonnet-4

profile pulls in the known API mode, base URL, model-catalog URL, and default auth shape. If you do not use a profile, provide the required fields explicitly:

providers:
  - id: local
    api_mode: openai-compatible
    auth_mode: none
    base_url: http://127.0.0.1:1234/v1
    default_model: local-model

main_model:
  provider_id: local
  model: local-model

default_model: provider/model is still accepted as a shorthand for the main model. Anyy normalizes it with main_model when the config is loaded.

Provider Profiles

The setup-ready profile ids currently accepted for configured providers are:

openrouter, novita, lmstudio, anthropic, openai-codex, openai-api, alibaba, xiaomi, tencent-tokenhub, nvidia, huggingface, gemini, deepseek, xai, zai, kimi-coding, kimi-coding-cn, stepfun, minimax, minimax-cn, ollama-cloud, arcee, gmi, kilocode, opencode-zen, opencode-go, azure-foundry, alibaba-coding-plan, and ai-gateway.

Two setup templates intentionally have no profile id: anthropic-compatible and custom-openai-compatible. They write explicit api_mode, base_url, and auth fields instead.

Profile aliases are accepted for convenience. Prefer canonical ids in committed examples:

Alias	Canonical profile
`openai`	`openai-api`
`codex`	`openai-codex`
`qwen`, `qwen-cloud`	`alibaba`
`xiaomi-mimo`	`xiaomi`
`nvidia-nim`	`nvidia`
`google-ai-studio`, `google-gemini`	`gemini`
`zai-glm`	`zai`
`kimi-cn`	`kimi-coding-cn`

Some catalog entries can be listed as blocked when their auth flow is not available yet. A blocked entry is not a usable provider until that auth path is implemented and enabled.

API Modes

api_mode chooses the wire protocol:

Value	Use
`openai-compatible`	OpenAI-compatible chat/completions endpoints and many hosted routers.
`anthropic-messages`	Anthropic Messages-compatible endpoints.
`google-gemini`	Native Google Gemini API.
`openai-responses`	OpenAI Responses API.
`codex-responses`	Codex Responses backend used by the `openai-codex` profile.

Do not invent adapter names. For example, DeepSeek uses openai-compatible; a deepseek-compatible value is rejected.

Authentication

Provider credential fields accept references, not raw secrets:

Ref	Use
`env:NAME`	Credential supplied by the shell or service manager.
`file:/absolute/path`	Credential stored outside the profile home.
`secret:name`	Profile-local secret managed by Anyy.

credential_ref is preferred. api_key_ref remains accepted for API-key providers. Provider credential fields reject literal: values.

Auth modes are:

`auth_mode`	Credential rule
`api_key`	Use `credential_ref` or `api_key_ref`.
`oauth`	Use `credential_ref` when a reference is needed; `api_key_ref` is rejected.
`external_process`	Use `credential_ref` when needed; `api_key_ref` is rejected.
`aws_sdk`	Use `credential_ref` when needed.
`none`	No credential refs are allowed. The base URL must be local or private.

See Credentials & Authentication for where secrets are stored and how they are redacted.

Custom And Local Endpoints

Use a custom provider when the endpoint is OpenAI-compatible but not a built-in profile:

providers:
  - id: custom-openai
    api_mode: openai-compatible
    auth_mode: api_key
    base_url: https://models.example.com/v1
    credential_ref: env:CUSTOM_OPENAI_API_KEY
    default_model: team-model

Use auth_mode: none only for local or private endpoints:

providers:
  - id: lmstudio
    profile: lmstudio
    auth_mode: none
    base_url: http://127.0.0.1:1234/v1
    default_model: local-model

Public internet endpoints without auth are rejected by config validation.

Model Catalog And Overrides

When a provider has a model catalog, setup can list models during anyy setup model. If the catalog is empty, unavailable, or missing a model you need, choose Enter model id in the wizard or add a manual model entry:

providers:
  - id: local
    profile: lmstudio
    models:
      - id: local-model
        display_name: Local Model
        capabilities:
          tool_calls: true
          streaming: true
          max_context_tokens: 32768

Capability overrides are exact. Omit a key to keep the profile or provider adapter default; set true or false only when you know the provider behavior.

Routing And Fallback

Model routing is owned by Configuring Models. Use that page for:

setting main_model
configuring auxiliary_models.*
configuring auxiliary_models.fallback
understanding when fallback triggers

Provider-local fallback_chain remains accepted as a compatibility input and uses the same fields as auxiliary_models.fallback. The recommended setup path writes canonical fallback routing to auxiliary_models.fallback.

Fallback is a resilience path, not a way to bypass capability requirements. A candidate can be skipped when it cannot satisfy the turn's tools, media, context, or reasoning-continuity requirements.

Operational Checks

Run these after provider edits:

anyy config
anyy doctor

anyy config reports the resolved provider, model, API mode, base URL, auth reference status, and max-turn setting. Provider request failures still surface when a model is actually used; config.yaml has no separate provider health-check block.

Troubleshooting

Auth shows "(not set)": the referenced environment variable, file, or secret is missing.
Unknown provider profile: use one of the canonical profile ids above, or configure api_mode and base_url explicitly.
Model list is empty: enter a model id manually. The provider catalog is a convenience, not the only supported source of model ids.
Fallback never triggers: fallback only runs for fallback-eligible provider errors and only to compatible candidates.

Mental Model​

Setup Flow​

Config Shape​

Provider Profiles​

API Modes​

Authentication​

Custom And Local Endpoints​

Model Catalog And Overrides​

Routing And Fallback​

Operational Checks​

Troubleshooting​