OpenCode na Rússia: configuração da API e primeira solicitação

O que é necessário para iniciar o OpenCode na Rússia

OpenCode é um agente de programação para terminal. Ele lê arquivos do projeto, trabalha com o modelo escolhido e pode executar ações no repositório. Para o primeiro início, você precisa de:

• macOS, Linux ou Windows com acesso a uma instalação oficial;
• sua própria API Key BetterToken;
• o Model ID atual do catálogo BetterToken;
• um diretório de teste para verificar a resposta com segurança.

O BetterToken cuida da solicitação de API externa nesse cenário. Ele não garante disponibilidade do site OpenCode, instalador, GitHub ou atualizações. Da Rússia, você pode conectar-se ao BetterToken API Endpoint sem VPN; isso não se aplica a sites e downloads de terceiros.

Instalar o OpenCode da fonte oficial

Escolha um método. Node.js só é necessário para instalação por npm.

macOS e Linux: instalador oficial

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

npm

npm install -g opencode-ai

Homebrew

brew install anomalyco/tap/opencode

O OpenCode recomenda seu próprio tap porque a fórmula brew install opencode mantida pelo Homebrew pode mudar.

Windows

A documentação oficial sugere Chocolatey ou Scoop:

choco install opencode

scoop install opencode

Depois confira se o comando está disponível:

opencode --version

A versão deve aparecer sem command not found. O artigo não fixa um número porque ele muda com os lançamentos.

Como /connect e opencode.json funcionam

O OpenCode guarda credential e configuração de provider separadamente.

• /connect salva a API Key em ~/.local/share/opencode/auth.json.
• ~/.config/opencode/opencode.json define providers e modelos globais.
• opencode.json na raiz altera apenas aquele projeto.

Os arquivos são mesclados. Em conflitos, uma fonte posterior substitui a anterior. Na configuração local comum, a ordem é: configuração global → arquivo de OPENCODE_CONFIG → opencode.json do projeto. Configurações gerenciadas pela organização têm prioridade máxima separada.

1. Salvar a API Key com /connect

Inicie o OpenCode no diretório de teste:

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

Na TUI, execute:

/connect

Escolha Other, informe o provider id bettertoken e cole sua API Key no campo credential. Não adicione a chave real ao prompt, opencode.json, captura de tela ou Git.

Depois de salvar, saia do OpenCode e confirme o provider:

opencode auth list

O comando deve mostrar o provider sem revelar a chave.

2. Adicionar o provider BetterToken

Para todos os projetos, crie ou atualize:

~/.config/opencode/opencode.json

Para um único repositório, coloque opencode.json na raiz. Configuração mínima:

{
  "$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"
        }
      }
    }
  }
}

Troque YOUR_MODEL_ID pelo ID exato do catálogo atual. O mesmo valor deve estar em model, na chave de models e em name. Não acrescente /chat/completions: OpenCode e @ai-sdk/openai-compatible montam a solicitação.

Os comandos detalhados de configuração automática e limites atuais estão na documentação BetterToken para OpenCode. O Model ID fica como marcador porque os modelos disponíveis mudam.

3. Verificar qual arquivo tem prioridade

O opencode.json do projeto pode substituir o modelo ou provider global. Se o OpenCode escolher endpoint inesperado, confira:

1. ~/.config/opencode/opencode.json;
2. OPENCODE_CONFIG, se estiver definido;
3. opencode.json do projeto atual ou do diretório pai mais próximo até a raiz Git.

Não apague arquivos ao acaso. Compare model, provider.bettertoken.options.baseURL e provider.bettertoken.models em todas as configurações encontradas.

Executar e testar a primeira solicitação

Reinicie o OpenCode após mudar o JSON:

opencode

Abra a seleção de modelos:

/models

Selecione bettertoken/YOUR_MODEL_ID e envie uma consulta curta:

Retorne apenas JSON: {"tool":"opencode","sum":4}. Não modifique arquivos.

A primeira solicitação está confirmada quando:

• OpenCode retorna JSON válido sem alterar arquivos;
• bettertoken/YOUR_MODEL_ID está selecionado na TUI;
• aparece uma solicitação com modelo e status esperados no BetterToken Dashboard;
• o Dashboard mostra Token de entrada, saída, cache aplicável e cobrança correspondente.

O Dashboard não precisa guardar prompt ou resposta completos: a verificação é de metadados de consumo. Se não houver registro, a resposta pode ter vindo de outro provider por override de configuração.

Corrigir erros comuns

opencode: command not found

Feche e reabra o terminal. Em instalação npm, confira se o diretório global está em PATH. Não rode outro instalador antes de saber onde o primeiro binário foi instalado.

401 ou erro de credential

Execute /connect novamente e escolha bettertoken. Verifique com opencode auth list. Não cole a chave na linha de comando ou JSON para testar.

404 ou erro de API

provider.bettertoken.options.baseURL deve conter:

https://www.bettertoken.ai/v1

Não adicione /chat/completions. Se a URL estiver correta, reinicie o OpenCode e repita a solicitação curta.

model not found

Confira o Model ID na documentação e catálogo atuais. O campo model deve ser bettertoken/YOUR_MODEL_ID, e provider.bettertoken.models deve conter a mesma YOUR_MODEL_ID.

OpenCode usa outro modelo ou endpoint

Isso normalmente indica override de configuração. Compare arquivo global, OPENCODE_CONFIG e arquivo do projeto. O projeto tem prioridade maior entre arquivos padrão. Depois da correção, reinicie completamente o OpenCode e confira /models e Dashboard.

Perguntas frequentes

Preciso guardar a API Key em opencode.json?

Não. Use /connect: OpenCode grava o credential em ~/.local/share/opencode/auth.json. O arquivo de configuração pode ficar sem a chave real.

Qual Base URL o OpenCode precisa?

Para o provider OpenAI-compatible BetterToken, use https://www.bettertoken.ai/v1. É uma Base URL, portanto não adicione /chat/completions manualmente.

Escolho opencode.json global ou do projeto?

O global é útil para provider e modelo comuns. O arquivo de projeto serve para outro Model ID ou permissões. Em conflito, o projeto substitui o global.

Preciso de conta OpenCode para o provider BetterToken?

Custom provider usa o credential do serviço de API escolhido. BetterToken fornece sua própria API Key, mas não substitui site, conta ou outros serviços OpenCode. Confira requisitos atuais na documentação oficial do OpenCode.