Permissions OpenCode 2 : migrer depuis V1 et rétablir les confirmations d’accès externe

Ajoutez une règle explicite external_directory avec effect: "ask" pour rétablir les confirmations d’accès aux répertoires externes après le passage à OpenCode 2. Au 2026-10-31, le guide officiel de migration indique que V2 utilise allow par défaut, contre ask dans V1. Conservez la configuration V1 compatible jusqu’à pouvoir convertir ses règles dans le tableau ordonné permissions de V2.

Ce guide propose une configuration de base pour le développement interactif et une procédure de vérification prenant OpenCode v2.2.0 comme référence. Les résultats attendus reposent sur la documentation et le code source portant ce tag de version, pas sur un test du client en fonctionnement.

Pourquoi V2 autorise-t-il les chemins externes si une vérification sans correspondance utilise ask ?

Les règles intégrées participent à l’évaluation. L’absence d’une règle définie par l’utilisateur ne signifie donc pas qu’aucune règle ne correspond à l’opération.

D’après la section Defaults de V2, chaque agent commence avec une règle d’autorisation utilisant des caractères génériques. Elle contient action: "*", resource: "*" et effect: "allow". Les règles de base suivantes demandent confirmation avant de lire *.env et *.env.*, puis autorisent *.env.example. Les agents fournis peuvent ajouter des restrictions.

Les lectures, modifications, commandes shell et vérifications de répertoires externes courantes disposent donc déjà d’une règle de base correspondante. Le résultat de repli ask ne s’applique que si aucune règle de l’ensemble évalué ne correspond. Ne considérez pas l’absence de réglages read ou edit comme une obligation de demander confirmation.

L’approbation d’un répertoire externe et celle d’une opération sur un fichier restent distinctes. OpenCode considère la Location active et l’arbre de travail du projet, sauf si cet arbre correspond à la racine du système de fichiers. Pour les chemins situés hors de ces deux zones, il vérifie external_directory avant read ou edit. Ici, Location désigne l’emplacement de travail actif. Un fichier externe peut donc franchir la vérification de périmètre tout en restant soumis à une restriction de lecture ou de modification.

Cet ordre vient du mécanisme de vérification des répertoires, pas de la position d’actions portant des noms différents dans le tableau. Placer une règle external_directory avant une règle read ne détermine pas cet ordre de vérification.

Peut-on conserver la configuration V1 et quels noms changent ?

Oui. Le format natif V2 est facultatif. OpenCode normalise la configuration V1 compatible sans vous obliger à réécrire ses fichiers d’origine. Les instructions de migration recommandent de vérifier les modèles, identifiants, agents, permissions et serveurs MCP existants avant de tout convertir.

V1 regroupe les décisions de permission par outil :

{
  "permission": {
    "bash": {
      "git push *": "ask"
    },
    "edit": "allow"
  },
  "tools": {
    "websearch": false
  }
}

La conversion V2 documentée exprime ces réglages explicites sous forme de règles ordonnées :

{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

Chaque règle exige trois champs de type chaîne : action, resource et effect. allow laisse poursuivre sans demander confirmation, deny bloque l’opération et ask attend une décision dans le client.

Cet exemple convertit uniquement les réglages affichés. Il ne constitue pas la configuration de base recommandée plus bas. Il autorise toujours les modifications et ne rétablit pas les confirmations pour les répertoires externes.

Les actions sont renommées ainsi : bash → shell, task → subagent et write/patch → edit. Dans V2, edit contrôle les chemins cibles des opérations edit, write et patch. subagent compare un ID d’agent ; shell compare les chaînes de commandes produites par l’analyseur. La référence des actions indique aussi que doom_loop et lsp ne font pas partie des actions de permission actuelles de V2 Core.

Examinez les réglages de premier niveau, les définitions d’agents et les scripts qui génèrent la configuration. Ne remplacez pas ces mots dans des fichiers sans rapport. Après une conversion volontaire, évitez de laisser des définitions V1 et V2 concurrentes pour les mêmes permissions.

Utilisez une configuration de base prudente pour les permissions V2

Pour le développement interactif, demandez confirmation avant les accès externes, les commandes shell et les modifications. Autorisez les vérifications Git courantes, refusez les commandes push correspondantes et bloquez la lecture des fichiers d’environnement, sauf ceux d’exemple.

Placez les réglages propres au dépôt dans opencode.jsonc, à la racine du projet. Utilisez ~/.config/opencode/opencode.jsonc pour la configuration de votre utilisateur. OpenCode accepte aussi les variantes .json ; la référence de configuration décrit les emplacements pris en charge.

Intégrez ce tableau à la configuration existante. Conservez les réglages du fournisseur, les définitions d’agents et les restrictions déjà présentes, au lieu de remplacer tout le fichier.

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" }
  ]
}

L’exception .env.example suit volontairement les deux règles qui refusent la lecture. Réservez cette exception aux fichiers d’exemple ne contenant aucun secret.

Les actions non spécifiées continuent d’hériter de leurs réglages par défaut effectifs. Cette configuration ne bloque pas tous les outils MCP, n’empêche pas tous les moyens possibles de faire un push et n’isole pas le système de fichiers hôte. Ses restrictions read n’interdisent pas non plus aux commandes shell de lire les mêmes fichiers.

L’avertissement concernant le shell précise que ses commandes conservent les privilèges de l’utilisateur hôte. L’identification des répertoires concernés n’est pas exhaustive. Vérifiez les commandes avant de les approuver et ajoutez des contrôles shell distincts lorsque les règles sur les fichiers ne suffisent pas.

Pour un autre client, consultez les permissions Claude Code pour les secrets et Git. N’y réutilisez pas la syntaxe de configuration d’OpenCode.

Placez les exceptions après les règles qu’elles remplacent

L’ordre compte entre les règles qui correspondent à la même action et à la même ressource. Une correspondance ultérieure remplace la décision précédente. Un caractère générique dans l’action peut couvrir plusieurs noms d’actions.

Dans la configuration de base, shell: "*" exige d’abord une confirmation. Les règles suivantes, git status * et git diff *, autorisent ces commandes. La règle git push * refuse les commandes push correspondantes.

Un motif shell se terminant par * correspond aussi à la commande sans argument. Ainsi, git status * couvre à la fois git status et git status --short.

La référence de correspondance définit des motifs appliqués à la valeur entière. * correspond à zéro ou plusieurs caractères, y compris / ; ? correspond à un caractère. Les séparateurs de chemins sont normalisés en barres obliques et, sous Windows, la comparaison ignore la casse.

Une opération portant sur plusieurs ressources demande une étape supplémentaire. Déterminez d’abord la dernière règle correspondante de chaque ressource. Tout refus ainsi obtenu bloque l’opération ; sinon, toute demande de confirmation impose une approbation. Les commandes shell composées peuvent produire plusieurs ressources. Autoriser une commande Git n’autorise donc pas toute la commande composée.

Ajoutez un répertoire externe de confiance avec précaution

Autorisez séparément l’accès au répertoire de confiance et les opérations sur ses fichiers. Ces règles facultatives complètent la configuration de base ; elles ne la remplacent pas :

[
  { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "edit", "resource": "~/projects/reference/*", "effect": "deny" }
]

Placez l’autorisation d’accès externe après la règle générale external_directory avec ask. Placez l’autorisation de lecture avant les refus visant les fichiers d’environnement, pour conserver ces restrictions. Placez le refus de modification après la règle générale qui demande confirmation avant de modifier.

Les règles de répertoires acceptent les références initiales au répertoire personnel, comme ~/, pour ces actions sur les chemins. Les ressources shell restent le texte brut des commandes. Elles ne bénéficient pas de cette expansion lors du chargement de la configuration.

Le refus de modification bloque les opérations contrôlées par edit, notamment les outils write et patch. Il ne bloque pas les modifications effectuées via le shell. Maintenez des restrictions shell distinctes et examinez toute approbation susceptible de permettre une modification de ces fichiers.

Migrez, puis validez avec des fichiers de test sans risque

Sauvegardez les fichiers réellement utilisés, demandez une proposition de modifications et validez la configuration acceptée dans un projet jetable. Commencez avec un client V2 installé et une connexion fonctionnelle au fournisseur et au modèle.

Examinez la migration proposée avant de l’appliquer

Sauvegardez la configuration globale et celle du projet, y compris les définitions d’agents dans .opencode/agents/. La documentation sur les emplacements des agents inclut aussi les définitions utilisateur dans ~/.config/opencode/agents/.

Traitez séparément les plugins, les intégrations à l’API du serveur et les réglages du terminal. Le guide de migration signale des changements incompatibles dans ces domaines.

Transmettez ce prompt à OpenCode. Il demande une revue préalable et interdit de modifier les fichiers avant approbation :

Read the official OpenCode V1 migration and V2 permissions documentation.

Inspect my global, project, and agent permission configuration.
Do not modify any files yet.

Propose native V2 permissions rules.
Preserve unrelated settings and existing restrictions.
Map bash to shell, task to subagent, and write and patch to edit where applicable.
Identify unsupported fields and competing V1/V2 definitions.
Restore external_directory approval without weakening existing deny rules.
Use the baseline's shell and edit approval rules unless existing rules are stricter.
Put environment-file denies before the .env.example exception.
Show the complete proposed diff and explain every behavior change.
Wait for approval before applying it.

Vérifiez le résultat fusionné, pas uniquement le fichier du projet. Les permissions propres à l’agent suivent les règles de premier niveau déjà résolues. Une autorisation ultérieure de l’agent peut donc remplacer un refus ordinaire de premier niveau.

Pour les restrictions imposées par une organisation, consultez les politiques OpenCode. Elles peuvent bloquer une opération après l’évaluation des permissions de l’agent et des approbations enregistrées. Un tableau ordinaire de permissions ne remplace pas une restriction imposée par un administrateur.

Après avoir accepté les modifications, rechargez la configuration avec opencode reload. La référence CLI décrit cette commande ; examinez les avertissements de configuration avant de poursuivre.

Effectuez une série de vérifications

Prenez v2.2.0 et l’agent intégré build comme référence pour les résultats attendus ci-dessous. Le tableau suppose que la configuration de base est effective, sans règles d’agent contradictoires, approbations enregistrées ni politiques supplémentaires.

Créez des fichiers de test sans données sensibles dans Bash :

lab=$(mktemp -d)
mkdir -p "$lab/project" "$lab/outside"
git -C "$lab/project" init -q
printf 'ordinary fixture\n' > "$lab/project/README.md"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env.example"
printf 'outside fixture\n' > "$lab/outside/fixture.txt"
cd "$lab/project"

Enregistrez la configuration de base dans le fichier opencode.jsonc de ce projet, puis lancez opencode. Sélectionnez build avec /agents, comme l’indique le guide de l’interface de terminal.

Demandez à l’agent de tenter chaque opération séparément avec l’outil indiqué. Les commandes exécutées manuellement dans le terminal ne remplacent pas les vérifications de permissions de l’agent.

Opération de l’agent	Résultat attendu de la vérification
Lire README.md avec read	Autorisé par la règle de lecture de base
Lire ../outside/fixture.txt avec read	Confirmation demandée pour le répertoire externe ; lecture ordinaire autorisée après approbation
Lire .env avec read	Refusé
Lire .env.example avec read	Autorisé
Modifier README.md avec edit, write ou patch	Confirmation demandée via edit
Exécuter git status, git status --short ou git diff via shell	Autorisé
Exécuter git push via shell	Refusé par la règle shell correspondante
Exécuter pwd via shell	Confirmation demandée

Avant de vérifier le push, exécutez vous-même git remote et confirmez qu’aucun nom ne s’affiche. N’ajoutez pas de dépôt distant. Une erreur Git signalant l’absence de dépôt distant ne prouve pas que les permissions ont bloqué la commande.

Pour les tests d’approbation, choisissez Allow once (« Autoriser une fois »), plutôt qu’Allow always (« Toujours autoriser »). Les approbations enregistrées persistent pour le projet et peuvent supprimer les demandes suivantes, mais elles ne remplacent pas les refus configurés. Gardez l’approbation automatique désactivée.

Examinez la requête réelle de l’outil, la décision de permission et les modifications des fichiers. Une promesse du modèle de ne pas faire de push ou de ne pas lire un fichier ne prouve pas que le moteur de permissions l’a bloqué.

Cherchez la cause d’un écart avant d’assouplir une règle

Vérifiez d’abord la configuration chargée et l’agent sélectionné. Les commandes de débogage CLI comprennent opencode debug config et opencode debug agents. Examinez leur sortie localement ; ne partagez ni identifiants ni configuration sensible.

Si aucune confirmation n’apparaît pour un accès externe, vérifiez que la cible se trouve hors de la Location et de l’arbre de travail du projet. Contrôlez ensuite les approbations enregistrées et l’approbation automatique. Si une lecture produit un résultat inattendu, vérifiez que l’agent a utilisé read, et non shell.

Si une commande Git est bloquée, examinez la ressource produite par l’analyseur et les éventuelles sous-commandes. Si .env.example est refusé, cherchez une règle *.env.* ultérieure ou une politique supplémentaire qui remplace l’exception prévue.

Vérifiez séparément le fournisseur existant, l’ID du modèle, l’authentification et la Base URL. Les instructions d’intégration OpenCode de BetterToken décrivent une connexion personnalisée compatible OpenAI utilisant https://www.bettertoken.ai/v1. Cette connexion ne remplace pas la configuration des permissions d’OpenCode.

Si la migration implique aussi de choisir un outil, comparez les configurations et modes d’accès de Cursor et OpenCode. Pour évaluer une autre méthode de travail dans le terminal, utilisez la même tâche jetable avec Aider ou OpenCode dans un projet Git.

Que change le correctif du système de fichiers dans v2.2.0 ?

Le correctif change la manière dont les vérifications de répertoires externes retrouvent les fichiers du projet. Il ne change pas la recommandation de définir explicitement une règle d’approbation.

Les notes de version v2.2.0 mentionnent le passage au système de fichiers du projet. Le PR #59089 explique que les projets distants ou en mémoire consultaient auparavant le disque de la machine hôte. Son auteur précise que les projets locaux ordinaires ne sont pas concernés.

Pour un projet distant, recommencez la vérification du répertoire externe sur le système de fichiers réel de ce projet. Les réglages par défaut de V2 documentés au 2026-10-31 nécessitent toujours une règle explicite external_directory avec ask ou deny pour imposer cette limite.