OpenCode API Key: Astra, Grok e configuração de proxy

Muitas dúvidas sobre autenticação no OpenCode parecem iguais, mas se referem a camadas diferentes. A chave de API de um provedor de modelos não é a mesma coisa que o login do OpenCode Go, o fluxo OAuth da xAI ou a senha usada para proteger o opencode web.

Este guia separa essas camadas e apresenta uma configuração funcional de provedor personalizado para a BetterToken, incluindo um exemplo pronto para copiar com gpt-6-astra, ajustes de rede regional para Linux e Astra Linux, autenticação direta do Grok e a forma correta de proteger a interface Web do OpenCode.

O OpenCode evolui rapidamente. Antes de usar em produção, compare os comandos abaixo com a documentação atual do OpenCode e confirme o ID exato do modelo no catálogo de modelos da BetterToken.

Resposta rápida

O que você quer fazer	Local ou comando correto
Salvar interativamente a chave de um provedor	Execute `/connect` dentro do OpenCode
Ver os provedores salvos	Execute `opencode auth list`
Definir provedor personalizado, Base URL e modelos	`opencode.json` ou `opencode.jsonc`
Usar a BetterToken	Base URL: `https://www.bettertoken.ai/v1`
Usar o GPT-6 Astra	ID do modelo: `gpt-6-astra`, se estiver disponível para sua conta
Entrar no OpenCode Go	`/connect` → OpenCode Go → `https://opencode.ai/auth`
Autenticar diretamente com xAI/Grok	`/connect` → xAI → assinatura via OAuth ou API Key
Proteger o OpenCode Web	Defina `OPENCODE_SERVER_PASSWORD` antes de `opencode web`
Usar proxy regional ou corporativo	Defina `HTTP_PROXY`, `HTTPS_PROXY` e `NO_PROXY`

Antes de começar

Prepare o seguinte:

uma instalação recente do OpenCode;
uma API Key separada para testes, em vez de uma chave de produção compartilhada;
o ID exato do modelo exibido no catálogo do provedor;
um repositório pequeno de teste, no qual o agente não possa alterar arquivos importantes;
acesso pelo terminal ao instalador do OpenCode e ao endpoint da API.

Trate uma API Key como uma senha. Não cole uma chave real em prompts, capturas de tela, issues, artigos ou repositórios Git.

Instale o OpenCode

O instalador oficial funciona no macOS e no Linux:

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

Também é possível instalar pelo npm:

npm install -g opencode-ai

No Windows, o OpenCode recomenda o WSL para obter a melhor compatibilidade. Chocolatey e Scoop também aparecem como opções documentadas:

choco install opencode

scoop install opencode

Verifique a instalação:

opencode --version

O terminal deve exibir um número de versão. Se aparecer command not found, reabra o terminal e confira se o diretório de instalação está incluído em PATH.

Entenda as quatro camadas de autenticação

1. API Key do provedor

Essa chave autoriza chamadas à BetterToken, xAI, OpenAI ou a outro provedor de modelos. O OpenCode pode salvá-la com /connect ou lê-la de uma variável de ambiente referenciada no arquivo de configuração.

2. Autenticação do OpenCode Go ou OpenCode Zen

OpenCode Go e Zen são serviços de modelos operados pelo OpenCode. O fluxo abre https://opencode.ai/auth, onde você entra na conta, conclui a configuração de cobrança, copia uma API Key e a cola novamente em /connect.

Essa chave não tem relação com a chave da BetterToken.

3. Autenticação da xAI/Grok

O fluxo atual de provedores do OpenCode aceita uma assinatura xAI compatível por OAuth com código de dispositivo ou uma API Key pré-paga da xAI. Essa é uma conexão direta com a xAI, não com a BetterToken.

4. Senha do OpenCode Web

OPENCODE_SERVER_PASSWORD protege o servidor HTTP local e a interface no navegador do OpenCode por autenticação básica. Ela não autoriza chamadas de modelo e não substitui a API Key de um provedor.

Como definir uma API Key no OpenCode

O OpenCode aceita JSON e JSONC. Os exemplos oficiais usam com frequência opencode.json; o JSONC é útil quando você precisa incluir comentários. O ponto principal é que as credenciais e as definições do provedor são coisas separadas.

Método 1: salve a chave com `/connect`

Inicie o OpenCode em um diretório seguro de teste:

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

Dentro da TUI, execute:

/connect

Para a BetterToken:

Selecione Other.
Digite o ID de provedor bettertoken.
Cole sua API Key da BetterToken no campo de credencial.
Saia ou reinicie o OpenCode depois de adicionar a configuração do provedor.

O OpenCode salva as credenciais adicionadas por /connect em:

~/.local/share/opencode/auth.json

Confirme que o provedor foi registrado sem exibir o segredo:

opencode auth list

O ID usado em /connect deve ser exatamente igual ao ID presente na configuração. Se você digitou bettertoken, a chave do provedor no arquivo também deve ser bettertoken.

Método 2: configure `opencode.json` ou `opencode.jsonc`

Use o arquivo global quando o provedor deve estar disponível em todos os projetos:

~/.config/opencode/opencode.json

Use um opencode.json ou opencode.jsonc no projeto quando apenas um repositório precisar de um modelo ou endpoint específico.

O exemplo abaixo usa a BetterToken e o ID atual de API gpt-6-astra:

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

Antes de usar, confirme que gpt-6-astra aparece no catálogo atual da BetterToken e no grupo de acesso da sua conta. Se o catálogo mostrar outro ID, substitua tanto bettertoken/gpt-6-astra quanto a chave gpt-6-astra dentro de models.

Não acrescente /chat/completions à Base URL. O adaptador monta o caminho da requisição automaticamente.

Use uma variável de ambiente em vez de `/connect`

No macOS ou Linux:

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

No PowerShell:

$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"

Depois, referencie a variável nas opções do provedor:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/gpt-6-astra",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1",
        "apiKey": "{env:BETTERTOKEN_API_KEY}"
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        }
      }
    }
  }
}

Isso é mais seguro do que gravar o segredo literalmente no arquivo JSON. Se a variável não existir, o OpenCode a substitui por uma string vazia, o que normalmente causa um erro 401.

Por que o OpenCode pode ignorar sua configuração

O OpenCode combina várias fontes de configuração. Quando o mesmo campo entra em conflito, as fontes posteriores substituem as anteriores. A ordem mais relevante é:

padrões remotos da organização;
configuração global em ~/.config/opencode/opencode.json;
arquivo personalizado indicado por OPENCODE_CONFIG;
opencode.json ou opencode.jsonc do projeto;
conteúdo inline em OPENCODE_CONFIG_CONTENT;
configurações administradas, que podem substituir os arquivos do usuário.

Se o OpenCode selecionar o modelo ou endpoint errado, não apague arquivos ao acaso. Procure todas as configurações ativas e compare:

o valor de model no nível superior;
provider.bettertoken.options.baseURL;
as chaves de modelo em provider.bettertoken.models;
OPENCODE_CONFIG e OPENCODE_CONFIG_CONTENT no shell atual.

Reinicie o OpenCode depois de alterar configurações de provedor.

OpenCode Astra: nome de modelo ou Astra Linux?

A busca “OpenCode Astra” pode significar duas coisas diferentes.

Use o GPT-6 Astra no OpenCode

Se você se refere ao modelo da OpenAI, use o ID exato da API: gpt-6-astra. Com o provedor BetterToken configurado acima, selecione:

bettertoken/gpt-6-astra

Abra o seletor de modelos dentro do OpenCode:

/models

Se o modelo não aparecer, confira o ID do provedor, o mapa models, seu grupo de acesso na BetterToken e o catálogo atual. Não tente adivinhar um ID a partir do nome exibido.

Execute o OpenCode no Astra Linux

A documentação do OpenCode lista métodos de instalação para Linux, mas não publica uma promessa separada de suporte específico ao Astra Linux. Trate o Astra Linux como um ambiente Linux e verifique a máquina real, em vez de pressupor compatibilidade.

Confira a arquitetura e as ferramentas necessárias:

uname -m
command -v curl
command -v bash

Depois, teste separadamente o instalador e as rotas da API. Conseguir acessar a API do modelo não garante que o instalador do OpenCode, o registro npm, o GitHub ou o servidor de atualizações também estejam acessíveis.

Para um proxy padrão:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,::1
opencode

NO_PROXY é importante porque a TUI se comunica com um servidor HTTP local do OpenCode. Enviar tráfego de loopback pelo proxy pode gerar ciclos de conexão ou uma interface que parece travada.

Se a sua organização usa uma autoridade certificadora privada:

export NODE_EXTRA_CA_CERTS=/etc/company/ca.pem
opencode

Não grave credenciais reais de proxy em scripts de shell compartilhados. Use o gerenciador de segredos da organização ou uma configuração de ambiente protegida.

Autenticação do Grok no OpenCode: xAI direta ou gateway?

Conexão direta com a xAI

Execute:

/connect

Selecione xAI. A documentação atual do OpenCode apresenta duas formas de autenticação:

uma assinatura xAI compatível por OAuth com código de dispositivo;
uma API Key da xAI inserida manualmente a partir do console da xAI.

Depois de autorizar, execute:

/models

e selecione um modelo Grok disponível.

Grok pela BetterToken ou por outro gateway

Um gateway personalizado só funciona se ele realmente disponibilizar um modelo Grok válido e o protocolo correto naquele momento. Não invente um ID do Grok nem suponha que todo gateway compatível com OpenAI oferece modelos da xAI.

Consulte primeiro o catálogo ativo do provedor. Se o Grok não estiver listado, use o provedor xAI direto do OpenCode. Plugins comunitários, como extensões de autenticação do Grok, são diferentes do fluxo oficial e devem ser avaliados quanto a manutenção, permissões e tratamento de credenciais antes da instalação.

Autenticação do OpenCode Go

OpenCode Go não é um comando que autentica qualquer provedor. É um serviço de assinatura do próprio OpenCode.

Para conectá-lo:

Execute /connect.
Escolha OpenCode Go.
Abra https://opencode.ai/auth.
Entre, conclua a cobrança se necessário e copie a chave gerada.
Cole a chave novamente no OpenCode.
Execute /models para escolher um modelo incluído no plano.

Use esse fluxo apenas quando quiser utilizar o OpenCode Go. Para a BetterToken, mantenha o ID e a chave do provedor em bettertoken.

Senha do OpenCode Web: use a variável de ambiente

Uma busca comum é opencode web password, e alguns exemplos sugerem incorretamente uma opção -p para a senha. O método documentado é a variável de ambiente OPENCODE_SERVER_PASSWORD.

No macOS ou Linux:

OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' opencode web

Para definir também um nome de usuário personalizado:

OPENCODE_SERVER_USERNAME='developer' \
OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' \
opencode web

No PowerShell:

$env:OPENCODE_SERVER_USERNAME = "developer"
$env:OPENCODE_SERVER_PASSWORD = "replace-with-a-strong-password"
opencode web

O nome de usuário padrão é opencode. Sem senha, o uso estritamente local em 127.0.0.1 pode ser aceitável, mas qualquer acesso pela rede deve ser protegido. Não vincule o serviço a 0.0.0.0 nem o exponha por túnel antes de configurar autenticação e controles de rede.

A senha Web protege o servidor do OpenCode. Ela não protege sua conta no provedor caso a API Key vaze em outro lugar.

Verifique a primeira requisição

Reinicie o OpenCode depois de editar o JSON:

opencode

Abra o seletor de modelos:

/models

Escolha bettertoken/gpt-6-astra e envie um prompt pequeno e fácil de verificar:

Retorne apenas este JSON e não modifique nenhum arquivo: {"tool":"opencode","sum":4}

Uma configuração bem-sucedida deve atender a todos estes pontos:

o OpenCode retorna um JSON válido;
nenhum arquivo do projeto é alterado;
o modelo selecionado é bettertoken/gpt-6-astra;
uma requisição correspondente aparece no painel da BetterToken;
modelo, status, tokens de entrada, tokens de saída e cobrança parecem coerentes.

Se o OpenCode responder, mas nenhuma requisição aparecer na BetterToken, uma configuração de prioridade maior pode estar roteando a chamada para outro provedor.

Solução de problemas

Erro `401` ou de credencial

Execute /connect novamente e use o ID bettertoken.
Execute opencode auth list.
Se estiver usando {env:BETTERTOKEN_API_KEY}, verifique apenas se a variável existe, sem imprimir o segredo.
Confirme que a chave está ativa e tem saldo ou permissões suficientes.

Erro `404` ou de caminho da API

A Base URL da BetterToken deve ser:

https://www.bettertoken.ai/v1

Não acrescente /chat/completions manualmente.

`model not found`

Confirme o ID atual exato no catálogo de modelos. O valor de model no nível superior e a chave em models devem corresponder ao provedor e ao modelo que você deseja chamar.

Endpoint ou modelo errado

Verifique as configurações global, personalizada, do projeto, inline e administrada. Depois, reinicie o OpenCode e selecione o modelo novamente com /models.

O OpenCode trava quando o proxy está ativo

Garanta que os endereços de loopback estejam excluídos:

export NO_PROXY=localhost,127.0.0.1,::1

O OpenCode Web retorna `Unauthorized`

Confirme se o navegador está usando o nome de usuário e a senha configurados. Verifique também se ficou um valor antigo de OPENCODE_SERVER_PASSWORD no ambiente do shell ou se algum processo cliente herdou outro valor.

`opencode: command not found`

Reabra o terminal, confira o PATH e execute o comando do gerenciador de pacotes que mostra o diretório global de binários. Evite instalar o mesmo executável por vários gerenciadores até saber qual deles está ativo.

Perguntas frequentes

Como definir uma API Key no OpenCode?

O método interativo recomendado é /connect. Para um provedor personalizado, escolha Other, informe o ID do provedor e cole a chave. Ainda será necessário definir o provedor e os modelos em opencode.json ou opencode.jsonc.

O arquivo se chama `opencode.json` ou `opencode.jsonc`?

O OpenCode aceita JSON e JSONC. Use JSONC quando precisar de comentários. Mantenha apenas uma configuração de projeto ativa, a menos que você entenda deliberadamente como várias fontes são combinadas.

Onde o OpenCode armazena as API Keys?

As credenciais adicionadas por /connect ficam em ~/.local/share/opencode/auth.json. Não publique, sincronize nem faça commit desse arquivo.

Posso colocar a API Key diretamente na configuração?

O OpenCode aceita options.apiKey, mas gravar um segredo literal em um arquivo JSON versionado é arriscado. Prefira /connect, {env:VARIABLE_NAME} ou {file:path/to/secret}.

A autenticação do OpenCode Go é igual à autenticação do provedor?

Não. OpenCode Go é um serviço separado do OpenCode. A chave da BetterToken, xAI ou de outro provedor continua independente.

Como definir uma senha para o OpenCode Web?

Defina OPENCODE_SERVER_PASSWORD antes de executar opencode web. O método documentado usa uma variável de ambiente, e não uma opção genérica -p de senha.

Como autenticar o Grok no OpenCode?

Execute /connect, escolha xAI e selecione o fluxo OAuth de assinatura compatível ou a entrada manual de uma API Key. Um gateway só é válido quando realmente lista um modelo Grok.

“OpenCode Astra” significa GPT-6 Astra ou Astra Linux?

Pode significar ambos. Para o modelo, use gpt-6-astra. Para o Astra Linux, siga as verificações de instalação e rede do Linux e valide a compilação específica da distribuição.

Preciso de VPN para usar o OpenCode da Rússia?

Não existe uma resposta única, porque downloads de instalação, GitHub, npm, o site do OpenCode e a API do modelo são rotas de rede diferentes. Teste cada rota separadamente e use configurações corporativas ou regionais em conformidade quando necessário.