OpenCode: OpenCode Configuration File
Última atualização: 2026-08-31
--- title: Arquivo de Configuração do OpenCode description: Aprenda a estrutura do arquivo de configuração do OpenCode, incluindo todos os itens do opencode.json e configurações comuns order: 4 lang: pt-br
O OpenCode gerencia todas as configurações pelo arquivo opencode.json, incluindo modelos, agentes, ferramentas, temas etc.
1. O Que Você Vai Aprender
- Localização e prioridade dos arquivos de configuração
- Estrutura completa do opencode.json
- Detalhes dos itens de configuração comuns
- Configuração por variáveis de ambiente
2. Localização do Arquivo de Configuração
O OpenCode carrega configurações na seguinte prioridade (posterior sobrescreve anterior):
| Prioridade | Caminho | Escopo |
|---|---|---|
| 1 | ~/.config/opencode/opencode.json |
Configuração global |
| 2 | <project>/.opencode/opencode.json |
Configuração do projeto |
| 3 | Variáveis de ambiente | Sobrescrever em tempo de execução |
3. Estrutura Completa de Configuração
{
"$schema": "https://opencode.ai/config.json",
"provider": {},
"model": {},
"agent": {},
"tools": {},
"permission": {},
"theme": {},
"tui": {}
}
- provider: Configuração de provedores de modelos personalizados
- model: Modelo padrão a ser usado
- agent: Configuração de agentes personalizados (detalhes na aula 13)
- tools: Interruptores globais de ferramentas
- permission: Controle de permissões granular (allow/ask/deny)
- tui: Configurações da interface do terminal
4. AGENTS.md (Regras do Projeto)
AGENTS.md é o arquivo de regras em nível de projeto do OpenCode, colocado na raiz do projeto.
Criar via TUI:
/init
Ou criar manualmente o arquivo AGENTS.md.
Conteúdo de exemplo:
# Project Rules
- Always use TypeScript for new files
- Follow ESLint configuration
- Write unit tests for all new functions
- Use conventional commits format
5. Variáveis de Ambiente
| Variável | Tipo | Função |
|---|---|---|
OPENCODE_AUTO_SHARE |
boolean | Compartilhar sessões automaticamente |
OPENCODE_CONFIG |
string | Caminho de configuração personalizado |
OPENCODE_DISABLE_AUTOUPDATE |
boolean | Desativar atualização automática |
OPENCODE_SERVER_PASSWORD |
string | Senha de autenticação do serviço API |
OPENCODE_MODELS_URL |
string | Fonte de modelos personalizada |
OPENCODE_EXPERIMENTAL |
boolean | Ativar funcionalidades experimentais |
OPENCODE_EXPERIMENTAL_LSP_TOOL |
boolean | Ferramenta LSP experimental |
❓ FAQ
P: Quando configurações global e do projeto conflitam, qual prevalece?
R: A do projeto. O OpenCode carrega por prioridade e o posterior sobrescreve o anterior.
P: Qual a diferença entre AGENTS.md e opencode.json?
R: AGENTS.md descreve regras em linguagem natural que a IA lê e segue. opencode.json define configurações em JSON estruturado que o programa OpenCode lê e executa. São complementares.
📖 Resumo
- Carregamento por prioridade: global < projeto < variáveis de ambiente
- opencode.json é a configuração central: modelos, agentes, ferramentas, permissões
- AGENTS.md define regras do projeto em linguagem natural
- Variáveis de ambiente são ideais para CI/CD e sobrescritas temporárias
📝 Exercícios
-
Básico: Crie um opencode.json global configurando seu provedor de modelo.
-
Intermediário: Crie .opencode/opencode.json para seu projeto com permissões de ferramentas específicas.
-
Avançado: Escreva um AGENTS.md definindo padrões de codificação e faça o OpenCode segui-lo.
