OpenCode in Russia: API Setup and First Request

What is needed to launch OpenCode in Russia

OpenCode is a coding agent for the terminal. It reads project files, works with the selected model, and can perform actions in the repository. For the first launch you will need:

• macOS, Linux or Windows with access to one of the official installation methods;
• own API Key BetterToken;
• current Model ID from the BetterToken model catalog;
• a test directory where you can safely test the agent's response.

BetterToken in this scheme is responsible for the external API request. It does not guarantee the availability of the OpenCode site, installation file, GitHub, or updates. From Russia, you can connect to BetterToken API Endpoint without a VPN, but this does not apply to third-party sites and downloads.

How to install OpenCode from the official source

Choose one method. Node.js is only needed for installation via npm.

macOS and Linux: official installer

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

npm

npm install -g opencode-ai

Homebrew

brew install anomalyco/tap/opencode

OpenCode recommends its own tap because the brew install opencode formula that the Homebrew command maintains can be updated later.

Windows

The official documentation suggests Chocolatey or Scoop:

choco install opencode

scoop install opencode

After installation, check that the command is available:

opencode --version

The version should print without command not found. The specific number is not fixed in the article: it changes along with releases.

How /connect and opencode.json work

OpenCode credential and provider settings are stored separately.

• /connect stores the API Key in ~/.local/share/opencode/auth.json.
• Global ~/.config/opencode/opencode.json specifies providers and models for the user.
• opencode.json in the project root changes settings only for this project.

Configuration files are merged. If there is a conflict, the later source overrides the earlier one. For normal local configuration, the following order is important: global config → file from OPENCODE_CONFIG → project opencode.json. Organization-managed settings have a separate highest priority.

1. Save the API Key via /connect

Run OpenCode in the test directory:

mkdir opencode-first-test
cd opencode-first-test
opencode

In TUI run:

/connect

Select Other, enter provider id bettertoken, then paste your API Key into the credential field. Don't add the real key to the prompt, opencode.json, screenshot, or Git.

After saving, exit OpenCode and make sure the provider is registered:

opencode auth list

The command should show provider without revealing the key itself.

2. Add a BetterToken provider

To configure in all projects, create or update:

~/.config/opencode/opencode.json

If provider is only needed in one repository, put opencode.json at its root. Minimum configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/YOUR_MODEL_ID",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

Replace YOUR_MODEL_ID with the exact ID from the current BetterToken directory. The same value must appear in model, the object key models and its name. Do not add the /chat/completions path to the Base URL: OpenCode and the @ai-sdk/openai-compatible package generate the request themselves.

Detailed automatic setup commands and current restrictions for model groups can be found in BetterToken documentation for OpenCode. The article leaves Model ID as a placeholder because the list of available models changes.

3. Check which file takes precedence

Project opencode.json can override the global model or provider. If OpenCode chooses an unexpected endpoint, check in order:

1. ~/.config/opencode/opencode.json;
2. value OPENCODE_CONFIG, if the variable is set;
3. opencode.json in the current project or nearest parent directory to the Git root.

Don't delete files at random. Match the model, provider.bettertoken.options.baseURL, and provider.bettertoken.models fields in all found configurations.

How to execute and test the first request

Restart OpenCode after changing JSON:

opencode

Open the model selection with the command:

/models

Select bettertoken/YOUR_MODEL_ID. Then send a short query whose result is easy to verify:

Верни только JSON: {"tool":"opencode","sum":4}. Не изменяй файлы.

The first request is considered confirmed when four checks match:

• OpenCode returned valid JSON and did not change the files;
• model bettertoken/YOUR_MODEL_ID is selected in TUI;
• a request with the expected model and status appeared in the BetterToken Dashboard;
• the Dashboard shows input, output, applicable cache Tokens, and the corresponding charge.

The Dashboard does not need to be used as a repository for the full prompt or response: the statement is about Token usage and consumption metadata. If the entry did not appear, the response could have come from another provider due to config override.

How to fix common errors

opencode: command not found

Close and reopen the terminal. If you installed via npm, check if the npm global directory is included in PATH. Do not run the second installer until you have figured out where the first binary was installed.

401 or credential error

Execute /connect again and select provider id bettertoken. Check the result via opencode auth list. Don't paste the key into the command line or JSON for the sake of a quick check.

404 or API error

provider.bettertoken.options.baseURL should have a Base URL:

https://www.bettertoken.ai/v1

Do not add /chat/completions. If the URL is correct, restart OpenCode and retry the short request.

model not found

Check the exact Model ID in the current documentation and model catalog. The top-level model field should look like bettertoken/YOUR_MODEL_ID, and provider.bettertoken.models should contain a key with the same YOUR_MODEL_ID.

OpenCode uses a different model or endpoint

This usually means config override. Compare global, OPENCODE_CONFIG and project file. Project settings have higher priority among standard files. After fixing, restart OpenCode completely and check /models and Dashboard again.

FAQ

Do I need to store the API Key in opencode.json?

No. For normal setup use /connect: OpenCode will store the credential in ~/.local/share/opencode/auth.json. The configuration file can be kept without the real key.

What Base URL does OpenCode need?

For OpenAI-compatible provider BetterToken, https://www.bettertoken.ai/v1 is used. This is a Base URL, so /chat/completions is not added manually.

Should I choose global or project opencode.json?

The global file is convenient for a common provider and model. A project file is suitable when the repository needs a different Model ID or set of permissions. If there is a conflict, the project file overrides the global one.

Do I need an OpenCode account for BetterToken provider?

Custom provider uses the credential of the selected API service. BetterToken provides its own API Key, but does not replace the OpenCode website, account or other services. Check the official OpenCode documentation for current requirements of the tool itself.