Plugin-Verwaltung

Vorbereitung

Workspace-Administratoren können einen Plugin-Marktplatz aus GitHub importieren und dessen Plugins über das Repository aktuell halten. Ein Marktplatz ist ein JSON-Katalog, in dem die zu importierenden Plugins aufgeführt sind.

Diese Seite behandelt den Import und die Synchronisierung im Arbeitsbereich. Wie Sie Marktplätze direkt auf lokalen Clients über eine in der Cloud verwaltete oder systemweite config.toml konfigurieren, erfahren Sie unter Plugin-Marktplätze und Standardeinstellungen konfigurieren. Wie Sie Plugins für ein bestimmtes Projekt aktivieren oder deaktivieren, erfahren Sie unter Ein Plugin für ein Repository aktivieren oder deaktivieren.

Verwenden Sie ein GitHub-Konto, das das Marktplatz-Repository und alle weiteren darin referenzierten Repositorys lesen kann. Öffentliche und private GitHub-Repositorys werden unterstützt. Schließen Sie vor dem Import alle für den Repository-Zugriff erforderlichen Genehmigungen der GitHub-Organisation ab.

Prüfen Sie vor dem Import den Inhalt des Repositorys. Neue Plugins beginnen mit Available als Installationsrichtlinie und einer Authentifizierung bei der Installation. Für neue Marktplätze ist die automatische tägliche Synchronisierung aktiviert. Beim Import werden alle gültigen Einträge verarbeitet, und bei zukünftigen Synchronisierungen werden neue Plugins im Repository automatisch hinzugefügt.

Marktplatzsynchronisierung konfigurieren

1. Öffnen Sie Admin > Plugins und wählen Sie Add > Import marketplace.
2. Geben Sie unter Source die Repository-URL ein, beispielsweise https://github.com/example/team-plugins. Verwenden Sie nur die Repository-URL ohne eine Branch- oder Ordner-URL.
3. Wenn sich der Marktplatz in einem Unterverzeichnis befindet, geben Sie dieses Verzeichnis unter Path ein. Verwenden Sie beispielsweise team-tools für team-tools/.agents/plugins/marketplace.json. Lassen Sie Path für das Stammverzeichnis des Repositorys leer. Geben Sie nicht den Namen der Manifestdatei ein.
4. Geben Sie optional einen Branch, tag, or commit ein. Lassen Sie dieses Feld leer, um den Standard-Branch des Repositorys zu verwenden. Verwenden Sie einen Branch, um zukünftige Commits zu erhalten. Ein fester Commit verbleibt auf diesem Revisionsstand.
5. Wählen Sie Import marketplace und autorisieren Sie den GitHub-Zugriff, wenn Sie dazu aufgefordert werden. Der Erstimport kann bei sehr großen Marktplätzen bis zu einer Stunde dauern. Nachfolgende tägliche Synchronisierungen dauern normalerweise wenige Minuten.
6. Prüfen Sie die Import results und öffnen Sie anschließend jedes importierte Plugin, um seine Installationsrichtlinie und alle erforderlichen Apps zu konfigurieren.

Um eine Aktualisierung anzufordern, ohne auf die tägliche Synchronisierung zu warten, öffnen Sie den Marktplatz unter Admin > Plugins > Marketplaces und wählen Sie Sync now.

Unterstützte Formate

Das ausgewählte Verzeichnis muss eine dieser Dateien enthalten:

Einträge in einem Marktplatz können native Plugins mit .codex-plugin/plugin.json, Claude-kompatible Plugins, Agent Plugins 1.0-Pakete oder unterstützte Skill-Pakete referenzieren.

Verwenden Sie bei einem Codex-Marktplatz lokale Pfade für Plugins im selben Repository:

{
  "name": "team-plugins",
  "interface": {
    "displayName": "Team plugins"
  },
  "plugins": [
    {
      "name": "team-tools",
      "source": {
        "source": "local",
        "path": "./plugins/team-tools"
      }
    }
  ]
}

Der Pfad ist relativ zum ausgewählten Marktplatz-Stammverzeichnis und nicht zu .agents/plugins/.

Ein Claude-kompatibler Marktplatz kann für jedes lokale Plugin eine Pfadzeichenfolge verwenden:

{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "team-tools",
      "source": "./plugins/team-tools"
    }
  ]
}

Codex-Marktplatzeinträge unterstützen außerdem source: "url" für ein Plugin im Stammverzeichnis eines GitHub-Repositorys und source: "git-subdir" für ein Plugin in einem GitHub-Unterverzeichnis. Beispiel:

{
  "name": "team-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/team-tools.git",
    "path": "./plugins/team-tools",
    "ref": "main"
  }
}

Git-Quellen können einen ref oder einen vollständigen 40-stelligen Commit sha auswählen. Das autorisierende GitHub-Konto muss jedes referenzierte Repository lesen können. Der Workspace-Import unterstützt derzeit nur GitHub-Repositorys.

Workspace-Zugriff konfigurieren

Beim Importieren und Synchronisieren über GitHub werden keine Installations- oder Authentifizierungsrichtlinien aus dem Repository angewendet, darunter AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL und ON_USE. Workspace-Administratoren konfigurieren diese Einstellungen für jedes Plugin. Beim Synchronisieren einer Aktualisierung oder beim Überführen eines bestehenden Plugins in die GitHub-Verwaltung bleiben dessen Workspace-Richtlinien erhalten.

Wählen Sie unter Installation policy für jede berechtigte Rolle Available oder Installed aus. Erforderliche Apps müssen ebenfalls aktiviert sein, und Mitglieder müssen Zugriff auf den verbundenen Dienst haben. Durch den Import eines Plugins wird weder App-Zugriff gewährt noch werden die Konten der Mitglieder verbunden. Weitere Informationen zu Rollen-, App- und Aktionssteuerelementen finden Sie unter Plugin-Steuerelemente.

Ein bestehendes Plugin in die GitHub-Verwaltung überführen

Fügen Sie dem Marktplatzeintrag des bestehenden Plugins pluginId hinzu:

{
  "name": "team-tools",
  "pluginId": "plugin_0123456789abcdef0123456789abcdef",
  "source": {
    "source": "local",
    "path": "./plugins/team-tools"
  }
}

Öffnen Sie das Plugin unter Admin > Plugins und kopieren Sie aus seiner URL die ID nach /admin/plugins/. Fügen Sie pluginId neben name und source in den Marktplatzeintrag ein. Das bestehende Plugin muss sich im selben Workspace befinden.

Dadurch wird ein hochgeladenes oder anderweitig nicht verwaltetes Workspace-Plugin in die GitHub-Verwaltung überführt. ID, Freigabe und Workspace-Richtlinien des Plugins bleiben erhalten. Zukünftige Aktualisierungen stammen aus GitHub. Archiv-Uploads können das verwaltete Plugin nicht mehr ersetzen. Ein Plugin, das bereits von einer anderen GitHub-Quelle verwaltet wird, kann auf diese Weise nicht übernommen werden.

Reine Desktop-Plugins

Jedes importierte Plugin, das MCP-Server in mcp.json oder .mcp.json deklariert, wird als Desktop only gekennzeichnet und funktioniert nur in der ChatGPT-Desktop-App. Dies gilt auch für Server, die eine Remote-HTTPS-URL verwenden. Dieselbe Einschränkung gilt für andere unterstützte MCP-Konfigurationsformen, beispielsweise Inline-Serverdeklarationen.

Eine bestehende App mit .app.json referenzieren

Fügen Sie .app.json im Stammverzeichnis des Plugins hinzu. Der Dateiname enthält einen führenden Punkt. app.json ohne den Punkt wird nicht unterstützt.

{
  "apps": {
    "team-tools": {
      "id": "asdk_app_example",
      "required": true
    }
  }
}

Ersetzen Sie asdk_app_example durch die ID der bestehenden App. Unterstützte App-IDs beginnen mit asdk_app_, connector_ oder templated_apps_. Verwenden Sie die App-ID und keine plugin_...-ID. Beispielsweise repräsentiert eine Plugin-URL mit plugin_asdk_app_example die App asdk_app_example.

Der Schlüssel team-tools benennt die Referenz innerhalb dieser Datei. Setzen Sie required auf true, wenn das Plugin von der App abhängig ist. Sie können weitere Einträge hinzufügen, um andere bestehende Apps zu referenzieren.

Setzen Sie bei einem nativen Plugin apps in .codex-plugin/plugin.json auf ./.app.json. Hier sehen Sie ein vollständiges Manifest für dieses Beispiel:

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Use the team's approved tools.",
  "author": {
    "name": "Example team"
  },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team tools",
    "shortDescription": "Use approved team tools",
    "longDescription": "Connect to the team's existing app.",
    "developerName": "Example team",
    "category": "Productivity",
    "capabilities": ["Read"]
  }
}

Behalten Sie für die Dateien diese Struktur bei:

team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
    ├── .codex-plugin/plugin.json
    └── .app.json

Die Referenz erstellt keine App und erteilt keine Berechtigungen. Administratoren müssen die App für die vorgesehenen Rollen verfügbar machen, und Mitglieder müssen alle erforderlichen Authentifizierungsschritte abschließen. Bestehende App-Berechtigungen, Aktionssteuerelemente und Dienstzugriffe gelten weiterhin.

Plugins aktuell halten

Neue Marktplätze suchen täglich nach Aktualisierungen. Öffnen Sie Admin > Plugins > Marketplaces, wählen Sie den Marktplatz aus und wählen Sie Sync now, um eine Aktualisierung anzufordern, ohne auf die automatische Synchronisierung zu warten.

Bei der Synchronisierung können neue Marktplatzeinträge hinzugefügt und bestehende Plugins aktualisiert werden. Prüfen Sie Änderungen am Repository vor dem Zusammenführen, da bei der automatischen Synchronisierung alle neuen Plugins importiert werden.

Prüfen Sie nach einer Synchronisierung den Status und den gespeicherten Bericht. Completed — N errors bedeutet, dass der Durchlauf abgeschlossen wurde, einige Plugins jedoch nicht verarbeitet werden konnten. Wenn eine Aktualisierung eines bestehenden Plugins ungültig ist, bleibt dessen letzte funktionsfähige Version erhalten. Beheben Sie das gemeldete Problem in GitHub und wählen Sie anschließend Sync now, um es erneut zu versuchen.

Wenn ein Eintrag aus dem Repository entfernt wird, wird seine importierte Workspace-Kopie nicht gelöscht. Sie wird als No longer in source gekennzeichnet. Wenn Sie den Marktplatz in ChatGPT löschen, werden alle daraus importierten Plugins gelöscht.

GitHub-Zugriff erneut verbinden oder ändern

Um den GitHub-Zugriff erneut zu verbinden, vergewissern Sie sich zunächst, dass das für den Import verwendete GitHub-Konto weiterhin Zugriff auf das Repository und alle referenzierten Repositorys hat. Anschließend sollte der Administrator, der den Marktplatz ursprünglich importiert hat, das GitHub-Plugin in ChatGPT öffnen und sein Konto erneut verbinden, da die Marktplatzsynchronisierung die GitHub-Verbindung dieses Administrators verwendet.

Für die Übertragung an einen neuen Eigentümer sollte der neue Workspace-Administrator Admin > Plugins > Add > Import marketplace öffnen und denselben Marktplatz mit denselben Werten für Source, Path und Branch, tag, or commit importieren. Zukünftige Synchronisierungen verwenden dann dessen GitHub-Verbindung.

Löschen Sie den Marktplatz nicht, nur um ihn erneut zu verbinden oder den Eigentümer zu ändern: Beim Löschen werden auch die daraus importierten Plugins entfernt.