ki-codex/02-grundlagen-und-konfiguration.md

Kapitel 2

Grundlagen und Konfiguration – AGENTS.md und Sandbox/Approvals

Kern in einem Satz: Weiches Memory (AGENTS.md) und harte Policy (Sandbox × Approvals) sind zwei verschiedene Hebel – verwechsle sie nicht.

---

2.1 Szene: „sollte nicht“ vs. „darf nicht“

Dienstag, erstes Ticket im neuen Repo: „Bitte Tests grün machen.“ Codex tippt npm test. Dein Stack ist Python mit pytest. Fünf Minuten rote Logs, dann rät der Agent poetry run pytest – und mittendrin liegt schon eine „hilfreiche“ package.json im Diff.

Nichts davon war böse Absicht. Ohne Projektwissen rät das Modell den häufigsten Stack aus dem Training. Command-Halluzination: ohne oder mit leeren Instructions schlägt der Agent den Stack vor, den er aus dem Training am häufigsten kennt – nicht den aus deinem Repo. Der Harness führt aus, was technisch erlaubt ist – und du siehst entweder rote Logs oder, schlimmer, „erfolgreiche“ Änderungen am falschen Stack.

Zwei Hebel teilen die Arbeit:

Hebel	Rolle	Wirkung
AGENTS.md (weich)	Memory in Markdown, reviewbar im Git	Build/Test, Layout, „immer/nie“ – steuert über Kontext
Sandbox × Approvals (hart)	OS-Boundary + wann der Agent fragt	Schreiben, Netzwerk, Escapes – steuert über den Harness

{width=90%}

Kern: „Sollte nicht“ → AGENTS.md. „Darf nicht“ → Sandbox, Approval-Policy, Rules oder Hooks. Die Verwechslung ist der häufigste Config-Fehler: weiche Wünsche an harte Risiken.

{width=90%}

Kurze, prüfbare Sätze im Memory statt Roman: Je vager die Dateien, desto breiter rät das Modell – und desto teurer wird der Diff.

Project Trust (Kapitel 1) ist die grobe Tür: Projekt-.codex/ lädt nur, wenn du dem Ordner vertraust. Dieses Kapitel füllt die nächste Schicht: was der Agent wissen soll (AGENTS.md) und was er dürfen soll (sandbox_mode × approval_policy).

---

2.2 Weich: AGENTS.md und Overrides

AGENTS.md ist natürliche Sprache in Markdown. Codex liest sie vor der Arbeit und legt sie als Kontext – du tippst „Tests: pytest -q“ einmal ins Repo und sparst dir den Satz in jedem Prompt.

{width=90%}

Stand der Fakten: Mitte/Ende 2026. Primär: Custom instructions with AGENTS.md. UI-Details und exakte Labels können driften; das Konzept bleibt: Discovery baut eine Kette, näher am CWD gewinnt inhaltlich durch Reihenfolge im Prompt.

Discovery: global → root → cwd

Codex baut die Instruction-Kette einmal pro Run (in der TUI typisch einmal pro gestarteter Session):

1. Global unter Codex-Home (Default ~/.codex, overridebar mit CODEX_HOME): zuerst AGENTS.override.md, sonst AGENTS.md – eine nicht-leere Datei auf dieser Ebene.
2. Projekt: vom Projekt-Root (meist Git-Root) abwärts bis zum aktuellen Arbeitsverzeichnis. Pro Verzeichnis: AGENTS.override.md, sonst AGENTS.md, sonst ein Name aus project_doc_fallback_filenames. Höchstens eine Datei pro Verzeichnis.
3. Merge: Dateien von der Wurzel abwärts, mit Leerzeilen verbunden. Dateien näher am CWD erscheinen später und überschreiben faktisch frühere Guidance.

Leere Dateien werden übersprungen. Die kombinierte Größe stoppt bei project_doc_max_bytes – Default 32 KiB. Limit anheben oder Anweisungen auf nested Verzeichnisse verteilen, wenn du den Cap triffst.

~/.codex/AGENTS.md                 # persönliche Defaults (alle Repos)
repo/AGENTS.md                     # Team-Baseline im Git
repo/services/payments/AGENTS.override.md   # Scope-Override nur hier

Startest du in services/payments/, lädt Codex typisch: global → Root-AGENTS.md → Payments-Override. Die Override-Datei ersetzt in diesem Verzeichnis die reguläre AGENTS.md (falls beide existieren).

{width=90%}

Was rein gehört – und was raus

Minimum – und oft genug:

# Projekt-Kompass

## Build & Test

- Install: `pip install -e ".[dev]"`
- Tests: `pytest -q`
- Lint: `ruff check .` (wenn im Repo)

## Layout

- App-Code unter `todo/`, Tests unter `tests/`
- Keine Secrets committen

## Immer

- Vor Commit: Tests grün
- Diff kurz zusammenfassen

## Nie

- Secrets in Dateien oder Commits
- `rm -rf` auf Projektwurzel oder Home
- Force-Push auf `main`/`master`
- Production-Deploy aus der Agent-Session

Was rein gehört:

• Build / Test / Lint – besonders nicht-offensichtliche Commands
• Layout in 5–15 Zeilen (Orientierung, kein Dateibaum-Roman)
• 2–3 Immer / Nie (prüfbar, wiederkehrend)
• Gotchas („Tests brauchen lokales Redis“)

Was raus gehört:

• Generische Floskeln („schreib sauberen Code“)
• 200-Zeilen-Dateibaum (veraltet, frisst Kontext)
• Lange Tutorials (besser Skill oder Verweis auf docs/…)
• Harte Verbote, die technisch greifen müssen – die gehören in Sandbox, Approvals, Rules oder Hooks

Vorlagen:

• Stabile Kernfassung im Buch: Anhang A
• vorlagen/AGENTS.md.minimal.md
• vorlagen/AGENTS.md.team.md

Vollständig und aktuell: Begleit-Service → Material → vorlagen.zip. Im Beispielprojekt: beispiele/todo-cli/AGENTS.md.

Global vs. Projekt

Persönliche Gewohnheiten – Ton, generische Git-Hygiene – gehören nach ~/.codex/AGENTS.md, nicht den Test-Command dieses Repos:

~/.codex/AGENTS.md          # User-weit
~/dein-repo/AGENTS.md       # Team-geteilt über Git

Repo-Fakten ins Git; User-Prefs lokal. Sonst committest du deine Tastatur-Vorlieben und der Kollege bekommt deinen Editor-Stil als „Team-Policy“.

Temporärer globaler Override ohne die Basis zu löschen:

~/.codex/AGENTS.override.md

Entfernen = zurück zur normalen AGENTS.md.

Fallback-Dateinamen und Byte-Cap

Wenn das Repo schon TEAM_GUIDE.md o. Ä. nutzt:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Pro Verzeichnis prüft Codex dann: Override → AGENTS.md → Fallbacks in Listenreihenfolge. Dateien nicht auf der Liste bleiben für die Discovery unsichtbar.

Achtung: Truncation ist eine echte Fehlerklasse. Bei 32 KiB Default werden spätere Dateien ggf. abgeschnitten oder gar nicht mehr geladen – kritische Regeln gehören nach vorne und kurz, oder du hebst das Limit an und splitest nested.

/init – Generator, kein Source of Truth

/init

Erzeugt ein AGENTS.md-Gerüst im aktuellen Verzeichnis (Repo-Root oder Subdir). Danach: lesen, kürzen, halluzinierte Commands streichen, speichern. Source of Truth ist die Datei nach deinem Review – nicht der Generator-Lauf.

CLI-Alternative zum Prüfen der geladenen Guidance (ohne Projekt zu ändern):

codex --ask-for-approval never "Summarize the current instructions."

Erwartung: Codex zitiert globale und projektbezogene Punkte in der Discovery-Reihenfolge. Nested Overrides:

codex --cd services/payments --ask-for-approval never \
  "List the instruction sources you loaded."

Session-Audit (wenn nötig): /status für Workspace und Policy; bei tieferem Debug codex -c log_dir=./.codex-log bzw. codex debug prompt-input (Doku). Die Kette wird pro Run neu gebaut – es gibt keinen manuellen „Instruction-Cache“ zum Leeren; bei Zweifel Session neu starten.

Jetzt selbst machen

cd beispiele/todo-cli
# AGENTS.md ist schon da – oder Vorlage:
# cp ../../vorlagen/AGENTS.md.minimal.md ./AGENTS.md

codex

In der Session:

Welche Test- und Install-Commands gelten in diesem Repo?
Nenne sie wörtlich aus den Instructions. Ändere nichts.

Wenn die Antwort npm test ist, greifen die Dateien nicht oder der CWD stimmt nicht – Fix: Datei, Verzeichnis, Session neu.

---

2.3 Hart: Sandbox × Approvals

Instructions bitten. Sandbox und Approvals erzwingen (soweit der Harness greift). Ein eloquenter Prompt ändert kein read-only und kein never.

In Kapitel 1 hast du Auto vs. Read-only vs. Full Access am Dialog geübt. Hier die Defaults in config.toml, die strengere Shell-Seite und was Netzwerk und Profiles dazu tun.

Zwei Achsen, eine Entscheidung

Du willst festnageln, was die Session technisch darf – und wann Codex dich fragt. Zwei Config-Keys steuern das:

Achse	Frage	Typische Werte
sandbox_mode	Was dürfen gespawnte Commands technisch?	read-only · workspace-write · danger-full-access
approval_policy	Wann muss Codex dich fragen?	untrusted · on-request · never

Die Sandbox gilt für ausgeführte Commands (inkl. git, Package Manager, Test-Runner) – nicht nur für eingebaute File-Tools. Approvals greifen, wenn der Agent die Boundary verlassen will, Netzwerk braucht oder Tools mit Side-Effects anstößt (auch App/MCP mit destruktiver Annotation).

Auto / Read-only / Full Access wie in Kapitel 1.6 – hier die neuen Ränder:

Intent	Config / Flags	Effekt
Strenger shell-seitig	workspace-write + approval_policy = "untrusted"	Edits ok; untrusted Commands fragen
CI read-only	read-only + never	nur lesen, keine Prompts
Extra-Schreiborte	writable_roots / --add-dir	enger als Full Access
Full Access / YOLO	--yolo / danger-full-access + never	Ausnahme in Isolation – nicht Default

Alltags-Default bleibt Auto: workspace-write + on-request (siehe TOML unten und Kapitel 1).

In der Session:

/permissions

Wechselt Presets (z. B. Auto vs. Read Only) bzw. benannte Permission-Profiles, wo konfiguriert. Writable Roots und aktives Setup: /status.

Defaults in config.toml

User-Defaults:

# ~/.codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"
# model = "gpt-5.6"   # je Kontingent/Org

Projekt-Overrides (nur wenn Project trusted):

# .codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Kommentierte Startvorlage: vorlagen/config.permissions.toml. Stabile Kernfassung: Anhang A.

Precedenz (kurz; Detail Kapitel 4): CLI-Flags und -c → trusted Project-.codex/config.toml (Root → CWD, näher gewinnt) → Profile (--profile) → ~/.codex/config.toml → System → Built-ins. Untrusted Project = keine Projekt-.codex/-Layer (Config, Hooks, Rules).

Netzwerk und geschützte Pfade

Default bei workspace-write: Netzwerk aus. Anschalten nur bewusst:

[sandbox_workspace_write]
network_access = true

Web-Suche ist ein eigenes Tool und default oft cached (Index, weniger Live-Injection-Fläche) – das ist nicht dasselbe wie freies Command-Netzwerk. Live-Suche und Full Access vergrößern die Angriffsfläche (Prompt Injection über untrusted Content). Details und Domain-Allowlists: Agent approvals & security.

In writable Roots bleiben u. a. geschützt (read-only, rekursiv):

• <root>/.git (und aufgelöster gitdir, wenn Pointer-Datei)
• <root>/.agents (falls Verzeichnis)
• <root>/.codex (falls Verzeichnis)

Approval in der Session

Wenn Codex fragt (Formulierungen driftfähig):

Wahl	Bedeutung
Einmal / Yes	dieses Mal erlauben
Session-Scope (wo angeboten)	Rest der Session freigeben – bequem und riskant
Ablehnen + Feedback	steuern: „Nein, nutze pytest -q vom Repo-Root“

Achtung: Session-weite Freigaben für destruktive Pfade (rm, weitreichende Shell, unkontrolliertes Netzwerk) sind der Klassiker „erst harmlos, dann ohne erneute Frage“. Freigabe-Scope so eng wie möglich.

Optional (Doku, Feature-Drift prüfen): approvals_reviewer = "auto_review" leitet eligible Approval-Requests an einen Reviewer-Agenten – die Sandbox-Boundary ändert sich dadurch nicht. Wer reviewt, ist eine andere Frage als was technisch erlaubt ist.

Permission Profiles vs. sandbox_mode

Codex kennt zusätzlich benannte Permission Profiles (Built-ins u. a. :read-only, :workspace, :danger-full-access; Custom unter [permissions.<name>], Default über default_permissions). /permissions kann Presets und Profiles mischen.

Kern: Profiles und die klassischen Keys sandbox_mode / approval_policy beschreiben ähnliche Intent-Ebenen – nicht wild mischen, ohne die effektive Policy zu prüfen (/status, /debug-config). Bei Drift: Konzept behalten, Syntax der Permissions-Doku und Config-Reference folgen.

Rules (Command-Prefix allow/prompt/forbid) und Hooks vertiefen Kapitel 4 und 5 – oft besser als pauschal Full Access.

Full Access und --yolo

# NICHT als Alltags-Default
codex --dangerously-bypass-approvals-and-sandbox
# alias: --yolo

Entspricht faktisch sandbox_mode = "danger-full-access" plus approval_policy = "never". Sinnvoll höchstens in isolierten Umgebungen (eigene VM, enger Container, Wegwerf-Clone) – nicht auf dem Alltags-Laptop mit SSH-Keys und Prod-Zugang.

Sandbox lokal testen

# macOS
codex sandbox macos [--log-denials] -- <COMMAND>
# Linux
codex sandbox linux -- <COMMAND>

Hilft zu verstehen, was die Boundary blockt, bevor du sie erweiterst.

Jetzt selbst machen (hart)

cd beispiele/todo-cli
codex --sandbox workspace-write --ask-for-approval on-request

Prompt:

Führe pytest -q aus und fasse das Ergebnis in drei Zeilen zusammen.
Schreibe keine Dateien.

Dann /permissions auf Read Only stellen und denselben Auftrag – beobachte, wo Approval oder Ablehnung greift. Optional: absichtlich etwas außerhalb des Workspace anfordern und ablehnen.

---

2.4 Faustregel und Checkliste

Aussage	Mittel
„Sollte nicht force-pushen“	AGENTS.md (Nie-Liste)
„Darf nicht außerhalb des Workspace schreiben“	sandbox_mode = "workspace-write" / read-only
„Darf pytest ohne Rückfrage im Workspace“	Auto: workspace-write + on-request
„Nie ohne Nachfrage untrusted Commands“	approval_policy = "untrusted" (ggf. enger Sandbox)
„YOLO für diesen Task“	nur mit engem Scope, ideal isolierte Umgebung – und nach enger Baseline

Vier Hebel in diesem Kapitel (kurz):

1. Scope eng – kurze AGENTS.md, Override nur wo nötig
2. Diff lesen – bevor du freigibst, was der Agent „nur schnell“ geschrieben hat
3. Enge Sandbox + Approvals vor Full Access – Auto zuerst; --yolo Ausnahme
4. Weich vs. hart – bitten in Markdown, Boundary im Harness

Checkliste „Tag-2-Config sitzt“

• Root-AGENTS.md mit Build/Test + 2–3 Immer/Nie
• optional nested AGENTS.override.md für Hot-Paths
• „Summarize instructions“ / Session-Prompt zeigt die erwarteten Commands
• sandbox_mode + approval_policy in User- oder trusted Project-Config
• Kein dauerhaftes YOLO-Alias
• Nach großen Memory-Edits: neue Session, wenn das Verhalten „alt“ wirkt
• Project Trust bewusst – sonst greift .codex/ nicht

Häufige Fehler

Symptom	Typische Ursache
Agent nutzt npm test im Python-Repo (Command-Halluzination)	AGENTS.md fehlt, leer, truncated oder falscher CWD
„Ich habe es in die Datei geschrieben, er ignoriert es“	Override höher/näher; leere Datei; Cap; untrusted Project für Config-Erwartung
Project-Config greift nicht	Project untrusted – Kapitel 1
Zu viele Approval-Prompts	engere Alltags-Commands in AGENTS.md; Auto-Preset; bewusste Session-Scopes
Ungewollte Weite	Session-Scope auf destruktive Pfade oder --yolo ohne Isolation
Widersprüchliche Rules	Global „npm“ vs. Repo „pytest“ – Kette lesen, kürzen

---

Was du jetzt kannst

• Die Trennlinie weich (AGENTS.md) vs. hart (Sandbox × Approvals) erklären und anwenden
• Discovery (global → root → cwd), Override und Byte-Cap skizzieren
• Kurze, prüfbare Project-Instructions anlegen und mit einem Verify-Prompt prüfen
• /init als Generator (nicht Source of Truth) einordnen
• Sandbox-Modi und Approval-Policies als Alltags-Defaults setzen
• Defaults in config.toml setzen und wissen, dass Project-Layer Trust brauchen
• Netzwerk-Default, protected paths und das YOLO-Risiko benennen
• Permission Profiles nicht blind mit sandbox_mode vermischen

Nächste Schritte

• Kapitel 3 – Alltag und Workflows: Explore → Plan → Code → Verify → Commit, /plan, /review, Modelle
• Kapitel 4: Config-Hierarchie, Profiles, Rules, Sessions
• Vorlagen kopieren und im eigenen Repo anpassen – nicht ungelesen committen (Kern: Anhang A; voll: Begleit-Service → Material)

Primärquellen: AGENTS.md, Sandboxing, Agent approvals & security, Config basics, Developer commands.