Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Zusammenarbeiten und teilen

Codex mit einem Home-Verzeichnis auf NFS ausführen

Richte ein gemeinsames Codex-Home-Verzeichnis für die interaktive Arbeit auf mehreren Linux-Hosts ein.

Wenn mehrere Linux-Hosts ein Codex-Home-Verzeichnis (standardmäßig ~/.codex) über das Network File System (NFS) gemeinsam nutzen und gleichzeitig dieselbe SQLite-Datenbank im Write-Ahead-Logging-Modus (WAL) öffnen, können sie die Datenbank beschädigen. Für die interaktive Arbeit mit der CLI oder der Codex App über SSH migriere das gemeinsame Home-Verzeichnis. Speichere für unabhängige Batchjobs auf jedem Host das Codex-Home-Verzeichnis oder das SQLite-Verzeichnis auf einem lokalen Datenträger.

Warum NFS SQLite-Datenbanken beschädigen kann

Die Codex App und die Terminaloberfläche verwenden einen SQLite-Index, um Unterhaltungen aufzulisten. Die Datenbanken speichern außerdem Ziele und den Verarbeitungsstand von Erinnerungen. Auf lokalen Datenträgern verwendet Codex normalerweise den WAL-Modus. Prozesse auf verschiedenen Hosts können den Arbeitsspeicher, den WAL benötigt, nicht gemeinsam nutzen.

Wenn Codex unter Linux NFS erkennt, erstellt es Datenbanken im Rollback-Journal-Modus (DELETE). Dieser Modus verwendet Dateisperren. Migriere vorhandene WAL-Datenbanken, bevor du sie von einem anderen Host aus öffnest.

Codex speichert die Ereignisse einer Unterhaltung außerdem in rollout-*.jsonl-Dateien. Diese Dateien können schon vor der Migration auf NFS liegen, da zu jedem Zeitpunkt nur ein Prozess in die jeweilige Rollout-Datei schreibt. Bei der SQLite-Migration bleiben diese Dateien an ihrem Speicherort.

Ein vorhandenes Home-Verzeichnis auf NFS migrieren

1. Das gemeinsame Home-Verzeichnis prüfen

Führe codex --version auf jedem Host aus, auch auf allen SSH-Backends. Verwende eine Version, die codex migrate-nfs-db enthält, zum Beispiel Codex CLI 0.166.0. Prüfe, ob alle Hosts, die das gemeinsame Home-Verzeichnis nutzen, dasselbe SQLite-Verzeichnis verwenden. Bitte die Speicheradministration zu prüfen, ob eine Dateisperre auf einem Host eine damit unvereinbare Sperre auf dem anderen Host verhindert. Wenn das eingebundene Dateisystem dies nicht unterstützt, speichere die SQLite-Datenbanken lokal.

Während der Migration darfst du weder das SQLite-Home-Verzeichnis noch das Protokollverzeichnis festlegen oder ändern.

2. Codex auf allen Hosts beenden

Beende vor der Migration alle Clients

Beende laufende Dialogschritte und schließe die App und die CLI. Stoppe auch alle App Server auf Remote-Hosts, Hintergrunddaemons und geplanten Jobs, die dieses Home-Verzeichnis verwenden. Starte sie auf keinem Host erneut, bevor die Migration abgeschlossen ist. Schreibt gleichzeitig ein anderer Prozess in die Datenbank, kann er sie beschädigen. Dabei können Änderungen an Zielen oder Erinnerungen verloren gehen.

Sitzungs-Rollouts liegen in separaten Dateien. Mit ihnen lässt sich der Datenbankzustand nur teilweise wiederherstellen.

Im Daemon-Modus verbindet sich die CLI mit einem Hintergrundserver, der zwischen den Sitzungen weiterläuft. Sein Unix-Socket funktioniert nur auf dem Host, auf dem der Server gestartet wurde. Wenn mehrere Hosts ein Codex-Home-Verzeichnis über NFS gemeinsam nutzen, empfehlen wir, die CLI ohne Daemon auszuführen. Stoppe den Daemon auf jedem Host, auf dem er läuft, mit codex app-server daemon stop.

Damit die CLI den Daemon nicht erneut startet, setze daemon_auto_start auf false. Die Einstellung gehört in den Abschnitt [features] deiner gemeinsamen config.toml.

[features]
daemon_auto_start = false

Für eine einzelne CLI-Sitzung kannst du --no-daemon übergeben. Mit diesem Flag umgeht die CLI auch einen bereits laufenden Daemon.

3. Die Migration ausführen

Führe die Migration für jedes gemeinsame Codex-Home-Verzeichnis auf genau einem Linux-Host aus. Verwende das Konto, dem das Home-Verzeichnis gehört, und die für dieses Konto übliche Konfiguration. Starte Codex auf den anderen Hosts erst wieder, wenn die Migration abgeschlossen ist.

codex migrate-nfs-db

4. Eine Unterhaltung fortsetzen

Wenn der Befehl Skipped logs database meldet, prüfe den Speicherort der Protokolldatenbank. Liegt sie auf einem lokalen Datenträger, ist nichts weiter zu tun. Liegt sie auf NFS, vergewissere dich, dass sie den Journalmodus DELETE verwendet, oder verschiebe sie auf einen lokalen Datenträger, bevor du Codex auf einem anderen Host wieder öffnest.

Öffne nach erfolgreicher Migration dasselbe Projekt auf einem anderen Host mit demselben Benutzerkonto. Setze eine dir bekannte Unterhaltung in der App fort oder führe codex --no-daemon resume aus. Prüfe, ob dein letzter Dialogschritt vorhanden ist und du die Unterhaltung fortsetzen kannst.

Diagnoseprotokolle auf einen lokalen Datenträger verlagern

Optional, nach der Migration empfohlen. Diagnoseprotokolle helfen dir, Fehler und lange Startzeiten zu untersuchen. Wenn du die Protokolle lokal speicherst, reduzierst du den Datenverkehr über NFS.

Erstelle auf jedem Host ein privates Protokollverzeichnis, in das das jeweilige Benutzerkonto schreiben kann. Setze log_dir in der config.toml des Kontos auf den absoluten Pfad zu dessen Protokollverzeichnis. Für Alice könnte die Einstellung so aussehen.

log_dir = "/var/local/codex/alice/logs"

Codex schreibt neue Protokolle in dieses Verzeichnis. Ältere Protokolle bleiben an ihrem bisherigen Speicherort.

Wenn die verwaltete Konfiguration sqlite_home vorgibt, bleibt die SQLite-Protokolldatenbank auch dann im vorgeschriebenen Verzeichnis, wenn du log_dir festlegst. Weitere Informationen findest du in der Dokumentation zur verwalteten Konfiguration.

Den Journalmodus für eine Gruppe von Hosts erzwingen

Beende zuerst alle Clients auf jedem Host, der ein betroffenes Home-Verzeichnis verwendet. Der Name der Einstellung enthält unsafe, weil die Konvertierung eine Datenbank beschädigen kann, wenn währenddessen ein anderer Host in die Datenbank schreibt.

Sobald alle Clients beendet sind, füge die folgende Einstellung zur verwalteten Konfiguration der Hosts in /etc/codex/requirements.toml hinzu.

unsafe_enforce_sqlite_journal_mode = true

Die Einstellung gilt für alle Benutzerkonten auf den konfigurierten Hosts. Wenn jemand Codex das nächste Mal startet, migriert Codex vorhandene WAL-Datenbanken auf NFS automatisch, sobald es sie zum Schreiben öffnet. Warte bei jedem gemeinsamen Home-Verzeichnis, bis die Migration auf einem Host abgeschlossen ist, bevor du die anderen Hosts wieder verbindest. Wenn die Migration fehlschlägt, lass die anderen Clients beendet und folge den Schritten zur Wiederherstellung.

Unabhängige Batchjobs ausführen

Wenn ein unbeaufsichtigter Job den Verlauf deiner interaktiven Sitzungen nicht benötigt, führe codex exec mit einem Codex-Home-Verzeichnis auf dem lokalen Datenträger des Workers aus. Wenn die Sitzungsdateien auf NFS bleiben müssen, setze CODEX_SQLITE_HOME für jeden Job auf ein eigenes privates, lokales Verzeichnis. So konkurrieren die Worker nicht um dieselbe Datenbank.

  • Den Unterhaltungsverlauf aufbewahren. Weise jedem Job ein privates, dauerhaftes CODEX_HOME für seinen Rollout und ein privates CODEX_SQLITE_HOME auf dem jeweiligen Host für seine Datenbank zu. Der Worker verwendet einen eigenen Index, der von deinem interaktiven Index getrennt ist. Bewahre den Rollout unter $CODEX_HOME/sessions/ auf, wenn du den Job nach dem Beenden des Workers prüfen möchtest.
  • Nur das Ergebnis aufbewahren. Lege das Home-Verzeichnis des Jobs auf einem lokalen Datenträger ab und führe codex exec --ephemeral aus. Codex speichert dann keine Sitzung, die du später fortsetzen kannst. Verwende -o, um die abschließende Antwort dauerhaft in einer Datei zu speichern, oder --json, um Ereignisse fortlaufend an deinen Job-Runner zu senden.

Wenn ein Job einen Rollout benötigt, lass den Scheduler beide Verzeichnisse erstellen und die Authentifizierung und Konfiguration für das Home-Verzeichnis des Jobs bereitstellen. Ersetze die Beispielpfade durch das dauerhafte Codex-Home-Verzeichnis dieses Jobs und das lokale SQLite-Verzeichnis auf dem Worker. Ein über die verwaltete oder die sonstige Konfiguration festgelegtes sqlite_home hat Vorrang vor CODEX_SQLITE_HOME.

CODEX_HOME="/mnt/nfs/codex/jobs/job-1234" \
CODEX_SQLITE_HOME="/var/local/codex/jobs/job-1234" \
  codex exec "Summarize this repository's build steps."

Häufig gestellte Fragen

Woran erkenne ich, ob ein Fehler mit NFS zusammenhängt?

Ein Migrationsfehler wie cannot open source database exclusively bedeutet, dass Codex die Datenbank nicht sperren konnte. Auch auf einem lokalen Datenträger kann ein anderer Client diesen Fehler verursachen. Führe unter Linux findmnt -T "$DB_PATH" mit dem Pfad zur betroffenen Datenbank aus. Gibt der Befehl nfs oder nfs4 aus, prüfe auf allen Hosts, ob noch Prozesse in die Datenbank schreiben. Bitte die Speicheradministration zu prüfen, ob Dateisperren auf diesem eingebundenen Dateisystem hostübergreifend funktionieren. Beende die verbleibenden Clients, bevor du die Migration erneut versuchst.

Worauf sollte ich bei der Ausgabe der Migration achten?

Für jede Datenbank gibt Codex Migrated database: und WAL backup: oder Already in DELETE mode: aus. Wenn du auf Gruppenberechtigungen oder erweiterte Zugriffsregeln angewiesen bist, überprüfe diese nach der Migration, bevor du die Clients wieder startest.

Wenn log_dir bereits gesetzt war, überspringt der Befehl die Protokolldatenbank. Bevor du sie auf mehreren Hosts gemeinsam nutzt, vergewissere dich, dass sie DELETE verwendet, oder speichere sie weiterhin auf einem lokalen Datenträger.

Wenn du No databases found. siehst, prüfe das tatsächlich verwendete SQLite-Verzeichnis für das Benutzerkonto, dem das Home-Verzeichnis gehört. Reicht der lokale Speicherplatz für die temporären Dateien nicht aus, wähle auf dem Host ein lokales Verzeichnis mit ausreichend freiem Speicherplatz und übergib dessen absoluten Pfad mit --staging-dir.

Wie stelle ich die Daten nach einer fehlgeschlagenen Migration wieder her?

Lass die anderen Clients beendet. Halte die genaue Fehlermeldung, den Datenbankpfad und den ausgegebenen Sicherungspfad fest. Möglicherweise wurden einige Datenbanken bereits migriert. Bewahre die ursprüngliche Datenbank zusammen mit ihren Begleitdateien im zugehörigen Sicherungsverzeichnis auf. Wenn du ein Problem mit einer Dateisperre oder dem verfügbaren Speicherplatz behoben hast, führe codex migrate-nfs-db auf demselben Host erneut aus. Bei einem Integritätsfehler oder einer fehlenden Ersatzdatei arbeite zuerst mit Kopien, bevor du etwas wiederherstellst. Sitzungs-Rollouts können dir helfen, den Unterhaltungsverlauf zu rekonstruieren. Um Daten wiederherzustellen, die nur in SQLite gespeichert sind, etwa Ziele, brauchst du eine intakte Datenbank.

Bevor du eine separate CLI-Sitzung startest, vergewissere dich, dass die verwalteten Speichereinstellungen Schreibvorgänge nicht in das betroffene Home-Verzeichnis umleiten. Starte Codex dann mit einem temporären Verzeichnis auf einem lokalen Datenträger. Möglicherweise musst du dich für das neue Home-Verzeichnis anmelden.

recovery_home=$(mktemp -d /tmp/codex-nfs-recovery.XXXXXXXX) &&
  CODEX_HOME="$recovery_home" CODEX_SQLITE_HOME="$recovery_home" \
  codex --no-daemon --sandbox read-only \
    "Help me recover a failed Codex NFS migration, run `$ codex doctor` to get the information about corrupted databases. Backup paths for databases should be in the original database with `_wal_migration_backup` in the end of the file. Ask user for the original error. Plan a recovery using copies and leave the originals untouched."