Config

Usando a configuração JSON do opencode.

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

Formato

O opencode suporta os formatos JSON e JSONC (JSON com Comentários).

{
  "$schema": "https://opencode.ai/config.json",
  // Theme configuration
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
}

Localizações

Você pode colocar sua configuração em algumas localizações diferentes e elas têm uma ordem de precedência diferente.

Os arquivos de configuração são mesclados, não substituídos. As configurações das seguintes localizações de configuração são combinadas. Configurações posteriores substituem as anteriores apenas para chaves conflitantes. Configurações não conflitantes de todas as configurações 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á as três configurações.

Ordem de precedência

As fontes de configuração são carregadas nesta ordem (fontes posteriores substituem 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 (OPENCODE_CONFIG var de ambiente) - substituições personalizadas
Configuração do projeto (opencode.json no projeto) - configurações específicas do projeto
Diretórios .opencode - agentes, comandos, plugins
Configuração inline (OPENCODE_CONFIG_CONTENT var de ambiente) - substituições em tempo de execução

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

Remoto

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

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

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

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

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

{
  "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 de usuário, como temas, provedores ou atalhos de teclado.

A configuração global substitui 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 substitui tanto as configurações globais quanto as remotas.

Quando o opencode é iniciado, ele procura um arquivo de configuração no diretório atual ou sobe até o diretório Git mais próximo.

Isso também é seguro para ser verificado no Git e usa o mesmo esquema que 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 as configurações globais e 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 por 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 substituir suas configurações.

Esquema

O arquivo de configuração tem um esquema que está definido em opencode.ai/config.json.

Seu editor deve ser capaz de validar e autocompletar com base no esquema.

TUI

Você pode configurar as configurações específicas do TUI através da opção tui.

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

Opções disponíveis:

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

Saiba mais sobre o uso do TUI aqui.

Servidor

Você pode configurar as configurações do 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 - Nome do host para escutar. Quando mdns está habilitado e nenhum nome de host está definido, o padrão é 0.0.0.0.
mdns - Habilitar descoberta de serviço 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 várias instâncias na mesma rede.
cors - Origens adicionais a serem permitidas para CORS ao usar o servidor HTTP de um cliente baseado em navegador. Os valores devem ser origens completas (esquema + host + porta opcional), por exemplo, 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.

{
  "$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 em sua configuração 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ítulos. Por padrão, o opencode tenta usar um modelo mais barato se um estiver disponível do seu provedor, caso contrário, ele recua para seu modelo principal.

As opções do provedor podem incluir timeout e setCacheKey:

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

timeout - Tempo limite da solicitação em milissegundos (padrão: 300000). Defina como false para desabilitar.
setCacheKey - Garantir 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

Amazon Bedrock suporta 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 Bedrock (padrão para AWS_REGION var de ambiente ou us-east-1)
profile - Perfil nomeado da AWS em ~/.aws/credentials (padrão para AWS_PROFILE var de ambiente)
endpoint - URL de endpoint personalizada 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.

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

Temas

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

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

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

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

O agente padrão deve ser um agente primário (não um subagente). Isso 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 recuará para "build" com um aviso.

Essa configuração se aplica a todas as interfaces: TUI, CLI (opencode run), aplicativo desktop e GitHub Action.

Compartilhamento

Você pode configurar o recurso share através da opção share.

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

Isso aceita:

"manual" - Permitir compartilhamento manual via comandos (padrão)
"auto" - Compartilhar novas conversas automaticamente
"disabled" - Desabilitar compartilhamento completamente

Por padrão, o compartilhamento é definido para o modo manual, onde você precisa compartilhar explicitamente as conversas 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.

Atalhos de teclado

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

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

Saiba mais aqui.

Atualização automática

O opencode fará o download automaticamente de quaisquer novas atualizações quando for iniciado. Você pode desabilitar isso com a opção autoupdate.

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

Se você não quiser atualizações, mas deseja ser notificado quando uma nova versão estiver disponível, defina autoupdate como "notify". Observe que isso só funciona se não foi instalado usando um gerenciador de pacotes como o Homebrew.

Formatadores

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

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

Compactação

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
  }
}

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

Observador

Você pode configurar padrões de ignorar do observador 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 barulhentos da observação de arquivos.

Servidores MCP

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

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

Saiba mais aqui.

Plugins

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

Coloque 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"]
}

Saiba mais aqui.

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ção. 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ê deseja impedir que certos provedores sejam carregados, mesmo que suas credenciais estejam disponíveis.

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

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

Ele não será carregado, mesmo que variáveis de ambiente estejam definidas.
Ele não será carregado, mesmo que 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 lista de permissão 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ê deseja restringir o opencode para usar apenas provedores específicos, em vez de desabilitá-los um a um.

Se um provedor aparecer em enabled_providers e disabled_providers, a 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": {}
}

Variáveis

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

{
  "$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 dos arquivos podem ser:

Relativos ao diretório do arquivo de configuração
Ou caminhos absolutos começando com / ou ~

Esses são úteis para:

Manter dados sensíveis, como chaves de API, em arquivos separados.
Incluir grandes arquivos de instrução sem sobrecarregar sua configuração.
Compartilhar trechos de configuração comuns entre vários arquivos de configuração.