Plug-in-Verwaltung

Bevor du beginnst

Workspace-Admins können einen Plug-in-Marketplace aus GitHub importieren und seine Plug-ins über das Repository aktuell halten. Ein Marketplace ist ein JSON-Katalog, der die zu importierenden Plug-ins auflistet.

Diese Seite behandelt den Import und die Synchronisierung im Workspace. Wie du Marketplaces direkt auf lokalen Clients über eine cloudverwaltete oder systemweite config.toml konfigurierst, erfährst du unter Plug-in-Marketplaces und Standardeinstellungen konfigurieren. Wie du Plug-ins für ein bestimmtes Projekt aktivierst oder deaktivierst, erfährst du unter Ein Plug-in für ein Repository aktivieren oder deaktivieren.

Verwende ein GitHub-Konto mit Lesezugriff auf das Marketplace-Repository und alle weiteren darin referenzierten Repositorys. Öffentliche und private GitHub-Repositorys werden unterstützt. Hole vor dem Import alle Genehmigungen deiner GitHub-Organisation ein, die für den Zugriff auf die Repositorys erforderlich sind.

Überprüfe vor dem Import den Inhalt des Repositorys. Neue Plug-ins erhalten zunächst die Installationsrichtlinie Verfügbar und erfordern eine Authentifizierung bei der Installation. Bei neuen Marketplaces ist die automatische tägliche Synchronisierung aktiviert. Beim Import werden alle gültigen Einträge verarbeitet. Künftige Synchronisierungen fügen automatisch alle neuen Plug-ins aus dem Repository hinzu.

Marketplace-Synchronisierung konfigurieren

1. Öffne Admin > Plug-ins und wähle Hinzufügen > Marketplace importieren.
2. Gib unter Quelle die Repository-URL ein, zum Beispiel https://github.com/example/team-plugins. Verwende nur die URL des Repositorys, keine URL eines Branches oder Ordners.
3. Wenn sich der Marketplace in einem Unterverzeichnis befindet, gib dieses unter Pfad ein. Verwende beispielsweise team-tools für team-tools/.agents/plugins/marketplace.json. Lass Pfad für das Stammverzeichnis des Repositorys leer. Gib nicht den Dateinamen des Manifests ein.
4. Optional kannst du das Feld Branch, Tag oder Commit ausfüllen. Lass es leer, um den Standard-Branch des Repositorys zu verwenden. Verwende einen Branch, um künftige Commits zu übernehmen. Bei einem festgelegten Commit bleibt der Stand unverändert.
5. Wähle Marketplace importieren und autorisiere den GitHub-Zugriff, wenn du dazu aufgefordert wirst. Bei sehr großen Marketplaces kann der erste Import bis zu einer Stunde dauern. Die anschließenden täglichen Synchronisierungen dauern in der Regel nur wenige Minuten.
6. Überprüfe die Importergebnisse. Öffne anschließend jedes importierte Plug-in, um seine Installationsrichtlinie und gegebenenfalls erforderliche Apps zu konfigurieren.

Um ein Update anzufordern, ohne auf die tägliche Synchronisierung zu warten, öffne den Marketplace unter Admin > Plug-ins > Marketplaces und wähle Jetzt synchronisieren.

Unterstützte Formate

Das ausgewählte Verzeichnis muss eine dieser Dateien enthalten:

Einträge in einem Marketplace können auf native Plug-ins mit .codex-plugin/plugin.json, Claude-kompatible Plug-ins, Pakete im Format Agent Plugins 1.0 oder unterstützte Skill-Pakete verweisen.

Verwende in einem Codex-Marketplace lokale Pfade für Plug-ins 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 Stammverzeichnis des Marketplaces, nicht zu .agents/plugins/.

Ein Claude-kompatibler Marketplace kann für jedes lokale Plug-in einen Pfad als Zeichenfolge verwenden:

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

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

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

Bei Git-Quellen kannst du eine ref oder den vollständigen, 40 Zeichen langen sha-Wert eines Commits angeben. Das zur Autorisierung verwendete GitHub-Konto muss Lesezugriff auf jedes referenzierte Repository haben. Der Workspace-Import unterstützt derzeit nur GitHub-Repositorys.

Zugriff im Workspace konfigurieren

Beim GitHub-Import und bei der Synchronisierung werden die Installations- und Authentifizierungsrichtlinien aus dem Repository nicht übernommen. Dazu gehören AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL und ON_USE. Workspace-Admins konfigurieren diese Einstellungen für jedes Plug-in. Wenn ein Update synchronisiert oder ein bestehendes Plug-in auf die Verwaltung über GitHub umgestellt wird, bleiben seine Workspace-Richtlinien erhalten.

Wähle unter Installationsrichtlinie für jede berechtigte Rolle Verfügbar oder Installiert aus. Erforderliche Apps müssen ebenfalls aktiviert sein, und Mitglieder müssen Zugriff auf den verbundenen Dienst haben. Der Import eines Plug-ins gewährt keinen App-Zugriff und verbindet keine Konten von Mitgliedern. Informationen zu den Kontrollen für Rollen, Apps und Aktionen findest du unter Kontrollen für Plug-ins.

Ein bestehendes Plug-in auf die Verwaltung über GitHub umstellen

Füge pluginId zum Marketplace-Eintrag des bestehenden Plug-ins hinzu:

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

Öffne das Plug-in unter Admin > Plug-ins und kopiere die ID, die in seiner URL auf /admin/plugins/ folgt. Füge pluginId neben name und source im Marketplace-Eintrag ein. Das bestehende Plug-in muss sich im selben Workspace befinden.

Damit stellst du ein hochgeladenes oder anderweitig nicht verwaltetes Workspace-Plug-in auf die Verwaltung über GitHub um. Seine ID, Freigaben und Workspace-Richtlinien bleiben erhalten. Künftige Updates kommen aus GitHub. Das verwaltete Plug-in lässt sich dann nicht mehr durch das Hochladen eines Archivs ersetzen. Ein Plug-in, das bereits über eine andere GitHub-Quelle verwaltet wird, lässt sich auf diese Weise nicht übernehmen.

Plug-ins nur für den Desktop

Jedes importierte Plug-in, das MCP-Server in mcp.json oder .mcp.json deklariert, wird als Nur Desktop gekennzeichnet und funktioniert ausschließlich in der ChatGPT-Desktop-App. Das gilt auch für Server, die eine entfernte HTTPS-URL verwenden. Dieselbe Einschränkung gilt für andere unterstützte Formen der MCP-Konfiguration, etwa Inline-Serverdeklarationen.

Mit .app.json auf eine bestehende App verweisen

Füge .app.json im Stammverzeichnis des Plug-ins hinzu. Der Dateiname beginnt mit einem Punkt. app.json ohne den Punkt wird nicht unterstützt.

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

Ersetze asdk_app_example durch die ID der bestehenden App. Unterstützte App-IDs beginnen mit asdk_app_, connector_ oder templated_apps_. Verwende die App-ID, keine plugin_...-ID. Eine Plug-in-URL, die plugin_asdk_app_example enthält, steht beispielsweise für die App asdk_app_example.

Der Schlüssel team-tools benennt die Referenz innerhalb dieser Datei. Setze required auf true, wenn das Plug-in von der App abhängt. Du kannst weitere Einträge hinzufügen, um auf andere bestehende Apps zu verweisen.

Setze bei einem nativen Plug-in in .codex-plugin/plugin.json den Schlüssel apps auf ./.app.json. Hier ist 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"]
  }
}

Verwende für die Dateien diese Verzeichnisstruktur:

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

Die Referenz erstellt keine App und erteilt keine Berechtigungen. Admins müssen die App für die vorgesehenen Rollen verfügbar machen, und Mitglieder müssen sich bei Bedarf authentifizieren. Bestehende App-Berechtigungen, Aktionskontrollen und Zugriffsregeln für den Dienst gelten weiterhin.

Plug-ins aktuell halten

Neue Marketplaces prüfen täglich auf Updates. Öffne Admin > Plug-ins > Marketplaces, wähle den Marketplace und anschließend Jetzt synchronisieren , um ein Update anzufordern, ohne auf die automatische Synchronisierung zu warten.

Die Synchronisierung kann neue Marketplace-Einträge hinzufügen und bestehende Plug-ins aktualisieren. Überprüfe Änderungen am Repository, bevor du sie mergst, da die automatische Synchronisierung alle neuen Plug-ins importiert.

Überprüfe nach einer Synchronisierung den Status und den gespeicherten Bericht. Abgeschlossen: N Fehler bedeutet, dass der Durchlauf beendet wurde, aber einige Plug-ins nicht verarbeitet werden konnten. Ist ein Update für ein bestehendes Plug-in ungültig, bleibt dessen letzte funktionierende Version erhalten. Behebe das gemeldete Problem in GitHub und wähle anschließend Jetzt synchronisieren , um es erneut zu versuchen.

Wenn du einen Eintrag aus dem Repository entfernst, wird seine importierte Kopie im Workspace nicht gelöscht. Sie wird als Nicht mehr in der Quelle vorhanden gekennzeichnet. Wenn du den Marketplace in ChatGPT löschst, werden alle daraus importierten Plug-ins gelöscht.

GitHub-Zugriff wiederherstellen oder ändern

Um den GitHub-Zugriff wiederherzustellen, prüfe zunächst, ob das für den Import verwendete GitHub-Konto weiterhin Zugriff auf das Repository und alle referenzierten Repositorys hat. Die Person mit Adminrechten, die den Marketplace ursprünglich importiert hat, sollte anschließend das GitHub-Plug-in in ChatGPT öffnen und ihr Konto erneut verbinden. Die Marketplace-Synchronisierung verwendet nämlich die GitHub-Verbindung dieser Person.

Um die Inhaberschaft zu übertragen, sollte die neu zuständige Person mit Workspace-Adminrechten Admin > Plug-ins > Hinzufügen > Marketplace importieren öffnen und denselben Marketplace mit denselben Werten für Quelle, Pfad und Branch, Tag oder Commit importieren. Künftige Synchronisierungen verwenden dann ihre GitHub-Verbindung.

Lösche den Marketplace nicht, nur um ihn erneut zu verbinden oder die Inhaberschaft zu ändern: Beim Löschen werden auch seine importierten Plug-ins entfernt.