b1008510f8
- Add docs/guide/agent-model-matching.md with TL;DR table, detailed breakdown per agent, configuration examples, decision tree, common pitfalls, and default fallback chains - Update README.md to reference the guide in TOC, Just Install This section, and Features overview
167 lines
4.4 KiB
Markdown
167 lines
4.4 KiB
Markdown
# Agent-Model Matching Guide for Newcomers
|
|
|
|
> **Quick Reference**: Which model to use with which agent for the best results
|
|
|
|
This guide helps you match the right AI model to each oh-my-opencode agent based on real-world usage and testing.
|
|
|
|
---
|
|
|
|
## TL;DR
|
|
|
|
| Agent | Best Models | Avoid |
|
|
|-------|-------------|-------|
|
|
| **Sisyphus** | Claude Opus, Sonnet, Kimi K2.5, GLM 5 | GPT ❌ |
|
|
| **Hephaestus** | GPT-5.3-codex only | Non-GPT ❌ |
|
|
| **Prometheus** | Claude Opus | GPT (untested) |
|
|
| **Atlas** | Claude Opus, GPT-5.2+ | — |
|
|
|
|
---
|
|
|
|
## Detailed Breakdown
|
|
|
|
### Sisyphus (ultraworker)
|
|
**Purpose**: Primary orchestrator for complex multi-step tasks
|
|
|
|
**Recommended Models** (in order of preference):
|
|
1. **Claude Opus-4-6** — The best overall performance
|
|
2. **Claude Sonnet-4-6** — Satisfiable, often better than pure Claude Code + Opus
|
|
3. **Kimi K2.5** — Good for broad tasks, excellent cost-performance
|
|
4. **GLM 5** — Good for various tasks, not as capable on broad tasks as Kimi
|
|
5. **MiniMax** — Budget option when cost matters
|
|
|
|
**⚠️ NEVER USE GPT** — Sisyphus is optimized for Claude-style models and performs poorly on GPT.
|
|
|
|
**Configuration Example**:
|
|
```json
|
|
{
|
|
"agent": {
|
|
"sisyphus": {
|
|
"model": "anthropic/claude-opus-4-6",
|
|
"variant": "max"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Hephaestus (deep worker)
|
|
**Purpose**: Deep coding tasks requiring extensive reasoning
|
|
|
|
**Required Model**: **GPT-5.3-codex** (always)
|
|
|
|
Think of Hephaestus as "Codex on steroids" — it's specifically designed and tuned for GPT models.
|
|
|
|
**⚠️ DO NOT USE** if you don't have GPT access. DeepSeek *might* work but is not officially supported.
|
|
|
|
**Configuration Example**:
|
|
```json
|
|
{
|
|
"agent": {
|
|
"hephaestus": {
|
|
"model": "openai/gpt-5.3-codex",
|
|
"variant": "medium"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Prometheus (planner)
|
|
**Purpose**: Strategic planning and work plan generation
|
|
|
|
**Recommended Model**: **Claude Opus-4-6** (strongly recommended)
|
|
|
|
Prometheus is optimized for Claude's reasoning capabilities. GPT compatibility is not yet tested but may be evaluated in the future.
|
|
|
|
**Configuration Example**:
|
|
```json
|
|
{
|
|
"agent": {
|
|
"plan": {
|
|
"model": "anthropic/claude-opus-4-6",
|
|
"variant": "max"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Atlas (orchestrator)
|
|
**Purpose**: Todo list orchestration and multi-agent coordination
|
|
|
|
**Recommended Models**:
|
|
1. **Claude Opus-4-6** — Best performance (recommended)
|
|
2. **GPT-5.2+** — Good enough, has GPT-optimized prompt
|
|
|
|
Atlas has model-specific prompt detection and will automatically use GPT-optimized instructions when running on GPT models.
|
|
|
|
**Configuration Example**:
|
|
```json
|
|
{
|
|
"agent": {
|
|
"atlas": {
|
|
"model": "anthropic/claude-opus-4-6"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Decision Tree
|
|
|
|
```
|
|
Do you have GPT access?
|
|
├── YES → Use Hephaestus for deep coding, Atlas for orchestration
|
|
└── NO → Use Sisyphus (Claude/Kimi/GLM) for all tasks
|
|
|
|
Need planning/strategy?
|
|
├── YES → Use Prometheus (Claude Opus recommended)
|
|
└── NO → Skip Prometheus, use other agents directly
|
|
|
|
Complex multi-step task?
|
|
├── YES → Use Sisyphus (Claude-family models)
|
|
└── NO → Use category-specific agents or Hephaestus
|
|
```
|
|
|
|
---
|
|
|
|
## Common Pitfalls to Avoid
|
|
|
|
1. **Don't use GPT with Sisyphus** — Performance will be subpar
|
|
2. **Don't use non-GPT with Hephaestus** — It's specifically built for GPT
|
|
3. **Don't force Prometheus on GPT** — It's untested; use Claude for now
|
|
4. **Don't overthink Atlas** — It adapts automatically to your model
|
|
|
|
---
|
|
|
|
## Model Fallback Chains (Default Behavior)
|
|
|
|
The system will automatically fall back through these chains if your preferred model is unavailable:
|
|
|
|
**Sisyphus**: Opus → Kimi K2.5 → GLM 4.7 → Big Pickle
|
|
**Hephaestus**: GPT-5.3-codex only (no fallback)
|
|
**Prometheus**: Opus → Kimi K2.5 → GLM 4.7 → GPT-5.2 → Gemini 3 Pro
|
|
**Atlas**: Kimi K2.5 → GLM 4.7 → Opus → GPT-5.2 → Gemini 3 Pro
|
|
|
|
---
|
|
|
|
## Tips for Newcomers
|
|
|
|
- **Start with Sisyphus + Claude Opus** for general tasks
|
|
- **Use Hephaestus when you need deep reasoning** (requires GPT)
|
|
- **Try GLM 5 or Kimi K2.5** for cost-effective alternatives to Claude
|
|
- **Check the model requirements** in your config to avoid mismatches
|
|
- **Use `variant: "max"` or `variant: "high"`** for best results on capable models
|
|
|
|
---
|
|
|
|
## See Also
|
|
|
|
- [AGENTS.md](../AGENTS.md) — Full agent documentation
|
|
- [configurations.md](./configurations.md) — Configuration reference
|
|
- [orchestration-guide.md](./orchestration-guide.md) — How orchestration works
|