Pi Agent Sicherheit und Projektvertrauen

Pi Agent wird mit den Berechtigungen deines aktuellen Benutzers ausgeführt.

Dieses Kapitel stellt den Projektvertrauensmechanismus, Sicherheitsgrenzen und Optionen für containerisierte Ausführung vor.

Pi Agent-Sicherheitsmodell

Pi Agent ist einlokaler Coding-Agent—er wird mit den Benutzerberechtigungen ausgeführt, die du beim Start hattest, und kann Dateien lesen, schreiben, bearbeiten und Shell-Befehle ausführen.

Das bedeutet:

Es kann auf alle Dateien zugreifen, auf die dein Benutzerkonto zugreifen kann
Der Umfang der Befehle, die es ausführen kann, ist genau derselbe wie der, den du manuell in einem Terminal ausführen würdest
esKein eingebauterSandbox-Isolationsmechanismus

Dies ist beabsichtigt – Pi Agent muss Projekt-Toolchains aufrufen, Tests ausführen und Abhängigkeiten installieren, was alles echte Systemberechtigungen erfordert.

Pi Agents Designphilosophie ist: keine halbgare Sandbox bereitzustellen, die "sicher aussieht, aber leicht missverstanden werden kann."
Echte Isolation sollte von der Betriebssystemebene oder von Virtualisierungs-/Container-Grenzen kommen.

Projektvertrauensmechanismus

Projektvertrauen steuert, ob Pi Agent projektlokale Konfiguration und Erweiterungen lädt.

Es ist keine Sandbox – es steuert nurwas beim Start geladen wird, und schränkt nicht ein, was das Modell während einer Konversation tun kann.

Wann wird eine Vertrauensprüfung ausgelöst?

Pi Agent löst eine Vertrauensprüfung aus, wenn er eines der folgenden Elemente im Projektverzeichnis erkennt:

.pi/settings.json (Projektkonfigurationsdatei)
.pi/extensions, .pi/skills, .pi/prompts, .pi/themes (Projektressourcenverzeichnisse)
.pi/SYSTEM.md oder .pi/APPEND_SYSTEM.md (Projekt-System-Prompts)
.agents/skills (Projekt-Skills-Verzeichnis)

Ein leeres .pi-Verzeichnis allein löst keine Vertrauensprüfung aus.

Vertrauensentscheidungsprozess

Pi Agent entscheidet in einer festen Reihenfolge, ob die Ressourcen des aktuellen Projekts geladen werden.

Prüfen, ob trust.json eine gespeicherte Entscheidung enthält (vom aktuellen Verzeichnis aus nach oben suchend)
Wenn ja, die gespeicherte Entscheidung verwenden
Wenn nicht, dem Verhalten der Einstellung defaultProjectTrust folgen (Standard: ask)
Nachdem der Benutzer eine Entscheidung getroffen hat, kann er "Remember" wählen, um sie in trust.json zu schreiben

Vertrauensentscheidungen werden pro Verzeichnis in der globalen ~/.pi/agent/trust.json gespeichert.

Bei der Suche wird sie Ebene für Ebene mit dieser Datei in den übergeordneten Verzeichnissen nach oben abgeglichen; nur wenn keine gespeicherte Entscheidung gefunden wird, wird auf die defaultProjectTrust-Logik zurückgegriffen.

Wenn Sie zum ersten Mal ein nicht vertrauenswürdiges Projekt betreten, zeigt die UI die folgende Aufforderung an:

检测到项目本地配置 .pi/settings.json
是否信任此项目并加载其配置与扩展？(y/n/always/never)

Der Prompt-Text und die Optionen können je nach Version variieren; maßgeblich ist die tatsächliche UI.

Projektvertrauen steuert nur das Laden geschützter Ressourcen wie Erweiterungen und Skills.
Kontextdateien wie AGENTS.md und CLAUDE.md werden unabhängig vom Vertrauensstatus geladen.

Einstellung defaultProjectTrust

Diese Einstellung bestimmt die Standardauswahl von Pi Agent, wenn niemand bestätigt; das Verhalten unterscheidet sich zwischen interaktivem und nicht-interaktivem Modus.

Wert	Verhalten im interaktiven Modus	Verhalten im nicht-interaktiven Modus
"ask" (Standard)	Eine Aufforderung zur Vertrauensbestätigung anzeigen	Projektressourcen nicht laden (Verhalten wie bei "never")
"always"	Automatisches Vertrauen	Automatisches Vertrauen
"never"	Automatisch ablehnen	Automatisch ablehnen

Konfigurationsmethode:

Beispiele

{
"defaultProjectTrust": "always"
}

Sie können das Verhalten pro Aufruf auch mit Befehlszeilenargumenten überschreiben:

# 本次运行信任项目
$ pi --approve
$ pi -a

# 本次运行不信任项目
$ pi --no-approve
$ pi -na

Verwenden Sie den Befehl /trust, um Entscheidungen zu speichern

Im interaktiven Modus können Sie jederzeit den Befehl /trust verwenden, um eine Vertrauensentscheidung für das aktuelle Projekt zu speichern:

/trust

Dieser Befehl schreibt in~/.pi/agent/trust.json, in der pro Verzeichnis gespeicherte Vertrauensentscheidungen abgelegt werden.

/trust speichert die aktuelle Entscheidung, lädt aber die aktuelle Sitzung nicht neu.
Wenn Sie eine Vertrauensentscheidung ändern, müssen Sie Pi Agent neu starten, damit die Änderung wirksam wird.

Sicherheitsüberlegungen für den nicht-interaktiven Modus

Im Print-Modus (-p), im JSON-Modus (--mode json) und im RPC-Modus (--mode rpc) zeigt Pi Agent keine Vertrauensaufforderungen an.

Das Verhalten hängt in diesem Fall vollständig von der Einstellung defaultProjectTrust ab:

Auf "ask" oder "never" gesetzt: Projektressourcen werden ignoriert
Auf "always" setzen: Projektressourcen werden geladen

Verwenden Sie --approve oder --no-approve, um dieses Verhalten vorübergehend zu überschreiben.

Ausführen von nicht vertrauenswürdigem Code

Wenn Sie mit nicht vertrauenswürdigen Repositories oder automatisierten Aufgaben umgehen müssen, wird empfohlen, Pi Agent in einem Container oder einer Sandbox auszuführen:

Pi Agent 安全分层：进程权限、项目信任、容器隔离与 Gondolin 微 VM

Container-Ansatz: Den gesamten pi-Prozess in einem Docker-Container oder einer VM ausführen
Gondolin-Ansatz: pi auf dem Host ausführen und die Ausführung von Tools in eine Gondolin-Micro-VM leiten
OpenShell-Ansatz: Den gesamten pi-Prozess in einer richtliniengesteuerten Sandbox von NVIDIA ausführen und Sandboxes über ein Gateway erstellen
Mount-Steuerung: Mounten Sie nur die Arbeitsverzeichnisse, auf die der Agent zugreifen muss
Anmeldeinformationsverwaltung: Vermeiden Sie das Mounten des Verzeichnisses ~/.pi/agent/ des Hosts; übergeben Sie einen temporären API-Schlüssel mit geringsten Rechten
Netzwerkisolierung: Wenn die Aufgabe keinen Netzwerkzugriff benötigt, schränken Sie das Netzwerk des Containers ein
Ergebnisüberprüfung: Überprüfen Sie Diffs und Änderungen, bevor Sie die Ausgabe zurück in ein vertrauenswürdiges System kopieren

Gondolin ist ein separates Open-Source-Micro-VM-Projekt (eine lokale Linux-Micro-VM, die QEMU-Unterstützung erfordert); Pi leitet die Ausführung integrierter Tools über eine Beispielerweiterung dorthin.

OpenShell überopenshell sandbox create --from piUm Sandboxes zu erstellen, müssen Sie zuerst ein Gateway registrieren und auswählen.

Der Remote-Gateway-Modus bindet lokale Verzeichnisse nicht per Bind-Mount ein; Sie müssen Upload-/Download-Befehle verwenden, um Dateien zwischen innerhalb und außerhalb der Sandbox zu übertragen. Modell-Anmeldeinformationen können außerhalb der Sandbox bleiben.

Wenn Sie das Arbeitsverzeichnis des Hosts mit Lese-/Schreibzugriff in den Container bind-mounten, wirken sich Schreibvorgänge im Container weiterhin auf Host-Dateien aus.
Wenn Sie strengeren Schutz benötigen, verwenden Sie schreibgeschützte Mounts oder kopieren Sie Dateien in die Sandbox hinein und aus ihr heraus.

Sicherheitstipps

Die folgenden Sicherheitsempfehlungen sind nach gängigen Nutzungsszenarien gegliedert; prüfen Sie sie, bevor Sie beginnen.

Szenario	Empfehlung
Überprüfen von Drittanbieter-Code	In einem Container mit schreibgeschützten Mounts ausführen
Automatisierte CI/CD	Temporäre Anmeldeinformationen verwenden und die Tool-Allowlist einschränken
Von Team gemeinsam genutzte Konfiguration	Verwenden Sie die .pi/settings.json des Projekts, aber legen Sie keine sensiblen Informationen darin ab
Installation von Erweiterungspaketen von Drittanbietern	Überprüfe den Quellcode vor der Installation; Erweiterungen können beliebigen Code ausführen
Installation von Skills von Drittanbietern	Überprüfe den Inhalt von SKILL.md; Skills können das Modell anweisen, beliebige Aktionen auszuführen

Weitere Erweiterungen

Referenz-Favoriten