OpenCode Configuration Skill

OpenCode Configuration

Overview

OpenCode config is managed via opencode.json. Configs merge by priority: project > global > remote.

Config Locations

| Location | Path | Priority | |----------|------|----------| | Project | ./opencode.json | Highest | | Global | ~/.config/opencode/opencode.json | Medium | | Auth | ~/.local/share/opencode/auth.json | Credentials only |

Quick Reference

{
  "$schema": "https://opencode.ai/config.json",
  "model": "provider/model-name",
  "small_model": "provider/small-model",
  "provider": {
    "provider-id": {
      "options": {
        "baseURL": "https://api.example.com/v1"
      }
    }
  }
}

Adding Custom Provider

For OpenAI-compatible APIs:

{
  "provider": {
    "my-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Display Name",
      "options": {
        "baseURL": "https://api.example.com/v1"
      },
      "models": {
        "model-id": {
          "name": "Model Display Name"
        }
      }
    }
  }
}

Example: Z.AI Coding Plan

Different Z.AI products use different baseURLs:

| Provider | baseURL | Use Case | |----------|---------|----------| | zai | https://api.z.ai/api/paas/v4 | Regular Z.AI API | | zai-coding-plan | https://api.z.ai/api/coding/paas/v4 | GLM Coding Plan subscription |

Config for Coding Plan:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "zai-coding-plan/glm-4.7",
  "small_model": "zai-coding-plan/glm-4-flash",
  "provider": {
    "zai-coding-plan": {
      "options": {
        "baseURL": "https://api.z.ai/api/coding/paas/v4"
      }
    }
  }
}

Modes Configuration

{
  "mode": {
    "build": {
      "model": "anthropic/claude-sonnet-4-5",
      "tools": { "write": true, "edit": true, "bash": true }
    },
    "plan": {
      "model": "anthropic/claude-haiku-4-5",
      "tools": { "write": false, "edit": false, "bash": false }
    }
  }
}

CLI Commands

| Command | Description | |---------|-------------| | /connect | Add provider credentials | | /models | Select model | | opencode auth login | Add credentials via CLI | | opencode auth list | List configured providers |

Common Mistakes

| Mistake | Fix | |---------|-----| | Wrong provider for subscription | Check if your subscription uses different baseURL | | Missing baseURL for custom provider | Add options.baseURL in provider config | | Model not appearing in /models | Check auth.json has credentials for provider | | Wrong model after config change | Restart OpenCode to reload config |

Troubleshooting

Check auth: cat ~/.local/share/opencode/auth.json
Check config: cat ~/.config/opencode/opencode.json
Verify model format: provider-id/model-name
Test provider: Run /models and check if provider appears

Agent Skills: OpenCode Configuration

Install this agent skill to your local

Skill Files