Codex CLI instalacja na Windows krok po kroku (npm, winget, WSL)

👁 114 przeczytań

Codex CLI na Windowsie 11 instalujesz jednym poleceniem w PowerShellu: oficjalnym instalatorem, przez npm albo przez winget. WSL nie jest już potrzebny, bo Codex ma własny sandbox dla Windowsa. Poniżej cała droga od instalacji do pierwszego zadania, z poleceniami, które sprawdziłem na swoim komputerze 3 października 2026. Pełny opis agenta, cen i modeli jest w przewodniku Codex od OpenAI.

Wymagania: Node, PowerShell czy WSL

Najczęstsze pytanie brzmi: czy na Windowsie trzeba stawiać WSL. Dokumentacja OpenAI na 3 października 2026 mówi jasno: domyślnie używaj natywnego sandboksa Windows, a WSL2 wybierz tylko wtedy, gdy potrzebujesz narzędzi linuksowych albo cały projekt i tak żyje w WSL. Uwaga na stary plik docs/install.md w repozytorium na GitHubie, który dalej podaje „Windows 11 via WSL2” - to nieaktualna tabela, nowsza strona o sandboksie Windows ją wyprzedza.

• System: 64-bitowy Windows (instalator przerywa pracę na 32-bitowym), najlepiej Windows 11. Windows 10 potrzebuje mechanizmu konsoli ConPTY, czyli wersji 1809 lub nowszej.
• winget powinien być dostępny w systemie - dokumentacja wymienia go jako założenie.
• Node.js tylko przy instalacji przez npm. Pakiet wymaga node >=16 (pole engines w package.json). Instalator PowerShell i winget Node nie potrzebują.
• RAM: według repozytorium minimum 4 GB, zalecane 8 GB. Git nie jest obowiązkowy, ale się przydaje.

Sprawdziłem u siebie, co faktycznie ląduje na dysku przy instalacji przez npm. Node to tylko starter: plik codex.js uruchamia natywny program napisany w Rust. Cały pakiet zajmuje 430 MB, z czego sam codex.exe ma 327 MB. Obok leżą m.in. rg.exe (ripgrep do przeszukiwania kodu), codex-windows-sandbox-setup.exe i codex-command-runner.exe.

Instalacja krok po kroku

Masz trzy oficjalne drogi. Wybierz jedną, bo dwie równoległe instalacje to najczęstsze źródło zamieszania z PATH.

Przejrzałem treść instalatora PowerShell (warto tak robić z każdym skryptem irm ... | iex). Wynika z niej, że:

• dopisuje katalog z codex.exe do PATH użytkownika, więc po instalacji otwórz nowe okno PowerShella;
• sprawdza sumę SHA256 pobranego archiwum;
• wykrywa wcześniejszą instalację z npm i proponuje jej usunięcie, ostrzegając, że przy dwóch instalacjach „o tym, która się uruchomi, decyduje kolejność w PATH”.

Po instalacji sprawdź, co masz. Wynik z mojego komputera:

1. codex --version zwraca codex-cli 0.160.0 (sprawdziłem).
2. where codex pokazuje dwa pliki: C:\Users\...\AppData\Roaming\npm\codex i codex.cmd (sprawdziłem). W tym samym katalogu npm tworzy jeszcze codex.ps1 - to on sprawia kłopot z ExecutionPolicy, o czym niżej.
3. node --version zwraca u mnie v26.10.0 (sprawdziłem).

Logowanie: konto ChatGPT czy klucz API

Wpisz codex login (albo po prostu codex w katalogu projektu). Otworzy się przeglądarka, logujesz się do ChatGPT, a dane wracają do terminala. Stan sprawdzisz poleceniem codex login status - u mnie zwraca Logged in using ChatGPT (sprawdziłem).

• Konto ChatGPT - zużywasz limit planu, działają funkcje chmurowe. Codex w CLI jest od planu Plus; Free i Go dostają tylko GPT-6 Luna w aplikacji na komputer. Ile tego limitu realnie jest, opisałem w tekście Codex limity w Plus.
• Klucz API - płacisz za tokeny według cennika API, tracisz chmurę i automatyczne przeglądy na GitHubie. W PowerShellu: $env:OPENAI_API_KEY | codex login --with-api-key (dokumentacja podaje wersję z printenv dla Linuksa i macOS).
• Bez przeglądarki (serwer, zdalna maszyna) - w codex login --help jest flaga --device-auth, czyli logowanie kodem urządzenia (sprawdziłem, że flaga istnieje; opisu w pomocy brak).

Dane logowania trafiają do katalogu %USERPROFILE%\.codex (u mnie plik auth.json). Nie wrzucaj tego katalogu do repozytorium ani do chmury z synchronizacją.

Pierwsze uruchomienie i AGENTS.md

1. Zrób commit w repozytorium, żeby mieć punkt powrotu.
2. W katalogu projektu wpisz codex i daj zadanie bez ryzyka, np. „Opisz strukturę tego projektu”.
3. Wpisz /init - Codex wygeneruje szkielet pliku AGENTS.md z instrukcjami dla agenta.
4. Stałe reguły dla wszystkich projektów zapisz w %USERPROFILE%\.codex\AGENTS.md.

Codex czyta najpierw globalny AGENTS.md, potem pliki od katalogu głównego repozytorium w dół do bieżącego folderu. Łączny limit to 32 KiB (ustawienie project_doc_max_bytes), więc długie elaboraty i tak zostaną ucięte. Pełny opis pracy w sesji, z modelami i poleceniami, jest w hubie Codex.

Tryby zatwierdzania i sandbox

Dwie rzeczy działają razem: sandbox wyznacza, do czego agent ma dostęp, a polityka zatwierdzania mówi, kiedy pyta. W sesji ustawiasz to poleceniem /permissions, przy starcie flagami. Wartości poniżej pochodzą z codex --help w wersji 0.160.0 (sprawdziłem):

Domyślny tryb z dokumentacji, „Ask for approval”, to workspace-write plus on-request: agent edytuje pliki w projekcie i uruchamia zwykłe polecenia, ale pyta przed wejściem do internetu albo poza katalog. Na Windowsie sandbox ma dwa warianty, wybierane w config.toml:

• [windows] sandbox = "elevated" - zalecany, tworzy osobnych użytkowników o niższych uprawnieniach i reguły zapory, przy konfiguracji wymaga zgody administratora (UAC). U mnie w config.toml jest właśnie ten wariant (sprawdziłem w pliku).
• sandbox = "unelevated" - zapasowy, działa na ograniczonym tokenie Twojego użytkownika i uprawnieniach ACL, słabiej izoluje sieć. Przydaje się na firmowym laptopie, gdzie polityka blokuje tworzenie użytkowników.

Pełnego dostępu nie daję agentowi w katalogach z danymi klientów - więcej w tekście agent do kodu w firmie.

Aktualizacja

• dowolna instalacja: codex update (podpolecenie „Update Codex to the latest version” w codex --help, sprawdziłem);
• npm: npm install -g @openai/codex@latest;
• winget: winget upgrade --id OpenAI.Codex;
• instalator PowerShell: uruchom ten sam skrypt jeszcze raz, tak podaje dokumentacja.

Na npm są też wersje alfa: 3 października rano opublikowano 0.162.0-alpha.10 (sprawdziłem w npm view). Zwykłe @latest ich nie instaluje. Problemy z instalacją diagnozuje codex doctor.

Typowe błędy na Windowsie i rozwiązania

• „codex is not recognized” - terminal nie widzi nowego PATH. Otwórz nowe okno. Przy npm sprawdź, czy %APPDATA%\npm jest w PATH (npm config get prefix pokaże katalog). where codex powie, który plik się uruchamia.
• „running scripts is disabled on this system” - PowerShell trafia na codex.ps1 z npm, a polityka wykonywania to Restricted. Rozwiązania: uruchom codex.cmd, użyj cmd albo zmień politykę tylko dla siebie: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. Oficjalny instalator omija problem przez -ExecutionPolicy ByPass tylko dla jednego procesu.
• Dwie wersje naraz - codex --version pokazuje starą wersję po aktualizacji. Zwykle masz npm i instalator jednocześnie. Zostaw jedną instalację.
• Nie udała się konfiguracja sandboksa - odrzucony UAC, zablokowane tworzenie użytkowników albo reguł zapory. Według dokumentacji: powtórz ze zgodą administratora, a gdy firma blokuje, przejdź tymczasowo na unelevated.
• Błąd 1385 - Windows odmawia użytkownikom sandboksa prawa logowania. To sprawa dla działu IT; do tego czasu unelevated.
• Sandbox nie może czytać katalogu - w sesji: /sandbox-add-read-dir C:\pelna\sciezka. Dostęp działa do końca sesji.
• Za długie ścieżki - Codex tego nie opisuje, ale Git na Windowsie przy głębokich node_modules zgłasza „Filename too long”. Pomaga git config --global core.longpaths true, a w systemie włączenie długich ścieżek (LongPathsEnabled) przez administratora.
• Antywirus - dokumentacja o nim milczy, u mnie blokady nie było. Jeśli firmowy antywirus usuwa codex.exe albo codex-windows-sandbox-setup.exe, nie wyłączaj ochrony, tylko poproś administratora o wyjątek dla katalogu instalacji.
• Uszkodzony config.toml po awarii - przytrafiło mi się to naprawdę: po niebieskim ekranie 9 września 2026 mój config.toml miał 73 334 bajty i wszystkie były zerami. Trzymaj kopię tego pliku, bo bez niej odtwarzasz ustawienia z pamięci.
• Wolno w WSL - nie pracuj na /mnt/c/.... OpenAI radzi trzymać repozytorium w katalogu domowym Linuksa, np. ~/code.

Odinstalowanie

1. Jeśli używałeś konta ChatGPT, najpierw codex logout.
2. npm: npm uninstall -g @openai/codex; winget: winget uninstall --id OpenAI.Codex.
3. Instalator PowerShell: oficjalnego polecenia do odinstalowania nie znalazłem. Ze skryptu wynika, że pliki leżą w %LOCALAPPDATA%\Programs\OpenAI\Codex i %USERPROFILE%\.codex\packages\standalone, a wpis jest w PATH użytkownika.
4. Katalog %USERPROFILE%\.codex z ustawieniami, historią sesji i AGENTS.md usuń tylko, jeśli nie wrócisz do Codeksa. Korzysta z niego także aplikacja ChatGPT na komputer.

Porównanie z konkurentem jest w tekście Codex czy Claude Code, a wersję działającą bez Twojego komputera opisuję w Codex w chmurze.

Źródła i data sprawdzenia

• OpenAI: Windows sandbox (wersje Windows, tryby elevated i unelevated, błędy)
• OpenAI: Codex w WSL (WSL1 do wersji 0.114)
• OpenAI: dokumentacja Codex CLI
• OpenAI: logowanie i tryby uprawnień
• OpenAI: AGENTS.md
• GitHub: openai/codex (README, instalator, wymagania RAM)
• npm: @openai/codex i manifest winget OpenAI.Codex

Polecenia oznaczone „sprawdziłem” uruchomiłem 3 października 2026 na Windows 11 z Codex CLI 0.160.0 zainstalowanym przez npm. Pozostałe kroki opisuję według dokumentacji OpenAI i treści skryptu instalacyjnego.