Configuration des autorisations OpenCode

Le système de permissions d'OpenCode contrôle quelles opérations peuvent s'exécuter automatiquement, lesquelles nécessitent votre approbation manuelle et lesquelles sont directement bloquées. Bien configurer les permissions permet à l'IA d'accomplir les tâches efficacement tout en évitant les opérations accidentelles qui pourraient endommager le code ou divulguer des fichiers sensibles.

À partir de la v1.1.1, l'anciennetoolsconfiguration booléenne a été dépréciée et fusionnée danspermission. L'ancienne configuration est toujours prise en charge pour la compatibilité descendante, mais il est recommandé de migrer vers la nouvellepermissionsyntaxe.

Trois actions de permission

Chaque règle de permission se résout finalement en l'une des trois actions suivantes :

Action Effet Scénarios applicables
"allow" S'exécute automatiquement sans approbation Opérations à faible risque et à haute fréquence, telles que la lecture de fichiers et l'exécution de tests
"ask" Affiche une invite d'approbation pour que vous décidiez d'autoriser ou non Opérations présentant un certain risque, telles que l'écriture de fichiers et l'exécution de scripts
"deny" Bloquées directement, ni exécutées ni soumises à une invite Opérations dangereuses explicitement interdites, telles que la suppression de fichiers et le push de code

Configuration de base

La configuration des permissions est écrite sous le répertoire racine du dépôt (ou le répertoire de configuration utilisateur) dans leopencode.jsonfichier, en utilisantpermissionchamp à configurer.

1. Définir toutes les permissions globalement

La façon la plus simple : utiliser une seule chaîne pour définir les permissions de toutes les opérations en une fois. Convient pour un démarrage rapide ou un débogage temporaire :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
"permission": "allow" // Toutes les opérations s'exécutent automatiquement sans aucune invite de confirmation (convient au développement local, lorsqu'on fait entièrement confiance à l'IA)
}

2. Configurer par nom d'outil

En utilisant la syntaxe d'objet, vous pouvez spécifier les permissions pour différents outils séparément."*"est un joker, ce qui signifie qu'il correspond à toutes les opérations, généralement utilisé comme valeur par défaut de repli :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask", // Règle de repli : tous les outils non configurés individuellement affichent par défaut une invite
"bash": "allow", // bash (exécution de commandes Shell) : autoriser directement, sans invite
"edit": "deny" // edit (modification de fichiers) : bloquer directement
  }
}

Règles granulaires (syntaxe d'objet)

Pour la plupart des permissions, en plus de définir une action unifiée, vous pouvez également utiliserla syntaxe d'objetpour appliquer différentes règles en fonction de l'entrée spécifique de l'outil. Par exemple, pourbashoutils, vous pouvez distinguer quelles commandes sont autorisées, lesquelles nécessitent une approbation et lesquelles sont directement rejetées :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
"*": "ask", // Repli : toutes les commandes bash nécessitent une approbation par défaut
"git *": "allow", // Les commandes commençant par git (par ex., git status, git log) sont autorisées directement
"npm *": "allow", // Les commandes commençant par npm (par ex., npm install, npm run build) sont autorisées directement
"grep *": "allow", // Les commandes de recherche grep sont autorisées directement
"rm *": "deny" // Les commandes de suppression rm sont directement bloquées (pour éviter la suppression accidentelle de fichiers)
    },
    "edit": {
"*": "deny", // Bloquer toutes les modifications de fichiers par défaut
"packages/web/src/content/docs/*.mdx": "allow" // Autoriser uniquement la modification des fichiers .mdx dans le répertoire docs
    }
  }
}

Ordre de correspondance des règles : la dernière règle correspondante est prioritaire.Il est recommandé de placer la règle joker"*"règle en haut comme valeur par défaut, et de placer les règles plus spécifiques après elle pour la remplacer. Ainsi, plus une règle est spécifique, plus sa priorité est élevée, ce qui rend la logique claire et moins sujette aux erreurs.

Règles de joker

Les motifs d'autorisation prennent en charge une correspondance simple avec des jokers, selon les règles suivantes :

Joker Signification Exemple
* Correspond à zéro ou plusieurs caractères arbitraires (sans traverser les répertoires) git *Correspondancesgit status、git log --onelinewait
** Correspond à n'importe quel chemin à travers les répertoires ~/projects/**Correspond à tous les fichiers et sous-répertoires sous projects
? Correspond exactement à un caractère arbitraire file?.txtCorrespondancesfile1.txt、fileA.txt
Autres caractères Correspond exactement par valeur littérale git statusCorrespond uniquementgit status, ne correspond pas aux variantes avec paramètres

Remarque :Pour les commandes avec paramètres, veillez à l'ajouter à la fin*. Par exemple"grep *"peut correspondregrep pattern file.txt, lorsqu'il est écrit seul"grep"ne correspond qu'aux commandes nues sans aucun paramètre, ce qui ne sera presque jamais mis en correspondance lors de l'exécution réelle.

Expansion du répertoire personnel

Au début d'un motif, vous pouvez utiliser~ou$HOMEpour faire référence au répertoire personnel de l'utilisateur actuel, et OpenCode le développera automatiquement en chemin complet :

Exemple

// Les trois formes suivantes ont le même effet, toutes se développent en /Users/username/projects/* (le chemin varie selon le système)
"~/projects/*"
"$HOME/projects/*"
"/Users/username/projects/*" // Écrire directement le chemin absolu fonctionne aussi, mais n'est pas recommandé (pas assez portable)

Autorisations des répertoires externes (external_directory)

Par défaut, OpenCode autorise uniquement les outils à accéder àle répertoire de travail au démarrageet à ses sous-répertoires. Si vous devez accéder à des chemins en dehors du répertoire du projet (par exemple, un autre projet ou un répertoire de configuration partagé), vous devez utiliserexternal_directoryune autorisation explicite.

Expansion du répertoire personnel (~/...) n'est qu'unenotation abrégée de chemin, et n'autorise pas automatiquement l'accès à ce chemin. Les chemins en dehors du répertoire de travail doivent encore passer parexternal_directorypour être autorisés.

1. Autoriser l'accès aux répertoires externes

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow" // Autoriser l'accès à tous les fichiers et sous-répertoires sous ~/projects/personal/
// ** correspond aux sous-chemins à n'importe quel niveau
    }
  }
}

2. Autoriser la lecture mais interdire la modification

Enexternal_directoryLes répertoires autorisés héritent des autorisations par défaut de l’espace de travail actuel. Commereada pour valeur par défaut"allow", après autorisation, les fichiers situés sous ce répertoire peuvent être lus. Si vous devez restreindre davantage une opération donnée (par exemple, autoriser la lecture mais interdire la modification), vous pouvez ajouter des règles supplémentaires :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow" // Étape 1 : Accorder l’accès à ce répertoire externe
    },
    "edit": {
"~/projects/personal/**": "deny" // Étape 2 : Ajouter une règle prioritaire sur ce répertoire, autorisant la lecture mais interdisant la modification
    }
  }
}

Tous les éléments d’autorisation disponibles

Les autorisations d’OpenCode utilisent les noms d’outils comme clés, couvrant tous les types, y compris les opérations sur fichiers, l’exécution de commandes et l’accès réseau :

Élément d’autorisation Opération contrôlée Contenu correspondant au motif Valeur par défaut
read Lire le contenu des fichiers Chemin de fichier (par ex.,src/index.js） allow（.envfichiers exclus)
edit Toutes les modifications de fichiers, incluant edit, write, patch et multiedit Chemin du fichier allow
glob Recherche de fichiers par glob (par ex., trouver tous.tsfichiers) Motif glob (par ex.,**/*.ts） allow
grep Rechercher du texte dans le contenu des fichiers Motif d'expression régulière allow
list Lister les fichiers dans un répertoire Chemin du répertoire allow
bash Exécuter une commande shell Commande complète analysée (par ex.,git status --porcelain） allow
task Démarrer un sous-agent Nom du type de sous-agent allow
skill Charger une compétence Nom de la compétence allow
lsp Exécuter une requête du service de langage LSP La configuration fine n'est actuellement pas prise en charge allow
webfetch Récupérer le contenu d'une URL réseau URL complète (par ex.,https://example.com/api） allow
websearch Recherche Web Chaîne de requête de recherche allow
codesearch Recherche de code Chaîne de requête de recherche allow
external_directory Accéder aux chemins en dehors du répertoire de travail Chemin du répertoire externe ask
doom_loop Déclenché lorsque le même outil est appelé 3 fois de suite avec la même entrée (empêche l'IA de rester bloquée dans une boucle) — ask

Description de l'autorisation par défaut

Si vous n'avez configuré aucune autorisation, OpenCode utilise les valeurs par défaut intégrées suivantes :

  • La plupart des autorisations d'outils sont définies par défaut sur"allow", ce qui signifie qu'elles s'exécutent automatiquement sans demander de confirmation
  • doom_loopetexternal_directoryEst défini par défaut sur"ask", ce qui nécessite une approbation manuelle
  • readLa lecture de tous les fichiers est autorisée par défaut, mais.envles fichiers associés bénéficient d'une protection intégrée :

Exemple

// Règles de lecture par défaut intégrées d'OpenCode (aucune configuration manuelle nécessaire, pour référence uniquement)
{
  "permission": {
    "read": {
"*": "allow", // Autoriser la lecture de tous les fichiers par défaut
"*.env": "deny", // Bloquer la lecture des fichiers .env (empêcher la fuite des mots de passe de base de données, des clés API, etc.)
"*.env.*": "deny", // Bloquer la lecture des variantes telles que .env.local, .env.production
"*.env.example": "allow" // Autoriser la lecture de .env.example (fichier d'exemple, aucun secret réel)
    }
  }
}

Trois options dans l'invite d'approbation

Lorsque l'autorisation d'une opération est"ask", OpenCode affiche une invite d'approbation proposant les trois choix suivants :

Option Effet Scénario d'application
une fois (cette fois uniquement) Approuver uniquement cette requête ; la même opération demandera à nouveau une confirmation la prochaine fois Autoriser temporairement une opération sans l'activer de façon permanente
toujours (toujours autoriser) Ajouter le motif correspondant à l'opération à la liste blanche ; plus d'invites pour le reste de la session en cours Confirmer qu'un type d'opération est sûr et souhaitez qu'il passe automatiquement dans cette session
rejeter (refuser) Rejeter cette requête ; l'opération ne sera pas exécutée L’opération semble risquée et vous ne voulez explicitement pas qu’elle soit exécutée

En sélectionnantalwaysaprès, OpenCode fera en sorte que l’outil fournisse automatiquement un motif de liste blanche suggéré (par ex., après approbationgit status, il ajoutera généralementgit status*à la liste blanche).La liste blanche n’est valide que pour la session en cours et sera réinitialisée après le redémarrage d’OpenCode.

Configurer les autorisations séparément pour les agents

Si votre flux de travail utilise plusieurs agents, vous pouvez remplacer la configuration des autorisations pour chaque agent individuellement. Les autorisations des agents sont fusionnées avec la configuration globale, etles règles des agents ont priorité sur les règles globales。

1. Configurer les autorisations des agents dans opencode.json

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
// Autorisations globales : opérations git autorisées, mais commit et push interdits
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
"build": { // Agent nommé build
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
"git commit *": "ask", // Remplace le paramètre global : l'agent build autorise commit, mais nécessite une approbation
"git push *": "deny", // Hérite du paramètre global : push reste interdit
          "grep *": "allow"
        }
      }
    }
  }
}

2. Configurer les autorisations des agents dans les fichiers Markdown

Les agents peuvent également être configurés via des fichiers Markdown, avec les autorisations écrites dans le YAML Front Matter en haut du fichier (---la partie située entre les deux) :

Exemple

# Chemin du fichier : ~/.config/opencode/agents/review.md
---
description: Agent de revue de code (analyse uniquement le code, n'effectue aucune modification)
mode: subagent
permission:
  edit: deny        # Interdire toute modification de fichier
  bash: ask         # les commandes bash nécessitent une approbation
  webfetch: deny    # Interdire l'accès aux URL externes
---

Analyser uniquement le code et suggérer des modifications.
# Ci-dessous se trouve le prompt système de l'agent, décrivant les responsabilités et les normes comportementales de l'agent

Exemples de configuration pratiques

Exemple 1 : Mode conservateur (toutes les opérations nécessitent une approbation)

Convient à ceux qui débutent avec OpenCode ou lorsque vous travaillez sur des projets importants ; toutes les opérations nécessitent une confirmation manuelle :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask" // Toutes les opérations de tous les outils déclenchent des demandes d'approbation
  }
}

Exemple 2 : Configuration de développement courante (opérations de lecture autorisées, opérations d'écriture nécessitant une approbation)

Convient au développement quotidien : permet à l'IA de lire et rechercher librement du code, mais nécessite une confirmation lors de la modification de fichiers et de l'exécution de commandes :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask", // Repli : les outils non configurés individuellement nécessitent une approbation par défaut
"read": "allow", // Lecture de fichiers : autoriser directement
"glob": "allow", // Recherche de fichiers avec glob : autoriser directement
"grep": "allow", // Recherche de contenu : autoriser directement
"list": "allow", // Lister les répertoires : autoriser directement
    "bash": {
"*": "ask", // les commandes bash nécessitent une approbation par défaut
"git status *": "allow", // Voir git status : autoriser
"git log *": "allow", // Voir git log : autoriser
"git diff *": "allow", // Voir git diff : autoriser
"npm run *": "allow", // Exécuter les scripts npm : autoriser
"npm test *": "allow", // Exécuter les tests : autoriser
"rm *": "deny" // Supprimer des fichiers : bloquer directement
    }
  }
}

Exemple 3 : Autoriser l'accès à plusieurs répertoires de projet

Lorsque l'IA doit travailler sur plusieurs répertoires de projet, accordez l'accès aux répertoires externes :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow", // Autoriser l'accès aux répertoires de projet personnels
"~/projects/work/**": "allow", // Autoriser l'accès aux répertoires de projet professionnels
"~/dotfiles/**": "allow" // Autoriser l'accès au répertoire dotfiles
    },
    "edit": {
"~/dotfiles/**": "deny" // Même si l'accès aux dotfiles est autorisé, la modification est interdite (lecture seule)
    }
  }
}
Autres extensions