Troubleshooting

Diese Seite ordnet devkit-Symptomen sichere Lösungen zu. Beginne mit devkit status und devkit doctor.

bash

devkit status     # Version, Quelle/Channel, Sync-Alter, fehlende Tools
devkit doctor     # Tiefenprüfung: Symlinks, persönliche Config, Tools
devkit version    # installierte Versionen

Symptom, Ursache und Lösung

Symptom	Ursache	Lösung	Prüfen
Signatur- oder Checksummenfehler	Artefakt unvollständig, verändert oder aus der falschen Quelle	devkit config show prüfen, dann devkit sync. Stoppt es weiterhin, nicht umgehen.	devkit status zeigt die erwartete Version
Skills oder Agents fehlen	Sync unvollständig	devkit sync, dann devkit doctor.	devkit list skills zeigt Einträge
Persönlicher Skill scheint überschrieben	Namenskollision; der Schutz hat deine Datei behalten und die geteilte inaktiv gelassen	Eine von beiden umbenennen.	devkit doctor meldet keine Kollision
Config ist veraltet	Hintergrund-Fetch noch nicht angewendet	devkit sync.	Sync-Alter in devkit status ist frisch
Tool fehlt, etwa gitleaks	Nicht installiert	devkit tools --outdated, dann devkit tools --upgrade.	Keine fehlenden Tools in devkit status
Tool hat die falsche Version	Ein älteres Binary kommt im PATH zuerst	which -a <tool> vergleichen, die fremde npm/nvm/volta/brew-Kopie entfernen, dann devkit sync.	<tool> --version entspricht dem Pin
Regression nach Update	Neue Version unerwünscht	devkit rollback oder devkit rollback <version>.	devkit status zeigt das Ziel
Hooks feuern nicht	Hooks nicht verdrahtet	devkit sync; devkit hook-install verdrahtet nur die Hooks.	Erwartete Hook-Ausgabe erscheint
Setup abschalten	Debugging, fremde Maschine oder fremdes Repository	devkit off entfernt Links und Hooks, behält aber Version und Config; devkit on stellt sie wieder her.	devkit status sagt off
Doctor sagt, ein Standard-MCP-Server sei deaktiviert	/mcp hat ihn in disabledMcpServers geschrieben; claude mcp remove löscht das nicht	In /mcp wieder aktivieren.	devkit doctor nennt ihn nicht mehr
devkit init meldet foreign-context7	Von Hand gepflegter Context7-Eintrag in der .mcp.json des Projekts	Im Terminal fragt devkit init, ob er ersetzt wird (Default ja); sonst entfernt devkit init --replace-context7 nur diesen Block, der globale Server bleibt.	Der nächste Lauf meldet keine Context7-Arbeit
Start warnt vor Write(...)-Berechtigungen	Legacy-Regel Write(pfad)	devkit init entfernt sie dort, wo Edit(pfad) existiert.	Keine Warnung beim Start
Weder od noch devkit antworten	Der Befehl wurde in v0.12.0 zu devkit, und die PATH-Links gleichen sich beim nächsten Session-Start ab	~/.onedot-devkit/current/bin/devkit bin-reconcile. Den Installer nicht erneut ausführen; er holt und synct sofort.	which -a devkit zeigt einen Eintrag
git push stoppt mit sandbox proxy refused SSH auth to github.com	Der Claude-Code-Sandbox-Proxy lässt nur HTTP(S) durch, nie SSH	Einmal pro Rechner: git config --global url."https://github.com/".insteadOf "git@github.com:" und gh auth setup-git.	git push --dry-run läuft durch
Auto-Modus fragt bei einem nur lesenden Befehl immer wieder	Der Befehl steht nicht auf der Standard-Allowlist	Nach echter Nutzung schreibt /fewer-permission-prompts eine priorisierte Allowlist aus den Projekt-Transkripten in .claude/settings.json.	Der Befehl läuft ohne Rückfrage

Der macOS-Menüleisten-Schalter hat seine eigene Seite mit seiner Symptomtabelle.

Projekt migrieren

devkit init richtet einen Projekt-Checkout für devkit ein — neu oder aus einer älteren devkit-Version —, ein Git-Checkout pro Aufruf. Git ist Pflicht, weil Git das Rückgängig ist.

bash

devkit init --dry-run   # zeigt den Plan
devkit init             # wendet ihn an
devkit init --dry-run   # prüft: "Nothing to do"

Es entfernt hängende .hooks-Einträge, deren Skript fehlt (PROJECT_HOOK_DANGLING/PROJECT_HOOK_STRIPPED), veraltete Modell-Pins — Opus- und Sonnet-ID-Pins gleichermaßen, nicht mehr auf einen Alias normalisiert — und Write(X)-Berechtigungsregeln, ignoriert Agent-State-Caches, verschiebt einen Legacy-Spec-Baum baut .agents/context/ sowie den verwalteten Block in AGENTS.md neu und macht CLAUDE.md zum einzeiligen Import @AGENTS.md. Eine lokale Skill-Datei, die ein Skript unter .claude/scripts/ nennt, das es nicht mehr gibt, wird als PROJECT_LOCAL_SKILL_DANGLING gemeldet.

Projekte, die das alte npx-ai-setup eingerichtet hat, werden nicht mehr bereinigt: entferne seine Reste, etwa .ai-setup.json und die kopierten Template-Dateien unter .claude/ und .codex/, von Hand.

Abschließender state	Bedeutung
clean	Nichts zu tun; das Projekt ist eingerichtet.
pending	Der Dry-Run hat Änderungen gefunden; führe devkit init ohne --dry-run aus.
applied	Änderungen wurden geschrieben.
attention	Nichts geschrieben; eine Phase wartet auf deine Entscheidung.

Vollständiger Reset

bash

devkit unlink  # Runtime und Zustand entfernen; MCP-Client-Einträge behalten
curl -fsSL https://devkit.one-dot.io/install.sh | sh

Der gehostete Installer führt ein frisches Onboarding durch und repariert inkompatible Runtime-Verträge.