Config
Usando a config JSON do OpenCode.
Você pode configurar o OpenCode usando um arquivo de config JSON.
Formato
O OpenCode oferece suporte aos formatos JSON e JSONC (JSON com Comentários).
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5",
"autoupdate": true,
"server": {
"port": 4096,
},
}Locais
Você pode colocar sua config em alguns locais diferentes e eles têm uma ordem de precedência diferente.
Nota: Os arquivos de configuração são mesclados, não substituídos.
Os arquivos de configuração são mesclados, não substituídos. As configurações dos seguintes locais de config são combinadas. Configs posteriores substituem as anteriores apenas para chaves conflitantes. Configurações não conflitantes de todas as configs são preservadas.
Por exemplo, se sua config global define autoupdate: true e sua config de projeto define model: "anthropic/claude-sonnet-4-5", a configuração final incluirá ambas as configurações.
Ordem de precedência
As fontes de config são carregadas nesta ordem (fontes posteriores substituem as anteriores):
- Config remota (de
.well-known/opencode) - padrões organizacionais - Config global (
~/.config/opencode/opencode.json) - preferências do usuário - Config personalizada (variável de ambiente
OPENCODE_CONFIG) - substituições personalizadas - Config de projeto (
opencode.jsonno projeto) - configurações específicas do projeto - Diretórios
.opencode- agentes, comandos, plugins - Config inline (variável de ambiente
OPENCODE_CONFIG_CONTENT) - substituições em tempo de execução - Arquivos de config gerenciados (
/Library/Application Support/opencode/no macOS) - controlados pelo administrador - Preferências gerenciadas do macOS (
.mobileconfigvia MDM) - prioridade mais alta, não sobrescrevível pelo usuário
Isso significa que configs de projeto podem substituir padrões globais, e configs globais podem substituir padrões organizacionais remotos. Configurações gerenciadas substituem tudo.
Nota: Os diretórios
.opencodee~/.config/opencodeusam nomes no plural para os subdiretórios:agents/,commands/,modes/,plugins/,skills/,tools/ethemes/. Nomes no singular (ex.:agent/) também são suportados para compatibilidade retroativa.
Remota
Organizações podem fornecer configuração padrão via o endpoint .well-known/opencode. Isso é buscado automaticamente quando você se autentica com um provedor que oferece suporte a ela.
A config remota é carregada primeiro, servindo como camada base. Todas as outras fontes de config (global, projeto) podem substituir esses padrões.
Por exemplo, se sua organização fornece servidores MCP que estão desabilitados por padrão:
{
"mcp": {
"jira": {
"type": "remote",
"url": "https://jira.example.com/mcp",
"enabled": false
}
}
}Você pode habilitar servidores específicos na sua config local:
{
"mcp": {
"jira": {
"type": "remote",
"url": "https://jira.example.com/mcp",
"enabled": true
}
}
}Global
Coloque sua config global do OpenCode em ~/.config/opencode/opencode.json. Use a config global para preferências de servidor/runtime que valem para todo o usuário, como provedores, modelos e permissões.
Para configurações específicas da TUI, use ~/.config/opencode/tui.json.
A config global substitui os padrões organizacionais remotos.
Por projeto
Adicione opencode.json na raiz do seu projeto. A config de projeto tem a precedência mais alta entre os arquivos de config padrão - ela substitui tanto as configs globais quanto as remotas.
Para configurações de TUI específicas do projeto, adicione tui.json junto a ela.
Dica: Coloque a config específica do projeto na raiz do seu projeto.
Quando o OpenCode inicia, ele procura por um arquivo de config no diretório atual ou sobe até o diretório Git mais próximo.
Isso também é seguro para ser versionado no Git e usa o mesmo schema da config global.
Caminho personalizado
Especifique um caminho de arquivo de config personalizado usando a variável de ambiente OPENCODE_CONFIG.
export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"A config personalizada é carregada entre as configs global e de projeto na ordem de precedência.
Diretório personalizado
Especifique um diretório de config personalizado usando a variável de ambiente
OPENCODE_CONFIG_DIR. Este diretório será pesquisado por agentes, comandos,
modes e plugins exatamente como o diretório .opencode padrão, e deve
seguir a mesma estrutura.
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"O diretório personalizado é carregado depois da config global e dos diretórios .opencode, então ele pode substituir suas configurações.
Configurações gerenciadas
Organizações podem impor configurações que os usuários não podem substituir. Configurações gerenciadas são carregadas no nível de prioridade mais alto.
Baseadas em arquivo
Coloque um arquivo opencode.json ou opencode.jsonc no diretório de config gerenciado pelo sistema:
| Plataforma | Caminho |
|---|---|
| macOS | /Library/Application Support/opencode/ |
| Linux | /etc/opencode/ |
| Windows | %ProgramData%\opencode |
Esses diretórios exigem acesso de admin/root para escrever, então os usuários não podem modificá-los.
Preferências gerenciadas do macOS
No macOS, o OpenCode lê preferências gerenciadas do domínio de preferência ai.opencode.managed. Implante um .mobileconfig via MDM (Jamf, Kandji, FleetDM) e as configurações são impostas automaticamente.
O OpenCode verifica estes caminhos:
/Library/Managed Preferences/<user>/ai.opencode.managed.plist/Library/Managed Preferences/ai.opencode.managed.plist
As chaves do plist mapeiam diretamente para campos do opencode.json. Chaves de metadados do MDM (PayloadUUID, PayloadType, etc.) são removidas automaticamente.
Criando um .mobileconfig
Use o PayloadType ai.opencode.managed. As chaves de config do OpenCode vão diretamente no dict do payload:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>PayloadContent</key>
<array>
<dict>
<key>PayloadType</key>
<string>ai.opencode.managed</string>
<key>PayloadIdentifier</key>
<string>com.example.opencode.config</string>
<key>PayloadUUID</key>
<string>GENERATE-YOUR-OWN-UUID</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>share</key>
<string>disabled</string>
<key>server</key>
<dict>
<key>hostname</key>
<string>127.0.0.1</string>
</dict>
<key>permission</key>
<dict>
<key>*</key>
<string>ask</string>
<key>bash</key>
<dict>
<key>*</key>
<string>ask</string>
<key>rm -rf *</key>
<string>deny</string>
</dict>
</dict>
</dict>
</array>
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadIdentifier</key>
<string>com.example.opencode</string>
<key>PayloadUUID</key>
<string>GENERATE-YOUR-OWN-UUID</string>
<key>PayloadVersion</key>
<integer>1</integer>
</dict>
</plist>Gere UUIDs únicos com uuidgen. Personalize as configurações para atender aos requisitos da sua organização.
Implantando via MDM
- Jamf Pro: Computers > Configuration Profiles > Upload > delimite o escopo para os dispositivos-alvo ou grupos inteligentes
- FleetDM: Adicione o
.mobileconfigao seu repositório gitops emmdm.macos_settings.custom_settingse executefleetctl apply
Verificando em um dispositivo
Dê um duplo clique no .mobileconfig para instalar localmente para testes (aparece em System Settings > Privacy & Security > Profiles), depois execute:
opencode debug configTodas as chaves de preferência gerenciada aparecem na config resolvida e não podem ser substituídas pela configuração de usuário ou de projeto.
Schema
O schema de config de servidor/runtime é definido em opencode.ai/config.json (opens in a new tab).
A config da TUI usa opencode.ai/tui.json (opens in a new tab).
Seu editor deve conseguir validar e autocompletar com base no schema.
TUI
Use um arquivo tui.json (ou tui.jsonc) dedicado para configurações específicas da TUI.
{
"$schema": "https://opencode.ai/tui.json",
"scroll_speed": 3,
"scroll_acceleration": {
"enabled": true
},
"diff_style": "auto",
"mouse": true,
"attention": {
"enabled": true,
"notifications": true,
"sound": true,
"volume": 0.4
}
}Use OPENCODE_TUI_CONFIG para apontar para um arquivo de config de TUI personalizado.
Defina attention.enabled para ativar as notificações de desktop e os sons da TUI. Veja atenção da TUI.
As chaves legadas theme, keybinds e tui no opencode.json estão obsoletas e são migradas automaticamente quando possível.
Servidor
Você pode configurar as opções de servidor para os comandos opencode serve e opencode web através da opção server.
{
"$schema": "https://opencode.ai/config.json",
"server": {
"port": 4096,
"hostname": "0.0.0.0",
"mdns": true,
"mdnsDomain": "myproject.local",
"cors": ["http://localhost:5173"]
}
}Opções disponíveis:
port- Porta para escutar.hostname- Hostname para escutar. Quandomdnsestá habilitado e nenhum hostname é definido, o padrão é0.0.0.0.mdns- Habilita a descoberta de serviços mDNS. Isso permite que outros dispositivos na rede descubram seu servidor OpenCode.mdnsDomain- Nome de domínio personalizado para o serviço mDNS. O padrão éopencode.local. Útil para rodar múltiplas instâncias na mesma rede.cors- Origens adicionais a permitir para CORS ao usar o servidor HTTP a partir de um cliente baseado em navegador. Os valores devem ser origens completas (esquema + host + porta opcional), por exemplohttps://app.example.com.
Saiba mais sobre o servidor aqui.
Shell
Você pode configurar o shell usado para o terminal interativo usando a opção shell. Shells compatíveis também são usados para chamadas de ferramentas do agente.
{
"$schema": "https://opencode.ai/config.json",
"shell": "pwsh"
}Se não for especificado, o OpenCode descobrirá e usará automaticamente um padrão sensato com base no seu sistema operacional (ex.: pwsh ou cmd.exe no Windows, /bin/zsh ou /bin/bash no macOS/Linux). Você pode fornecer um caminho absoluto ou um nome curto.
Ferramentas
Você pode gerenciar as ferramentas que um LLM pode usar através da opção tools.
{
"$schema": "https://opencode.ai/config.json",
"tools": {
"write": false,
"bash": false
}
}Saiba mais sobre ferramentas aqui.
Modelos
Você pode configurar os provedores e modelos que deseja usar na sua config do OpenCode através das opções provider, model e small_model.
{
"$schema": "https://opencode.ai/config.json",
"provider": {},
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5"
}A opção small_model configura um modelo separado para tarefas leves, como geração de título. Por padrão, o OpenCode tenta usar um modelo mais barato se houver um disponível do seu provedor; caso contrário, recorre ao seu modelo principal.
As opções do provedor podem incluir timeout, chunkTimeout e setCacheKey:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"timeout": 600000,
"chunkTimeout": 30000,
"setCacheKey": true
}
}
}
}timeout- Timeout da requisição em milissegundos (padrão: 300000). Defina comofalsepara desabilitar.chunkTimeout- Timeout em milissegundos entre chunks de resposta transmitidos. Se nenhum chunk chegar a tempo, a requisição é abortada.setCacheKey- Garante que uma chave de cache esteja sempre definida para o provedor designado.
Você também pode configurar modelos locais. Saiba mais.
Anexos de imagem
O OpenCode normaliza os anexos de imagem antes de enviá-los ao modelo. Por padrão, as imagens são redimensionadas quando excedem 2000x2000 pixels ou 5242880 bytes em base64.
Configure os limites de anexos de imagem com a opção attachment.image:
{
"$schema": "https://opencode.ai/config.json",
"attachment": {
"image": {
"auto_resize": true,
"max_width": 2000,
"max_height": 2000,
"max_base64_bytes": 5242880
}
}
}auto_resize- Redimensiona imagens que excedem os limites configurados antes das requisições ao provedor. Defina comofalsepara rejeitar imagens grandes demais em vez disso.max_width- Largura máxima da imagem em pixels antes do redimensionamento ou rejeição.max_height- Altura máxima da imagem em pixels antes do redimensionamento ou rejeição.max_base64_bytes- Tamanho máximo do payload de imagem codificada. Este é o tamanho do payload em base64, não o tamanho do arquivo original.
Se uma imagem ainda não couber após o redimensionamento, o OpenCode omite imagens de resultado de ferramenta grandes demais ou falha em imagens fornecidas pelo usuário que sejam grandes demais com um erro de tamanho de imagem.
Opções específicas do provedor
Alguns provedores oferecem suporte a opções de configuração adicionais além das configurações genéricas timeout e apiKey.
Amazon Bedrock
O Amazon Bedrock oferece suporte a configuração específica da AWS:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"amazon-bedrock": {
"options": {
"region": "us-east-1",
"profile": "my-aws-profile",
"endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
}
}
}
}region- Região AWS para o Bedrock (padrão: variável de ambienteAWS_REGIONouus-east-1)profile- Perfil nomeado da AWS de~/.aws/credentials(padrão: variável de ambienteAWS_PROFILE)endpoint- URL de endpoint personalizado para endpoints de VPC. Este é um alias para a opção genéricabaseURLusando a terminologia específica da AWS. Se ambos forem especificados,endpointtem precedência.
Nota: Tokens bearer (
AWS_BEARER_TOKEN_BEDROCKou/connect) têm precedência sobre a autenticação baseada em perfil. Veja precedência de autenticação para detalhes.
Saiba mais sobre a configuração do Amazon Bedrock.
Temas
Defina o tema da sua interface em tui.json.
{
"$schema": "https://opencode.ai/tui.json",
"theme": "tokyonight"
}Agentes
Você pode configurar agentes especializados para tarefas específicas através da opção agent.
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"code-reviewer": {
"description": "Reviews code for best practices and potential issues",
"model": "anthropic/claude-sonnet-4-5",
"prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
"tools": {
// Disable file modification tools for review-only agent
"write": false,
"edit": false,
},
},
},
}Você também pode definir agentes usando arquivos markdown em ~/.config/opencode/agents/ ou .opencode/agents/. Saiba mais aqui.
Agente padrão
Você pode definir o agente padrão usando a opção default_agent. Isso determina qual agente é usado quando nenhum é especificado explicitamente.
{
"$schema": "https://opencode.ai/config.json",
"default_agent": "plan"
}O agente padrão deve ser um agente primário (não um subagente). Pode ser um agente integrado como "build" ou "plan", ou um agente personalizado que você definiu. Se o agente especificado não existir ou for um subagente, o OpenCode recorrerá a "build" com um aviso.
Esta configuração se aplica a todas as interfaces: TUI, CLI (opencode run), aplicativo desktop e GitHub Action.
Compartilhamento
Você pode configurar o recurso de compartilhamento através da opção share.
{
"$schema": "https://opencode.ai/config.json",
"share": "manual"
}Isso aceita:
"manual"- Permite o compartilhamento manual via comandos (padrão)"auto"- Compartilha automaticamente novas conversas"disabled"- Desabilita o compartilhamento completamente
Por padrão, o compartilhamento é definido como modo manual, no qual você precisa compartilhar conversas explicitamente usando o comando /share.
Comandos
Você pode configurar comandos personalizados para tarefas repetitivas através da opção command.
{
"$schema": "https://opencode.ai/config.json",
"command": {
"test": {
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
"description": "Run tests with coverage",
"agent": "build",
"model": "anthropic/claude-haiku-4-5",
},
"component": {
"template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
"description": "Create a new component",
},
},
}Você também pode definir comandos usando arquivos markdown em ~/.config/opencode/commands/ ou .opencode/commands/. Saiba mais aqui.
Keybinds
Personalize os atalhos de teclado da TUI em tui.json com keybinds.
{
"$schema": "https://opencode.ai/tui.json",
"keybinds": {
"command_list": "ctrl+p"
}
}keybinds é mesclado com os padrões integrados, então você só precisa configurar os atalhos que deseja alterar.
Snapshot
O OpenCode usa snapshots para rastrear alterações de arquivo durante as operações do agente, permitindo desfazer e reverter alterações dentro de uma sessão. Os snapshots são habilitados por padrão.
Para repositórios grandes ou projetos com muitos submódulos, o sistema de snapshots pode causar indexação lenta e uso significativo de disco, já que rastreia todas as alterações usando um repositório git interno. Você pode desabilitar os snapshots usando a opção snapshot.
{
"$schema": "https://opencode.ai/config.json",
"snapshot": false
}Observe que desabilitar os snapshots significa que as alterações feitas pelo agente não podem ser revertidas pela interface.
Autoupdate
O OpenCode baixará automaticamente quaisquer novas atualizações quando iniciar. Você pode desabilitar isso com a opção autoupdate.
{
"$schema": "https://opencode.ai/config.json",
"autoupdate": false
}Se você não quer atualizações, mas quer ser notificado quando uma nova versão estiver disponível, defina autoupdate como "notify".
Observe que isso só funciona se ele não foi instalado usando um gerenciador de pacotes como o Homebrew.
Formatadores
Você pode habilitar e configurar formatadores de código através da opção formatter. Omita-a para manter os formatadores desabilitados.
{
"$schema": "https://opencode.ai/config.json",
"formatter": true
}Use um objeto para manter os integrados habilitados enquanto configura substituições ou formatadores personalizados.
{
"$schema": "https://opencode.ai/config.json",
"formatter": {
"prettier": {
"disabled": true
},
"custom-prettier": {
"command": ["npx", "prettier", "--write", "$FILE"],
"environment": {
"NODE_ENV": "development"
},
"extensions": [".js", ".ts", ".jsx", ".tsx"]
}
}
}Saiba mais sobre formatadores aqui.
Servidores LSP
Você pode habilitar e configurar servidores LSP através da opção lsp. Omita-a para manter o LSP desabilitado.
{
"$schema": "https://opencode.ai/config.json",
"lsp": true
}Use um objeto para manter os integrados habilitados enquanto configura substituições ou servidores LSP personalizados.
{
"$schema": "https://opencode.ai/config.json",
"lsp": {
"typescript": {
"disabled": true
}
}
}Saiba mais sobre servidores LSP aqui.
Permissões
Por padrão, o opencode permite todas as operações sem exigir aprovação explícita. Você pode mudar isso usando a opção permission.
Por exemplo, para garantir que as ferramentas edit e bash exijam aprovação do usuário:
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "ask",
"bash": "ask"
}
}Saiba mais sobre permissões aqui.
Compaction
Você pode controlar o comportamento de compactação de contexto através da opção compaction.
{
"$schema": "https://opencode.ai/config.json",
"compaction": {
"auto": true,
"prune": true,
"reserved": 10000
}
}auto- Compacta a sessão automaticamente quando o contexto está cheio (padrão:true).prune- Remove saídas de ferramenta antigas para economizar tokens (padrão:true).reserved- Buffer de tokens para a compactação. Deixa janela suficiente para evitar overflow durante a compactação.
Watcher
Você pode configurar os padrões de ignore do watcher de arquivos através da opção watcher.
{
"$schema": "https://opencode.ai/config.json",
"watcher": {
"ignore": ["node_modules/**", "dist/**", ".git/**"]
}
}Os padrões seguem a sintaxe glob. Use isso para excluir diretórios ruidosos do monitoramento de arquivos.
Servidores MCP
Você pode configurar os servidores MCP que deseja usar através da opção mcp.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {}
}Plugins
Os plugins estendem o OpenCode com ferramentas, hooks e integrações personalizadas.
Coloque os arquivos de plugin em .opencode/plugins/ ou ~/.config/opencode/plugins/. Você também pode carregar plugins do npm através da opção plugin.
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}Instruções
Você pode configurar as instruções para o modelo que está usando através da opção instructions.
{
"$schema": "https://opencode.ai/config.json",
"instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}Isso aceita um array de caminhos e padrões glob para arquivos de instruções. Saiba mais sobre regras aqui.
Provedores desabilitados
Você pode desabilitar provedores que são carregados automaticamente através da opção disabled_providers. Isso é útil quando você quer impedir que certos provedores sejam carregados mesmo que suas credenciais estejam disponíveis.
{
"$schema": "https://opencode.ai/config.json",
"disabled_providers": ["openai", "gemini"]
}Nota:
disabled_providerstem prioridade sobreenabled_providers.
A opção disabled_providers aceita um array de IDs de provedor. Quando um provedor é desabilitado:
- Ele não será carregado mesmo que as variáveis de ambiente estejam definidas.
- Ele não será carregado mesmo que as chaves de API estejam configuradas através do comando
/connect. - Os modelos do provedor não aparecerão na lista de seleção de modelos.
Provedores habilitados
Você pode especificar uma allowlist de provedores através da opção enabled_providers. Quando definida, apenas os provedores especificados serão habilitados e todos os outros serão ignorados.
{
"$schema": "https://opencode.ai/config.json",
"enabled_providers": ["anthropic", "openai"]
}Isso é útil quando você quer restringir o OpenCode a usar apenas provedores específicos em vez de desabilitá-los um por um.
Nota:
disabled_providerstem prioridade sobreenabled_providers.
Se um provedor aparecer tanto em enabled_providers quanto em disabled_providers, disabled_providers tem prioridade para compatibilidade retroativa.
Experimental
A chave experimental contém opções que estão em desenvolvimento ativo.
{
"$schema": "https://opencode.ai/config.json",
"experimental": {}
}Cuidado: As opções experimentais não são estáveis. Elas podem mudar ou ser removidas sem aviso prévio.
Variáveis
Você pode usar a substituição de variáveis nos seus arquivos de config para referenciar variáveis de ambiente e conteúdos de arquivos.
Variáveis de ambiente
Use {env:VARIABLE_NAME} para substituir variáveis de ambiente:
{
"$schema": "https://opencode.ai/config.json",
"model": "{env:OPENCODE_MODEL}",
"provider": {
"anthropic": {
"models": {},
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
}
}
}Se a variável de ambiente não estiver definida, ela será substituída por uma string vazia.
Arquivos
Use {file:path/to/file} para substituir o conteúdo de um arquivo:
{
"$schema": "https://opencode.ai/config.json",
"instructions": ["./custom-instructions.md"],
"provider": {
"openai": {
"options": {
"apiKey": "{file:~/.secrets/openai-key}"
}
}
}
}Os caminhos de arquivo podem ser:
- Relativos ao diretório do arquivo de config
- Ou caminhos absolutos começando com
/ou~
Estes são úteis para:
- Manter dados sensíveis, como chaves de API, em arquivos separados.
- Incluir arquivos de instruções grandes sem poluir sua config.
- Compartilhar trechos de configuração comuns entre vários arquivos de config.