Instalação e Primeira Configuração

Iniciante⏱30 min📖3 min de leituraLição 2 de 5

Instalação e Primeira Configuração

Instale o OpenCode em seu sistema e configure-o com seu primeiro provedor LLM. Configure chaves de API, verifique a instalação e execute seu primeiro comando.

Pré-requisitos

Antes de instalar o OpenCode, certifique-se de ter:

Requisito	Versão Mínima	Como Verificar
Node.js	18.0+	`node --version`
npm	8.0+	`npm --version`
Git	2.0+	`git --version`

ℹ️Nota

OpenCode é uma aplicação Node.js distribuída via npm. Ele executa em macOS, Linux e Windows.

Instalação

Usando npm (Recomendado)

bash

npm install -g opencode

Usando yarn

bash

yarn global add opencode

Usando pnpm

bash

pnpm add -g opencode

Verificar Instalação

bash

opencode --version

Saída esperada:

opencode v1.x.x

💡Dica

Se você vir "command not found", certifique-se de que o diretório global do npm está em seu PATH.

Configuração Inicial

Passo 1: Criar Diretório de Configuração

bash

mkdir -p .opencode

Passo 2: Criar opencode.json

Crie opencode.json na raiz do seu projeto:

json

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Assistente de codificação de propósito geral"
    }
  }
}

Passo 3: Configurar Chaves de API

Crie um arquivo .env na raiz do seu projeto:

bash

# OpenAI
OPENAI_API_KEY=sk-sua-chave-api-aqui

# Anthropic (opcional)
ANTHROPIC_API_KEY=sk-ant-sua-chave-api-aqui

# Google (opcional)
GOOGLE_API_KEY=sua-chave-api-google-aqui

⚠️Aviso

Nunca comprometa chaves de API no controle de versão. Adicione .env ao seu arquivo .gitignore.

Configuração de Provedores

OpenAI

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o"
    }
  }
}

Anthropic

json

{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

Google

json

{
  "providers": {
    "google": {
      "apiKey": "${GOOGLE_API_KEY}",
      "model": "gemini-pro"
    }
  }
}

Primeira Execução

Iniciar OpenCode

bash

opencode

Você deve ver:

OpenCode v1.x.x
Type your message or /help for commands
>

Testar a Conexão

Digite uma mensagem simples:

> Olá, você pode me ajudar com meu código?

Se bem-sucedido, a IA responderá com uma saudação e perguntará como pode ajudar.

Localizações de Arquivos de Configuração

O OpenCode procura configuração nesta ordem:

Prioridade	Localização	Finalidade
1	`.opencode/config.json`	Específico do projeto (preferido)
2	`opencode.json`	Específico do projeto (legado)
3	`~/.config/opencode/config.json`	Padrões do usuário

💡Dica

Use .opencode/config.json para projetos em equipe. Você pode versionar seletivamente enquanto mantém dados sensíveis em .env.

Comandos Básicos

Comando	Descrição
`opencode`	Iniciar sessão interativa
`opencode --version`	Mostrar versão
`opencode --help`	Mostrar ajuda
`opencode config`	Abrir configuração
`opencode providers`	Listar provedores disponíveis

Solução de Problemas

Problemas Comuns

Problema	Causa	Solução
"Command not found"	npm PATH não configurado	Execute `npm config get prefix` e adicione ao PATH
"Invalid API key"	Formato de chave incorreto	Verifique se a chave começa com `sk-` (OpenAI) ou `sk-ant-` (Anthropic)
"Rate limit exceeded"	Muitas solicitações	Aguarde ou atualize seu plano de API
"Model not found"	Nome do modelo incorreto	Verifique a documentação do provedor para nomes de modelos válidos