Guida
Agenti: Build e Plan
In OpenCode V2 «Build» e «Plan» non sono modalità della TUI: sono due agenti. Questo cambia il modo in cui si passa dall'uno all'altro.
Che cos'è un agente
Un agente combina un prompt di sistema, un modello preferito, permessi e dettagli di visualizzazione. È un profilo assistente con un nome: sceglierlo cambia come lavora OpenCode, non solo l'etichetta nell'interfaccia.
Gli agenti inclusi
| Agente | ID | Modalità | A cosa serve |
|---|---|---|---|
| Build | build |
primary |
Agente di coding predefinito. Può modificare file e usare strumenti fuori dalla workspace; la lettura dei file .env chiede approvazione. |
| Plan | plan |
primary |
Esplora e pianifica senza modificare i file normali del progetto. Può scrivere i file di piano di OpenCode; i comandi shell restano soggetti ai permessi. |
| General | general |
subagent |
Ricerca e lavoro multi-step con accesso ampio agli strumenti, ma non può lanciare altri subagenti. |
| Explore | explore |
subagent |
Cerca e legge codice o fonti web senza modificare file. |
Esistono anche tre agenti nascosti (compaction,
title, summary) che svolgono manutenzione e non
si possono selezionare.
Come cambiare agente
| Azione | Come |
|---|---|
| Agente successivo | Shift+Tab |
| Lista agenti | Ctrl+X, poi A |
| Lista agenti (comando) | /agents |
| Scorciatoia personalizzata | agent.cycle in cli.json |
agent.cycle). Se
Shift+Tab non fa nulla, quasi sempre è il
terminale che la intercetta: rimappa il comando su un altro tasto.
Esempio: rimappare il cambio agente
Crea o modifica ~/.config/opencode/cli.json (su Windows
%USERPROFILE%\.config\opencode\cli.json):
{
"keybinds": {
"agent.cycle": "alt+p"
}
}
Alt+P è libero nelle impostazioni
predefinite della V2 e non collide con le scorciatoie di which-key
(Ctrl+Alt+…). Le modifiche a
cli.json vengono ricaricate senza riavviare.
Configurare un agente
Puoi definire agenti in Markdown oppure in JSON. I file Markdown stanno in:
~/.config/opencode/agents/<nome>.md
.opencode/agents/<nome>.md
Su Windows la prima cartella è
%USERPROFILE%\.config\opencode\agents\.
Markdown
---
description: Revisiona le modifiche senza toccare i file
mode: subagent
model: anthropic/claude-sonnet-5-5#high
permissions:
- action: edit
resource: "*"
effect: deny
- action: shell
resource: "*"
effect: deny
---
Revisiona le modifiche correnti. Elenca i problemi in ordine di gravità,
con file e riga.
JSON
{
"$schema": "https://opencode.ai/config.json",
"agents": {
"reviewer": {
"description": "Revisiona le modifiche correnti",
"mode": "subagent",
"system": "Riporta i problemi in ordine di gravità.",
"permissions": [
{ "action": "edit", "resource": "*", "effect": "deny" }
]
}
}
}
Campi principali
| Campo | Significato |
|---|---|
mode | primary (agente principale), subagent (solo sessione figlia) o all. Default per un nuovo agente: primary. |
model | provider/modello, con variante opzionale #high. |
system | Prompt di sistema. In Markdown è il corpo del file. |
description | Spiega lo scopo, soprattutto per i subagenti. |
permissions | Regole ordinate: action, resource, effect (allow, ask, deny). Vince l'ultima regola che corrisponde. |
steps | Numero massimo di passi del modello. |
hidden | Nasconde l'agente dagli elenchi. Non è una misura di sicurezza. |
disabled | Rimuove un agente (anche incluso) in quel punto della configurazione. |
color | Colore dell'agente, esadecimale a sei cifre. |
Agente predefinito
Per scegliere l'agente usato quando una sessione non ne ha già uno:
{
"$schema": "https://opencode.ai/config.json",
"default_agent": "plan",
"agents": {
"plan": { "mode": "primary" }
}
}
L'agente predefinito deve esistere, essere visibile e supportare l'uso
come primario. Altrimenti OpenCode usa build, poi il primo
agente primario visibile.
Disattivare un agente incluso
{
"$schema": "https://opencode.ai/config.json",
"agents": {
"plan": { "disabled": true }
}
}
Utile se vuoi che Shift+Tab non passi più da Plan.