Codex CLI: The Definitive Technical Reference

Codex działa jako wielopowierzchniowy agent programistyczny, a nie chatbot piszący kod. CLI odczytuje bazę kodu, wykonuje polecenia w sandboxie, modyfikuje pliki, łączy się z usługami zewnętrznymi przez MCP i deleguje długotrwałe zadania do chmury. Działa lokalnie, ale myśli globalnie — ta sama inteligencja napędza cztery odrębne powierzchnie w zależności od stylu pracy.

Różnica między przypadkowym a efektywnym używaniem Codex sprowadza się do pięciu kluczowych systemów. Opanowanie ich sprawia, że Codex staje się mnożnikiem produktywności:

1. System konfiguracji — kontroluje zachowanie poprzez config.toml
2. Sandbox i model zatwierdzania — określa, co Codex może wykonać
3. AGENTS.md — definiuje kontrakty operacyjne na poziomie projektu
4. Protokół MCP — rozszerza możliwości o usługi zewnętrzne
5. System skills — pakietuje wiedzę domenową do wielokrotnego użytku

Spędziłem miesiące, używając Codex równolegle z Claude Code w produkcyjnych bazach kodu, pipeline’ach CI/CD i przepływach pracy zespołowej. Ten przewodnik destyluje to doświadczenie w kompleksowe kompendium, które chciałbym mieć, gdy zaczynałem. Każda funkcja zawiera rzeczywistą składnię, prawdziwe przykłady konfiguracji oraz przypadki brzegowe, które potrafią zaskoczyć nawet doświadczonych użytkowników.

Uwaga dotycząca stabilności: Funkcje oznaczone [EXPERIMENTAL] mogą ulec zmianie między wydaniami. Codex Cloud oraz grupa poleceń MCP mają status eksperymentalny od wersji v0.101.0. Rdzeń CLI, sandbox, AGENTS.md, config.toml oraz Skills są stabilne.

Jak działa Codex: model mentalny

Zanim przejdziemy do omawiania funkcji, warto zrozumieć, jak architektura Codex kształtuje wszystko, co można z nim zrobić. System działa na czterech powierzchniach wspieranych przez wspólną warstwę inteligencji:

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                        │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │ │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                  │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (untrusted → never)        │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions              │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

Warstwa podstawowa (Core Layer): Rodzina modeli GPT-5.x-Codex napędza wszystko. Od wersji v0.101.0 domyślnym modelem jest gpt-5.3-codex z oknem kontekstowym o pojemności 272 tys. tokenów. Odczytuje pliki, tworzy poprawki (patch), wykonuje polecenia powłoki i analizuje bazę kodu. Gdy kontekst się zapełnia, Codex kompresuje konwersację, aby zwolnić miejsce. Ta warstwa zużywa tokeny.

Warstwa bezpieczeństwa (Security Layer): Każde polecenie wykonywane przez Codex przechodzi przez sandbox na poziomie systemu operacyjnego. W macOS framework Seatbelt firmy Apple wymusza ograniczenia na poziomie jądra. W systemie Linux Landlock + seccomp filtrują dostęp do systemu plików i wywołań systemowych. Nie jest to rozwiązanie oparte na kontenerach — jest wbudowane w system operacyjny. Polityka zatwierdzania (approval policy) określa następnie, kiedy wymagane jest potwierdzenie przez użytkownika.

Warstwa rozszerzeń (Extension Layer): MCP łączy się z zewnętrznymi usługami (GitHub, Figma, Sentry). Skills to pakiety wielokrotnego użytku, które Codex ładuje na żądanie. Apps łączą się z konektorami ChatGPT. Wyszukiwanie internetowe dodaje kontekst w czasie rzeczywistym z internetu.

Warstwa powierzchni (Surface Layer): CLI dla zaawansowanych użytkowników terminala i automatyzacji. Aplikacja desktopowa do wielowątkowego zarządzania projektem. Rozszerzenie IDE do cykli edycja-kompilacja-test. Cloud do asynchronicznych zadań uruchamianych niezależnie.

Kluczowa obserwacja: Większość użytkowników korzysta tylko z jednej powierzchni. Zaawansowani użytkownicy wykorzystują wszystkie cztery — Cloud do długotrwałych zadań, CLI do deterministycznych operacji na repozytorium, rozszerzenie IDE do ścisłych pętli kodowania i aplikację desktopową do planowania i koordynacji.

Spis treści

1. Jak zainstalować Codex?
2. Podstawowe powierzchnie interakcji
3. Szczegółowe omówienie systemu konfiguracji
4. Jaki model wybrać?
5. Ramy decyzyjne
6. Jak działa sandbox i system zatwierdzeń?
7. Jak działa AGENTS.md?
8. Czym jest MCP (Model Context Protocol)?
9. Czym są Skills?
10. Plan Mode i współpraca
11. Tryb nieinteraktywny (codex exec)
12. Codex Cloud i zadania w tle
13. Codex Desktop App
14. GitHub Action i CI/CD
15. Codex SDK
16. Ile kosztuje Codex?
17. Optymalizacja wydajności
18. Jak diagnozować problemy?
19. Wdrożenie w przedsiębiorstwie
20. Wskazówki i techniki społeczności
21. Przewodnik migracji
22. Karta szybkiego odniesienia
23. Dziennik zmian
24. Źródła

Jak zainstalować Codex?

Menedżery pakietów

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# Upgrade to latest
npm install -g @openai/codex@latest

Pliki binarne do pobrania

W środowiskach bez npm lub Homebrew można pobrać pliki binarne dla konkretnych platform z GitHub Releases¹:

Wymagania systemowe

• macOS: Apple Silicon lub Intel (pełne wsparcie sandbox poprzez Seatbelt)
• Linux: x86_64 lub arm64 (sandbox poprzez Landlock + seccomp)
• Windows: Eksperymentalne (WSL zalecane dla pełnego wsparcia sandbox)²

Uwierzytelnianie

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

Dostępne są dwie ścieżki uwierzytelniania:

1. Konto ChatGPT (zalecane): Logowanie za pomocą istniejącej subskrypcji Plus, Pro, Team, Business, Edu lub Enterprise. Pełny dostęp do funkcji, w tym zadań Cloud.
2. Klucz API: Ustawiany przez zmienną środowiskową CODEX_API_KEY lub codex login --with-api-key. Niektóre funkcje (wątki Cloud) mogą być niedostępne.

Wskazówka eksperta: Przechowywanie poświadczeń można konfigurować za pomocą cli_auth_credentials_store w config.toml. Dostępne opcje: file (domyślnie), keyring (systemowy pęk kluczy) lub auto (pęk kluczy, jeśli dostępny, w przeciwnym razie plik).

Uzupełnianie poleceń w powłoce

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

Weryfikacja instalacji

codex --version
# Codex CLI v0.101.0

Podstawowe powierzchnie interakcji

Codex udostępnia cztery odrębne interfejsy wspierane przez tę samą inteligencję. Każda powierzchnia jest zoptymalizowana pod kątem innego wzorca pracy.

1. Interaktywne CLI (Terminal UI)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.3-codex      # Specify model
codex --full-auto            # Workspace-write sandbox + on-request approval

Terminal UI to pełnoekranowa aplikacja z następującymi elementami:

• Kompozytor: Wpisywanie promptów, dołączanie plików za pomocą @, uruchamianie poleceń powłoki z prefiksem !
• Panel wyjściowy: Strumieniowe odpowiedzi modelu, wywołania narzędzi i wyniki poleceń
• Pasek statusu: Model, zużycie tokenów, gałąź git, tryb sandbox

Kluczowe skróty TUI:

Slash commands dostępne w TUI:

2. Codex Desktop App (macOS)

codex app                    # Launch desktop app (auto-installs if missing)

Aplikacja desktopowa oferuje funkcje niedostępne w CLI:

• Wielozadaniowość: Uruchamianie wielu równoległych agentów w różnych projektach jednocześnie
• Izolacja git worktree: Każdy wątek pracuje na odizolowanej kopii repozytorium
• Wbudowany przegląd różnic: Stagowanie, cofanie i zatwierdzanie zmian bez opuszczania aplikacji
• Zintegrowany terminal: Terminal dla każdego wątku do uruchamiania poleceń
• Rozwidlanie konwersacji: Rozgałęzianie konwersacji w celu eksplorowania alternatyw
• Pływające okna: Odczepianie konwersacji do przenośnych okien
• Automatyzacje: Planowanie cyklicznych zadań (triażowanie zgłoszeń, monitorowanie CI, reagowanie na alerty)

Kiedy używać aplikacji zamiast CLI: Aplikacja desktopowa sprawdza się przy koordynowaniu wielu strumieni pracy lub gdy potrzebny jest wizualny przegląd różnic. CLI jest lepsze, gdy zależy nam na komponowalności terminala, skryptach lub integracji z CI/CD.

3. Rozszerzenie IDE (VS Code, Cursor, Windsurf)

Rozszerzenie Codex IDE integruje się bezpośrednio z edytorem:

• Tryb agenta domyślnie: Odczytuje pliki, wprowadza zmiany, uruchamia polecenia
• Edycja inline: Kontekstowe sugestie w aktywnych plikach
• Współdzielone sesje: Sesje synchronizują się między CLI a rozszerzeniem IDE
• Wspólne uwierzytelnianie: Logowanie kontem ChatGPT lub kluczem API

Instalacja z VS Code Marketplace lub sklepów z rozszerzeniami Cursor/Windsurf.³

4. Codex Cloud [EKSPERYMENTALNE]

Zadania Cloud działają asynchronicznie w środowiskach zarządzanych przez OpenAI:

• Wyślij i zapomnij: Kolejkowanie zadań, które działają niezależnie od lokalnej maszyny
• Równoległe wykonywanie: Uruchamianie wielu zadań Cloud jednocześnie
• Tworzenie pull requestów: Codex tworzy pull requesty na podstawie ukończonej pracy
• Lokalne zastosowanie: Pobieranie wyników Cloud do lokalnego repozytorium za pomocą codex apply <TASK_ID>

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

Zadania Cloud są również dostępne z poziomu chatgpt.com/codex.⁴

Szczegółowe omówienie systemu konfiguracji

Codex używa formatu TOML do konfiguracji. Zrozumienie hierarchii priorytetów jest kluczowe — to ona określa, które ustawienia mają pierwszeństwo w przypadku konfliktów.

Priorytety (od najwyższego do najniższego)

1. Nadpisania sesji (najwyższy): flagi CLI (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) oraz nadpisania -c key=value
2. Konfiguracja projektu (.codex/config.toml, wyszukiwana od bieżącego katalogu w górę do korzenia projektu — wygrywa najbliższy katalog)
3. Konfiguracja użytkownika ($CODEX_HOME/config.toml, domyślnie ~/.codex/config.toml)
4. Konfiguracja systemowa (/etc/codex/config.toml w systemach Unix)
5. Wartości domyślne (najniższy)

Managed admin config działa jako warstwa ograniczeń polityki i może wymuszać lub zabraniać określonych wartości po standardowym scalaniu. Zobacz Wdrożenie korporacyjne.

Lokalizacje plików konfiguracyjnych

Wskazówka ekspercka: Zmienna środowiskowa CODEX_HOME nadpisuje domyślny katalog ~/.codex. Przydatne w środowiskach CI/CD lub przy konfiguracji wielu kont.

Kompletna dokumentacja konfiguracji

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.3-codex"                # Default model (272K context)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_reasoning_effort = "medium"       # low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.2-codex"         # Model for /review command
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # untrusted|on-failure|on-request|never

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output
log_dir = ""                            # Custom log directory

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
collaboration_modes = true              # Plan mode (stable)
personality = true                      # Personality selection (stable)
request_rule = true                     # Smart approvals (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
remote_models = true                    # Refresh remote model list (stable)
apps = false                            # ChatGPT Apps/connectors (experimental)
child_agents_md = false                 # AGENTS.md guidance (experimental)
runtime_metrics = false                 # Runtime summary in turns

# ─── Project Trust ─────────────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

Profile

Nazwane zestawy konfiguracji dla różnych trybów pracy:

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

Aktywacja profilu:

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

Wskazówka ekspercka: Można ustawić domyślny profil za pomocą profile = "fast" na najwyższym poziomie konfiguracji. Nadpisanie dla konkretnej sesji odbywa się przez --profile.

Niestandardowi dostawcy modeli

Połączenie z Azure, modelami lokalnymi lub usługami proxy:

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

Użycie modeli lokalnych z flagą --oss:

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

Lub ustawienie w konfiguracji:

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

Nadpisania konfiguracji w wierszu poleceń

Nadpisanie dowolnej wartości konfiguracyjnej bezpośrednio z wiersza poleceń:

codex -c model="gpt-5.2-codex" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

Który model wybrać?

Dostępne modele (luty 2026)

Dokładna lista modeli zależy od konta i etapu wdrożenia. Można sprawdzić lokalny cache: ~/.codex/models_cache.json.

Schemat wyboru modelu

Is this a quick fix or simple question?
├─ Yes → gpt-5.1-codex-mini (fastest, cheapest)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (interactive, lower latency)
   │  └─ No
   │     ├─ Is this a multi-file refactor or migration?
   │     │  ├─ Yes → gpt-5.2-codex (272K context, strong at long tasks)
   │     │  └─ No → gpt-5.3-codex (default, best overall)
   └─ Still unsure? → gpt-5.3-codex

Poziom reasoning

Kontrola nad intensywnością „myślenia” modelu przed udzieleniem odpowiedzi:

Dostępne poziomy zależą od modelu. Nie wszystkie modele obsługują każdy poziom.

codex -c model_reasoning_effort="xhigh" "find the race condition"

Wskazówka ekspercka: reasoning na poziomie xhigh może zużywać 3–5× więcej tokenów niż medium dla tego samego promptu. Należy rezerwować go dla naprawdę trudnych problemów, w których dodatkowe „myślenie” przynosi wymierne korzyści.

Przełączanie modeli

Zmiana modelu w trakcie sesji odbywa się za pomocą slash command /model lub ustawienia per sesja przez --model / -m:

codex -m gpt-5.3-codex-spark "pair with me on this component"

Ramy decyzyjne

Kiedy używać poszczególnych interfejsów

Kiedy używać poszczególnych trybów sandbox

Kiedy używać poszczególnych poziomów reasoning

Jak działa system sandbox i zatwierdzeń?

Codex wykorzystuje dwuwarstwowy model bezpieczeństwa, który oddziela to, co jest technicznie możliwe od tego, kiedy wymagane jest zatwierdzenie przez człowieka. Różni się to fundamentalnie od systemu uprawnień Claude Code — Codex wymusza ograniczenia na poziomie jądra systemu operacyjnego.⁵

Warstwa 1: Sandbox (co jest możliwe)

Sandbox kontroluje dostęp do systemu plików i sieci za pomocą natywnych mechanizmów systemu operacyjnego:

Wymuszanie specyficzne dla platformy:

• macOS: Framework Seatbelt firmy Apple poprzez sandbox-exec z profilami specyficznymi dla trybu, kompilowanymi w czasie wykonania i wymuszanymi przez jądro⁶
• Linux: Landlock do ograniczeń systemu plików + seccomp do filtrowania wywołań systemowych. Samodzielny proces pomocniczy (codex-linux-sandbox) zapewnia izolację w ramach obrony wielowarstwowej. Opcjonalnie dostępny potok Bubblewrap (bwrap) jako alternatywa⁷
• Windows: Eksperymentalny natywny sandbox z ograniczonymi tokenami. Zalecany WSL dla pełnego wsparcia sandbox (dziedziczy Linux Landlock + seccomp)

Dlaczego to istotne: W przeciwieństwie do sandboxingu opartego na kontenerach (Docker), sandboxing na poziomie systemu operacyjnego jest szybszy, lżejszy i trudniejszy do obejścia. Jądro wymusza ograniczenia, zanim Codex w ogóle zobaczy wywołanie systemowe.

Warstwa 2: Polityka zatwierdzeń (kiedy pytać)

Polityka zatwierdzeń określa, kiedy Codex wstrzymuje działanie, aby poprosić o potwierdzenie przez człowieka:

Flaga --full-auto

--full-auto to wygodny alias dla:

codex --sandbox workspace-write --ask-for-approval on-request

Istotna pułapka: --full-auto nadpisuje każdą jawną wartość --sandbox. Jeśli podasz --full-auto --sandbox read-only, uzyskasz workspace-write, ponieważ --full-auto ma pierwszeństwo.⁸

Zalecane konfiguracje

Codzienna praca deweloperska (bezpieczne ustawienie domyślne):

sandbox_mode = "workspace-write"
approval_policy = "on-request"

Zaawansowany użytkownik (pełny dostęp, człowiek w pętli decyzyjnej):

sandbox_mode = "danger-full-access"
approval_policy = "untrusted"

To rekomendowany przez społeczność „złoty środek” — maksymalne możliwości, ale zatwierdzenie wymagane dla każdego polecenia.⁹

Automatyzacja CI/CD:

sandbox_mode = "workspace-write"
approval_policy = "never"

Włączanie dostępu do sieci

Sieć jest domyślnie zablokowana w trybie workspace-write. Można ją włączyć w razie potrzeby:

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

Testowanie sandbox

Przed poleganiem na sandbox warto zweryfikować jego zachowanie:

codex sandbox macos --full-auto -- ls /etc/passwd   # macOS test
codex sandbox linux --full-auto -- cat /etc/shadow   # Linux test

Jak działa AGENTS.md?

AGENTS.md to system instrukcji projektowych Codex — otwarty standard¹⁰ wspierany przez Codex, Cursor, Amp, Jules (Google) i Factory. Definiuje, jak Codex powinien zachowywać się w ramach konkretnego repozytorium lub katalogu.

Hierarchia odkrywania

Codex buduje łańcuch instrukcji na początku sesji, przechodząc drzewo katalogów:

1. Globalny (~/.codex/): AGENTS.override.md > AGENTS.md
2. Projektowy (od korzenia git do bieżącego katalogu): Każdy poziom sprawdzany pod kątem AGENTS.override.md > AGENTS.md > nazwy zastępcze
3. Scalanie: Pliki są konkatenowane od korzenia w dół; bliższe pliki pojawiają się później w prompcie i nadpisują wcześniejsze wytyczne

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

Co sprawia, że AGENTS.md jest dobry

Na podstawie bezpośrednich wskazówek od samego Codex i wzorców ze społeczności¹¹:

TAK: - Bądź konkretny: "Use rg --files for discovery" jest lepsze niż "search efficiently" - Definiuj zakończenie: Co oznacza „gotowe”? (testy przechodzą, lint czysty itp.) - Podawaj polecenia: Build, test, lint, format — dokładne wywołania - Organizuj według zadań: Sekcje na kodowanie, przegląd, wydanie, incydent/debugowanie - Definiuj eskalację: Co robić, gdy pojawią się blokady lub nieoczekiwany stan

NIE: - Nie wrzucaj całych przewodników stylu bez reguł wykonania - Nie używaj niejednoznacznych dyrektyw („bądź ostrożny”, „optymalizuj”) - Nie mieszaj sprzecznych priorytetów (szybkość + wyczerpująca weryfikacja + brak budżetu czasowego) - Nie pisz dokumentacji opisowej — AGENTS.md to polityka operacyjna, nie README

Przykład: Produkcyjny AGENTS.md

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

Mechanizm nadpisywania

AGENTS.override.md na dowolnym poziomie katalogu zastępuje standardowy AGENTS.md dla danego zakresu. Zastosowania:

• Zamrożenie wydania: „Brak nowych funkcji, tylko poprawki”
• Tryb incydentu: „Wszystkie zmiany muszą być przejrzane przez dyżurnego”
• Tymczasowe utwardzenie: „Brak aktualizacji zależności w tym sprincie”

Konfiguracja

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

Generowanie szkieletu

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

Lub weryfikacja łańcucha instrukcji:

codex --ask-for-approval never "Summarize your current instructions"

Czym jest MCP (Model Context Protocol)? [experimental]

MCP rozszerza możliwości Codex, łącząc go z zewnętrznymi narzędziami i usługami. Grupa poleceń codex mcp jest obecnie oznaczona jako eksperymentalna — polecenia i format konfiguracji mogą ulec zmianie między wydaniami. Codex obsługuje dwa typy transportu: STDIO (procesy lokalne) i Streamable HTTP (serwery zdalne).¹²

Konfigurowanie serwerów MCP

Serwery STDIO (procesy lokalne):

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

Serwery HTTP (zdalne):

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

Zarządzanie przez CLI

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

W sesji: /mcp wyświetla aktywne serwery i dostępne narzędzia.

Uruchamianie Codex JAKO serwer MCP

Codex może udostępniać się jako serwer MCP do orkiestracji wieloagentowej:¹³

codex mcp-server                        # Start as MCP server (stdio transport)

Udostępnia to dwa narzędzia: 1. codex(): Rozpoczęcie nowej sesji z parametrami promptu, sandbox, modelu i zatwierdzeń 2. codex-reply(): Kontynuacja istniejącej sesji z threadId i promptem

Użycie z Agents SDK (Python):

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

Godne uwagi serwery MCP

Czym są skills?

Skills to wielokrotnego użytku, specyficzne dla zadań pakiety możliwości, które Codex ładuje na żądanie. Opierają się na otwartym standardzie agent skills.¹⁴

Struktura skill

my-skill/
  SKILL.md           (required — instructions)
  scripts/           (optional — executable scripts)
  references/        (optional — reference docs)
  assets/            (optional — images, icons)
  agents/openai.yaml (optional — metadata, UI, dependencies)

Lokalizacje odkrywania

Skills zainstalowane przez użytkownika są zarządzane w $CODEX_HOME/skills (domyślnie: ~/.codex/skills), w tym wbudowane skills systemowe w .system/. Codex obsługuje dowiązania symboliczne do folderów skills.

Tworzenie skill

Format SKILL.md:

---
name: security-audit
description: Run a comprehensive security audit on the codebase.
---

## Procedura audytu bezpieczeństwa

1. Skanowanie w poszukiwaniu zakodowanych na stałe sekretów za pomocą `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Sprawdzenie podatności na SQL injection: szukanie interpolacji ciągów znaków w zapytaniach
3. Weryfikacja walidacji danych wejściowych na wszystkich endpointach API
4. Sprawdzenie podatności zależności: `pip audit` lub `npm audit`
5. Przegląd wzorców uwierzytelniania i autoryzacji
6. Raportowanie wyników z poziomami ważności (Critical/High/Medium/Low)

Metadane (agents/openai.yaml):

interface:
  display_name: "Security Audit"
  short_description: "Comprehensive codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

Wywoływanie skills

• Jawne: menu /skills lub wzmianka $skill-name w prompcie
• Niejawne: Codex automatycznie wykrywa pasujące skills na podstawie opisu zadania (jeśli allow_implicit_invocation: true)
• Tworzenie: użycie $skill-creator do interaktywnego budowania nowego skilla
• Instalacja: użycie $skill-installer install <name> do instalacji skills społeczności

Włączanie/wyłączanie

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Plan mode i współpraca

Plan mode pozwala Codex zaprojektować podejście przed wprowadzeniem zmian. Jest domyślnie włączony (od wersji v0.94.0).¹⁵

Wchodzenie w plan mode

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

W plan mode Codex: - Czyta pliki i analizuje bazę kodu - Proponuje plan implementacji - Nie wprowadza zmian, dopóki nie zostaną zatwierdzone - Strumieniuje plan w dedykowanym widoku TUI

Steer mode

Steer mode (domyślnie włączony od wersji v0.98.0) umożliwia wstrzykiwanie nowych instrukcji podczas pracy Codex:

• Enter: natychmiast wysyła instrukcje podczas trwającej tury
• Tab: kolejkuje kontynuację na po zakończeniu bieżącej tury

Umożliwia to korektę kursu w czasie rzeczywistym bez zatrzymywania agenta.

Rozwidlanie konwersacji

Rozwidlanie konwersacji pozwala eksplorować alternatywy bez utraty bieżącego postępu:

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

Rozwidlenia tworzą niezależne wątki — zmiany w jednym rozwidleniu nie wpływają na drugie.

Tryb nieinteraktywny (codex exec)

codex exec uruchamia Codex nieinteraktywnie na potrzeby skryptów, CI/CD i automatyzacji.¹⁶

Podstawowe użycie

codex exec "summarize the repository structure"
codex exec --full-auto "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

Domyślnie codex exec zapisuje postęp/zdarzenia do stderr, a końcową wiadomość agenta do stdout. Dzięki temu jest komposowalny ze standardowymi potokami Unix.

Wyjście JSON Lines

Z flagą --json, stdout staje się strumieniem zdarzeń JSONL:

codex exec --json "fix the tests" | jq

Typy zdarzeń: thread.started, turn.started/completed/failed, item.started/completed, error

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

Strukturyzowane wyjście

Wymuszanie kształtu odpowiedzi za pomocą JSON Schema:

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

-o / --output-last-message zapisuje końcową wiadomość do pliku.

Wznawianie i przeglądanie sesji

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

Kluczowe flagi

Uwierzytelnianie w CI

codex exec obsługuje CODEX_API_KEY do nieinteraktywnego uwierzytelniania w środowiskach automatyzacji.

Codex Cloud i zadania w tle [EKSPERYMENTALNE]

Status: Codex Cloud jest funkcją eksperymentalną. Interfejsy, ceny i dostępność mogą ulec zmianie. Środowiska chmurowe są zarządzane przez OpenAI — użytkownik nie kontroluje infrastruktury.

Codex Cloud uruchamia zadania asynchronicznie w środowiskach zarządzanych przez OpenAI.⁴

Jak to działa

1. Przesłanie zadania (przez chatgpt.com/codex, integrację ze Slack lub CLI)
2. Codex klonuje repozytorium do izolowanego sandboxa w chmurze
3. Agent pracuje niezależnie — czyta kod, uruchamia testy, wprowadza zmiany
4. Po zakończeniu Codex tworzy PR lub udostępnia diff do przeglądu
5. Zastosowanie wyników lokalnie za pomocą codex apply <TASK_ID>

Dostęp do internetu w chmurze

Internet agenta jest domyślnie wyłączony i konfigurowany per środowisko:

• Wyłączony: brak dostępu agenta do internetu (domyślnie)
• Włączony: opcjonalna lista dozwolonych domen + ograniczenia metod HTTP

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

Skrypty konfiguracyjne mogą nadal korzystać z internetu do instalacji zależności, nawet gdy internet agenta jest wyłączony.

Integracja ze Slack

Wzmianka @Codex w kanale lub wątku Slack rozpoczyna zadanie w chmurze.

Wymagania wstępne: 1. Kwalifikujący się plan ChatGPT (Plus, Pro, Business, Enterprise lub Edu) 2. Połączone konto GitHub 3. Co najmniej jedno skonfigurowane środowisko chmurowe 4. Zainstalowana aplikacja Slack dla danego workspace’u

Codex odpowiada linkiem do zadania i publikuje wyniki po zakończeniu.

Cloud CLI

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

Codex Desktop App

Codex Desktop App (tylko macOS, Apple Silicon) zapewnia interfejs graficzny zoptymalizowany do zarządzania wieloma projektami.¹⁷

Instalacja

codex app                      # Auto-downloads and installs on first run

Lub bezpośrednie pobranie: Codex.dmg

Kluczowe funkcje

Automatyzacje

Automatyzacje działają lokalnie w aplikacji — aplikacja musi być uruchomiona, a projekt dostępny na dysku:

• W repozytoriach Git automatyzacje używają dedykowanych worktrees w tle
• W projektach bez Git uruchomienia odbywają się bezpośrednio w katalogu projektu
• Automatyzacje korzystają z domyślnych ustawień sandboxa

Przykładowe zastosowania: - Triażowanie zgłoszeń: automatyczna kategoryzacja i priorytetyzacja nowych zgłoszeń - Monitorowanie CI: obserwacja błędów kompilacji i sugerowanie poprawek - Reagowanie na alerty: reakcja na alerty monitoringu z analizą diagnostyczną - Aktualizacje zależności: sprawdzanie i aplikowanie poprawek bezpieczeństwa

Wyniki pojawiają się w kolejce do przeglądu w celu zatwierdzenia przez człowieka.

Wsparcie dla systemu Windows

Testy alfa dla Windows rozpoczęły się w lutym 2026. Rejestracja na stronie openai.com zapewnia wczesny dostęp.¹⁸

GitHub Action i CI/CD

Oficjalna GitHub Action integruje Codex z pipeline’em CI/CD.¹⁹

Podstawowe użycie

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

Opcje konfiguracji

Wyjście: final-message — końcowy tekst odpowiedzi Codex dla dalszych kroków/zadań.

Strategie bezpieczeństwa

Kontrola dostępu

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

Domyślnie: tylko współpracownicy z uprawnieniami zapisu mogą wyzwalać workflow Codex.

Codex SDK

TypeScript SDK umożliwia osadzenie możliwości agenta Codex w niestandardowych aplikacjach.²⁰

Instalacja

npm install @openai/codex-sdk

Podstawowe użycie

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

Zaawansowane funkcje SDK

• runStreamed(...): asynchroniczny strumień zdarzeń dla pośrednich aktualizacji
• outputSchema: wymuszanie końcowego wyniku w formacie JSON
• Dane multimodalne: przekazywanie tekstu i lokalnych obrazów ({ type: "local_image", path: "..." })

Konfiguracja wątku i klienta

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.2-codex" },
});

Sesje są przechowywane w katalogu ~/.codex/sessions.

Wymagania: Node.js 18+.

Ile kosztuje Codex?

Dostęp poprzez plany ChatGPT

Dostępność Codex zależy od planu ChatGPT i ustawień organizacji:

Limity planów i przepustowość mogą ulec zmianie. Aktualne uprawnienia można sprawdzić w ChatGPT i ustawieniach administratora.

Rozliczenia API

W przypadku korzystania z Codex poprzez API, użycie jest rozliczane za token zgodnie ze standardowym cennikiem OpenAI API dla wybranego modelu (z uwzględnieniem ewentualnych rabatów za buforowanie promptów). Aktualne stawki można sprawdzić na oficjalnej stronie z cennikiem API.

Strategie optymalizacji kosztów

1. Profile: można utworzyć profil fast z modelem gpt-5.1-codex-mini i ustawieniem model_reasoning_effort = "low" dla rutynowych zadań
2. Oszczędne użycie rozumowania: xhigh należy stosować wyłącznie do rzeczywiście trudnych problemów — zużywa 3–5x więcej tokenów
3. Flaga --ephemeral: pomijanie trwałości sesji w CI/CD w celu zmniejszenia narzutu
4. Minimalizacja podsumowań rozumowania: ustawienie model_reasoning_summary = "none", gdy wyjaśnienia nie są potrzebne
5. Tryb exec dla przetwarzania wsadowego: codex exec eliminuje narzut TUI w przypadku automatyzacji
6. Monitorowanie użycia: sprawdzanie /status w TUI oraz paneli rozliczeniowych organizacji

Optymalizacja wydajności

Zarządzanie kontekstem

Flagowe modele mają okna kontekstowe o pojemności 272K tokenów, ale zapełniają się szybciej, niż mogłoby się wydawać. Należy zarządzać kontekstem proaktywnie:

1. Regularne użycie /compact: podsumowuje historię konwersacji, zwalniając tokeny
2. Lokalna dokumentacja: dobrej jakości AGENTS.md i lokalna dokumentacja zmniejszają narzut eksploracji (który zużywa kontekst)
3. Załączanie plików za pomocą @: odwoływanie się bezpośrednio do plików zamiast proszenia Codex o ich wyszukanie
4. Skupione prompty: precyzyjne prompty z konkretnymi plikami zużywają mniej kontekstu niż otwarte eksploracje

Efektywność tokenowa

Optymalizacja szybkości

1. gpt-5.3-codex-spark: wariant o niższym opóźnieniu do interaktywnego programowania w parze
2. --profile fast: wstępnie skonfigurowany mini model z niskim poziomem rozumowania
3. Równoległe wykonywanie narzędzi: Codex uruchamia niezależne odczyty/sprawdzenia jednocześnie — prompty należy formułować tak, aby to umożliwić
4. Pętle zorientowane na wynik: lepiej prosić o „zaimplementuj, przetestuj, napraw, zakończ gdy testy przejdą” zamiast instrukcji krok po kroku

Jak debugować problemy?

Częste problemy i rozwiązania

Narzędzia diagnostyczne

codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

Diagnostyka w sesji TUI:

/status                                # Token/session overview
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

Uwaga: codex --verbose nie jest prawidłową flagą najwyższego poziomu. Należy korzystać z powyższych podpoleceń debug i diagnostyki TUI.

Czysta reinstalacja

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

Tryb debugowania

codex debug app-server send-message-v2  # Test app-server client

Zgłaszanie problemów

/feedback                              # Send logs to Codex maintainers (in TUI)

Problemy można również zgłaszać na stronie github.com/openai/codex/issues.¹

Wdrożenie w przedsiębiorstwie

Kontrole administracyjne (managed admin config)

Polityka korporacyjna jest egzekwowana poprzez managed admin config (na poziomie systemu), który może wymuszać bezpieczne tryby wykonywania i ograniczać ustawienia użytkowników:²²

# /etc/codex/managed-admin-config.toml

model_reasoning_effort = "high"
model_reasoning_summary = "auto"
model = "gpt-5.3-codex"

require_approval = "untrusted"
require_sandbox = "workspace-write"

Managed admin config działa jako warstwa ograniczeń — wymusza lub zabrania wartości po normalnym scalaniu konfiguracji, a nie jako kolejny poziom nadpisywania.

Konfiguracja macOS MDM

Dystrybucja poprzez MDM z wykorzystaniem domeny preferencji com.openai.codex:

Integracja z OpenTelemetry

Codex obsługuje propagację kontekstu śledzenia OpenTelemetry ze standardowych zmiennych środowiskowych OTel do wywołań OpenAI API. Konfigurację OTel należy przeprowadzić w stosie runtime/kolektora:

• Standardowe zmienne środowiskowe OTEL_* są respektowane
• Kontekst śledzenia jest propagowany przez Codex do wywołań API
• Przy włączaniu logowania promptów/narzędzi należy uwzględnić wymagania dotyczące prywatności

Dostęp korporacyjny

• ChatGPT Business / Enterprise / Edu: dostęp kontrolowany przez administratora organizacji
• API: standardowa autoryzacja API, rozliczenia i kontrole organizacji/projektu
• Codex SDK: osadzanie w wewnętrznych narzędziach i przepływach pracy
• Managed config: użycie managed config + managed admin config do egzekwowania polityk na dużą skalę

Wskazówki i techniki społeczności

Wzorce promptów

1. Prompty oparte na ograniczeniach: na początku należy podać granice — „NIE zmieniaj kontraktów API. Refaktoryzuj wyłącznie wewnętrzną implementację.”
2. Ustrukturyzowane kroki reprodukcji: numerowane kroki dają lepsze poprawki błędów niż niejasne opisy
3. Prośby o weryfikację: zakończenie promptu zdaniem „Uruchom lint + najmniejszy odpowiedni zestaw testów. Zgłoś polecenia i wyniki.”
4. Odwołania do plików: użycie @filename do załączania konkretnych plików do kontekstu
5. Pętle zorientowane na wynik: „Zaimplementuj, uruchom testy, napraw błędy, zakończ dopiero gdy wszystkie testy przejdą” — Codex iteruje aż do osiągnięcia celu

Filozofia testowania

Społeczność zbieżnie stosuje podejście testowe we współpracy z AI:²³

• Definiowanie testów z góry jako sygnałów ukończenia
• Pozwolenie Codex na iterowanie do momentu przejścia testów (red → green → refactor)
• Stosowanie wzorców programowania Tiger Style
• Podawanie dokładnego tekstu pliku przy proszeniu o łatki — Codex używa ścisłego dopasowania, a nie rozmytego łatania opartego na AST

Najlepsze praktyki zarządzania kontekstem

• Dostarczanie wysokiej jakości lokalnej dokumentacji zamiast polegania na wyszukiwaniu w sieci
• Utrzymywanie ustrukturyzowanego markdownu ze spisami treści i plikami postępu („progresywne ujawnianie”)
• Normalizacja końców wierszy (LF vs CRLF) we wszystkich śledzonych plikach w celu zapobiegania niepowodzeniom łatek
• Zwięzły plik AGENTS.md — długie instrukcje są wypychane poza kontekst

Przepływ pracy z Git

• Zawsze należy utworzyć nową gałąź przed uruchomieniem Codex na nieznanym repozytorium
• Stosowanie przepływów opartych na łatkach (git diff / git apply) zamiast bezpośrednich edycji
• Przeglądanie sugestii Codex tak jak recenzja kodu w pull requestach
• Użycie /diff do weryfikacji zmian przed commitowaniem

Skills i prompty społeczności

Repozytorium feiskyer/codex-settings zawiera sprawdzone w boju konfiguracje:²⁴

Prompty wielokrotnego użytku (w ~/.codex/prompts/): - deep-reflector: wyciąganie wniosków z sesji deweloperskich - github-issue-fixer [issue-number]: systematyczna analiza błędów i tworzenie PR - github-pr-reviewer [pr-number]: przepływy pracy recenzji kodu - ui-engineer [requirements]: tworzenie frontendów na poziomie produkcyjnym

Skills społeczności: - claude-skill: przekazywanie zadań do Claude Code z trybami uprawnień - autonomous-skill: automatyzacja zadań w wielu sesjach ze śledzeniem postępu - deep-research: równoległa orkiestracja podzadań - kiro-skill: pipeline wymagania → projektowanie → zadania → realizacja

Przewodnik migracji

Z Claude Code

Kluczowe różnice do zrozumienia:

• Sandbox działa na poziomie systemu operacyjnego: Codex wykorzystuje Seatbelt/Landlock, a nie kontenery. Ograniczenia są trudniejsze do obejścia.
• Brak hooks: Codex nie posiada bezpośredniego odpowiednika 1:1 dla hooks w Claude Code. Zamiast tego należy użyć instrukcji w AGENTS.md lub skills.
• Brak subagentów: Codex nie posiada bezpośredniego lokalnego modelu subagentów 1:1. Do delegowania zadań należy użyć zadań w chmurze lub orkiestracji SDK.
• AGENTS.md działa między narzędziami: AGENTS.md działa również w Cursor, Amp i Jules. CLAUDE.md jest wyłącznie dla Claude.
• Profile zastępują ręczne przełączanie: Zamiast zmieniać flagi przy każdym uruchomieniu, można zdefiniować profile w config.toml.

Z GitHub Copilot

Co zyskujesz: - Pełne możliwości agentowe (edycja plików, wykonywanie poleceń, operacje git) - Delegowanie zadań do chmury - Sandboxing na poziomie systemu operacyjnego - Integracje MCP

Z Cursor

Karta szybkiego odniesienia

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --full-auto                workspace-write + on-request      ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /init        AGENTS.md scaffold  ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --full-auto "task"          Sandboxed auto        ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [experimental]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers                ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  managed-admin-config.toml   Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-failure    Auto-run until failure                         ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (Feb 2026)                                            ║
║  gpt-5.3-codex         Default flagship (272K)               ║
║  gpt-5.3-codex-spark   Interactive, lower latency (128K)     ║
║  gpt-5.2-codex         Long-horizon refactors (272K)         ║
║  gpt-5.1-codex-mini    Quick tasks, cost-efficient (272K)    ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Dziennik zmian

Przypisy