La plupart des problèmes de Crew ont un correctif qui se résume à une commande shell. Cette page est un guide de tri. Commencez par une vérification de l'état :
kirocrew doctor
doctor rapporte l'état de chaque sous-système : détection du binaire kiro-cli, authentification de l'agent, modèle d'incorporation, jetons Slack, validité de la configuration, sondes de serveur MCP et une section Identifiants pour les profils AWS. La section Identifiants répertorie les noms de profils et l'état d'actualisation sans lire ni afficher de valeurs secrètes. S'il ne trouve aucune configuration AWS, configurez les identifiants dans votre propre terminal avec aws configure sso ou aws configure, puis exécutez de nouveau kirocrew doctor.
Le répertoire cible de l'installation n'est pas dans votre PATH. Les correctifs dépendent de l'installateur :
- Installateur de roue précompilée — utilise
pipxlorsqu'il est disponible, sinon~/.kiro/crew-venv. Assurez-vous que~/.local/bin(valeur par défaut de pipx) ou~/.kiro/crew-venv/binfigure dansPATH. pip install -e .— assurez-vous que le répertoire des scripts de votre Python figure dansPATH. Habituellement~/.local/bin(installation utilisateur) ou lebin/du venv.- Docker — appelez via
docker exec kirocrew kirocrew ….
Puis source ~/.bashrc (ou redémarrez votre shell).
Sur Windows, utilisez python et py depuis un venv :
py -3.12 -m venv .venv .venv\Scripts\activate pip install -e . tzdata python -m kiro_crew gateway
tzdata est requis — Windows ne fournit aucune base de données de zones IANA, donc zoneinfo.ZoneInfo(...) échoue sans elle.
Le point d'entrée a sondé le bac à sable interne de l'espace de noms utilisateur Linux et cela a échoué sous la politique seccomp/AppArmor de l'environnement d'exécution du conteneur. Deux options :
- Autoriser les espaces de noms utilisateur — redémarrez avec
--security-opt seccomp=<profil autorisant unshare/clone>. La passerelle sonde à nouveau au prochain démarrage et active le bac à sable. - Accepter une exécution non isolée — redémarrez avec
-e KIROCREW_ALLOW_UNSANDBOXED=1. Les commandes de l'agent s'exécutent sans le bac à sable interne; le conteneur reste la seule limite d'isolation.
La sortie du journal au démarrage indique quelle posture a été choisie.
Le backend de l'agent n'a pas répondu à la prise de contact. Causes courantes :
kiro-clin'est pas installé — la page Set up Kiro du tableau de bord vous guide, oukirocrew doctorsignale un binaire manquant- Non connecté — exécutez
kiro-cli login - Configuration MCP brisée —
kirocrew setup --agent-only --cleanreconstruit l'agent à partir de zéro - Le premier lancement est lent — l'initialisation du serveur MCP peut prendre plus de 60 secondes; patientez
Le processus kiro-cli s'est arrêté brusquement. Crew récupère automatiquement en recréant la session et en réessayant. Si cela se répète :
- Consultez
kirocrew logs -fpour l'erreur sous-jacente - Si le processus a été tué par manque de mémoire (OOM), réduisez les sous-agents concurrents (
agent.max_subagents) ou augmentez la mémoire de l'hôte - Le coupe-circuit se déclenche après 5 échecs consécutifs et se réinitialise automatiquement — récupère habituellement de lui-même
Le répertoire de projet actif n'est pas défini. Vérifiez avec kirocrew config get project_dir, ou définissez-le dans l'en-tête de session du tableau de bord.
Si le CWD est défini mais que l'agent ne peut toujours pas lire un chemin particulier, consultez le bac à sable du SE — certains chemins sont masqués dans les modes auto et strict.
- Vérifiez l'état du modèle d'incorporation :
kirocrew doctorsignale si l'environnement d'exécution groupé a téléchargé le modèle - Les téléchargements à la première exécution se font en arrière-plan (~610 Mo). Attendez quelques minutes et revérifiez.
- Définissez une URL miroir si le CDN est inaccessible :
export KIROCREW_EMBED_MODEL_URL=<url> - Repliez-vous sur Ollama si vous préférez :
ollama pull qwen3-embedding:0.6bet vérifiezcurl http://localhost:11434/api/tags
Jusqu'à ce que le modèle arrive, la mémoire se replie sur la recherche par mots-clés (LIKE sur le texte + les balises). L'agent continue de fonctionner — simplement sans classement sémantique.
Le memory.db restauré est corrompu. Habituellement un problème de copie (transfert interrompu). Essayez :
kirocrew restore snapshot.tar.gz --mode replace --dry-run # preview kirocrew restore snapshot.tar.gz --mode replace --components memory
Si cela échoue toujours, l'instantané lui-même est défectueux. Restaurez à partir d'un instantané plus ancien ou importez manuellement memory.db depuis une autre source.
- Le mode incognito est activé — vérifiez l'indicateur incognito dans l'en-tête de session. Les sessions incognito n'écrivent jamais en mémoire.
- Le consolidateur ne fonctionne pas — la consolidation de la mémoire se déclenche à 30 messages (chemin des préférences) ou après 3 h d'inactivité (chemin de l'historique). Une session courte peut n'atteindre aucun des deux déclencheurs.
- Disque plein —
df -h ~/.kiro/crew; SQLite échoue silencieusement à l'écriture lorsque le disque est plein
Slack est optionnel — le tableau de bord fonctionne sans lui. Si vous voulez utiliser Slack :
- Vérifiez que les jetons sont définis :
cat ~/.kiro/crew/.envdevrait afficherSLACK_APP_TOKEN=xapp-…,SLACK_BOT_TOKEN=xoxb-…,KIROCREW_OWNER_ID=U0… - Confirmez que le mode Socket est activé dans les paramètres de votre application Slack
- Réexécutez
kirocrew setup— l'assistant demande les deux jetons kirocrew doctorsignale l'état de la connexion Slack
- Verrou du propriétaire — la passerelle Slack est verrouillée sur
KIROCREW_OWNER_ID. Seul votre identifiant de membre Slack peut envoyer un message direct au bot. Les messages non-propriétaires sont abandonnés silencieusement. - Enterprise Grid — si
slack.allowed_enterprise_idsest défini, les messages provenant d'autres espaces de travail sont abandonnés - Bot hors ligne — consultez
kirocrew logs -fpour des erreurs de déconnexion websocket
Vous avez ajouté une nouvelle fonctionnalité qui nécessite une portée non accordée au moment de l'installation. Correctif :
- Dans les paramètres de l'application Slack, ajoutez la portée manquante sous OAuth & Permissions → Bot Token Scopes
- Réinstallez l'application dans votre espace de travail (bouton Install to Workspace)
- Réexécutez
kirocrew setup— collez le nouveau jeton de bot
Ajoutez l'événement app_home_opened, activez le Home Tab dans les paramètres de l'application Slack, réinstallez l'application.
Bug connu de l'interface utilisateur de Slack. Utilisez plutôt Features → OAuth & Permissions → Install to Workspace — cela fait la même chose.
- Confirmez que
DISCORD_BOT_TOKENest défini et quekirocrew doctorsignale Discord connecté - Vérifiez que l'utilisateur figure dans
discord.allowed_users(liste d'autorisation refusant par défaut)
Ajoutez l'identifiant Discord de l'utilisateur à discord.allowed_users via la configuration ou le panneau de paramètres Discord du tableau de bord.
Discord limite les messages à 2000 caractères. Le transport se divise automatiquement. Si vous voyez une troncature au lieu d'une division, vérifiez la présence d'un formateur personnalisé fragile.
- Vérifiez que
~/.kiro/agents/kirocrew.jsoncontientkirocrew-coreetkirocrew-cron - Vérifiez que
includeMcpJson: falseest défini - Exécutez
kirocrew doctor— il signale l'état des sondes MCP - Le panneau Integrations (MCP) du tableau de bord affiche les résultats des sondes en direct
Détruit et reconstruit la configuration MCP à partir de zéro. Résout la plupart des problèmes de « MCP brisé ».
La passerelle déclenche automatiquement une sonde lorsqu'un nouveau serveur apparaît, mais les résultats ne se manifestent qu'au prochain rafraîchissement du tableau de bord. Attendez quelques secondes et rechargez. Si cela reste sur « Unknown », le serveur échoue à la prise de contact — vérifiez le texte de l'erreur ou kirocrew logs -f.
Comportement correct. kirocrew-core et kirocrew-cron sont limités à l'agent et ne devraient pas apparaître dans les sessions kiro-cli interactives. Si c'est le cas, quelque chose les a écrits dans une configuration globale de fournisseur — signalez un bogue.
Vérifiez le badge Crew sur la ligne. S'il reste vert, la règle de préservation copie la configuration du serveur dans ~/.kiro/crew/mcp.json avant de le retirer du global, il continue donc de se charger dans les sessions Crew.
Désactivez le badge Crew avant de retirer du global pour un retrait complet.
La réinitialisation de session vide le bassin préchargé. Utilisez Dashboard → Apply & Restart, ou exécutez kirocrew config set (ce qui déclenche automatiquement un redémarrage).
- Jeton expiré — générez-en un nouveau :
kirocrew token --ttl 2h - Adresse IP modifiée — les jetons du tableau de bord sont épinglés à l'IP dès la première utilisation; si votre IP a changé, générez un nouveau jeton
- Accès distant sans jeton — vous ne pouvez pas accéder au tableau de bord à distance sans un jeton valide; les trois exceptions sont les sondes de santé, les ressources statiques et l'amorçage en boucle locale uniquement
L'environnement d'exécution groupé télécharge son modèle via HTTPS depuis le CDN de Crew au démarrage de la passerelle. Vérifiez :
- L'accessibilité réseau vers le CDN
- L'espace disque dans
~/.kiro/crew/models/ - Définissez
KIROCREW_EMBED_MODEL_URLvers un miroir si le CDN par défaut est inaccessible
Jusqu'à ce que le modèle arrive, la mémoire fonctionne avec la recherche par mots-clés.
- Bassin de sessions froid — le premier message d'un nouvel onglet subit une pénalité de démarrage à froid de 3 à 5 secondes. Augmentez
session.pool_size(par défaut1) si vous disposez de RAM disponible. - Rafale de préchauffage — les conteneurs Docker avec de nombreux serveurs MCP peuvent prendre plus de 60 secondes au premier démarrage
La passerelle est encore en cours d'initialisation. Causes courantes :
- Les serveurs MCP terminent leurs sondes initiales
- Le bassin de sessions préchargé est en train d'être généré
- Le téléchargement du modèle d'incorporation est en cours
Attendez 30 secondes, puis rafraîchissez. Si cela persiste → consultez kirocrew logs -f.
kirocrew doctor # diagnose kirocrew gateway --port auto # try a random port if 5476 is in use
Si le port 5476 est utilisé :
lsof -iTCP:5476 -sTCP:LISTEN # find what's on it
- Coupe-circuit — 5 échecs consécutifs se réinitialisent automatiquement; récupère habituellement de lui-même
- Réinitialisation forcée — depuis le tableau de bord, supprimez l'emplacement et démarrez-en un nouveau
- Tout arrêter —
kirocrew restart
Le contexte de session se remplit trop rapidement. Options :
- Réduire le contexte injecté :
skills.lazy_load: truepour un budget plus strict - Augmenter le seuil de compaction :
session.autocompact_pct: 95 - Utiliser le mode incognito pour les conversations sensibles à volume élevé
Le chien de garde se déclenche à 60 min (avertissement) et 2 h (réinitialisation). Si la tâche est réellement bloquée :
- Consultez
kirocrew logs -fpour l'activité de session de l'étape spécifique - Annulez et redémarrez à partir d'une étape spécifique :
POST /api/taskrunner/{task_id}/retryavecfrom_step: N
TEST_TIMEOUTest de 90 min par exécution de test; si votre suite de tests prend plus de temps, remplacez-la par une configuration par étape ou divisez la tâche- Exécutez les tests manuellement avec
kirocrew run TASK.md --no-testpour voir ce que l'agent produit avant la barrière de test
La tâche a réessayé la même étape en échec 3 fois avec des erreurs identiques. L'exécuteur de tâches marque l'étape FAILED pour éviter de gaspiller des tentatives sur un correctif impossible.
Déboguer : vérifiez le message d'erreur de l'étape. Causes courantes :
- Le critère d'acceptation de l'étape est irréalisable compte tenu de la base de code actuelle
- Une dépendance est manquante (l'agent ne peut pas non plus l'installer)
- Le réviseur rejette pour une raison sans rapport avec la justesse
Envisagez de marquer l'étape requires_approval: true et d'inspecter l'état manuellement.
Consultez spawn list pour l'état. S'il affiche stalled (aucune activité depuis 120 s), le sous-agent est inactif — soit légitimement (en attente d'approbation), soit bloqué.
- Bloqué en attente d'approbation — vérifiez le tableau de bord pour une invite d'approbation en attente
- Bloqué — utilisez
spawn cancel <id>depuis le bouton Stop de la ligne du tableau de bord
Le récupérateur force la récupération après le délai d'expiration strict de trois heures par défaut. Définissez agent.subagent_timeout_secs pour l'ajuster.
Le sous-agent peut avoir échoué au démarrage (tâche vide, mémoire faible, cwd rejeté, refus de gouvernance). Consultez spawn list pour un état terminal failed avec la raison.
- La passerelle était hors service — le planificateur ne rattrape pas le retard au redémarrage
- La tâche est en pause —
kirocrew cron listaffiche l'état --no-cronsa été passé àgateway— le planificateur est désactivé
Vérifiez l'acheminement de la livraison :
- Par défaut : message direct Slack si configuré, sinon notification du tableau de bord
- Avec le marqueur
<!-- deliver:C0123CHANNEL -->: acheminé vers ce canal Slack - Avec
--silent: aucune notification à moins que l'agent n'en envoie une explicitement
Exécutez kirocrew config defaults pour voir les valeurs enregistrées qui correspondent toujours à une ancienne valeur par défaut. Utilisez kirocrew config defaults --adopt pour supprimer ces valeurs et utiliser les valeurs par défaut actuelles, ou kirocrew config defaults --keep pour les consigner comme intentionnelles et arrêter l'avis. Les deux commandes peuvent prendre des clés pointillées précises lorsque vous voulez décider une valeur à la fois.
kirocrew config set— déclenche automatiquement un redémarrage du bassin de sessions. Devrait fonctionner.- Changement de variable d'environnement — nécessite
kirocrew restart - Modification manuelle de fichier — vous pouvez aussi exécuter
kirocrew restartpour forcer un rechargement
Vous avez défini une valeur de configuration numérique hors de la plage autorisée. Elle a été plafonnée à la limite; l'entrée SEL enregistre le plafonnement. Ajustez votre valeur ou consultez la référence Configuration pour connaître les plages valides.
Le point de contrôle WAL a échoué parce que la passerelle détient un verrou. L'instantané se poursuit tout de même — l'API backup() de SQLite produit une copie cohérente incluant les données WAL validées. L'avertissement est informatif.
Les instantanés rejettent les liens symboliques et les liens physiques pour des raisons de sécurité. Si votre instantané en contient un (inhabituel), l'archive est mal formée. Régénérez l'instantané à partir d'une source propre.
Définissez instances.enabled: true dans ~/.kiro/crew/config.json et redémarrez la passerelle.
L'assouplissement du CSP frame-src ne s'applique qu'aux ports de tunnel actifs. Confirmez que l'instance est connectée (le panneau Manage affiche un badge connecté vert), pas seulement ajoutée.
Renouvelez les identifiants SSH (rajoutez la clé à ssh-agent). Les tunnels se réparent d'eux-mêmes une fois SSH restauré.
La sonde de santé + l'auto-réparation à deux niveaux réessaient pendant environ 2 min (8 tentatives, avec un plafond de recul exponentiel). Si elle abandonne, un diagnostic s'exécute automatiquement. Vérifiez :
- Que la passerelle distante fonctionne réellement (
ssh <host> kirocrew doctor) - La stabilité SSH du concentrateur vers le distant
- La dérive temporelle — les jetons sont signés dans le temps; un grand décalage d'horloge cause un rejet
Accordez l'autorisation d'utiliser le microphone du navigateur pour l'origine du tableau de bord. Dans Chrome : cadenas de la barre d'adresse → Site settings → Microphone → Allow.
- Vérifiez l'autorisation audio de l'onglet du tableau de bord (cadenas du navigateur)
- Confirmez que la sortie du système n'est pas coupée
- Le téléchargement de la voix Piper à la première utilisation peut ne pas être terminé; vérifiez le réseau +
~/.kiro/crew/voices/
- Essayez une pièce plus silencieuse
- Passez à
aws_transcribepour une précision de niveau infonuagique :pip install "kirocrew[voice]", puis définissezvoice.stt_provider: "aws_transcribe"et configurez les identifiants AWS
La pile de récupération est manquante pour ce profil / cette région. Deux options :
- Exécutez
install-reaper.sh --profile <name> --region <region> - Utilisez
ttl_hours: 0(persistant, aucun récupérateur nécessaire)
Les en-têtes du site déployé datent d'avant la pile de base actuelle. Tout déploiement subséquent met à jour la pile en place. En attendant, la carte affiche le statut de repli avec un lien simple — cliquez pour voir le site.
Lorsqu'un problème survient, Crew peut rassembler un ensemble de données de soutien à votre place plutôt que de vous laisser recueillir les journaux à la main. Utilisez Signaler un problème, accessible à la fois depuis le tableau de bord et l'interface en ligne de commande, pour recueillir en une seule étape un ensemble de diagnostics de soutien, afin qu'un rapport de bogue contienne ce dont un mainteneur a besoin pour le reproduire.
Chaque message d'erreur comporte aussi une transmission Demander à l'agent : au lieu de copier l'erreur ailleurs, transmettez-la directement à l'agent, qui peut lire les diagnostics et souvent suggérer le correctif ou la prochaine commande à exécuter.
Pour une vérification manuelle rapide au préalable, kirocrew doctor signale l'état de chaque sous-système, et kirocrew logs -f suit en direct le journal du gateway.
Si rien ici ne correspond à votre problème :
- Journaux détaillés —
kirocrew logs -f(suivi en direct),kirocrew doctor --verbose - Signaler un bogue — github.com/kirodotdev/KiroCrew/issues
- Consulter la source — chaque sous-système est documenté sous
docs/system-specs/modules/dans le dépôt Crew
Dépannage