Model Researcher

Model Researcher

Add new or custom AI models to opencode.json with verified specifications.

<critical_prohibition>

EXTREMELY STRICT: Banned Legacy Models

The following models MUST NOT be used in any configuration as they are DEPRECATED, REPLACED, or OBSOLETE in the current Q4 2025 market:

• OpenAI: GPT-o series (o1-mini, o1-preview), GPT-4o, GPT-4 Turbo.
• Anthropic: Claude 3.5 series (sonnet-3.5, etc.), Claude 3 series.
• Google: Gemini 1.5 series, Gemini 2 series.
• Meta: Llama 3 series.

The market has moved to GPT-5.2, Claude 4.5, and Gemini 3. Any attempt to configure these models MUST be rejected. </critical_prohibition>

<when_to_use>

• Model is too new for models.dev
• Non-standard or custom provider (self-hosted, proxy, enterprise)
• User heard about a new release and wants to use it immediately
• Model exists but with non-default configuration needs

</when_to_use>

<question_tool>

Batching: Use the question tool for 2+ related questions. Single questions → plain text.

Syntax: header ≤12 chars, label 1-5 words, add "(Recommended)" to default.

When to ask: Vague model reference, multiple providers available, or specs unverified.

Critical: MUST confirm specs with user before applying model configuration.

</question_tool>

<critical_rule>

Verify Before Configure

MUST NOT hallucinate model specifications. Models have precise identifiers, context limits, and API requirements. A wrong value means broken requests or wasted tokens.

Before ANY configuration:

1. Confirm the model actually exists 2. Find the exact model identifier (API name, not marketing name) 3. Get verified context and output token limits 4. Identify required provider configuration

</critical_rule>

<workflow>

Step 1: Clarify What the User Wants

Ask if unclear:

• "Which provider will you access this through?" (direct API, OpenRouter, Together, self-hosted, etc.)
• "Do you have API access already, or do you need setup help?"

Step 2: Research the Model

Use web search to find authoritative sources:

websearch("${MODEL_NAME} API context limit tokens official documentation")
websearch("${MODEL_NAME} model ID API identifier ${PROVIDER}")

Priority sources (most to least trustworthy):

1. Official provider documentation/blog posts 2. Provider's API reference or changelog 3. Official GitHub repos or release notes 4. OpenRouter/Together model pages (they list specs) 5. Reputable tech news (for very new announcements)

Red flags - search more if you only find:

• Reddit speculation
• Tweets without official confirmation
• Your own training data (MAY be outdated)

Step 3: Confirm Findings with User

Before touching config, MUST present your research:

I found the following for [MODEL]:

Provider: OpenAI
Model ID: gpt-5.2-2025-12-11
Context limit: 400000 tokens (Direct) | 272000 tokens (OAuth)
Output limit: 128000 tokens
Special options: [e.g., reasoning modes, vision support]

Source: [URL]

Does this match what you expected? Should I add this to your config?

MUST NOT proceed without user confirmation.

Step 4: Apply Configuration

Read the current config first:

read ~/.config/opencode/opencode.json

Then apply using surgical edits. Choose the right pattern:

Pattern A: GPT-5.2 (OpenAI)

OpenAI GPT-5.2 supports specialized reasoning modes via variants (Cycle with ctrl+t). Note that models configured via OAuth plugins (e.g., opencode-openai-codex-auth) often have different enforced limits.

{
  "provider": {
    "openai": {
      "models": {
        "gpt-5.2": {
          "limit": { "context": 400000, "output": 128000 }, // Use 272000 for OAuth
          "variants": {
            "pro": {
              "reasoningEffort": "xhigh",
              "reasoningSummary": "detailed",
            },
            "thinking": { "reasoningEffort": "high" },
            "instant": { "reasoningEffort": "low", "textVerbosity": "low" },
          },
        },
        "gpt-5.2-codex": {
          "limit": { "context": 400000, "output": 128000 }, // Use 272000 for OAuth
        },
      },
    },
  },
}

Pattern B: Other Labs (DeepSeek, Zhipu, MiniMax, Moonshot)

For labs using OpenAI-compatible or Anthropic-compatible endpoints (Verified Q4 2025):

{
  "provider": {
    "deepseek": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "DeepSeek",
      "options": { "baseURL": "https://api.deepseek.com" },
      "models": {
        "deepseek-v3.2": { "limit": { "context": 128000, "output": 32768 } },
      },
    },
    "zhipu": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Zhipu AI (ZAI)",
      "options": { "baseURL": "https://api.z.ai/api/paas/v4" },
      "models": {
        "glm-4.7": { "limit": { "context": 200000, "output": 128000 } },
      },
    },
    "minimax": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "MiniMax",
      "options": { "baseURL": "https://api.minimax.chat/v1" },
      "models": {
        "minimax-m2.1": { "limit": { "context": 204800, "output": 128000 } },
      },
    },
    "moonshot": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Moonshot AI (Kimi)",
      "options": { "baseURL": "https://api.moonshot.cn/v1" },
      "models": {
        "kimi-k2-thinking": { "limit": { "context": 256000, "output": 64000 } },
      },
    },
  },
}

Pattern C: Claude 4.5 Opus (Extended Thinking)

For models that need specific options like Anthropic's extended thinking:

{
  "provider": {
    "anthropic": {
      "models": {
        "claude-4-5-opus-thinking": {
          "id": "claude-4-5-opus-20251124",
          "name": "Claude 4.5 Opus (Extended Thinking)",
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 32000,
            },
          },
        },
      },
    },
  },
}

Step 5: Validate

After editing, remind user to test:

Config updated. To verify it works:
1. Restart OpenCode or run: opencode
2. Run /models and select [model name]
3. Send a test message

If you see errors, check:
- API key is set (run /connect if needed)
- Model ID matches provider's documentation exactly
- Context limits aren't higher than the model actually supports

</workflow>

<research_queries>

</research_queries>

<spec_checklist>

Before configuring, ensure you have:

• [ ] Model ID: Exact API identifier (not marketing name)
• [ ] Context limit: Maximum input tokens
• [ ] Output limit: Maximum output/completion tokens
• [ ] Provider: Which service hosts it
• [ ] Base URL: For custom providers only
• [ ] Special options: Vision, reasoning modes, thinking budgets
• [ ] Availability: Is it actually accessible (not waitlist-only)?

</spec_checklist>

<handling_uncertainty>

If you cannot verify specifications:

1. Be honest: "I couldn't find official documentation for the exact context limit." 2. Provide best guess with source: "Based on [source], it appears to be 128k, but this isn't confirmed." 3. Suggest conservative defaults: "I'll configure with 100k context as a safe starting point. You can increase it once you confirm the actual limit." 4. Recommend checking: "Try the provider's /models endpoint or documentation for exact specs."

</handling_uncertainty>

References

• references/provider-patterns.md - Common provider configuration examples

Provider Configuration Patterns (Q4 2025 Verified)

<instructions> This document lists the ONLY verified configuration patterns for the current frontier model market. You MUST NOT deviate from these patterns unless authorized by deep research and user confirmation. </instructions>

<builtin_providers>

These providers are pre-configured in OpenCode. Just add the model.

OpenAI

GPT-5.2 is the primary model family.

Direct API Patterns

{
  "provider": {
    "openai": {
      "whitelist": ["gpt-5.2", "gpt-5.2-codex"],
      "models": {
        "gpt-5.2": {
          "limit": { "context": 400000, "output": 128000 },
        },
        "gpt-5.2-codex": {
          "limit": { "context": 400000, "output": 128000 },
        },
      },
    },
  },
}

OAuth Plugin Patterns

Models configured via OAuth plugins (e.g., opencode-openai-codex-auth) often have different enforced limits and settings.

{
  "provider": {
    "openai": {
      "whitelist": ["gpt-5.2", "gpt-5.2-codex"],
      "models": {
        "gpt-5.2": {
          "name": "GPT 5.2 (OAuth)",
          "limit": { "context": 272000, "output": 128000 },
        },
        "gpt-5.2-codex": {
          "name": "GPT 5.2 Codex (OAuth)",
          "limit": { "context": 272000, "output": 128000 },
        },
      },
    },
  },
}

Anthropic

Claude 4.5 family is the current standard. You MUST NOT use Claude 3.5.

{
  "provider": {
    "anthropic": {
      "models": {
        "claude-4-5-opus": {
          "id": "claude-4-5-opus-20251124",
          "limit": { "context": 200000, "output": 64000 },
        },
        "claude-4-5-sonnet": {
          "id": "claude-4-5-sonnet-20250929",
          "limit": { "context": 200000, "output": 64000 },
        },
      },
    },
  },
}

Google (Generative AI)

Gemini 3 family is the current standard. You MUST NOT use Gemini 1.5 or 2.

{
  "provider": {
    "google": {
      "models": {
        "gemini-3-pro": {
          "limit": { "context": 1048576, "output": 64000 },
        },
        "gemini-3-flash": {
          "limit": { "context": 1048576, "output": 64000 },
        },
      },
    },
  },
}

xAI

{
  "provider": {
    "xai": {
      "models": {
        "grok-4.1": {
          "limit": { "context": 256000, "output": 64000 },
        },
      },
    },
  },
}

DeepSeek

{
  "provider": {
    "deepseek": {
      "models": {
        "deepseek-v3.2": {
          "name": "DeepSeek V3.2",
          "limit": { "context": 128000, "output": 32768 }
        },
        "deepseek-v3.2-speciale": {
          "name": "DeepSeek V3.2 Speciale",
          "limit": { "context": 128000, "output": 32768 }
        }
      }
    },
    "zhipu": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.z.ai/api/paas/v4" },
      "models": {
        "glm-4.7": {
          "limit": { "context": 200000, "output": 128000 }
        },
        "glm-4.6v": {
          "limit": { "context": 128000, "output": 128000 }
        }
      }
    },
    "moonshot": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.moonshot.cn/v1" },
      "models": {
        "kimi-k2-thinking": {
          "limit": { "context": 256000, "output": 64000 }
        },
        "kimi-k2-instruct": {
          "limit": { "context": 256000, "output": 64000 }
        }
      }
    },
    "minimax": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.minimax.chat/v1" },
      "models": {
        "minimax-m2.1": {
          "limit": { "context": 204800, "output": 128000 }
        },
        "minimax-m2": {
          "limit": { "context": 196608, "output": 65536 }
        }
      }
    }

        "deepseek-v3.2-speciale": {
          "name": "DeepSeek V3.2 Speciale",
          "limit": { "context": 128000, "output": 32768 }
        }
      }
    },
    "zhipu": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.z.ai/api/anthropic/v1" },
      "models": {
        "glm-4.7": {
          "limit": { "context": 200000, "output": 128000 }
        },
        "glm-4.6v": {
          "limit": { "context": 128000, "output": 128000 }
        }
      }
    },
    "moonshot": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.moonshot.cn/v1" },
      "models": {
        "kimi-k2-thinking": {
          "limit": { "context": 256000, "output": 64000 }
        },
        "kimi-k2-instruct": {
          "limit": { "context": 256000, "output": 64000 }
        }
      }
    },
    "minimax": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.minimax.chat/v1" },
      "models": {
        "minimax-m2.1": {
          "limit": { "context": 204800, "output": 128000 }
        },
        "minimax-m2": {
          "limit": { "context": 196608, "output": 65536 }
        }
      }
    }
    "zhipu": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.z.ai/api/anthropic/v1" },
      "models": {
        "glm-4.7": {
          "limit": { "context": 200000, "output": 128000 },
        },
        "glm-4.6v": {
          "limit": { "context": 128000, "output": 128000 },
        },
      },
    },
    "moonshot": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.moonshot.cn/v1" },
      "models": {
        "kimi-k2-thinking": {
          "limit": { "context": 256000, "output": 64000 },
        },
        "kimi-k2-instruct": {
          "limit": { "context": 256000, "output": 64000 },
        },
      },
    },
    "minimax": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.minimax.chat/v1" },
      "models": {
        "minimax-m2.1": {
          "limit": { "context": 204800, "output": 128000 },
        },
        "minimax-m2": {
          "limit": { "context": 196608, "output": 65536 },
        },
      },
    },
  },
}

</builtin_providers>

<aggregator_providers>

Route through model aggregators for access to many models.

OpenRouter

{
  "provider": {
    "openrouter": {
      "models": {
        "anthropic/claude-4-5-opus": {
          "name": "Claude 4.5 Opus (via OpenRouter)",
        },
        "openai/gpt-5.2": {
          "name": "GPT-5.2",
        },
        "moonshotai/kimi-k2-thinking": {
          "name": "Kimi K2 Thinking",
        },
      },
    },
  },
}

With provider routing:

{
  "provider": {
    "openrouter": {
      "models": {
        "moonshotai/kimi-k2-thinking": {
          "name": "Kimi K2 Thinking",
        },
      },
    },
  },
}

Together AI

{
  "provider": {
    "together": {
      "models": {
        "deepseek-ai/DeepSeek-V3.2": {
          "name": "DeepSeek V3.2",
          "limit": { "context": 128000, "output": 32768 },
        },
        "mistralai/Mistral-Large-3-2512": {
          "name": "Mistral Large 3 (2512)",
          "limit": { "context": 262144, "output": 65536 },
        },
      },
    },
  },
}

</aggregator_providers>

<custom_providers>

Generic OpenAI-Compatible

{
  "provider": {
    "my-server": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Local Server",
      "options": {
        "baseURL": "http://localhost:8080/v1",
      },
      "models": {
        "my-model": {
          "name": "My Custom Model",
          "limit": { "context": 32000, "output": 4096 },
        },
      },
    },
  },
}

Ollama (Local)

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1",
      },
      "models": {
        "llama3.3:70b": {
          "name": "Llama 3.3 70B",
          "limit": { "context": 128000, "output": 8192 },
        },
      },
    },
  },
}

LM Studio

{
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1",
      },
      "models": {
        "loaded-model": {
          "name": "Currently Loaded Model",
        },
      },
    },
  },
}

vLLM Server

{
  "provider": {
    "vllm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "vLLM Server",
      "options": {
        "baseURL": "http://localhost:8000/v1",
      },
      "models": {
        "NousResearch/Hermes-3-Llama-3.1-70B": {
          "name": "Hermes 3 70B",
          "limit": { "context": 131072, "output": 16384 },
        },
      },
    },
  },
}

</custom_providers>

<enterprise_setups>

Azure OpenAI

{
  "provider": {
    "azure": {
      "models": {
        "gpt-5.2": {
          "limit": { "context": 400000, "output": 128000 },
        },
      },
    },
  },
}

Note: Requires AZURE_RESOURCE_NAME env var and model deployment matching model name.

Cloudflare AI Gateway

{
  "provider": {
    "cloudflare-ai-gateway": {
      "models": {
        "openai/gpt-5.2": {},
        "anthropic/claude-4-5-sonnet": {},
      },
    },
  },
}

Note: Requires CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_GATEWAY_ID env vars.

Custom Headers (e.g., auth proxy)

{
  "provider": {
    "corp-proxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Corporate Proxy",
      "options": {
        "baseURL": "https://ai-proxy.corp.internal/v1",
        "headers": {
          "X-Corp-Auth": "Bearer ${env:CORP_AI_TOKEN}",
          "X-Team-ID": "engineering",
        },
      },
      "models": {
        "gpt-5.2": { "name": "GPT-5.2 (via proxy)" },
      },
    },
  },
}

</enterprise_setups>

<model_options>

Reasoning / Thinking Modes

Models with reasoning capabilities should be configured via variants to allow cycling modes.

OpenAI Specific Options

• reasoningEffort: "minimal" | "low" | "medium" | "high" | "xhigh"
• reasoningSummary: "auto" | "detailed"
• include: ["reasoning.encrypted_content"]

Anthropic Specific Options

• thinking: { type: "enabled", budgetTokens: number }

Google Specific Options

• includeThoughts: boolean
• thinkingLevel: "low" | "high"

Native OpenCode Options (OpenAI Compatible)

• textVerbosity: "low" | "medium" | "high" (Controls response length)

{
  "variants": {
    "thinking": {
      "reasoningEffort": "high",
      "reasoningSummary": "detailed",
    },
    "instant": {
      "reasoningEffort": "low",
      "textVerbosity": "low",
    },
  },
}

Anthropic extended thinking:

{
  "options": {
    "thinking": {
      "type": "enabled",
      "budgetTokens": 32000,
    },
  },
}

Variant Configuration (Cycle with ctrl+t)

You SHOULD define variants to expose model specific capabilities like "Thinking" or "Instant" response modes.

{
  "variants": {
    "thinking": {
      // OpenAI / Azure / Bedrock
      "reasoningEffort": "high",
      "reasoningSummary": "auto",
      // Anthropic
      "thinking": { "type": "enabled", "budgetTokens": 16000 },
      // Google
      "includeThoughts": true,
      "thinkingLevel": "high",
    },

    "instant": {
      "reasoningEffort": "low",
      "textVerbosity": "low", // Native OpenCode field for OpenAI Compatible
    },
  },
}

Token Limits

Common context window sizes:

MUST verify actual limits from official docs - these change frequently.

</token_limits>