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