Mods für Ihre Organisation verwalten

Steuern Sie Mods in Claude Code mit verwalteten Einstellungen: Verhindern Sie von Benutzern installierte Mods, lassen Sie nur Ihre eigenen zu, prüfen Sie, was ein Mod tun kann, und setzen Sie Richtlinien mit Ihrem eigenen Mod durch.

Ein Mod ist ein Plugin, das Code innerhalb von Claude Code mit den Berechtigungen des Benutzers ausführt, der es installiert hat. Mods laufen nicht in einer Sandbox. Über verwaltete Einstellungen legen Sie fest, ob Mods auf den Rechnern Ihrer Benutzer ausgeführt werden, welche davon und in welcher Reihenfolge. Sie können auch einen eigenen Mod installieren, der überwacht oder ablehnt, was andere Mods tun.

Diese Seite richtet sich an die Person, die verwaltete Einstellungen für Claude Code bereitstellt, ob als Datei, über MDM oder über die claude.ai-Admin-Konsole. Mods sind in Claude Code v2.1.286 und höher standardmäßig aktiviert. Beginnen Sie mit dem Abschnitt, der Ihrem Anliegen entspricht:

• Eigene Mods der Benutzer ausschließen, mit oder ohne eigene Mods: Das Laden von Mods verhindern, die von Benutzern installiert wurden
• Sehen, was Ihre Benutzer erhalten, wenn Sie nichts ändern: Das Standardverhalten kennen
• Mods mit anderen Einschränkungen aktiviert lassen: Festlegen, wie viel erlaubt ist

Verhindern, dass von Benutzern installierte Mods geladen werden

Um zu verhindern, dass Mods geladen werden, die Ihre Benutzer mitbringen, setzen Sie die Option allowManagedModsOnly für den integrierten Wächter, einen Richtlinien-Mod, den Claude Code vor jedem von einem Benutzer installierten Mod lädt. Die Option gehört in die verwalteten Einstellungen unter pluginConfigs, mit dem Schlüssel cc-plugin-sec-default@builtin:

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": {
        "allowManagedModsOnly": true
      }
    }
  }
}

Wenn die Option in den verwalteten Einstellungen gesetzt ist:

• Kein Mod, den ein Benutzer mitbringt, wird geladen: Das umfasst einen Mod in einem Plugin, das der Benutzer installiert hat, einen mit --plugin-dir geladenen Mod und einen Mod, den Claude während einer Sitzung geschrieben hat
• Die Mods Ihrer Organisation werden weiterhin geladen: Ein Mod, der als Mod Ihrer Organisation gilt, wird nicht geprüft. Jeder andere Mod gilt als Mod eines Benutzers und wird nicht geladen. Dazu gehört ein Mod in einem Plugin, das Sie aus einem GitHub- oder anderen Remote-Marketplace aktivieren, sowie einer, den Ihre Organisation auf claude.ai für ihre Mitglieder aktiviert. Wenn keiner als Ihrer gilt, wird kein installierter Mod geladen.
• Benutzer können dies nicht rückgängig machen: Der Wächter liest die Option nur aus den verwalteten Einstellungen, sodass derselbe Eintrag in einer Benutzer-, Projekt- oder lokalen Einstellungsdatei oder in einer mit --settings übergebenen Datei nichts ändert
• Eine Datei- oder MDM-Richtlinie gilt für jeden Anbieter: Wenn Sie die Option als Datei oder über MDM bereitstellen, funktioniert sie auf Amazon Bedrock, Google Clouds Agent Platform und Microsoft Foundry auf die gleiche Weise. Informationen zur Bereitstellung über die Admin-Konsole von claude.ai finden Sie unter Plattformverfügbarkeit
• Andere Anpassungen der Benutzer funktionieren weiterhin: Ihre Hooks in Einstellungsdateien, Statuszeilen und /goal sind nicht betroffen
• Integrierte Mods laufen weiterhin: In Claude Code integrierte Mods, wie die Unterstützung für AGENTS.md, haben jeweils einen eigenen Schalter

Um die Option auf dem Rechner eines Benutzers zu überprüfen, starten Sie Claude Code dort mit --plugin-dir und dem Pfad eines Verzeichnisses, das einen Mod enthält, zum Beispiel claude --plugin-dir ./first-mod. Die Hooks des Mods werden nicht ausgeführt, und das Transkript sowie das Debug-Log enthalten die Meldung des Wächters, die den Mod und allowManagedModsOnly nennt. Wenn der Mod geladen wird, lesen Sie Prüfen, ob eine Richtlinie in Kraft ist und die Regeln, die bestimmen, ob eine Option wirksam wird.

Wenn Sie während des Early Access CLAUDE_CODE_ENABLE_FUNCTION_HOOKS auf 0 gesetzt haben, ersetzen Sie dies durch diese Option. Claude Code v2.1.287 und neuer ignoriert die Variable unabhängig von ihrem Wert, sodass eine 0 dort Mods aktiviert lässt.

Wissen, was standardmäßig geschieht

Ohne eigene Mod-Einstellungen erhalten Ihre Benutzer Folgendes:

• Mods sind aktiviert. Ein Benutzer kann ein Plugin, das einen Mod enthält, aus jedem Marketplace installieren, den Ihre Plugin-Einstellungen zulassen, oder einen Mod mit --plugin-dir aus einem Verzeichnis laden.

• Ein integrierter Wächter läuft zuerst. Claude Code lädt einen integrierten Mod namens sec-default@builtin vor jedem Mod, den ein Benutzer installiert. Benutzer können ihn nicht ausschalten. /plugin und das Debug-Log führen ihn als cc-plugin-sec-default. Der Wächter wird geladen, wenn eine der folgenden Bedingungen zutrifft:

  • Der Rechner verfügt über verwaltete Einstellungen
  • Der Benutzer ist bei Claude Code mit einem Team- oder Enterprise-Plan angemeldet

  Ein Benutzer, der sich mit einem API-Schlüssel oder über Amazon Bedrock, die Agent Platform von Google Cloud oder Microsoft Foundry authentifiziert, erhält den Wächter nur auf einem Rechner mit verwalteten Einstellungen.

• Der Wächter schützt, was Sie verwalten. Der Mod eines Benutzers kann nicht ändern, was Ihre verwalteten Hooks erhalten oder entscheiden, den System-Prompt, Ihre verwaltete CLAUDE.md und andere verwaltete Anweisungen, was ein Mod als Einstellungen liest, oder die Tools und Beschreibungen Ihrer verwalteten MCP-Server.

• Alles andere ist erlaubt. Der Wächter fügt keine weiteren Einschränkungen hinzu. Der Mod eines Benutzers kann weiterhin Dateien lesen und schreiben, Prozesse starten, Netzwerkanfragen stellen, Tool-Aufrufe und Prompts umschreiben, einen Tool-Aufruf ablehnen, einen Aufruf genehmigen, für den sonst eine Berechtigungsabfrage erscheinen würde, und in der Oberfläche zeichnen, alles mit den Berechtigungen dieses Benutzers.

• Deny-Regeln und Ihre verwalteten Hooks haben Vorrang. Wo der Wächter geladen wird, kann der Mod eines Benutzers keinen Aufruf genehmigen, den eine deny-Regel ablehnt, unabhängig davon, in welcher Einstellungsdatei die Regel steht. Eine Blockierung durch einen PreToolUse-Hook in verwalteten Einstellungen ist ebenfalls endgültig. Beides gilt für die Tool-Aufrufe von Claude. Keines von beiden gilt für die eigenen $.fs- und $.process-Aufrufe eines Mods: Wenn Read(.env) abgelehnt ist, kann ein Mod diese Datei trotzdem mit $.fs.read lesen oder ein Programm starten, das dies tut. Um diese Aufrufe einzuschränken, verhindern Sie, dass der Mod geladen wird, oder behandeln Sie den Aufruf in einem Richtlinien-Mod.

• Andere Berechtigungsprüfungen können übergangen werden. Der Mod eines Benutzers, der Tool-Aufrufe genehmigt, kann einen Aufruf genehmigen, für den eine ask-Regel nachfragen würde oder den ein PreToolUse-Hook außerhalb der verwalteten Einstellungen blockiert hat. Im Auto-Modus wird ein vom Mod genehmigter Aufruf ohne Prüfung durch den Klassifikator ausgeführt.

Der Quellcode des Wächters ist öffentlich im Verzeichnis mods/sec-default des Claude Code-Repositorys verfügbar.

Wissen, welche Kontrollen weiterhin gelten

Mods ersetzen die Kontrollen, die Sie bereits haben, nicht:

• Einstellungs-Hooks funktionieren weiterhin. Command-, HTTP-, Prompt- und Agent-Hooks in Einstellungsdateien und in hooks/hooks.json von Plugins laufen wie bisher, parallel zu Mods. Nichts davon ist veraltet.
• Deny-Regeln haben Vorrang, wo der Wächter geladen wird. Der Mod eines Benutzers kann keinen Aufruf genehmigen, den eine deny-Regel ablehnt, es sei denn, Sie setzen allowModsToOverrideDenyRules.
• Verwaltete Hooks laufen zuerst. Ein PreToolUse-Hook in verwalteten Einstellungen läuft, bevor ein Mod den Tool-Aufruf sieht, und seine Blockierung ist endgültig. Wenn ein Mod den Aufruf anschließend umschreibt, laufen Ihre verwalteten Hooks erneut für den umgeschriebenen Aufruf, sodass eine Blockierung weiterhin gilt. PreToolUse-Hooks aus anderen Einstellungsdateien und aus Plugins laufen nach dem letzten Mod, sodass ein Mod, der anstelle der Ausführung des Tools ein eigenes Ergebnis zurückgibt, deren Ausführung verhindert. Siehe Die Reihenfolge, in der Mods laufen.
• Die Netzwerkrichtlinie gilt für $.http.fetch. Wenn Ihre Organisation das Abrufen aus dem Web deaktiviert oder nicht wesentlicher Netzwerkverkehr für die Sitzung ausgeschaltet ist, lehnt Claude Code eine Netzwerkanfrage ab, die ein Mod mit $.http.fetch stellt. Die Richtlinie gilt nicht für ein Programm, das der Mod mit $.process.run startet. Dieses Programm greift mit dem eigenen Zugriff des Benutzers auf das Netzwerk zu.
• Plugin-Kontrollen gelten für Mods. Ein Mod ist ein Plugin, daher entscheiden die Einstellungen, die einschränken, was Benutzer installieren können, etwa strictKnownMarketplaces, ob er überhaupt installiert werden kann.
• Mods können die Berechtigungsabfrage nicht ändern. Ein Mod kann einen Großteil der Oberfläche von Claude Code umgestalten, aber nicht die Berechtigungsabfrage, sodass er nicht ändern kann, was eine Abfrage anzeigt. Ein Mod kann einen Tool-Aufruf dennoch genehmigen oder ablehnen, bevor die Abfrage erscheint, wie unter Wissen, was standardmäßig geschieht beschrieben.
• Vertrauensabfragen kommen zuerst. In einer interaktiven Sitzung in einem Verzeichnis, dem der Benutzer noch nicht vertraut hat, wird kein Mod geladen, bis er die Vertrauensabfrage beantwortet.
• --safe-mode schaltet installierte Mods aus, auch Ihre. Starten Sie eine Sitzung mit claude --safe-mode, um zu prüfen, ob ein Mod ein Problem verursacht hat.

Keine dieser Kontrollen führt einen Mod in einer Sandbox aus. Ein Mod, den Sie zulassen, läuft als der Benutzer, mit dessen Zugriff auf Dateien, Prozesse und das Netzwerk.

Entscheiden, ob Mods aktiviert bleiben sollen

Ein Mod kann mehr als die anderen Bestandteile eines Plugins, weil er innerhalb von Claude Code ausgeführt wird. Er sieht jeden Prompt und jeden Tool-Aufruf, kann diese ändern und kann einen Tool-Aufruf erlauben oder ablehnen, bevor eine Berechtigungsabfrage erscheint.

Was ein Benutzer als Mod laden kann, hängt von den Plugin-Steuerungen ab, die Sie bereits eingerichtet haben:

Plugins für Ihre Organisation verwalten listet die Wege auf, auf denen ein Plugin geladen wird, sowie die Einstellung, die jeden davon steuert.

Um die Mods in einem Marketplace zu prüfen, bevor Ihre Benutzer sie installieren, lesen Sie Prüfen, was ein Mod tun kann. Um von Benutzern installierte Mods fernzuhalten, bis Sie dies getan haben, lesen Sie Von Benutzern installierte Mods am Laden hindern.

Prüfen, was ein Mod tun kann

Sie können sehen, was ein Mod tun kann, ohne ihn auszuführen. Führen Sie in Ihrer Shell claude plugin validate für das Verzeichnis des Plugins aus:

claude plugin validate ./some-mod

Zwei Zeilen in der Ausgabe beschreiben den Code des Mods:

  ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}
  ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

Die Zeile hooks: listet die Events auf, die der Mod empfängt. Die Zeile calls: listet die Methoden der Mods-API auf, die sein Code aufruft. Über die Mods-API, im Code eines Mods als $ geschrieben, greift ein Mod auf Dateien, Prozesse und das Netzwerk zu. Claude Code verweigert das Laden eines Mods, der die Mods-API auf eine Weise verwendet, die dieser Befehl nicht auslesen kann.

Achten Sie in der Zeile calls: auf Folgendes:

In der Zeile hooks: bedeuten tool.call und prompt.submit, dass der Mod jeden Tool-Aufruf und jeden Prompt sieht und diese ändern kann. session.append bedeutet, dass der Mod jede Zeile der Konversation umschreiben kann, bevor sie gespeichert wird. ui.render{component=AskUserQuestion} bedeutet, dass der Mod den Dialog neu zeichnen kann, mit dem Claude dem Benutzer eine Frage stellt. tool.check bedeutet, dass der Mod einen Tool-Aufruf genehmigen oder ablehnen kann, bevor eine Berechtigungsabfrage erscheint. Wissen, was standardmäßig passiert listet auf, welche Ihrer Regeln und Hooks Vorrang vor seiner Antwort haben.

Festlegen, wie viel erlaubt ist

Mod-Richtlinien reichen von gar keinen installierten Mods bis zu jedem Mod, den ein Benutzer wählt, wobei Ihr eigener Mod die anderen prüft, und jede davon besteht aus einigen verwalteten Einstellungen. Suchen Sie die gewünschte Richtlinie in der ersten Spalte und setzen Sie, was die zweite Spalte nennt. Verwaltete Einstellungen bereitstellen beschreibt, wo verwaltete Einstellungen liegen.

Was jede Einstellung bewirkt:

• allowManagedModsOnly: eine Option des integrierten Wächters. Die eigenen Mods der Benutzer werden nicht geladen, und ihre Einstellungs-Hooks, Statuszeilen und /goal funktionieren weiterhin. Vom Benutzer installierte Mods am Laden hindern führt auf, was sie abdeckt.
• allowManagedHooksOnly: eine umfassendere Einstellung. Nur die Mods Ihrer Organisation und die in Claude Code integrierten Mods werden geladen. Ein Mod, den ein Benutzer selbst installiert hat, wird nicht geladen. Die Einstellung blockiert außerdem Hooks in den eigenen Einstellungsdateien der Benutzer. Lesen Sie Was unter allowManagedHooksOnly ausgeführt wird, bevor Sie sie setzen.
• disableAllHooks: die umfassendste Einstellung. In verwalteten Einstellungen stoppt sie die Mods in jedem installierten Plugin, einschließlich Ihrer eigenen, und schaltet jeden Hook in Einstellungsdateien aus, sodass ein PreToolUse-Hook in Ihren verwalteten Einstellungen nichts mehr blockiert. Benutzerdefinierte Statuszeilen und /goal funktionieren ebenfalls nicht mehr. Lesen Sie disableAllHooks, bevor Sie sie setzen.
• disableSideloadFlags: lehnt --plugin-dir und --plugin-url beim Start ab und verhindert, dass Mods geladen werden, die Claude während einer Sitzung schreibt. Die Einstellung lehnt außerdem --agents und --mcp-config ab. Lesen Sie disableSideloadFlags, bevor Sie sie setzen.

In Claude Code integrierte Mods, wie die Unterstützung für AGENTS.md, sind von diesen Einstellungen nicht betroffen. Jeder davon hat einen eigenen Schalter.

Ein Benutzer, dessen Mod nicht geladen wurde, findet den Grund in seinem Debug-Log. Ablehnungsmeldungen führt die Zeilen für allowManagedHooksOnly und disableAllHooks auf, und Meldungen des integrierten Wächters enthält die Zeile für allowManagedModsOnly.

Nur die Mods Ihrer Organisation zulassen

Um die Mods Ihrer Organisation auszuführen und die von Benutzern mitgebrachten zu blockieren, stellen Sie die Einstellungen aus der Zeile Nur die Mods Ihrer Organisation der Richtlinientabelle sowie disableSideloadFlags bereit. Mit dieser vollständigen managed-settings.json lehnt Claude Code die eigenen Mods der Benutzer ab, sodass keiner ihrer Hooks ausgeführt wird, und Ihr Richtlinien-Mod wird vor anderen Mods ausgeführt:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"],
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": { "allowManagedModsOnly": true }
    }
  },
  "disableSideloadFlags": true
}

Jede Gruppe von Schlüsseln erfüllt eine Aufgabe:

• extraKnownMarketplaces, enabledPlugins und prependPlugins: installieren Ihren Mod so, dass er als Ihrer gilt, und führen ihn zuerst aus, mit dem Wächter danach. Die Mods Ihrer Organisation installieren und die Reihenfolge festlegen beschreibt das Verzeichnis, auf das diese Schlüssel verweisen.
• pluginConfigs: setzt die Option allowManagedModsOnly des Wächters, sodass Claude Code die eigenen Mods der Benutzer ablehnt. Ihre Einstellungs-Hooks, Statuszeilen und /goal funktionieren weiterhin.
• disableSideloadFlags: siehe disableSideloadFlags für die Flags, die sie beim Start ablehnt

Um die Richtlinie auf einem Testrechner zu überprüfen, starten Sie in Ihrer Shell eine Sitzung mit claude --debug und lesen Sie das Debug-Log:

• Ihr Mod: Seine Zeile hooks module enthält tier prepend
• Ein vom Benutzer installierter Mod: Eine Zeile lautet refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly). Eine frühere Zeile besagt, dass das Hooks-Modul dieses Mods loaded wurde, suchen Sie also nach der Ablehnung.
• Ein Plugin-Verzeichnis: claude --plugin-dir ./any-mod wird mit einer Meldung beendet, die mit --plugin-dir is disabled by your organization's managed settings (disableSideloadFlags) beginnt

Um zusätzlich einzuschränken, welche Marketplaces Benutzer hinzufügen können, kombinieren Sie diese Datei mit Ihren Marketplace-Einschränkungen.

Ihre Plugin-Steuerungen auf Mods anwenden

Ein Mod ist ein Plugin, daher gelten die Möglichkeiten, mit denen Sie Plugins für Ihre Organisation verwalten, auch für ein Plugin, das einen Mod enthält:

• Sehen, welche Plugins in Ihrer gesamten Flotte geladen werden: Prüfen und überprüfen
• Entscheiden, wann ein von Ihnen geprüftes Plugin aktualisiert werden darf: Update-Richtlinie festlegen
• Einer Gruppe eine andere Richtlinie geben, etwa für ein Pilotprojekt: Planen, was verwaltete Einstellungen nicht durchsetzen können
• Prüfen, welche Apps und Sitzungsarten die Plugin-Schlüssel anwenden: Wann jede Oberfläche die Plugin-Schlüssel anwendet
• CI und Container einrichten: Container und CI vorbereiten
• Mods anbieten, die Ihre Benutzer installieren dürfen: Einen Marketplace hosten. Ein Mod, den Claude Code aus einer GitHub-, Git-, URL- oder npm-Quelle kopiert, gilt als Mod eines Benutzers, nicht als Mod Ihrer Organisation.

Optionen für den integrierten Wächter festlegen

Der integrierte Wächter akzeptiert Optionen. Setzen Sie diese in verwalteten Einstellungen unter pluginConfigs mit dem Schlüssel cc-plugin-sec-default@builtin, wie es das Beispiel in Vom Benutzer installierte Mods am Laden hindern tut.

Die Tabelle zeigt, was Ihre Benutzer erhalten, wenn die jeweilige Option nicht gesetzt ist und wenn sie auf true gesetzt ist:

Diese Regeln entscheiden, ob eine Option wirksam wird:

• Die ID hat hier eine Form: Claude Code liest die Optionen nur unter cc-plugin-sec-default@builtin. prependPlugins akzeptiert auch sec-default@builtin, pluginConfigs dagegen nicht.
• Nur verwaltete Einstellungen zählen: Derselbe Eintrag in einer Benutzer-, Projekt- oder lokalen Einstellungsdatei oder in einer mit --settings übergebenen Datei setzt weder eine Option noch lockert er eine
• Der Wächter muss geladen werden: Wenn Sie prependPlugins setzen, führen Sie den Wächter in der Liste auf. Wo der Wächter nicht geladen wird, gilt keine der beiden Optionen.
• Der Wächter schlägt sicher fehl: Wenn der Wächter die verwalteten Einstellungen nicht lesen kann, lehnt er beim Laden jeden Mod eines Benutzers ab. Wenn er die Deny-Regeln für einen Aufruf, den ein Mod eines Benutzers genehmigt hat, nicht prüfen kann, lehnt er den Aufruf ab.

Die Meldungen des integrierten Wächters sehen Ihre Benutzer, wenn eine der beiden Optionen greift.

Eigene Mods Ihrer Organisation ausführen

Sie können eigene Mods für alle Benutzer bereitstellen, festlegen, wo sie relativ zu den Mods der Benutzer ausgeführt werden, und einen Mod verwenden, um eine Richtlinie durchzusetzen.

Mods Ihrer Organisation installieren und die Reihenfolge festlegen

Die Mods Ihrer Organisation werden auch dort geladen, wo Mods von Benutzern nicht geladen werden, und können vor diesen ausgeführt werden. Daher muss Claude Code erkennen können, dass ein Mod von Ihnen stammt. Claude Code behandelt einen Mod nur dann als Mod Ihrer Organisation, wenn alle folgenden Bedingungen erfüllt sind:

• Das verwaltete enabledPlugins setzt das Plugin des Mods auf true
• Die verwalteten Einstellungen benennen den Marketplace des Plugins als Verzeichnis auf dem Rechner des Benutzers, und zwar über einen absoluten Pfad. Ein Eintrag in extraKnownMarketplaces leistet das und registriert den Marketplace zusätzlich für den Benutzer.
• Der Marketplace führt das Plugin über einen relativen Pfad auf, sodass Claude Code es direkt an Ort und Stelle lädt, und zwar aus diesem Verzeichnis

Um diese Bedingungen zu erfüllen, lassen Sie das Marketplace-Verzeichnis von Ihrer Geräteverwaltung auf jedem Rechner an denselben Pfad kopieren. Sorgen Sie dafür, dass das Verzeichnis und jedes übergeordnete Verzeichnis nur von einem Administrator beschreibbar sind, so wie die Datei mit den verwalteten Einstellungen. Wer dort schreiben kann, kann Ihren Mod umschreiben. Verwaltete Einstellungen, die Sie über die Admin-Konsole von claude.ai bereitstellen, können die Schlüssel enthalten, aber sie können das Verzeichnis nicht auf einem Rechner ablegen.

Das Verzeichnis enthält das Manifest des Marketplace und das Plugin:

/opt/acme/claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── acme-guard/
        ├── .claude-plugin/
        │   └── plugin.json
        └── hooks/
            ├── hooks.json
            └── register.js

Das Manifest führt das Plugin über seinen Pfad relativ zu diesem Verzeichnis auf:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "acme-guard", "source": "./plugins/acme-guard", "description": "Acme policy mod" }
  ]
}

Ein Plugin, das Claude Code in seinen Cache kopiert, gilt als Plugin eines Benutzers, auch wenn das verwaltete enabledPlugins es aktiviert. Das betrifft jedes Plugin aus einer GitHub-, Git-, URL- oder npm-Quelle. Sein Mod wird zusammen mit den Mods der Benutzer ausgeführt, prependPlugins und appendPlugins überspringen ihn, und er wird unter allowManagedModsOnly oder allowManagedHooksOnly nicht geladen. Das Debug-Log des Benutzers enthält eine Zeile, die mit der ID des Plugins und is enabled by managed settings, but beginnt.

Claude Code löst jedes Mal ein Ereignis aus, wenn es im Begriff ist, eine Aktion auszuführen, etwa ein Tool auszuführen, und übergibt es nacheinander an jeden Mod. Ein Mod, der als Ihrer gilt, wird vor den Mods der Benutzer ausgeführt, auch wenn Sie ihn nirgends aufführen. Um seine Position festzulegen, führen Sie seine ID in einer von zwei Einstellungen auf. Die ID besteht aus dem Namen des Plugins, @ und dem Namen des Marketplace, etwa acme-guard@acme-tools.

• prependPlugins: Ihr Mod sieht jedes Ereignis vor jedem Mod eines Benutzers und jedes Ergebnis danach. Er kann das Ereignis ändern, es ablehnen oder die Mods der Benutzer überspringen.
• appendPlugins: Ihr Mod wird nach jedem Mod eines Benutzers ausgeführt und sieht daher nur die Ereignisse, die diese Mods weitergeben, und zwar in der Form, in der sie sie weitergeben

Dieses Beispiel deklariert den Marketplace acme-tools unter /opt/acme/claude-plugins, aktiviert daraus acme-guard und führt diesen Mod zuerst aus, gefolgt vom integrierten Wächter:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]
}

Jeder Schlüssel erfüllt eine Aufgabe:

• extraKnownMarketplaces: benennt das Verzeichnis, das den Marketplace acme-tools enthält. path ist der absolute Pfad des Verzeichnisses, das .claude-plugin/marketplace.json enthält.
• enabledPlugins: aktiviert acme-guard für jeden Benutzer, der diese verwalteten Einstellungen erhält
• prependPlugins: stellt acme-guard an die erste und den integrierten Wächter an die zweite Stelle, beide vor jedem Mod, den ein Benutzer installiert. Claude Code hält sich an die Reihenfolge, die Sie angeben.

Wie Sie prüfen, ob der Rechner eines Benutzers die Einstellungen erhalten hat, erfahren Sie unter Prüfen, ob eine Richtlinie in Kraft ist.

Um zu prüfen, wo der Mod ausgeführt wird, starten Sie auf diesem Rechner eine Sitzung mit claude --debug und durchsuchen Sie das Debug-Log nach der ID des Mods:

• hooks module acme-guard@acme-tools loaded, mit tier prepend: Der Mod gilt als Mod Ihrer Organisation und wird zuerst ausgeführt
• Dieselbe Zeile mit tier user: Claude Code behandelt ihn als Mod eines Benutzers. Eine zweite Zeile, prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped, besagt, dass die Liste ihn übersprungen hat.

Diese Regeln bestimmen, welche IDs in den beiden Listen wirksam werden:

• Die Liste ersetzt den Standard: Wenn Sie prependPlugins in verwalteten Einstellungen setzen, führen Sie darin sec-default@builtin auf, um den integrierten Wächter beizubehalten. Der Wächter ist integriert und benötigt keinen Eintrag in enabledPlugins.
• Ihre eigenen IDs müssen als Ihre gelten: In verwalteten Einstellungen überspringt Claude Code eine ID, deren Plugin die Bedingungen für einen Mod einer Organisation nicht erfüllt
• Repositorys können sie nicht setzen: Claude Code liest beide Einstellungen aus den verwalteten Einstellungen und niemals aus der Einstellungsdatei eines Repositorys. Ein Benutzer kann sie in ~/.claude/settings.json setzen, um seine eigenen Mods zu ordnen, allerdings nur auf einem Rechner ohne verwaltete Einstellungen und nur, wenn er nicht mit einem Team- oder Enterprise-Plan angemeldet ist. In allen anderen Fällen ignoriert Claude Code beide Schlüssel in den Benutzereinstellungen. Eine Liste dort fügt den integrierten Wächter weder hinzu noch entfernt sie ihn.

Eine Richtlinie mit einem eigenen Mod durchsetzen

Um alle Mods von Benutzern fernzuhalten, benötigen Sie keinen eigenen Mod. Setzen Sie allowManagedModsOnly. Schreiben Sie einen Richtlinien-Mod, wenn Sie einige Mods von Benutzern zulassen und andere ablehnen möchten oder wenn Sie protokollieren möchten, was Mods tun.

Jedes Mal, wenn ein anderer Mod geladen werden soll, erhält Ihr Mod die Liste, die claude plugin validate ausgibt, in einem Ereignis namens plugin.register. Ein Mod in prependPlugins kann diese Liste lesen und den Mod ablehnen. Er kann außerdem jeden Aufruf der Mods-API über ihren Namen behandeln, um diesen Aufruf für jeden anderen Mod zu protokollieren oder abzulehnen. Der Name ist die Methode ohne $., sodass ein Hook auf fs.write jeden Aufruf von $.fs.write sieht.

Dieser Richtlinien-Mod lehnt jeden Mod eines Benutzers ab, dessen eigener Code $.process.run oder $.process.spawn aufruft. Außerdem führt er ein Audit-Log, indem er jeden Tool-Aufruf und jede Datei, die ein Mod schreibt, in das Debug-Log schreibt. Da er zuerst ausgeführt wird, hält das Log fest, was angefordert wurde, bevor ein Mod eines Benutzers es ändert. Speichern Sie ihn als acme-guard/hooks/register.js:

// The methods no user's mod may call, each spelled namespace.method
const BLOCKED_CALLS = ['process.run', 'process.spawn']

export function register(on) {
  // Runs each time another mod is about to load
  on('plugin.register', async ($, e, next) => {
    // Keep the calls in that mod's code that are on the blocked list
    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
    if (e.tier === 'user' && blocked.length > 0) {
      // Returning refuse keeps the mod from loading, and the text is the reason
      return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
    }
    // Let every other mod load
    return next(e)
  })

  // Record each tool call, then let it go ahead unchanged
  on('tool.call', async ($, e, next) => {
    $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })
    return next(e)
  })

  // Record which mod wrote a file, then the path, quoted because the mod chose it
  on('fs.write', async ($, e, next) => {
    $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })
    return next(e)
  })
}

Die Datei registriert drei Hooks:

• plugin.register: entscheidet, ob ein anderer Mod geladen wird. Er lehnt einen Mod eines Benutzers ab, der eine blockierte Methode aufruft, und lässt jeden anderen Mod durch.
• tool.call: schreibt für jeden Tool-Aufruf eine Zeile wie audit tool.call Bash in das Debug-Log und ändert nichts
• fs.write: schreibt für jeden Aufruf von $.fs.write, den ein anderer Mod ausführt, eine Zeile wie audit fs.write by reader "/tmp/notes.md" und ändert nichts. Der Name des Mods steht zuerst und der Pfad in Anführungszeichen, sodass ein Pfad, den ein Mod wählt, nicht als ein anderes Feld der Zeile durchgehen kann.

Der Hook plugin.register liest zwei Felder des Ereignisses:

• e.tier: wo der Mod ausgeführt würde, einer der Werte prepend, user, append oder builtin. Jeder Mod, den eine Person installiert, ist user.
• e.uses.calls: die Methoden der Mods-API, die der Mod aufruft, jeweils als namespace.method geschrieben, etwa process.run, ohne das $., das claude plugin validate ausgibt

Wenn ein Benutzer einen Mod installiert, der $.process.run aufruft, wird der Mod nicht geladen, und sein Debug-Log enthält eine Zeile, die mit refused by acme-guard: und Ihrer Begründung endet. Die Ablehnung erscheint außerdem im Transkript einer Sitzung, die ein Plugin-Verzeichnis per Hot-Reload neu lädt. Um einen Aufruf zu blockieren, ohne den gesamten Mod abzulehnen, geben Sie { deny: 'your reason' } aus einem Hook auf den Namen dieses Aufrufs zurück.

Um die Audit-Zeilen an ein anderes Ziel als das Debug-Log zu senden, rufen Sie $.http.fetch aus denselben Hooks auf.

Eine Sitzung kann ohne Ihren Mod laufen. Wenn der Worker-Thread, der installierte Mods ausführt, dreimal abstürzt, entlädt Claude Code jeden Mod, der nicht integriert ist, einschließlich Ihres, bis der Benutzer /reload-plugins ausführt oder eine neue Sitzung startet. Und ein Benutzer, der Claude Code mit --safe-mode startet, arbeitet ohne installierte Mods, Ihren eingeschlossen.

Einen Mod erstellen behandelt die Dateien, die ein Mod benötigt. Einen Richtlinien-Mod testen enthält eine Testdatei für diesen Richtlinien-Mod.

Mods ablehnen, wenn Ihre Prüfung fehlschlägt

Wenn Ihr Hook plugin.register eine Ausnahme auslöst oder sein Zeitlimit überschreitet, überspringt Claude Code den Hook. Die Prüfung schlägt also offen fehl, und der Mod, der geprüft wurde, wird geladen. Damit die Prüfung geschlossen fehlschlägt und Mods von Benutzern abgelehnt werden, verschieben Sie die Prüfung in eine benannte Funktion und fügen Sie einen .catch-Handler hinzu, der die Ablehnung zurückgibt. Diese Version der Datei zeigt nur den Hook plugin.register. Behalten Sie daher die beiden Audit-Hooks aus der ersten Version in register bei:

const BLOCKED_CALLS = ['process.run', 'process.spawn']

// The same check as before, moved into a function of its own
async function checkMod($, e, next) {
  const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
  if (e.tier === 'user' && blocked.length > 0) {
    return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
  }
  return next(e)
}

export function register(on) {
  // The handler runs only when checkMod throws or exceeds its time limit
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    // Let your organization's mods and built-in mods load
    if (e.tier !== 'user') return next(e)
    // Refuse the user's mod that couldn't be checked
    return { refuse: 'Acme policy check failed, so this mod was not loaded' }
  })
}

Mit dem Handler wird ein Mod, der gerade geprüft wurde, als die Prüfung eine Ausnahme auslöste oder das Zeitlimit überschritt, nicht geladen, und die Ablehnungszeile enthält die zweite Begründung, wie in refused by acme-guard: Acme policy check failed, so this mod was not loaded. Der Handler übergibt jeden Mod außerhalb der Stufe user an next(e), sodass eine fehlgeschlagene Prüfung die Mods, die Ihre Organisation aufführt, nicht aufhält. Einen fehlschlagenden Hook behandeln behandelt .catch für andere Ereignisse.

Nächste Schritte

• Plugin-Sicherheit: was jedes Plugin auf dem Rechner eines Benutzers tun kann und wie Sie ein Plugin prüfen, bevor es installiert wird
• Mods-Übersicht: was ein Mod ist und wie er sich im Vergleich zu Hooks, Skills und MCP-Servern verhält
• Die Reihenfolge, in der Mods ausgeführt werden: wie prependPlugins und appendPlugins mit den Mods der Benutzer zusammenspielen
• Einstellungen und Umgebungsvariablen: alle auf dieser Seite genannten Einstellungen in einer Tabelle