Explication détaillée de la configuration de l'agent OpenCode

Les agents sont des assistants IA spécialisés dans OpenCode. Chaque agent peut être configuré avec son propre prompt système, modèle, autorisations d'accès aux outils et contraintes comportementales pour gérer des types spécifiques de tâches et de flux de travail. Vous pouvez changer d'agent à tout moment pendant une session, ou en@ProxyNameinvoquant directement un agent spécifique.

Types d'agents

Dans OpenCode, les agents sont divisés en deux types, chacun avec des méthodes d'invocation et des responsabilités différentes :

Type Description Méthode de commutation
Agent principal L'assistant principal avec lequel vous interagissez directement, gérant le flux de conversation principal. Les autorisations d'accès aux outils se font viapermissionconfiguration appuyezTabune commutation cyclique par touche, ou utilisez leagent_cycleraccourci clavier configuré
Sous-agent Un assistant invoqué par l'agent principal pour effectuer des tâches spécialisées, s'exécutant dans une session enfant indépendante sans affecter le contexte de la session principale Automatiquement invoqué par l'agent principal, ou manuellement invoqué dans un message à l'aide de@ProxyNameinvoquer manuellement

Agents intégrés

OpenCode inclut 4 agents prêts à l'emploi, ainsi que 3 agents système s'exécutant automatiquement :

1. Build (Agent principal)

L'agent principal par défaut, avec tous les outils activés, adapté au travail de développement quotidien nécessitant des opérations complètes sur les fichiers et l'accès aux commandes système. C'est l'agent que vous utiliserez le plus souvent.

2. Plan (Agent principal)

Un agent restreint conçu spécifiquement pour l'analyse de code et la planification. Par défaut, les opérations suivantes déclenchent toutes une invite d'approbation (défini surask）：

  • modifications de fichiers: toutes les opérations d'écriture, de correctif et de modification
  • bash: toutes les commandes bash

Lorsque vous souhaitez que le LLM analyse le code, fasse des suggestions ou crée un plan d'exécution, mais que vous ne voulez pas qu'il apporte de modifications réelles à la base de code, basculez vers l'agent Plan.

3. General (Sous-agent)

Un sous-agent polyvalent avec un accès complet aux outils (sauf l'outil todo) et la capacité de modifier des fichiers. Adapté à la recherche de problèmes complexes et à l'exécution de tâches en plusieurs étapes, et peut également exécuter plusieurs unités de travail indépendantes en parallèle.

4. Explore (Sous-agent)

Un sous-agent en lecture seule qui ne peut modifier aucun fichier. Adapté pour trouver rapidement des fichiers, rechercher des mots-clés dans le code ou répondre à des questions sur la structure de la base de code. Il est rapide et sans effets secondaires.

5. Agents système (masqués)

Les trois agents suivants sont automatiquement gérés par OpenCode,et n'apparaissent pas dans la liste de commutation d'agentsIl n'est pas nécessaire ni possible de les sélectionner manuellement :

Nom de l'agent Responsabilité Moment de déclenchement
Compaction Compresse un contexte trop long en un résumé plus court pour éviter de dépasser la limite de contexte du modèle S'exécute automatiquement lorsque la longueur du contexte atteint un seuil
Title Génère un titre court pour la session S'exécute automatiquement après le démarrage d'une nouvelle session
Résumé Crée un résumé pour la session S'exécute automatiquement lorsqu'un résumé de session est nécessaire

Comment utiliser les agents

1. Changer d'agents principaux

Pendant une session, appuyez surTabla touche pour parcourir tous les agents principaux, appuyez surShift+Tabpour basculer en sens inverse. Vous pouvez aussi utiliser<Leader>apour ouvrir la liste des agents et sélectionner directement.

2. Invoquer des sous-agents

Il existe deux façons d'invoquer des sous-agents :

  • Invocation automatique: Lorsque l'agent principal détermine qu'un certain sous-agent est nécessaire en fonction de la nature de la tâche, il invoque automatiquement le sous-agent et lui délègue la tâche
  • Invocation manuelle @: Utilisez dans un message@ProxyNamepour spécifier directement quel sous-agent doit s'en charger
@general help me search for this function across the codebase

3. Naviguer entre les sessions parentes et enfants

Lorsqu'un sous-agent s'exécute, il crée une session enfant indépendante. Vous pouvez utiliser des raccourcis clavier pour naviguer entre la session parente et chaque session enfant :

Raccourci clavier Action
<Leader>+→（session_child_cycle） Parcourir en avant : Session parente → Session enfant 1 → Session enfant 2 → … → Session parente
<Leader>+←（session_child_cycle_reverse） Parcourir en arrière : Session parente ← Session enfant 1 ← Session enfant 2 ← … ← Session parente
<Leader>+↑（session_parent） Revenir directement à la session parente

Deux méthodes de configuration

Les agents peuvent être définis soit via une configuration JSON, soit via des fichiers Markdown. Les deux méthodes ont le même effet ; choisissez selon vos besoins :

Méthode 1 : Configurer dans opencode.json

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {                                           // Surcharger la configuration de l'agent build intégré
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",           // Charger le prompt système depuis un fichier
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "code-reviewer": {                                   // Sous-agent personnalisé
      "description": "Passe en revue le code pour les bonnes pratiques et les problèmes potentiels",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "Vous êtes un relecteur de code. Concentrez-vous sur la sécurité, les performances et la maintenabilité.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Méthode 2 : fichier Markdown

Créer un.mdfichier dans le chemin suivant,Le nom du fichier est le nom de l'agent(e.g.,review.mdcorrespond au nom de l'agentreview）：

  • Global :~/.config/opencode/agents/(Valable pour tous les projets)
  • Niveau projet :.opencode/agents/(Valable uniquement pour le projet actuel)

Exemple

# Chemin du fichier : ~/.config/opencode/agents/review.md
---
description: Examine le code pour la qualité et les bonnes pratiques
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

Vous êtes en mode de revue de code. Concentrez-vous sur:

- Qualité du code et bonnes pratiques
- Bugs potentiels et cas limites
- Implications sur les performances
- Considérations de sécurité

Fournissez des retours constructifs sans apporter de modifications directes.

Options de configuration expliquées

description (Description)

Une description des fonctionnalités de l'agent, affichée dans la liste des agents et@menu d'autocomplétion. Il aide les utilisateurs et l'agent principal à décider quand invoquer cet agent. Pour les agents personnalisés, ce champ estobligatoire：

Exemple

{
  "agent": {
    "review": {
      "description": "Passe en revue le code pour les bonnes pratiques et les problèmes potentiels"
    }
  }
}

mode (Mode)

Contrôle la façon dont l'agent est utilisé. Il peut être défini sur l'une des trois valeurs suivantes :

Valeur Description
"primary" Agent principal, apparaît dans la liste de commutation d'onglets, utilisé pour la conversation principale
"subagent" Sous-agent, absent de la liste de commutation d'onglets, invoqué par l'agent principal ou manuellement via @
"all" Utilisé à la fois comme agent principal et comme sous-agent (valeur par défaut lorsque mode n'est pas spécifié)

Exemple

{
  "agent": {
    "review": {
      "mode": "subagent"    // Utilisé uniquement comme sous-agent, n'apparaît pas dans la liste de commutation des agents principaux
    }
  }
}

model (Modèle)

Spécifie un modèle spécifique pour l'agent, en remplaçant le modèle par défaut de la configuration globale. Le format estprovider/model-id. Convient pour utiliser différents modèles pour différentes tâches, par exemple un petit modèle plus rapide pour les tâches de planification et un grand modèle plus puissant pour la génération de code :

Exemple

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"    // Utiliser le modèle Haiku plus rapide pour les tâches de planification
    },
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514"   // Utiliser le modèle Sonnet plus performant pour les tâches de développement
    }
  }
}

S'il n'est pas spécifiémodel, l'agent principal utilisera le modèle par défaut de la configuration globale, et les sous-agents hériteront du modèle utilisé par l'agent principal qui les a invoqués. En exécutantopencode modelsVous pouvez consulter la liste de tous les modèles disponibles.

prompt (Invite système)

Spécifiez une invite système personnalisée pour l’agent. Vous pouvez écrire directement une chaîne, ou utiliser la{file:./路径}syntaxe pour charger depuis un fichier externe. Le chemin est relatif à l’emplacement du fichier de configuration :

Exemple

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
      // Lire l’invite depuis prompts/code-review.txt dans le même répertoire que opencode.json
      // Convient aux invites longues ; conservez-les séparément dans un fichier texte
    }
  }
}

temperature

Contrôle le caractère aléatoire de la sortie du modèle. Des valeurs plus faibles produisent une sortie plus déterministe, adaptée aux tâches nécessitant des résultats précis ; des valeurs plus élevées produisent une sortie plus diversifiée, adaptée aux tâches créatives :

Plage de température Caractéristiques de sortie Scénarios applicables
0.0 – 0.2 Très concentré, très déterministe Analyse de code, planification, débogage, revue
0.3 – 0.5 Équilibré, combinant précision et flexibilité Tâches de développement générales, rédaction de documentation
0.6 – 1.0 Plus créatif et diversifié Brainstorming, exploration de solutions, écriture créative

Exemple

{
  "agent": {
    "analyze": {
      "temperature": 0.1,                          // Tâches d'analyse : déterminisme élevé
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3                           // Tâches de développement : équilibré
    },
    "brainstorm": {
      "temperature": 0.7,                          // Brainstorming : plus créatif
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Lorsque non spécifiétemperature, OpenCode utilise la valeur par défaut du modèle — la plupart des modèles utilisent par défaut0, tandis que les modèles de la série Qwen utilisent par défaut0.55。

steps (Nombre maximal d'étapes)

Contrôle le nombre maximal d'itérations (c'est-à-dire, cycles d'appels d'outils) que l'agent peut exécuter avant d'être forcé de répondre en texte brut. Convient aux scénarios où vous devez contrôler les coûts ou empêcher l'agent de boucler indéfiniment :

Exemple

{
  "agent": {
    "quick-thinker": {
      "description": "Raisonnement rapide avec un nombre limité d'itérations",
      "prompt": "Vous êtes un penseur rapide. Résolvez les problèmes avec un minimum d'étapes.",
      "steps": 5    // Exécuter au maximum 5 itérations ; ensuite, l'agent produira un résumé de la progression actuelle et des tâches suggérées restantes
    }
  }
}

Lorsqu'il n'est pas définisteps, l'agent continuera d'itérer jusqu'à ce que le modèle s'arrête de lui-même ou que l'utilisateur l'interrompe manuellement.

HéritémaxStepschamp est obsolète, veuillez utilisersteps。

tools (Accès aux outils)

Contrôle les outils que cet agent peut utiliser. Définissez le nom de l'outil surtrueoufalse. La configuration au niveau de l'agent varemplacer la configuration globale：

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,     // Global : autoriser l'écriture de fichiers
    "bash": true       // Global : autoriser les commandes bash
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,    // plan agent : remplacer les paramètres globaux, désactiver l'écriture de fichiers
        "bash": false      // plan agent : remplacer les paramètres globaux, désactiver bash
      }
    }
  }
}

Vous pouvez également utiliser des jokers pour contrôler les outils en masse, par exemple, désactiver tous les outils d'un serveur MCP particulier :

Exemple

{
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,    // Désactiver tous les outils du serveur mymcp (correspondance Glob)
        "write": false,
        "edit": false
      }
    }
  }
}

permission (Permissions)

Configurez un contrôle des autorisations plus fin pour l'agent. Vous pouvez définir chaque opération sur"allow"(autoriser),"ask"(demander), ou"deny"(deny) :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"         // Global : refuser par défaut toute édition de fichier
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"      // agent de build : surcharger les paramètres globaux, exiger une approbation avant modification
      }
    }
  }
}

Pourbashles outils, vous pouvez affiner davantage vers des commandes spécifiques, avec prise en charge des caractères génériques Glob, etla dernière règle correspondante est prioritaire(Il est recommandé de placer*les règles avec caractères génériques d'abord, et les règles spécifiques ensuite) :

Exemple

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",             // Repli : toutes les commandes bash nécessitent une approbation par défaut
          "git status *": "allow",// les commandes liées à git status sont autorisées directement (plus spécifique, prend la priorité)
          "grep *": "allow"       // les commandes de recherche grep sont autorisées directement
        }
      }
    }
  }
}

Dans un fichier d'agent Markdown, vous pouvez également configurer les autorisations dans le frontmatter :

Exemple

# Chemin du fichier : ~/.config/opencode/agents/review.md
---
description: Revue de code sans modifications
mode: subagent
permission:
  edit: deny          # Refuser toute modification de fichier
  bash:
    "*": ask          # Les commandes bash nécessitent une approbation par défaut
    "git diff": allow # Autoriser git diff
    "git log*": allow # Autoriser git log et ses variantes
    "grep *": allow   # Autoriser la recherche grep
  webfetch: deny      # Refuser l'accès aux URL externes
---

Analyser uniquement le code et suggérer des modifications.

permission.task (Autorisations des tâches)

Contrôle quels sous-agents cet agent peut appeler via l'outil Task. Prend en charge la correspondance Glob. Défini sur"deny", le sous-agent sera complètement supprimé de la description de l'outil Task, et le modèle ne tentera pas de l'appeler :

Exemple

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",                  // Solution de repli : refuser par défaut l'appel de tous les sous-agents
          "orchestrator-*": "allow",   // Autoriser l'appel des sous-agents commençant par orchestrator-
          "code-reviewer": "ask"        // L'appel à code-reviewer nécessite la confirmation de l'utilisateur
          // La dernière règle correspondante est prioritaire : orchestrator-planner correspond à la fois à * et orchestrator-*,
          // Comme orchestrator-* vient plus tard, le résultat est allow
        }
      }
    }
  }
}

hidden (Masqué)

Masque le sous-agent du@menu d'autocomplétion, et permet uniquement son appel par programmation via l'outil Task. Convient aux sous-agents d'outils qui ne doivent être appelés qu'en interne par d'autres agents :

Exemple

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",    // hidden ne fonctionne que pour les sous-agents
      "hidden": true         // Après masquage, cet agent n'apparaîtra pas dans le menu de complétion @ de l'utilisateur,
                             // mais lorsque les permissions le permettent, le modèle peut toujours l'appeler via l'outil Task
    }
  }
}

color

Personnalise la couleur d'affichage de l'agent dans l'interface. Prend en charge les valeurs de couleur hexadécimales ou les mots-clés de couleur de thème (primary、secondary、accent、success、warning、error、info）：

Exemple

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"      // Utiliser une couleur hexadécimale
    },
    "code-reviewer": {
      "color": "accent"       // Utiliser un mot-clé de couleur de thème
    }
  }
}

top_p (Diversité d'échantillonnage)

top_pOuitemperatureUn autre paramètre pour contrôler la diversité de sortie, avec une plage de valeurs de 0.0 – 1.0. Des valeurs plus faibles produisent une sortie plus concentrée, des valeurs plus élevées produisent une sortie plus diversifiée :

Exemple

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9    // Un top_p plus élevé augmente la diversité de sortie
    }
  }
}

disable (Désactiver)

Définit l'agent sur un état désactivé. Une fois désactivé, l'agent n'apparaîtra pas dans la liste de sélection :

Exemple

{
  "agent": {
    "review": {
      "disable": true    // Désactiver cet agent sans affecter les autres agents
    }
  }
}

Autres paramètres du modèle

Tous les champs non reconnus dans la configuration de l'agent seront transmis directement au fournisseur de services en tant que paramètres de modèle. Cela vous permet d'utiliser des fonctionnalités avancées spécifiques au fournisseur :

Exemple

{
  "agent": {
    "deep-thinker": {
      "description": "Agent qui utilise un effort de raisonnement élevé pour les problèmes complexes",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",    // Paramètre d'effort de raisonnement d'OpenAI, transmis directement à l'API OpenAI
      "textVerbosity": "low"        // Paramètre de verbosité de la réponse OpenAI
    }
  }
}

Les paramètres transmis varient selon le fournisseur de service et le modèle. Veuillez consulter la documentation API du fournisseur correspondant pour confirmer les noms des paramètres disponibles.

Créer rapidement des agents

En plus d'écrire manuellement les fichiers de configuration, vous pouvez également utiliser l'outil interactif en ligne de commande pour générer rapidement un agent :

opencode agent create

Cette commande vous guidera à travers les étapes suivantes, dans l'ordre :

  1. Choisissez où enregistrer l'agent (global~/.config/opencode/agents/ou au niveau du projet).opencode/agents/）
  2. Décrivez les responsabilités et les objectifs de l'agent
  3. Générez automatiquement un prompt système approprié et un identifiant de l'agent
  4. Choisissez les outils auxquels l'agent peut accéder
  5. Générez un fichier Markdown avec la configuration complète à l'emplacement sélectionné

Exemples d'agents

Agent de rédaction de documentation

Exemple

# Chemin du fichier : ~/.config/opencode/agents/docs-writer.md
---
description: Rédige et maintient la documentation du projet
mode: subagent
tools:
  bash: false    # Désactiver bash ; l'écriture de documentation n'a pas besoin d'exécuter de commandes
---

Vous êtes un rédacteur technique. Créez une documentation claire et complète.

Concentrez-vous sur:
- Explications claires
- Structure appropriée
- Exemples de code
- Langage accessible

Agent d'audit de sécurité

Exemple

# Chemin du fichier : ~/.config/opencode/agents/security-auditor.md
---
description: Effectue des audits de sécurité et identifie les vulnérabilités
mode: subagent
tools:
  write: false    # Lecture seule : ne pas écrire de fichiers
  edit: false     # Lecture seule : ne pas modifier de fichiers
---

Vous êtes un expert en sécurité. Concentrez-vous sur l'identification des problèmes de sécurité potentiels.

Recherchez:
- Vulnérabilités de validation des entrées
- Failles d'authentification et d'autorisation
- Risques d'exposition des données
- Vulnérabilités des dépendances
- Problèmes de sécurité liés à la configuration

Cas d'utilisation courants

Scénario Configuration d'agent recommandée
Développement quotidien, nécessite des autorisations complètes pour les outils Utilisez l'agent intégréBuildagent
Analysez le code et créez des plans sans modifier les fichiers Passez à l'agent intégréPlanagent
Requête en lecture seule sur la structure de la base de code ou les mots-clés Via@exploreAppelez le sous-agent intégréExploresubagent
Exécutez plusieurs tâches indépendantes en parallèle Via@generalappeler plusieursGeneralsous-agents pour le traitement parallèle
Effectuer une revue de sécurité ou de qualité sur le code Sous-agent personnalisé en lecture seule (désactiver l’écriture/édition), définir une température basse (0.1)
Contrôler les coûts, limiter les étapes d’exécution de l’IA Configurezstepsparamètre pour limiter le nombre maximum d’itérations
Autres extensions