Configure Providers, Agents, and Models

This page collects the configuration reference for this OpenCode setup so you can update providers, agents, and models without re-reading the entire docs section.

If you are still deciding whether to use a direct provider or a proxy layer, read Choose between opencode, opencode-go, and cliproxyapi first.

1. Configure oh-my-openagent

Create ~/.config/opencode/oh-my-opencode.json.

Even though the project is now called oh-my-openagent, current config examples still commonly use the legacy oh-my-opencode filename and plugin key.

This file defines:

• named agents like hephaestus, oracle, explore, and librarian
• categories such as quick, deep, and visual-engineering
• model routing and fallback behavior

Recommended structure

Use your existing config as the baseline. The important pattern is:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/dev/assets/oh-my-opencode.schema.json",
  "agents": {
    "hephaestus": {
      "model": "openai/gpt-5.3-codex",
      "variant": "medium"
    },
    "oracle": {
      "model": "openai/gpt-5.4",
      "variant": "high"
    },
    "explore": {
      "model": "opencode/minimax-m2.5-free"
    }
  },
  "categories": {
    "deep": {
      "model": "openai/gpt-5.3-codex",
      "variant": "medium"
    },
    "visual-engineering": {
      "model": "opencode-go/kimi-k2.5"
    }
  }
}

Why this split is useful

• Agents describe named roles
• Categories describe workload classes
• Fallback models reduce session failure when one model is unavailable

Expanded example

If you want a richer starting point, this expanded oh-my-opencode.json example mirrors the current setup more closely:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/dev/assets/oh-my-opencode.schema.json",
  "agents": {
    "sisyphus": {
      "model": "opencode-go/kimi-k2.5",
      "fallback_models": ["opencode-go/glm-5"]
    },
    "hephaestus": {
      "model": "openai/gpt-5.3-codex",
      "variant": "medium"
    },
    "oracle": {
      "model": "openai/gpt-5.4",
      "variant": "high"
    },
    "librarian": {
      "model": "opencode/minimax-m2.5-free",
      "fallback_models": ["opencode-go/minimax-m2.5"]
    },
    "explore": {
      "model": "opencode/minimax-m2.5-free",
      "fallback_models": [
        "opencode-go/minimax-m2.5",
        "opencode/gpt-5-nano",
        "openai/gpt-5-nano",
        "opencode/claude-haiku-4-5"
      ]
    },
    "multimodal-looker": {
      "model": "gpt-5.3-codex",
      "variant": "medium",
      "fallback_models": [
        "opencode-go/kimi-k2.5",
        "openai/gpt-5-nano",
        "opencode/gpt-5-nano"
      ]
    },
    "prometheus": {
      "model": "openai/gpt-5.4",
      "variant": "high",
      "fallback_models": ["openai/gpt-5.4"]
    },
    "metis": {
      "model": "opencode-go/kimi-k2.5",
      "fallback_models": ["openai/gpt-5.4"]
    },
    "momus": {
      "model": "openai/gpt-5.4",
      "variant": "xhigh"
    },
    "atlas": {
      "model": "opencode-go/kimi-k2.5",
      "fallback_models": ["openai/gpt-5.4"]
    }
  },
  "categories": {
    "visual-engineering": {
      "model": "opencode-go/kimi-k2.5"
    },
    "ultrabrain": {
      "model": "openai/gpt-5.3-codex",
      "variant": "xhigh"
    },
    "deep": {
      "model": "openai/gpt-5.3-codex",
      "variant": "medium"
    },
    "artistry": {
      "model": "opencode-go/kimi-k2.5"
    },
    "quick": {
      "model": "opencode/minimax-m2.5-free",
      "fallback_models": ["opencode-go/minimax-m2.5"]
    },
    "unspecified-low": {
      "model": "opencode/minimax-m2.5-free",
      "fallback_models": ["opencode-go/minimax-m2.5"]
    },
    "unspecified-high": {
      "model": "openai/gpt-5.4",
      "variant": "high"
    },
    "writing": {
      "model": "opencode/minimax-m2.5-free",
      "fallback_models": ["opencode-go/minimax-m2.5"]
    }
  }
}

2. Connect OpenCode to CLIProxyAPI

Create ~/.config/opencode/opencode.json.

This section shows the proxy-based path used in this repository. If you use opencode or opencode-go directly, the provider block changes, but the surrounding ideas about models, variants, MCP, and plugins remain similar.

The important pieces are:

• provider.cliproxyapi.options.baseURL
• provider.cliproxyapi.options.apiKey
• plugin: ["oh-my-opencode"]
• mcp definitions for external tools
• model variants for reasoning effort

Minimal provider example

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask"
  },
  "plugin": ["oh-my-opencode"],
  "provider": {
    "cliproxyapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CLIProxyAPI",
      "options": {
        "baseURL": "http://localhost:8317/v1",
        "apiKey": "your-api-key-1"
      },
      "models": {
        "gpt-5.4": {
          "id": "gpt-5.4",
          "name": "GPT-5.4",
          "reasoning": true,
          "variants": {
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"},
            "xhigh": {"reasoningEffort": "xhigh"}
          }
        }
      }
    }
  }
}

Full provider example

If you want the current repo-style model matrix instead of a minimal example, use this fuller pattern:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask"
  },
  "autoupdate": true,
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"],
      "enabled": true
    },
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp@latest"],
      "enabled": true
    },
    "react-grab-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@react-grab/mcp", "--stdio"]
    }
  },
  "plugin": ["oh-my-opencode"],
  "provider": {
    "cliproxyapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CLIProxyAPI",
      "options": {
        "baseURL": "http://localhost:8317/v1",
        "apiKey": "your-api-key-1"
      },
      "models": {
        "gpt-5": {
          "id": "gpt-5",
          "name": "GPT-5",
          "reasoning": true,
          "cost": {"input": 2.0, "output": 8.0},
          "limit": {"context": 400000, "output": 128000},
          "variants": {
            "minimal": {"reasoningEffort": "minimal"},
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"}
          }
        },
        "gpt-5-codex": {
          "id": "gpt-5-codex",
          "name": "GPT-5 Codex",
          "reasoning": true,
          "cost": {"input": 2.0, "output": 8.0},
          "limit": {"context": 400000, "output": 128000},
          "variants": {
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"}
          }
        },
        "gpt-5-codex-mini": {
          "id": "gpt-5-codex-mini",
          "name": "GPT-5 Codex Mini",
          "reasoning": true,
          "cost": {"input": 0.5, "output": 2.0},
          "limit": {"context": 400000, "output": 128000},
          "variants": {
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"}
          }
        },
        "gpt-5.1": {
          "id": "gpt-5.1",
          "name": "GPT-5.1",
          "reasoning": true,
          "cost": {"input": 2.5, "output": 10.0},
          "limit": {"context": 400000, "output": 128000},
          "variants": {
            "none": {"reasoningEffort": "none"},
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"}
          }
        },
        "gpt-5.1-codex": {
          "id": "gpt-5.1-codex",
          "name": "GPT-5.1 Codex",
          "reasoning": true,
          "cost": {"input": 2.5, "output": 10.0},
          "limit": {"context": 400000, "output": 128000},
          "variants": {
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"}
          }
        },
        "gpt-5.1-codex-mini": {
          "id": "gpt-5.1-codex-mini",
          "name": "GPT-5.1 Codex Mini",
          "reasoning": true,
          "cost": {"input": 0.75, "output": 3.0},
          "limit": {"context": 400000, "output": 128000},
          "variants": {
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"}
          }
        },
        "gpt-5.1-codex-max": {
          "id": "gpt-5.1-codex-max",
          "name": "GPT-5.1 Codex Max",
          "reasoning": true,
          "cost": {"input": 5.0, "output": 20.0},
          "limit": {"context": 400000, "output": 128000},
          "variants": {
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"},
            "xhigh": {"reasoningEffort": "xhigh"}
          }
        },
        "gpt-5.2": {
          "id": "gpt-5.2",
          "name": "GPT-5.2",
          "reasoning": true,
          "cost": {"input": 3.0, "output": 12.0},
          "limit": {"context": 400000, "output": 128000},
          "variants": {
            "none": {"reasoningEffort": "none"},
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"},
            "xhigh": {"reasoningEffort": "xhigh"}
          }
        },
        "gpt-5.2-codex": {
          "id": "gpt-5.2-codex",
          "name": "GPT-5.2 Codex",
          "reasoning": true,
          "cost": {"input": 3.0, "output": 12.0},
          "limit": {"context": 400000, "output": 128000},
          "variants": {
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"},
            "xhigh": {"reasoningEffort": "xhigh"}
          }
        },
        "gpt-5.3-codex": {
          "id": "gpt-5.3-codex",
          "name": "GPT-5.3 Codex",
          "reasoning": true,
          "cost": {"input": 3.0, "output": 12.0},
          "limit": {"context": 400000, "output": 128000},
          "variants": {
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"},
            "xhigh": {"reasoningEffort": "xhigh"}
          }
        },
        "gpt-5.3-codex-spark": {
          "id": "gpt-5.3-codex-spark",
          "name": "GPT-5.3 Codex Spark",
          "reasoning": true,
          "cost": {"input": 1.0, "output": 4.0},
          "limit": {"context": 128000, "output": 128000},
          "variants": {
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"},
            "xhigh": {"reasoningEffort": "xhigh"}
          }
        },
        "gpt-5.4": {
          "id": "gpt-5.4",
          "name": "GPT-5.4",
          "reasoning": true,
          "cost": {"input": 3.0, "output": 12.0},
          "limit": {"context": 1050000, "output": 128000},
          "variants": {
            "low": {"reasoningEffort": "low"},
            "medium": {"reasoningEffort": "medium"},
            "high": {"reasoningEffort": "high"},
            "xhigh": {"reasoningEffort": "xhigh"}
          }
        }
      }
    }
  }
}

3. Add MCP servers

The current setup uses these MCP integrations:

{
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"],
      "enabled": true
    },
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp@latest"],
      "enabled": true
    },
    "react-grab-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@react-grab/mcp", "--stdio"]
    }
  }
}

This keeps the core setup small, then layers tools on top through MCP.

4. Key configuration notes

Field	Purpose
npm	Uses @ai-sdk/openai-compatible for OpenAI-compatible endpoints
options.baseURL	Points to CLIProxyAPI at http://localhost:8317/v1
options.apiKey	Must match one of the keys in cliproxyapi.conf
reasoning: true	Enables the thinking and reasoning variant toggle in the TUI
variants	Defines selectable reasoning effort levels per model

5. Direct providers vs proxy providers

• Direct providers such as opencode and opencode-go keep the setup simpler when you do not need a local proxy
• Proxy providers such as cliproxyapi are useful when you want one stable local endpoint and multiple upstream Codex accounts behind it

6. Model selection strategy

The current setup favors:

• GPT-5.4 for high-context and high-reasoning tasks
• GPT-5.3 Codex for coding-heavy tasks
• lighter fallback models for exploration and low-cost background work

Use /models inside OpenCode to switch models during a session.

7. Keep the full reference nearby

The model matrix now lives in this docs section under Launch OpenCode and use model variants.

Next step

Continue to Set up workflows, MCP tools, and project rules.