Plugin-Berechtigungsanfragen

Plugin-Berechtigungsanfragen ermöglichen es Plugin-Code, einen Tool-Aufruf oder einen Plugin-eigenen Vorgang anzuhalten, bis ein Benutzer ihn genehmigt oder ablehnt. Sie verwenden den Gateway- plugin.approval.*-Ablauf und dieselben Genehmigungsoberflächen, die Chat- Genehmigungsschaltflächen und /approve-Befehle verarbeiten.

Verwenden Sie Plugin-Berechtigungsanfragen für Plugin-/App-Berechtigungen. Sie ersetzen weder Host-Ausführungsgenehmigungen, optionale Tool-Zulassungslisten noch die native Berechtigungsprüfung von Codex.

Die richtige Prüfstufe auswählen

Wählen Sie die Prüfstufe, die dem benötigten Entscheidungspunkt entspricht:

Optionale Tools bilden eine Prüfstufe während der Ermittlung. Plugin-Berechtigungsanfragen bilden eine Prüfstufe pro Aufruf. Verwenden Sie beides, wenn ein sensibles Tool eine ausdrückliche Zustimmung erfordern soll, bevor das Modell es sehen kann, sowie eine Genehmigung, bevor die Aktion ausgeführt wird.

Genehmigung vor einem Tool-Aufruf anfordern

Die meisten von Plugins erstellten Abfragen sollten in einem before_tool_call-Hook beginnen. Der Hook wird ausgeführt, nachdem das Modell ein Tool ausgewählt hat und bevor OpenClaw es ausführt:

 export default definePluginEntry({  id: "deploy-policy",  name: "Deploy Policy",  register(api) {    api.on("before_tool_call", async (event) => {      if (event.toolName !== "deploy_service") {        return;      }       const environment =        typeof event.params.environment === "string" ? event.params.environment : "unknown";       return {        requireApproval: {          title: "Deploy service",          description: `Deploy service to ${environment}.`,          severity: environment === "production" ? "critical" : "warning",          allowedDecisions:            environment === "production"              ? ["allow-once", "deny"]              : ["allow-once", "allow-always", "deny"],          timeoutMs: 120_000,          onResolution(decision) {            console.log(`deploy approval resolved: ${decision}`);          },        },      };    });  },});

Formulieren Sie den Abfragetext für die Person, die die Aktion genehmigen wird:

• Halten Sie title kurz und aktionsbezogen; der Gateway begrenzt den Text auf 80 Zeichen.
• Formulieren Sie description spezifisch und klar begrenzt; der Gateway beschränkt den Text auf 512 Zeichen.
• Geben Sie Aktion, Ziel und Risiko an. Fügen Sie keine Secrets, Tokens oder privaten Nutzdaten ein, die nicht auf Chat-Genehmigungsoberflächen erscheinen dürfen.
• severity verwendet standardmäßig "warning", wenn keine Angabe erfolgt. Verwenden Sie "critical" nur für Aktionen, bei denen eine falsche Entscheidung Produktionsschäden oder Datenverlust verursachen könnte.
• allowedDecisions verwendet standardmäßig ["allow-once", "allow-always", "deny"], wenn keine Angabe erfolgt. Übergeben Sie ["allow-once", "deny"], wenn dauerhaftes Vertrauen für diese Aktion unsicher ist.
• timeoutMs verwendet standardmäßig 120000 (2 Minuten) und ist unabhängig vom angeforderten Wert auf 600000 (10 Minuten) begrenzt.

Entscheidungsverhalten

OpenClaw erstellt eine ausstehende Genehmigung mit einer plugin:-ID, übermittelt sie an die verfügbaren Genehmigungsoberflächen und wartet auf eine Entscheidung.

Nur die von der Anfrage zugelassenen exakten Entscheidungen allow-once und allow-always ermöglichen die Ausführung. Unbekannte, fehlerhafte, nicht übereinstimmende, fehlende und abgelaufene Entscheidungen führen zum sicheren Abbruch. Das veraltete Feld timeoutBehavior wird aus Gründen der Plugin-Kompatibilität weiterhin akzeptiert, ist jedoch veraltet und wird ignoriert; setzen Sie es nicht in neuen Hooks.

allow-always ist nur dauerhaft, wenn das anfordernde Plugin oder die Laufzeit diese Persistenz implementiert. Bei gewöhnlichen before_tool_call.requireApproval-Hooks behandelt OpenClaw allow-once und allow-always als Genehmigungsentscheidungen für den aktuellen Aufruf und übergibt den aufgelösten Wert an onResolution. Wenn Ihr Plugin allow-always anbietet, dokumentieren und implementieren Sie genau, welchen zukünftigen Aufrufen es vertraut.

Wenn der Hook außerdem params zurückgibt, wendet OpenClaw diese Parameteränderungen erst nach erfolgreicher Genehmigung an. Ein Hook mit niedrigerer Priorität kann weiterhin blockieren, nachdem ein Hook mit höherer Priorität eine Genehmigung angefordert hat.

allowedDecisions beschränkt die Schaltflächen und Befehle, die dem Benutzer angezeigt werden. Der Gateway lehnt jeden Auflösungsversuch für eine Entscheidung ab, die von der Anfrage nicht angeboten wurde.

Genehmigungsabfragen weiterleiten

Genehmigungsabfragen können auf lokalen UI-Oberflächen oder in Chat-Kanälen aufgelöst werden, die Genehmigungen unterstützen. Konfigurieren Sie approvals.plugin, um Plugin-Genehmigungsabfragen an explizite Chat-Ziele weiterzuleiten:

{  approvals: {    plugin: {      enabled: true,      mode: "targets",      agentFilter: ["main"],      targets: [{ channel: "slack", to: "U12345678" }],    },  },}

approvals.plugin ist unabhängig von approvals.exec. Das Aktivieren der Weiterleitung von Ausführungsgenehmigungen leitet keine Plugin-Genehmigungsabfragen weiter, und das Aktivieren der Weiterleitung von Plugin-Genehmigungen ändert nicht die Host-Ausführungsrichtlinie.

Wenn eine Abfrage manuellen Genehmigungstext enthält, lösen Sie sie mit einer der angebotenen Entscheidungen auf:

/approve <id> allow-once/approve <id> allow-always/approve <id> deny

Weitere Informationen zum vollständigen Weiterleitungsmodell, zur Genehmigung im selben Chat, zur nativen Kanalzustellung und zu kanalspezifischen Regeln für Genehmigende finden Sie unter Erweiterte Ausführungsgenehmigungen.

Native Codex-Berechtigungen

Native Codex-Berechtigungsabfragen können ebenfalls über Plugin-Genehmigungen übertragen werden, haben jedoch eine andere Zuständigkeit als von Plugins erstellte Hooks.

• Genehmigungsanfragen des Codex-App-Servers werden nach der Codex-Prüfung über OpenClaw geleitet.
• Die Weiterleitung des nativen Hooks permission_request kann über plugin.approval.request nachfragen, wenn diese Weiterleitung aktiviert ist.
• MCP-Tool-Genehmigungsabfragen werden über Plugin-Genehmigungen geleitet, wenn Codex _meta.codex_approval_kind als "mcp_tool_call" kennzeichnet.

Informationen zum Codex-spezifischen Verhalten und zu den Fallback-Regeln finden Sie unter Codex-Harness-Laufzeit.

Fehlerbehebung

Das Tool meldet, dass Plugin-Genehmigungen nicht verfügbar sind. Keine Genehmigungs-UI und kein konfigurierter Genehmigungsweg hat die Anfrage angenommen. Verbinden Sie einen genehmigungsfähigen Client, verwenden Sie einen Kanal, der /approve im selben Chat unterstützt, oder konfigurieren Sie approvals.plugin.

allow-always wird angezeigt, aber beim nächsten Aufruf erfolgt erneut eine Abfrage. Der generische Plugin-Genehmigungsablauf speichert Vertrauen für beliebige Hooks nicht automatisch dauerhaft. Speichern Sie Plugin-eigenes Vertrauen nach onResolution("allow-always") dauerhaft in Ihrem Plugin oder bieten Sie nur allow-once und deny an.

/approve lehnt die Entscheidung ab. Die Anfrage hat allowedDecisions eingeschränkt. Verwenden Sie eine der in der Abfrage ausgegebenen Entscheidungen.

Eine Abfrage in Discord, Matrix, Slack oder Telegram wird anders weitergeleitet als Ausführungsgenehmigungen. Plugin-Genehmigungen und Ausführungsgenehmigungen verwenden separate Konfigurationen und möglicherweise unterschiedliche Autorisierungsprüfungen. Prüfen Sie approvals.plugin und die Unterstützung des Kanals für Plugin-Genehmigungen, statt ausschließlich approvals.exec zu prüfen.

Verwandte Themen

• Plugin-Hooks
• Plugins erstellen
• Erweiterte Ausführungsgenehmigungen
• Gateway-Protokoll
• Codex-Harness-Laufzeit