Skip to content

The open source coding agent.

TypeScript
8.8 KB
Raw Blame
---
title: Modos
description: Modos diferentes para diferentes casos de uso.
---

:::caution
Os modos agora são configurados através da opção `agent` na configuração do opencode. A opção `mode` agora está obsoleta. [Saiba mais](/docs/agents).
:::

Os modos no opencode permitem que você personalize o comportamento, as ferramentas e os prompts para diferentes casos de uso.

Ele vem com dois modos integrados: **build** e **plan**. Você pode personalizar esses ou configurar os seus próprios através da configuração do opencode.

Você pode alternar entre os modos durante uma sessão ou configurá-los no seu arquivo de configuração.

---

## Integrados

O opencode vem com dois modos integrados.

---

### build

Build é o modo **padrão** com todas as ferramentas habilitadas. Este é o modo padrão para trabalho de desenvolvimento onde você precisa de acesso total a operações de arquivos e comandos do sistema.

---

### plan

Um modo restrito projetado para planejamento e análise. No modo plan, as seguintes ferramentas estão desativadas por padrão:

- `write` - Não pode criar novos arquivos
- `edit` - Não pode modificar arquivos existentes, exceto para arquivos localizados em `.opencode/plans/*.md` para detalhar o plano em si
- `patch` - Não pode aplicar patches
- `bash` - Não pode executar comandos de shell

Este modo é útil quando você deseja que a IA analise o código, sugira alterações ou crie planos sem fazer modificações reais em sua base de código.

---

## Alternando

Você pode alternar entre modos durante uma sessão usando a tecla _Tab_. Ou sua tecla de atalho configurada `switch_mode`.

Veja também: [Formatadores](/docs/formatters) para informações sobre configuração de formatação de código.

---

## Configuração

Você pode personalizar os modos integrados ou criar os seus próprios através da configuração. Os modos podem ser configurados de duas maneiras:

### Configuração JSON

Configure os modos no seu arquivo de configuração `opencode.json`:

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "mode": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}
```

### Configuração Markdown

Você também pode definir modos usando arquivos markdown. Coloque-os em:

- Global: `~/.config/opencode/modes/`
- Projeto: `.opencode/modes/`

```markdown title="~/.config/opencode/modes/review.md"
---
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.
```

O nome do arquivo markdown se torna o nome do modo (por exemplo, `review.md` cria um modo `review`).

Vamos analisar essas opções de configuração em detalhes.

---

### Modelo

Use a configuração `model` para substituir o modelo padrão para este modo. Útil para usar diferentes modelos otimizados para diferentes tarefas. Por exemplo, um modelo mais rápido para planejamento, um modelo mais capaz para implementação.

```json title="opencode.json"
{
  "mode": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}
```

---

### Temperatura

Controle a aleatoriedade e a criatividade das respostas da IA com a configuração `temperature`. Valores mais baixos tornam as respostas mais focadas e determinísticas, enquanto valores mais altos aumentam a criatividade e a variabilidade.

```json title="opencode.json"
{
  "mode": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}
```

Os valores de temperatura geralmente variam de 0.0 a 1.0:

- **0.0-0.2**: Respostas muito focadas e determinísticas, ideais para análise de código e planejamento
- **0.3-0.5**: Respostas equilibradas com alguma criatividade, boas para tarefas de desenvolvimento geral
- **0.6-1.0**: Respostas mais criativas e variadas, úteis para brainstorming e exploração

```json title="opencode.json"
{
  "mode": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}
```

Se nenhuma temperatura for especificada, o opencode usa padrões específicos do modelo (geralmente 0 para a maioria dos modelos, 0.55 para modelos Qwen).

---

### Prompt

Especifique um arquivo de prompt do sistema personalizado para este modo com a configuração `prompt`. O arquivo de prompt deve conter instruções específicas para o propósito do modo.

```json title="opencode.json"
{
  "mode": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}
```

Este caminho é relativo a onde o arquivo de configuração está localizado. Portanto, isso funciona tanto para a configuração global do opencode quanto para a configuração específica do projeto.

---

### Ferramentas

Controle quais ferramentas estão disponíveis neste modo com a configuração `tools`. Você pode habilitar ou desabilitar ferramentas específicas definindo-as como `true` ou `false`.

```json
{
  "mode": {
    "readonly": {
      "tools": {
        "write": false,
        "edit": false,
        "bash": false,
        "read": true,
        "grep": true,
        "glob": true
      }
    }
  }
}
```

Se nenhuma ferramenta for especificada, todas as ferramentas estão habilitadas por padrão.

---

#### Ferramentas disponíveis

Aqui estão todas as ferramentas que podem ser controladas através da configuração do modo.

| Ferramenta  | Descrição                       |
| ----------- | ------------------------------- |
| `bash`      | Executar comandos de shell      |
| `edit`      | Modificar arquivos existentes   |
| `write`     | Criar novos arquivos            |
| `read`      | Ler conteúdos de arquivos       |
| `grep`      | Pesquisar conteúdos de arquivos |
| `glob`      | Encontrar arquivos por padrão   |
| `list`      | Listar conteúdos de diretório   |
| `patch`     | Aplicar patches a arquivos      |
| `todowrite` | Gerenciar listas de tarefas     |
| `webfetch`  | Buscar conteúdo da web          |

---

## Modos personalizados

Você pode criar seus próprios modos personalizados adicionando-os à configuração. Aqui estão exemplos usando ambas as abordagens:

### Usando configuração JSON

```json title="opencode.json" {4-14}
{
  "$schema": "https://opencode.ai/config.json",
  "mode": {
    "docs": {
      "prompt": "{file:./prompts/documentation.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": false,
        "read": true,
        "grep": true,
        "glob": true
      }
    }
  }
}
```

### Usando arquivos markdown

Crie arquivos de modo em `.opencode/modes/` para modos específicos do projeto ou `~/.config/opencode/modes/` para modos globais:

```markdown title=".opencode/modes/debug.md"
---
temperature: 0.1
tools:
  bash: true
  read: true
  grep: true
  write: false
  edit: false
---

You are in debug mode. Your primary goal is to help investigate and diagnose issues.

Focus on:

- Understanding the problem through careful analysis
- Using bash commands to inspect system state
- Reading relevant files and logs
- Searching for patterns and anomalies
- Providing clear explanations of findings

Do not make any changes to files. Only investigate and report.
```

```markdown title="~/.config/opencode/modes/refactor.md"
---
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
tools:
  edit: true
  read: true
  grep: true
  glob: true
---

You are in refactoring mode. Focus on improving code quality without changing functionality.

Priorities:

- Improve code readability and maintainability
- Apply consistent naming conventions
- Reduce code duplication
- Optimize performance where appropriate
- Ensure all tests continue to pass
```

---

### Casos de uso

Aqui estão alguns casos de uso comuns para diferentes modos.

- **Modo Build**: Trabalho de desenvolvimento completo com todas as ferramentas habilitadas
- **Modo Plan**: Análise e planejamento sem fazer alterações
- **Modo Review**: Revisão de código com acesso somente leitura e ferramentas de documentação
- **Modo Debug**: Focado em investigação com ferramentas bash e de leitura habilitadas
- **Modo Docs**: Redação de documentação com operações de arquivo, mas sem comandos do sistema

Você também pode descobrir que diferentes modelos são bons para diferentes casos de uso.