Porady dotyczące środowiska chmurowego

Przesłałeś zadanie do chmury i trwało dwanaście minut, bo Codex spędził osiem z nich na npm install. Następne zadanie się nie powiodło, bo nie mogło połączyć się z zewnętrznym API, od którego zależą twoje testy. Zadania chmurowe są potężne — działają w izolowanych kontenerach, produkują czyste diffy i wspierają równoległe próby — ale tylko wtedy, gdy środowisko jest poprawnie skonfigurowane. Dobrze dostrojone środowisko chmurowe robi różnicę między zadaniem, które kończy się w cztery minuty, a takim, które przekracza limit czasu.

Co wyniesiesz z tego artykułu

• Wzorce konfiguracji środowiska minimalizujące czas zimnego startu
• Strategie cachowania kontenerów utrzymujące środowisko w gotowości
• Konfiguracje dostępu do internetu dla różnych poziomów bezpieczeństwa
• Techniki best-of-N maksymalizujące jakość rozwiązań dla krytycznych zadań
• Przepływy pracy CLI do wydajnego przesyłania i zarządzania zadaniami chmury

Konfiguracja środowiska

Automatyczna vs. ręczna konfiguracja

Codex oferuje dwie ścieżki konfiguracji:

• Automatyczna: Codex wykrywa popularne menedżery pakietów (npm, yarn, pnpm, pip, pipenv, poetry) i instaluje zależności automatycznie
• Ręczna: Dostarczasz niestandardowy skrypt konfiguracyjny dla złożonych środowisk

Dla większości projektów zacznij od automatycznej konfiguracji i dodaj ręczny skrypt tylko wtedy, gdy Codex coś pomija.

Pisanie skutecznego skryptu konfiguracyjnego

# Zainstaluj zależności systemowe
apt-get update && apt-get install -y postgresql-client redis-tools

# Zainstaluj zależności projektu
pnpm install --frozen-lockfile

# Zainstaluj narzędzia deweloperskie, których agent może potrzebować
pip install pyright ruff

# Zbuduj wygenerowany kod
pnpm run codegen

# Zweryfikuj, że środowisko działa
pnpm run type-check

Kluczowe zasady:

• Używaj lockfile’ów (--frozen-lockfile, --no-update) dla powtarzalnych instalacji
• Instaluj narzędzia deweloperskie, których agent będzie potrzebował do lintowania, sprawdzania typów i testowania
• Uruchom krok weryfikacyjny na końcu, aby błędy były wychwytywane podczas konfiguracji, a nie podczas zadania

Utrwalanie zmiennych środowiskowych

Skrypty konfiguracyjne działają w osobnej sesji Bash niż agent. export nie przenosi się. Zamiast tego:

# Źle: to się nie utrwali
export DATABASE_URL="postgresql://localhost:5432/test"

# Dobrze: zapisz do .bashrc
echo 'export DATABASE_URL="postgresql://localhost:5432/test"' >> ~/.bashrc

Lub lepiej — skonfiguruj zmienne środowiskowe w UI ustawień Codex, aby były ustawione na cały czas trwania zadania.

Prompt: Debugowanie konfiguracji środowiska chmurowego

“My Codex Cloud task failed during setup with this error: [wklej błąd] The setup script installs dependencies with pnpm and runs codegen. Diagnose why the setup failed and suggest a fix for the setup script.”

Skrypty konserwacyjne

Gdy cachowanie kontenerów jest aktywne, agent wznawia pracę ze stanu cache’owanego, który może bazować na starszym commicie. Użyj skryptu konserwacyjnego, aby utrzymać zależności aktualne:

# Pobierz najnowsze zmiany
git fetch origin

# Zaktualizuj zależności, jeśli lockfile się zmienił
pnpm install --frozen-lockfile

# Ponownie uruchom codegen na wypadek zmian w schematach
pnpm run codegen

Skrypt konserwacyjny uruchamia się za każdym razem, gdy cache’owany kontener jest wznawiany, więc utrzymuj go szybkim.

Cachowanie kontenerów

Jak działa cachowanie

1. Codex klonuje repozytorium i uruchamia skrypt konfiguracyjny
2. Wynikowy stan kontenera jest cache’owany na maksymalnie 12 godzin
3. Przyszłe zadania wznawiają się ze stanu cache’owanego, pomijając pełną konfigurację
4. Skrypt konserwacyjny uruchamia się przy wznowieniu, aby obsłużyć zmiany zależności

Unieważnianie cache

Cache unieważnia się automatycznie, gdy zmienisz:

• Skrypt konfiguracyjny
• Skrypt konserwacyjny
• Zmienne środowiskowe
• Sekrety

Jeśli twoje repozytorium zmieni się w sposób powodujący niezgodność ze stanem cache’owanym (np. duża aktualizacja zależności), ręcznie zresetuj cache ze strony ustawień środowiska.

Optymalizacja trafień cache

Ustrukturyzuj swój skrypt konfiguracyjny tak, aby kosztowne części (pakiety systemowe, instalacje dużych zależności) były na początku i zmieniały się rzadko. Zmienne kroki (codegen, aktualizacje schematów) umieść w skrypcie konserwacyjnym.

# Skrypt konfiguracyjny: kosztowny, rzadko się zmienia
apt-get update && apt-get install -y build-essential
pnpm install --frozen-lockfile

# Skrypt konserwacyjny: tani, uruchamia się za każdym razem
pnpm install --frozen-lockfile  # obsługuje dryf lockfile'a
pnpm run codegen

Współdzielone cache dla zespołów

Dla użytkowników Business i Enterprise cache jest współdzielony między wszystkimi użytkownikami mającymi dostęp do środowiska. Konfiguracja jednego członka zespołu przynosi korzyści wszystkim. Pamiętaj, że resetowanie cache wpływa na wszystkich użytkowników.

Dostęp do internetu

Trzy poziomy

Poziom	Opis	Zastosowanie
Wyłączony (domyślny)	Brak internetu podczas fazy agenta	Maksymalne bezpieczeństwo, wewnętrzne bazy kodu
Ograniczony	Tylko dozwolone domeny	Projekty wymagające konkretnych zewnętrznych API
Nieograniczony	Pełny dostęp do internetu	Projekty open-source, zadania wymagające Web API

Skrypt konfiguracyjny zawsze ma internet

Ograniczenia dostępu do internetu dotyczą tylko fazy agenta. Skrypty konfiguracyjne zawsze mają dostęp do internetu do instalacji zależności.

Allowlisting domen

Dla ograniczonego dostępu skonfiguruj dozwolone domeny w ustawieniach środowiska:

• registry.npmjs.org — do instalacji pakietów npm
• pypi.org — do instalacji pip
• api.stripe.com — do testów integracyjnych wywołujących Stripe
• api.github.com — do wywołań GitHub API

Ryzyko dostępu do internetu

Nieograniczony dostęp do internetu oznacza, że agent może wykonywać żądania HTTP do dowolnej domeny. Tworzy to ryzyko wstrzyknięcia promptu, jeśli agent pobiera treści z niezaufanych źródeł. Używaj ograniczonego dostępu z jawną listą dozwolonych domen, gdy to możliwe.

Strategie best-of-N

Kiedy używać wielu prób

Zadania chmurowe wspierają 1-4 równoległe próby. Używaj wielu prób dla:

• Krytycznych poprawek, gdzie pierwsze podejście może nie zadziałać
• Złożonych migracji z wieloma poprawnymi strategiami
• Niejednoznacznych zadań, gdzie chcesz porównać podejścia

# Prześlij z 3 równoległymi próbami
codex cloud exec --env my-env --attempts 3 "Implement the caching layer for the user service"

Kwestia kosztów

Każda próba zużywa kredyty niezależnie. Zadanie z 3 próbami kosztuje mniej więcej 3x tyle co pojedyncza próba. Rezerwuj best-of-N dla zadań, gdzie uzyskanie właściwej odpowiedzi za pierwszym razem jest ważniejsze niż koszt.

Przeglądanie wielu prób

Gdy wiele prób zostanie ukończonych, przejrzyj każdą w panelu Codex. Sprawdź:

• Które podejście agent wybrał
• Wyniki testów dla każdej próby
• Rozmiar i złożoność diffu
• Czy agent napotkał jakieś błędy podczas wykonywania

Wybierz najlepszy wynik i zastosuj go, lub wykorzystaj wnioski z wielu prób do stworzenia bardziej szczegółowego promptu kontynuacji.

Prompt: Zadanie chmurowe z weryfikacją

codex cloud exec --env production-mirror --attempts 2 \
  "The /api/users endpoint returns stale data after profile updates.
   Reproduce the issue by writing a test that updates a profile and
   immediately reads it back. Find the caching bug, fix it, and verify
   the test passes. Also run the full user service test suite."

Dwie próby zwiększają szansę na znalezienie właściwej poprawki dla wyścigu (race condition).

Przepływy pracy CLI dla zadań chmurowych

Prześlij i monitoruj

# Prześlij zadanie
codex cloud exec --env my-env "Fix the failing integration tests"

# Wyświetl ostatnie zadania ze statusem
codex cloud list --json | jq '.tasks[] | {title, status, url}'

# Zastosuj diff ukończonego zadania lokalnie
codex apply TASK_ID

Interaktywny selektor

Uruchom codex cloud bez argumentów, aby otworzyć interaktywny selektor. Przeglądaj aktywne i ukończone zadania, sprawdzaj ich status i stosuj diffy bezpośrednio.

Naciśnij Ctrl + O w selektorze, aby wybrać inne środowisko.

Skryptowane przesyłanie wsadowe

#!/bin/bash
PACKAGES=("api" "web" "worker")
ENV_ID="my-env-id"

for pkg in "${PACKAGES[@]}"; do
  codex cloud exec --env "$ENV_ID" \
    "In the $pkg package, migrate from lodash to native JavaScript equivalents. Run tests." &
done

wait
echo "All cloud tasks submitted."

Zmienne środowiskowe i sekrety

Zmienne vs. sekrety

• Zmienne środowiskowe: Dostępne przez cały czas trwania zadania (fazy konfiguracji i agenta). Widoczne w logach.
• Sekrety: Zaszyfrowane w spoczynku. Dostępne tylko podczas skryptów konfiguracyjnych. Usuwane przed rozpoczęciem fazy agenta.

Używaj sekretów dla kluczy API, tokenów i danych uwierzytelniających, do których agent nie powinien mieć bezpośredniego dostępu. Skrypt konfiguracyjny może ich użyć do uwierzytelnienia i pobrania prywatnych pakietów, ale agent nie może ich wypisać ani wyeksfiltrować.

Typowy wzorzec

# Zmienne środowiskowe (widoczne dla agenta)
NODE_ENV=test
DATABASE_URL=postgresql://localhost:5432/test

# Sekrety (tylko konfiguracja)
NPM_TOKEN=your-private-registry-token
GITHUB_TOKEN=your-ghcr-token

Gdy coś się psuje

• Skrypt konfiguracyjny przekracza limit czasu: Przenieś ciężkie instalacje do skryptu konfiguracyjnego (nie konserwacyjnego), aby były cache’owane. Użyj --frozen-lockfile, aby uniknąć rozwiązywania zależności.
• Agent nie może zainstalować pakietów: Dostęp do internetu jest domyślnie wyłączony podczas fazy agenta. Zainstaluj pakiety w skrypcie konfiguracyjnym lub włącz ograniczony dostęp do internetu.
• Cache ciągle się unieważnia: Każda zmiana skryptów konfiguracyjnych, konserwacyjnych lub zmiennych środowiskowych unieważnia cache. Grupuj zmiany konfiguracji.
• Zadanie uruchamia się na złej gałęzi: Zweryfikuj wybór gałęzi podczas przesyłania. Zadania chmurowe wykonują checkout określonej gałęzi po sklonowaniu.
• Próby best-of-N dają identyczne wyniki: Zadanie może być zbyt deterministyczne. Dodaj zmienność do promptu: “Try different approaches for the caching strategy.”

Co dalej

• Optymalizacja AGENTS.md — Upewnij się, że zadania chmurowe czytają właściwe wskazówki projektu
• Zaawansowane techniki — Łącz zadania chmurowe z innymi powierzchniami
• Współpraca zespołowa — Współdziel środowiska chmurowe w swoim zespole