Instalar o OpenCode é apenas o primeiro passo.

Depois de experimentar a ferramenta, é natural começar a fazer perguntas mais específicas: qual modelo devo usar? Como faço o OpenCode seguir as regras do meu projeto? Posso controlar o que o agente pode alterar? Como evitar que determinados comandos sejam executados automaticamente?

É justamente aí que entra a configuração.

Neste guia, vamos configurar o OpenCode de forma progressiva, começando pelo básico e chegando a um ambiente de desenvolvimento mais controlado e personalizado.

Você vai aprender a trabalhar com:

• opencode.json;
• modelos e provedores;
• AGENTS.md;
• comando /init;
• permissões;
• Git;
• e um fluxo de trabalho prático para usar o OpenCode em um projeto real.

A ideia não é criar uma configuração complicada. É entender o que cada peça faz e quando realmente vale a pena utilizá-la.

Nota: opções e formatos de configuração podem mudar entre versões do OpenCode. Os exemplos deste artigo seguem a documentação atual consultada em setembro de 2026.

---

O que você pode configurar no OpenCode?

Antes de começar a editar arquivos, vale entender o que estamos tentando configurar.

De forma simplificada, podemos pensar no OpenCode assim:

                         OpenCode
                            │
            ┌───────────────┼────────────────┐
            │               │                │
         Modelos        Instruções       Permissões
            │               │                │
       Provedores       AGENTS.md        Ferramentas
            │               │                │
            └───────────────┼────────────────┘
                            │
                       Seu projeto

Esses componentes cumprem funções diferentes.

Modelos

Determinam qual modelo de IA será utilizado para trabalhar no projeto.

O OpenCode oferece integração com diversos provedores e também permite trabalhar com modelos locais. O comando /models permite consultar os modelos disponíveis no ambiente atual.

opencode.json

É o arquivo usado para configurar o comportamento do OpenCode.

Entre outras possibilidades, ele pode definir modelo padrão, provedores e permissões. O OpenCode suporta tanto JSON quanto JSONC, que permite comentários no arquivo.

AGENTS.md

É onde colocamos instruções específicas para o agente trabalhar dentro de determinado projeto.

Ele pode conter informações sobre arquitetura, comandos, padrões de código, testes e outras regras importantes para aquele repositório.

Permissões

Determinam quais ações podem ser executadas automaticamente, quais precisam da sua aprovação e quais devem ser bloqueadas.

---

Onde ficam as configurações do OpenCode?

Existem dois níveis especialmente importantes para quem está começando.

Configuração global

A configuração global fica em:

~/.config/opencode/opencode.json

Ela pode ser usada para preferências que você deseja manter entre diferentes projetos, como modelos, provedores e permissões.

No Windows, o caminho efetivo pode variar conforme o ambiente utilizado. Por isso, é melhor consultar a documentação da versão instalada quando estiver trabalhando fora do caminho padrão.

Configuração por projeto

Para configurações específicas de um projeto, coloque:

opencode.json

na raiz do projeto.

Exemplo:

meu-projeto/
├── opencode.json
├── AGENTS.md
├── src/
├── tests/
└── package.json

A configuração específica do projeto tem precedência sobre a configuração global. As configurações são combinadas, e valores posteriores substituem valores conflitantes.

Isso permite ter, por exemplo, um modelo padrão global e uma configuração diferente para um projeto específico.

---

Criando seu primeiro opencode.json

Vamos começar com o arquivo mais simples possível:

{
  "$schema": "https://opencode.ai/config.json"
}

O campo $schema ajuda editores compatíveis a oferecer validação e sugestões para a configuração.

Neste momento, ainda não estamos alterando praticamente nada.

E isso é proposital.

Antes de copiar dezenas de opções da documentação, é melhor entender quais configurações realmente fazem diferença no seu fluxo de trabalho.

---

Como escolher o modelo usado pelo OpenCode

Uma das configurações mais importantes é o modelo.

Mas existe uma distinção fundamental:

OpenCode não é o modelo de IA.

O OpenCode é o ambiente que permite trabalhar com agentes e ferramentas. O modelo é o componente responsável pela geração e pelo raciocínio.

Por isso, você pode mudar o modelo sem precisar trocar a ferramenta.

Consultando os modelos disponíveis

Dentro do OpenCode, use:

/models

O comando abre a seleção de modelos disponíveis no ambiente atual.

Também é possível escolher um modelo diretamente pela linha de comando com --model em determinadas execuções.

Definindo um modelo padrão

Você também pode definir um modelo no opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "provider/model"
}

O identificador segue o formato:

provider_id/model_id

Por exemplo, a documentação atual utiliza identificadores nesse formato para modelos configurados no OpenCode.

Como escolher um modelo?

Em vez de procurar pelo modelo “mais poderoso”, considere o que realmente importa para sua tarefa:

• qualidade na geração de código;
• capacidade de utilizar ferramentas;
• tamanho do contexto;
• velocidade;
• custo;
• disponibilidade;
• possibilidade de execução local.

Um modelo excelente para uma tarefa pode não ser necessariamente a melhor opção para outra.

---

E os modelos locais?

Se você chegou até aqui depois de acompanhar nosso artigo sobre OpenCode + Ollama, já sabe que também é possível trabalhar com modelos locais.

O OpenCode suporta modelos locais e integrações com diferentes provedores.

Neste artigo, não vamos repetir o tutorial de Ollama.

A ideia é manter cada conteúdo com uma função específica:

O post #6 ensina a executar IA localmente. Este post ensina a configurar o OpenCode para trabalhar de acordo com o seu projeto.

Se você ainda não viu o tutorial, vale voltar a ele antes de continuar.

---

opencode.json e AGENTS.md: qual é a diferença?

Essa é provavelmente a distinção mais importante deste artigo.

Os dois arquivos podem parecer semelhantes, mas cumprem funções diferentes.

Recurso	Função
opencode.json	Configura o comportamento e os recursos do OpenCode
AGENTS.md	Explica ao agente como trabalhar no projeto

Uma forma simples de lembrar:

opencode.json configura a ferramenta. AGENTS.md orienta o agente.

Por exemplo, no opencode.json podemos definir:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Já no AGENTS.md podemos escrever:

# Regras do projeto

- Use TypeScript.
- Execute os testes depois de alterações relevantes.
- Não faça commits automaticamente.
- Não altere arquivos de configuração sem explicar o motivo.
- Preserve a arquitetura existente.

Essa separação torna a configuração muito mais fácil de entender e manter.

---

Criando seu AGENTS.md

O OpenCode possui um comando próprio para ajudar nessa tarefa:

/init

O comando analisa o projeto e cria ou atualiza um arquivo AGENTS.md com informações relevantes para futuras sessões. A documentação atual indica que o processo considera aspectos como comandos de build, lint e testes, estrutura do projeto e convenções específicas do repositório.

Portanto, em vez de começar escrevendo tudo manualmente, você pode entrar no diretório do projeto:

cd meu-projeto

iniciar o OpenCode:

opencode

e executar:

/init

Depois, revise o arquivo gerado.

Esse último passo é importante.

O AGENTS.md não deve ser tratado como um arquivo mágico que você nunca mais toca. Ele deve refletir as regras que realmente importam para o projeto.

A própria documentação recomenda versionar o AGENTS.md do projeto com Git.

---

O que colocar no AGENTS.md?

Não existe uma fórmula única.

Um bom arquivo deve responder a perguntas que o agente provavelmente terá durante o desenvolvimento.

Por exemplo:

# Regras do projeto

## Tecnologia

Este projeto utiliza TypeScript e Node.js.

## Estrutura

- `src/` contém o código principal.
- `tests/` contém os testes automatizados.
- `docs/` contém a documentação.

## Desenvolvimento

- Use TypeScript.
- Preserve a arquitetura existente.
- Prefira alterações pequenas e isoladas.

## Testes

- Execute os testes relacionados depois de alterações relevantes.
- Não remova testes existentes para fazer uma implementação passar.

## Git

- Não faça commits automaticamente.
- Não faça push para o repositório remoto.

Observe que estamos dando contexto e regras, e não tentando transformar o arquivo em um manual gigantesco.

Quanto mais claro e relevante for o conteúdo, mais útil ele tende a ser.

---

Controlando o que o agente pode fazer

Agora chegamos a uma das configurações mais importantes: permissões.

O OpenCode utiliza a configuração permission para determinar se uma determinada ação deve ser:

• allow — executada sem aprovação;
• ask — executada somente depois da sua aprovação;
• deny — bloqueada.

Entre as permissões disponíveis estão ações relacionadas a leitura, edição de arquivos, execução de comandos, busca, subagentes e acesso a diretórios externos.

Uma configuração simples para começar

Para um iniciante, podemos exigir aprovação para edição de arquivos e comandos de shell:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Assim, o agente pode trabalhar, mas você participa das decisões mais importantes.

A documentação atual mostra justamente esse padrão como uma forma de fazer edit e bash solicitarem aprovação.

---

allow, ask ou deny?

A diferença é simples:

Configuração	Comportamento
allow	executa automaticamente
ask	pede sua aprovação
deny	bloqueia a ação

Por exemplo:

{
  "permission": {
    "edit": "deny"
  }
}

impede alterações de arquivos.

Já:

{
  "permission": {
    "edit": "ask"
  }
}

faz o OpenCode pedir autorização antes de modificar arquivos.

Essa possibilidade é especialmente útil quando você quer começar usando o agente em modo mais supervisionado.

---

Permissões mais específicas

As permissões também podem ser configuradas de maneira granular.

Por exemplo:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "git diff *": "allow",
      "git push *": "deny"
    }
  }
}

Nesse exemplo:

• comandos são solicitados por padrão;
• consultas como git status podem ser executadas sem aprovação;
• git diff também pode ser permitido;
• git push fica bloqueado.

As regras utilizam padrões e a última regra correspondente tem precedência. Por isso, regras gerais normalmente aparecem antes das regras específicas.

Esse tipo de configuração é útil quando você já conhece melhor seu fluxo de trabalho.

Para quem está começando, entretanto, não há necessidade de criar uma política extremamente complexa.

---

OpenCode + Git: uma combinação importante

Se você pretende permitir que um agente altere seu código, Git deixa de ser apenas uma ferramenta para publicar versões.

Ele também passa a ser uma camada de segurança operacional.

Um fluxo simples pode ser:

Git
 ↓
OpenCode analisa
 ↓
OpenCode propõe alterações
 ↓
OpenCode implementa
 ↓
Você revisa
 ↓
git diff
 ↓
Testes
 ↓
Commit

A ideia não é impedir o agente de trabalhar.

É garantir que você consiga entender, revisar e recuperar alterações quando necessário.

Antes de permitir modificações maiores, verifique se o projeto está em um estado conhecido:

git status

Depois das alterações:

git diff

E só então decida o que deve ser mantido e commitado.

---

Montando uma configuração inicial

Agora podemos juntar as peças.

Imagine um projeto chamado TaskFlow:

TaskFlow/
├── opencode.json
├── AGENTS.md
├── src/
├── tests/
├── package.json
└── README.md

O opencode.json poderia começar assim:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

E o AGENTS.md:

# TaskFlow

## Tecnologia

- TypeScript
- Node.js

## Regras

- Preserve a arquitetura existente.
- Não faça commits automaticamente.
- Não altere configurações importantes sem explicar o motivo.
- Prefira alterações pequenas e isoladas.

## Testes

- Execute os testes relacionados depois das alterações.
- Não remova testes existentes para corrigir falhas.

## Git

- Não faça push automaticamente.

Pronto.

Não criamos dezenas de regras.

Criamos um ambiente previsível.

---

Testando a configuração em um projeto real

Agora vem a parte mais importante.

Não basta criar os arquivos. Precisamos verificar se o fluxo realmente funciona.

Teste 1 — somente análise

Comece com uma solicitação que não exige alterações:

Analise a estrutura deste projeto e explique como os principais componentes estão organizados. Não faça nenhuma alteração.

O objetivo é observar como o OpenCode interpreta o projeto.

---

Teste 2 — planejamento

Depois:

Quero adicionar autenticação ao projeto. Analise a estrutura atual e proponha um plano de implementação. Não altere nenhum arquivo.

Essa etapa separa planejamento de execução.

Isso é particularmente útil quando você ainda está conhecendo um projeto.

---

Teste 3 — implementação

Depois de revisar o plano:

Implemente o primeiro passo do plano aprovado. Preserve a arquitetura existente e explique quais arquivos foram alterados.

Agora o agente pode começar a modificar o projeto.

Como configuramos edit com ask, você terá a oportunidade de revisar as ações que exigirem aprovação.

---

Teste 4 — validação

Depois:

Execute os testes relacionados às alterações realizadas e explique os resultados.

O objetivo é fechar o ciclo:

Analisar
   ↓
Planejar
   ↓
Implementar
   ↓
Testar
   ↓
Revisar

Esse fluxo tende a ser muito mais previsível do que simplesmente pedir:

“Faça essa funcionalidade.”

---

Como escolher entre configuração global e configuração do projeto?

Uma regra simples ajuda bastante.

Use configuração global quando…

A preferência faz sentido para vários projetos.

Exemplos:

• modelo padrão;
• provedor;
• algumas permissões pessoais;
• preferências que você quer manter entre projetos.

Use configuração do projeto quando…

A regra depende daquele repositório.

Exemplos:

• modelo específico;
• permissões específicas;
• ferramentas;
• configurações particulares daquele ambiente.

Use AGENTS.md quando…

A informação explica como trabalhar naquele projeto.

Exemplos:

• arquitetura;
• comandos de teste;
• convenções;
• estrutura de diretórios;
• regras de implementação.

Essa separação evita transformar uma configuração global em um arquivo cheio de exceções específicas de cada projeto.

---

O que você não precisa configurar agora

É tentador abrir a documentação do OpenCode e tentar configurar absolutamente tudo.

Não faça isso.

Você não precisa começar configurando:

• agentes personalizados;
• subagentes;
• MCP;
• skills;
• LSP;
• workflows avançados;
• dezenas de regras de permissão.

Esses recursos existem e podem ser extremamente úteis em cenários específicos, mas representam uma camada posterior de aprendizado.

O objetivo deste artigo é chegar a um ambiente funcional e compreensível.

---

Erros comuns ao configurar o OpenCode

1. Copiar uma configuração antiga

O OpenCode continua evoluindo.

Uma configuração encontrada em um artigo, vídeo ou fórum pode ter sido criada para outra versão.

Sempre confira a documentação correspondente à versão que você está utilizando.

---

2. Misturar configuração com instrução

opencode.json e AGENTS.md não são a mesma coisa.

Um configura o ambiente.

O outro fornece instruções para o agente.

---

3. Dar autonomia demais logo no início

Se você ainda está aprendendo como o agente trabalha, pode ser mais interessante utilizar ask para operações importantes.

Depois, conforme seu fluxo amadurece, algumas ações rotineiras podem receber permissões mais específicas.

---

4. Não usar controle de versão

Antes de deixar um agente fazer alterações importantes, tenha uma forma de revisar e recuperar o estado anterior do projeto.

Git é particularmente útil para isso.

---

5. Criar um AGENTS.md enorme

Mais texto não significa necessariamente melhores instruções.

Prefira regras:

• claras;
• relevantes;
• específicas;
• verificáveis.

---

Uma configuração simples para começar

Se você está acompanhando a série desde o primeiro artigo, não precisa terminar este tutorial com uma configuração gigantesca.

Um bom ponto de partida é:

Seu projeto
│
├── opencode.json
│   └── modelo + permissões
│
├── AGENTS.md
│   └── regras e contexto do projeto
│
├── Git
│   └── histórico e revisão
│
└── OpenCode
    ├── análise
    ├── planejamento
    ├── implementação
    └── testes

O objetivo não é automatizar tudo.

É construir um ambiente em que você saiba o que o agente pode fazer, como ele deve trabalhar e como revisar o resultado.

---

Perguntas frequentes

Preciso configurar o OpenCode para começar a usar?

Não necessariamente.

Você pode começar com a configuração padrão e personalizar o ambiente conforme suas necessidades aparecem.

---

O que é opencode.json?

É o arquivo de configuração do OpenCode. Ele pode definir opções como modelo, provedores e permissões. O OpenCode também suporta o formato JSONC.

---

O que é AGENTS.md?

É um arquivo de instruções usado para fornecer ao OpenCode contexto e regras específicas sobre como trabalhar em determinado projeto.

---

Qual é a diferença entre opencode.json e AGENTS.md?

De forma resumida:

opencode.json configura o OpenCode; AGENTS.md orienta o agente sobre o projeto.

---

Posso usar mais de um modelo?

Sim. O OpenCode trabalha com diferentes provedores e modelos, e você pode selecionar modelos disponíveis pelo comando /models. Também é possível definir um modelo padrão na configuração.

---

Posso usar Ollama com OpenCode?

Sim. O OpenCode suporta modelos locais e diferentes provedores. O funcionamento específico depende da configuração do provedor e do modelo utilizado.

---

Posso impedir o OpenCode de alterar arquivos?

Sim.

A permissão edit pode ser configurada como deny, impedindo operações de edição, ou como ask, exigindo aprovação antes das alterações.

---

É possível controlar comandos específicos?

Sim.

As permissões de bash podem utilizar padrões para permitir, solicitar aprovação ou bloquear determinados comandos.

---

Conclusão

Configurar o OpenCode não significa encontrar uma configuração mágica que funcione para todo mundo.

Significa definir três coisas fundamentais:

qual modelo utilizar, quais regras o agente deve seguir e quais ações ele pode executar.

Com opencode.json, você configura o ambiente.

Com AGENTS.md, você fornece contexto e regras para o projeto.

Com as permissões, você controla a autonomia do agente.

E com Git, você mantém suas alterações sob controle.

O resultado é diferente de simplesmente instalar uma ferramenta de IA e começar a enviar prompts.

Você passa a construir um ambiente de desenvolvimento em que o agente conhece o projeto, segue suas regras e trabalha dentro dos limites que você definiu.

E esse é o verdadeiro próximo passo depois de aprender a usar o OpenCode:

não apenas usar um agente de programação, mas configurar o agente para trabalhar do seu jeito.

---

O que vem depois?

Agora que você já sabe configurar o ambiente, o próximo passo natural é aprender a controlar melhor o próprio fluxo de trabalho.

Nos próximos artigos, podemos avançar para temas como:

• comandos e atalhos essenciais do OpenCode;
• criação de agentes personalizados;
• uso de MCP;
• skills;
• workflows avançados;
• e construção de um fluxo completo de desenvolvimento assistido por IA.