SpyBara
Go Premium

plugins/mods/admin.md 2026-09-30 23:00 UTC to 2026-10-01 21:59 UTC

This page contains 375 additions and 0 deletions.

2026
Thu 1 23:02

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 hooken 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 jeden Weg auf, auf dem ein Plugin geladen wird, und die Einstellung, die jeden 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, daher lädt niemand einen Mod aus einem Verzeichnis, 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.

Setzen Sie Optionen auf dem integrierten Guard

Der integrierte Guard nimmt zwei 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 Mods Ihrer eigenen für jeden Benutzer bereitstellen, wählen, wo sie relativ zu Mods von Benutzern ausgeführt werden, und einen verwenden, um eine Richtlinie durchzusetzen.

Installieren Sie die Mods Ihrer Organisation und setzen Sie die Reihenfolge

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 in der Lage sein zu sagen, dass ein Mod von Ihnen kam. Es behandelt einen Mod als Mod Ihrer Organisation nur, wenn alle diese Punkte zutreffen:

  • Verwaltete enabledPlugins setzt das Plugin des Mods auf true
  • Verwaltete Einstellungen benennen den Marketplace des Plugins als Verzeichnis auf der Maschine des Benutzers, nach absolutem Pfad. Ein extraKnownMarketplaces Eintrag tut das und registriert den Marketplace für den Benutzer auch.
  • Der Marketplace listet das Plugin nach einem relativen Pfad auf, daher lädt Claude Code es an Ort und Stelle aus diesem Verzeichnis

Um sie zu erfüllen, lassen Sie Ihre Geräteverwaltung das Marketplace-Verzeichnis auf den gleichen Pfad auf jeder Maschine kopieren. Machen Sie das Verzeichnis und jedes Verzeichnis darüber nur für einen Administrator beschreibbar, wie die verwaltete Einstellungsdatei. 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 tragen, aber sie können das Verzeichnis nicht auf eine Maschine legen.

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 nach seinem Pfad relativ zu diesem Verzeichnis:

{
  "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 eines eines Benutzers, auch wenn verwaltete enabledPlugins es aktiviert. Das umfasst jedes Plugin von einer GitHub-, Git-, URL- oder npm-Quelle. Sein Mod wird unter Mods von Benutzern ausgeführt, prependPlugins und appendPlugins überspringen es, und es wird nicht unter allowManagedModsOnly oder allowManagedHooksOnly geladen. Das Debug-Protokoll des Benutzers hat eine Zeile, die mit der ID des Plugins beginnt und is enabled by managed settings, but.

Claude Code löst ein Ereignis aus, jedes Mal wenn es etwas tun soll, wie ein Tool ausführen, und übergibt es an jeden Mod der Reihe nach. Ein Mod, der als Ihrer zählt, wird vor Mods von Benutzern ausgeführt, auch wenn Sie ihn nirgendwo auflisten. Um seinen Platz zu setzen, listen Sie seine ID in einer von zwei Einstellungen auf. Die ID ist der Name des Plugins, @, und der Name des Marketplace, wie 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 acme-tools Marketplace bei /opt/acme/claude-plugins, aktiviert acme-guard von ihm und führt diesen Mod zuerst aus, mit dem integrierten Guard danach:

{
  "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 tut einen Job:

  • extraKnownMarketplaces: benennt das Verzeichnis, das den acme-tools Marketplace 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 zuerst und den integrierten Guard zweite, beide vor jedem Mod, den ein Benutzer installiert. Claude Code folgt der Reihenfolge, die Sie auflisten.

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

Um zu bestätigen, wo der Mod ausgeführt wird, starten Sie eine Sitzung auf dieser Maschine mit claude --debug und suchen Sie das Debug-Protokoll 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
  • Die gleiche Zeile mit tier user: Claude Code behandelt es 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, sagt, dass die Liste es übersprungen hat.

Diese Regeln entscheiden, welche IDs in den zwei Listen wirksam werden:

  • Die Liste ersetzt die Standardeinstellung: Wenn Sie prependPlugins in verwalteten Einstellungen setzen, benennen Sie sec-default@builtin darin, um den integrierten Guard zu behalten. Der Guard ist integriert und braucht keinen enabledPlugins Eintrag.
  • Ihre eigenen IDs müssen als Ihre zählen: In verwalteten Einstellungen überspringt Claude Code eine ID, deren Plugin nicht die drei Bedingungen für einen Mod einer Organisation erfüllt
  • Repositories können sie nicht setzen: Claude Code liest beide Einstellungen aus verwalteten Einstellungen und niemals aus einer Einstellungsdatei eines Repositorys. Ein Benutzer kann sie in ~/.claude/settings.json setzen, um nur seine eigenen Mods auf einer Maschine ohne verwaltete Einstellungen zu ordnen, 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 weder fügt noch entfernt den integrierten Guard.

Erzwingen Sie eine Richtlinie mit einem Mod Ihrer eigenen

Um jeden Mod eines Benutzers auszuschließen, brauchen Sie keinen Mod Ihrer eigenen. Setzen Sie allowManagedModsOnly. Schreiben Sie einen Policy-Mod, wenn Sie einige Mods von Benutzern zulassen und andere ablehnen möchten, oder um zu protokollieren, was Mods tun.

Jedes Mal wenn ein anderer Mod geladen werden soll, erhält Ihr Mod die Liste, die claude plugin validate druckt, in einem Ereignis namens plugin.register. Ein Mod in prependPlugins kann diese Liste lesen und den Mod ablehnen. Er kann auch jeden Mods API-Aufruf nach Name hooken, um diesen Aufruf für jeden anderen Mod zu protokollieren oder abzulehnen. Der Name ist die Methode ohne das $., daher sieht ein Hook auf fs.write jeden $.fs.write Aufruf.

Dieser Policy-Mod lehnt jeden Mod eines Benutzers ab, dessen eigener Code $.process.run oder $.process.spawn aufruft. Er führt auch ein Audit-Protokoll, schreibt jeden Tool-Aufruf und jede Datei, die ein Mod schreibt, in das Debug-Protokoll. Da er zuerst ausgeführt wird, protokolliert das Protokoll, was angefordert wurde, bevor ein Mod eines Benutzers es ändert. Speichern Sie es als acme-guard/hooks/register.js:

// Die Methoden, die kein Mod eines Benutzers aufrufen darf, jede geschrieben als namespace.method
const BLOCKED_CALLS = ['process.run', 'process.spawn']

export function register(on) {
  // Wird jedes Mal ausgeführt, wenn ein anderer Mod geladen werden soll
  on('plugin.register', async ($, e, next) => {
    // Behalten Sie die Aufrufe in diesem Mod's Code, die auf der blockierten Liste stehen
    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
    if (e.tier === 'user' && blocked.length > 0) {
      // Das Zurückgeben von refuse verhindert, dass der Mod geladen wird, und der Text ist der Grund
      return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
    }
    // Lassen Sie jeden anderen Mod laden
    return next(e)
  })

  // Protokollieren Sie jeden Tool-Aufruf, dann lassen Sie ihn unverändert weitergehen
  on('tool.call', async ($, e, next) => {
    $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })
    return next(e)
  })

  // Protokollieren Sie, welcher Mod eine Datei geschrieben hat, dann den Pfad, zitiert, weil der Mod ihn gewählt hat
  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 eine Zeile wie audit tool.call Bash in das Debug-Protokoll für jeden Tool-Aufruf und ändert nichts
  • fs.write: schreibt eine Zeile wie audit fs.write by reader "/tmp/notes.md" für jeden $.fs.write Aufruf, den ein anderer Mod macht, und ändert nichts. Der Name des Mods kommt zuerst und der Pfad ist zitiert, daher kann ein Pfad, den ein Mod wählt, nicht als ein anderes Feld der Zeile durchgehen.

Der plugin.register Hook liest zwei Felder des Ereignisses:

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

Wenn ein Benutzer einen Mod installiert, der $.process.run aufruft, wird der Mod nicht geladen, und sein Debug-Protokoll hat eine Zeile, die mit refused by acme-guard: und Ihrem Grund endet. Die Verweigerung erreicht auch das Transkript in einer Sitzung, die ein Plugin-Verzeichnis neu lädt. Um einen Aufruf zu blockieren, ohne den ganzen Mod abzulehnen, geben Sie { deny: 'your reason' } von einem Hook auf den Namen dieses Aufrufs zurück.

Um die Audit-Zeilen woanders als im Debug-Protokoll zu senden, rufen Sie $.http.fetch von den gleichen Hooks auf.

Eine Sitzung kann ohne Ihren Mod ausgeführt werden. 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, wird ohne installierte Mods ausgeführt, einschließlich Ihrer.

Erstellen Sie einen Mod behandelt die Dateien, die ein Mod braucht. Testen Sie einen Mod, der andere Mods beurteilt hat eine Test-Datei für diesen Policy-Mod.

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

Wenn Ihr plugin.register Hook wirft oder seine Zeitlimit überschreitet, überspringt Claude Code den Hook, daher schlägt die Überprüfung offen fehl und der Mod, den er überprüft, 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 Verweigerung zurückgibt. Diese Version der Datei zeigt nur den plugin.register Hook, daher behalten Sie die zwei Audit-Hooks aus der ersten Version in register:

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

// Die gleiche Überprüfung wie zuvor, in eine Funktion ihrer eigenen verschoben
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) {
  // Der Handler wird nur ausgeführt, wenn checkMod wirft oder sein Zeitlimit überschreitet
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    // Lassen Sie die Mods Ihrer Organisation und integrierte Mods laden
    if (e.tier !== 'user') return next(e)
    // Lehnen Sie den Mod eines Benutzers ab, der nicht überprüft werden konnte
    return { refuse: 'Acme policy check failed, so this mod was not loaded' }
  })
}

Mit dem Handler an Ort und Stelle wird ein Mod, der überprüft wurde, als die Überprüfung wirft oder das Zeitlimit überschreitet, nicht geladen, und die Verweigerungszeile trägt 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 des user Tier an next(e) weiter, daher stoppt eine fehlgeschlagene Überprüfung nicht die Mods, die Ihre Organisation auflistet. Behandeln Sie einen Hook, der fehlschlägt, behandelt .catch für andere Ereignisse.

Nächste Schritte