Оточення хмарних завдань Codex: setup-скрипт, кеш і доступ до інтернету

Хмарне завдання Codex падає не тому, що модель погано пише код. Воно падає тому, що в контейнері не виявилося потрібної версії PHP, лок-файл потягнув пакет із приватного реєстру без токена, а тест поліз в інтернет, якого на цей момент уже немає. Модель тут ні до чого: усе перелічене — налаштування оточення, і всі вони у ваших руках. Розберемо цей контейнер шарами: що в ньому вже стоїть, що робить ваш скрипт, що виживає між завданнями, а що стирається перед тим, як агент візьметься до роботи.

Усе нижче звірено з документацією OpenAI та відкритими обговореннями на 11 серпня 2026 року.

Коротко (TL;DR)

• Оточення — окремий налаштовуваний обʼєкт, привʼязаний до репозиторію. Живе в налаштуваннях Codex, а не у файлах проєкту, і працює для всіх завдань цього репозиторію.
• У завдання два різні бюджети довіри. Фаза встановлення отримує інтернет і секрети, але не бачить моделі. Фаза агента отримує модель, проте втрачає секрети й типово залишається без мережі.
• Setup-скрипт виконується один раз, а його результат кешується — до 12 годин. Будь-яка правка скрипта, змінної або секрета кеш скидає.
• Секрети видаляються перед фазою агента. Це не налаштування, а архітектурне рішення: інтеграційний тест із живим ключем у хмарі не пройде, а обходити це небезпечно.
• Головне джерело падінь — мережа й версії. Обидва лікуються ще до постановки завдання: залежності ставляться у скрипті, версії рантаймів закріплюються, домени вносяться до allowlist.

Оточення Codex Cloud: що це за обʼєкт і де він налаштовується

Оточення (environment) — це опис контейнера, у якому виконуватиметься хмарне завдання: базовий образ, версії рантаймів, скрипт встановлення, змінні, секрети й політика доступу до мережі. Задають його один раз на репозиторій, на сторінці налаштувань оточень в інтерфейсі Codex, і всі наступні завдання цього репозиторію беруть його як заготовку.

Перше, що варто розвести, — три різні шари конфігурації, які початківці плутають між собою:

• Оточення хмарного завдання — те, про що ця стаття. Живе у вебналаштуваннях, описує контейнер OpenAI.
• Локальний config.toml — налаштування Codex CLI на вашій машині: модель, пісочниця, політика схвалень. До хмарного контейнера стосунку не має.
• AGENTS.md — інструкція проєкту, яку агент читає вже всередині контейнера: якою командою гонити тести, куди не лізти. Оточення готує інструменти, а файл AGENTS.md пояснює, що з ними робити.

Різниця між локальним і хмарним запуском тут принципова. Коли ви працюєте в терміналі, агент бачить вашу машину з усім, що ви туди роками доставляли. У хмарі машини немає: є чистий контейнер, піднятий під завдання, і в ньому рівно те, що ви описали. Три поверхні продукту та їхні відмінності розібрані окремо — в уроці про три способи запустити Codex; тут важливий один наслідок: у хмарі «у мене працює» не аргумент, працювати має в контейнері.

GPT-6.1 Astra не вийде в жовтні: модель обманювала й діяла без дозволу

OpenAI і Anthropic розслідують десятки тисяч інцидентів агентів: злами й чужі ключі

Есе Arthur Hayes «Safety First»: борг ШІ, страховики й ставка на друк грошей

Агенти OpenAI 16 500 разів сканували портал ООН UNCTADstat, підбираючи поля API

Уповільнення розвитку ШІ: три різні плани лабораторій і релізи без паузи

Кожне паралельне завдання при цьому отримує власне оточення з попередньо завантаженим кодом. Тобто налаштування оточення — не разова процедура заради одного завдання, а вкладення, яке відбивається на кожному наступному.

Життя хмарного завдання за етапами: де ви ще можете вплинути

Порядок етапів важливіший за перелік налаштувань: половина проблем виникає через спробу налаштувати те, що на цьому етапі вже недоступне. Маршрут завдання від постановки до готового pull request розібраний в уроці про хмарні завдання Codex — нижче той самий маршрут, але очима оточення.

З таблиці видно правило, яке економить найбільше часу: усе, що потребує мережі або секрета, зобовʼязане статися до фази агента. Далі запізно.

Образ universal: які рантайми вже стоять і як закріпити версії

Контейнер піднімається не з порожнього місця, а з образу universal, куди OpenAI заздалегідь поклала поширені мови, пакети та інструменти. Публічний референс цього образу викладено як openai/codex-universal — його можна завантажити й подивитися власними очима.

Версії рантаймів не збираються заново на кожне завдання: образ підставляє потрібну за змінною CODEX_ENV_*, і це помітно швидше за встановлення з нуля. Допустимі значення на 11 серпня 2026 року:

Понад рантайми в образі вже лежить обвʼязка, яку інакше довелося б ставити руками: для Python — pyenv, poetry, uv, ruff, black, mypy, pyright, isort; для Node — corepack, npm, yarn, pnpm; окремо bun, bazelisk, Erlang та Elixir.

Звірте свій стек із цим переліком перед тим, як писати скрипт. Якщо проєкт на Python або Node, скрипт може взагалі не знадобитися: для npm, yarn, pnpm, pip, pipenv і poetry Codex вміє ставити залежності самостійно, опираючись на лок-файл. А от PHP в образі немає — у практичному розборі налаштування під Symfony автор ставить php8.4 з розширеннями через apt і підкладає Composer з перевіркою контрольної суми установника. Те саме стосується баз даних: PostgreSQL піднімається й ініціалізується тим самим скриптом.

Setup-скрипт: коли він запускається і що встигає зробити

Setup-скрипт — звичайний bash, який виконується після викладення коду й до того, як агент отримає керування. Три його властивості визначають майже все інше.

Інтернет у цій фазі є. Формулювання документації пряме: setup-скрипти виконуються з доступом до мережі, щоб ви могли поставити залежності. Саме тому встановлення живе тут, а не в командах агента.

Скрипт іде в окремій bash-сесії. Документація попереджає: команди на зразок export до фази агента не доживають. Змінну, потрібну агентові, дописують у ~/.bashrc або задають у налаштуваннях оточення — тоді вона буде і під час встановлення, і в роботі.

Час не безмежний. Межа міряється хвилинами. У червні 2025 року учасники спільноти OpenAI ловили обрив на пʼятій хвилині за оголошених десяти; співробітник OpenAI підтвердив, що це помилка, і виправив її того ж дня. Тоді ж прозвучала скарга, що й десяти хвилин не досить: встановлення важких бібліотек падало на 600 секундах «зовсім близько до кінця». Практичний висновок не залежить від поточного значення межі — важке збирання зі скрипта встановлення треба виносити, а не сподіватися дотягнути.

Звідси робочий порядок: повільне й стабільне — першим, швидке й змінне — останнім, самоперевірка — у кінці.

#!/usr/bin/env bash
set -euo pipefail

# 1. Системні пакети: найповільніше й таке, що змінюється найрідше
apt-get update -qq
apt-get install -y -qq libpq-dev

# 2. Залежності проєкту строго за лок-файлом.
#    --frozen-lockfile не дасть скрипту тихо оновити дерево,
#    --ignore-scripts рятує, коли postinstall лізе в мережу.
pnpm install --frozen-lockfile --ignore-scripts

# 3. Змінна, потрібна агентові: export її не переживе
echo 'export APP_ENV=test' >> ~/.bashrc

# 4. Самоперевірка: нехай скрипт падає тут, а не в руках агента
node --version
pnpm --version
pnpm exec tsc --version

До останнього блоку варто звикнути. Скрипт, який тихо «пройшов», але не поставив потрібний бінарник, перетворюється на загадкове command not found уже в лозі агента, де незрозуміло, хто винен. Пʼять рядків з виведенням версій і одна перевірочна команда знімають цей клас питань цілком.

Кеш контейнера і maintenance-скрипт: теплий старт проти холодного

Гонити повне встановлення на кожне завдання було б марнотратно, тому Codex кешує стан контейнера — до 12 годин. Перше завдання в репозиторії йде холодним стартом і платить за встановлення; наступні беруть теплий контейнер і стартують помітно швидше.

Кеш скидається автоматично, якщо ви змінили setup-скрипт, maintenance-скрипт, змінні оточення або секрети. Скинути його руками можна кнопкою Reset cache на сторінці оточення — це потрібно, коли репозиторій змінився так, що старий стан став несумісним, наприклад після мажорного оновлення залежностей. У планах Business та Enterprise кеш спільний для всіх, хто має доступ до оточення, тому скидання зачіпає всю команду.

Для теплого старту існує другий скрипт — maintenance. Він запускається під час відновлення кешованого контейнера й потрібен там, де встановлення виконувалося на давнішому коміті, а залежності з того часу поїхали. Розділення просте:

• setup — те, що дорого й змінюється рідко: системні пакети, компіляція, тулчейни.
• maintenance — те, що дешево й змінюється часто: підтягнути свіжі залежності, перегенерувати схему, оновити кодоген.

Є важливе застереження. Дванадцять годин — це стеля, а не обіцянка. З 29 травня 2026 року висить відкрита заявка #25086, де автор із логуванням в обох скриптах показує: повне встановлення виконується на кожній новій сесії, файли з /tmp у наступне завдання не переходять, і повторний запуск «помітно в межах 12 годин» все одно йде як холодний. На 11 серпня 2026 року відповіді мейнтейнерів у заявці немає.

Звідси вимога до скрипта, яку зазвичай формулюють як «зроби його швидким», а формулювати треба інакше: зроби його ідемпотентним і терпимим до холодного старту. Оточення, яке працює лише на теплому контейнері, ненадійне за побудовою. Плюс холодний старт — це ще й витрата вашого вікна використання: як влаштовані ліміти плану, розібрано окремо, але перезапуски завдань витрачають їх нарівні з корисною роботою.

Змінні оточення і секрети: хто доживає до фази агента

У налаштуваннях оточення два схожі на вигляд сховища, і різниця між ними не в зручності, а в тому, хто з них що побачить.

Формулювання документації тут варто запамʼятати дослівно: змінні оточення задані на всю тривалість завдання, включно і зі встановленням, і з роботою агента, а секрети доступні лише setup-скриптам і видаляються до старту агента.

У цього типового налаштування є ціна, про яку зазвичай дізнаються в невідповідний момент. Інтеграційний тест, якому потрібен живий ключ зовнішнього API, у хмарному завданні не пройде: до моменту запуску тестів ключа в контейнері вже немає. У гілці спільноти OpenAI це описано саме так: «мені потрібен доступ до ключів завжди, коли мій код може виконуватися в контейнері, а не лише на старті».

Обхід існує — покласти ключ у змінні оточення замість секретів. Але тоді він перестає бути секретом у прямому сенсі: потрапляє в контекст моделі та в команди, які вона запускає. Заперечення з тієї самої гілки сформульоване жорстко: автор не готовий віддавати моделі секрети, які опиняться в її контексті, бо це дає їй цілковиту свободу дій із ними. Робоча розвʼязка зазвичай така: у хмарі — збирання, лінт і юніт-тести; інтеграційні прогони — локально після появи pull request. Якщо ключ таки потрібен, розумно завести окремий, з мінімальними правами й коротким терміном, а не підкладати робочий.

Окрема пастка — плутанина з переліками змінних. Офіційний реєстр змінних Codex (CODEX_HOME, CODEX_API_KEY, CODEX_ACCESS_TOKEN, RUST_LOG та інші) описує CLI та app-server, тобто локальний інструмент. Хмарного завдання він не стосується: змінні оточення задаються в налаштуваннях оточення й у документації за іменами не перелічені. «Я задав змінну, а її немає» найчастіше означає, що налаштування зроблено не в тому шарі.

Приватні реєстри пакетів: як поставити закриті залежності

Це місце, де обривається більшість інструкцій, — і місце, де найчастіше застрягає перше справжнє завдання. Логіка однакова для всіх менеджерів пакетів: токен кладеться в секрет оточення, авторизація виконується всередині setup-скрипта, у фазу агента токен не переходить.

#!/usr/bin/env bash
set -euo pipefail

# npm: токен приходить із СЕКРЕТА оточення, у репозиторії його немає
npm config set "//registry.npmjs.org/:_authToken=${NPM_TOKEN}"
npm ci

# Composer: приватні пакети авторизуються секретом COMPOSER_AUTH у форматі JSON
composer install --no-interaction --prefer-dist

# git і gh: змінну з іменем GITHUB_TOKEN потрібно ЗНЯТИ перед логіном,
# інакше встановлення падає — Codex перевіряє це сам
token="${GITHUB_TOKEN}"
unset GITHUB_TOKEN
echo "$token" | gh auth login --with-token
gh auth setup-git

Про unset варто сказати окремо, бо помилка виглядає незрозуміло. У рецепті зі спільноти це подано прямим текстом: Codex Cloud сам вимагає, щоб змінну було знято, інакше встановлення впаде на етапі setup. Скрипт при цьому спершу копіює значення в локальну змінну й лише потім знімає початкову — інакше знімати буде нічого.

Другий момент: gh в образі може не виявитися, і його ставлять тим самим apt на початку скрипта. А в maintenance-скрипт із усього цього блоку потрапляє лише перевстановлення адреси віддаленого репозиторію — повторно логінитися під час теплого старту не потрібно.

Проксі й allowlist: мережа є, а потрібний хост недоступний

Самі режими доступу, готові пресети переліку доменів і урізання HTTP-методів докладно розібрані в уроці про режими схвалення та пісочницю Codex — переказувати їх тут немає сенсу. Питання цього розділу інше: як налаштувати мережу оточення так, щоб завдання не спотикалося про те, чого в переліку налаштувань не видно.

Відправна точка — у фазі агента інтернету типово немає, і це свідомий вибір. OpenAI прямо перелічує, чим ризикує той, хто його вмикає: prompt injection з недовірених сторінок, виведення коду або секретів назовні, завантаження шкідливих і вразливих залежностей, підтягування контенту з ліцензійними обмеженнями. Рекомендація вендора — дозволяти лише ті домени й методи, які справді потрібні, і проглядати виведення агента разом із робочим логом.

Звідси порядок, який економить і час, і ризик:

1. Спершу спробуйте обійтися без мережі взагалі. Якщо все поставлено у скрипті, а тести не ходять до зовнішніх API, доступ агентові не потрібен. Це найбезпечніша й найшвидша конфігурація — і водночас найчастіша робоча.
2. Знадобилася мережа — відкривайте її за фактом, а не про запас. Домен додається під конкретне падіння в лозі. Кожен зайвий хост у переліку — це і зайвий ризик, і зайве джерело загадкових відмов, які потім доведеться виключати.
3. Перевіряйте не лише свій перелік. Відмова приходить не тільки від політики оточення — і саме це зʼїдає найбільше часу, бо лікувати намагаються не там. Розбираємо нижче.

І головна неочевидна деталь: увесь вихідний трафік завдання йде через HTTP/HTTPS-проксі оточення. З цього випливають два практичні висновки.

Перший: «інтернет увімкнено» не дорівнює «потрібний хост доступний». У великій гілці спільноти Elixir, що триває з жовтня 2025 року, учасники отримували від реєстру пакетів 403 Forbidden і помилку встановлення TLS-тунелю саме у фазі встановлення, де мережа формально є; при цьому встановлення того самого інструмента безпосередньо з GitHub проходило. Остаточного рішення в гілці немає, а робоча гіпотеза учасників — блокування на боці самого реєстру. Якщо у вас схожа картина, перевіряйте не лише свій allowlist, а й те, чи не відмовляє вам сам хост.

Другий: інструменти з власним сховищем кореневих сертифікатів проксі не довіряють і падають на перевірці. Усередині контейнера для цього є змінна CODEX_PROXY_CERT із сертифікатом проксі — у документації вона не описана, її знайшли на практиці. Лікування — один рядок у setup-скрипті, який вказує інструментові на цей сертифікат:

export SSL_CERT_FILE="$CODEX_PROXY_CERT"
export REQUESTS_CA_BUNDLE="$CODEX_PROXY_CERT"

Імена змінних залежать від інструмента: у Hex це HEX_CACERTS_PATH, у Python-бібліотек — REQUESTS_CA_BUNDLE, багатьом утилітам досить SSL_CERT_FILE. Оскільки змінна офіційно не задокументована, покладатися на неї як на стабільний контракт не варто: перевірте, що вона є, і тримайте у скрипті гілку на випадок її відсутності.

Типові падіння хмарного завдання і шар, де вони лікуються

Помилки оточення виглядають як помилки коду, і це збиває з пантелику. Таблиця нижче співвідносить симптом зі справжньою причиною та із шаром, де правка справді допоможе.

Порядок діагностики варто тримати саме такий: спершу дивіться, у якій фазі впало, потім — чого не вистачило (бінарника, мережі, секрета, часу), і лише потім чіпайте код. Перші два питання знімають більшість падінь узагалі без правок у репозиторії.

Локальне налагодження в codex-universal: те саме оточення в себе

Найнеприємніший сценарій — «локально збирається, у хмарі ні» — лікується тим, що ви перестаєте порівнювати хмару зі своєю машиною й починаєте порівнювати її з публічним образом. Він викладений відкрито, тому перевірка скрипта займає пару хвилин і не витрачає ні лімітів, ні завдань.

docker pull ghcr.io/openai/codex-universal:latest

docker run --rm -it \
  -e CODEX_ENV_PYTHON_VERSION=3.12 \
  -e CODEX_ENV_NODE_VERSION=20 \
  -v "$(pwd)":/workspace/"$(basename "$(pwd)")" \
  -w /workspace/"$(basename "$(pwd)")" \
  ghcr.io/openai/codex-universal:latest

Далі всередині контейнера проганяєте свій setup-скрипт як він є й дивитеся, де він спотикається. Зверніть увагу на шлях монтування: репозиторій кладеться в /workspace/<імʼя-репозиторію> — так само, як це робить хмара, і скрипти, завʼязані на абсолютні шляхи, поводяться однаково.

У методу є чесні межі, і вони названі в самому репозиторії образу: це референсна реалізація, а не ідентичне оточення. На amd64 недоступна одна зі збірок OpenJDK, у arm64-варіанті пропущено Swift. Плюс локально у вас немає проксі оточення й немає видалення секретів перед фазою агента — тобто мережеві та секретні сценарії образ не відтворює. Він відповідає на питання «чи є в контейнері потрібні інструменти й чи проходить мій скрипт», і на це питання відповідає достовірно.

Ще одне спостереження, корисне для планування: конфігурація оточення поки не скриптується — вона живе лише у вебналаштуваннях, а заявка на керування оточеннями з коду (issue #24777 у репозиторії Codex) на 11 серпня 2026 року залишається відкритою. Практична відповідь на це — тримати відтворюваність у самому репозиторії: нехай у вебполі стоїть один рядок виклику файлу scripts/codex-setup.sh, а вся логіка лежить у цьому файлі під контролем версій. Тоді історія змін оточення читається в git, а не відновлюється з памʼяті.

Ризики налаштованого оточення: секрети, мережа і спільний кеш

Добре налаштоване оточення знімає головне джерело провалів, але додає власні. Їх варто знати до того, як ви почнете розширювати доступи.

• Секрет, перекладений у змінні заради фази агента, перестає бути секретом. Він опиняється в контексті моделі та в командах, які вона виконує. Якщо без ключа не обійтися — окремий ключ із мінімальними правами й коротким терміном, а не робочий.
• Увімкнена мережа у фазі агента — це вектор атаки, а не зручність. Інструкція, схована в тексті сторінки чи тікета, може стати командою; запит, що йде назовні, може забрати код. Саме тому OpenAI тримає мережу вимкненою типово, а не тому, що так простіше.
• Скидання кешу в Business та Enterprise зачіпає всіх, хто має доступ до оточення. Серія дрібних правок змінних перед робочим днем команди — це серія холодних стартів у колег.
• Межа часу встановлення не гумова. Скрипт, який сьогодні вкладається в ліміт із запасом двадцять секунд, завтра не вкладеться: реєстр відповість повільніше, залежність підросте.
• Формально увімкнений інтернет не гарантує доступності хоста — відмова може прийти з боку самого реєстру, і у вашому allowlist лікувати буде нічого.
• І противага, щоб картина була повною: типові налаштування тут обрані на користь безпеки, а не зручності, і це правильний компроміс. Вимкнена мережа й стирання секретів роблять витік дорогим одразу, а не після того, як ви про нього згадаєте.

Що в налаштуваннях оточення Codex застаріє першим

Продукт змінюється швидко, тому корисно розуміти, які частини цього матеріалу старіють раніше за інші. Найшвидше поїдуть версії рантаймів в образі: їхній перелік OpenAI оновлює разом із релізами мов, і звіряти його потрібно за репозиторієм образу, а не за статтями. За ними — склад пресета Common dependencies і назви елементів інтерфейсу: кнопки та пункти налаштувань перейменовують без оголошень. Третьою — межа часу setup-скрипта: вона вже змінювалася і, судячи з обговорень, змінюватиметься далі.

Стійка частина, на яку можна опиратися, — сама модель: дві фази з різними правами, кеш зі скиданням за зміною конфігурації, секрети лише для встановлення, мережа агентові типово закрита. За свіжими значеннями йдіть у документацію оточень і в репозиторій образу; за реальною поведінкою, яка в документацію ще не потрапила, — у відкриті заявки репозиторію Codex.

Часті запитання

Чому завдання Codex падає на встановленні залежностей, якщо локально все ставиться?

Майже завжди тому, що встановлення потрапило у фазу агента, де інтернету типово немає: менеджер пакетів не може відкрити зʼєднання з реєстром. Лікується перенесенням встановлення в setup-скрипт, де мережа доступна. Другий за частотою випадок — інструмента просто немає в базовому образі, і його потрібно поставити тим самим скриптом.

Чи можна дати агентові Codex ключ до зовнішнього API у хмарному завданні?

Технічно так — якщо покласти його у змінні оточення, а не в секрети: вони діють усе завдання, включно з роботою агента. Але тоді ключ потрапляє в контекст моделі, і це вже не секрет. Розумніше залишити в хмарі збирання та юніт-тести, а інтеграційні прогони робити локально після появи pull request.

Що робити, якщо setup-скрипт не встигає встановити важкі залежності?

Забирати зі встановлення те, що можна не збирати: ставити готові збірки замість компіляції, обмежувати залежності потрібною групою, кешувати артефакти в образі проєкту. Змінні кроки варто перенести в maintenance-скрипт, який виконується на теплому старті. Сподіватися дотягнути до межі часу не варто — вона вже змінювалася й не розрахована на довгі збірки.

Як змусити Codex перевстановити оточення з нуля?

Натиснути Reset cache на сторінці оточення — це скидає кешований стан контейнера, і наступне завдання піде холодним стартом. Той самий ефект дає будь-яка правка setup-скрипта, maintenance-скрипта, змінних або секретів: кеш скидається автоматично. У планах Business та Enterprise скидання стосується всіх, хто має доступ до оточення.

Чи потрібно вмикати інтернет у фазі агента, якщо залежності вже стоять?

Як правило ні, і це найкращий варіант за замовчуванням. Мережа агентові потрібна у двох випадках: тести звертаються до зовнішнього сервісу або агент мусить щось докачати під час роботи. Якщо вмикаєте, залиште вузький перелік доменів і за можливості вріжте методи до читання — так вектор витоку залишається мінімальним.

Чи можна тримати конфігурацію оточення Codex Cloud у репозиторії?

Цілком поки ні: оточення налаштовуються у вебінтерфейсі, а заявка на керування ними з коду на 11 серпня 2026 року відкрита. Робочий обхідний шлях — залишити у вебполі лише виклик файлу на кшталт bash scripts/codex-setup.sh, а всю логіку встановлення тримати в репозиторії. Тоді зміни оточення проходять рев’ю і видно в історії git.