Instalação do OpenCode e configuração do OmniProxy

O OpenCode é um assistente de programação de código aberto que permite escrever código pelo terminal, pela IDE ou pelo aplicativo para desktop. Ele também não armazena seu código nem seu contexto, sendo adequado para projetos que priorizam a privacidade. O modo build é usado para modificar o projeto, enquanto plan é somente leitura por padrão, sendo útil para primeiro entender um código desconhecido e organizar as alterações. Você pode escolher o serviço de modelos de acordo com suas necessidades.

Preparação antes da instalação

O script de instalação é a opção mais simples. Você precisa de um terminal moderno, ou seja, um programa de terminal capaz de executar comandos e manipular os arquivos do projeto, como WezTerm, Alacritty, Ghostty ou Kitty. No Windows, dê preferência ao WSL, uma ferramenta que executa um ambiente Linux dentro do Windows e oferece recursos e desempenho mais completos.

Mais fácil

Script de instalação

• curl opencode.ai/install
• Use diretamente no macOS e Linux
• No Windows, recomenda-se WSL

macOS e Linux

Homebrew tap

• anomalyco/tap/opencode
• É atualizado com mais frequência que a fórmula
• Também há um pacote para Arch

Windows nativo

Gerenciador de pacotes

• choco ou scoop
• Ou instale globalmente com npm
• Também é possível baixar em Releases

Tenha também em mãos o ID do modelo disponível na lista atual de modelos. O ID do modelo é o nome usado pelo serviço para identificar precisamente um modelo específico.

Instalação e primeira inicialização

O comando de instalação mais simples é:

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

Você também pode usar os seguintes métodos de instalação:

• Node.js: npm install -g opencode-ai. Bun, pnpm e Yarn também têm comandos correspondentes de instalação global; consulte a página de apresentação indicada no final deste guia.
• Homebrew no macOS e no Linux: brew install anomalyco/tap/opencode. Use esse tap, pois ele é atualizado com mais frequência do que o brew install opencode, mantido pela equipe do Homebrew.
• Arch Linux: para a versão estável, use sudo pacman -S opencode; para uma versão mais recente, você pode usar o pacote opencode-bin do AUR.
• Windows: use choco install opencode ou scoop install opencode. Outra opção é npm install -g opencode-ai. Também é possível baixar o arquivo binário em Releases. O suporte à instalação com Bun no Windows ainda está em desenvolvimento.

Entre no diretório do projeto e inicie o OpenCode:

cd /path/to/project
opencode

No primeiro uso, você pode executar /init. Esse comando analisa o projeto e cria um arquivo AGENTS.md na raiz. O arquivo pode ser incluído no Git para manter essas instruções junto ao projeto.

Obtenção dos parâmetros de conexão no OmniProxy

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: copie o ID completo da lista atual de modelos do OmniProxy

baseURL é o endereço do serviço, API Key é a credencial de acesso e Model ID é o nome completo do modelo.

Ao usar /v1/chat/completions, utilize o pacote npm @ai-sdk/openai-compatible. Nesse caso, Chat Completions é uma interface para solicitações de conversa. Altere para @ai-sdk/openai somente quando o modelo usar /v1/responses. Ao usar o OmniProxy pela rota de chat completions, mantenha o pacote de compatibilidade.

Copie integralmente o ID do modelo na lista atual do OmniProxy, preservando também as barras. Em 2026-10-09, dois IDs usados para comparação eram claude-sonnet-5-5 e gpt-6-luna. O gpt-6-luna oferece suporte a Chat Completions; nesse tipo de solicitação, chamadas de função são compatíveis somente quando reasoning_effort está definido como none. Não use IDs que não estejam na lista.

Preenchimento da configuração da ferramenta

Um Provider pode ser entendido como um conjunto de configurações que o OpenCode usa para se conectar a um serviço de modelos. A documentação de Provider trata como Provider personalizado qualquer serviço compatível com OpenAI que não esteja na lista de /connect. Um serviço compatível com OpenAI utiliza o mesmo formato de solicitação e pode ser acessado pela mesma categoria de clientes.

1. Execute /connect no OpenCode e role até Other.
2. Digite um Provider ID. O exemplo abaixo usa omniproxy. Escolha um ID fácil de lembrar, pois você deverá usar o mesmo valor no arquivo de configuração.
3. Digite a API Key do OmniProxy. Essa etapa armazena apenas a credencial; o endereço e os modelos ainda precisam ser definidos em opencode.json. A credencial fica armazenada em ~/.local/share/opencode/auth.json.
4. Crie ou modifique opencode.json no diretório do projeto:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

5. Execute /models. O Provider personalizado e os modelos aparecerão na lista.

O ID informado em /connect deve ser idêntico à chave definida em opencode.json. Não coloque a chave real nesse arquivo. Caso não use /connect, você também pode usar a sintaxe de variável de ambiente em options.apiKey, por exemplo, {env:NOME_DA_VARIAVEL}. Em 2026-10-09, usando o OpenCode 1.18.34, também foi possível estabelecer conexão colocando a chave diretamente em options.apiKey no projeto, sem passar por /connect. Se o gateway não validar a chave, esse campo pode conter uma sequência de caracteres de preenchimento usada somente na máquina local. As chaves em models devem usar os IDs completos exibidos na lista.

Chave

/connect

• Selecione Other no final da lista
• Defina seu próprio Provider ID
• Fica armazenada em auth.json

Projeto

opencode.json

• A chave provider deve ter o mesmo nome
• Use o pacote de compatibilidade do npm
• baseURL deve terminar em /v1

Seleção

/models

• O modelo aparece na lista
• Selecione um antes de perguntar
• Use o ID exibido na lista do gateway

Verificação com uma tarefa real

Primeiro, execute uma tarefa real no diretório do projeto. O formato da referência ao modelo é Provider ID/ID do modelo, e as barras presentes no ID do modelo devem ser preservadas:

opencode run --model omniproxy/claude-sonnet-5-5 --auto "Explique o que faz um arquivo que eu especificar, sem modificar o arquivo."

A opção --auto permite que essa execução use ferramentas como a leitura de arquivos. Em 2026-10-09, usando o OpenCode 1.18.34, o conteúdo do arquivo especificado foi lido. A primeira execução levou aproximadamente dois minutos.

Para usar o modo interativo, execute opencode e selecione o modelo com /models. No uso documentado, você pode pesquisar arquivos com @. Use opencode auth list para confirmar as credenciais registradas por /connect e depois verifique, no histórico de chamadas do OmniProxy, a origem e o ID do modelo.

Inicialização

opencode abre

• Primeiro, use cd para ir ao projeto
• O ID aparece em auth list
• O arquivo de configuração está no projeto

Tarefa

Ele leu o código

• Pergunte sobre um arquivo específico
• Confira a explicação
• Se estiver incorreto, use /undo

Registros

Visível no gateway

• A origem é OpenCode
• O ID do modelo corresponde
• Não envie a chave ao repositório

Erros comuns

• O OmniProxy não aparece em /models: verifique se o ID usado em /connect corresponde à chave em opencode.json, se npm está definido como @ai-sdk/openai-compatible e se baseURL termina com /v1.
• A credencial desapareceu: execute opencode auth list. Providers como o Bedrock, que dependem de variáveis de ambiente, não aparecem nessa lista; um Provider personalizado configurado por /connect deve aparecer.
• Os recursos no Windows estão incompletos: use o script de instalação dentro do WSL.
• O ID do modelo é inválido: copie-o novamente da lista atual do OmniProxy e atualize a chave correspondente em models.
• A solicitação está usando a interface errada: para chat completions, mantenha @ai-sdk/openai-compatible. Não troque o pacote por causa da interface Responses, a menos que esse modelo no OmniProxy realmente use /v1/responses.

Referências oficiais

Para a instalação, consulte a apresentação do OpenCode. Para Providers personalizados, consulte Providers. Para os IDs de modelo usados nos exemplos, consulte a visão geral dos modelos Claude e GPT-6 Luna.

Substitua todos os espaços reservados por valores de sua própria configuração do OmniProxy. Nunca publique uma chave real.

Um resultado salvo ou HTTP 200 sozinho não prova compatibilidade total com o Agente. Verifique a origem e o modelo no registro de chamadas do OmniProxy.

Fontes oficiais · OpenCode ↗