OpenCode Configuration Guide

Last updated: October 17, 2026 (Asia/Shanghai)

Related: Help Center · Claude Code · Codex · Gemini CLI

OpenCode is a multi-model coding workbench built for the terminal: you can use Claude, Gemini, Kimi, and others in the same tool instead of being limited to a single vendor's official CLI.

Tool	Better suited for
Claude Code / Codex / Gemini CLI	Going deep in a single official ecosystem
OpenCode	Managing multiple vendors in one place, with room for routing and plugins later

---

1. Install

npm install -g opencode-ai
opencode --help

If the command is not on your PATH, open a new terminal window.

---

2. Create a token

Create a new token under "Token Management" in the console (e.g. opencode) and copy the sk- key. If you plan to split quota by protocol, you can create one token each for OpenAI-compatible / Anthropic / Gemini.

---

3. Configuration file location

mkdir -p ~/.config/opencode
# main configuration
touch ~/.config/opencode/opencode.json

Path: ~/.config/opencode/opencode.json.

---

4. Minimal working configuration (get one model working first)

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": true,
  "permission": "allow",
  "provider": {
    "ciyuan": {
      "name": "TokenExplore",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "sk-xxxxxxxx",
        "baseURL": "https://ai.afp.net/v1"
      },
      "models": {
        "claude-sonnet-4-6": {
          "id": "claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6"
        }
      }
    }
  },
  "tools": {
    "bash": true,
    "edit": true,
    "glob": true,
    "grep": true,
    "read": true,
    "write": true
  }
}

Key points:

1. apiKey: your TokenExplore token
2. baseURL: the OpenAI-compatible path, must include /v1
3. models.*.id: exactly matches the platform model ID
4. tools: keep enabled when you need to edit files / run commands

Configure just one model first, and add vendors once you have confirmed that chat works.

---

5. Splitting providers by protocol

OpenAI-compatible (Claude / Gemini / Kimi, etc. can all start here)

{
  "provider": {
    "ciyuan-openai": {
      "name": "TokenExplore · OpenAI Compatible",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "sk-xxxxxxxx",
        "baseURL": "https://ai.afp.net/v1"
      },
      "models": {
        "claude-sonnet-4-6": {"id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6"},
        "gemini-3.1-pro": {"id": "gemini-3.1-pro", "name": "Gemini 3.1 Pro"},
        "kimi-k3": {"id": "kimi-k3", "name": "Kimi K3"},
        "deepseek-v4-flash": {"id": "deepseek-v4-flash", "name": "DeepSeek V4 Flash"}
      }
    }
  }
}

Anthropic protocol (native Claude)

{
  "provider": {
    "ciyuan-anthropic": {
      "name": "TokenExplore · Anthropic",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "apiKey": "sk-xxxxxxxx",
        "baseURL": "https://ai.afp.net"
      },
      "models": {
        "claude-sonnet-4-6": {"id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6"},
        "claude-opus-4-8": {"id": "claude-opus-4-8", "name": "Claude Opus 4.8"}
      }
    }
  }
}

Anthropic SDK-style baseURL usually does not include /v1; if your OpenCode / AI SDK version requires /v1, try both forms and go by the actual error.

Google protocol (Gemini)

{
  "provider": {
    "ciyuan-gemini": {
      "name": "TokenExplore · Gemini",
      "npm": "@ai-sdk/google",
      "options": {
        "apiKey": "sk-xxxxxxxx",
        "baseURL": "https://ai.afp.net"
      },
      "models": {
        "gemini-3.1-pro": {"id": "gemini-3.1-pro", "name": "Gemini 3.1 Pro"},
        "gemini-3.5-flash": {"id": "gemini-3.5-flash", "name": "Gemini 3.5 Flash"}
      }
    }
  }
}

Whether Gemini's baseURL includes /v1beta depends on the SDK; when connecting to TokenExplore, you generally enter the gateway root URL and let the compatibility layer assemble the path. Model IDs must match /v1/models.

---

6. Verification order

1. Run ls ~/.config/opencode/opencode.json to confirm the file exists and is valid JSON (no trailing commas).
2. opencode --help starts.
3. Start a simple task (e.g. "write a hello world").
4. Then add a second provider / model.

---

7. About oh-my-opencode (optional)

oh-my-opencode is an orchestration / routing plugin, not a provider. Recommendations:

• opencode.json: only providers, keys, models, and whether the plugin is enabled
• oh-my-opencode.json: agent / category → provider/model routing

Enable it only after the main configuration works. Reference names must match the provider key; for example, if the main configuration uses ciyuan-openai, write ciyuan-openai/claude-sonnet-4-6 in the route.

---

8. Troubleshooting

Symptom	Fix
Configuration parsing failed	Check the JSON syntax and nesting
OpenAI-compatible call fails	Check that baseURL includes /v1 and that npm is set to @ai-sdk/openai-compatible
Native Claude fails	Check that you use @ai-sdk/anthropic, the model ID, and whether the Base URL should include /v1
Gemini fails	Check that you use @ai-sdk/google; do not force GPT-specific fields onto it
Model not found	Check against /v1/models and the token group

---

9. Recommended workflow

1. Install OpenCode
2. Create a TokenExplore token
3. Write a minimal config with only one model
4. Once it works, add native Claude / Gemini
5. Consider a routing plugin last

---

Back to: Help Center