OpenCode setup: install, models and an API key provider

OpenCode is an open-source AI agent for code. It reads your project, edits files and runs commands, and you pick the model behind it. You can install it with one command in the terminal or as a ready-made app. Below: installation on macOS, Linux and Windows, what is paid and what is free in OpenCode, and how to connect a codexkey key with a ready config.

OpenCode: what it is and how it differs from Claude Code

OpenCode describes itself as an open-source AI agent for code. It runs in the terminal, as a desktop app and as an IDE extension, under the MIT license. The old repository address, sst/opencode, now opens as anomalyco/opencode, and the repository has about 223 thousand stars as of 29 October 2026.

The main difference from Claude Code is how tightly it is tied to models. OpenCode does not hold on to a single vendor: you connect models from different companies and switch between them with the /models command. Claude Code is built around Claude models, and we have covered its alternatives and comparisons separately. If you want to run different models against the same repository without swapping tools, we would pick OpenCode.

Installing OpenCode on macOS, Linux and Windows

A warning first: OpenCode has two branches. The documentation covers both, but the home page and the download page already show the commands for the second one. They share one terminal command, opencode, so they cannot live side by side.

On Windows the main documentation recommends WSL and also mentions scoop install opencode and choco install opencode. The second branch's documentation says Windows package managers are not supported and you need a standalone binary. You can check the install with opencode --version.

Which branch to take. The codexkey config in this article is written for OpenCode 1, so install that one: npm install -g opencode-ai. The second branch uses a different file format: a top-level providers key, plus the fields package, settings.baseURL and env. If you already have OpenCode 2, carry the address, key and model IDs over following the example in the second branch's documentation at opencode.ai/v2/docs.

Desktop app

Installers are on the opencode.ai/download page: macOS for Apple Silicon and Intel, Windows x64 and ARM64, and Linux as .deb and .rpm packages. On macOS you can use Homebrew instead: brew install --cask opencode-desktop.

Zen, Go and free models: OpenCode providers

There are two ways to add a model: the /connect command in the interface or an entry in opencode.json. Anything you enter through /connect is stored in ~/.local/share/opencode/auth.json.

OpenCode Zen is a catalog of models curated by the team, with pay-as-you-go billing: you top up a balance in the OpenCode console and spend it on requests. A top-up carries a 4.6% fee plus $0.31. The models come from OpenAI, Anthropic, Google, xAI, Qwen, DeepSeek, Kimi and others, and IDs are written as opencode/<model-id>.

OpenCode Go sells a subscription to popular open models for code. Go costs $10 a month, Go Plus $40, Go Teams $20 per member. Limits are set in dollars per model: the 5-hour window gives 20% of the monthly amount, the week 50%. On Go, for example, Kimi K3 gets $15 a month. The model list changes, and the documentation warns about that separately.

Now the free models in Zen. As of 29 October 2026 the documentation lists GLM-5.3-Flash Free, DeepSeek V4.1 Flash Free, MiMo-V2.6-Flash Free, several Nemotron models and Big Pickle, and all of them are available for a limited time. You can hide them with the OPENCODE_DISABLE_FREE_MODELS=1 variable. The program itself is free; you pay only for tokens or a subscription. Whether the OpenCode console accepts payment from Russia, and by what methods, the documentation does not say, and we did not check.

Connecting OpenCode to codexkey with an API key

codexkey provides an OpenAI-compatible address, https://api.codexkey.online/v1, and one sk_cdx_... key for every model. You can pay with a Russian-issued card, through SBP (the Russian Faster Payments System) or with crypto. You need neither an OpenCode account nor a Zen subscription. The config below comes from the OpenCode guide unchanged, except that the key is replaced with a placeholder.

The file lives at ~/.config/opencode/opencode.json, or on Windows at %USERPROFILE%\.config\opencode\opencode.json. Paste this into it:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "codexkey-claude/claude-sonnet-5",
  "provider": {
    "codexkey-claude": {
      "npm": "@ai-sdk/anthropic",
      "name": "codexkey · Claude",
      "options": { "baseURL": "https://api.codexkey.online/v1", "apiKey": "sk_cdx_YOUR_KEY" },
      "models": {
        "claude-opus-5-5": { "name": "Claude Opus 5.5", "limit": { "context": 1000000, "output": 128000 } },
        "claude-sonnet-5": { "name": "Claude Sonnet 5", "limit": { "context": 1000000, "output": 32000 } }
      }
    },
    "codexkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "codexkey · GPT, Gemini and others",
      "options": { "baseURL": "https://api.codexkey.online/v1", "apiKey": "sk_cdx_YOUR_KEY" },
      "models": {
        "gpt-6-astra": { "name": "GPT-6 Astra", "limit": { "context": 1000000, "output": 128000 } },
        "gemini-3.1-pro": { "name": "Gemini 3.1 Pro", "limit": { "context": 1000000, "output": 65000 } },
        "deepseek-v4.1-flash": { "name": "DeepSeek V4.1 Flash", "limit": { "context": 1000000, "output": 131072 } }
      }
    }
  }
}

Start opencode and choose a model through /models, for example codexkey/gpt-6-astra. A few rules.

• Keep the limit block: without it OpenCode does not know the context size and cannot compact the history.
• A model name is built from the provider, a slash and the name. Claude models are defined in the codexkey-claude provider, the rest in codexkey.
• If you name the file opencode.jsonc, comments are allowed in it.
• Keep the key in the global file. The project opencode.json usually sits in the repository and overrides the global one, so a key in it is easy to commit by accident.
• Add a new model to the right models block following its neighbors, and take the ID from the catalog or from the response to GET https://api.codexkey.online/v1/models.

OpenCode configs are merged rather than replaced, and the project file wins on conflicts. So the repository can hold a minimal opencode.json with no key, while the providers and the key come from the global file:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "codexkey/deepseek-v4.1-flash"
}

A model missing from the /models list? Check three places: that the JSON is valid (one stray comma breaks the whole file), that the model is defined in the models block of the right provider, and that the ID matches the response of GET /v1/models character for character.

Which model to use in OpenCode

There is no single best model, only different prices for different jobs. The prices in the table come from the codexkey price list as of 29 October 2026; check the models page for current ones.

The setup is built on price and role; no benchmark stands behind it. Testing it on your own repository is simple: take 10 typical tasks with tests, run each on two or three models, then compare the share solved and the price per solved task. The article on choosing an AI for programming covers the method in more detail.

The small_model setting helps cut spend: OpenCode hands it light tasks such as session titles. Add "small_model": "codexkey/deepseek-v4.1-flash" next to model, and a cheap model takes over the housekeeping work. Other ways to save are collected in the piece on cutting a Claude Code bill threefold. If you need an agent for chats rather than OpenCode, look at OpenClaw.

The codexkey catalog also has free models: deepseek-v4.1-flash-1017-free, minimax-m3-free and qwen3.8-flash-free. See the models page for their terms and limits; we do not invent numbers here. They connect through the same models block in the codexkey provider.

FAQ

Is OpenCode free?

OpenCode itself is free, and its source is open under MIT. You pay for models: per token through Zen or with your own key, through the Go subscription ($10 a month), or through a gateway such as codexkey. Zen has free models, but only temporary ones.

How do I install OpenCode on Windows?

The main documentation recommends WSL and mentions scoop install opencode, choco install opencode and npm install -g opencode-ai. For OpenCode 2, ready installers are on the download page. To check, run opencode --version.

What is OpenCode Zen?

A set of models vetted by the OpenCode team, billed per use through the OpenCode console. You connect it with /connect, and names look like opencode/<model-id>. Topping up the balance carries a 4.6% fee plus $0.31.

What is OpenCode Go?

A subscription to popular open models for code: Go costs $10 a month, Go Plus $40, Go Teams $20 per member. The limit is counted in dollars per model across windows: 5 hours, a week and a month. You connect it with /connect.

How do I connect my own API key or model to OpenCode?

Add a provider to ~/.config/opencode/opencode.json: the @ai-sdk/openai-compatible package, a baseURL and a list of models. The ready codexkey config is above: two providers and one sk_cdx_... key.

Is there an OpenCode desktop app?

Yes. Installers for macOS, Windows and Linux are on opencode.ai/download, and on macOS there is also a Homebrew cask.

How does OpenCode differ from Claude Code?

OpenCode is open, works with models from different vendors and switches between them on the fly. Claude Code is built around Claude and connects to it through the ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN and ANTHROPIC_DEFAULT_* variables, including through codexkey. Let one question decide: do you want to be tied to one model family?