playbooks

home / skills / serejaris / ris-claude-code / opencode-config

opencode-config skill

/skills/opencode-config

This skill helps you configure the OpenCode CLI by managing opencode.json, providers, and baseURL with project-global-auth precedence.

npx playbooks add skill serejaris/ris-claude-code --skill opencode-config

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
3.0 KB
---
name: opencode-config
description: Use when configuring OpenCode CLI - changing default model, adding providers, setting baseURL, or troubleshooting model selection issues
---

# 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

```json
{
  "$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:

```json
{
  "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:**

```json
{
  "$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

```json
{
  "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

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

Overview

This skill helps you configure the OpenCode CLI by editing and validating opencode.json and related files. It covers changing the default model, adding or customizing providers (including baseURL), and diagnosing model selection or authentication issues. Use it to ensure project, global, and auth configs merge correctly and the CLI picks the intended model.

How this skill works

The skill inspects configuration files in the three OpenCode locations (project ./opencode.json, global ~/.config/opencode/opencode.json, and auth ~/.local/share/opencode/auth.json) and explains how they merge by priority. It validates model identifiers (provider-id/model-name), checks provider options like baseURL, and guides you through CLI commands (/connect, /models, opencode auth login/list) to surface provider and model availability. It also provides targeted troubleshooting steps for common problems and restart guidance to reload changes.

When to use it

  • Set or change the default model for your project or global scope.
  • Add a custom provider or when using OpenAI‑compatible APIs with a nonstandard baseURL.
  • Switch to a subscription-specific endpoint (e.g., Z.AI coding plan) or configure multiple provider baseURLs.
  • Troubleshoot missing models in /models or incorrect model selection after config changes.
  • Verify credentials and provider access when models don’t appear or auth fails.

Best practices

  • Always prefer project ./opencode.json for project-specific overrides and global for defaults.
  • Specify models as provider-id/model-name to avoid ambiguity.
  • When adding custom providers, include options.baseURL and npm or SDK info to ensure compatibility.
  • Check ~/.local/share/opencode/auth.json contains credentials for the provider you intend to use.
  • After changing configs, restart OpenCode to force a config reload if the CLI still shows the old model.

Example use cases

  • Configure a Z.AI coding-plan model with the correct baseURL so the CLI uses glm-4.7 for coding tasks.
  • Add an OpenAI-compatible third‑party provider with options.baseURL and a custom model mapping.
  • Resolve a missing model in /models by confirming credentials exist in auth.json and provider ID matches the config.
  • Switch default model per mode (build vs plan) so build uses a stronger model and plan uses a cheaper small_model.
  • Debug why a model change didn’t apply by checking the three config layers and restarting OpenCode.

FAQ

Why doesn’t my model appear in /models?

Confirm auth.json has credentials for that provider and the provider ID in opencode.json matches the authenticated provider; then run /models again.

How do I set a provider’s baseURL?

Add provider.<id>.options.baseURL in opencode.json (project or global) with the correct endpoint for your subscription.

Which config wins when multiple levels set the same key?

Project-level ./opencode.json overrides global ~/.config/opencode/opencode.json; both override remote defaults when applicable.