ki-codex/04-fortgeschrittene-konfiguration.md

Kapitel 4

Fortgeschrittene Konfiguration – Hierarchie, Profiles und Trust

Kern in einem Satz: Config-Schichten und Project Trust entscheiden, was wirklich geladen wird – nicht der Wunsch im Chat und nicht die Datei, die du „irgendwo“ abgelegt hast.

---

4.1 Warum „meine Config greift nicht“

Szene: Du legst in .codex/config.toml approval_policy = "untrusted" ab. Die Session läuft trotzdem wie Auto. Drei mögliche Ursachen, eine Diagnose:

1. Project ist untrusted → Projekt-.codex/ wird ignoriert.
2. CLI-Flag oder Profile überschreibt die Projekt-Datei.
3. Du schaust in die falsche Datei (CODEX_HOME zeigt woanders hin).

Kapitel 2 hat weich vs. hart und die Auto-Matrix gelegt. Hier kommt die Schichtlogik: wer gewinnt, was Trust blockt, wie Profiles und Rules ergänzen – und wie Sessions den Zustand tragen.

{width=90%}

---

4.2 Precedenz: Flags → Project → Profile → User → System

Codex löst Werte in dieser Reihenfolge auf (höchste Precedenz zuerst):

Rang	Schicht	Typisch
1	CLI-Flags und -c / --config	einmaliger Override
2	Project .codex/config.toml	Root → CWD, näher gewinnt; nur trusted
3	Profile-Datei	~/.codex/<name>.config.toml via --profile
4	User ~/.codex/config.toml	persönliche Defaults
5	System /etc/codex/config.toml (Unix)	Org-Maschine
6	Built-in Defaults	falls nichts gesetzt

# Dedicated Flag, wenn vorhanden
codex --model gpt-5.6

# Beliebiger Key (Wert = TOML, nicht JSON)
codex -c sandbox_workspace_write.network_access=true
codex -c 'shell_environment_policy.include_only=["PATH","HOME"]'

Dot-Notation setzt nested Keys. Shell-Quoting beachten. Diagnose in der Session:

/status
/debug-config

/debug-config listet Layer-Reihenfolge und Policy-Quellen (u. a. erlaubte Approval-/Sandbox-Modi, wenn Managed greift).

CODEX_HOME: Default ~/.codex. Anderes Home = andere config.toml, andere History, andere User-Hooks/Rules unter diesem Home. Skills liegen separat unter ~/.agents/skills (Projekt: .agents/skills) – nicht unter CODEX_HOME (Kap. 5).

CODEX_HOME=$(pwd)/.codex-home codex

---

4.3 Project-Config und Trust

Trusted Project:

# .codex/config.toml  (nur wenn Project trusted)
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Codex lädt alle .codex/config.toml vom Projekt-Root bis zum CWD; bei gleichem Key gewinnt die nähere Datei. Relative Pfade in der Project-Config beziehen sich auf den jeweiligen .codex/-Ordner.

Untrusted: Codex überspringt Projekt-.codex/ – inkl. config.toml, project-local Hooks und Rules. User- und System-Layer bleiben aktiv. Das ist Absicht, kein Bug: fremdes Repo soll nicht still deine Policy umbiegen.

Achtung: Project-Config darf bestimmte host-nahe Keys nicht überschreiben. Codex ignoriert sie dort und warnt beim Start, u. a.: openai_base_url, chatgpt_base_url, model_provider, model_providers, notify, profile/profiles, otel, … Provider, Notifications und Telemetry gehören in User-Config; Profiles nur per --profile + ~/.codex/<name>.config.toml.

Beispiel-Repo: beispiele/configs/config.repo.example.toml. Permissions-Vorlage: vorlagen/config.permissions.toml.

Project root: Default Marker .git. Anpassen:

project_root_markers = [".git", ".hg"]
# project_root_markers = []  # kein Parent-Walk – CWD ist Root

---

4.4 Config-Profiles (nicht Permission Profiles)

Zwei „Profile“-Begriffe – nicht mischen:

Begriff	Was es ist	Auswahl
Config-Profile	benannte Abweichung der User-Config (Modell, Sandbox, Approvals, …)	--profile NAME → Datei ~/.codex/<name>.config.toml
Permission Profile	neuere Policy-Sprache für FS/Netz (default_permissions, [permissions.*], Built-ins :read-only, :workspace, :danger-full-access)	Config-Keys / Managed – siehe Permissions

Dieses Kapitel lehrt Config-Profiles als Alltags-Hebel. Permission Profiles komponieren nicht mit dem älteren sandbox_mode/sandbox_workspace_write: entweder das eine System oder das andere (Managed allowed_permission_profiles erzwingt die neue Seite). Buch-Defaults bleiben die klassische Matrix Sandbox × Approvals (Kap. 1–2).

Config-Profiles speichern benannte Abweichungen von der User-Baseline – z. B. Deep-Review (read-only + hohes Reasoning) vs. Alltag (Auto).

Ab Codex 0.134+ (Stand Docs Mitte/Ende 2026): Config-Profiles liegen als eigene Dateien, nicht mehr als [profiles.*] in config.toml:

# ~/.codex/deep-review.config.toml
model = "gpt-5.6"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "read-only"

codex --profile deep-review
codex exec --profile deep-review "review this change"

Profil-Namen: Buchstaben, Ziffern, Bindestrich, Unterstrich. Die Datei braucht nur die Keys, die von der Baseline abweichen. Legacy-[profiles.…] und top-level profile = "…" in config.toml sind abgelöst – bei Drift: Advanced-Config-Doku.

---

4.5 Rules (execpolicy) – Commands außerhalb der Sandbox

Rules steuern, welche Commands Codex außerhalb der Sandbox laufen darf – ergänzend zu Sandbox und Approvals. Feature ist experimental; Syntax kann driften. Primär: Rules.

Ablage: rules/*.rules neben aktiven Config-Layern, z. B. ~/.codex/rules/default.rules oder trusted <repo>/.codex/rules/. Sprache: Starlark mit prefix_rule(...).

# ~/.codex/rules/default.rules  (Beispiel – Syntax der aktuellen Doku prüfen)
prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "PR lesen ist ok, aber mit Approval",
    match = ["gh pr view 7888"],
    not_match = ["gh pr --repo your-org/your-repo view 7888"],
)

decision	Wirkung
allow	außerhalb der Sandbox ohne Prompt
prompt	jedes Mal fragen
forbidden	blocken

Bei mehreren Treffern gilt die strengste Entscheidung (forbidden > prompt > allow). Compound-Shell (bash -lc '…') wird, wo sicher, in Teilcommands zerlegt – git add . && rm -rf / wird nicht pauschal durch ein git add-Allow freigeschaltet.

Testen:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888

Smart Approvals können in der TUI prefix_rule-Vorschläge schreiben – Prefix eng reviewen, bevor du akzeptierst. Org-requirements.toml kann restriktive Rules erzwingen (Kapitel 6).

---

4.6 Writable roots, Shell-Env, Netzwerk (Kurz)

Workspace erweitern, ohne Full Access:

[sandbox_workspace_write]
writable_roots = ["/Users/YOU/shared-libs"]
network_access = false

CLI: oft --add-dir (Flags der aktuellen Version prüfen). Env an Subprozesse:

[shell_environment_policy]
inherit = "core"   # oder "none"
include_only = ["PATH", "HOME"]
exclude = ["AWS_*", "AZURE_*"]

Ziel: keine Secrets in Agent-Shells leaken, die du nicht brauchst. Netzwerk und network_proxy: Kapitel 2 und Approvals-Doku – Default bleibt eng.

---

4.7 Sessions und Persistenz

Befehl / Mittel	Zweck
codex resume / /resume	interaktive Session fortsetzen (--last, ID, --all)
codex fork / /fork	Abzweig mit frischer ID
codex archive / /archive	aus aktiven Listen; Transcript bleibt
codex unarchive	wiederherstellen
codex delete / /delete	permanent (mit Nachkommen)
/new, /clear	neuer Chat in derselben CLI
/compact	Kontext verdichten (verlustbehaftet – Kap. 7)
/rename	Session benennen

codex resume --last
codex archive <SESSION>

History unter CODEX_HOME (z. B. history.jsonl), wenn Persistence an ist:

[history]
persistence = "none"     # optional abschalten
# max_bytes = 104857600

tui.resume_cwd ("current" | "session") steuert, welches CWD bei Resume ohne Prompt gilt; explizites --cd schlägt das.

Kern: Session-State ist nicht Workspace-State. Archive/Delete und Compact ändern nicht magisch dein Git. Diff und git status bleiben Wahrheit.

---

4.8 Multi-Repo und Worktrees

• Ein CWD pro Session – Policy und AGENTS.md hängen am Ordner.
• Zweites Repo: neue Session oder extra writable root / Worktree, nicht „einfach Full Access“.
• IDE: oft /worktree für isolierte Git-Worktrees (Labels driftfähig).
• Fremde Clones: erst untrusted/read-only explorieren, Trust bewusst setzen.

---

So baust du das nach (Baseline)

1. User-Baseline in ~/.codex/config.toml (Auto: workspace-write + on-request).
2. Pro Repo: Root-AGENTS.md (Kap. 2) + optional trusted .codex/config.toml.
3. Ein Config-Profile deep-review (read-only + Effort) für Explain/Review – siehe 4.4.
4. Optional: ~/.codex/rules/ mit engen forbidden/prompt für destruktive Prefixes.
5. Verify: /status, /debug-config, ggf. codex execpolicy check.

Jetzt selbst machen

cd beispiele/todo-cli
# Project trust bestätigen (Kap. 1), dann:
mkdir -p .codex
cp ../../beispiele/configs/config.repo.example.toml .codex/config.toml
codex

/status
/debug-config

Erwartung: Workspace = todo-cli; Policy spiegelt Project- oder User-Layer. Danach:

codex --profile deep-review   # erst Datei anlegen, siehe 4.4

---

Häufige Fehler

Symptom	Ursache
Project-TOML wirkt nicht	untrusted; oder Flag/Profile überschreibt
Config-Profile „tot“	alte [profiles.]-Syntax; Datei name.config.toml fehlt; mit Permission-Profile-Keys verwechselt
Rules greifen nicht	falscher Layer; untrusted Project-Rules; Prefix unmatched
git commit fragt trotz workspace-write	.git oft protected – Rules/Approval, nicht „broken sandbox“
Falsches Home	CODEX_HOME / anderer User

Was du jetzt kannst

• Config-Precedenz skizzieren und mit /debug-config prüfen
• Project Trust als Schalter für .codex/-Layer erklären
• Config-Profiles als Datei-Layer anlegen und per --profile wählen (vs. Permission Profiles)
• Rules als Ergänzung außerhalb der Sandbox einordnen und testen
• Sessions (resume/fork/archive/delete) und History-Schalter bedienen
• Multi-Repo ohne pauschales Full Access steuern

Nächste Schritte

• Kapitel 5: MCP, Skills, Hooks, Subagents, Plugins
• Kapitel 6: Managed requirements, CI, Cloud
• Vorlagen: vorlagen/config.permissions.toml, beispiele/configs/

Primärquellen: Config basics, Advanced config, Rules, Approvals & security.