Codex CLI: The Definitive Technical Reference

TL;DR: Codex to wielopowierzchniowy agent programistyczny, który odczytuje bazę kodu, wykonuje polecenia w piaskownicy na poziomie systemu operacyjnego, modyfikuje pliki i deleguje zadania do chmury. Wystarczy opanować pięć podstawowych systemów (config.toml, model piaskownicy/zatwierdzeń, AGENTS.md, MCP oraz skills), a Codex stanie się mnożnikiem produktywności. Profiles umożliwiają przełączanie kontekstu, /compact pozwala zarządzać budżetem 272K tokenów, a AGENTS.md służy jako międzynarzędziowa instrukcja projektowa działająca w Codex, Cursor, Amp i innych narzędziach.

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

Różnica między zwykłym a efektywnym korzystaniem z Codex sprowadza się do pięciu podstawowych systemów. Po ich opanowaniu Codex staje się mnożnikiem produktywności:

1. System konfiguracji: steruje zachowaniem przez config.toml
2. Model piaskownicy i zatwierdzeń: kontroluje, co Codex może wykonać
3. AGENTS.md: definiuje kontrakty operacyjne na poziomie projektu
4. Protokół MCP: rozszerza możliwości o zewnętrzne usługi
5. System skills: pakietyzuje 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 zespołowych przepływach pracy. Ten przewodnik stanowi destylat tego doświadczenia — kompletną referencję, jakiej sam szukałem na początku. 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.107.0. Podstawowe elementy — CLI, piaskownica, AGENTS.md, config.toml i Skills — są stabilne.

Najważniejsze wnioski

• Cztery interfejsy, jeden mózg: CLI, aplikacja desktopowa, rozszerzenie IDE i zadania w chmurze — wszystkie korzystają z tej samej inteligencji GPT-5.x-Codex, więc wystarczy wybrać interfejs pasujący do danego przepływu pracy.
• Sandboxing na poziomie systemu operacyjnego: Codex wymusza ograniczenia systemu plików i sieci na poziomie jądra (Seatbelt na macOS, Landlock + seccomp na Linux), a nie wewnątrz kontenerów.
• AGENTS.md działa między narzędziami: Instrukcje projektowe działają w Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed oraz w ponad 60 000 projektów open source. Wystarczy napisać raz i używać wszędzie.
• Profile oszczędzają czas przy przełączaniu kontekstu: Można zdefiniować nazwane presety konfiguracji (fast, careful, auto) i przełączać się między nimi za pomocą --profile.
• 272K tokenów kontekstu wejściowego szybko się zapełnia: Należy korzystać z /compact, precyzyjnych promptów i referencji @file, aby proaktywnie zarządzać budżetem tokenów.

Jak korzystać z tego przewodnika

To ponad 2500 wierszy materiału referencyjnego — najlepiej zacząć od poziomu odpowiadającego własnemu doświadczeniu:

Karta szybkiego odniesienia na końcu zawiera skrócone podsumowanie wszystkich najważniejszych poleceń.

Jak działa Codex: model mentalny

Przed zagłębieniem się w funkcje warto zrozumieć, jak architektura Codex kształtuje wszystko, co można z nim zrobić. System działa na czterech interfejsach wspieranych przez współdzieloną 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 zasila wszystko. Od wersji v0.107.0 domyślnym modelem jest gpt-5.3-codex z oknem kontekstu wejściowego 272K tokenów (128K wyjściowych, łączny budżet 400K).³⁵ Model czyta pliki, tworzy łatki, wykonuje polecenia powłoki i rozumuje nad bazą kodu. Gdy kontekst się zapełnia, Codex kompaktuje konwersację, aby zwolnić miejsce. Ta warstwa zużywa tokeny.

Warstwa bezpieczeństwa (Security Layer): Każde polecenie uruchamiane przez Codex przechodzi przez sandbox na poziomie systemu operacyjnego. Na macOS framework Seatbelt firmy Apple wymusza ograniczenia na poziomie jądra. Na Linux Landlock + seccomp filtrują dostęp do systemu plików i wywołań systemowych. Sandbox działa na poziomie jądra, a nie wewnątrz kontenerów. Następnie polityka zatwierdzania (approval policy) decyduje, kiedy prosić o potwierdzenie ze strony użytkownika.

Warstwa rozszerzeń (Extension Layer): MCP łączy zewnętrzne usługi (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 interfejsów (Surface Layer): CLI dla zaawansowanych użytkowników terminala i automatyzacji. Aplikacja desktopowa do wielowątkowego zarządzania projektami. Rozszerzenie IDE do pętli edycja-kompilacja-testowanie. Chmura do zadań asynchronicznych działających niezależnie.

Kluczowa obserwacja: Większość użytkowników korzysta tylko z jednego interfejsu. Zaawansowani użytkownicy używają wszystkich czterech: chmury do długotrwałych zadań, CLI do deterministycznych operacji na repozytorium, rozszerzenia IDE do ścisłych pętli programowania oraz aplikacji desktopowej do planowania i koordynacji.

Spis treści

1. Jak zainstalować Codex?
2. Szybki start: pierwsza sesja
3. Podstawowe interfejsy interakcji
4. System konfiguracji — szczegółowe omówienie
5. Który model wybrać?
6. Ile kosztuje Codex?
7. Ramki decyzyjne
8. Jak działa sandbox i system zatwierdzeń?
9. Jak działa AGENTS.md?
10. Hooks
11. Czym jest MCP (Model Context Protocol)?
12. Środowisko uruchomieniowe JavaScript REPL
13. Czym są Skills?
14. Tryb planowania i współpraca
15. System pamięci
16. Zarządzanie sesjami
17. Tryb nieinteraktywny (codex exec)
18. Codex Cloud i zadania w tle
19. Aplikacja desktopowa Codex
20. GitHub Action i CI/CD
21. Codex SDK
22. Optymalizacja wydajności
23. Jak debugować problemy?
24. Wdrożenie enterprise
25. Najlepsze praktyki i antywzorce
26. Przepisy na przepływy pracy
27. Przewodnik migracji
28. Karta szybkiego odniesienia
29. Dziennik zmian
30. Odniesienia

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

Skrypt bezpośredniej instalacji (v0.106.0+)

Dla macOS i Linux dostępny jest jednolinijkowy skrypt instalacyjny jako zasób wydania na GitHub:⁶²

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

Skrypt automatycznie wykrywa platformę i architekturę, pobiera odpowiedni plik binarny i umieszcza go w ścieżce PATH.

Pobieranie plików binarnych

W środowiskach bez npm lub Homebrew można pobrać pliki binarne dla konkretnej platformy z wydań na GitHub¹:

Wymagania systemowe

• macOS: Apple Silicon lub Intel (pełne wsparcie sandboxa przez Seatbelt)
• Linux: x86_64 lub arm64 (sandbox przez Landlock + seccomp)
• Windows: Natywny sandbox z ograniczonymi tokenami (awansowany z wersji eksperymentalnej w v0.100.0). WSL również obsługiwany²

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

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ń w chmurze.
2. Klucz API: Ustawiany przez zmienną środowiskową CODEX_API_KEY lub codex login --with-api-key. Niektóre funkcje (wątki w chmurze) mogą być niedostępne.

Wskazówka ekspercka: Sposób przechowywania danych uwierzytelniających można skonfigurować za pomocą cli_auth_credentials_store w config.toml. Opcje: file (domyślnie), keyring (pęk kluczy systemu operacyjnego) 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.104.0

Szybki start: pierwsza sesja

Od zera do produktywności w 5 minut.

1. Instalacja i uwierzytelnianie:

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. Przejście do projektu:

cd ~/my-project                  # Any git repo works

3. Uruchomienie Codex:

codex

Pojawi się interaktywny TUI. Codex automatycznie odczytuje strukturę projektu.

4. Zadanie pytania:

> What does this project do? Summarize the architecture.

Codex odczytuje kluczowe pliki i wyjaśnia strukturę bazy kodu. W domyślnym trybie suggest żadne zmiany nie są wprowadzane.

5. Wprowadzanie zmian:

> Add input validation to the login endpoint

Codex proponuje edycje w formie diffa. Można je zatwierdzić klawiszem y lub odrzucić klawiszem n.

6. Użycie slash commands:

> /plan Refactor the database layer to use connection pooling

Codex tworzy plan bez jego wykonywania. Po przejrzeniu planu można go zatwierdzić, aby rozpocząć realizację.

7. Sprawdzenie wyników:

> /diff

Wyświetlenie wszystkich zmian wprowadzonych przez Codex w bieżącej sesji.

Co dalej: - Konfiguracja AGENTS.md z instrukcjami projektowymi (zob. Jak działa AGENTS.md?) - Skonfigurowanie profilu dla własnego przepływu pracy (zob. Profile) - Wypróbowanie codex exec do nieinteraktywnej automatyzacji (zob. Tryb nieinteraktywny)

Główne powierzchnie interakcji

Codex udostępnia cztery odrębne interfejsy oparte na tej samej inteligencji. Każda powierzchnia jest zoptymalizowana pod kątem innego wzorca pracy.

1. Interaktywny 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 zawierająca:

• 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 stanu: 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 możliwości niedostępne w CLI:

• Wielozadaniowość: Równoczesne uruchamianie wielu równoległych agentów w różnych projektach
• Izolacja za pomocą git worktree: Każdy wątek pracuje na odizolowanej kopii repozytorium
• Wbudowany przegląd diffów: Stagowanie, cofanie i commitowanie zmian bez opuszczania aplikacji
• Zintegrowany terminal: Terminal dedykowany dla każdego wątku do uruchamiania poleceń
• Rozgałęzianie rozmów: Tworzenie odgałęzień rozmów w celu eksploracji alternatyw
• Pływające okna pop-out: Odczepianie rozmów do przenośnych okien
• Automatyzacje: Planowanie cyklicznych zadań (triage zgłoszeń, monitoring CI, reakcja na alerty)

Kiedy używać aplikacji a kiedy CLI: Aplikacja desktopowa sprawdza się przy koordynacji wielu strumieni pracy lub gdy potrzebny jest wizualny przegląd diffów. CLI jest lepszym wyborem, gdy zależy nam na kompozycji terminalowej, skryptowaniu 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: Odczytywanie plików, wprowadzanie edycji, uruchamianie poleceń
• Edycje inline: Sugestie uwzględniające kontekst w aktywnych plikach
• Współdzielone sesje: Sesje synchronizowane między CLI a rozszerzeniem IDE
• Wspólne uwierzytelnianie: Logowanie kontem ChatGPT lub kluczem API

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

4. Codex Cloud [EXPERIMENTAL]

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

• Wyślij i zapomnij: Kolejkowanie zadań działających niezależnie od maszyny lokalnej
• Równoległe wykonywanie: Jednoczesne uruchamianie wielu zadań w chmurze
• Tworzenie PR: Codex tworzy pull requesty z ukończonych prac
• Lokalne zastosowanie: Pobieranie wyników z chmury 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 w chmurze są również dostępne na chatgpt.com/codex.⁴

Szczegółowe omówienie systemu konfiguracji

Codex używa formatu TOML do konfiguracji. Zrozumienie hierarchii priorytetów jest kluczowe, ponieważ określa ona, 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 katalogu głównego 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. Wbudowane wartości domyślne (najniższy)

requirements.toml działa jako warstwa ograniczeń polityki, która ogranicza wartości dostępne dla użytkowników po standardowym scaleniu konfiguracji. 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 input context)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|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 ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[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
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── 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)
command_attribution = true              # Codex co-author in commits (v0.103.0+)
request_user_input = true               # Allow agent to ask clarifying questions in Default mode (v0.106.0+)
multi_agent = false                     # Enable multi-agent collaboration tools (v0.102.0+)
apply_patch_freeform = false            # Expose freeform apply_patch tool
apps = false                            # ChatGPT Apps/connectors (experimental)
child_agents_md = false                 # AGENTS.md guidance (experimental)
runtime_metrics = false                 # Runtime summary in turns
search_tool = false                     # Enable search_tool_bm25 for Apps discovery

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

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

Profile

Nazwane zestawy konfiguracji do 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 poszczególnych sesji odbywa się za pomocą --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"

Uwaga: Protokół chat/completions wire API (wire_api = "chat") został wycofany dla modeli hostowanych przez OpenAI — OpenAI ogłosiło usunięcie w lutym 2026.³⁶ Lokalni dostawcy (Ollama, LM Studio) mogą nadal akceptować ten format. Dla endpointów OpenAI należy używać wire_api = "responses".

Użycie modeli lokalnych za pomocą flagi --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"

Nadpisywanie konfiguracji w wierszu poleceń

Nadpisanie dowolnej wartości konfiguracyjnej z poziomu 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 różni się w zależności od konta i etapu wdrożenia. Od wersji v0.106.0, gpt-5.3-codex jest widoczny na liście modeli CLI dla użytkowników z kluczem API.⁶² Sprawdź lokalną pamięć podręczną: ~/.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 rozumowania

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

Obsługiwane poziomy zależą od modelu. minimal jest dostępny wyłącznie dla modeli GPT-5. Nie wszystkie modele obsługują każdy poziom.

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

Wskazówka eksperta: rozumowanie na poziomie xhigh może zużyć 3-5x więcej tokenów niż medium dla tego samego promptu. Należy go zarezerwować dla naprawdę trudnych problemów, w których dodatkowe przetwarzanie się opłaca.

Przełączanie modeli

Modele można przełączać w trakcie sesji za pomocą slash command /model lub ustawić dla pojedynczego uruchomienia przez --model / -m:

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

Ile kosztuje Codex?

Zobacz także Wybór modelu w zakresie możliwości oraz Ramy decyzyjne w zakresie wyboru odpowiedniego modelu do zadania.

Dostęp przez plany ChatGPT

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

Stawki promocyjne: dostęp Free/Go oraz podwójne limity dla płatnych planów zbiegły się z premierą Codex Desktop App (luty 2026). Te wyższe limity obowiązują na wszystkich platformach — aplikacja, CLI, IDE i chmura. OpenAI nie ogłosiło daty zakończenia promocji.¹⁷

Koszty kredytów

Operacje Codex zużywają kredyty z przydziału planu:

Plany Enterprise i Edu skalują kredyty zgodnie z przydziałem kontraktowym. Sprawdź /status w TUI, aby zobaczyć bieżące zużycie.

Rozliczenia API

Podczas korzystania z Codex przez API OpenAI nalicza opłaty za zużycie na podstawie tokenów, 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 cenami API.²¹

Strategie optymalizacji kosztów

1. Używaj profili: utwórz profil fast z modelem gpt-5.1-codex-mini i model_reasoning_effort = "low" do rutynowych zadań
2. Zarezerwuj wysoki poziom rozumowania: używaj xhigh wyłącznie do naprawdę trudnych problemów, ponieważ kosztuje 3-5x więcej tokenów
3. Używaj --ephemeral: pomiń trwałość sesji w CI/CD, aby zmniejszyć obciążenie
4. Minimalizuj podsumowania rozumowania: ustaw model_reasoning_summary = "none", gdy nie potrzebujesz wyjaśnień
5. Grupuj z trybem exec: codex exec eliminuje obciążenie TUI w przepływach automatyzacji
6. Monitoruj zużycie: sprawdzaj /status w TUI oraz panele rozliczeniowe organizacji

Realne przykłady kosztów

Reprezentatywne koszty API dla typowych zadań (gpt-5.3-codex w standardowym cenniku, rozumowanie medium):

Koszty różnią się w zależności od poziomu rozumowania, buforowania i długości konwersacji. Używaj gpt-5.1-codex-mini do rutynowych zadań, aby obniżyć koszty o ~40-60%. Buforowane tokeny wejściowe są rozliczane z rabatem.

Ukryty narzut tokenowy

Każde wywołanie narzędzia dodaje tokeny wykraczające poza widoczny prompt:

Wskazówka eksperta: monitoruj rzeczywiste zużycie przez /status w TUI. Liczba tokenów obejmuje cały narzut, nie tylko widoczne wiadomości. Jeśli koszty są zaskakująco wysokie, sprawdź liczbę podłączonych serwerów MCP — każdy dodaje definicje narzędzi do każdego wywołania API.

Zarządzanie kosztami zespołu

Strategie kontroli kosztów zespołu: - Ustaw requirements.toml, aby wymusić limity modeli i poziomu rozumowania w całej organizacji - Używaj gpt-5.1-codex-mini dla CI/CD — zautomatyzowane potoki rzadko potrzebują maksymalnego rozumowania - Budżetowanie oparte na profilach — zdefiniuj profile ci, review i dev z odpowiednimi pułapami kosztów - Monitorowanie przez OpenTelemetry — wdrożenia enterprise mogą eksportować telemetrię zużycia do istniejących stosów obserwacyjnych

Ramki decyzyjne

Kiedy używać poszczególnych interfejsów

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

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

Tryb planowania a bezpośrednie wykonanie

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Steer Mode: Enter a Tab

Zasada ogólna: Enter = „zatrzymaj się, posłuchaj tego teraz.” Tab = „kiedy skończysz, zrób też to.”

Desktop App a CLI

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

Który profil?

Dopasuj zadanie do wstępnie skonfigurowanego profilu:

Konfiguracja config.toml:

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Przełączanie profilu na sesję: codex --profile careful

Jak działa system sandbox i zatwierdzania?

Codex wykorzystuje dwuwarstwowy model bezpieczeństwa, który oddziela to, co jest technicznie możliwe od momentu, w którym Codex prosi o zatwierdzenie przez człowieka. Podejście to różni się fundamentalnie od systemu uprawnień Claude Code — Codex wymusza ograniczenia na poziomie jądra systemu operacyjnego.⁵ Zobacz również Wdrożenia korporacyjne dla ograniczeń w requirements.toml, które administratorzy wymuszają w całej organizacji.

Warstwa 1: Sandbox (co jest możliwe)

Sandbox kontroluje dostęp do systemu plików i sieci przy użyciu 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. Oddzielny proces pomocniczy (codex-linux-sandbox) zapewnia izolację w modelu obrony wielowarstwowej.⁵ Bubblewrap (bwrap) jest dołączany i kompilowany jako część kompilacji dla systemu Linux (awansowany z opcjonalnego w v0.100.0)⁷
• Windows: Natywny sandbox z ograniczonymi tokenami (awansowany z eksperymentalnego w v0.100.0). WSL jest również obsługiwany (dziedziczy Landlock + seccomp z systemu Linux)

Dlaczego to ma znaczenie: 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.

Poprawki bezpieczeństwa: - Obejście sandboxa przez fork zsh (v0.106.0): Naprawiono lukę, w której wykonanie powłoki przez forkowanie zsh mogło obejść ograniczenia sandboxa.⁶² W przypadku korzystania z wcześniejszej wersji należy natychmiast zaktualizować. - Limit rozmiaru danych wejściowych (v0.106.0): Codex wymusza teraz limit około 1 miliona znaków na dane wejściowe, aby zapobiec zawieszaniu się przy nadmiernie dużych danych.⁶² - System plików /dev w systemie Linux (v0.105.0): Polecenia w sandboxie na Linuksie otrzymują teraz minimalny system plików /dev, co poprawia kompatybilność z narzędziami oczekującymi węzłów urządzeń.⁶³

Polityka ReadOnlyAccess (v0.100.0+): Konfigurowalna polityka zapewniająca szczegółową kontrolę dostępu do odczytu. Służy do ograniczania katalogów, z których Codex może czytać, nawet w trybie workspace-write:

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

Warstwa 2: Polityka zatwierdzania (kiedy pytać)

Polityka zatwierdzania określa, kiedy Codex wstrzymuje się, aby poprosić o potwierdzenie ze strony człowieka:

Unikalne identyfikatory zatwierdzania (v0.104.0+)

Codex przypisuje teraz unikalne identyfikatory zatwierdzania do każdego polecenia w ramach wieloetapowego wykonywania powłoki. Oznacza to, że zatwierdzenia są szczegółowe — zatwierdzenie jednego polecenia w sekwencji nie oznacza automatycznego zatwierdzenia kolejnych w tej samej sesji powłoki.⁵¹

Elastyczne mechanizmy zatwierdzania (v0.105.0+)

Proces zatwierdzania obsługuje teraz dodatkowe uprawnienia sandboxa i szczegółowe odrzucanie:⁶³

• Dodatkowe uprawnienia sandboxa: Gdy polecenie wymaga dostępu wykraczającego poza bieżący tryb sandboxa, Codex może zażądać konkretnych dodatkowych uprawnień zamiast wymagać pełnej zmiany trybu
• Szczegółowe odrzucanie: Odrzucanie poszczególnych wywołań narzędzi z informacją zwrotną, dzięki czemu Codex może dostosować swoje podejście zamiast po prostu powtarzać to samo polecenie

Flaga --full-auto

--full-auto to wygodny alias dla:

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

Ważna uwaga: --full-auto nadpisuje każdą jawną wartość --sandbox. Jeśli zostanie przekazane --full-auto --sandbox read-only, wynikiem będzie workspace-write, ponieważ --full-auto ma pierwszeństwo.⁸

Zalecane konfiguracje

Codzienne programowanie (bezpieczne ustawienie domyślne):

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

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

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

Ta kombinacja jest rekomendowanym przez społeczność optymalnym rozwiązaniem: 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

Codex domyślnie blokuje dostęp do sieci w trybie workspace-write. Należy go 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

Obsługa proxy WebSocket (v0.104.0+)

W środowiskach korporacyjnych, które kierują ruch WebSocket przez proxy, Codex obsługuje teraz zmienne środowiskowe WS_PROXY i WSS_PROXY:⁵¹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

Uzupełniają one istniejącą obsługę proxy HTTPS_PROXY i SOCKS5 (v0.93.0+), obejmując wszystkie warstwy transportu.

Testowanie sandboxa

Przed zaufaniem sandboxowi należy zweryfikować jego zachowanie:

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

Jeśli sandbox działa prawidłowo, oba polecenia powinny zakończyć się błędem odmowy dostępu — sandbox uniemożliwia odczyt wrażliwych plików systemowych nawet w trybie --full-auto. Jeśli którekolwiek polecenie się powiedzie, konfiguracja sandboxa wymaga zbadania.

Jak działa AGENTS.md?

AGENTS.md to system instrukcji projektowych Codex — otwarty standard¹⁰ zarządzany obecnie przez Agentic AI Foundation w ramach Linux Foundation. Obsługiwany przez Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode oraz ponad 60 000 projektów open source. Definiuje sposób, w jaki Codex zachowuje się w ramach konkretnego repozytorium lub katalogu. Zobacz Skills dla pakietów wiedzy eksperckiej wielokrotnego użytku, które uzupełniają AGENTS.md.

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 (korzeń git do bieżącego katalogu): Każdy poziom sprawdzany pod kątem AGENTS.override.md > AGENTS.md > nazwy zastępcze
3. Scalanie: Pliki są łączone od korzenia w dół; pliki bliższe 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 tworzy dobry plik AGENTS.md

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

NALEŻY: - Być konkretnym: "Use rg --files for discovery" jest lepsze niż "search efficiently" - Definiować zakończenie: Co oznacza „gotowe”? (testy przechodzą, linting czysty itp.) - Zawierać polecenia: Build, test, lint, format (dokładne wywołania) - Organizować według zadań: Sekcje kodowania, przeglądu, wydawania, debugowania - Definiować eskalację: Co robić w przypadku blokady lub nieoczekiwanego stanu

NIE NALEŻY: - Kopiować całych przewodników stylu bez reguł wykonawczych - Używać niejednoznacznych dyrektyw („bądź ostrożny”, „optymalizuj”) - Mieszać sprzecznych priorytetów (szybkość + wyczerpująca weryfikacja + brak budżetu czasu wykonania) - Pisać 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.

## Bezpieczeństwo
- Nigdy nie commituj sekretów. Używaj `.env` do lokalnej konfiguracji.
- Waliduj wszystkie zewnętrzne wywołania API z odpowiednią obsługą błędów.

Mechanizm nadpisywania

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

• Zamrożenie wydania: „Żadnych nowych funkcji, tylko poprawki”
• Tryb incydentu: „Wszystkie zmiany muszą być zrecenzowane przez dyżurnego”
• Tymczasowe zaostrzenie: „Żadnych 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 szablonu

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

Lub weryfikacja łańcucha instrukcji:

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

Hooks

Codex dodał hooks w wersji v0.99.0 (AfterAgent) i v0.100.0 (AfterToolUse). System hooks jest we wczesnej fazie rozwoju w porównaniu z ponad 12 zdarzeniami cyklu życia w Claude Code, ale zapewnia punkty wejścia do automatyzacji typowych przepływów pracy.

Dostępne zdarzenia hooks

Konfiguracja hooks

Hooks konfiguruje się w .codex/config.toml:

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

Odtwarzanie wzorców hooks z Claude Code

Podczas migracji z Claude Code poniżej przedstawiono sposoby osiągnięcia podobnej automatyzacji bez pełnego zestawu zdarzeń hooks:

Wskazówka ekspercka: System hooks jest aktywnie rozwijany. Sprawdzaj dziennik zmian Codex, aby śledzić nowe zdarzenia hooks w każdym wydaniu.

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

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

Konfiguracja 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 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 na potrzeby wieloagentowej orkiestracji:¹³

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

Serwer udostępnia dwa narzędzia: 1. codex(): Rozpoczęcie nowej sesji z parametrami prompt, sandbox, model i approval 2. codex-reply(): Kontynuacja istniejącej sesji z threadId i prompt

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")

Popularne serwery MCP

Wzorce praktyczne

Wzorzec 1: Rozwój z uwzględnieniem kontekstu — Połącz Context7 z dokumentacją frameworka, aby Codex zawsze miał aktualne odniesienia API:

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Wzorzec 2: Limity wyjścia — Odpowiedzi narzędzi MCP są domyślnie obcinane do ~25 000 znaków. W przypadku narzędzi zwracających duże ładunki (zapytania do bazy danych, przechwytywanie logów) należy użyć enabled_tools, aby ograniczyć się do konkretnych narzędzi i utrzymać skupione odpowiedzi.

Wzorzec 2a: Multimodalne dane wyjściowe narzędzi (v0.107.0) — Niestandardowe narzędzia mogą teraz zwracać multimodalne dane wyjściowe (obrazy, treści rozszerzone) obok tekstu. Umożliwia to narzędziom generującym artefakty wizualne — zrzuty ekranu, diagramy, renderowania wykresów — przekazywanie ich bezpośrednio do modelu do analizy.⁶⁴

Wzorzec 3: Zarządzanie MCP w przedsiębiorstwie — Kontrola dostępu do serwerów MCP dla deweloperów za pomocą requirements.toml:

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

Każdy serwer, który nie pasuje do tożsamości w requirements.toml, zostanie zablokowany przy starcie. Zobacz Wdrożenie w przedsiębiorstwie, aby poznać pełną konfigurację polityk.

Środowisko uruchomieniowe JavaScript REPL [EXPERIMENTAL]

Codex v0.100.0 dodał eksperymentalne środowisko uruchomieniowe JavaScript REPL (js_repl), które utrzymuje stan między wywołaniami narzędzi. W wersji v0.106.0 REPL został przeniesiony do polecenia slash /experimental z kontrolami kompatybilności przy starcie — wymaga Node.js w wersji 22.22.0 lub nowszej.⁶²

Włączanie JS REPL:

# In config.toml
[features]
js_repl = true

Lub aktywacja w sesji za pomocą /experimental w TUI.

Przykład użycia: Po włączeniu Codex może utrzymywać stan między wywołaniami narzędzi w ramach sesji:

// Codex can accumulate data across multiple tool calls
const results = await fetchTestResults();
const failures = results.filter(r => r.status === "failed");
console.log(`${failures.length} failures out of ${results.length} tests`);
// Variable 'failures' persists and is available in subsequent tool calls

Wymagania: Node.js 22.22.0+ (kontrole przy starcie weryfikują kompatybilność). Wersja v0.105.0 dodała ulepszone raportowanie błędów i odzyskiwanie po awariach REPL.⁶³

Ta funkcja jest eksperymentalna. Interfejs może się zmieniać między wydaniami.

Czym są skills?

Skills to wielokrotnego użytku, zadaniowe pakiety funkcjonalności, które Codex ładuje na żądanie. Są zgodne z otwartym standardem 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 wykrywania

Codex przechowuje zainstalowane przez użytkownika skills w $CODEX_HOME/skills (domyślnie: ~/.codex/skills), w tym wbudowane systemowe skills w katalogu .system/. Codex obsługuje foldery skills jako dowiązania symboliczne.

Tworzenie skill

Format SKILL.md:

---
name: security-audit
description: Run a thorough 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. Sprawdzanie 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. Sprawdzanie podatności zależności: `pip audit` lub `npm audit`
5. Przegląd wzorców uwierzytelniania i autoryzacji
6. Raportowanie znalezisk z poziomami ważności (Critical/High/Medium/Low)

Metadane (agents/openai.yaml):

interface:
  display_name: "Security Audit"
  short_description: "Full 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)
• Kreator: Użyj $skill-creator, aby interaktywnie zbudować nowy skill
• Instalator: Użyj $skill-installer install <name>, aby zainstalować skills społeczności

Włączanie/wyłączanie

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

Skills a slash commands

Debugowanie skills

Jeśli skill się nie aktywuje:

1. Sprawdzenie wykrywalności: /skills powinno wyświetlić go w TUI
2. Weryfikacja ścieżki: Upewnij się, że folder skill znajduje się w rozpoznawanej lokalizacji (~/.codex/skills/, katalog główny projektu lub /etc/codex/skills/)
3. Sprawdzenie enabled: Skills z enabled = false w config.toml nie zostaną załadowane
4. Sprawdzenie aktywacji niejawnej: Jeśli polegasz na automatycznym wykrywaniu, upewnij się, że allow_implicit_invocation: true w agents/openai.yaml
5. Użycie słów kluczowych: Umieść terminy z pola description skill w swoim prompcie, aby poprawić dopasowanie niejawne

Przykład produkcyjny: skill Deploy

Kompletny wieloplikowy skill pokazujący współpracę referencji i skryptów:

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md:

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

Wywoływanie za pomocą: $deploy to staging lub $deploy production with canary rollout

Tryb planowania i współpraca

Tryb planowania umożliwia Codex zaprojektowanie podejścia przed wykonaniem zmian. Jest domyślnie włączony (od v0.94.0).¹⁵ Zobacz Ramy decyzyjne, aby zapoznać się z drzewem decyzyjnym „Tryb planowania a bezpośrednie wykonanie”.

Wejście w tryb planowania

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

W trybie planowania Codex: - Odczytuje pliki i analizuje bazę kodu - Proponuje plan implementacji - Nie wprowadza zmian, dopóki nie zatwierdzisz - Strumieniuje plan w dedykowanym widoku TUI

Tryb Steer

Tryb Steer (domyślnie włączony od v0.98.0) umożliwia wstrzykiwanie nowych instrukcji podczas aktywnej pracy Codex, bez przerywania bieżącego zadania.¹⁵

Dostępne są dwie metody wstrzykiwania:

Praktyczne przykłady:

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

Tryb Steer jest zawsze aktywny w TUI. Jeśli wolisz poczekać, aż Codex zakończy pracę przed wydaniem instrukcji, po prostu wpisz je normalnie po zakończeniu tury — nie jest potrzebny żaden specjalny tryb.

Ulepszenia TUI (v0.105.0–v0.106.0)

Podświetlanie składni (v0.105.0): TUI teraz podświetla składnię bloków kodu i diffów inline. Użyj /theme, aby wybrać schemat kolorów.⁶³

Nowe polecenia TUI (v0.105.0+):⁶³

Transkrypcja głosowa (v0.105.0, eksperymentalna): Naciśnij spację, aby dyktować prompty za pomocą transkrypcji głosowej. Ta funkcja jest eksperymentalna i może wymagać uprawnień do mikrofonu.⁶³ Od v0.107.0 sesje głosowe w czasie rzeczywistym obsługują wybór urządzeń mikrofonu i głośnika, umożliwiając wybór konkretnego sprzętu audio wejścia/wyjścia.⁶⁴

Inne ulepszenia: - Długie linki pozostają teraz klikalne nawet po zawinięciu w liniach TUI (v0.105.0)⁶³ - Linki do plików lokalnych renderowane są z ulepszonym formatowaniem (v0.106.0)⁶² - Obsługa Ctrl+C dla sub-agentów naprawiona, aby prawidłowo kończyć procesy potomne (v0.106.0)⁶²

System pamięci

Codex posiada trwały system pamięci (v0.100.0+), który przechowuje fakty, preferencje i kontekst projektu pomiędzy sesjami.²⁵

Polecenia pamięci

Wspomnienia są przechowywane w plikach markdown w ~/.codex/memory/. Codex ładuje je przy starcie sesji i wykorzystuje do kształtowania zachowania we wszystkich przyszłych sesjach.

Co przechowywać

Wspomnienia sprawdzają się najlepiej w przypadku trwałych preferencji i faktów projektowych:

• Konwencje projektowe: „Ten projekt używa tabulatorów, nie spacji” lub „Odpowiedzi API zawsze zawierają pole meta“
• Preferencje narzędzi: „Używaj pnpm zamiast npm” lub „Uruchamiaj testy za pomocą pytest -x --tb=short“
• Decyzje architektoniczne: „Moduł auth jest w src/core/auth/, nie w src/middleware/“
• Preferencje przepływu pracy: „Zawsze uruchamiaj linter przed pokazaniem mi diffa”

Pamięć w potokach

Podczas uruchamiania codex exec wspomnienia są ładowane automatycznie. Oznacza to, że potoki CI/CD i skrypty korzystają z tego samego kontekstu co sesje interaktywne — nie ma potrzeby powtarzania instrukcji przy każdym wywołaniu.

Udoskonalenia pamięci (v0.101.0–v0.107.0)

• Sanityzacja sekretów: Wspomnienia są automatycznie skanowane pod kątem sekretów przed zapisem na dysk
• Świadomość CWD: Pliki pamięci zawierają teraz kontekst katalogu roboczego dla przywoływania specyficznego dla projektu
• Wykluczanie wiadomości deweloperskich: Wiadomości deweloperskie/systemowe są wykluczane z danych wejściowych pamięci fazy 1, co poprawia jakość pamięci poprzez skupienie na interakcjach użytkownika
• Zapominanie oparte na diffach (v0.106.0): Pamięć wykorzystuje teraz zapominanie oparte na diffach do usuwania nieaktualnych faktów, utrzymując magazyn pamięci w postaci zwięzłej i aktualnej⁶²
• Wybór uwzględniający użycie (v0.106.0): Pobieranie wspomnień jest teraz świadome użycia, priorytetyzując często odwoływane i niedawno istotne wspomnienia⁶²
• Konfigurowalność wspomnień (v0.107.0): Wspomnienia są teraz w pełni konfigurowalne. Użyj codex debug clear-memories, aby zresetować wszystkie przechowywane wspomnienia i zacząć od nowa — przydatne przy przełączaniu się między niepowiązanymi projektami lub gdy stan pamięci uległ rozbieżności⁶⁴

Pamięć a AGENTS.md

Wskazówka: Używaj /m_update dla faktów, które powinny być zachowane na stałe. Dla kontekstu specyficznego dla sesji, po prostu powiedz Codex bezpośrednio w rozmowie. Dla wspólnego kontekstu zespołowego używaj AGENTS.md.

Zarządzanie sesjami

Codex przechowuje sesje w katalogu ~/.codex/sessions/, umożliwiając wznawianie, rozgałęzianie i wielowątkowe przepływy pracy między CLI a aplikacją desktopową.

Wznawianie

Kontynuacja pracy od miejsca, w którym została przerwana:

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

Polecenie /resume w TUI otwiera ten sam interaktywny selektor z funkcją wyszukiwania.

Rozgałęzianie

Rozgałęzienie konwersacji w celu eksplorowania alternatyw bez utraty dotychczasowego postępu:

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

Rozgałęzienia tworzą niezależne wątki współdzielące tę samą historię aż do punktu rozgałęzienia. Zmiany w jednym rozgałęzieniu nie wpływają na drugie. Jest to przydatne do porównywania podejść (np. „rozgałęź i wypróbuj Redis zamiast Memcached”) lub bezpiecznego eksplorowania ryzykownych zmian.

Rozgałęzianie wątków w sub-agenty (v0.107.0): Wątki mogą być teraz rozgałęziane w niezależnych sub-agentów, co pozwala konwersacji uruchamiać równoległe strumienie pracy działające autonomicznie. Rozszerza to istniejący model rozgałęzień — zamiast jedynie rozgałęziać konwersację, rozgałęziony wątek staje się sub-agentem z własnym kontekstem wykonania.⁶⁴

Lista wątków

Przeglądanie i zarządzanie aktywnymi sesjami:

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

W aplikacji desktopowej wątki są widoczne na pasku bocznym z pełną historią i podglądem zmian.

Cykl życia sesji

Sesje synchronizują się między CLI a aplikacją desktopową — można rozpocząć w jednym środowisku i kontynuować w drugim.

Tryb nieinteraktywny (codex exec)

codex exec uruchamia Codex w trybie nieinteraktywnym 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 i zdarzenia do stderr, a końcową wiadomość agenta do stdout. Taki projekt umożliwia komponowanie z standardowymi potokami Unix.

Wyjście w formacie JSON

Z flagą --json strumień 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ąd 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 to funkcja eksperymentalna. Interfejsy, ceny i dostępność mogą ulec zmianie. OpenAI zarządza środowiskami chmurowymi — użytkownik nie kontroluje infrastruktury.

Codex Cloud uruchamia zadania asynchronicznie w środowiskach zarządzanych przez OpenAI.⁴ Zobacz także Akcja GitHub i CI/CD, aby dowiedzieć się, jak zintegrować Codex z potokiem CI.

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

Dostęp agenta do internetu 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 dostęp agenta do internetu jest wyłączony.

Integracja ze Slack

Oznaczenie @Codex w kanale lub wątku Slack uruchamia zadanie w chmurze.

Wymagania wstępne: 1. Odpowiedni 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

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

CLI w chmurze

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)

## Aplikacja Codex Desktop

Aplikacja Codex Desktop (tylko macOS, Apple Silicon) zapewnia graficzny interfejs zoptymalizowany do zarządzania wieloma projektami.[^17]

### Instalacja

```bash
codex app                      # Auto-downloads and installs on first run

Lub pobierz bezpośrednio: Codex.dmg

Kluczowe funkcje

Tryby wątków

Każdy wątek działa w jednym z trzech trybów, wybieranym podczas jego tworzenia:

Mechanika izolacji worktree:

Gdy uruchamiany jest wątek Worktree, aplikacja desktopowa: 1. Tworzy nowy git worktree (git worktree add) w katalogu tymczasowym 2. Przełącza się na nową gałąź utworzoną z bieżącego HEAD 3. Uruchamia agenta wewnątrz worktree — wszystkie zmiany plików są izolowane 4. Po zakończeniu prezentuje przegląd zmian — użytkownik decyduje, które zmiany scalić

Oznacza to, że wiele wątków Worktree może działać jednocześnie na tym samym repozytorium bez konfliktów. Każdy otrzymuje własną gałąź i katalog roboczy.

Automatyzacje

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

• W repozytoriach Git automatyzacje korzystają z dedykowanych worktree w tle (izolowanych od katalogu roboczego)
• W projektach bez Git uruchomienia wykonywane są bezpośrednio w katalogu projektu
• Automatyzacje korzystają z domyślnych ustawień sandbox

Konfiguracja automatyzacji: 1. Otwórz projekt w aplikacji desktopowej 2. Kliknij zakładkę Automations na pasku bocznym 3. Zdefiniuj wyzwalacz (harmonogram, webhook lub ręczny) 4. Napisz prompt i wybierz tryb wątku 5. Automatyzacje uruchamiają się zgodnie z harmonogramem i kolejkują wyniki do przeglądu

Przykładowe zastosowania: - Klasyfikacja zgłoszeń: Automatyczne kategoryzowanie i priorytetyzacja nowych zgłoszeń - Monitorowanie CI: Obserwowanie błędów kompilacji i sugerowanie poprawek - Reakcja na alerty: Reagowanie na alerty monitoringu analizą diagnostyczną - Aktualizacje zależności: Sprawdzanie i stosowanie poprawek bezpieczeństwa

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

Wsparcie dla systemu Windows

Wsparcie dla systemu Windows jest planowane. Aktualne informacje można znaleźć na stronie Codex Desktop App lub w wydaniach GitHub.¹⁸

GitHub Action i CI/CD

Oficjalna GitHub Action integruje Codex z potokiem 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 kolejnych 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ć przepływy 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ń z aktualizacjami pośrednimi
• outputSchema: Wymuszenie wyjścia w kształcie JSON
• Wejście multimodalne: Przekazywanie tekstu + 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 ~/.codex/sessions.

Środowisko uruchomieniowe: Node.js 18+.

Optymalizacja wydajności

Zarządzanie kontekstem

Flagowe modele mają okna wejściowe o pojemności 272 tys. tokenów (128 tys. wyjściowych, 400 tys. całkowitego budżetu), ale zapełniają się szybciej niż można by przypuszczać. Zarządzanie kontekstem wymaga proaktywnego podejścia:

1. Regularne używanie /compact: Podsumowuje historię konwersacji, zwalniając tokeny
2. Dostarczanie lokalnej dokumentacji: Wysokiej jakości AGENTS.md i lokalna dokumentacja zmniejszają narzut eksploracji (który zużywa kontekst)
3. Używanie @ do dołączania konkretnych plików: Bezpośrednie odwoływanie się do plików zamiast proszenia Codex o ich wyszukanie
4. Precyzyjne prompty: Prompty o wąskim zakresie z konkretnymi plikami zużywają mniej kontekstu niż otwarta eksploracja

Efektywność tokenów

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 model mini z niskim poziomem reasoning
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: Proszenie o „zaimplementuj, przetestuj, napraw, zatrzymaj się gdy testy przechodzą” zamiast instrukcji krok po kroku

Jak debugować problemy?

Typowe problemy i rozwiązania

Referencja komunikatów błędów

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)

Lub zgłoś problem na stronie github.com/openai/codex/issues.¹

Wdrożenie w przedsiębiorstwie

Kontrole administracyjne (requirements.toml)

Administratorzy egzekwują politykę korporacyjną za pomocą pliku requirements.toml — wymuszanego przez administratora pliku konfiguracyjnego, który ogranicza ustawienia wrażliwe z punktu widzenia bezpieczeństwa, których użytkownicy nie mogą nadpisać:²²

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["untrusted", "on-request", "on-failure"]

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"

W odróżnieniu od config.toml na poziomie użytkownika, który ustawia preferencje, requirements.toml jest twardą warstwą ograniczeń, która limituje wartości dostępne do wyboru przez użytkowników — nie można jej nadpisać. Reguły administracyjne w requirements mogą jedynie pytać o zgodę lub zabraniać (nigdy nie zezwalają cicho).

Konfiguracja macOS MDM

Dystrybucja przez MDM z wykorzystaniem domeny preferencji com.openai.codex.²² Codex obsługuje standardowe payloady macOS MDM (Jamf Pro, Fleet, Kandji itp.). TOML należy zakodować w base64 bez zawijania linii:

Priorytet (od najwyższego do najniższego):

1. Zarządzane preferencje macOS (MDM)
2. Wymagania pobierane z chmury (ChatGPT Business / Enterprise)
3. /etc/codex/requirements.toml (lokalny system plików)

Wymagania z chmury wypełniają jedynie nieustawione pola, więc warstwy zarządzane o wyższym priorytecie zawsze mają pierwszeństwo. Wymagania z chmury są dostarczane na zasadzie best-effort; jeśli pobranie nie powiedzie się lub przekroczy limit czasu, Codex kontynuuje pracę bez warstwy chmurowej.

Integracja z OpenTelemetry

Codex obsługuje propagację kontekstu śledzenia OpenTelemetry ze standardowych zmiennych środowiskowych OTel do wywołań API OpenAI. Należy ustawić standardowe zmienne środowiskowe przed uruchomieniem Codex:

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

• Standardowe zmienne środowiskowe OTEL_* są obsługiwane (endpoint, nazwa usługi, atrybuty zasobów)
• Kontekst śledzenia propaguje przez Codex do wywołań API, umożliwiając pełną obserwowalność end-to-end
• Atrybuty zasobów pozwalają tagować ślady według zespołu, środowiska lub projektu
• Przy włączaniu logowania promptów/narzędzi należy pamiętać o wymaganiach dotyczących prywatności — ślady mogą zawierać fragmenty kodu

Dostęp korporacyjny

• ChatGPT Business / Enterprise / Edu: Kontrola dostępu przez administratora organizacji, z automatycznie stosowanymi wymaganiami pobieranymi z chmury. Obsługa SSO przez SAML/OIDC za pośrednictwem dostawcy tożsamości (Okta, Entra ID itp.)
• API: Standardowa autoryzacja API, rozliczenia oraz kontrole organizacji/projektu. OpenAI publikuje raporty SOC 2 Type II i SOC 3; BAA zgodne z HIPAA dostępne dla poziomu Enterprise
• Codex SDK: Osadzanie w wewnętrznych narzędziach i przepływach pracy
• Egzekwowanie polityki na skalę: Dystrybucja requirements_toml_base64 przez MDM lub /etc/codex/requirements.toml na poziomie systemu plików

Obsługa danych i zgodność z regulacjami: - Dane wejściowe/wyjściowe API nie są wykorzystywane do treningu na warunkach Business/Enterprise/API OpenAI - W kwestii rezydencji danych: ruch API OpenAI jest domyślnie kierowany przez infrastrukturę zlokalizowaną w USA; w przypadku wymogów rezydencji danych w UE należy skontaktować się z zespołem Enterprise sales OpenAI - Transkrypty sesji są przechowywane lokalnie; tylko wywołania API opuszczają maszynę - ChatGPT Enterprise obsługuje ramy zgodności, w tym SOC 2, RODO i CCPA

Strategia wdrożenia

Zalecane fazowe wdrożenie dla organizacji:

1. Pilotaż (tydzień 1–2): Wdrożenie dla 3–5 starszych inżynierów z requirements.toml wymuszającym tryb sandbox untrusted i wyszukiwanie cached. Zbieranie opinii na temat wzorców AGENTS.md i potrzeb dotyczących serwerów MCP.
2. Rozszerzenie na zespół (tydzień 3–4): Wdrożenie dla całego zespołu. Dystrybucja standardowego config.toml zespołowego przez MDM lub repozytorium. Włączenie sandboxa workspace-write dla zaufanych repozytoriów.
3. Integracja z CI (tydzień 5–6): Dodanie codex-action do potoków CI/CD w celu automatycznej recenzji PR i generowania testów. Użycie --ephemeral dla przewidywalnych kosztów.
4. Wdrożenie organizacyjne (miesiąc 2+): Dystrybucja przez MDM z requirements.toml wymuszającym zatwierdzone serwery MCP, polityki sandbox i listy dozwolonych modeli.

Wzorce audytu

Śledzenie użycia Codex i egzekwowanie zgodności:

• Ślady OpenTelemetry: Monitorowanie wolumenu wywołań API, zużycia tokenów i opóźnień w podziale na zespoły
• Trwałość sesji: Audyt ~/.codex/sessions/ na potrzeby przeglądu zgodności (wyłączenie za pomocą --ephemeral w kontekstach wrażliwych)
• Egzekwowanie tożsamości MCP: requirements.toml rejestruje zablokowane próby serwerów — przegląd pod kątem nieautoryzowanego użycia narzędzi
• Ślad audytu Git: Wszystkie zmiany plików dokonane przez Codex przechodzą przez standardowy git — weryfikacja przez historię gałęzi i różnice w PR

Najlepsze praktyki i antywzorce

Wzorce promptowania

1. Prompty oparte na ograniczeniach: Zacznij od granic. „NIE zmieniaj kontraktów API. Refaktoryzuj tylko wewnętrzną implementację.”
2. Ustrukturyzowane kroki reprodukcji: Ponumerowane kroki dają lepsze poprawki błędów niż niejasne opisy
3. Żądania weryfikacji: Zakończ promptem „Uruchom lint + najmniejszy odpowiedni zestaw testów. Podaj polecenia i wyniki.”
4. Odniesienia do plików: Użyj @filename, aby dołączyć konkretne pliki do kontekstu
5. Pętle zorientowane na wynik: „Zaimplementuj, uruchom testy, napraw błędy, zatrzymaj się dopiero gdy wszystkie testy przejdą.” Codex iteruje aż do zakończenia

Filozofia testowania

Społeczność konwerguje w kierunku współpracy z AI opartej na testach:²³

• Definiuj testy z góry jako sygnały ukończenia
• Pozwól Codex iterować aż testy przejdą (red → green → refactor)
• Stosuj wzorce programowania Tiger Style
• Podawaj dokładny tekst pliku przy żądaniu łatek. Codex stosuje ścisłe dopasowanie, a nie rozmyte łatanie oparte na AST

Najlepsze praktyki zarządzania kontekstem

• Dostarczaj wysokiej jakości lokalną dokumentację zamiast polegać na wyszukiwaniu w sieci
• Utrzymuj ustrukturyzowany markdown ze spisami treści i plikami postępu („stopniowe ujawnianie”)
• Normalizuj końce linii (LF vs CRLF) we wszystkich śledzonych plikach, aby zapobiec błędom łatek
• Utrzymuj AGENTS.md zwięzłe, ponieważ długie instrukcje są wypychane poza kontekst

Przepływ pracy z Git

• Zawsze twórz nową gałąź przed uruchomieniem Codex na nieznanych repozytoriach
• Używaj przepływów opartych na łatkach (git diff / git apply) zamiast bezpośrednich edycji
• Przeglądaj sugestie Codex jak code review PR-ów
• Używaj /diff, aby zweryfikować zmiany przed zatwierdzeniem

Umiejętności i prompty społeczności

Repozytorium feiskyer/codex-settings udostępnia konfiguracje utrzymywane przez społeczność:²⁴

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 code review - ui-engineer [requirements]: Profesjonalny rozwój frontendu

Umiejętności 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 → projekt → zadania → wykonanie

Antywzorce

Częste błędy, które marnują tokeny, dają słabe wyniki lub tworzą frustrujące przepływy pracy.

Antywzorce kosztowe

Antywzorce kontekstu

Antywzorce przepływu pracy

Antywzorce promptowania

Przepisy na przepływy pracy

Kompleksowe wzorce dla typowych scenariuszy deweloperskich.

Przepis 1: Konfiguracja nowego projektu

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

Przejrzyj wygenerowany AGENTS.md, edytuj zgodnie ze swoimi konwencjami, a następnie:

> Run the health endpoint test and confirm it passes

Przepis 2: Codzienny przepływ pracy deweloperskiej

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

Przejrzyj za pomocą /diff, a następnie zatwierdź.

Przepis 3: Złożona refaktoryzacja z trybem planowania

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

Przejrzyj plan. Zatwierdź lub skoryguj:

[Tab] Also add a migration script using Alembic

Po wykonaniu przez Codex zweryfikuj:

> Run the full test suite and report results
> /diff

Przepis 4: Przegląd PR za pomocą codex exec

codex exec --model gpt-5.1-codex-mini \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

Przepis 5: Debugowanie z zadaniami w chmurze [EKSPERYMENTALNE]

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."

Sprawdź postęp później:

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

Zastosuj poprawkę lokalnie po zakończeniu:

codex apply <TASK_ID>

Przewodnik po migracji

Z Claude Code

Kluczowe różnice do zrozumienia:

• Sandbox działa na poziomie systemu operacyjnego: Codex wykorzystuje Seatbelt/Landlock, a nie kontenery. Ograniczenia działają na poziomie jądra systemu, poniżej warstwy aplikacji.
• Hooks są we wczesnej fazie: Codex dodał hooks w v0.99.0 (AfterAgent) i v0.100.0 (AfterToolUse), ale system jest na wczesnym etapie w porównaniu z 12+ zdarzeniami cyklu życia w Claude Code. W przypadku wzorców automatyzacji, które nie są jeszcze obsługiwane, należy korzystać z instrukcji w AGENTS.md lub skills.
• Sub-agenty są wewnętrzne, ale teraz konfigurowalne: Codex posiada mechanizm sub-agentów (maks. 6 równoległych, zmniejszono z 12 w v0.91.0). Od wersji v0.104.0 role wielu agentów można dostosowywać poprzez konfigurację, umożliwiając nazwane role agentów z odrębnymi profilami.⁴⁹ Wersja v0.105.0 dodała spawn_agents_on_csv do rozgałęziania pracy na wiersze z śledzeniem postępu i szacowanym czasem ukończenia.⁶³ Codex nadal nie posiada odpowiednika jawnego narzędzia Task z Claude Code do delegowania zadań przez użytkownika — w przypadku wzorców delegowania należy korzystać z zadań w chmurze lub orkiestracji SDK.
• AGENTS.md jest wielonarzędziowy: AGENTS.md działa w Cursor, Copilot, Amp, Jules, Gemini CLI oraz ponad 60 000 projektów open source. 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: - Sandbox na poziomie systemu operacyjnego (Seatbelt/Landlock — wymuszany przez jądro systemu vs oparty na kontenerach) - Delegowanie zadań w chmurze za pomocą codex apply - Profile konfiguracji do przełączania przepływów pracy - Aplikacja desktopowa z izolacją worktree

Z Cursor

Skrócona karta referencyjna

╔═══════════════════════════════════════════════════════════════╗
║                    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       ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║  /experimental Toggle experimental features (js_repl)        ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  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             ║
║  requirements.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, v0.106.0)                                  ║
║  gpt-5.3-codex         Default flagship (272K in / 400K)     ║
║  gpt-5.3-codex-spark   Interactive, lower latency (128K)     ║
║  gpt-5.2-codex         Long-horizon refactors (272K / 400K)  ║
║  gpt-5.1-codex-mini    Quick tasks, cost-efficient (272K/400K)║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Historia zmian

Źródła

Uwaga dotycząca adresów URL bloga OpenAI: Źródła ¹⁷, ²⁶–³¹ i ³⁴ prowadzą do wpisów na blogu openai.com/index/, które zwracają HTTP 403 przy dostępie automatycznym z powodu ochrony Cloudflare przed botami. Adresy te są dostępne w standardowej przeglądarce internetowej.