Official provider plugins

Official provider plugins publish their own model catalog rows. These providers require no models.providers model entries; enable the provider plugin, set auth, and pick a model. Use models.providers only for explicit custom providers or narrow request settings such as timeouts.

OpenAI

• Provider: openai
• Auth: OPENAI_API_KEY
• Optional rotation: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, plus APUS_LIVE_OPENAI_KEY (single override)
• Fresh setup default: openai/gpt-6-astra.
• Example models: openai/gpt-6-astra, openai/gpt-5.6-sol, openai/gpt-5.6-terra, openai/gpt-5.6-luna, openai/gpt-5.5; the bare direct-API openai/gpt-5.6 alias remains supported.
• Verify account/model availability with apus models list --provider openai if a specific install or API key behaves differently.
• CLI: apus onboard --auth-choice openai-api-key
• Direct OpenAI API-key Responses requests default to "sse".
• Override per model via agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket", "websocket-cached", or "auto"). Cached WebSockets reuse the session connection and send only new input with previous_response_id when history still matches.
• The "sse" transport also supports HTTP continuation for a native openai/openai-responses model at the exact public https://api.openai.com/v1 base URL (ChatGPT/Codex openai-chatgpt-responses routes are excluded and deliberately stay store: false): Apus caches the request per session+credential and, when the next turn's history is a strict extension, sends only the new input plus previous_response_id instead of the full growing history. A rejected/expired previous_response_id (Zero Data Retention, TTL eviction) retries once, same turn, with the full request.
  • That in-process cache evicts a session's baseline after 90 minutes without a turn; a gap longer than that resends full history once and starts a fresh baseline. This is a fixed default, not an operator-configurable setting.
  • For a custom openai-responses model, set models.providers.<provider>.models[].compat.supportsResponsesContinuation: true after verifying that its endpoint supports stored responses and previous_response_id. This enables store: true for that model, allowing the backend to retain requests even when a turn cannot continue. Other custom models remain stateless. compat.supportsStore: false disables this opt-in. The azure-openai-responses and ChatGPT/Codex transports, plus the azure-openai and azure-openai-responses provider IDs, are excluded.
• Set an explicit OpenAI API service tier with params.serviceTier or params.service_tier; Fast mode (formerly Priority processing) uses service_tier=priority.
• On native public OpenAI and ChatGPT/Codex Responses requests, precedence is payload/transport service_tier, then a valid explicit model param, then the fast-mode default.
• /fast and valid params.fastMode / params.fast_mode values are shared agent-runtime controls; on direct embedded openai/* Responses requests they supply service_tier=priority only when no higher-precedence tier exists.
• Hidden Apus attribution headers (originator, version, User-Agent) apply only on native OpenAI traffic to api.openai.com, not generic OpenAI-compatible proxies
• Native OpenAI provider-managed storage, prompt-cache hints, and reasoning payload shaping are unchanged. Raw native transport calls retain store: false by default. The custom-model continuation opt-in enables storage only; it does not enable prompt-cache hints or server compaction.
• openai/gpt-5.3-codex-spark is available only through ChatGPT/Codex OAuth; direct OpenAI API-key and Azure API-key routes reject it

{
  agents: { defaults: { model: { primary: "openai/gpt-6-astra" } } },
}

If the API organization does not expose GPT-5.6, set openai/gpt-5.5 explicitly. Normal onboarding and reauthentication preserve an existing explicit primary model; models auth login --set-default and models set are the intentional replacement paths.

Anthropic

• Provider: anthropic
• Auth: ANTHROPIC_API_KEY
• Optional rotation: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, plus APUS_LIVE_ANTHROPIC_KEY (single override)
• Example model: anthropic/claude-opus-5-5
• CLI: apus onboard --auth-choice apiKey
• Direct public Anthropic requests support the shared /fast toggle and params.fastMode, including API-key and OAuth-authenticated traffic sent to api.anthropic.com; Apus maps that to Anthropic service_tier (auto vs standard_only)
• Preferred Claude CLI config keeps the model ref canonical and selects the CLI backend separately: anthropic/claude-opus-5-5 with model-scoped agentRuntime.id: "claude-cli". Legacy claude-cli/claude-opus-4-7 refs still work for compatibility.

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-5-5" } } },
}

OpenAI ChatGPT/Codex OAuth

• Provider: openai
• Auth: OAuth (ChatGPT)
• Fresh native Codex app-server harness ref: openai/gpt-6-astra
• Native Codex app-server harness docs: Codex harness
• Astra (openai/gpt-6-astra) defaults to medium reasoning effort when the account supports it. The OpenAI provider default is shared by model controls and both runtimes; explicit thinking settings take precedence.
• Legacy model refs: codex/gpt-*, openai-codex/gpt-*
• Plugin boundary: openai/* loads the OpenAI plugin; explicit runtime policy or the provider-owned effective route decides whether the native Codex app-server plugin is selected.
• CLI: apus onboard --auth-choice openai or apus models auth login --provider openai
• Apus's embedded ChatGPT Responses transport defaults to auto (WebSocket-first, SSE fallback).
• agents.defaults.models["openai/<model>"].params.transport and params.serviceTier are authored embedded-provider request settings. They keep implicit runtime selection on Apus; native Codex owns its app-server transport and service tier.
• Valid model-scoped params.fastMode / params.fast_mode values and valid cutoff keys are portable typed agent-runtime controls. They do not count as authored provider request params and do not select a runtime. Pin agentRuntime.id: "apus" or agentRuntime.id: "codex" when a recipe depends on one runtime.
• Hidden Apus attribution headers (originator, version, User-Agent) are only attached on native Codex traffic to chatgpt.com/backend-api, not generic OpenAI-compatible proxies
• The shared /fast toggle, configured defaults, and valid model-scoped Fast params resolve through one runtime-control policy. See Thinking levels for precedence.
• OpenAI API Fast mode is premium-priced and model-specific. GPT-5.6 Sol currently costs 2× Standard token pricing, and long-context multipliers stack. ChatGPT/Codex-credit Fast mode is separate: GPT-5.6 and GPT-5.5 currently consume 2.5× Standard credits, while API-key Codex runs use API token pricing. See Fast mode, API pricing, and Codex speed.
• The native Codex catalog can expose exact openai/gpt-5.6-sol, openai/gpt-5.6-terra, and openai/gpt-5.6-luna refs according to account access. It does not apply the direct API's bare gpt-5.6 alias client-side.
• openai/gpt-5.5 uses the Codex catalog native contextWindow = 400000 and default runtime contextTokens = 272000; override the runtime cap with models.providers.openai.models[].contextTokens
• Sign in with openai auth and use openai/gpt-6-astra for a fresh subscription-backed setup. Select openai/gpt-5.5 explicitly if that Codex workspace does not expose Astra.
• Use provider/model agentRuntime.id: "apus" to keep an otherwise eligible route on the built-in runtime. With runtime unset or auto, only an exact official HTTPS Responses/ChatGPT-compatible route with no authored provider request override may select Codex implicitly.
• Legacy Codex GPT refs are legacy state, not a live provider route. Use canonical openai/* refs for new agent config, and run apus doctor --fix to migrate codex/* and openai-codex/* refs while preserving their native Codex semantics with model-scoped agentRuntime.id: "codex". Existing explicit canonical openai/gpt-5.5 selections are not upgraded.

{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-6-astra" },
    },
  },
}

{
  models: {
    providers: {
      openai: {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}

Other subscription-style hosted options

MiniMax Coding Plan OAuth or API key access.

Qwen Cloud provider surface plus Alibaba DashScope and Coding Plan endpoint mapping.

Z.AI Coding Plan or general API endpoints.

OpenCode

• Auth: OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY)
• Zen runtime provider: opencode
• Go runtime provider: opencode-go
• Example models: opencode/claude-opus-4-6, opencode-go/kimi-k2.6
• CLI: apus onboard --auth-choice opencode-zen or apus onboard --auth-choice opencode-go

{
  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
}

Google Gemini (API key)

• Provider: google
• Auth: GEMINI_API_KEY
• Optional rotation: GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, GOOGLE_API_KEY fallback, and APUS_LIVE_GEMINI_KEY (single override)
• Default model: google/gemini-4-argon
• Other bundled models include google/gemini-3.8-flash and google/gemini-3.5-flash-lite
• Compatibility: legacy Apus config using google/gemini-3.1-flash-preview is normalized to google/gemini-3-flash-preview
• Alias: google/gemini-3.1-pro is accepted and normalized to Google's live Gemini API id, google/gemini-3.1-pro-preview
• CLI: apus onboard --auth-choice gemini-api-key
• Thinking: /think adaptive uses Google dynamic thinking. Gemini 3/3.1 omit a fixed thinkingLevel; Gemini 2.5 sends thinkingBudget: -1.
• Direct Gemini runs also accept agents.defaults.models["google/<model>"].params.cachedContent (or legacy cached_content) to forward a provider-native cachedContents/... handle; Gemini cache hits surface as Apus cacheRead

Google Vertex and Gemini CLI runtime

• google-vertex: managed Google Cloud access through gcloud Application Default Credentials. With a recognized ADC file plus GOOGLE_CLOUD_PROJECT (or GCLOUD_PROJECT) and GOOGLE_CLOUD_LOCATION in the gateway service environment, Apus discovers the provider automatically and no credential needs to be stored. For metadata-only credentials or an explicit override, the ADC path is selected by storing the literal sentinel value gcp-vertex-credentials. Other stored values are sent as an API key, not as ADC credentials; do not paste an OAuth access token. See Google provider setup.
• google-gemini-cli: optional local runtime for an explicitly configured canonical google/* model.

Apus does not create Gemini CLI OAuth or Antigravity OAuth profiles. Connect Google through an AI Studio API key or Vertex AI. If you explicitly choose the Gemini CLI runtime, it can use the selected Google API-key profile. Existing valid Gemini CLI OAuth profiles remain runtime-compatible, but they are not a setup or recovery route.

Gemini CLI uses stream-json by default. Apus reads assistant stream messages and normalizes stats.cached into cacheRead; legacy --output-format json overrides still read reply text from response.

Z.AI (GLM)

• Provider: zai
• Auth: ZAI_API_KEY
• Example model: zai/glm-5.2
• CLI: apus onboard --auth-choice zai-api-key
  • Model refs use the canonical zai/* provider ID.
  • zai-api-key auto-detects the matching Z.AI endpoint; zai-coding-global, zai-coding-cn, zai-global, and zai-cn force a specific surface

Vercel AI Gateway

• Provider: vercel-ai-gateway
• Auth: AI_GATEWAY_API_KEY
• Example models: vercel-ai-gateway/anthropic/claude-opus-4.6, vercel-ai-gateway/moonshotai/kimi-k2.6
• CLI: apus onboard --auth-choice ai-gateway-api-key

Other bundled provider plugins

Quirks worth knowing

Applies its app-attribution headers and Anthropic `cache_control` markers only on verified `openrouter.ai` routes. DeepSeek, Moonshot, and ZAI refs are cache-TTL eligible for OpenRouter-managed prompt caching but do not receive Anthropic cache markers. As a proxy-style OpenAI-compatible path, it skips native-OpenAI-only shaping (`serviceTier`, Responses `store`, prompt-cache hints, OpenAI reasoning-compat). Gemini-backed refs keep proxy-Gemini thought-signature sanitation only.

Gemini-backed refs follow the same proxy-Gemini sanitation path; `kilocode/kilo-auto/balanced` and other proxy-reasoning-unsupported refs skip proxy reasoning injection.

API-key onboarding writes explicit M3 and M2.7 chat model definitions; image understanding stays on the plugin-owned `MiniMax-VL-01` media provider.

Model ids use a `nvidia/<vendor>/<model>` namespace (for example `nvidia/nvidia/nemotron-...`); pickers preserve the literal `<provider>/<model-id>` composition while the canonical key sent to the API stays single-prefixed.

Uses the xAI Responses path. The recommended path is SuperGrok/X Premium OAuth; OAuth and API-key setup use the curated `xai/grok-4.7` default. Existing primary models stay pinned. Run `apus doctor --fix` to repair retired `xai/auto` selections on the native API and subscription routes. API keys still work via `XAI_API_KEY` or plugin config. Grok `web_search` reuses the same auth profile before API-key fallback. Older `/fast` and `params.fastMode: true` configurations still resolve through xAI's Grok 4.3 compatibility redirects, but new configurations should select a current model directly. `tool_stream` defaults on; disable via `agents.defaults.models["xai/<model>"].params.tool_stream=false`.