SpyBara
Go Premium

plugins/mods/admin.md 2026-10-01 23:59 UTC to 2026-10-02 10:59 UTC

This page contains 101 additions and 50 deletions.

2026
Thu 1 23:59 Fri 2 11:59

Mods für Ihre Organisation verwalten

Kontrollieren Sie Claude Code Mods mit verwalteten Einstellungen: Deaktivieren Sie von Benutzern installierte Mods, erlauben Sie nur Ihre eigenen, überprüfen Sie, was ein Mod tun kann, und erzwingen Sie eine Richtlinie mit Ihrem eigenen Mod.

Ein Mod ist ein Plugin, das Code innerhalb von Claude Code mit den Berechtigungen des Benutzers ausführt, der es installiert hat. Mods sind nicht isoliert. Durch verwaltete Einstellungen entscheiden Sie, ob Mods auf den Maschinen Ihrer Benutzer ausgeführt werden, welche und in welcher Reihenfolge. Sie können auch einen Mod Ihrer eigenen installieren, der überwacht oder ablehnt, was andere Mods tun.

Diese Seite ist für die Person, die verwaltete Einstellungen für Claude Code bereitstellt, ob als Datei, über MDM oder über die claude.ai Admin-Konsole. Mods sind standardmäßig in Claude Code v2.1.287 und später aktiviert. Beginnen Sie mit dem Abschnitt, der zu dem passt, was Sie tun möchten:

Verhindern Sie, dass von Benutzern installierte Mods geladen werden

Um zu verhindern, dass jeder Mod, den Ihre Benutzer mitbringen, geladen wird, setzen Sie die Option allowManagedModsOnly auf dem integrierten Guard, einem Policy-Mod, den Claude Code vor jedem Mod lädt, den ein Benutzer installiert. Die Option befindet sich in verwalteten Einstellungen unter pluginConfigs, mit dem Schlüssel cc-plugin-sec-default@builtin:

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

Mit der in verwalteten Einstellungen gesetzten Option:

  • Kein Mod, den ein Benutzer mitbringt, wird geladen: Das umfasst einen Mod in einem Plugin, das der Benutzer installiert hat, einen Mod, der mit --plugin-dir geladen wird, 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 zählt, wird nicht überprüft. Jeder andere Mod zählt als Mod eines Benutzers und wird nicht geladen. Das umfasst einen Mod in einem Plugin, das Sie von einem GitHub oder anderen Remote-Marketplace aktivieren, und einen, den Ihre Organisation für ihre Mitglieder auf claude.ai aktiviert. Wenn keiner als Ihrer zählt, wird kein installierter Mod geladen.
  • Benutzer können es nicht rückgängig machen: Der Guard liest die Option nur aus verwalteten Einstellungen, daher ändert derselbe Eintrag in einer Benutzer-, Projekt- oder lokalen Einstellungsdatei oder in einer Datei, die mit --settings übergeben wird, nichts
  • Eine Datei oder MDM-Richtlinie deckt jeden Provider ab: Wenn Sie die Option als Datei oder über MDM bereitstellen, funktioniert sie auf Amazon Bedrock, Google Cloud's Agent Platform und Microsoft Foundry auf die gleiche Weise. Für die Bereitstellung über die claude.ai Admin-Konsole siehe Plattformverfügbarkeit
  • Die anderen Anpassungen der Benutzer funktionieren weiterhin: Ihre Hooks in Einstellungsdateien, Statuszeilen und /goal sind nicht betroffen
  • Integrierte Mods funktionieren weiterhin: Mods, die in Claude Code integriert sind, wie z. B. AGENTS.md Unterstützung, haben jeweils ihren eigenen Schalter

Um die Option auf der Maschine eines Benutzers zu bestätigen, starten Sie Claude Code dort mit --plugin-dir und dem Pfad eines Verzeichnisses, das einen Mod enthält, z. B. claude --plugin-dir ./first-mod. Die Hooks des Mods werden nicht ausgeführt, und das Transkript und das Debug-Protokoll enthalten die Nachricht des Guards, die den Mod und allowManagedModsOnly benennt. Wenn der Mod geladen wird, siehe Überprüfen Sie, dass eine Richtlinie in Kraft ist und die Regeln, die entscheiden, ob eine Option wirksam wird.

Wenn Sie CLAUDE_CODE_ENABLE_FUNCTION_HOOKS während des Early Access auf 0 gesetzt haben, ersetzen Sie es durch diese Option. Claude Code v2.1.287 und später ignoriert die Variable bei jedem Wert, daher lässt ein 0 dort Mods aktiviert.

Wissen Sie, was standardmäßig passiert

Ohne Ihre eigenen Mod-Einstellungen erhalten Ihre Benutzer folgendes:

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

  • Ein integrierter Guard wird zuerst ausgeführt. 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-Protokoll listen ihn als cc-plugin-sec-default auf. Der Guard wird geladen, wenn einer dieser Punkte zutrifft:

    • Die Maschine hat verwaltete Einstellungen
    • Der Benutzer ist bei Claude Code mit einem Team- oder Enterprise-Plan angemeldet

    Ein Benutzer, der sich mit einem API-Schlüssel authentifiziert oder über Amazon Bedrock, Google Cloud's Agent Platform oder Microsoft Foundry, erhält den Guard nur auf einer Maschine, die verwaltete Einstellungen hat.

  • Der Guard schützt, was Sie verwalten. Ein Mod eines Benutzers kann nicht ändern, was Ihre verwalteten Hooks erhalten oder entscheiden, die Systemaufforderung, Ihre verwaltete CLAUDE.md und andere verwaltete Anweisungen, was jeder Mod als Einstellungen liest, oder die Tools und Beschreibungen Ihrer verwalteten MCP-Server.

  • Alles andere ist erlaubt. Der Guard fügt keine anderen Einschränkungen hinzu. Ein Mod eines Benutzers kann immer noch Dateien lesen und schreiben, Prozesse starten, Netzwerkanfragen stellen, Tool-Aufrufe und Aufforderungen umschreiben, einen Tool-Aufruf ablehnen, einen genehmigen, der sonst eine Aufforderung auslösen würde, und in der Benutzeroberfläche zeichnen, alles mit den Berechtigungen dieses Benutzers.

  • Deny-Regeln und Ihre verwalteten Hooks haben Vorrang. Wo der Guard geladen wird, kann ein Mod eines Benutzers einen Aufruf nicht genehmigen, den eine deny Regel ablehnt, unabhängig davon, welche Einstellungsdatei die Regel enthält. Ein Block von einem PreToolUse Hook in verwalteten Einstellungen ist auch endgültig. Beide gelten für Claude's Tool-Aufrufe. Keiner gilt für die eigenen $.fs und $.process Aufrufe eines Mods: Mit Read(.env) verweigert, kann ein Mod diese Datei immer noch mit $.fs.read lesen oder ein Programm starten, das dies tut. Um diese Aufrufe zu begrenzen, verhindern Sie, dass der Mod geladen wird, oder behandeln Sie den Aufruf in einem Policy-Mod.

  • Andere Berechtigungsprüfungen können überschrieben werden. Ein Mod eines Benutzers, der Tool-Aufrufe genehmigt, kann einen Aufruf genehmigen, den eine ask Regel auffordern würde, oder den ein PreToolUse Hook außerhalb verwalteter Einstellungen blockiert hat. Im Auto-Modus wird ein Aufruf, den der Mod genehmigt, ohne eine Klassifiziererprüfung ausgeführt.

Der Quellcode des Guards ist öffentlich im mods/sec-default Verzeichnis des Claude Code Repositorys.

Wissen Sie, welche Kontrollen noch gelten

Mods ersetzen nicht die Kontrollen, die Sie bereits haben:

  • Einstellungs-Hooks funktionieren weiterhin. Command-, HTTP-, Prompt- und Agent-Hooks in Einstellungsdateien und in hooks/hooks.json von Plugins werden wie zuvor ausgeführt, zusammen mit Mods. Nichts daran ist veraltet.
  • Deny-Regeln haben Vorrang, wo der Guard geladen wird. Ein Mod eines Benutzers kann einen Aufruf nicht genehmigen, den eine deny Regel ablehnt, es sei denn, Sie setzen allowModsToOverrideDenyRules.
  • Verwaltete Hooks werden zuerst ausgeführt. Ein PreToolUse Hook in verwalteten Einstellungen wird ausgeführt, bevor ein Mod den Tool-Aufruf sieht, und sein Block ist endgültig. Wenn ein Mod dann den Aufruf umschreibt, werden Ihre verwalteten Hooks erneut auf dem umgeschriebenen Aufruf ausgeführt, daher gilt ein Block immer noch. PreToolUse Hooks aus anderen Einstellungsdateien und von Plugins werden nach dem letzten Mod ausgeführt, daher verhindert ein Mod, der sein eigenes Ergebnis anstelle der Ausführung des Tools zurückgibt, dass diese ausgeführt werden. Siehe Die Reihenfolge, in der Mods ausgeführt werden.
  • Netzwerkrichtlinie deckt $.http.fetch ab. Wenn Ihre Organisation Web-Abrufe deaktiviert oder nicht wesentlicher Netzwerkverkehr für die Sitzung deaktiviert ist, lehnt Claude Code eine Netzwerkanfrage ab, die ein Mod mit $.http.fetch macht. Die Richtlinie deckt kein Programm ab, das der Mod mit $.process.run startet. Dieses Programm erreicht das Netzwerk mit dem eigenen Zugriff des Benutzers.
  • Plugin-Kontrollen decken Mods ab. Ein Mod ist ein Plugin, daher entscheiden die Einstellungen, die einschränken, was Benutzer installieren können, wie z. B. strictKnownMarketplaces, ob er überhaupt installiert werden kann.
  • Mods können die Berechtigungsaufforderung nicht ändern. Ein Mod kann viel von Claude Code's Benutzeroberfläche umgestalten, aber nicht die Berechtigungsaufforderung, daher kann er nicht ändern, was eine Aufforderung zeigt. Ein Mod kann immer noch einen Tool-Aufruf genehmigen oder ablehnen, bevor die Aufforderung erscheint, wie Wissen Sie, was standardmäßig passiert beschreibt.
  • Vertrauensaufforderungen kommen zuerst. In einer interaktiven Sitzung in einem Verzeichnis, das der Benutzer noch nicht vertraut hat, wird kein Mod geladen, bis er die Vertrauensaufforderung beantwortet.
  • --safe-mode schaltet installierte Mods aus, einschließlich Ihrer. Starten Sie eine Sitzung mit claude --safe-mode, um zu überprüfen, ob ein Mod ein Problem verursacht hat.

Keine dieser Kontrollen isoliert einen Mod. Ein Mod, den Sie erlauben, wird als Benutzer ausgeführt, mit dem Zugriff des Benutzers auf Dateien, Prozesse und das Netzwerk.

Entscheiden Sie, ob Sie Mods aktiviert lassen

Ein Mod kann mehr tun als die anderen Teile eines Plugins, da er innerhalb von Claude Code ausgeführt wird. Er sieht jede Aufforderung und jeden Tool-Aufruf, kann sie ändern und kann einen Tool-Aufruf genehmigen oder ablehnen, bevor eine Berechtigungsaufforderung erscheint.

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

Ihre heutigen Plugin-Kontrollen Was ein Benutzer als Mod laden kann
Keine Ein Mod von jedem Marketplace, aus jedem Verzeichnis mit --plugin-dir oder den Claude während einer Sitzung schreibt
Ein Marketplace-Allowlist Ein Mod von den Marketplaces, die Sie erlauben, oder aus jedem Verzeichnis mit --plugin-dir. Ein Mod, den Claude während einer Sitzung schreibt, wird nur geladen, wenn die Allowlist skills-dir enthält.
Ein Marketplace-Allowlist und disableSideloadFlags Ein Mod von den Marketplaces, die Sie erlauben

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

Um die Mods in einem Marketplace zu überprüfen, bevor Ihre Benutzer sie installieren, siehe Überprüfen Sie, was ein Mod tun kann. Um Mods von Benutzern auszuschließen, bis Sie dies getan haben, siehe Verhindern Sie, dass von Benutzern installierte Mods geladen werden.

Überprüfen Sie, 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 im 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 hooks: Zeile listet die Ereignisse auf, die der Mod empfängt. Die calls: Zeile listet die Mods API-Methoden auf, die sein Code aufruft. Die Mods API, geschrieben als $ im Code eines Mods, ist, wie ein Mod Dateien, Prozesse und das Netzwerk erreicht. Claude Code weigert sich, einen Mod zu laden, der die Mods API auf eine Weise verwendet, die dieser Befehl nicht lesen kann.

Schauen Sie sich die calls: Zeile auf diese an:

Aufruf Was es bedeutet
$.fs.read, $.fs.write Liest oder schreibt Dateien überall, wo der Benutzer kann
$.process.run, $.process.spawn Startet Programme als Benutzer
$.http.fetch Macht Netzwerkanfragen
$.env.get, $.settings.read Liest Umgebungsvariablen und Einstellungen, die API-Schlüssel enthalten können. Eine env reads: Zeile in der Ausgabe benennt jede Variable.
$.env.set Setzt eine Umgebungsvariable für Claude Code und für jeden Befehl und MCP-Server, den es danach startet, was ändern kann, was diese Programme ausführen. Eine env writes: Zeile benennt jede Variable.
$.mcp.call Ruft ein Tool auf einem verbundenen MCP-Server auf, unter den Berechtigungsregeln der Sitzung
$.model.complete Verwendet den Plan oder API-Schlüssel des Benutzers für Modellaufrufe
$.prompt.submit Sendet eine Aufforderung und kann sie als die eigenen Worte des Benutzers senden
$.session.send Sendet eine Nachricht, die eine andere Sitzung oder ein Subagent von Claude liest

In der hooks: Zeile bedeuten tool.call und prompt.submit, dass der Mod jeden Tool-Aufruf und jede Aufforderung sieht und sie ä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 umzeichnen kann, den Claude verwendet, um den Benutzer eine Frage zu stellen. tool.check bedeutet, dass der Mod einen Tool-Aufruf genehmigen oder ablehnen kann, bevor eine Berechtigungsaufforderung erscheint. Wissen Sie, was standardmäßig passiert listet auf, welche Ihrer Regeln und Hooks Vorrang vor seiner Antwort haben.

Wählen Sie, wie viel Sie erlauben

Mod-Richtlinien reichen von keinen installierten Mods bis zu jedem Mod, den ein Benutzer wählt, mit Ihrem eigenen Mod, der die anderen überprüft, und jede ist ein paar verwaltete Einstellungen. Finden Sie die Richtlinie, die Sie möchten, in der ersten Spalte und setzen Sie, was die zweite Spalte benennt. Verwaltete Einstellungen bereitstellen behandelt, wo verwaltete Einstellungen leben.

Was Sie möchten Einstellungen
Keine installierten Mods, mit Hooks unverändert Setzen Sie allowManagedModsOnly und stellen Sie keine Mods Ihrer eigenen bereit
Keine installierten Mods und überhaupt keine Hooks, einschließlich Ihrer verwalteten Hooks Setzen Sie disableAllHooks auf true
Nur die Mods Ihrer Organisation Setzen Sie die Option allowManagedModsOnly des Guards und installieren Sie Ihre Mods, damit sie als Ihre zählen
Jeder Mod von Marketplaces, die Sie genehmigen Behalten Sie Ihre Marketplace-Einschränkungen und setzen Sie disableSideloadFlags auf true
Jeder Mod, mit Ihrem eigenen Mod, der die anderen überprüft Installieren Sie Ihren Mod und listen Sie ihn mit sec-default@builtin in prependPlugins auf

Was jede Einstellung tut:

  • allowManagedModsOnly: eine Option auf dem integrierten Guard. Mods von Benutzern werden nicht geladen, und ihre Einstellungs-Hooks, Statuszeilen und /goal funktionieren weiterhin. Verhindern Sie, dass von Benutzern installierte Mods geladen werden listet auf, was es abdeckt.
  • allowManagedHooksOnly: eine breitere 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 auch Hooks in den eigenen Einstellungsdateien von Benutzern. Lesen Sie Was unter allowManagedHooksOnly ausgeführt wird, bevor Sie es setzen.
  • disableAllHooks: die breiteste Einstellung. In verwalteten Einstellungen stoppt es die Mods in jedem installierten Plugin, einschließlich Ihrer, und schaltet jeden Hook in Einstellungsdateien aus, daher blockiert ein PreToolUse Hook in Ihren verwalteten Einstellungen nichts mehr. Benutzerdefinierte Statuszeilen und /goal funktionieren auch nicht mehr. Lesen Sie disableAllHooks, bevor Sie es setzen.
  • disableSideloadFlags: lehnt --plugin-dir und --plugin-url beim Start ab und verhindert, dass Mods, die Claude während einer Sitzung schreibt, geladen werden. Die Einstellung lehnt auch --agents und --mcp-config ab. Lesen Sie disableSideloadFlags, bevor Sie es setzen.

Mods, die in Claude Code integriert sind, wie z. B. AGENTS.md Unterstützung, sind von diesen Einstellungen nicht betroffen. Jeder hat seinen eigenen Schalter.

Ein Benutzer, dessen Mod nicht geladen wurde, findet den Grund in seinem Debug-Protokoll. Verweigerungsmeldungen listet die Zeilen für allowManagedHooksOnly und disableAllHooks auf, und Meldungen vom integrierten Guard hat die Zeile für allowManagedModsOnly.

Nur die Mods Ihrer Organisation zulassen

Um die Mods Ihrer Organisation auszuführen und die Mods zu blockieren, die Benutzer mitbringen, 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 von Benutzern 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 zählt, und führen ihn zuerst aus, mit dem Guard danach. Installieren Sie die Mods Ihrer Organisation und legen Sie die Reihenfolge fest behandelt das Verzeichnis, auf das diese Schlüssel verweisen.
  • pluginConfigs: setzt die Option allowManagedModsOnly des Guards, sodass Claude Code die eigenen Mods von Benutzern ablehnt. Ihre Einstellungs-Hooks, Statuszeilen und /goal funktionieren weiterhin.
  • disableSideloadFlags: siehe disableSideloadFlags für die Flags, die es beim Start ablehnt

Um die Richtlinie auf einem Testrechner zu bestätigen, 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 Mod, den der Benutzer installiert hat: 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 ist, 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 außerdem einzuschränken, welche Marketplaces Benutzer hinzufügen können, kombinieren Sie diese Datei mit Ihren Marketplace-Einschränkungen.

Wenden Sie Ihre Plugin-Steuerungen auf Mods an

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:

Setzen Sie Optionen auf dem integrierten Guard

Der integrierte Guard nimmt Optionen. Setzen Sie sie in verwalteten Einstellungen unter pluginConfigs, mit dem Schlüssel cc-plugin-sec-default@builtin, wie das Beispiel in Verhindern Sie, dass von Benutzern installierte Mods geladen werden tut.

Die Tabelle gibt an, was Ihre Benutzer mit jeder Option nicht gesetzt und mit ihr auf true gesetzt erhalten:

Option Nicht gesetzt true
allowManagedModsOnly Mods von Benutzern werden geladen Nur die Mods Ihrer Organisation und in Claude Code integrierte Mods werden geladen. Claude Code lehnt jeden anderen Mod ab, einschließlich eines, den ein Benutzer installiert hat oder mit --plugin-dir benannt hat.
allowModsToOverrideDenyRules Deny-Regeln haben Vorrang vor Mods von Benutzern Ein Mod eines Benutzers, der Tool-Aufrufe genehmigt, kann einen Aufruf genehmigen, den eine deny Regel ablehnt

Diese Regeln entscheiden, ob eine Option wirksam wird:

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

Die Meldungen vom integrierten Guard sind das, was Ihre Benutzer sehen, wenn eine Option gilt.

Führen Sie die Mods Ihrer Organisation aus

Sie können eigene Mods für jeden Benutzer bereitstellen, wählen, wo sie relativ zu Mods von Benutzern ausgeführt werden, und einen davon verwenden, um eine Richtlinie durchzusetzen.

Installieren Sie die Mods Ihrer Organisation und legen Sie die Reihenfolge fest

Die Mods Ihrer Organisation werden geladen, wo Mods von Benutzern nicht geladen werden, und können vor ihnen ausgeführt werden. Daher muss Claude Code erkennen können, dass ein Mod von Ihnen stammt. Es behandelt einen Mod nur dann als Mod Ihrer Organisation, wenn alle diese Punkte zutreffen:

  • Verwaltete enabledPlugins setzt das Plugin des Mods auf true
  • Verwaltete Einstellungen benennen den Marketplace des Plugins als Verzeichnis auf dem Rechner des Benutzers, per absolutem Pfad. Ein extraKnownMarketplaces-Eintrag leistet das und registriert den Marketplace zudem für den Benutzer.
  • Der Marketplace listet das Plugin über einen relativen Pfad auf, sodass Claude Code es an Ort und Stelle lädt, und zwar aus diesem Verzeichnis

Um diese Bedingungen zu erfüllen, lassen Sie Ihre Geräteverwaltung das Marketplace-Verzeichnis auf jedem Rechner an denselben Pfad kopieren. Machen Sie das Verzeichnis und jedes übergeordnete Verzeichnis nur für einen Administrator beschreibbar, wie die Datei mit den verwalteten Einstellungen. Jeder, der dort schreiben kann, kann Ihren Mod umschreiben. Verwaltete Einstellungen, die Sie über die claude.ai-Admin-Konsole 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 listet 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, zählt als Plugin eines Benutzers, auch wenn verwaltete enabledPlugins es aktiviert. Das betrifft jedes Plugin aus einer GitHub-, Git-, URL- oder npm-Quelle. Sein Mod wird unter den Mods von Benutzern 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, etwas zu tun, etwa ein Tool auszuführen, und übergibt es der Reihe nach an jeden Mod. Ein Mod, der als Ihrer zählt, wird vor Mods von Benutzern ausgeführt, auch wenn Sie ihn nirgendwo auflisten. Um seine Position festzulegen, listen Sie seine ID in einer von zwei Einstellungen auf. Die ID besteht aus dem Namen des Plugins, @ und dem Namen des Marketplace, z. B. acme-guard@acme-tools.

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

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

{
  "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: schaltet acme-guard für jeden Benutzer ein, der diese verwalteten Einstellungen erhält
  • prependPlugins: setzt acme-guard an die erste und den integrierten Guard an die zweite Stelle, beide vor jedem Mod, den ein Benutzer installiert. Claude Code folgt der Reihenfolge, in der Sie sie auflisten.

Um zu bestätigen, dass der Rechner eines Benutzers die Einstellungen erhalten hat, siehe Überprüfen, ob eine Richtlinie in Kraft ist.

Um zu bestätigen, 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 zählt 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 entscheiden, welche IDs in den beiden Listen wirksam werden:

  • Die Liste ersetzt den Standard: Wenn Sie prependPlugins in verwalteten Einstellungen setzen, nennen Sie darin sec-default@builtin, um den integrierten Guard zu behalten. Der Guard ist integriert und benötigt keinen enabledPlugins-Eintrag.
  • Ihre eigenen IDs müssen als Ihre zählen: 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 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. Überall sonst ignoriert Claude Code beide Schlüssel in Benutzereinstellungen. Eine Liste dort fügt den integrierten Guard weder hinzu noch entfernt sie ihn.

Erzwingen Sie eine Richtlinie mit einem eigenen Mod

Um jeden Mod eines Benutzers auszuschließen, 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 anhand seines Namens behandeln, um diesen Aufruf für jeden anderen Mod zu protokollieren oder abzulehnen. Der Name ist die Methode ohne $., daher sieht ein Hook auf fs.write jeden $.fs.write-Aufruf.

Dieser Richtlinien-Mod lehnt jeden Mod eines Benutzers ab, dessen eigener Code $.process.run oder $.process.spawn aufruft. Er führt außerdem ein Audit-Log und schreibt jeden Tool-Aufruf und jede Datei, die ein Mod schreibt, in das Debug-Log. 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 gibt jeden anderen Mod weiter.
  • 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 $.fs.write-Aufruf, 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 ist in Anführungszeichen gesetzt, sodass ein Pfad, den ein Mod wählt, nicht als ein anderes Feld der Zeile durchgehen kann.

Der plugin.register-Hook 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 Ihrem Grund endet. Die Ablehnung erscheint außerdem im Transkript einer Sitzung, die ein Plugin-Verzeichnis im laufenden Betrieb neu lädt. Um einen Aufruf zu blockieren, ohne den ganzen Mod abzulehnen, geben Sie { deny: 'your reason' } aus einem Hook auf den Namen dieses Aufrufs zurück.

Um die Audit-Zeilen an einen anderen Ort 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 nicht integrierten Mod, 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.

Lehnen Sie Mods ab, wenn Ihre Überprüfung fehlschlägt

Wenn Ihr plugin.register-Hook einen Fehler auslöst oder sein Zeitlimit überschreitet, überspringt Claude Code den Hook. Die Überprüfung schlägt also offen fehl, und der Mod, den sie prüfen sollte, wird geladen. Um geschlossen fehlzuschlagen und Mods von Benutzern abzulehnen, verschieben Sie die Überprü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 plugin.register-Hook. 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 Überprüfung einen Fehler auslöste oder das Zeitlimit überschritt, nicht geladen, und die Ablehnungszeile enthält den zweiten Grund, wie in refused by acme-guard: Acme policy check failed, so this mod was not loaded. Der Handler gibt jeden Mod außerhalb der user-Stufe an next(e) weiter, sodass eine fehlgeschlagene Überprüfung die Mods, die Ihre Organisation auflistet, nicht aufhält. Einen fehlschlagenden Hook behandeln behandelt .catch für andere Ereignisse.

Nächste Schritte