Nouveau sur Kiro CLI V3? Cette page couvre la migration depuis la CLI 2.x. Si vous configurez les autorisations pour la première fois, commencez par la référence actuelle des autorisations. Sans
permissions.yaml, Kiro autorise les lectures dans l'espace de travail et les commandes en lecture seule courantes, bloque les écritures dans ses propres paramètres et demande une approbation avant les autres opérations.
Kiro CLI V3 remplace les règles toolsSettings persistantes par outil par des politiques permissions.yaml structurées. L'indicateur de démarrage --trust-all-tools et la commande à barre oblique /tools trust-all accordent une confiance à l'échelle de la session. Dans les exécutions V3 non interactives, --trust-tools peut approuver à l'avance des ID d'outils V3 exacts ; l'interface terminal interactive de V3 ignore cet indicateur. Utilisez des règles allow permissions.yaml à portée définie pour les politiques de capacités réutilisables.
Le changement fondamental consiste à passer d'une configuration par outil à des règles de capacités qui s'appliquent de façon cohérente à chaque outil effectuant le même type d'opération. Le schéma des règles, les portées, les effets, les préréglages et la syntaxe des motifs sont documentés une seule fois dans Autorisations; cette page couvre seulement ce qui change lorsque vous migrez depuis la 2.x.
| Comportement 2.x | Comportement V3 | Migration |
|---|---|---|
toolsSettings avec des listes allow et deny par outil | permissions.rules unifié avec capability, match et effect | Réécrivez en utilisant le tableau de migration de toolsSettings → |
autoAllowReadonly configurait l'approbation des commandes shell en lecture seule | Politique read-only-shell générée par /upgrade-agent, sauf si l'ancien denyByDefault s'applique aussi | Exécutez /upgrade-agent, vérifiez la politique générée et ajoutez des règles allow shell pour toute commande supplémentaire que vous utilisez |
denyByDefault bloquait les opérations d'outils non listées | Règles deny explicites, avec des exceptions exclude facultatives | Utilisez { capability: shell, exclude: ["git *", "npm *"], effect: deny } pour tout refuser sauf les motifs exclus; consultez Syntaxe Exclude |
| Motifs regex dans les autorisations | Motifs glob seulement (pas de regex) | Réécrivez .* en *, \.ts$ en *.ts, etc. |
Caractère générique ? pour un seul caractère dans les motifs de commandes | Non pris en charge pour les motifs shell ou URL | Utilisez * ou explicitez les alternatives. Les motifs de chemins de fichiers (fs_read, fs_write) prennent toujours en charge ? |
| Restrictions de lecture et d'écriture configurées par outil | Une seule règle de capacité s'applique à chaque outil qui effectue cette opération | Tenez compte de la portée plus large de fs_read, fs_write et des autres capacités; consultez la liste des capacités sous Fonctionnement |
| Refus par outil évalués indépendamment | Le refus l'emporte toujours, dans toutes les portées | Supprimez les autorisations en conflit ou restreignez le motif de refus |
| Les outils préapprouvés d'un sous-agent s'exécutaient sans invite, même si le parent ne les autorisait pas | L'appel d'outil d'un sous-agent s'exécute sans invite seulement lorsque la politique de la session parente l'autorise aussi | Ajoutez les règles allow du sous-agent aux permissions.rules de l'agent parent ou à permissions.yaml. Consultez Autorisations des sous-agents |
Ces contrôles s'appliquent seulement à la session en cours :
# Trust every tool in a V3 session kiro-cli chat --v3 --trust-all-tools # In headless V3, trust exact tool IDs kiro-cli chat --v3 --no-interactive --trust-tools=read_file,grep_search "Review this repository" # In interactive V3, trust every tool after startup /tools trust-all
Dans V3, --trust-tools est pris en compte seulement avec --no-interactive et correspond à des ID d'outils; dans Kiro CLI 3.3.0 ou version ultérieure, il accepte aussi des noms d'outils V2, des références @server et des motifs */? (consultez le mode sans interface). L'interface terminal interactive de V3 l'ignore. La CLI 2.x accepte ses propres noms d'outils. Pour des règles réutilisables ou au niveau des capacités, utilisez permissions.yaml.
Créez ~/.kiro/settings/permissions.yaml pour les règles à portée utilisateur, ou un fichier à portée d'espace de travail à ~/.kiro/workspace-roots/<hash>/permissions.yaml pour limiter les règles à un projet. Les fichiers d'espace de travail sont stockés par utilisateur hors du dépôt, de sorte qu'un dépôt cloné ne peut pas injecter de règles d'autorisation. Pour le format du fichier, les portées et des exemples concrets, consultez Définition des règles et Portées.
Approve for me et son effet evaluate sont documentés dans Autorisations. Ils ne constituent pas une étape de migration : aucun paramètre 2.x ne leur correspond.
Le sélecteur de règles à trois niveaux qui apparaît lorsqu'une session V3 pose une question sur une commande shell est documenté dans Autorisations. La CLI 2.x n'avait aucun sélecteur équivalent.
Pour les pipelines d'intégration continue qui utilisaient auparavant --trust-all-tools, créez un fichier d'autorisations à portée utilisateur dans votre environnement d'intégration continue :
# ~/.kiro/settings/permissions.yaml (CI environment) rules: - capability: all effect: allow
L'indicateur --trust-all-tools fonctionne toujours comme un remplacement à portée de session et continue de fonctionner pour les cas d'utilisation d'intégration continue sans changement de configuration.
Une exécution sans interface refuse les appels d'outils d'un sous-agent que la politique de la session parente n'autorise pas, même lorsque les propres règles du sous-agent les autorisent. --trust-all-tools approuve les appels d'outils des sous-agents qui demanderaient autrement une approbation. Les règles deny s'appliquent toujours.
Une fois vos règles en place, poursuivez avec la migration des Hooks si vos agents 2.x intégraient des Hooks, ou revenez au guide de migration.
Migration des autorisations