config.toml w OpenAI Codex: Kompletny przewodnik

Codex działa out-of-the-box, ale pełna kontrola wymaga znajomości config.toml. Ten plik decyduje o wszystkim – od modelu, przez uprawnienia, po eksperymentalne funkcje.

W poprzednich wpisach omawialiśmy podstawy Codex i bezpieczeństwo sandboxa. Dziś wchodzimy w konfigurację – jeden plik TOML, który zmienia wszystko.

1. Warstwy konfiguracji
2. Podstawowe ustawienia
3. Sandbox i uprawnienia szczegółowo
4. Feature flags
5. Profile: różne konfiguracje dla różnych kontekstów
6. Zaawansowana konfiguracja
7. Troubleshooting

Warstwy konfiguracji

Codex czyta konfigurację z wielu źródeł, stosując ścisłą hierarchię priorytetów. Wyższy priorytet nadpisuje niższy:

Praktyczny przykład: Masz w ~/.codex/config.toml ustawiony model gpt-5.2. W projekcie .codex/config.toml jest gpt-5.1-codex-mini. Projekt wygrywa – Codex użyje Mini. Ale jeśli uruchomisz codex -m gpt-5.3, CLI flag nadpisze wszystko.

Podstawowe ustawienia

Oto minimalny config.toml z objaśnieniami każdego parametru:

# ~/.codex/config.toml

# Model domyślny – wpływa na jakość i koszt
# Opcje: gpt-5.3, gpt-5.2, gpt-5.1-codex-mini, gpt-5.1-codex-max
model = "gpt-5.2"

# Poziom reasoning dla modeli z chain-of-thought
# Opcje: low, medium, high
# Wyższy = lepsza jakość, wolniejsze odpowiedzi, więcej tokenów
model_reasoning_effort = "high"

# Styl komunikacji Codex
# friendly = przyjazny, wyjaśniający
# pragmatic = zwięzły, na temat
# none = minimalne komentarze
personality = "friendly"

# Wyszukiwanie w sieci
# cached = pre-indeksowane wyniki (domyślne)
# live = najświeższe dane, wyższe ryzyko prompt injection
# disabled = brak dostępu do sieci
web_search = "cached"

Sandbox i uprawnienia szczegółowo

Bezpieczeństwo Codex opiera się na dwóch mechanizmach: sandbox mode i approval policy. Działają niezależnie – możesz mieć restrykcyjny sandbox z luźną polityką zatwierdzania lub odwrotnie.

Tryby sandbox

# Opcje: read-only | workspace-write | danger-full-access
sandbox_mode = "workspace-write"

*Sieć w workspace-write można włączyć osobno:

[sandbox_workspace_write]
network_access = true  # Włącza sieć w trybie workspace-write

Chronione ścieżki

Nawet w workspace-write Codex chroni niektóre pliki:

• /.git – tylko odczyt (nie zepsuje historii)
• /.agents – tylko odczyt (nie zmodyfikuje skills)
• /.codex – tylko odczyt (nie zmieni własnej konfiguracji)

Polityka zatwierdzania

# Opcje: on-request | untrusted | never
approval_policy = "on-request"

on-request (domyślna) – Codex pyta o zgodę gdy chce wyjść poza workspace lub użyć sieci. Dla większości przypadków to optymalny wybór.

untrusted – Codex pyta przed każdą nieznaną komendą. Bezpieczne, ale wymaga więcej interakcji.

never – Codex nie pyta o nic. Używaj tylko w kontrolowanych środowiskach lub z restrykcyjnym sandboxem.

Feature flags

Sekcja [features] włącza eksperymentalne i beta funkcje:

[features]
multi_agent = true          # Experimental: multi-agent collaboration
shell_snapshot = true       # Beta: cache dla powtarzanych komend
undo = true                 # Stable: git snapshots per-turn
apps = false                # Experimental: ChatGPT Apps/connectors

undo = true to must-have – pozwala cofnąć każdą zmianę jedną komendą. Codex tworzy git snapshot przed każdym turnem, więc możesz bezpiecznie eksperymentować.

Więcej o multi-agent workflows w osobnym artykule.

Profile: różne konfiguracje dla różnych kontekstów

Profile pozwalają przełączać zestawy ustawień jedną flagą. Przydatne gdy pracujesz z różnymi projektami lub środowiskami.

Definicja profilu:

# ~/.codex/profiles/production.toml
model = "gpt-5.3"
model_reasoning_effort = "high"
approval_policy = "untrusted"
sandbox_mode = "read-only"

# ~/.codex/profiles/experiment.toml
model = "gpt-5.3"
approval_policy = "never"
sandbox_mode = "danger-full-access"

# ~/.codex/profiles/budget.toml
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

Użycie:

codex --profile production   # Bezpieczny tryb dla prod
codex --profile experiment   # Pełna autonomia do testów
codex --profile budget       # Oszczędność kredytów

Zaawansowana konfiguracja

Konfiguracja agentów

Gdy używasz multi-agent, możesz definiować specjalistyczne agenty:

[agents]
max_threads = 6      # Maks. równoległych agentów
max_depth = 1        # Maks. zagnieżdżenie agentów

[agents.reviewer]
description = "Code reviewer dla bezpieczeństwa i jakości"
config_file = "agents/reviewer.toml"

Plik agenta:

# agents/reviewer.toml
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Recenzuj kod jak właściciel projektu.
Priorytet: bezpieczeństwo, poprawność, pokrycie testami.
"""

AGENTS.md – alternatywa dla developer_instructions

Zamiast wpisywać instrukcje w TOML, możesz użyć AGENTS.md:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536  # Default: 32768

Timeout i limity

# Timeout dla pojedynczego turnu (sekundy)
turn_timeout = 300

# Maksymalna liczba turnów w sesji
max_turns = 100

# Limit tokenów w kontekście
context_max_tokens = 128000

Troubleshooting

Częste problemy:

1. Untrusted project – Codex nie czyta .codex/config.toml z niezaufanego projektu. Uruchom codex trust w katalogu.

2. Model niedostępny – Niektóre modele wymagają wyższego planu. Sprawdź codex models dla listy dostępnych.

3. Feature flag nie działa – Upewnij się że format jest poprawny: feature_name = true (nie "true" w cudzysłowach).

4. Zmiany nie działają – Zrestartuj sesję po edycji config.toml. Codex czyta konfigurację przy starcie.

5. Profile nie ładuje się – Sprawdź czy plik istnieje w ~/.codex/profiles/nazwa.toml i czy składnia TOML jest poprawna.

Diagnostyka:

codex config show          # Pokaż aktywną konfigurację
codex config validate      # Sprawdź błędy składni
codex doctor               # Pełna diagnostyka instalacji

Więcej o bezpieczeństwie i sandbox znajdziesz w artykule o Exec Policy Rules. Jeśli szukasz alternatywnego podejścia do agentów AI, sprawdź Co to jest OpenClaw?.