opencode: what this agent is and how to connect your own models

If you searched for "opencode ai что это" (what is opencode ai), the short answer is: an open-source AI coding agent. It runs in the terminal, reads your project, proposes and applies edits, and runs commands. The main difference from closed assistants is that you choose the model: opencode works with many providers, not one. Below: what it does, how to install it, how the workflow goes, and where to put a key.

The description was checked against the opencode.ai/docs documentation as of October 18, 2026. The project moves fast, and the docs even carry a banner about a second version. If a command in this article does not work for you, check the section for your version.

What opencode is

By the project's own description, it is an AI agent with open source code. The main interface is text-based, in the terminal (TUI), but there is also a desktop app and an IDE extension. For comfortable use the docs recommend a modern terminal such as WezTerm, Alacritty, Ghostty or Kitty. On Windows the authors suggest WSL, saying it gives better performance and full compatibility.

What it does in principle, like other agents of this class: it takes a task in plain language, finds the relevant files itself, reads them, makes edits and runs commands when needed. We covered how these tools differ in a separate article, Claude Code, opencode, Aider, Cline: how harnesses differ↗.

Do you need an "opencode api key"

The program itself has no key. It is a client, and the key comes from the model vendor: Anthropic, OpenAI, any gateway, or the project's own Zen catalog. The query "opencode api key" really means "where do I put a key in opencode". The answer: either with the /connect command or in the opencode.json config. A short step-by-step guide to connecting to the gateway is in opencode: connecting in five minutes↗, and here we go in order, with explanations.

Installation

The simplest way from the docs:

curl -fsSL https://opencode.ai/install | bash

There are others: npm install -g opencode-ai (also bun, pnpm, yarn), brew install anomalyco/tap/opencode for macOS and Linux, packages for Arch, Chocolatey and Scoop on Windows, and a Docker image. The authors note that the script install provides the opencode binary and may conflict with an installed second version. Do not mix methods.

First run

1. Connect a provider. In the interface type /connect and choose a vendor.
2. Go to the project directory: cd /path/to/project.
3. Run opencode.
4. Run /init. The agent studies the project and creates an AGENTS.md file in the root describing the structure and conventions. Commit it: it helps the agent understand the code.

After that you can just write tasks. Files are mixed into a request with @ and name search, and images can be dragged into the terminal window.

Plan and Build modes

This is the most useful habit. The Tab key switches modes:

• Plan makes no changes; it only suggests how to implement the task. Ask for a plan, review it, refine it with follow-ups.
• Build does the work: edits files, runs commands.

The docs recommend asking for a plan first, especially for new features, and describing the task the way you would explain it to a junior teammate. For small edits you can skip the plan.

If the result is wrong, /undo rolls the changes back and returns your message for editing, and /redo reapplies them. It works several times in a row.

How to connect your own models

There are three options.

The Zen catalog. In /connect choose the opencode provider, sign in at opencode.ai/auth, add credits and copy the key. Models picked by the project team and vetted as agents.

Any OpenAI-compatible service. In /connect scroll to Other, set an id and paste the key, then describe the provider in opencode.json using the @ai-sdk/openai-compatible package.

Override the address of a built-in provider. This is how Zukko is connected for Claude, as described in our opencode documentation↗. The file ~/.config/opencode/opencode.json:

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

Put the fetch_... key in an environment variable:

export ZUKKO_API_KEY=fetch_your_key
opencode models

The opencode models command lists available models, and inside the program /models does the same. Pick anthropic/claude-sonnet-5. The address must end in /v1: without it requests from opencode go to the wrong path and return 404. This is where opencode differs from Claude Code, which adds /v1 itself.

You can check the setup without the interface: opencode run "Explain what this project does" sends one command and exits.

The config file can live globally (~/.config/opencode/opencode.json) and in the project root. The project file takes precedence over the global one and can safely be kept in git as long as it does not contain the key itself. That is why the key is best read from an environment variable, as above.

Does opencode work in Russia

The program itself is local, and availability is determined by the model vendor. If the vendor you need is unreachable directly or does not accept your payment method, connect models through a gateway. Access from Russia with Zukko goes through a gateway, paid by SBP (the payment page adds an 8.5% fee on top), by MasterCard, or in crypto. The balance is shared across tools: the same key works for Claude Code or Cursor.

What it costs

Take a hypothetical first day (the volumes are an assumption for the example): you ask it to explain the project and make a couple of edits, about 300,000 input tokens and 20,000 output tokens. Zukko prices on October 18, 2026, $ per 1M tokens, cache ignored:

Agent sessions usually read a lot, so the real spend depends on the project. Current prices are in GET https://api.zukko.pro/v1/models, and which model suits you, find out on your own tasks. To start, create a key in the dashboard↗.

FAQ

Is opencode free?

The program is open source. You pay for model calls to whichever vendor you connected. Zen and other providers have their own pricing and terms; read them in those services' documentation.

How is opencode different from Claude Code?

Claude Code is built around Claude models, while opencode connects to different vendors. They also differ in commands, settings format and addresses: for Claude Code the address has no /v1, for opencode it does.

Where is the key stored after /connect?

In ~/.local/share/opencode/auth.json. If you want the key only from the environment, put {env:NAME} in the config's apiKey.

Can I keep several providers at once?

Yes. Each is described by its own block in provider, and you can switch models with /models.