ki-codex/08-anhang-cheatsheets.md

Kapitel 8

Anhang – Cheatsheets, Vorlagen-Index und Glossar

Kern: Spickzettel zum Nachschlagen beim Arbeiten im echten Repo – nicht zum linearen Lesen statt der Kapitel 0–7.

So nutzt du den Anhang: Beim Arbeiten offen halten. Flag, Slash-Command oder Pfad nachschlagen → bei Unklarheit ins Kapitel springen. codex --help, / in der TUI und die Primärdoku sind Source of Truth – dieser Anhang ist eine Kernmenge (Stand Mitte/Ende 2026).

Hybrid: Syntax und Slash-Labels hier können driften. Stabile Kernvorlagen (kopierfertige Minima, Rituale, Approval-Faustregeln) stehen in Anhang A. Vollständige und laufend aktualisierte Materialien: Begleit-Service → Material.

---

8.1 Install & Auth (Spickzettel)

Plattform / Weg	Befehl (prüfen)
Standalone (macOS/Linux)	curl -fsSL https://chatgpt.com/codex/install.sh | sh
Windows (PowerShell)	irm https://chatgpt.com/codex/install.ps1 | iex
npm	npm install -g @openai/codex
Homebrew	brew install --cask codex · Update: brew upgrade --cask codex
Version	codex --version
Diagnose	codex doctor
Hilfe	codex --help

# Interaktiv (ChatGPT-Browser-Flow)
codex login
codex login status
codex logout

# API-Key lokal
printenv OPENAI_API_KEY | codex login --with-api-key

# Headless / CI: Key nur an die eine Invocation
CODEX_API_KEY=YOUR_TOKEN codex exec --sandbox read-only "Summarize the repo structure"

In der Session oft: /logout (Verfügbarkeit: / tippen). Details: Kapitel 01, 06.

---

8.2 Slash-Commands (Kernmenge)

Slash-Commands steuern den Harness (Session, Policy, Diagnose) – nicht „das Modell umstimmen“.

Command	Zweck	Wann typisch
/ (leer) / Hilfe	verfügbare Commands	Einstieg, unbekannter Befehl
/status	Model, Policy, writable roots, Usage-Hinweise	Diagnose, Trust-Check
/debug-config	Config-Layer und Policy-Quellen	„greift nicht“
/permissions	Presets (Auto / Read Only / …)	Policy in der Session
/init	AGENTS.md generieren	neues Repo; Ergebnis reviewen
/plan	Plan Mode	multi-file / unklare Architektur
/diff	Änderungen prüfen	vor Commit / „fertig“
/review	agentic Code Review	vor Commit/PR
/compact	History verdichten	Fenster voll; Datei-Anker vorher
/new, /clear	neuer Chat	Themenwechsel
/resume	Session fortsetzen	gestern weitermachen
/fork	Session abzweigen	paralleler Ansatz
/archive, /delete	aufräumen / permanent löschen	Hygiene (Delete = endgültig)
/rename	Session benennen	Resume-Picker
/usage	Kontingent / Aktivität	Budgets
/mcp	MCP-Server	Server-Status
/skills	Skills durchsuchen/einbinden	Team-Workflows
/hooks	Hooks ansehen / Trust-Review	Guardrail-Debug
/agent / /subagents	Subagent-Threads	Spezial-Rolle, Isolation
/plugins	Plugins	Bundle verwalten
/mention / @pfad	Datei in den Kontext	Fokus setzen
/worktree	isolierter Git-Worktree	parallel (IDE/Labels driftfähig)
/fast	Fast-Service-Tier toggeln	Tempo vs. Qualität
/personality	Kommunikationsstil	ohne Instructions umzuschreiben
/logout	abmelden	Auth wechseln

Eingabe-Präfixe (Konzept):

Prefix	Bedeutung
@pfad	Datei/Ordner in den Kontext
!befehl	Shell ohne Modell-Umweg (wo unterstützt)

Compact-Fokus (Beispiele)

/compact

Vorher Entscheidungen in PLAN.md / Issue / Commit-Message sichern – Compact ist verlustbehaftet (Kap. 7).

Vollständige und aktuelle Liste: / in der TUI und Developer commands. Session-Steuerung: Kapitel 04, 07.

---

8.3 CLI-Flags & Subcommands

Häufige Start-Flags

Flag	Zweck
--sandbox read-only / workspace-write / danger-full-access	technische Boundary
--ask-for-approval untrusted / on-request / never	wann Codex fragt
--dangerously-bypass-approvals-and-sandbox / --yolo	kein Sandbox, keine Approvals – Ausnahme
--model NAME	Modell setzen
--profile NAME	~/.codex/<name>.config.toml
-c / --config KEY=VALUE	einmaliger Config-Override (TOML-Wert)
--cd / -C DIR	Working Directory
--add-dir	zusätzlicher writable root (Flag der Version prüfen)
--ephemeral	(v. a. exec) keine Session-Persistenz

# Alltag lokal (Auto-Preset)
codex --sandbox workspace-write --ask-for-approval on-request

# Nur erklären
codex --sandbox read-only --ask-for-approval on-request

# Einmaliger Key-Override
codex -c sandbox_workspace_write.network_access=true
codex -c 'shell_environment_policy.include_only=["PATH","HOME"]'

Subcommands (Auswahl)

Befehl	Zweck
codex	interaktive TUI
codex exec / codex e	non-interactive
codex resume / fork / archive / unarchive / delete	Sessions
codex mcp add / list / login	MCP
codex review	Review-Lauf (--untrusted, --base …)
codex cloud / cloud list / cloud exec	Cloud-Tasks
codex apply	Cloud-Diff lokal – nach Review
codex plugin …	Marketplace / Plugins
codex execpolicy check	Rules testen
codex sandbox macos / linux	OS-Sandbox um fremden Command
codex doctor	Install-/Runtime-Diagnose
codex login / logout	Auth

codex exec (CI / Skripte)

codex exec "Summarize risky areas. No file changes."
codex exec --sandbox workspace-write "Fix the failing unit tests only."
codex exec --json "List top 5 risks" | tee codex-events.jsonl
codex exec -o summary.md "Draft release notes for last 10 commits"
codex exec --profile deep-review "review this change"
codex exec resume --last "Continue with the plan."

Flag / Muster	Nutzen
--ephemeral	keine Session-Rollouts
--ignore-user-config	ohne $CODEX_HOME/config.toml
--ignore-rules	ohne User/Project-Rules
--output-schema schema.json	strukturiertes JSON
codex exec -	gesamter Prompt von stdin
--skip-git-repo-check	nur wenn Env wirklich safe

Details: Kapitel 06, Non-interactive mode.

---

8.4 Dateipfade (User / Repo)

Merksatz: Repo teilen und reviewen; User lokal; Project-.codex/ nur bei Trust; Managed/Org gewinnt bei Policy.

Was	Wo
Codex-Home	~/.codex (override: CODEX_HOME)
User config	~/.codex/config.toml
User AGENTS	~/.codex/AGENTS.md bzw. AGENTS.override.md
Profiles	~/.codex/<name>.config.toml
User skills	~/.agents/skills/**/SKILL.md (nicht unter CODEX_HOME)
User hooks	~/.codex/hooks.json / [hooks] in User-config
User rules	~/.codex/rules/*.rules
User agents	~/.codex/agents/
Project config	trusted .codex/config.toml (Root → CWD, näher gewinnt)
Project AGENTS	Root AGENTS.md / AGENTS.override.md (+ nested Kette)
Project skills	.agents/skills/**/SKILL.md (Kette CWD → Repo-Root)
Project hooks	trusted .codex/hooks.json
Project rules	trusted .codex/rules/
History	unter CODEX_HOME (z. B. history.jsonl)
System (Unix)	/etc/codex/config.toml

Config-Precedenz (höchste zuerst): CLI-Flags / -c → trusted Project-.codex/ → Profile (--profile) → User config.toml → System → Built-ins.

Untrusted Project = keine Projekt-.codex/-Layer (Config, Hooks, Rules). Diagnose: /status, /debug-config.

Kapitel 02, 04.

---

8.5 Sandbox × Approvals

Zwei Hebel – nicht verwechseln:

Key / Flag	Bedeutung	Werte (Kern)
sandbox_mode / --sandbox	Was dürfen Commands technisch?	read-only · workspace-write · danger-full-access
approval_policy / --ask-for-approval	Wann fragt Codex?	untrusted · on-request · never

Preset (Alltag)	Typisch
Auto	workspace-write + on-request
Read-only	read-only + on-request
CI read-only	read-only + never
Full Access / YOLO	bypass Sandbox+Approvals – nur isoliert

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

codex --sandbox workspace-write --ask-for-approval on-request
# Ausnahme, nicht Default:
# codex --yolo

Writable roots ohne Full Access:

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

Interaktiv: Yes · Session-Scope · ablehnen + Feedback. Session-Scope freigibt oft das Tool, nicht nur den einen harmlosen Pfad – bei rm/Push lieber einmalig freigeben oder ablehnen.

Minimale kopierfertige Baseline: Anhang A.3. Kapitel 01, 02.

---

8.6 Explore → Plan → Code → Verify → Commit

Kanon (drift-resistent, 6 Schritte): Anhang A.5 – Explore → Plan → Code → Verify → Diff → Commit. Unten dieselbe Reihenfolge als Spickzettel mit typischen Session-Commands (Labels können driften; / in der TUI):

1. Explore:  „Erkläre X. Ändere nichts.“
2. Plan:     strukturieren – noch kein Produktiv-Code  (/plan)
3. Review:   Plan lesen, anpassen, freigeben
4. Code:     „Setze den freigegebenen Plan um – nicht mehr.“
5. Verify:   Test-Command aus AGENTS.md / Verify-Skill
6. Diff:     menschlich lesen  (/diff oder git diff)
7. Optional: /review (Bugs/Security)
8. Commit:   erst nach Diff; Merge bleibt menschlich

Mittel	Kurz
/plan	strukturierter Plan vor Code (optional zu A.5-Schritt 2)
/diff	Workspace-Änderungen prüfen (A.5-Schritt Diff)
/review / codex review	agentic Review-Filter
/permissions Read Only	Explore ohne Edit-Pfad
Cloud / codex apply	async Isolation; Diff vor Apply

Kapitel 03; kopierfertiges Ritual ohne Slash-Pflicht: A.5.

---

8.7 MCP / Skills / Hooks / Agents / Plugins

Bedarf	Mittel	Härte
Immer gültige Normen	AGENTS.md	weich
Wiederholbarer Task on-demand	Skill (SKILL.md)	weich, gezielt
Neue externe Fähigkeiten	MCP	Angriffsfläche
Erzwingen / Guardrail	Hook / Rules	hart
Spezial-Persona / Isolation	Subagent / Custom agent	Isolation
Bundle verteilen	Plugin	review vor Trust
OS-Boundary	Sandbox × Approvals	Boundary
Org-Zwang	Managed requirements.toml	Org

/mcp
/skills
/hooks
/agent
/plugins

codex mcp list
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex plugin list

Kapitel 05.

---

8.8 Symptom → Fix (Kurz)

Symptom	Typischer Fix
Project-Config greift nicht	Trust; /status
Config-Profile wirkt nicht	~/.codex/name.config.toml + --profile (nicht Permission-Profile-Keys)
npm test im Python-Repo	AGENTS.md / CWD / Cap
Zu viele Approvals	Auto-Preset; Rules allow eng
Zu wenige / Überraschungen	zurück on-request; Session archive
MCP-Tool fehlt	codex mcp list; login; logs
Hook silent	/hooks; [features].hooks
Antworten matschig	/compact + Datei-Anker; /new
CI leakt Key	Key nur am Exec-Step; Action-Proxy (Glossar)
Managed blockt Config	/debug-config; Org-Runbook, nicht YOLO
Cloud-Diff zerstört lokal	Diff lesen vor codex apply

Diagnose in 5 Minuten: pwd → /status → /debug-config → Instructions-Summary → codex doctor → dann Config umbauen.

Volles Raster: Kapitel 07.

---

8.9 Vorlagen- und Beispiel-Index

Zuerst im Buch: Anhang A – Stabile Kernvorlagen (A.1–A.7, kopierfertig, drift-resistent).

Vollständig und aktuell: Begleit-Service → Material (vorlagen.zip, beispiele.zip): https://books.maatini.space/projects/codex-harness/. Dort auch Stand & Drift, Errata, Schnelle Hilfe. ZIP entpacken, dann beispiele/… bzw. vorlagen/….

Bedarf	Im Buch	Online / Repo
Minimale Repo-AGENTS.md	A.1	vorlagen/AGENTS.md.minimal.md
Team-AGENTS.md	A.1 (Team)	vorlagen/AGENTS.md.team.md
User-AGENTS.md	A.2	vorlagen/user/
Sandbox × Approvals	A.3	vorlagen/config.permissions.toml
MCP-Snippet	A.4	vorlagen/config.mcp.toml
Ritual Plan/Verify	A.5	vorlagen/PLAN.md.skeleton.md
Approval-Faustregeln	A.6	Kap. 1–2
todo-cli Start	A.7	beispiele/todo-cli/
Skills / Hooks / Agents / Plugin / CI	—	vorlagen/, beispiele/configs/

Vorlage / Beispiel	Ziel im echten Projekt
vorlagen/AGENTS.md.minimal.md	Repo-Root AGENTS.md (solo)
vorlagen/AGENTS.md.team.md	Repo-Root AGENTS.md (Team)
vorlagen/user/AGENTS.md	~/.codex/AGENTS.md (nicht committen)
vorlagen/config.permissions.toml	User- oder trusted .codex/config.toml
vorlagen/config.mcp.toml	[mcp_servers]-Gerüst
vorlagen/PLAN.md.skeleton.md	Repo-PLAN.md
vorlagen/skills/verify/SKILL.md	.agents/skills/verify/SKILL.md
vorlagen/hooks/	Guard/Format – Schema an aktuelle Hooks-Doku
vorlagen/agents/security-reviewer.agent.md	Briefing → Custom agent / Prompt
vorlagen/plugins/team-baseline/	Plugin-Skeleton
beispiele/configs/config.repo.example.toml	trusted .codex/config.toml
beispiele/configs/github-actions-codex.yml	CI-Gerüst
beispiele/todo-cli/	Mitmach-Mini-Projekt

---

8.10 Glossar

Begriff	Bedeutung in diesem Buch
Coding-Agent	Sprachmodell in einer Tool-Schleife: planen, lesen/schreiben, Shell, iterieren (Kap. 0)
OpenAI Codex / Codex	Produktfamilie; hier primär die Codex CLI (codex)
Harness	Schicht ums Modell: Tools, Sandbox, Approvals, Memory, Loop, Sessions
AGENTS.md	weiches, reviewbares Memory (global + Projekt-Kette)
AGENTS.override.md	Override auf derselben Ebene (Global/Projekt)
Sandbox	technische Boundary (read-only / workspace-write / danger-full-access)
Approval policy	wann der Agent fragt (untrusted / on-request / never)
Project Trust	ob Projekt-.codex/-Layer geladen werden
Auto-Preset	typisch workspace-write + on-request
YOLO / Full Access	Bypass von Sandbox und Approvals – hohes Risiko
config.toml	User/Project-Config (Defaults, Sandbox, Approvals, MCP, Features)
Config-Profile	benannte Config-Abweichung: ~/.codex/<name>.config.toml + --profile (≠ Permission Profiles :read-only / :workspace)
Rules / execpolicy	Prefix-Regeln für Commands außerhalb der Sandbox
MCP	Model Context Protocol – externe Tool-Server
Skill	on-demand Workflow (SKILL.md + optional Scripts)
Hook	erzwungenes Lifecycle-Skript
Subagent	Spezialisierung + Kontext-Ventil
Plugin	gebündelte Customizations
codex exec	non-interactive Lauf (CI, Skripte)
Action-Proxy	Responses-API-Proxy der Codex GitHub Action – Key bleibt im Action-Input, weniger Leak an untrusted Steps (Kap. 6)
Codex Cloud	async/remote Tasks in managed Environments
codex apply	Cloud-Diff lokal anwenden – nach Review
Session	fortsetzbarer Lauf (resume/fork/archive/delete)
Compact	verlustbehaftete History-Verdichtung
Cap / Instructions-Cap	Größenlimit geladener AGENTS.md-Kette (u. a. project_doc_max_bytes); Truncation = kürzen, nicht stumm ignorieren (Kap. 2)
Vier Hebel	Scope eng · Diff lesen · enge Sandbox vor Full Access · weich vs. hart

---

8.11 Env-Variablen (Auswahl)

Variable	Rolle
CODEX_HOME	Config-Root statt ~/.codex (nicht Skills-Pfad)
CODEX_API_KEY	Auth nur für codex exec – prozesslokal, nicht job-weit in CI
OPENAI_API_KEY	API-Key-Login (codex login --with-api-key); Action-Input der GitHub Action

Vollständige und aktuelle Liste: codex --help und Environment-Abschnitte der Doku.

---

8.12 Ressourcen (nur offiziell + Begleit)

Ressource	URL
Codex Learn (Root)	https://learn.chatgpt.com/codex
AGENTS.md	https://learn.chatgpt.com/codex/agent-configuration/agents-md
Sandboxing	https://learn.chatgpt.com/codex/sandboxing
Approvals & security	https://learn.chatgpt.com/codex/agent-approvals-security
Permissions	https://learn.chatgpt.com/codex/permissions
Config basics	https://learn.chatgpt.com/codex/config-file/config-basic
Advanced config	https://learn.chatgpt.com/codex/config-file/config-advanced
Rules	https://learn.chatgpt.com/codex/agent-configuration/rules
Developer commands	https://learn.chatgpt.com/codex/developer-commands
Non-interactive	https://learn.chatgpt.com/codex/non-interactive-mode
MCP	https://learn.chatgpt.com/codex/extend/mcp
Skills / Plugins	https://learn.chatgpt.com/codex/skills-and-plugins · build-skills
Hooks	https://learn.chatgpt.com/codex/hooks
Subagents	https://learn.chatgpt.com/codex/agent-configuration/subagents
Best practices	https://learn.chatgpt.com/codex/guides/best-practices
Begleit-Service (Übersicht)	https://books.maatini.space/projects/codex-harness/
Stand & Drift / Errata / Material	unter dem Begleit-Service

Keine Fremd-Agent-Vergleiche in diesem Buch – bewusst.

---

8.13 Roadmap – so gehst du weiter

Phase	Fokus	Kapitel
1	Install, Trust, erste harmlose Session	01
2	AGENTS.md + enge Sandbox/Approvals	02
3	Plan → Code → Diff → Commit	03
4	Config-Hierarchie, Profiles, Rules, Sessions	04
5	MCP, Skills, Hooks, Subagents, Plugins	05
6	Team-Baseline, codex exec, Cloud, Managed	06
7	Context, Compact, Symptom→Fix	07
8	Diesen Anhang als Spickzettel pinnen	08
9	Stabile Kernvorlagen pinnen (Hybrid)	Anhang A

Minimal-Team-Setup in einer Stunde:

1. Kern aus Anhang A.1 / A.3 → Root-AGENTS.md + Auto-Preset in Config
2. Verify-Skill aus vorlagen/skills/verify
3. Optional trusted .codex/config.toml (kein YOLO)
4. Optional CI-Gerüst ohne Auto-Merge
5. / und codex --help einmal überfliegen

---

Was du jetzt kannst

• Kern-Slash-Commands und Flags nachschlagen, ohne die Kapitel zu durchwühlen
• User- vs. Project-Pfade und Sandbox×Approvals korrekt zuordnen
• stabile Kerne aus Anhang A und volle Vorlagen/Beispiele aus dem Begleit-Service gezielt ins eigene Repo übernehmen
• Begriffe des Harness-Modells einheitlich verwenden
• Offizielle Docs und codex --help als Source of Truth nutzen

Nächste Schritte

• Buch schließen und im echten Repo eine Baseline committen (Start: Anhang A)
• Internes Runbook aus Kapitel 07 ableiten
• Vierteljährlich: codex --version, Docs und eure Configs spiegeln
• Lesevertrag aus Kapitel 00 im Team teilen: Konzept behalten, Syntax verifizieren
• ZIPs im Begleit-Service (Material) aktuell halten