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.
| Level | Path |
|---|---|
| Global | ~/.config/opencode/opencode.json |
| Project | opencode.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:
export OPENCODE_CONFIG=/path/to/my/custom-config.jsonFile 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:
| Field | Purpose |
|---|---|
model | default model as provider/model |
small_model | a lightweight model for housekeeping tasks such as generating titles |
provider | providers: API address, key, model list |
agent, default_agent | agent definitions and the default agent |
mcp | MCP server connections |
permission | what the agent may do without asking |
plugin, instructions | plugins and instruction files |
enabled_providers, disabled_providers | which providers are shown or hidden |
A minimal working config:
{
"$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:
{
"permission": { "edit": "ask", "bash": "ask" }
}In OpenCode 2, they are an ordered array of rules:
{
"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:
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
{
"$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:
zukkois the provider ID and becomes the prefix inmodel.npmis the AI SDK package.@ai-sdk/openai-compatibletalks to/v1/chat/completions. For models served through/v1/responses, the opencode docs point to@ai-sdk/openai.baseURLmust end with/v1.apiKeyuses 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.modelskeys must match catalog IDs exactly.nameonly 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:
curl https://api.zukko.pro/v1/modelsCopy 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:
{
"$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:
| Model | Price, 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.
Related articles
- How to Install opencode on Windows, macOS and Linux: Step by StepOfficial ways to install opencode on macOS, Linux and Windows, choosing between OpenCode 1 and 2, first launch, and configuring Zukko with the key in an environment variable.
- Opencode for free: which models are available and what the limits areopencode itself is free, and its built-in provider offers a set of free models including Big Pickle. Here is what those models are, how they treat your data, and what an hour of agent work costs once you move to paid models.
- Configure OpenClaw with Zukko — provider choice and configOpenClaw connects to Zukko as a custom provider. We cover the two API options, ready-made openclaw.json configs, and common errors.
- OpenCode Go vs Zen: subscription, pricing, limits, and a bring-your-own-key alternativeOpenCode Go is a subscription with per-model dollar limits, Zen is pay-as-you-go from prepaid credits. Pricing, limits and payment per the docs as of 29.10.2026, plus when your own key costs less.
- Claude Code from scratch: install and configure with your own keyInstalling Claude Code and configuring it to run on your own API key, step by step, including the mistakes almost everyone makes.
- opencode agents: setting up roles, models and toolsA custom agent in opencode is a role, a model and a set of permissions. A working config where a cheap model handles routine work and a stronger one edits code.