Configuração

Usando a configuração JSON do OpenCode.

Você pode configurar o OpenCode usando um arquivo de configuração JSON.

Formato

O OpenCode suporta tanto JSON quanto JSONC (JSON com Comentários).

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  // Configuração do tema
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

Localizações

Você pode colocar sua configuração em diferentes locais que têm diferentes ordens de precedência.

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 são combinadas. Configurações posteriores sobrescrevem apenas as chaves em conflito. Configurações que não entram em conflito de todas as fontes são preservadas.

Por exemplo, se sua configuração global define theme: "opencode" e autoupdate: true, e sua configuração de projeto define model: "anthropic/claude-sonnet-4-5", a configuração final incluirá todas as três opções.

Ordem de precedência

As fontes de configuração são carregadas nesta ordem (fontes posteriores sobrescrevem as anteriores):

Configuração remota (de .well-known/opencode) - padrões organizacionais
Configuração global (~/.config/opencode/opencode.json) - preferências do usuário
Configuração personalizada (variável de ambiente OPENCODE_CONFIG) - sobrescritas personalizadas
Configuração do projeto (opencode.json no projeto) - configurações específicas do projeto
Diretórios .opencode - agentes, comandos, plugins
Configuração inline (variável de ambiente OPENCODE_CONFIG_CONTENT) - sobrescritas em tempo de execução

Isso significa que as configurações do projeto podem sobrescrever os padrões globais, e as configurações globais podem sobrescrever os padrões organizacionais remotos.

Nota: Os subdiretórios de .opencode e ~/.config/opencode usam nomes no plural: agents/, commands/, modes/, plugins/, skills/, tools/ e themes/. Nomes no singular (ex. agent/) também são suportados para compatibilidade retroativa.

Remota

As organizações podem fornecer configuração padrão através do endpoint .well-known/opencode. Esta é obtida automaticamente quando você se autentica com um provedor que a suporta.

A configuração remota é carregada primeiro, servindo como camada base. Todas as outras fontes de configuração (global, projeto) podem sobrescrever esses padrões.

Por exemplo, se sua organização fornece servidores MCP que estão desabilitados por padrão:

Configuração remota de .well-known/opencode

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

Você pode habilitar servidores específicos na sua configuração local:

opencode.json

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Global

Coloque sua configuração global do OpenCode em ~/.config/opencode/opencode.json. Use a configuração global para preferências a nível de usuário como temas, provedores ou atalhos de teclado.

A configuração global sobrescreve os padrões organizacionais remotos.

Por projeto

Adicione opencode.json na raiz do seu projeto. A configuração do projeto tem a maior precedência entre os arquivos de configuração padrão - ela sobrescreve tanto a configuração global quanto a remota.

Dica: Coloque a configuração específica do projeto na raiz do seu projeto.

Quando o OpenCode inicia, ele procura um arquivo de configuração no diretório atual ou percorre para cima até o diretório Git mais próximo.

Isso também é seguro para fazer commit no Git e usa o mesmo schema que a configuração global.

Caminho personalizado

Especifique um caminho de arquivo de configuração personalizado usando a variável de ambiente OPENCODE_CONFIG.

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

A configuração personalizada é carregada entre a configuração global e a do projeto na ordem de precedência.

Diretório personalizado

Especifique um diretório de configuração personalizado usando a variável de ambiente OPENCODE_CONFIG_DIR. Este diretório será pesquisado para agentes, comandos, modos e plugins assim como o diretório padrão .opencode, e deve seguir a mesma estrutura.

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

O diretório personalizado é carregado após a configuração global e os diretórios .opencode, então ele pode sobrescrever suas configurações.

Schema

O arquivo de configuração tem um schema definido em opencode.ai/config.json (opens in a new tab).

Seu editor deve ser capaz de validar e autocompletar baseado no schema.

TUI

Você pode configurar ajustes específicos de TUI através da opção tui.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

Opções disponíveis:

scroll_acceleration.enabled - Habilita a aceleração de rolagem estilo macOS. Tem precedência sobre scroll_speed.
scroll_speed - Multiplicador de velocidade de rolagem personalizado (padrão: 3, mínimo: 1). Ignorado se scroll_acceleration.enabled for true.
diff_style - Controla a renderização de diff. "auto" se adapta à largura do terminal, "stacked" sempre mostra uma única coluna.

Saiba mais sobre o uso do TUI aqui.

Servidor

Você pode configurar ajustes do servidor para os comandos opencode serve e opencode web através da opção server.

opencode.json

{
  "$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 - Nome do host para escutar. Quando mdns está 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 executar múltiplas instâncias na mesma rede.
cors - Origens adicionais a permitir para CORS quando usar o servidor HTTP de um cliente baseado em navegador. Os valores devem ser origens completas (esquema + host + porta opcional), ex. https://app.example.com.

Saiba mais sobre o servidor aqui.

Ferramentas

Você pode gerenciar as ferramentas que um LLM pode usar através da opção tools.

opencode.json

{
  "$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 configuração do OpenCode através das opções provider, model e small_model.

opencode.json

{
  "$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ítulos. 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 e setCacheKey:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}

timeout - Tempo limite de requisição em milissegundos (padrão: 300000). Defina como false para desabilitar.
setCacheKey - Garante que uma chave de cache seja sempre definida para o provedor designado.

Você também pode configurar modelos locais. Saiba mais.

Opções específicas do provedor

Alguns provedores suportam opções de configuração adicionais além das configurações genéricas timeout e apiKey.

Amazon Bedrock

O Amazon Bedrock suporta configuração específica da AWS:

opencode.json

{
  "$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 da AWS para o Bedrock (padrão para a variável de ambiente AWS_REGION ou us-east-1)
profile - Perfil nomeado da AWS de ~/.aws/credentials (padrão para a variável de ambiente AWS_PROFILE)
endpoint - URL de endpoint personalizado para endpoints VPC. Este é um alias para a opção genérica baseURL usando terminologia específica da AWS. Se ambos forem especificados, endpoint tem precedência.

Nota: Tokens Bearer (AWS_BEARER_TOKEN_BEDROCK ou /connect) têm precedência sobre autenticação baseada em perfil. Veja precedência de autenticação para detalhes.

Saiba mais sobre a configuração do Amazon Bedrock.

Temas

Você pode configurar o tema que deseja usar na sua configuração do OpenCode através da opção theme.

opencode.json

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

Saiba mais aqui.

Agentes

Você pode configurar agentes especializados para tarefas específicas através da opção agent.

opencode.jsonc

{
  "$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": {
        // Desabilitar ferramentas de modificação de arquivos para agente somente de revisão
        "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.

opencode.json

{
  "$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 embutido 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.

opencode.json

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

Isso aceita:

"manual" - Permitir compartilhamento manual através de comandos (padrão)
"auto" - Compartilhar automaticamente novas conversas
"disabled" - Desabilitar compartilhamento completamente

Por padrão, o compartilhamento está configurado no modo manual onde você precisa compartilhar conversas explicitamente usando o comando /share.

Comandos

Você pode configurar comandos personalizados para tarefas repetitivas através da opção command.

opencode.jsonc

{
  "$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.

Atalhos de teclado

Você pode personalizar seus atalhos de teclado através da opção keybinds.

opencode.json

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

Saiba mais aqui.

Atualização automática

O OpenCode baixará automaticamente quaisquer novas atualizações quando iniciar. Você pode desabilitar isso com a opção autoupdate.

opencode.json

{
  "$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". Note que isso só funciona se não foi instalado usando um gerenciador de pacotes como Homebrew.

Formatadores

Você pode configurar formatadores de código através da opção formatter.

opencode.json

{
  "$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.

Permissões

Por padrão, o opencode permite todas as operações sem requerer aprovação explícita. Você pode mudar isso usando a opção permission.

Por exemplo, para garantir que as ferramentas edit e bash requeiram aprovação do usuário:

opencode.json

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

Saiba mais sobre permissões aqui.

Compactação

Você pode controlar o comportamento de compactação de contexto através da opção compaction.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}

auto - Compactar automaticamente a sessão quando o contexto estiver cheio (padrão: true).
prune - Remover saídas de ferramentas antigas para economizar tokens (padrão: true).

Watcher

Você pode configurar padrões de ignorar do observador de arquivos através da opção watcher.

opencode.json

{
  "$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 da observação de arquivos.

Servidores MCP

Você pode configurar os servidores MCP que deseja usar através da opção mcp.

opencode.json

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

Saiba mais aqui.

Plugins

Os Plugins estendem o OpenCode com ferramentas personalizadas, hooks e integrações.

Coloque arquivos de plugins em .opencode/plugins/ ou ~/.config/opencode/plugins/. Você também pode carregar plugins do npm através da opção plugin.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Saiba mais aqui.

Instruções

Você pode configurar as instruções para o modelo que está usando através da opção instructions.

opencode.json

{
  "$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 prevenir que certos provedores sejam carregados mesmo se suas credenciais estiverem disponíveis.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

Nota: disabled_providers tem prioridade sobre enabled_providers.

A opção disabled_providers aceita um array de IDs de provedor. Quando um provedor está desabilitado:

Não será carregado mesmo se as variáveis de ambiente estiverem definidas.
Não será carregado mesmo se as chaves API estiverem 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 lista de permitidos de provedores através da opção enabled_providers. Quando definido, apenas os provedores especificados serão habilitados e todos os outros serão ignorados.

opencode.json

{
  "$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_providers tem prioridade sobre enabled_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.

opencode.json

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

Cuidado: Opções experimentais não são estáveis. Elas podem mudar ou ser removidas sem aviso prévio.

Variáveis

Você pode usar substituição de variáveis nos seus arquivos de configuração 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:

opencode.json

{
  "$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, será substituída por uma string vazia.

Arquivos

Use {file:path/to/file} para substituir o conteúdo de um arquivo:

opencode.json

{
  "$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 configuração
Ou caminhos absolutos começando com / ou ~

Estes são úteis para:

Manter dados sensíveis como chaves API em arquivos separados.
Incluir arquivos de instruções grandes sem bagunçar sua configuração.
Compartilhar fragmentos de configuração comuns entre múltiplos arquivos de configuração.

Introdução Provedores