opencode.json Config: Providers, Models and Keys Step by Step

A reference for opencode.json: file locations, merge order, key fields, and a step-by-step setup of a custom OpenAI-compatible provider with the API key read from an environment variable.

7 min · · opencode · setup · инструменты

opencode.json is the file where opencode keeps the default model, providers, agents, MCP servers and permissions. The global config lives at ~/.config/opencode/opencode.json, the project config sits in the repository root, and the two are merged, with project values taking precedence. A custom OpenAI-compatible provider is added through a provider block that uses the @ai-sdk/openai-compatible package, an API address ending in /v1, and a list of models. Each step below uses Zukko as the example.

If you are new to opencode, the overview of what the agent is is a good starting point. This article covers the config file itself.

Where the config lives and how files merge

The file is named opencode.json or opencode.jsonc. The JSONC variant allows comments and trailing commas, which removes a class of errors when editing by hand.

LevelPath
Global~/.config/opencode/opencode.json
Projectopencode.json in the project root or .opencode/opencode.json
System, macOS/Library/Application Support/opencode
System, Linux/etc/opencode
System, Windows%ProgramData%\opencode

Configs do not replace each other; they merge. If the global file defines a provider and the project file sets only the model, opencode uses both. When the same field appears in both, the project value wins.

A practical layout: keep providers in the global file and choose the model and permissions per repository in the project file. That way the provider definition is not copied into every project.

To load the config from a different location, OpenCode 1 supports an environment variable:

bash
export OPENCODE_CONFIG=/path/to/my/custom-config.json

File locations and merge rules are described in the config docs as of 29.10.2026.

The $schema field

The first line of the config points to the schema at https://opencode.ai/config.json. An editor with JSON Schema support will suggest field names and flag typos before opencode even starts.

Main fields in opencode.json

Fields in the OpenCode 1 format:

FieldPurpose
modeldefault model as provider/model
small_modela lightweight model for housekeeping tasks such as generating titles
providerproviders: API address, key, model list
agent, default_agentagent definitions and the default agent
mcpMCP server connections
permissionwhat the agent may do without asking
plugin, instructionsplugins and instruction files
enabled_providers, disabled_providerswhich providers are shown or hidden

A minimal working config:

bash
{
  "$schema": "https://opencode.ai/config.json",
  "model": "zukko/claude-sonnet-5-5",
  "small_model": "zukko/qwen3.8-flash"
}

The zukko prefix is the provider ID from the provider block covered below. Roles, per-agent models and tools are covered in the article on configuring opencode agents. For the mcp block, check the docs for the opencode version you have installed.

Permissions

In OpenCode 1, permissions are an object:

bash
{
  "permission": { "edit": "ask", "bash": "ask" }
}

In OpenCode 2, they are an ordered array of rules:

bash
{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" }
  ]
}

OpenCode 1 vs OpenCode 2

OpenCode 2 uses plural field names: providers, agents, plugins, permissions. The old fields are still accepted. V2 reads V1 configs from the same locations and normalizes them in memory without rewriting the file. The examples here use the V1 format, so they work in both versions. Details are in the migration guide as of 29.10.2026.

Adding an OpenAI-compatible provider

opencode pulls its model catalog from models.dev and supports 75+ providers through the AI SDK. If the provider you need is missing, or you need a custom API address, you describe it manually.

Step 1. Put the key in an environment variable

Zukko keys start with fetch_. To keep the key out of the repository, set it in the environment:

bash
export ZUKKO_API_KEY="fetch_..."

Add the line to your shell profile, otherwise the variable disappears when the terminal closes.

Step 2. Describe the provider

bash
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zukko": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Zukko",
      "options": {
        "baseURL": "https://api.zukko.pro/v1",
        "apiKey": "{env:ZUKKO_API_KEY}"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "claude-opus-5-5": { "name": "Claude Opus 5.5" },
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "qwen3.8-flash": { "name": "Qwen 3.8 Flash" }
      }
    }
  },
  "model": "zukko/claude-sonnet-5-5",
  "small_model": "zukko/qwen3.8-flash"
}

What matters here:

  • zukko is the provider ID and becomes the prefix in model.
  • npm is the AI SDK package. @ai-sdk/openai-compatible talks to /v1/chat/completions. For models served through /v1/responses, the opencode docs point to @ai-sdk/openai.
  • baseURL must end with /v1.
  • apiKey uses the {env:ZUKKO_API_KEY} substitution. If the variable is unset, it becomes an empty string. There is also {file:path/to/file}, which reads the value from a file.
  • models keys must match catalog IDs exactly. name only affects how the model is displayed.

Each model can also take limit.context and limit.output for context and response size. Take the values from the model description rather than guessing. The block format is documented in the providers docs as of 29.10.2026.

Step 3. Check model IDs

The current Zukko model list with prices is returned by a GET request:

bash
curl https://api.zukko.pro/v1/models

Copy IDs from the response instead of typing them from memory: claude-sonnet-5-5 and claude-sonnet-5-standard are different models at different prices.

The variant from the Zukko docs

The Zukko guide for opencode takes another route and overrides the built-in anthropic provider:

bash
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.zukko.pro/v1",
        "apiKey": "{env:ZUKKO_API_KEY}"
      },
      "models": {
        "claude-opus-5-5": {},
        "claude-sonnet-5": {}
      }
    }
  }
}

This is the variant described and tested in the Zukko docs, for Claude models only. The zukko provider from step 2 follows the template in the opencode docs: start with a short request, and if a model behaves unreliably there, fall back to the anthropic variant.

The /v1 suffix is required here too, even though the provider is Anthropic. This trips people up: Claude Code takes ANTHROPIC_BASE_URL without /v1, while opencode needs it. A shorter setup without the reference material is in opencode: connecting to an API gateway in five minutes.

Where keys are stored

You can supply the key in three ways: options.apiKey in the config, the /connect command with the Other option, or opencode auth login.

The last two store the key outside opencode.json. OpenCode 1 writes it to ~/.local/share/opencode/auth.json; OpenCode 2 uses the SQLite database ~/.local/share/opencode/opencode.db.

Project configs often end up in git, so avoid plain-text keys there and use {env:...} or {file:...}. On the Zukko side, you can also set a daily and monthly spending limit in dollars per key.

Choosing a model

/models switches the model for the current session and does not touch the config. The default model is set with "model": "provider/model", as in the examples above.

A sensible split is a main model for coding and a cheap small_model for housekeeping. A few options from the Zukko catalog:

ModelPrice, input/output
claude-opus-5-5$0.8/$4 per 1M
claude-sonnet-5-5$0.4/$2 per 1M
deepseek-v4-pro$0.07/$0.21 per 1M
qwen3.8-flash$0.03/$0.07 per 1M

For comparison, 10M input tokens cost 10 × $0.4 = $4 on claude-sonnet-5-5 and 10 × $0.03 = $0.3 on qwen3.8-flash. More ways to cut usage are in the token-saving checklist.

Common config mistakes

Invalid JSON. A missing or extra comma or an unclosed bracket, and opencode cannot read the file. $schema in the editor or switching to opencode.jsonc helps.

No /v1 in baseURL. Every request returns 404. Make sure the address ends with /v1.

Model not in the catalog. 404 model_not_found means the name is not in https://api.zukko.pro/v1/models. Check the spelling, including dots and hyphens.

Models missing from /models. Usually the file is not where opencode looks for it, or it has a syntax error. Check the path, fix the commas and restart opencode.

Empty key. {env:ZUKKO_API_KEY} resolves to an empty string if the variable is not set in the shell that launched opencode.

If requests go through but the provider occasionally returns 503, the config is not the cause; see the article on error 503.

FAQ

What is the difference between opencode.json and opencode.jsonc?

The content is the same. .jsonc additionally allows comments and trailing commas, which makes manual editing more forgiving.

Can I keep the API key directly in opencode.json?

Yes, via options.apiKey. If the file is in a repository, though, the key ends up in git history. {env:ZUKKO_API_KEY} or /connect is safer.

Why does opencode need /v1 when Claude Code does not?

Claude Code appends the path to ANTHROPIC_BASE_URL itself. opencode expects the full API address, so https://api.zukko.pro/v1 includes the suffix.

Does the /models command change the config?

No. It applies only to the current session. The persistent choice is the model field.

How is usage through Zukko billed?

The balance is in dollars, only tokens you use are charged, there is no subscription fee, and top-ups start at $1. A comparison with opencode's built-in option is in OpenCode Zen or your own provider.

zukko

Pay 25×
less

for Claude Code & ChatGPT

One fetch_* key and base URL api.zukko.pro — for Cursor, Claude Code, Codex, and any SDK.

Get API keyDocumentation

api.zukko.pro · fetch_*

opencode json: providers and config step by step · Zukko