Skonfiguruj środowisko i plik AGENTS.md
Na tej stronie
Zaktualizowano 3 listopada 2026 na podstawie dokumentacji Codex (Codex CLI, Uwierzytelnianie, Rozszerzenie IDE Codex, Niestandardowe instrukcje z AGENTS.md): pakiet
@openai/codex-clioraz poleceniecodex auth loginnie istnieją (użyjnpm install -g @openai/codexicodex login); identyfikator rozszerzenia toopenai.chatgpt; adres codex.openai.com oraz plany „Team, Enterprise lub API“ zastąpiono aktualnymi metodami dostępu; wyjaśniono również kolejność odczytu AGENTS.md (główny katalog projektu → bieżący katalog). Źródła: Codex CLI · Uwierzytelnianie · AGENTS.md · Cennik.
Przygotuj projekt dla Codex
Zanim przystąpisz do pierwszego zadania, muszą być spełnione dwa warunki: dostęp do Codex (twoje konto i połączenie z GitHub) oraz sam projekt, zdefiniowany poprzez plik AGENTS.md, który będzie kierował agentem. Pierwsza część zajmuje około 15 minut i jest konfiguracją jednorazową. Druga decyduje o jakości wszystkiego, co uzyskasz z Codex, oddzielając zespoły zadowolone z działania narzędzia od tych, które są rozczarowane.
Krok 1: Twój dostęp do Codex
Możesz korzystać z Codex za pomocą konta ChatGPT lub klucza API. Plany Free i Go zapewniają dostęp, w zależności od aktualnego wdrożenia, do modelu GPT-6 Luna w aplikacji desktopowej. Począwszy od planu Plus, Codex jest dostępny w przeglądarce, w CLI, w rozszerzeniu edytora oraz na iOS, z integracjami chmurowymi, takimi jak automatyczny przegląd kodu. Klucz API działa w przypadku automatyzacji w środowiskach współdzielonych, takich jak CI, przy użyciu CLI, SDK lub rozszerzenia – choć niektóre funkcje mogą być niedostępne. Szczegóły i limity użytkowania znajdziesz na stronie cennika Codex.
Aby pracować w chmurze nad swoimi repozytoriami, podłącz GitHub podczas tworzenia pierwszego środowiska Codex Cloud (Lekcja 2). Przy nadawaniu uprawnień zachowaj minimalizm: ogranicz dostęp wyłącznie do repozytoriów, których rzeczywiście potrzebujesz.
Krok 2: Zainstaluj rozszerzenie edytora
W VS Code i jego pochodnych (Cursor, Windsurf) zainstaluj rozszerzenie Codex z marketplace’u – jego identyfikator to openai.chatgpt:
code --install-extension openai.chatgpt
Następnie otwórz Codex poprzez jego ikonę lub przez paletę poleceń, wybierając Codex: Open Codex Sidebar, i zaloguj się. Xcode oraz IDE od JetBrains mają własne integracje: w JetBrains otwórz AI Chat i wybierz Codex.
Krok 3: Zainstaluj CLI
# Instalacja (macOS i Linux) lub npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Weryfikacja instalacji
codex --version
# Logowanie (przeglądarka) lub sprawdzenie statusu połączenia
codex login
codex login status
Polecenie codex login otwiera proces logowania w Twojej przeglądarce. W przypadku klucza API przekaż go przez standardowe wejście (printenv OPENAI_API_KEY | codex login --with-api-key). Codex buforuje dane uwierzytelniające albo w pliku tekstowym ~/.codex/auth.json, albo w systemowym magazynie kluczy, w zależności od ustawienia cli_auth_credentials_store (file, keyring, auto lub ephemeral). Jeśli używany jest plik, traktuj go jak hasło: zawiera tokeny dostępu, więc nigdy go nie commituj. CLI i rozszerzenie współdzielą ten bufor.
Plik AGENTS.md – przewodnik po Twoim projekcie
AGENTS.md jest kluczowy dla efektywnego korzystania z Codex. To prosty plik Markdown umieszczony w głównym katalogu repozytorium, który gromadzi instrukcje, konwencje i polecenia specyficzne dla Twojego projektu. Gdy Codex klonuje repozytorium, jako pierwsze odczytuje ten plik: potraktuj to jako automatyczne wdrożenie dla agenta, dokładnie tak, jak wyjaśniłbyś ustnie nowemu członkowi zespołu.
Wpływ jest natychmiastowy. Bez AGENTS.md, jeśli poprosisz o test jednostkowy w projekcie używającym Vitest, istnieje duże prawdopodobieństwo, że Codex zaproponuje Jesta, ponieważ jest to najczęstszy wybór w ekosystemie. Pojedyncza linia z konwencją wystarczy, aby za pierwszym razem uzyskać poprawny kod dla Vitest, oszczędzając Ci setek poprawek. Oto struktura podstawowego pliku dla projektu SaaS do zarządzania fakturami.
# AGENTS.md
## Kontekst projektu
Aplikacja SaaS do zarządzania fakturami.
Stos technologiczny: Next.js 15, TypeScript, Prisma, PostgreSQL.
## Konwencje kodu
- Używaj funkcyjnych komponentów React (bez klas)
- Nazywaj pliki w formacie kebab-case
- Typy TypeScript w osobnych plikach .types.ts
- Testy z Vitest, pliki .test.ts obok kodu
## Przydatne polecenia
- `npm run dev` — serwer deweloperski
- `npm run test` — uruchomienie testów
- `npm run lint` — sprawdzenie lintingu
- `npm run build` — build produkcyjny
## Struktura projektu
src/
app/ → strony Next.js (App Router)
components/ → wielokrotnego użytku komponenty React
lib/ → logika biznesowa i narzędzia
prisma/ → schemat bazy danych i migracje
## Ścisłe zasady
- NIGDY nie modyfikuj schematu Prisma bez migracji
- NIGDY nie commituj plików .env
- Zawsze używaj Server Actions do mutacji
Jak Codex odnajduje pliki AGENTS.md
Pojedynczy plik w katalogu głównym szybko staje się zbyt ogólny. Codex pozwala nakładać instrukcje w precyzyjnej kolejności, którą musisz znać:
- Poziom globalny: W folderze Codex (
~/.codex, chyba że zmiennaCODEX_HOMEto nadpisuje), Codex odczytujeAGENTS.override.md, jeśli istnieje, w przeciwnym razieAGENTS.md. - Poziom projektu: Codex zaczyna od katalogu głównego projektu (zwykle korzenia repozytorium Git), po czym schodzi do bieżącego katalogu i odczytuje w każdym odwiedzonym folderze
AGENTS.override.mdlub, w razie jego braku,AGENTS.md. - Scalanie: Pliki są łączone od katalogu głównego w dół do bieżącego katalogu; te znajdujące się najbliżej bieżącego katalogu są dołączane jako ostatnie, a zatem nadpisują bardziej ogólne instrukcje.
my-project/
AGENTS.md → Instrukcje projektu
src/
api/
AGENTS.md → „Trasy API używają Zod do walidacji“
Praktyczna konsekwencja: src/api/AGENTS.md zostanie odczytany tylko wtedy, gdy Codex pracuje z src/api lub jednego z jego podkatalogów, a nie gdy zostanie uruchomiony z katalogu głównego. Puste pliki są ignorowane, a scalanie domyślnie zatrzymuje się przy 32 KiB (project_doc_max_bytes). Jeśli Twoje repozytorium używa już innej nazwy, np. TEAM_GUIDE.md, dodaj ją do project_doc_fallback_filenames w pliku ~/.codex/config.toml.
Aby zweryfikować, co Codex faktycznie załadował, po prostu zapytaj: codex --ask-for-approval never "Summarize the current instructions.". Codex odbudowuje łańcuch instrukcji przy każdym uruchomieniu: jeśli masz wątpliwości, uruchom go ponownie w odpowiednim katalogu.
Najlepsze praktyki dla AGENTS.md
Naczelną zasadą jest jawność. „Używaj Vitest, a nie Jesta“ jest lepsze niż „Używaj naszego frameworka testowego“, co zakłada wiedzę, której agent nie posiada. Zawsze dołączaj polecenia: bez nich Codex nie będzie wiedział, jak uruchomić Twoje testy, linter czy build, i dostarczy kod, którego nie mógł zweryfikować. Udokumentuj strukturę jako drzewo katalogów, co zapobiegnie jej ślepemu eksplorowaniu i tworzeniu plików w niewłaściwych miejscach.
Na koniec wymień zakazy. Zasady sformułowane jako „NIGDY“ są najbardziej opłacalne w tym pliku, ponieważ blokują kosztowne błędy, które trudno naprawić: commitowanie pliku .env, modyfikowanie schematu bez migracji. Najtrudniejszą dyscypliną jest utrzymanie pliku w aktualności. AGENTS.md opisujący projekt z zeszłego roku aktywnie kieruje Codex ku porzuconym konwencjom – co jest znacznie gorsze niż brak pliku, ponieważ błąd staje się wtedy systematyczny.
Kluczowe wnioski
- Wstępna konfiguracja wymaga konta OpenAI i połączenia z GitHub
- Rozszerzenie IDE i CLI instalują się w kilka minut
- AGENTS.md to najważniejszy plik dla efektywnego korzystania z Codex
- Zawiera konwencje, polecenia i zasady specyficzne dla Twojego projektu
- Pliki AGENTS.md w podkatalogach umożliwiają instrukcje kontekstowe