Przejdź do głównej treści
Polski— Wybierz język
Menu

Skonfiguruj środowisko i plik AGENTS.md

Lekcja 3 z 20 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Przygotuj projekt dla Codex
  2. Krok 1: Twój dostęp do Codex
  3. Krok 2: Zainstaluj rozszerzenie edytora
  4. Krok 3: Zainstaluj CLI
  5. Plik AGENTS.md – przewodnik po Twoim projekcie
  6. Najlepsze praktyki dla AGENTS.md
  7. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 na podstawie dokumentacji Codex (Codex CLI, Uwierzytelnianie, Rozszerzenie IDE Codex, Niestandardowe instrukcje z AGENTS.md): pakiet @openai/codex-cli oraz polecenie codex auth login nie istnieją (użyj npm install -g @openai/codex i codex login); identyfikator rozszerzenia to openai.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ć:

  1. Poziom globalny: W folderze Codex (~/.codex, chyba że zmienna CODEX_HOME to nadpisuje), Codex odczytuje AGENTS.override.md, jeśli istnieje, w przeciwnym razie AGENTS.md.
  2. 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.md lub, w razie jego braku, AGENTS.md.
  3. 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