vrr/opencode
2
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-05-06 00:12:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 18
opencode/packages/web/src/content/docs/pt-br/config.mdx
opencode-agent[bot] d578f80f00 chore: generate
2026-02-09 17:35:30 +00:00

681 lines
20 KiB
Text
Raw Blame History

---
title: Config
description: 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).
```jsonc title="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 algumas localizações diferentes e elas têm uma
ordem de precedência diferente.
:::note
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 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):
1. **Configuração remota** (de `.well-known/opencode`) - padrões organizacionais
2. **Configuração global** (`~/.config/opencode/opencode.json`) - preferências do usuário
3. **Configuração personalizada** (`OPENCODE_CONFIG` var de ambiente) - substituições personalizadas
4. **Configuração do projeto** (`opencode.json` no projeto) - configurações específicas do projeto
5. **Diretórios `.opencode`** - agentes, comandos, plugins
6. **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.
:::note
Os diretórios `.opencode` e `~/.config/opencode` usam **nomes no plural** para subdiretórios: `agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, e `themes/`. Nomes no singular (por exemplo, `agent/`) também são suportados para compatibilidade retroativa.
:::
---
### 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:
```json title="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 em sua configuração local:
```json title="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 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.
:::tip
Coloque a configuração específica do projeto na raiz do seu projeto.
:::
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`.
```bash
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.
```bash
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`**](https://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`.
```json title="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` - 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](/docs/tui).
---
### Servidor
Você pode configurar as configurações do servidor para os comandos `opencode serve` e `opencode web` através da opção `server`.
```json title="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 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](/docs/server).
---
### Ferramentas
Você pode gerenciar as ferramentas que um LLM pode usar através da opção `tools`.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"tools": {
"write": false,
"bash": false
}
}
```
[Saiba mais sobre ferramentas aqui](/docs/tools).
---
### 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`.
```json title="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 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`:
```json title="opencode.json"
{
"$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](/docs/models#local). [Saiba mais](/docs/models).
---
#### 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:
```json title="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 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.
:::note
Tokens Bearer (`AWS_BEARER_TOKEN_BEDROCK` ou `/connect`) têm precedência sobre a autenticação baseada em perfil. Veja [precedência de autenticação](/docs/providers#authentication-precedence) para detalhes.
:::
[Saiba mais sobre a configuração do Amazon Bedrock](/docs/providers#amazon-bedrock).
---
### Temas
Você pode configurar o tema que deseja usar em sua configuração do OpenCode através da opção `theme`.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"theme": ""
}
```
[Saiba mais aqui](/docs/themes).
---
### Agentes
Você pode configurar agentes especializados para tarefas específicas através da opção `agent`.
```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"code-reviewer": {
"description": "Revisa o código em busca de melhores práticas e problemas potenciais",
"model": "anthropic/claude-sonnet-4-5",
"prompt": "Você é um revisor de código. Foque em segurança, desempenho e manutenibilidade.",
"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](/docs/agents).
---
### 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.
```json title="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). Isso pode ser um agente embutido como `"build"` ou `"plan"`, ou um [agente personalizado](/docs/agents) 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](/docs/share) através da opção `share`.
```json title="opencode.json"
{
"$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`.
```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
"command": {
"test": {
"template": "Execute a suíte de testes completa com relatório de cobertura e mostre quaisquer falhas.\nFoque nos testes que falharam e sugira correções.",
"description": "Executar testes com cobertura",
"agent": "build",
"model": "anthropic/claude-haiku-4-5",
},
"component": {
"template": "Crie um novo componente React chamado $ARGUMENTS com suporte a TypeScript.\nInclua tipagem adequada e estrutura básica.",
"description": "Criar um novo componente",
},
},
}
```
Você também pode definir comandos usando arquivos markdown em `~/.config/opencode/commands/` ou `.opencode/commands/`. [Saiba mais aqui](/docs/commands).
---
### Atalhos de teclado
Você pode personalizar seus atalhos de teclado através da opção `keybinds`.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"keybinds": {}
}
```
[Saiba mais aqui](/docs/keybinds).
---
### 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`.
```json title="opencode.json"
{
"$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`.
```json title="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](/docs/formatters).
---
### 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:
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "ask",
"bash": "ask"
}
}
```
[Saiba mais sobre permissões aqui](/docs/permissions).
---
### Compactação
Você pode controlar o comportamento de compactação de contexto através da opção `compaction`.
```json title="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 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`.
```json title="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 barulhentos da observação de arquivos.
---
### Servidores MCP
Você pode configurar servidores MCP que deseja usar através da opção `mcp`.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"mcp": {}
}
```
[Saiba mais aqui](/docs/mcp-servers).
---
### Plugins
[Plugins](/docs/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`.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}
```
[Saiba mais aqui](/docs/plugins).
---
### Instruções
Você pode configurar as instruções para o modelo que está usando através da opção `instructions`.
```json title="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ção. [Saiba mais sobre regras aqui](/docs/rules).
---
### 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.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"disabled_providers": ["openai", "gemini"]
}
```
:::note
A opção `disabled_providers` tem prioridade sobre `enabled_providers`.
:::
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.
```json title="opencode.json"
{
"$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.
:::note
A opção `disabled_providers` tem prioridade sobre `enabled_providers`.
:::
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.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"experimental": {}
}
```
:::caution
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 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:
```json title="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, ela será substituída por uma string vazia.
---
### Arquivos
Use `{file:path/to/file}` para substituir o conteúdo de um arquivo:
```json title="opencode.json"
{
"$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.
Reference in a new issue View git blame Copy permalink