Codex AGENTS.md не загружается в symlink-рабочих папках: фикс в v0.138 (2026)

Если вы подняли Codex CLI в симлинкованной рабочей папке, а модель делает вид, что AGENTS.md не существует — вы не сошли с ума, вы просто на v0.137 или старше. Релиз v0.138.0 от 8 июня 2026 чинит ровно это, в двух PR, тихо переписавших разрешение путей.

Со скидкой ofox: если устали возиться с CLI и просто хотите GPT-5.3-Codex, маршрутизация через api.ofox.ai даёт $1,49 за 1M input-токенов вместо листового $1,75 — с того же ключа можно отдавать модель в Cursor, Claude Code и собственный harness, минуя весь discovery walk. Лимиты не запрещают вызывать модель из России и СНГ напрямую.

Сценарий повторяется. Заходите в проект, на уровне выше лежит абсолютно валидный AGENTS.md, Codex стартует — и модель игнорирует все правила. Час уходит на проверку, не опечатались ли в имени. Причина почти никогда не в файле. Причина в пути, по которому Codex его искал.

Codex видит ваш AGENTS.md? Диагностика за 30 секунд

Выполните три команды из корня workspace, по порядку. Остановитесь на первой строке, которая помечает проблему.

Если на шаге 1 видна 0.137.x или старше и путь до workspace проходит через симлинк — от ~/work на внешний SSD до Docker bind mount или SSHFS — перестаньте читать и запустите npm install -g @openai/codex@latest. Повторите шаг 2. Судя по тикетам в Codex issues board, одно это обновление снимает тихий пропуск в подавляющем большинстве случаев.

Если шаг 1 уже показывает v0.138+, а шаг 2 не возвращает ваш файл — значит, файл или discovery walk всё ещё перекрыты чем-то. Переходите сразу к разделу «Типичные ошибки загрузки AGENTS.md».

Когда чинить Codex, а когда менять модель

Не каждый симптом «AGENTS.md не грузится» нужно лечить внутри Codex. Некоторые конфигурации просто не вписываются в discovery model, и попытки их подогнать стоят дня работы.

Обновляйтесь и чините на месте, если:

• Вы на v0.137 или старше, а AGENTS.md лежит за симлинком, NFS- или bind-маунтом.
• Перенесли монорепозиторий в worktree, и вложенные AGENTS.md перестали грузиться.
• Remote Codex на sandbox VM перестал видеть AGENTS.md проекта.

Сворачивайте чинку и меняйте рантайм или модель, если:

• Вы поддерживаете pre-v0.91 workflow, который держится на relative-path симлинках для .agents/skills. Issue #9898 закрыта как not planned. Это правило не вернётся. Конвертируйте симлинки в настоящие директории или переходите на CLI, который ходит по симлинкам нативно.
• Склеенный AGENTS.md превысил 32 KiB. Лимит project_doc_max_bytes молча режет файлы, начиная с самых далёких от cwd. Сокращайте инструкции, а не крутите тулинг.
• Вам нужна была не CLI-обвязка, а тренированная под код модель. Перенацельте свой OpenAI SDK на https://api.ofox.ai/v1 и зовите openai/gpt-5.3-codex напрямую — у модели codebase-навигация встроена в обучение, AGENTS.md discovery ей не нужен.

Правило остановки. Если обновились до v0.138, codex doctor рапортует здоровую установку, а файл всё равно не грузится — прекратите ковыряться в discovery-коде Codex. Баг теперь в вашей файловой системе: не те права, пустой stub, override-файл перекрывает. Переходите сразу к шагам верификации в следующем разделе.

Как работает discovery AGENTS.md: что сломало v0.137 и что починила v0.138

Официальные правила discovery AGENTS.md короткие. Из гайда Codex по AGENTS.md:

1. Global. ~/.codex/AGENTS.override.md, затем ~/.codex/AGENTS.md. Первый непустой выигрывает.
2. Project. Идти от Git-корня к cwd. На каждом уровне проверять AGENTS.override.md, потом AGENTS.md, потом имена из project_doc_fallback_filenames.
3. Merge. Конкатенация root-to-cwd. Более близкие к cwd правила перекрывают более ранние.
4. Cap. Суммарный объём ограничен project_doc_max_bytes (32 KiB по умолчанию). Сначала режутся байты, наиболее далёкие от cwd.

То, что v0.137 делала криво, спрятано в шагах 2 и 3. Walk шёл по физическим путям через системные вызовы, и в момент, когда корень workspace пересекал симлинк, пройденные сегменты переставали совпадать с тем, что пользователь имел в виду.

Два реальных режима поломки, повторявшиеся в issue board:

Симлинк корня workspace. ~/work/proj — симлинк на /Volumes/ssd/proj. Кладёте AGENTS.md в ~/work/proj/AGENTS.md. Физическое разрешение приземляется в /Volumes/ssd/proj/AGENTS.md, но детектор Git-корня цеплялся за ~/work и не следовал по симлинку. Walk проходил по [~/work, ~/work/proj], ища файлы, которые физически лежат в другом месте.

Remote workspace через TUI. Файловая система sandbox VM — это snapshot-маунт с другим драйвером. v0.137 читала пути из переменных host-оболочки и пробовала их внутри VM, где некоторые сегменты молча возвращали ENOENT. Walk их выкидывал и шёл дальше.

v0.138.0 чинит оба через два PR:

• PR #26205 — «Route AGENTS.md loading through environment filesystems.» Добавляет абстракцию environment filesystem. Walk теперь спрашивает у драйвера файловой системы самого workspace (local, remote VM, NFS) разрешить каждый сегмент, а не дёргает host-syscall напрямую.
• PR #26465 — «Preserve logical paths during AGENTS.md discovery.» Сохраняет user-visible путь (~/work/proj) на всём walk-е, чтобы симлинки прозрачно вели к физическому назначению, но логический сегмент, на который опирается детектор Git-корня, не терялся.

В официальном changelog запись одна и сухая: «Workspace instruction loading is more accurate for remote and symlinked workspaces, so the right AGENTS.md files are picked up consistently.» Два PR выше — это и есть фикс.

Discovery flow после v0.138

flowchart TD
    A[codex стартует в cwd] --> B{$CODEX_HOME задан?}
    B -- да --> C[Использовать $CODEX_HOME как глобальный корень]
    B -- нет --> D[Использовать ~/.codex как глобальный корень]
    C --> E[Прочитать global AGENTS.override.md, затем AGENTS.md]
    D --> E
    E --> F[Найти Git-корень через env filesystem]
    F --> G[Идти Git root → cwd, уровень за уровнем]
    G --> H{На уровне есть override?}
    H -- да --> I[Добавить override.md в merge buffer]
    H -- нет --> J{Есть AGENTS.md?}
    J -- да --> K[Добавить AGENTS.md в merge buffer]
    J -- нет --> L[Попробовать project_doc_fallback_filenames]
    I --> M{cwd достигнут?}
    K --> M
    L --> M
    M -- нет --> G
    M -- да --> N[Склеить, обрезать по 32 KiB]
    N --> O[Инжектить как системные инструкции]

Порядок discovery и приоритеты

Все непустые совпадения конкатенируются. Суммарный размер ограничен 32 KiB. При обрезке выживает контент, ближний к cwd.

Как починить «AGENTS.md не загружается»: решения для каждой конфигурации

Решение 1: локальная симлинкованная рабочая папка

Самый частый случай — Mac с ~/work, симлинкованной на внешний SSD, или Linux-машина с ~/dev на быстром NVMe-разделе. После апгрейда до v0.138:

npm install -g @openai/codex@latest
codex --version    # ожидается 0.138.0 или новее
cd ~/work/proj
codex --ask-for-approval never "Подведи итог текущих инструкций."

В сводке должен фигурировать ~/work/proj/AGENTS.md (или физический путь, в который он резолвится). Если не фигурирует — три быстрых проверки:

1. Файл непустой. wc -c AGENTS.md должна вернуть минимум 1 байт. Нулевые файлы пропускаются молча — свежий touch AGENTS.md, после которого редактор упал, оставляет такой stub чаще, чем кажется.
2. Override не перекрывает. find ~/.codex ~/work -name 'AGENTS.override.md' 2>/dev/null. Любое непустое попадание выше по дереву побеждает ваш проектный файл.
3. $CODEX_HOME не перенаправлен. echo $CODEX_HOME должна быть пустой или ~/.codex. Если вы выставили её на проектный профиль в каком-то эксперименте — global override hunt идёт внутри этого профиля, а не ~/.codex.

Решение 2: Remote workspace (Remote TUI / облачный sandbox)

Remote Codex запускает модельную сторону внутри sandbox VM, а TUI шлёт команды через WebSocket. v0.137 форвардила host-resolved пути, которые VM не всегда могла разрешить повторно. Абстракция environment filesystem из v0.138 разрешает пути изнутри workspace-процесса.

codex --remote ws://your-remote-endpoint
# затем внутри TUI:
/status

/status показывает активную модель, политику апрувов, writable roots, текущий расход токенов и — при удалённом подключении — remote-адрес и версию сервера. Если /status показывает не тот корень workspace или модель ведёт себя так, будто AGENTS.md не загружен — проблема в вашей WebSocket-сессии или в маунте workspace, не в discovery walk. Выйдите из TUI и переподключитесь через codex --remote ws://....

Решение 3: монорепо с вложенными AGENTS.md

До v0.138 монорепозитории теряли вложенные файлы. Issue #13288 зафиксировала каноничную раскладку:

~/monorepo
├── AGENTS.md           # правила всего репо
├── java/
│   └── AGENTS.md       # правила Java-сервиса
├── go/
│   └── AGENTS.md       # правила Go-сервиса
└── packages/web/
    └── AGENTS.md       # правила фронтенда

В v0.137, запуская Codex из ~/monorepo с просьбой поправить java/UserService.java, вы получали загруженным только корневой AGENTS.md. В v0.138 walk пересекает ~/monorepo → java, склеивает оба файла в этом порядке. Более близкая к cwd инструкция выигрывает при пересечении правил.

Лимит 32 KiB важен в реальном монорепо. Если корневой файл — 28 KiB общефирменных конвенций, в склейку из java/AGENTS.md влезет только 4 KiB. Сокращайте корень или растащите правила так, чтобы каждый лист нёс только то, чего корень сказать не может.

Быстрый способ узнать, какой именно файл Codex подхватил, — положите уникальный маркер в начало каждого AGENTS.md, одну строку вроде <!-- agents-marker:java -->, и попросите модель повторить маркер, который она видит. Должен прийти маркер, ближайший к cwd.

Три шага верификации, которые стоит прогнать после v0.138

Сам апгрейд — одна команда. Сложнее убедиться, что апгрейд реально подействовал на вашу конкретную раскладку — особенно если вы неделями жили с тихим пропуском и научились ему не доверять. Эти три шага укладываются в две минуты и закрывают режимы поломок, на которые приходится основной поток вопросов post-upgrade в Codex issues.

Шаг 1: попросите Codex перечислить цепочку инструкций

Главная команда верификации из официального гайда AGENTS.md — один неинтерактивный prompt. Запустите из самой глубокой директории, из которой вы реально стартуете Codex, и он перечислит каждый AGENTS.md и AGENTS.override.md, который подтянул, в порядке приоритета.

cd ~/monorepo/java
codex --ask-for-approval never "Подведи итог текущих инструкций. Перечисли каждый путь AGENTS.md, который ты загрузил, и в каком порядке они склеены."

Три сигнала, которые стоит вычитать из вывода. Во-первых, число файлов: если у вас есть вложенный файл, который должен загрузиться, а в сводке его нет — walk пропустил этот уровень (часто потому, что эта директория на другой файловой системе, чем родительская). Во-вторых, общий смысл: если правила из листа отсутствуют в сводке, скорее всего лимит 32 KiB их обрезал — Codex пропускает файл до инжекта в таком случае. В-третьих, порядок: Codex склеивает root-to-cwd, и более близкие файлы перекрывают совпадающие правила. Если порядок выглядит наоборот — у вас почти наверняка остался stale $CODEX_HOME от предыдущей сессии.

Чтобы заодно получить чистый отчёт о корне workspace и состоянии конфига, codex doctor (или codex doctor --json для machine-parsable вывода) печатает диагностику install/auth/runtime/config — полезно, чтобы исключить неверную конфигурацию Codex до того, как обвинять discovery walk.

Шаг 2: прогоните sentinel-маркер через модель

Сводка с шага 1 подтверждает, какие файлы Codex назвал, но не подтверждает, что каждый байт дожил до модели. Эти две вещи расходятся, если лимит 32 KiB обрезал секцию или хук в вашем harness снял system prompt.

Положите уникальный sentinel в начало каждого AGENTS.md в цепочке:

<!-- agents-marker:java-leaf -->

Затем в свежей сессии попросите модель: «Повтори дословно каждый комментарий agents-marker:*, который ты видишь в системных инструкциях.» Если все маркеры вернулись — merge выжил. Если вернулся только корневой, а листа нет — вы упёрлись в 32 KiB, надо подрезать корень до того, как обрежется лист.

Тот же приём ловит случай override-перекрытия. Положите agents-marker:override в любой AGENTS.override.md, и вы сразу увидите, не перекрывает ли ваш базовый файл какой-то override, о котором вы давно забыли.

Шаг 3: round-trip тест симлинка

Третий шаг существует, чтобы ловить одну конкретную регрессию, которую v0.138 починила, но которую легко вернуть случайно — запуск Codex против пути, который сам является симлинком, а не просто лежит внутри симлинкованной директории.

mkdir -p /tmp/codex-sym-test/real
echo "<!-- agents-marker:symtest -->" > /tmp/codex-sym-test/real/AGENTS.md
ln -s /tmp/codex-sym-test/real /tmp/codex-sym-test/linked
cd /tmp/codex-sym-test/linked
codex --ask-for-approval never "Повтори дословно каждый комментарий agents-marker, который ты видишь в системных инструкциях."

Если сводка возвращает <!-- agents-marker:symtest -->, абстракция environment filesystem работает в вашей установке. Если маркер отсутствует — либо апгрейд не приехал (перепроверьте codex --version), либо realpath в вашей shell даёт другой физический путь, чем видит workspace-процесс. Перенесите тестовую директорию в $HOME и попробуйте снова до того, как открывать issue.

Эти три проверки — то, что стоит положить в runbook на случай, если кто-то из команды через три месяца наступит на тот же симптом. Поток верификации один и тот же, неважно с чего начали — симлинкованный workspace, удалённый sandbox или подпапка монорепо. Вопрос всегда один: «увидел ли Codex файл так же, как я ожидаю».

Типичные ошибки загрузки AGENTS.md

История фиксов AGENTS.md: реальные issue 2026 года

Путь к v0.138 не был одним фиксом — это была цепочка похожих репортов, часть из которых отклонили до того, как приземилась workspace-абстракция. Шаблон показывает, куда проект реально инвестирует.

Разлом очевиден. Каждый репорт про симлинки на SKILL.md или дерево .agents/skills закрыли как not planned. Только AGENTS.md и резолв корня workspace признали достойными работы с абстракцией. Если ваш workflow держится на симлинке самой скилл-директории — v0.138 не делает для вас ничего, конвертируйте в настоящие директории или берите CLI, в котором симлинки first-class.

Когда Codex не может прочитать ваши инструкции: альтернативы, которые работают сейчас

Для большинства команд правильный ответ — просто «обновитесь до v0.138». Эти альтернативы — для пограничных случаев, где discovery model Codex по-прежнему не вписывается.

Альтернативы кратко

1. Звать GPT-5.3-Codex напрямую через ofox

Если Codex вы держали ради самой модели — 512K контекста, agentic tool use, codebase navigation — пропустите CLI. Модель работает через OpenAI-совместимый эндпоинт ofox. Прочитайте AGENTS.md в своём harness и передавайте как system prompt:

from openai import OpenAI
client = OpenAI(base_url="https://api.ofox.ai/v1", api_key="ofox-...")
with open("AGENTS.md") as f:
    house_rules = f.read()
resp = client.chat.completions.create(
    model="openai/gpt-5.3-codex",
    messages=[{"role": "system", "content": house_rules},
              {"role": "user", "content": "Перепиши UserService.java на async."}],
)
print(resp.choices[0].message.content)

Это полностью обходит discovery walk. Платите тем, что переписываете чтение файла, многоуровневый merge и семантику override в своём harness — но и перестаёте воевать с разрешением симлинков. Цена на ofox: $1,49/M input и $11,90/M output после стандартной скидки, cache reads $0,153/M (листовая ставка input — $1,75/M). Для пользователей из России и СНГ это, дополнительно, прямой доступ без VPN и без визовых требований к платёжке.

2. Закрепиться на настоящих директориях, выкинуть симлинки

Если менять модель не хочется, прагматичный патч — cp -r вместо ln -s. Настоящие директории работают в любой версии Codex, включая pre-v0.91. Ревьюверы issue #9898, #10470 и #11314 высказались прямо: симлинки в дереве скиллов не first-class, и таковыми не станут. Считайте это фактом и стройте проект вокруг него.

Workflow с общей библиотекой, который раньше симлинковал .agents/skills, можно перевести на закоммиченный subtree или git submodule. И то и другое резолвится в настоящие директории на диске и загружается в любой версии Codex.

3. Claude Code или Cursor для symlink-heavy workflows

Claude Code и Cursor оба читают правила проекта с физических путей и идут по симлинкам по умолчанию. Если у вашей команды дерево .agents/skills симлинкуется через много репозиториев как общая библиотека правил — ни один из этих инструментов не будет с вами спорить. Выставьте OPENAI_BASE_URL=https://api.ofox.ai/v1 в обоих, чтобы маршрутизировать на тот же бэкенд, что использует Codex, и выбор модели стал независимым от выбора CLI.

Это смена инструмента, не смена модели. Через любой из них можно по-прежнему звать openai/gpt-5.3-codex.

4. Остаться на v0.137 с обходом

Если апгрейд сегодня невозможен — заблокированная CI, vendored binary, замороженный Docker-образ — обход в том, чтобы скопировать разрешённый AGENTS.md в директорию, которую walk v0.137 реально посещает:

cp "$(realpath ~/work/proj/AGENTS.md)" ~/work/proj/AGENTS.md.physical
mv ~/work/proj/AGENTS.md.physical ~/work/proj/AGENTS.md

Решение неэлегантное. Плюс заставляет вручную пересинхронизировать файл при каждом изменении источника. Обновляйтесь сразу, как только закончится заморозка.

Как мониторить загрузку AGENTS.md и получать алёрты

Тихий режим поломки возможен и на v0.138. Кто-то добавляет AGENTS.override.md в родительской директории, перекрывает ваш файл, и поведение модели меняется без ошибок. Два практичных предохранителя ловят это до того, как съест день отладки.

Прогон sentinel-маркера в preflight

Sentinel можно прогнать через модель одной неинтерактивной командой и завалить CI, если он не вернётся. Положите одну строку <!-- agents-marker:repo-root --> в начало проектного AGENTS.md, затем:

#!/bin/bash
# scripts/preflight-codex.sh
marker="agents-marker:repo-root"
out="$(codex --ask-for-approval never exec \
  "Повтори дословно каждый комментарий agents-marker, который видишь в своих системных инструкциях.")"
echo "$out" | grep -q "$marker" || {
  echo "AGENTS.md не загружен: маркер '$marker' отсутствует в ответе"; exit 1; }

Обратите внимание на порядок флагов: --ask-for-approval — глобальный флаг и должен предшествовать subcommand exec. codex exec --ask-for-approval never будет отклонён как неизвестный флаг exec.

Прицепите скрипт к npm run codex или другой команде команды — CI поймает override-перекрытие и обрезку до того, как кто-то будет искать, почему модель «забыла» гайд по стилю.

Следить за override-файлами на уровне репо

Добавьте **/AGENTS.override.md в .gitignore репозитория. git status будет помечать любой новый override, который появится после эксперимента коллеги, а gitignore защитит от случайного коммита. Дополните Renovate- или Dependabot-правилом, бампающим @openai/codex — команда будет автоматически подбирать будущие discovery-фиксы без ручных апгрейдов.

Зафиксировать версию Codex в package.json

{
  "engines": {
    "codex": ">=0.138.0 <0.140.0"
  }
}

Изменения discovery ездят без фича-флага, и v0.137 → v0.138 — свежий пример. Закрепление диапазона в engines (или эквиваленте в вашем реестре инструментов) не даст latest сдвинуть команду на изменённое поведение, которое никто не ревьюил. Подпишитесь на фид релизов Codex и поднимайте верхнюю границу после тестов.

Источники, проверенные при подготовке материала

• Changelog OpenAI Codex (июнь 2026) (проверено 2026-06-10)
• Гайд Codex по discovery AGENTS.md (проверено 2026-06-10)
• openai/codex Release v0.138.0 (проверено 2026-06-10, релиз 2026-06-08 23:00 UTC)
• GitHub Issues: #8759, #9898, #11314, #13288
• Страница модели GPT-5.3-Codex на ofox (проверено 2026-06-10, $1,49/M input / $11,90/M output / $0,153/M cache read — со скидкой ofox; листовая $1,75/M input)
• Связанные материалы: codex: command not found — 7 решений, Codex CLI: настройка API и подключение провайдеров

Урок из года симлинк-репортов простой: Codex относится к AGENTS.md как к first-class концепту, а к .agents/skills — как к недокументированному поведению. Если ваш workflow держится на втором — меняйте инструмент, не ждите v0.139, которой не будет.