1Password-Secrets-Broker

Das gebündelte Plugin onepassword stellt Agenten ein richtliniengesteuertes Werkzeug zum Lesen einer kuratierten Auswahl von 1Password-Feldern bereit. Es ist standardmäßig deaktiviert und führt keine Aktionen aus, solange plugins.entries.onepassword.config nicht vorhanden ist.

Dies ist ein Agentenwerkzeug, kein SecretRef-Provider. Es injiziert keine Umgebungsvariablen und löst keine Geheimnisse aus der OpenClaw-Konfiguration auf.

Sicherheitsmodell

• Nur Dienstkontoauthentifizierung. Das Token verbleibt in einer lokalen Anmeldedatendatei und wird in openclaw.json niemals akzeptiert.
• Nur kuratiertes Register. Agenten können konfigurierte Slugs auflisten, aber das Plugin listet niemals den Inhalt eines 1Password-Tresors auf.
• Richtlinie auto, approve oder deny pro Slug.
• Genehmigungen laufen ab. Ein zwischengespeicherter Wert umgeht niemals die aktuelle Richtlinie.
• Jeder Zugriffsversuch wird im gemeinsamen SQLite-Status von OpenClaw aufgezeichnet. Audit- Zeilen enthalten die angegebene Begründung; halten Sie Begründungen frei von vertraulichen Daten. Der Broker kopiert weder einen abgerufenen Wert noch das Dienst-Token in eine Audit-Zeile.
• Nach der aktuellen Werkzeugausführung ersetzt die von OpenClaw verwaltete Transkriptpersistenz einen erfolgreichen Wert von get durch geschwärzte Metadaten.
• Der Wert ist für das Modell während dieser Ausführung sichtbar. Wenn das Modell ihn in einen späteren Werkzeugaufruf oder eine Antwort kopiert, liegt dieser separate Datensatz außerhalb des Persistenz-Hooks dieses Plugins. Halten Sie Richtlinien eng gefasst und fordern Sie das Modell nicht auf, einen Wert wiederzugeben.
• Das Plugin ruft op bei jedem Cache-Fehlschlag einmal auf. Bei Ratenbegrenzungen oder anderen Fehlern erfolgt kein erneuter Versuch.
• Jeder Aufruf von op wird mit einer minimalen Umgebung ausgeführt, welche die Integration mit der 1Password-Desktop-App deaktiviert (OP_LOAD_DESKTOP_APP_SETTINGS=false, OP_BIOMETRIC_UNLOCK_ENABLED=false), sodass eine auf dem Gateway-Host installierte 1Password-App niemals biometrische Dialoge oder macOS-Berechtigungsdialoge auslöst.

Gewähren Sie dem Dienstkonto nur Lesezugriff auf die Tresore und Elemente, die in der Plugin-Konfiguration registriert sind.

Vorbereitungen

Sie benötigen:

• die auf dem Gateway-Host installierte 1Password-CLI (op)
• ein 1Password-Dienstkonto mit Zugriff auf die ausgewählten Elemente
• eine dedizierte Token-Datei für das Dienstkonto

Aktivieren Sie das gebündelte Plugin:

openclaw plugins enable onepassword

Erstellen Sie das Token-Verzeichnis und die Datei im OpenClaw-Statusverzeichnis:

mkdir -p ~/.openclaw/credentials/onepasswordchmod 700 ~/.openclaw/credentials/onepasswordprintf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \  ~/.openclaw/credentials/onepassword/service-account-tokenchmod 600 ~/.openclaw/credentials/onepassword/service-account-tokenunset OP_SERVICE_ACCOUNT_TOKEN

Wenn OPENCLAW_STATE_DIR gesetzt ist, ersetzen Sie ~/.openclaw durch dieses Verzeichnis. Das Plugin warnt einmalig, wenn die Token-Datei für die Gruppe oder andere Benutzer lesbar oder beschreibbar ist.

Registrierte Geheimnisse konfigurieren

Fügen Sie die Plugin-Konfiguration zu openclaw.json hinzu:

{  "plugins": {    "entries": {      "onepassword": {        "enabled": true,        "config": {          "vault": "Automation",          "defaultPolicy": "approve",          "cacheTtlSeconds": 300,          "grantTtlHours": 720,          "opTimeoutMs": 15000,          "items": {            "repository-token": {              "item": "Repository automation token",              "field": "credential",              "policy": "approve",              "description": "Token for repository automation",            },            "model-key": {              "item": "Model provider key",              "vault": "Agent credentials",              "policy": "auto",            },          },        },      },    },  },}

Slugs verwenden Kleinbuchstaben, Ziffern und Bindestriche, beginnen mit einem Buchstaben oder einer Ziffer und umfassen höchstens 64 Zeichen. Ein Register kann bis zu 32 Slugs enthalten; Beschreibungen dürfen bis zu 200 Zeichen umfassen. field akzeptiert eine Feldbezeichnung oder ID, darf kein Komma enthalten und verwendet standardmäßig credential. Ein vault auf Elementebene überschreibt den Standardtresor. opBin kann einen absoluten Pfad zur ausführbaren Datei op festlegen; andernfalls löst das Plugin op aus PATH auf. Elementtitel dürfen nicht mit einem Bindestrich beginnen.

Agentenwerkzeug verwenden

Der Werkzeugname lautet onepassword.

Registrierte Slugs auflisten:

{ "action": "list" }

Das Ergebnis enthält nur den Slug, die Beschreibung, die Richtlinie und die Information, ob eine dauerhafte Genehmigung aktiv ist. Es enthält niemals einen geheimen Wert und fragt 1Password nicht ab.

Ein Geheimnis anfordern:

{  "action": "get",  "slug": "repository-token",  "reason": "Authenticate the requested repository operation"}

reason ist erforderlich, darf nicht leer sein und ist auf 300 Zeichen begrenzt. Ein erfolgreicher get gibt den Wert sowie den konfigurierten Slug, den Elementtitel und die Feldbezeichnung zurück.

Das Werkzeugschema deklariert außerdem einen internen Parameter authorizationNonce. Die Richtlinienebene injiziert ihn nach der Auswertung der Anfrage, um die Autorisierung an den ausführenden Werkzeugaufruf zu übergeben. Legen Sie ihn niemals manuell fest: Der Richtlinien-Hook überschreibt jeden angegebenen Wert, und ein unbekannter Wert lässt die Anfrage fehlschlagen.

Richtlinienstufen und Genehmigungen

• auto: sofort abrufen und die Anfrage protokollieren.
• deny: die Anfrage blockieren und protokollieren.
• approve: eine nicht abgelaufene dauerhafte Genehmigung verwenden oder eine Person bitten, einmalig oder immer zu erlauben beziehungsweise abzulehnen.

Eine einmalige Erlaubnis autorisiert nur den aktuellen Werkzeugaufruf. Eine dauerhafte Erlaubnis schreibt eine dauerhafte Genehmigung für diesen Agenten und Slug in SQLite; andere Agenten müssen eine eigene Genehmigung erhalten. OpenClaw bietet die dauerhafte Erlaubnis nur an, wenn der Aufrufer über eine konkrete Agentenidentität verfügt. Die Genehmigung läuft nach grantTtlHours ab, wobei der Standardwert 720 Stunden beträgt. Eine nicht beantwortete oder wegen Zeitüberschreitung abgebrochene Genehmigungsanfrage lehnt die Anfrage ab; die maximale Wartezeit für eine Genehmigung beträgt 600 Sekunden. Das Plugin bewahrt bis zu 1.024 dauerhafte Genehmigungen auf; bei Erreichen dieser Grenze wird die älteste Genehmigung entfernt, und der zugehörige Agent muss den nächsten Zugriff genehmigen lassen.

Jede ausgewertete Autorisierung kann nur einmal verwendet werden und wird über den gemeinsamen SQLite-Status an den ausführenden Werkzeugaufruf übergeben, sodass die Übergabe auch funktioniert, wenn mehr als eine Plugin-Instanz im Gateway-Prozess aktiv ist. Nicht verwendete Autorisierungen laufen nach dem 600-sekündigen Genehmigungsfenster ab.

Der In-Memory-Cache verwendet standardmäßig 300 Sekunden und ist durch das konfigurierte Slug-Register begrenzt. Setzen Sie cacheTtlSeconds auf 0, um ihn zu deaktivieren. Die Richtlinie wird vor jedem Cache-Zugriff ausgewertet, und Cache-Treffer werden protokolliert. Das erneute Laden der Laufzeitkonfiguration wird an jeder Richtlinien- und Ausführungsgrenze wirksam; das Deaktivieren des Plugins oder das Entfernen, Ablehnen oder Neuzuordnen eines Slugs macht ausstehende Autorisierungen und zwischengespeicherte Werte ungültig.

Status und Audit-Verlauf prüfen

Bereitschaft und Registerzahlen anzeigen:

openclaw onepassword status

Dies meldet, ob die Token-Datei vorhanden ist, ob op aufgelöst wurde und unter welchem Pfad, die Anzahl der registrierten Elemente sowie die Anzahl pro Richtlinie. Das Token oder geheime Werte werden niemals gelesen oder ausgegeben.

Die 50 neuesten Audit-Zeilen anzeigen:

openclaw onepassword auditopenclaw onepassword audit --limit 100

Die neuesten Zeilen stehen zuerst und zeigen Zeitstempel, Agent, Slug, Ergebnis, einen errorCode bei einem fehlgeschlagenen Versuch sowie eine gekürzte Begründung. Die Begründung wird wie angegeben gespeichert; der Broker fügt den abgerufenen Wert niemals zum Audit-Protokoll hinzu.

Verhalten der 1Password-CLI

Bei jedem Cache-Fehlschlag wird op item get mit dem konfigurierten Element, Tresor und exakten Feldselektor, JSON-Ausgabe, einer begrenzten Zeitüberschreitung und --cache=false ausgeführt. Der untergeordnete Prozess erhält nur dieses Feld anstelle des vollständigen Elements. In der Umgebung des untergeordneten Prozesses sind nur OP_SERVICE_ACCOUNT_TOKEN und HOME vorhanden.

Das Plugin führt einen Versuch aus. Fehler von RATE_LIMITED sollten behandelt werden, indem vor einer späteren Agentenanfrage gewartet wird; das Plugin erstellt keine automatische Schleife für erneute Versuche.

Fehlercodes

Fehlgeschlagene Versuche enthalten einen abgeschlossenen Fehlercode im Werkzeugergebnis und in der Audit- Zeile.

1Password-Zugriffsfehler:

Richtlinien- und Validierungsfehler: