Agent-Model Matching Guide

For agents and users: Why each agent needs a specific model — and how to customize without breaking things.

🚨 READ THIS FIRST — SISYPHUS IS NOT A "RUN IT ON ANY MODEL" SYSTEM 🚨

STOP. BEFORE YOU POINT SISYPHUS AT SOME OTHER MODEL, READ EVERY WORD BELOW. THIS IS THE SINGLE MOST IGNORED THING IN THIS WHOLE GUIDE.

SISYPHUS HAS ONLY EVER BEEN TESTED AND VERIFIED ON THE EXACT MODELS LISTED IN THIS DOCUMENT — AND NOTHING, NOTHING, ELSE. The supported set is narrow on purpose:

• Claude family: Fable 5 · Opus 4.8 · Opus 4.7 · Sonnet 4.6
• Kimi: K2.7 · K2.6 · K2.5
• GLM: 5 / 5.1 (acceptable — slightly looser on the long nested workflows)
• GPT: 5.4 / 5.5 (dedicated GPT prompt path exists — supported, but still NOT the recommended default for the orchestrator)

IF A MODEL IS NOT ON THAT LIST, IT IS 100% UNTESTED AND 100% UNVERIFIED WITH SISYPHUS. It may not work at all. It may look like it works and then fall apart three tool-calls later. AND IF IT SOMEHOW WORKS FOR YOU — THAT IS A LITERAL MIRACLE. IT IS NOT A SUPPORTED CONFIGURATION, IT IS NOT BLESSED, AND IT IS NOT A PROMISE THAT IT WILL STILL WORK TOMORROW.

EVERY SINGLE PROMPT CHANGE TO SISYPHUS IS WRITTEN, TUNED, AND REGRESSION-CHECKED AGAINST THE MODELS ABOVE — AND ONLY THOSE MODELS. Nobody is watching how an off-list model behaves. The consequences are not subtle:

• AN UNLISTED MODEL CAN BREAK AT THE VERY NEXT PATCH, WITH ZERO WARNING. A prompt tweak that helps Claude/Kimi can silently shatter whatever fragile thing was holding your off-list model together — and we will never notice, because we are not testing it. Do not file it as a bug. It was never working on purpose.
• A PROMPT CANNOT FIX A MODEL. Models have hard, intrinsic characteristics. No amount of prompt-carving makes a model do what it fundamentally cannot do. If a model is the wrong brain for orchestration, it stays the wrong brain — forever, no matter how perfectly the prompt is shaped. We have ground prompts down to the bone; the model that can't, still can't.

SO, GENUINELY AND SINCERELY, FROM THE BOTTOM OF OUR HEARTS: RUNNING SISYPHUS ON ANY MODEL NOT LISTED HERE IS STRONGLY, EMPHATICALLY, DESPERATELY NOT RECOMMENDED. Do it anyway and you are fully on your own — and you should expect it to break.

MiniMax / Qwen / MiMo / DeepSeek as Sisyphus — JUST DON'T

We have NOT found any way to make MiniMax, Qwen, MiMo, or DeepSeek work acceptably as Sisyphus. We tried. They do not hold up under Sisyphus's nested todo + delegation + orchestration prompt. This is not a "tune it more" situation — see the rule above: a prompt cannot fix a model.

MiniMax and Qwen in particular are so bad in the Sisyphus role that we would almost forbid it outright. Treat "Sisyphus on MiniMax" and "Sisyphus on Qwen" as configurations you should simply never reach for. (These models still have legitimate jobs elsewhere — MiniMax for fast utility fallback, Qwen for visual work, both documented below — just NEVER as the orchestrator.)

The Core Insight: Models Are Developers

Think of AI models as developers on a team. Each has a different brain, different personality, different strengths. A model isn't just "smarter" or "dumber." It thinks differently. Give the same instruction to Claude and GPT, and they'll interpret it in fundamentally different ways.

This isn't a bug. It's the foundation of the entire system.

Oh My OpenAgent assigns each agent a model that matches its working style — like building a team where each person is in the role that fits their personality.

Sisyphus: The Sociable Lead

Sisyphus is the developer who knows everyone, goes everywhere, and gets things done through communication and coordination. Talks to other agents, understands context across the whole codebase, delegates work intelligently, and codes well too. But deep, purely technical problems? He'll struggle a bit.

This is why Sisyphus uses Claude / Kimi / GLM. These models excel at:

• Following complex, multi-step instructions (Sisyphus's prompt is ~1,100 lines)
• Maintaining conversation flow across many tool calls
• Understanding nuanced delegation and orchestration patterns
• Producing well-structured, communicative output

Using Sisyphus with older GPT models would be like taking your best project manager — the one who coordinates everyone, runs standups, and keeps the whole team aligned — and sticking them in a room alone to debug a race condition. Wrong fit. GPT-5.4 and GPT-5.5 now have dedicated Sisyphus prompt paths, but GPT is still not the default recommendation for the orchestrator.

⚠️ Sisyphus is ONLY tested on Claude (Fable 5 / Opus 4.8 / 4.7 / Sonnet 4.6), Kimi (K2.7 / K2.6 / K2.5), GLM (5 / 5.1), and GPT (5.4 / 5.5). Anything else is untested, unsupported, and can break without warning. MiniMax and Qwen as Sisyphus are strongly discouraged to the point we'd almost forbid it. Read the 🚨 READ THIS FIRST warning at the very top of this guide before you override the orchestrator's model.

Hephaestus: The Deep Specialist

Hephaestus is the developer who stays in their room coding all day. Doesn't talk much. Might seem socially awkward. But give them a hard technical problem and they'll emerge three hours later with a solution nobody else could have found.

This is why Hephaestus uses GPT-5.5. GPT-5.5 is built for exactly this:

• Deep, autonomous exploration without hand-holding
• Multi-file reasoning across complex codebases
• Principle-driven execution (give a goal, not a recipe)
• Working independently for extended periods

Using Hephaestus with GLM or Kimi would be like assigning your most communicative, sociable developer to sit alone and do nothing but deep technical work. They'd get it done eventually, but they wouldn't shine — you'd be wasting exactly the skills that make them valuable.

The Takeaway

Every agent's prompt is tuned to match its model's personality. When you change the model, you change the brain — and the same instructions get understood completely differently. Model matching isn't about "better" or "worse." It's about fit.

How Claude and GPT Think Differently

This matters for understanding why some agents support both model families while others don't.

Claude responds to mechanics-driven prompts — detailed checklists, templates, step-by-step procedures. More rules = more compliance. You can write a 1,100-line prompt with nested workflows and Claude will follow every step.

GPT (especially 5.2+) responds to principle-driven prompts — concise principles, XML structure, explicit decision criteria. More rules = more contradiction surface = more drift. GPT works best when you state the goal and let it figure out the mechanics.

Real example: Prometheus's Claude prompt is ~1,100 lines across 7 files. The GPT prompt achieves the same behavior with 3 principles in ~121 lines. Same outcome, completely different approach.

Agents that support both families (Prometheus, Atlas) auto-detect your model at runtime and switch prompts via isGptModel(). You don't have to think about it.

Step 1 — Check What's Actually Available

Before configuring anything, see what your current system can run.

List all available models

opencode models

This prints every provider/model combination you can address right now. Providers are derived from your connected auth + the models.dev catalogue.

Opencode sorts the output so opencode* providers appear first — that's intentional, not cosmetic.

List connected providers

opencode auth list

Shows which providers you've already logged into.

If the model you want isn't listed

You need to log in to that provider:

opencode auth login

The interactive picker prioritizes providers in this order:

You can also skip the picker: opencode auth login --provider opencode-go.

Verify what oh-my-openagent will actually use

bunx oh-my-opencode doctor

This shows the effective model resolution for every agent and category based on your current auth state. If an agent says "system-default" instead of a real fallback, that's a signal you're missing providers from its chain.

Step 2 — The Recommended Stack

You don't need every provider. You need the right two.

The Optimal Combination: OpenCode Go + OpenAI Plus/Pro

~$30/month total. Beats direct Anthropic + OpenAI + Google subscriptions (~$60+/month) on both cost and coverage.

Why this specific combination

1. Hephaestus requires GPT-5.5. It has no Claude-family fallback. ChatGPT Plus/Pro or OpenAI API access is the cheapest real path.
2. OpenCode Go covers the orchestration and creative surface. Kimi K2.5/2.6 behaves like Claude for Sisyphus/Atlas. GLM-5 fills the long tail. Qwen handles visual tasks when Gemini isn't available.
3. No single provider can cover everything. Anthropic-only setups break Hephaestus. OpenAI-only setups degrade Sisyphus. You need at least one from each family.

What if you already have a Claude subscription?

Add --claude=max20 (or yes) on install. The Claude chain default (Opus 4.7, snapshot-backed) activates for Sisyphus/Prometheus/Atlas and you still get the OpenCode Go fallbacks for free. Pin claude-opus-4-8 or claude-fable-5 to run the current top Claude with its tuned prompt. Best-in-class orchestration + budget safety net.

What if you have zero subscriptions?

OpenCode Go alone gets Sisyphus/Atlas/Oracle/Librarian/Explore working. Hephaestus won't activate without GPT access, so you lose autonomous deep work. Consider adding ChatGPT Plus as soon as you can.

Step 3 — Model Family Alternatives (Priority Order)

When the "native" model isn't available, oh-my-openagent walks each agent's fallback chain until something connects. The chains are hardcoded in packages/omo-opencode/src/shared/model-requirements.ts. There is no single global priority list. Every agent and category has its own chain.

There are two separate systems:

• model-fallback: proactive resolution in chat.params using hardcoded AGENT_MODEL_REQUIREMENTS and CATEGORY_MODEL_REQUIREMENTS
• runtime-fallback: reactive recovery from session.error, configurable per category/agent in runtime-fallback hooks

Current top tier vs the auto-resolution chain

Two things move at different speeds, and the difference explains why "Opus 4.7" still appears as a default below:

• The current top models are Claude Fable 5 and Opus 4.8, and Kimi K2.7 — each with a dedicated per-agent prompt (the orchestrators auto-detect the model and switch). Pin one in your config — "anthropic/claude-opus-4-8", "anthropic/claude-fable-5", "opencode-go/kimi-k2.7" — to run it with its tuned prompt.
• The auto-resolution fallback chains below still lead with Opus 4.7 and Kimi K2.6. That is intentional, not stale: the chains only auto-select models the bundled capability snapshot is built against, so variant and context-window resolution stay correct. They promote Opus 4.8 / K2.7 to chain defaults once those land in the model catalog; until then you opt into the newer models — and their prompts — by naming them explicitly.

So an "Opus 4.7 (max)" entry in the chains below is the snapshot-backed floor, not a recommendation to prefer 4.7 over 4.8.

Claude Family (communicative, instruction-following)

Used by: Sisyphus, Atlas, Sisyphus-Junior, Metis (Claude path), Prometheus (Claude path), unspecified-low, unspecified-high.

Kimi ≻ GLM. Kimi (K2.7 newest, then K2.6/K2.5) holds up under Sisyphus's nested todo+delegation prompts better than GLM. Use Kimi whenever both are available.

GPT Family (principle-driven, autonomous)

Used by: Hephaestus, Oracle, Momus, deep, ultrabrain, quick, Prometheus (GPT path), Atlas (GPT path).

DeepSeek ≻≻ MiniMax. DeepSeek retains GPT's autonomous exploration character. MiniMax loses coherence on multi-step deep work. MiniMax is fine for grep-style utility agents, nothing more.

Gemini Family (visual, different reasoning style)

Used by: visual-engineering, artistry, Oracle (visual fallback), Multimodal-Looker.

No GLM/Kimi here. They're not Gemini substitutes for visual work. Use Qwen.

Cheat Sheet: Substitution Rules

Agent Profiles

Exact runtime chains from packages/omo-opencode/src/shared/model-requirements.ts.

Communicators → Claude / Kimi / GLM

These agents have Claude-optimized prompts — long, detailed, mechanics-driven. They need models that reliably follow complex, multi-layered instructions.

Dual-Prompt Agents → Claude preferred, GPT supported

These agents ship separate prompts for Claude and GPT families. They auto-detect your model and switch at runtime.

Deep Specialists → GPT

These agents are built for GPT's principle-driven style. Their prompts assume autonomous, goal-oriented execution. Don't override to Claude.

Utility Runners → Speed over Intelligence

These agents do grep, search, and retrieval. They intentionally use the fastest, cheapest models available. Don't "upgrade" them to Opus — that's hiring a senior engineer to file paperwork.

Model Families

Claude Family

Communicative, instruction-following, structured output. Best for agents that need to follow complex multi-step prompts. The orchestrator agents (Sisyphus, Sisyphus-Junior, Prometheus, Atlas, Metis) auto-detect the active model and switch to a prompt tuned for it. All five now carry a dedicated Kimi K2.7 prompt; Sisyphus and Prometheus additionally carry per-version Claude variants for Fable 5, Opus 4.8, and Opus 4.7.

GPT Family

Principle-driven, explicit reasoning, deep technical capability. Best for agents that work autonomously on complex problems.

Other Models

OpenCode Go

A premium subscription tier ($10/month) that provides reliable access to Chinese frontier models through OpenCode's infrastructure.

Available Models:

When It Gets Used:

OpenCode Go models appear throughout the fallback chains as intermediate options. Depending on the agent, they can sit before GPT, after GPT, or act as the last structured-model fallback before cheaper utility paths.

Go-Only Scenarios:

Some model identifiers in fallback chains are provider-specific aliases. For example, k2p5 resolves through kimi-for-coding, while glm-5 can resolve through zai-coding-plan, opencode, or vercel depending on availability.

About Free-Tier Fallbacks

You may see model names like kimi-k2.5-free, minimax-m3, minimax-m2.7, minimax-m2.7-highspeed, or big-pickle (GLM 4.6) in the source code or logs. These are provider-specific or speed-optimized entries in fallback chains.

You don't need to configure them. The system includes them so it degrades gracefully when you don't have every paid subscription. If you have the paid version, the paid version is always preferred.

Task Categories

When agents delegate work, they don't pick a model name — they pick a category. The category maps to the right model automatically.

See the Orchestration System Guide for how agents dispatch tasks to categories.

Vercel AI Gateway fallback coverage

packages/omo-opencode/src/shared/model-requirements.ts includes vercel on nearly every gateway-compatible fallback entry across both agent and category chains. Treat it as a universal extra provider path for the listed model IDs, not as a different model family.

Customization

Example A — Recommended Stack (OpenCode Go + OpenAI Plus/Pro)

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",

  "agents": {
    // Sisyphus: Kimi K2.7 is the top alternative to Claude for orchestration
    "sisyphus": {
      "model": "opencode-go/kimi-k2.7",
      "ultrawork": { "model": "opencode-go/kimi-k2.7" },
    },

    // Hephaestus: needs GPT. ChatGPT Plus gets you here.
    "hephaestus": { "model": "openai/gpt-5.5", "variant": "medium" },

    // Architecture consultation: GPT or Claude Opus
    "oracle": { "model": "openai/gpt-5.5", "variant": "high" },

    // Prometheus inherits Sisyphus behavior
    "prometheus": { "model": "opencode-go/kimi-k2.7" },

    // Atlas also communicative — Kimi works great
    "atlas": { "model": "opencode-go/kimi-k2.7" },

    // Utility agents stay cheap
    "explore": { "model": "opencode-go/qwen3.5-plus" },
    "librarian": { "model": "opencode-go/qwen3.5-plus" },
  },

  "categories": {
    "visual-engineering": { "model": "opencode-go/qwen3.6-plus" },  // Qwen as Gemini alt
    "deep": { "model": "openai/gpt-5.5", "variant": "medium" },
    "ultrabrain": { "model": "openai/gpt-5.5", "variant": "xhigh" },
    "quick": { "model": "openai/gpt-5.4-mini" },
    "unspecified-low": { "model": "opencode-go/kimi-k2.7" },
    "unspecified-high": { "model": "opencode-go/kimi-k2.7" },
    "writing": { "model": "opencode-go/kimi-k2.7" },
  },

  "background_task": {
    "providerConcurrency": {
      "openai": 3,
      "opencode-go": 10,
    },
  },
}

Example B — All Native (Anthropic + OpenAI + Google)

Highest quality, highest cost. No surprises.

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-8",
      "variant": "max",
    },
    "hephaestus": { "model": "openai/gpt-5.5", "variant": "medium" },
    "oracle": { "model": "openai/gpt-5.5", "variant": "high" },
  },
  "categories": {
    "visual-engineering": { "model": "google/gemini-3.1-pro", "variant": "high" },
    "deep": { "model": "openai/gpt-5.5", "variant": "medium" },
    "unspecified-high": { "model": "anthropic/claude-opus-4-8", "variant": "max" },
  },
}

Example C — OpenCode Go Only (Budget, No GPT)

Cheapest full-stack path. Hephaestus won't activate — accept that trade-off.

{
  "agents": {
    "sisyphus": { "model": "opencode-go/kimi-k2.7" },
    "atlas": { "model": "opencode-go/kimi-k2.7" },
    // Omit hephaestus entirely; it needs GPT.
    "oracle": { "model": "opencode-go/glm-5.1" },  // Degraded but functional
    "explore": { "model": "opencode-go/qwen3.5-plus" },
    "librarian": { "model": "opencode-go/qwen3.5-plus" },
  },
  "categories": {
    "visual-engineering": { "model": "opencode-go/qwen3.6-plus" },
    "deep": { "model": "opencode-go/kimi-k2.7" },  // Not ideal — Kimi isn't GPT, but best available
    "unspecified-high": { "model": "opencode-go/kimi-k2.7" },
    "unspecified-low": { "model": "opencode-go/kimi-k2.7" },
    "quick": { "model": "opencode-go/minimax-m2.7" },
    "writing": { "model": "opencode-go/kimi-k2.7" },
  },
}

Example D — Adding DeepSeek as GPT Alternative

If you have OpenRouter and want DeepSeek in the chain when GPT is unavailable:

{
  "agents": {
    "oracle": {
      "model": "openai/gpt-5.5",
      "variant": "high",
      "fallback_models": [
        "anthropic/claude-opus-4-8",
        { "model": "openrouter/deepseek/deepseek-v3.2", "temperature": 0.7 },
        "opencode-go/glm-5.1",
      ],
    },
  },
}

fallback_models accepts a mix of plain model strings and per-fallback objects with variant, reasoningEffort, temperature, top_p, maxTokens, thinking.

Safe vs Dangerous Overrides

Safe — same personality type:

• Sisyphus: Opus → Sonnet, Kimi K2.5/2.6, GLM 5 (all communicative models)
• Prometheus: Opus → GPT-5.5 (auto-switches to the GPT prompt)
• Atlas: Claude Sonnet 4.6 → Kimi K2.6 → GPT-5.5 (auto-switches to the GPT prompt)

Dangerous — personality mismatch:

• Sisyphus → ANY model not on the tested list: The supported set is Claude (Fable 5 / Opus 4.8 / 4.7 / Sonnet 4.6), Kimi (K2.7 / K2.6 / K2.5), GLM (5 / 5.1), GPT (5.4 / 5.5). Everything else is untested and can break at the very next patch. A prompt cannot fix a model — if it doesn't fit, no tuning makes it fit. See the 🚨 READ THIS FIRST warning at the very top of this guide.
• Sisyphus → MiniMax / Qwen: Strongly discouraged to the point of "almost forbidden." Neither holds up under the orchestration prompt. Never use them as the orchestrator.
• Sisyphus → MiMo / DeepSeek: No working configuration found. Untested and unsupported as the orchestrator.
• Sisyphus → older GPT models: Still a bad fit. GPT-5.4 and GPT-5.5 are the only dedicated GPT prompt paths.
• Hephaestus → Claude: Built for Codex's autonomous style. Claude can't replicate this.
• Hephaestus → MiniMax: MiniMax loses coherence on multi-step deep work. Never do this.
• Oracle → MiniMax: Same reason. Oracle needs sustained reasoning; MiniMax drifts.
• Explore → Opus: Massive cost waste. Explore needs speed, not intelligence.
• Librarian → Opus: Same. Doc search doesn't need Opus-level reasoning.
• visual-engineering → Kimi/GLM: Wrong reasoning style. Use Qwen if Gemini is unavailable, not Claude-likes.

How Model Resolution Works

Each agent has a fallback chain. The system tries models in priority order until it finds one available through your connected providers. You don't need to configure providers per model. Just authenticate (opencode auth login) and the system figures out which models are available and where.

Resolution pipeline (from packages/omo-opencode/src/shared/model-resolution-pipeline.ts):

1. Override          → User's explicit config or UI-selected model (primary agents only)
2. Category default  → From category config (when agent has category set)
3. User fallback_models → Configured strings/objects tried before hardcoded chain
4. Provider fallback → AGENT_MODEL_REQUIREMENTS / CATEGORY_MODEL_REQUIREMENTS
5. System default    → Ultimate safety net

Core-agent tab cycling is deterministic via injected runtime order field. The fixed priority order is Sisyphus (order: 0), Hephaestus (order: 1), Prometheus (order: 2), and Atlas (order: 3), then the remaining agents follow.

Your explicit configuration always wins. If you set a specific model for an agent, that choice takes precedence even when resolution data is cold.

Variant and reasoningEffort overrides are normalized to model-supported values, so cross-provider overrides degrade gracefully instead of failing hard.

Model capabilities are models.dev-backed, with a refreshable cache and capability diagnostics. Use bunx oh-my-opencode refresh-model-capabilities to update the cache, or configure model_capabilities.auto_refresh_on_start to refresh at startup.

To see which models your agents will actually use, run bunx oh-my-opencode doctor. This shows effective model resolution based on your current authentication and config.

Agent Request → User Override (if configured) → Fallback Chain → System Default

File-Based Prompts

You can load agent system prompts from external files using file:// URLs in the prompt field, or append additional content with prompt_append. The prompt_append field also works on categories.

{
  "agents": {
    "sisyphus": {
      "prompt": "file:///path/to/custom-prompt.md",
    },
    "oracle": {
      "prompt_append": "file:///path/to/additional-context.md",
    },
  },
  "categories": {
    "deep": {
      "prompt_append": "file:///path/to/deep-category-append.md",
    },
  },
}

The file content is loaded at runtime and injected into the agent's system prompt. Supports ~ expansion for home directory and relative file:// paths.

See Also

• Installation Guide — Setup and authentication
• Orchestration System Guide — How agents dispatch tasks to categories
• Configuration Reference — Full config options
• packages/omo-opencode/src/shared/model-requirements.ts — Source of truth for fallback chains