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

O OpenCode é um assistente de programação open source que permite escrever código no terminal, no IDE ou no ambiente de trabalho. Não guarda o seu código nem o contexto, pelo que é adequado para projetos em que a privacidade é importante. O modo build serve para modificar o projeto, enquanto o modo plan é só de leitura por predefinição e é útil para começar por compreender código desconhecido e organizar as alterações. Pode escolher o serviço de modelos de acordo com as suas necessidades.

Preparação antes da instalação

O script de instalação é a opção mais simples. Precisa de um terminal moderno, ou seja, uma aplicação de terminal que permita executar comandos e trabalhar com os ficheiros do projeto, como WezTerm, Alacritty, Ghostty ou Kitty. No Windows, dê preferência ao WSL, uma ferramenta que permite executar um ambiente Linux no Windows e oferece funcionalidades 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 Linux

Homebrew tap

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

Windows nativo

Gestor de pacotes

choco ou scoop
Ou instale globalmente com npm
Também pode transferir a partir de Releases

Comece pelo script de instalação. Se já estiver habituado a gestores de pacotes, utilize depois os outros comandos indicados.

Tenha também preparado o ID do modelo presente na lista de modelos atual. O ID do modelo é o nome utilizado pelo serviço para identificar com precisão um modelo específico.

Instalar e iniciar pela primeira vez

O comando de instalação mais simples é:

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

Também pode utilizar os seguintes métodos de instalação:

Node.js: npm install -g opencode-ai. Bun, pnpm e Yarn também têm comandos correspondentes para instalação global; consulte a página de apresentação indicada no final.
Homebrew no macOS e Linux: brew install anomalyco/tap/opencode. Utilize este tap, pois é atualizado com maior frequência do que o brew install opencode mantido pela equipa do Homebrew.
Arch Linux: para a versão estável, utilize sudo pacman -S opencode; para uma versão mais recente, pode utilizar opencode-bin do AUR.
Windows: choco install opencode ou scoop install opencode. Também pode utilizar npm install -g opencode-ai ou transferir o ficheiro binário a partir de Releases. O suporte para 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

Na primeira utilização, pode executar /init. Este comando analisa o projeto e cria o ficheiro AGENTS.md na raiz do projeto. Pode adicionar este ficheiro ao Git para manter estas instruções no projeto.

Obter os parâmetros de ligação no OmniProxy

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

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

Ao utilizar /v1/chat/completions, use o pacote npm @ai-sdk/openai-compatible. Neste contexto, Chat Completions é uma interface para pedidos de conversação. Mude para @ai-sdk/openai apenas quando o modelo utilizar /v1/responses. Quando o OmniProxy for utilizado através do caminho de Chat Completions, mantenha o pacote de compatibilidade.

Copie o ID completo a partir da lista atual do OmniProxy, incluindo quaisquer barras. Em 2026-10-09, os dois IDs usados para comparação eram claude-sonnet-5-5 e gpt-6-luna. O gpt-6-luna suporta Chat Completions; em Chat Completions, as chamadas de funções só são suportadas quando reasoning_effort está definido como none. Não copie IDs que não estejam presentes na lista.

Preencher a configuração da ferramenta

Um Provider pode ser entendido como um conjunto de configurações utilizado pelo OpenCode para estabelecer ligação ao serviço de modelos. A documentação de Providers classifica os serviços compatíveis com OpenAI que não aparecem na lista de /connect como Providers personalizados. Um serviço compatível com OpenAI utiliza o mesmo formato de pedidos e pode ser usado pelo mesmo tipo de cliente.

Execute /connect no OpenCode e desloque-se até Other.
Introduza um Provider ID. A configuração abaixo utiliza omniproxy. Escolha um ID fácil de memorizar, porque terá de utilizar o mesmo no ficheiro de configuração.
Introduza a API Key do OmniProxy. Este passo guarda apenas a credencial; o endereço e os modelos ainda têm de ser definidos em opencode.json. A credencial é guardada em ~/.local/share/opencode/auth.json.
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" }
      }
    }
  }
}

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

O ID utilizado em /connect tem de corresponder à chave definida em opencode.json. Não escreva a chave real neste ficheiro. Se não utilizar /connect, também pode referenciar uma variável de ambiente em options.apiKey, por exemplo, {env:NOME_DA_VARIAVEL}. Num teste realizado em 2026-10-09 com o OpenCode 1.18.34, a ligação também funcionou ao escrever a chave diretamente em options.apiKey no projeto, sem utilizar /connect. Se o gateway não validar a chave, este valor pode ser uma sequência de caracteres de preenchimento utilizada apenas localmente. As chaves dentro de models devem usar os IDs completos presentes na lista.

Chave

/connect

Selecione Other no fim da lista
Defina o Provider ID que quiser
É guardado em auth.json

Projeto

opencode.json

A chave provider deve ter o mesmo nome
Em npm, use o pacote compatível
baseURL termina em /v1

Seleção

/models

O modelo aparece na lista
Selecione um antes de fazer a pergunta
Use o ID indicado na lista do gateway

A chave e o endereço ficam em dois locais distintos. O Provider ID tem de ser igual em ambos.

Verificar com uma tarefa real

Execute primeiro uma tarefa real no diretório do projeto. O formato da referência ao modelo é Provider ID/ID do modelo; mantenha quaisquer barras existentes no ID do modelo:

opencode run --model omniproxy/claude-sonnet-5-5 --auto "Explique o que faz um ficheiro que eu indicar, sem alterar ficheiros."

A opção --auto permite que esta execução utilize ferramentas, como a leitura de ficheiros. Num teste realizado em 2026-10-09 com o OpenCode 1.18.34, o conteúdo do ficheiro indicado foi lido. A primeira execução demorou cerca de dois minutos.

Para utilização interativa, execute opencode e selecione o modelo através de /models. Pode utilizar @ para procurar ficheiros. Execute opencode auth list para confirmar as credenciais guardadas através de /connect e consulte depois o registo de chamadas do OmniProxy para confirmar a origem e o ID do modelo.

Arranque

O opencode abre

Primeiro, use cd para ir para o projeto
auth list apresenta o ID
O ficheiro de configuração está no projeto

Tarefa

Leu o código

Pergunte sobre um ficheiro específico
Veja a explicação apresentada
Se estiver errado, use /undo

Registo

Visível no gateway

A origem é OpenCode
O ID do modelo corresponde
Não faça commit da chave

Depois de guardar o ficheiro de configuração, faça ainda uma pergunta real dentro do projeto.

Erros comuns

O OmniProxy não aparece em /models: confirme se o ID de /connect corresponde à chave em opencode.json, se npm está definido como @ai-sdk/openai-compatible e se baseURL termina em /v1.
A credencial desapareceu: execute opencode auth list. Providers como o Bedrock, que dependem de variáveis de ambiente, não aparecem aqui; um Provider personalizado configurado através de /connect deverá estar visível.
As funcionalidades no Windows estão incompletas: utilize o script de instalação dentro do WSL.
O ID do modelo é inválido: volte a copiá-lo a partir da lista atual do OmniProxy e altere a chave correspondente em models.
O pedido está a utilizar a interface errada: para Chat Completions, mantenha @ai-sdk/openai-compatible. Não altere o pacote apenas por causa da interface Responses, exceto se esse modelo no OmniProxy utilizar efetivamente /v1/responses.

Referências oficiais

Para a instalação, consulte a apresentação do OpenCode. Para Providers personalizados, consulte Providers. Os IDs de modelos utilizados nos exemplos podem ser consultados na visão geral dos modelos Claude e em GPT-6 Luna.

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

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

Fontes oficiais · OpenCode ↗