Zaawansowane porady Codex

Opanowałeś podstawy każdej powierzchni Codex. Wiesz, jak działają worktree, twoja konfiguracja jest dostrojona, a AGENTS.md ma odpowiednią strukturę. Teraz chcesz pójść dalej: uruchomić Codex jako serwer MCP konsumowany przez inne agenty, skierować go na lokalne modele przez Ollama, przekierować ustrukturyzowane wyjście do swojego systemu budowania i śledzić każde wywołanie API przez OpenTelemetry. To techniki, które zmieniają Codex z asystenta kodowania w komponent infrastruktury deweloperskiej.

Co wyniesiesz z tego artykułu

• Wzorce orkiestracji wielopowierzchniowej łączące App, CLI i Cloud
• Konfiguracje niestandardowych dostawców modeli dla proxy, modeli lokalnych i Azure
• Programowa integracja przez @openai/codex-sdk i strumień zdarzeń codex exec --json
• Konfiguracja obserwowalności z OpenTelemetry do śledzenia użycia Codex
• Zaawansowane dostrajanie sandboxa dla środowisk wymagających wysokiego poziomu bezpieczeństwa

Orkiestracja wielopowierzchniowa

Wzorzec przekazywania między powierzchniami

Każda powierzchnia ma swój optymalny zastosowanie. Łącz je dla maksymalnego efektu:

1. Zacznij w CLI dla szybkiej diagnozy:

   codex "What's causing the TypeScript errors in src/services/?"

2. Przejdź do App dla równoległej implementacji:

   • Otwórz wątek Worktree dla poprawki
   • Otwórz kolejny wątek Worktree dla testów
   • Przeglądaj diffy wizualnie w panelu diff aplikacji

3. Prześlij do Cloud w celu weryfikacji:

   codex cloud exec --env staging --attempts 2 \
     "Run the full integration test suite against these changes"

4. Wróć do CLI na finalny commit:

   codex exec --full-auto "Create a PR with a summary of all changes"

Kontekst między powierzchniami

App i CLI współdzielą konfigurację, AGENTS.md i umiejętności — ale nie historię wątków. Aby przekazać kontekst między powierzchniami:

• Użyj zintegrowanego terminala w App do uruchamiania poleceń CLI
• Kopiuj istotne podsumowania z wątków App do promptów CLI
• Użyj codex resume, aby kontynuować sesję z App w CLI

Gdy rozszerzenie IDE i App są zsynchronizowane, współdzielą widoczność wątków i automatyczny kontekst. To najpłynniejszy przepływ międzypowierzchniowy.

Prompt: Dochodzenie międzypowierzchniowe

Zacznij w CLI:

codex "Analyze the performance regression introduced in the last 5 commits. Identify the suspect commit and explain what changed."

Następnie przejdź do App z wątkiem Worktree:

“Based on commit abc1234 being the cause of the performance regression, implement a fix that restores the previous query behavior while keeping the new feature. Run benchmarks to verify the fix.”

Niestandardowi dostawcy modeli

Kierowanie przez proxy

model = "gpt-5.5"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI via internal proxy"
base_url = "http://proxy.internal.company.com"
env_key = "OPENAI_API_KEY"

Użycie Ollama dla modeli lokalnych

Blok [model_providers.ollama] zawiera tylko szczegóły połączenia. Dostawca, którego Codex używa po podaniu --oss, jest wybierany przez oss_provider, który jest kluczem najwyższego poziomu (nie zagnieżdżonym wewnątrz tabeli):

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

# klucz najwyższego poziomu, NIE wewnątrz tabeli [model_providers.ollama] powyżej
oss_provider = "ollama"  # lub "lmstudio"

Następnie uruchom: codex --oss "Explain this function". Gdy nie podasz dostawcy, --oss użyje tego, na co wskazuje oss_provider.

Azure OpenAI

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

Dostrajanie specyficzne dla dostawcy

[model_providers.openai]
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

Zwiększ stream_idle_timeout_ms, jeśli widzisz błędy timeout przy długotrwałych zadaniach. Zwiększ liczbę ponownych prób przy niestabilnych warunkach sieciowych.

Szybkie nadpisanie endpointu

Jeśli potrzebujesz jedynie skierować wbudowanego dostawcę OpenAI na inny endpoint (np. ze względu na rezydencję danych):

# zastąp swoim rzeczywistym regionalnym endpointem / endpointem proxy
export OPENAI_BASE_URL="https://your-region.api.openai.com/v1"
codex

Nie trzeba zmieniać konfiguracji. OPENAI_BASE_URL nadpisuje endpoint wbudowanego dostawcy OpenAI dla bieżącej powłoki.

Rozumowanie modelu i kontrola wyjścia

Dostosuj wysiłek rozumowania

model_reasoning_effort = "high"    # Dla złożonych decyzji architektonicznych
# lub
model_reasoning_effort = "low"     # Dla prostych, szybkich zadań

Opcje: minimal, low, medium, high, xhigh (zależne od modelu).

Kontroluj gadatliwość

model_verbosity = "low"      # Krótsze odpowiedzi, mniej wyjaśnień
model_reasoning_summary = "concise"  # Zwięzłe podsumowania rozumowania

Dla logów CI całkowicie ukryj rozumowanie:

hide_agent_reasoning = true

Dostrajanie okna kontekstowego

model_context_window = 128000
model_auto_compact_token_limit = 100000  # Kompaktuj wcześniej, aby zostawić zapas

Ustaw model_auto_compact_token_limit niżej niż okno kontekstowe, aby wyzwolić kompaktowanie zanim okno wypełni się całkowicie.

Codex jako serwer MCP

Uruchom sam Codex jako serwer MCP, aby inne agenty mogły go konsumować:

codex mcp-server

To uruchamia Codex przez stdio, umożliwiając innemu narzędziu lub agentowi połączenie się i używanie Codex jako narzędzia. Przydatne do budowania systemów wieloagentowych, gdzie koordynator deleguje zadania do Codex.

Integracja programowa (SDK i strumień JSON)

Gdy chcesz mieć Codex wewnątrz własnego oprzyrządowania — niestandardowego CLI, bramki CI, chatbota — masz dwie powierzchnie integracji.

SDK dla TypeScript

Zainstaluj @openai/codex-sdk i steruj wątkami z poziomu kodu. SDK uruchamia tego samego agenta co CLI, więc twój AGENTS.md, umiejętności i konfiguracja obowiązują:

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

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

const result = await thread.run('Diagnose and fix the failing CI tests, then summarize what changed.');
console.log(result);

// Kontynuuj ten sam wątek lub wznów wcześniejszy po ID za pomocą codex.resumeThread(id)
await thread.run('Now add a regression test for the bug you fixed.');

Przekierowanie strumienia zdarzeń JSON

Dla automatyzacji niezależnej od języka dodaj --json do codex exec, aby otrzymać zdarzenia JSON rozdzielone znakami nowej linii (jedno na zmianę stanu). Przekieruj je do jq lub dowolnego parsera, aby wpiąć Codex w krok budowania:

Każda linia niesie najwyższego poziomu .type (thread.started, turn.started, turn.completed, turn.failed, item.started, item.completed, error); rodzaj pracy, którą reprezentuje element (agent_message, command_execution, file_change, mcp_tool_call, …) znajduje się w .item.type. Aby obserwować zakończone uruchomienia poleceń i wiadomości modelu:

codex exec --json --full-auto \
  "Bump every dependency to its latest minor and run the test suite" \
  | jq -c 'select(.type == "item.completed") | select(.item.type == "command_execution" or .item.type == "agent_message") | .item'

Połącz --json z --output-last-message out.txt w CI, aby w jednym uruchomieniu uchwycić zarówno czytelny dla maszyny strumień zdarzeń, jak i końcowe podsumowanie w języku naturalnym.

Prompt: Zbuduj niestandardową bramkę przeglądu CI

Steruj tym ze skryptu Node, który wywołuje SDK przy każdym PR:

“Review the diff between origin/main and HEAD. Fail (exit non-zero) only if you find a correctness bug, a missing null check on a new public function, or a test that asserts nothing. Ignore style. Output a one-line verdict prefixed with PASS or FAIL, then the reasons.”

Dostrajanie sandboxa

Zapis w workspace z siecią

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true
writable_roots = ["/Users/me/.pyenv/shims", "/tmp"]
exclude_tmpdir_env_var = false
exclude_slash_tmp = false

Przyznanie zapisu do dodatkowych katalogów

Użyj --add-dir zamiast rozszerzania sandboxa:

codex --cd apps/frontend --add-dir ../backend --add-dir ../shared \
  "Coordinate API changes between frontend and backend"

To przyznaje ograniczony dostęp do zapisu bez otwierania danger-full-access.

Testowanie zachowania sandboxa

Użyj polecenia codex sandbox, aby przetestować, co dane polecenie może zrobić przy twoich obecnych ustawieniach:

# Użyj `macos` na macOS, `linux` na Linux (aliasy: seatbelt / landlock)
codex sandbox macos -- ls /etc
codex sandbox macos -- cat /etc/passwd
codex sandbox macos --full-auto -- npm test

Podkomenda platformy jest wymagana; wszystko po -- to polecenie do uruchomienia. To uruchamia polecenie pod tym samym sandboxem, którego Codex używa wewnętrznie, więc możesz zweryfikować polityki zanim agent na nie natrafi.

Prompt: Audyt konfiguracji sandboxa

“Check my current sandbox settings: what directories can you write to, do you have network access, and what commands would require approval? Then suggest whether the sandbox is too restrictive or too permissive for a typical development workflow.”

Obserwowalność z OpenTelemetry

Włącz eksport OTel

[otel]
environment = "production"
log_user_prompt = false  # Nie eksportuj surowych promptów

[otel.exporter.otlp-http]
endpoint = "https://otel-collector.internal.company.com/v1/logs"
protocol = "binary"
headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }

Co jest eksportowane

Codex emituje ustrukturyzowane zdarzenia logów dla:

• codex.conversation_starts — Model, ustawienia, polityka sandboxa
• codex.api_request — Status, czas trwania, szczegóły błędu
• codex.tool_decision — Zatwierdzono/odrzucono, przez konfigurację vs użytkownika
• codex.tool_result — Czas trwania, sukces, fragment wyjścia

Wyłącz anonimowe metryki

Codex domyślnie wysyła anonimowe dane o użyciu. Wyłącz to:

[analytics]
enabled = false

To jest niezależne od eksportu OTel — analityka trafia do OpenAI, OTel trafia do twojej infrastruktury.

Zaawansowane wzorce powiadomień

Niestandardowy skrypt powiadomień

notify = ["python3", "/path/to/notify.py"]

Skrypt otrzymuje argument JSON ze szczegółami zdarzenia:

#!/usr/bin/env python3
import json, subprocess, sys

def main():
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Done!')}"
    subprocess.run([
        "terminal-notifier",
        "-title", title,
        "-message", " ".join(notification.get("input-messages", [])),
        "-group", "codex-" + notification.get("thread-id", ""),
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

Filtrowanie powiadomień TUI

[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "osc9"  # Powiadomienia desktopowe przez sekwencję ucieczki OSC 9

Flagi funkcji warte poznania

Flaga	Status	Co robi
shell_snapshot	Beta	Tworzy migawki środowiska powłoki dla szybszych powtarzanych poleceń
unified_exec	Beta	Używa PTY-backed exec dla lepszej obsługi terminala
remote_compaction	Eksperymentalna	Przenosi kompaktowanie kontekstu na serwer
request_rule	Stabilna	Inteligentne sugestie zatwierdzania na podstawie wzorców poleceń

Włącz za pomocą:

codex features enable shell_snapshot
codex features enable unified_exec

Edytor promptów dla długich instrukcji

Dla złożonych, wieloakapitowych promptów naciśnij Ctrl + G w TUI, aby otworzyć skonfigurowany edytor. Ustaw edytor:

export VISUAL=code  # Lub vim, nvim, nano, itp.

Napisz pełny prompt w edytorze, zapisz i zamknij, a Codex go wyśle. To znacznie wygodniejsze niż wpisywanie długich instrukcji w kompozytorze.

Gdy coś się psuje

• Uwierzytelnianie niestandardowego dostawcy nie działa: Sprawdź, czy zmienna środowiskowa env_key jest ustawiona i wyeksportowana. Użyj codex login status, aby sprawdzić autoryzację.
• Zdarzenia OTel się nie pojawiają: Sprawdź, czy exporter jest ustawiony na otlp-http lub otlp-grpc, a nie none. Zweryfikuj, czy endpoint jest osiągalny z twojej maszyny.
• Sandbox zbyt restrykcyjny dla twojego przepływu pracy: Użyj codex sandbox, aby przetestować konkretne polecenia. Dodaj writable_roots dla katalogów, których agent potrzebuje.
• Tryb serwera MCP się rozłącza: Codex kończy pracę, gdy klient zamknie połączenie. Upewnij się, że twój klient utrzymuje pipe stdio.
• Flagi funkcji znikają po restarcie: Flagi funkcji są zapisywane w config.toml, ale flagi związane z profilem działają tylko gdy dany profil jest aktywny.

Co dalej

• Współpraca zespołowa — Udostępnij te zaawansowane konfiguracje swojemu zespołowi
• Instalacja i konfiguracja — Podstawowa konfiguracja wspierająca te techniki
• Optymalizacja AGENTS.md — Nałóż instrukcje na zaawansowaną konfigurację