agents.defaults.model and agents.defaults.modelSelectionScope: which model an agent uses, what it falls back to, and how far a model change applies.

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      utilityModel: "openai/gpt-5.4-mini",
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      mediaModels: {
        image: {
          primary: "openai/gpt-image-2",
          fallbacks: ["google/gemini-3.1-flash-image"],
        },
        video: {
          primary: "qwen/wan2.6-t2v",
          fallbacks: ["qwen/wan2.6-i2v"],
        },
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // global default provider params
      pdfMaxMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      fastModeDefault: false,
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      mediaMaxMb: 5,
      maxConcurrent: 4,
    },
  },
}

Leaving agents.defaults.timeoutSeconds unset gives ordinary agent runs the 48-hour default. Set it only when you need a different whole-run limit; see Agent runtime.

• model: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).

  • String form sets only the primary model.
  • Object form sets primary plus ordered failover models.

• utilityModel: optional provider/model ref or alias for short internal tasks. It currently powers generated Control UI session titles, Telegram DM topic titles, Discord auto-thread titles, rolling Activity recaps, and progress-draft narration. When unset, Apus derives the primary provider's declared small-model default when one exists (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5); title tasks otherwise use the agent's primary model, and narration stays off. If a distinct utility model cannot prepare or complete a generated title, Apus retries that title once with the primary model. For dashboard titles, automatic utility derivation and the regular fallback use the effective session provider and auth profile; an explicit utility model keeps its configured provider/auth. Set utilityModel: "" to skip the alternate utility route; dashboard title generation still proceeds directly to the regular session model. agents.entries.*.utilityModel overrides the default, and an operation-specific model override wins over both. Utility tasks make separate model calls and send task-specific content to the selected model provider. Dashboard title generation sends at most the first 1,000 characters of the first non-command message; narration sends the inbound request plus compact redacted tool summaries. Activity recaps send the previous recap and bounded excerpts of new transcript messages. Recaps stay on the utility route, retain cached text when it is unavailable, and stop generating when utility routing is disabled. Choose a provider that matches your cost and data-handling requirements. During fresh setup, an explicit nonempty utilityModel can power the Apus setup assistant before a regular primary model is configured. Selecting the utility role leaves regular agent chat unconfigured. Automatic provider-derived utility models are not used to bootstrap setup. Once a primary model is configured, the system assistant uses it, while short utility tasks retain their utility route. Older configs retain their previous implicit primary, even when it matches the utility model or alias. Doctor and normal config writes preserve that route as an explicit primary before recording the utility-separation migration. Setup uses the config from before provider preparation, so a newly added utility provider cannot become the preserved primary. After migration, implicit fallback to a configured provider skips the explicit utility model; an explicit primary or fallback selection remains authoritative. Dynamic catalog IDs and ambiguous auth-profile suffixes keep their legacy routing until you choose an explicit primary; migration does not freeze those values. If utility setup encounters an unconverted legacy primary, it asks you to run apus doctor --fix or choose an explicit primary before authenticating the utility provider. Existing model routing stays available during that repair.

• imageModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).

  • Used by the view_image tool path as its vision-model config when the active model cannot accept images. Native-vision models receive loaded image bytes directly instead.
  • Also used as fallback routing when the selected/default model cannot accept image input.
  • Prefer explicit provider/model refs. Bare IDs are accepted for compatibility; if a bare ID uniquely matches a configured image-capable entry in models.providers.*.models, Apus qualifies it to that provider. Ambiguous configured matches require an explicit provider prefix.

• mediaModels.image: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).

  • Used by the shared image-generation capability and any future tool/plugin surface that generates images.
  • Typical values: google/gemini-3.1-flash-image for native Gemini image generation, fal/fal-ai/flux/dev for fal, openai/gpt-image-2 for OpenAI Images, or openai/gpt-image-1.5 for transparent-background OpenAI PNG/WebP output.
  • If you select a provider/model directly, configure matching provider auth too (for example GEMINI_API_KEY or GOOGLE_API_KEY for google/*, OPENAI_API_KEY or OpenAI Codex OAuth for openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY for fal/*).
  • If omitted, image_generate can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered image-generation providers in provider-id order.

• mediaModels.music: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).

  • Used by the shared music-generation capability and the built-in music_generate tool.
  • Typical values: google/lyria-3-clip-preview, google/lyria-3-pro-preview, or minimax/music-2.6.
  • If omitted, music_generate can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered music-generation providers in provider-id order.
  • If you select a provider/model directly, configure the matching provider auth/API key too.

• mediaModels.video: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).

  • Used by the shared video-generation capability and the built-in video_generate tool.
  • Typical values: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash, or qwen/wan2.7-r2v.
  • If omitted, video_generate can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered video-generation providers in provider-id order.
  • If you select a provider/model directly, configure the matching provider auth/API key too.
  • The official Qwen video-generation plugin supports up to 1 output video, 1 input image, 4 input videos, 10 seconds duration, and provider-level size, aspectRatio, resolution, audio, and watermark options.

• pdfModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).

  • Used by the pdf tool for model routing.
  • If omitted, the PDF tool falls back to imageModel, then to the resolved session/default model.

• pdfMaxMb: default PDF size limit for the pdf tool when maxBytesMb is not passed at call time.

• pdfMaxPages: default maximum pages considered by extraction fallback mode in the pdf tool.

• fastModeDefault: default fast mode for agents. Values: "auto", true, false. Per-agent agents.entries.*.fastModeDefault overrides it when no per-message or session fast-mode override is set.

• verboseDefault: default verbose level for agents. Values: "off", "on", "full". Default: "off".

• toolProgressDetail: detail mode for /verbose tool summaries and progress-draft tool lines. Values: "explain" (default, compact human labels) or "raw" (append raw command/detail when available). Per-agent agents.entries.*.toolProgressDetail overrides this default.

• reasoningDefault: default reasoning visibility for agents. Values: "off", "on", "stream". Per-agent agents.entries.*.reasoningDefault overrides this default. Configured reasoning defaults are only applied for owners, authorized senders, or operator-admin gateway contexts when no per-message or session reasoning override is set.

• elevatedDefault: default elevated-output level for agents. Values: "off", "on", "ask", "full". Default: "on".

• model.primary: format provider/model (e.g. openai/gpt-6-astra for Codex OAuth access). If you omit the provider, Apus tries an alias first, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider (deprecated compatibility behavior, so prefer explicit provider/model). If that provider no longer exposes the configured default model, Apus falls back to the first configured provider/model instead of surfacing a stale removed-provider default.

• To cap active input for one model, set models.providers.<provider>.models[].contextTokens; use contextWindow on the same entry for its native window. See OpenAI context window defaults.

• models: configured aliases and per-model settings. Each entry can include alias (shortcut) and params (provider-specific, for example temperature, maxTokens, cacheRetention, context1m, anthropicServerCompaction, anthropicCompactThreshold, responsesServerCompaction, responsesCompactThreshold, OpenRouter provider routing, chat_template_kwargs, extra_body/extraBody). Adding entries does not restrict model overrides.

  • Use provider/* entries such as "openai/*": {} or "vllm/*": {} to show all discovered models for selected providers without manually listing every model id.
  • Add agentRuntime to a provider/* entry when every dynamically discovered model for that provider should use the same runtime. Exact provider/model runtime policy still wins over the wildcard.
  • Add codeMode: true or codeMode: false to an exact provider/model entry to override Apus Code Mode activation. Omit it to inherit the global tools.codeMode default, including "auto"; agent-specific activation settings take precedence. This changes neither runtime selection nor Codex native Code Mode. The Control UI model editor offers Default, On, and Off alongside runtime settings. See per-model Code Mode for precedence and an example.
  • Safe metadata edits: use apus config set agents.defaults.models '<json>' --strict-json --merge to add entries. config set refuses replacements that would remove existing entries unless you pass --replace.

• modelPolicy.allow: explicit override allowlist. Accepts aliases, exact provider/model refs, and trailing prefix wildcards such as openai/* or clawrouter/anthropic/*. Omit it or use [] to allow any model. agents.entries.*.modelPolicy.allow replaces the default policy for that agent; an explicit empty list opts that agent into allow-any.

  • Provider-scoped configure/onboarding flows merge selected provider models into this map and preserve unrelated providers already configured.
  • For direct Anthropic models using API-key auth, set params.anthropicServerCompaction: true to enable server-side compaction. Use params.anthropicCompactThreshold to override the input-token trigger; the default is max(50000, floor(contextWindow * 0.7)), and lower configured values clamp to 50000. OAuth/subscription and non-direct endpoints are excluded. See Anthropic server-side compaction.
  • For store-capable direct OpenAI Responses models, server-side compaction is enabled automatically and the same effective threshold delays local preflight compaction. Use params.responsesServerCompaction: false to stop injecting context_management, or params.responsesCompactThreshold to override the default of 70% of the resolved context window (80,000 when unavailable). ChatGPT OAuth, custom proxies, and routes with compat.supportsStore: false do not enable this path. See OpenAI server-side compaction.

• params: global default provider parameters applied to all models. Set at agents.defaults.params (e.g. { cacheRetention: "long" }).

• params merge precedence (config): agents.defaults.params (global base), then agents.defaults.models["provider/model"].params (shared per-model), then agents.entries.*.models["provider/model"].params (agent-specific per-model), then agents.entries.*.params (agent-wide). Later layers override by key. See Prompt Caching for details.

• Model params.thinking sets that model's thinking default; an agent-specific model entry overrides the shared entry. Per-message and session choices, followed by the agent's thinkingDefault, take precedence over either model setting. See thinking resolution order.

• models.providers.openrouter.params.provider: OpenRouter-wide default provider-routing policy. Apus forwards this to OpenRouter's request provider object; per-model agents.defaults.models["openrouter/<model>"].params.provider and agent params override by key. See OpenRouter provider routing.

• params.extra_body/params.extraBody: advanced pass-through JSON merged into api: "openai-completions" request bodies for OpenAI-compatible proxies. If it collides with generated request keys, the extra body wins; non-native completions routes still strip OpenAI-only store afterward.

• params.chat_template_kwargs: vLLM/OpenAI-compatible chat-template arguments merged into top-level api: "openai-completions" request bodies. For vllm/nemotron-3-* with thinking off, the bundled vLLM plugin automatically sends enable_thinking: false and force_nonempty_content: true; explicit chat_template_kwargs override generated defaults, and extra_body.chat_template_kwargs still has final precedence. Configured vLLM Qwen and Nemotron thinking models expose binary /think choices (off, on) instead of the multi-level effort ladder.

• compat.thinkingFormat: OpenAI-compatible thinking payload style. Use "together" for Together-style reasoning.enabled, "qwen" for Qwen-style top-level enable_thinking, or "qwen-chat-template" for chat_template_kwargs.enable_thinking on Qwen-family backends that support request-level chat-template kwargs, such as vLLM. Apus maps disabled thinking to false and enabled thinking to true, and configured vLLM Qwen models expose binary /think choices for these formats.

• compat.supportedReasoningEfforts: per-model OpenAI-compatible reasoning effort list. Include "xhigh" for custom endpoints that truly accept it; Apus then exposes /think xhigh in command menus, Gateway session rows, session patch validation, agent CLI validation, and llm-task validation for that configured provider/model. Use compat.reasoningEffortMap when the backend wants a provider-specific value for a canonical level.

• params.preserveThinking: Z.AI-only opt-in for preserved thinking. When enabled and thinking is on, Apus sends thinking.clear_thinking: false and replays prior reasoning_content; see Z.AI thinking and preserved thinking.

• localService: optional provider-level process manager for local/self-hosted model servers. When the selected model belongs to that provider, Apus checks healthUrl (or baseUrl + "/models"), starts command with args if the endpoint is down, waits up to readyTimeoutMs, then sends the model request. command must be an absolute path. idleStopMs: 0 keeps the process alive until Apus exits; a positive value stops the Apus-spawned process after that many idle milliseconds. See Local model services.

• Runtime policy belongs on providers or models, not on agents.defaults. Use models.providers.<provider>.agentRuntime for provider-wide rules or agents.defaults.models["provider/model"].agentRuntime / agents.entries.*.models["provider/model"].agentRuntime for model-specific rules. A provider/model prefix alone never selects a harness. With runtime unset or auto, OpenAI may select Codex implicitly only for an exact official HTTPS Platform Responses or ChatGPT Responses route with no authored request override. See OpenAI implicit agent runtime.

• Config writers that mutate these fields (for example /models set, /models set-image, and fallback add/remove commands) save canonical object form and preserve existing fallback lists when possible.

• maxConcurrent: max parallel agent runs across sessions (each session still serialized). By default, Apus uses max(8, available CPU parallelism * 4), based on os.availableParallelism() with os.cpus().length as a fallback. This allows 32 runs on 8 available CPUs and 192 on 48. An explicit value overrides the CPU-derived default, including after upgrades.

{
  agents: { defaults: { modelSelectionScope: "session" } },
}

Agent and global updates can affect new and existing unpinned sessions and cron jobs that inherit the changed default on their next run. They do not rewrite other sessions' explicit model selections. /model default -s clears only the current session's selection so it inherits the current configured default. Selecting the effective configured default clears the session model pin, but agent/global scope still requests a write to the configured target. See Model selection in chat for persistence, permissions, and picker behavior.