Codex Setup Guide fuer Windows, WSL, VS Code und CLI
Dieser Guide ist fuer ein Developer-Setup gedacht, bei dem die Codex App auf Windows laeuft, der Agent in WSL2 arbeitet, VS Code per Remote WSL genutzt wird und die Codex CLI in WSL installiert ist. Ziel ist eine Einrichtung, bei der App, IDE und CLI nicht gegeneinander arbeiten, sondern dieselben Regeln, Tools und Skills nutzen.
1. Empfohlenes Zielbild​
Wenn dein Code, Node/Yarn, Python, Git und Shell-Workflow ohnehin in Linux laufen, ist WSL2 die sauberste gemeinsame Arbeitsumgebung:
| Bereich | Empfehlung |
|---|---|
| Repo-Speicherort | In WSL unter /home/<user>/code/..., nicht unter /mnt/c/... |
| Codex App | Windows App, Agent Environment auf WSL2 stellen und App neu starten |
| VS Code | Ordner aus WSL oeffnen: code ., Statusleiste zeigt WSL: ... |
| CLI | Codex in der WSL-Shell installieren und starten |
| Projektregeln | Repo-AGENTS.md im Git-Root |
| Persoenliche Regeln | ~/.codex/AGENTS.md in der Umgebung, die Codex wirklich nutzt |
| Projekt-Skills | .agents/skills/<skill-name>/SKILL.md im Repo |
| Persoenliche Skills | $HOME/.agents/skills/<skill-name>/SKILL.md |
| Einstellungen | ~/.codex/config.toml plus optional .codex/config.toml im Repo |
Der wichtigste Punkt: Windows App und WSL CLI haben standardmaessig unterschiedliche Home-Verzeichnisse. Die Windows App nutzt auf Windows normalerweise %USERPROFILE%\.codex; die CLI in WSL nutzt /home/<user>/.codex. Wenn du in beiden Welten Skills, Auth, Sessions, Memories oder Config erwartest, musst du die Pfade bewusst vereinheitlichen oder getrennt pflegen.
2. Warum WSL als Agent Environment sinnvoll sein kann​
WSL bringt echte Vorteile, wenn dein Projekt eine Linux-Toolchain erwartet:
- gleiche Shell- und Pfadlogik wie viele CI/CD-Systeme,
- schnellere und stabilere I/O, wenn das Repo unter
/home/...liegt, - weniger Probleme mit Symlinks, Permissions und Linux-nativen Tools,
- VS Code Remote WSL, integriertes Terminal und Codex arbeiten im selben Dateisystem,
- Codex nutzt in WSL die Linux-Sandbox statt der Windows-Sandbox.
WSL ist weniger sinnvoll, wenn dein Projekt Windows-nativ ist, zum Beispiel .NET Desktop, PowerShell-first Automation, Visual-Studio-lastige Workflows oder Repos auf dem Windows-Dateisystem. Dann ist der native Windows Agent oft direkter.
Lege Linux-Projekte nicht dauerhaft unter /mnt/c/... ab, nur damit Windows sie leichter sieht. Das ist oft langsamer und erzeugt mehr Pfad-, Symlink- und Permission-Probleme. Nutze fuer Windows-Zugriff lieber \\wsl$\Ubuntu\home\<user>\....
3. Installation in WSL​
Starte in Windows einmal WSL2, falls es noch fehlt:
wsl --install
wsl
In der WSL-Shell installierst du Codex:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex
Fuer WSL/Linux-Sandboxing sollte bubblewrap installiert sein:
sudo apt update
sudo apt install bubblewrap
Typische Basis-Tools fuer dieses Repo:
sudo apt update
sudo apt install git curl nodejs npm python3
corepack enable
yarn --version
Je nach Node-Setup ist nvm, fnm oder die NodeSource-Installation sauberer als das Ubuntu-Paket. Wichtig ist: dieses Projekt erwartet Node 20+ und Yarn.
4. Repo und VS Code richtig oeffnen​
Lege Repos in WSL ab:
mkdir -p ~/code
cd ~/code
git clone <repo-url>
cd <repo>
code .
In VS Code pruefen:
- unten links steht
WSL: <distro>, - das integrierte Terminal zeigt Linux-Pfade wie
/home/..., echo $WSL_DISTRO_NAMEgibt deine Distribution aus,which codexzeigt auf eine Linux-Installation, nicht aufC:\....
Wenn VS Code nicht in WSL laeuft: Ctrl+Shift+P -> WSL: Reopen Folder in WSL.
5. Codex App mit WSL verbinden​
In der Windows App:
- Settings oeffnen.
- Agent Environment von Windows native auf WSL stellen.
- App neu starten, weil der Wechsel erst danach greift.
- Projekt aus dem WSL-Dateisystem oeffnen. Falls der Picker den Ordner nicht zeigt:
\\wsl$eintippen und zur Distro navigieren. - Optional den integrierten Terminal ebenfalls auf WSL stellen. Agent Environment und Terminal sind getrennte Einstellungen.
Die App kann mit WSL-Projekten arbeiten, aber ihre Windows-seitige App-Konfiguration ist nicht automatisch dasselbe wie die WSL-CLI-Konfiguration. Genau dort entstehen die meisten "warum sehe ich X nicht?"-Effekte.
6. App und CLI sinnvoll verknuepfen​
App, CLI und IDE teilen Codex-Konzepte: config.toml, MCP, Skills, Plugins, AGENTS.md, Approvals, Sandbox, Modelle und Feature Flags. Praktisch verknuepfst du sie ueber gemeinsame Dateien und dieselbe Arbeitsumgebung.
| Funktion | In der App | In der CLI |
|---|---|---|
| Desktop starten | App direkt oeffnen | codex app |
| Feature Flags | Settings oder Prompt | codex features list, codex features enable goals |
| MCP pruefen | Settings oder /mcp | codex mcp ... und ~/.codex/config.toml |
| Skills nutzen | $skill-name oder Skill-Liste | $skill-name, /skills, Skill-Metadaten |
| Projektregeln | Automatisch aus AGENTS.md | Automatisch aus AGENTS.md |
| Review | Diff Panel oder /review | /review |
| Status | /status | /status |
| Zielmodus | /goal | /goal |
Gemeinsames CODEX_HOME​
Wenn du willst, dass WSL CLI und Windows App dieselbe Config/Auth/Sessions sehen, gibt es zwei Wege:
| Weg | Vorteil | Nachteil |
|---|---|---|
| Getrennt lassen | Sauber nach OS getrennt, weniger Pfadueberraschungen | Config, Skills, Auth und Sessions muessen doppelt gepflegt werden |
CODEX_HOME in WSL auf Windows-Home zeigen lassen | App und WSL CLI sehen denselben Codex-Home | WSL greift auf /mnt/c/... zu; kann langsamer sein und braucht Pfad-Disziplin |
Beispiel fuer geteiltes CODEX_HOME in WSL:
export CODEX_HOME=/mnt/c/Users/<WindowsUser>/.codex
Wenn das dauerhaft gelten soll:
echo 'export CODEX_HOME=/mnt/c/Users/<WindowsUser>/.codex' >> ~/.zshrc
Ich wuerde nur dann ein gemeinsames CODEX_HOME setzen, wenn du wirklich Sessions/Auth/Config teilen willst. Fuer Team- und Repo-Regeln ist es robuster, AGENTS.md und .agents/skills direkt ins Repo zu legen.
7. Warum sehe ich Skills in der App nicht?​
Meist liegt es an einem dieser Punkte:
| Ursache | Pruefung | Fix |
|---|---|---|
| Skills liegen nur in WSL | find ~/.agents/skills -maxdepth 2 -name SKILL.md in WSL | Repo-Skills nach .agents/skills legen oder Windows/WSL-Home synchronisieren |
| App nutzt anderes Codex-Home | Windows: %USERPROFILE%\.codex; WSL: ~/.codex | CODEX_HOME bewusst setzen oder Config getrennt pflegen |
| App wurde nach Skill-Aenderung nicht neu geladen | Skill taucht nach Neustart auf | App neu starten oder Skills neu laden |
| Skill liegt falsch | Erwartet wird <dir>/SKILL.md mit name und description | Struktur korrigieren |
| Projekt wurde anders geoeffnet | App zeigt Windows-Pfad, VS Code WSL-Pfad | Dasselbe Repo aus \\wsl$ bzw. /home/... oeffnen |
| Projekt ist nicht vertraut | Projekt-Config/Rules/Skills werden ignoriert | Projekt in Codex als trusted behandeln |
| Skill kommt aus Plugin | Plugin nicht installiert oder deaktiviert | App: Plugins oeffnen; CLI: /plugins |
| Zu viele Skills installiert | Nicht jede Skill steht sofort im Initialkontext | Skill explizit mit $skill-name aufrufen |
Eine minimale repo-lokale Skill sieht so aus:
.agents/
skills/
docs-review/
SKILL.md
---
name: docs-review
description: Review MDX documentation for structure, broken links, tone, and Docusaurus build risks.
---
1. Read the changed MDX files.
2. Check links, headings, admonitions, code fences, and sidebar metadata.
3. Run the documented build command if possible.
4. Report issues before style suggestions.
Repo-Skills sind fuer Teams am besten, weil App, CLI und IDE sie sehen, sobald sie im selben Repo-Kontext laufen.
8. Personalisierung, AGENTS.md und Config​
Die Codex App hat Personalization-Einstellungen wie Personality und Custom Instructions. Ob diese in der WSL-CLI sichtbar sind, haengt davon ab, ob App und CLI dieselben Dateien laden.
| Ziel | Richtiger Ort |
|---|---|
| Persoenliche Arbeitsweise fuer alle Repos | ~/.codex/AGENTS.md |
| Temporaerer persoenlicher Override | ~/.codex/AGENTS.override.md |
| Repo-Regeln fuer alle im Team | AGENTS.md im Repo-Root |
| Bereichsspezifische Repo-Regeln | AGENTS.md oder AGENTS.override.md in Unterordnern |
| Codex-Einstellungen | ~/.codex/config.toml |
| Projekt-Einstellungen | .codex/config.toml im Repo, nur fuer trusted Projekte |
| Wiederverwendbare Workflows | .agents/skills/.../SKILL.md oder $HOME/.agents/skills/.../SKILL.md |
Nicht gemeint ist normalerweise /.codex direkt im Linux-Root. Gemeint ist fast immer ~/.codex, also dein Home-Verzeichnis.
Ein gutes globales ~/.codex/AGENTS.md:
# Personal Codex defaults
## Working style
- Answer in German unless the repository or user asks for English.
- Prefer concise final summaries with validation status.
- Before editing, inspect the local conventions.
- Do not add dependencies without calling out why they are needed.
## Verification
- For documentation-only changes, run the project's documented build command when practical.
- If validation cannot run, explain why.
Ein gutes repo-lokales AGENTS.md bleibt technischer und weniger persoenlich:
# Repository Guidelines
## Commands
- Use `yarn build` to validate Docusaurus docs changes.
- Use `yarn start` for manual UI checks.
## Docs
- Keep filenames lowercase and descriptive.
- Use MDX frontmatter with `title`, `description`, and `sidebar_position`.
- Do not edit generated i18n files unless explicitly requested.
9. Sinnvolle config.toml-Basis​
Starte klein. Diese Datei liegt in WSL unter ~/.codex/config.toml, sofern du CODEX_HOME nicht anders setzt:
# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
web_search = "cached"
personality = "pragmatic"
[features]
goals = true
hooks = true
memories = false
[sandbox_workspace_write]
network_access = false
Wichtige Regeln:
approval_policy = "on-request"ist ein guter Start, weil Codex arbeiten kann, aber fuer riskante Aktionen fragt.sandbox_mode = "workspace-write"erlaubt Arbeit im Repo, ohne das ganze System zu oeffnen.network_access = falseist sicherer; fuer Paketinstallationen oder Webzugriff gezielt freigeben.memoriessind optional und in einigen Regionen nicht verfuegbar. Team-Regeln gehoeren trotzdem inAGENTS.md, nicht nur in Memories.- Projekt-Config in
.codex/config.tomlnur fuer Dinge nutzen, die wirklich zum Repo gehoeren.
10. VS Code Extension​
Die Codex VS Code Extension nutzt denselben Agenten wie CLI und App und teilt die Codex-Konfiguration. Beschraenkt auf VS Code sind diese Funktionen wichtig:
| Funktion | Bedeutung |
|---|---|
| IDE Context | Codex kann offene Dateien, Auswahl und explizit hinzugefuegte Dateien als Kontext nutzen |
| Auto Context | Codex bezieht aktuelle Editor-Signale automatisch ein; mit /auto-context steuerbar |
@file | Datei direkt im Prompt referenzieren |
| Add selected text to thread | Markierten Code als Kontext in die laufende Unterhaltung geben |
| Add file to thread | Ganze Datei als Kontext geben |
| Implement TODO | Ausgewaehlten TODO-Kommentar als Aufgabe starten |
| Model selector | Modell und Reasoning Effort im UI wechseln |
| Approval mode | Zwischen Chat, Agent und Agent Full Access wechseln |
| Cloud delegation | Groessere Jobs an Codex Cloud delegieren |
/review | Uncommitted Changes oder Branch-Diff reviewen lassen |
/goal | Zielmodus fuer eine persistent verfolgte Aufgabe starten |
Agent, Chat und Plan Mode​
In der VS Code Extension meint der Agent/Chat Mode Switch den Modus im Codex-Panel, nicht "ChatGPT-Fenster vs Codex-Fenster".
| Modus | Was passiert | Wann nutzen |
|---|---|---|
| Chat | Codex antwortet, erklaert und plant, ohne automatisch Code zu aendern oder Commands auszufuehren | Fragen, Architektur, Plan, Debugging-Gespraech |
| Agent | Codex darf im Workspace lesen, editieren und lokale Commands ausfuehren; fuer externe Pfade/Netzwerk wird gefragt | Normale Implementierung |
| Agent Full Access | Codex arbeitet mit deutlich mehr Zugriff und weniger Unterbrechung | Nur fuer vertraute Repos und klare Aufgaben |
Plan Mode ist die Arbeitsweise "erst Kontext sammeln und Plan bauen, dann implementieren". In App und CLI gibt es dafuer /plan. In VS Code erreichst du denselben Effekt ueber Chat Mode oder, falls in deiner Version vorhanden, ueber den Slash Command. Gute Prompts sind eindeutig:
Plane zuerst nur. Lies die relevanten Dateien, stelle offene Fragen und gib mir einen Umsetzungsplan. Noch keine Dateien aendern.
Pursue Goal / Goal Mode​
/goal startet ein dauerhaftes Ziel. Codex arbeitet daran, bis das Ziel fertig ist, pausiert oder weitere Eingaben braucht. Das ist hilfreich fuer Aufgaben wie "mache diese Migration komplett fertig und validiere sie".
Wenn /goal nicht auftaucht:
[features]
goals = true
Oder in der CLI:
codex features enable goals
Configuration Tools in VS Code​
Die wichtigsten Konfigurationsstellen:
- Gear/Menu im Codex Panel -> Codex Settings ->
config.tomloeffnen. - Model Selector unter dem Prompt -> Modell und Reasoning Effort.
- Approval/Mode Switch -> Chat, Agent, Full Access.
/status-> Thread-ID, Kontext, Limits./mcpoder MCP Settings -> verbundene MCP-Server pruefen.- VS Code Setting
chatgpt.runCodexInWindowsSubsystemForLinux-> Codex in WSL ausfuehren, wenn Windows und WSL verfuegbar sind.
11. CLI in WSL​
Die CLI ist dein schnellster Weg fuer Repo-nahe Arbeit:
# Interaktiv im aktuellen Repo
codex
# Kurze Aufgabe mit Repo-Kontext
codex "Erklaere mir die Struktur dieses Projekts"
# Nicht-interaktiv fuer Automationen
codex exec "Pruefe die Doku auf kaputte Links und fasse die Befunde zusammen"
# Letzte Session fortsetzen
codex resume --last
# Modell fuer diesen Lauf setzen
codex --model gpt-5.5
# Aktive Infos anzeigen
codex --version
Login:
codex login
Nutze ChatGPT Login, wenn du deine ChatGPT/Codex-Berechtigungen, Codex Cloud oder Workspace-Policies nutzen willst. Nutze API-Key-Login eher fuer CI/CD oder klar abrechenbare API-Workflows.
Gute CLI-Gewohnheiten:
- Starte
codeximmer im Repo-Root oder mit--cd. - Nutze
/status, wenn du unsicher bist, welche Session/Config aktiv ist. - Nutze
/permissions, wenn du voruebergehend enger oder weiter arbeiten willst. - Nutze
/review, bevor du groessere Aenderungen uebernimmst. - Nutze
codex execfuer wiederholbare Aufgaben in Scripts, aber mit engen Permissions.
12. MCP, Plugins und externe Tools​
MCP verbindet Codex mit externen Tools und Daten. Plugins sind installierbare Bundles, die Skills, Apps und MCP-Server zusammenbringen koennen.
| Bedarf | Empfehlung |
|---|---|
| GitHub, Linear, Slack, Drive, Figma oder interne Tools nutzen | MCP oder Plugin |
| Ein wiederholbarer Ablauf ohne externes Tool | Skill |
| Ein Team soll denselben Tool-Workflow installieren | Plugin |
| Nur repo-interne Regeln | AGENTS.md |
MCP-Konfiguration gehoert in ~/.codex/config.toml oder, fuer trusted Repos, in .codex/config.toml. Wenn App, CLI und IDE dieselbe Config laden, sehen sie dieselben MCP-Server.
13. Sicherheits-Checkliste​
Vor produktivem Einsatz:
- ChatGPT Account mit MFA absichern, besonders wenn Codex Cloud genutzt wird.
auth.json, API Keys, Tokens und.envnie committen.- Default bei
workspace-writeundon-requestlassen, bis du ein Repo gut kennst. - Full Access nur fuer klare Aufgaben in vertrauten Repos.
- Netzwerkzugriff gezielt freigeben, nicht pauschal.
- Repos aus unbekannten Quellen erst read-only inspizieren.
AGENTS.mdfuer Projektregeln nutzen, nicht nur Memory oder spontane Prompts.- Test-, Build- und Review-Befehle im Repo dokumentieren.
- Fuer WSL: Repo unter
/home/..., nicht/mnt/c/....
14. Setup-Pruefung fuer dein Szenario​
Fuehre diese Checks in WSL aus:
pwd
echo $WSL_DISTRO_NAME
which codex
codex --version
echo "${CODEX_HOME:-$HOME/.codex}"
find ~/.agents/skills -maxdepth 3 -name SKILL.md 2>/dev/null
test -f ~/.codex/AGENTS.md && sed -n '1,80p' ~/.codex/AGENTS.md
test -f ~/.codex/config.toml && sed -n '1,120p' ~/.codex/config.toml
git rev-parse --show-toplevel
In VS Code:
- Statusleiste zeigt
WSL: .... - Codex Extension ist im WSL-Fenster aktiv.
- Integrated Terminal findet
codex. - Auto Context laesst sich mit
/auto-contextsteuern. /goalerscheint oderfeatures.goals = trueist gesetzt.
In der Windows App:
- Agent Environment steht auf WSL.
- App wurde nach dem Wechsel neu gestartet.
- Projekt wurde aus
\\wsl$oder einem WSL-Projektpfad geoeffnet. - Skills/Plugins sind installiert oder liegen im Repo.
/status,/mcp,/reviewfunktionieren im Thread.
15. Kurzantworten auf die haeufigsten Fragen​
Greift Personalization aus der Codex App auch in der WSL CLI?
Nur wenn beide dieselben Config-/Instruction-Dateien laden. Bei Windows App plus WSL CLI ist das ohne CODEX_HOME-Sync normalerweise nicht der Fall. Lege wichtige persoenliche Regeln in WSL in ~/.codex/AGENTS.md oder teile bewusst CODEX_HOME.
Welche Markdown-Dateien brauche ich?
Minimum: repo-lokal AGENTS.md. Optional: global ~/.codex/AGENTS.md. Fuer Skills: SKILL.md in .agents/skills/<name>/ oder $HOME/.agents/skills/<name>/.
Ist .codex/config.toml dasselbe wie AGENTS.md?
Nein. AGENTS.md ist Arbeitsanweisung. config.toml ist technische Konfiguration: Modell, Sandbox, Approval, MCP, Feature Flags, Hooks.
Warum sieht die App meine CLI-Skills nicht?
Weil App und CLI sehr wahrscheinlich unterschiedliche Home-Verzeichnisse und Skill-Pfade sehen. Nutze repo-lokale .agents/skills, starte neu oder teile die relevanten Pfade bewusst.
Ist der Agent/Chat Switch in der Webdoku das ChatGPT- und Codex-Fenster?
Nein. Gemeint ist der Modus innerhalb der Codex IDE Extension: Chat fuer Fragen/Planung, Agent fuer echte Repo-Aktionen.
Soll ich App, IDE und CLI parallel nutzen?
Ja, aber mit klaren Rollen: App fuer parallele Threads, Worktrees, Review und groessere Arbeitsablaeufe; VS Code fuer editornahen Kontext; CLI fuer schnelle Repo-Arbeit, exec, Resume und Debugging.