Среда выполнения Codex harness

Контракт среды выполнения для ходов в инфраструктуре Codex. Сведения о настройке и маршрутизации см. в разделе Инфраструктура Codex. Поля конфигурации описаны в справочнике по инфраструктуре Codex.

Обзор

Codex управляет нативным циклом модели, нативным возобновлением потоков, нативным продолжением работы инструментов и нативной Compaction. OpenClaw управляет маршрутизацией каналов, файлами сеансов, доставкой видимых сообщений, динамическими инструментами OpenClaw, подтверждениями, доставкой медиафайлов и зеркалом расшифровки на этой границе.

Маршрутизация запросов определяется выбранной средой выполнения, а не только строкой провайдера. Нативный ход Codex получает инструкции разработчика от app-server Codex; при явном выборе маршрута совместимости OpenClaw сохраняется обычный системный запрос OpenClaw, даже если используются аутентификация или транспорт OpenAI в стиле Codex.

OpenClaw запускает и возобновляет нативные потоки Codex с отключённой встроенной индивидуальностью Codex (personality: "none"), чтобы файлы индивидуальности рабочей области и идентичность агента OpenClaw оставались авторитетными. В остальном нативный Codex сохраняет базовые инструкции и инструкции модели, принадлежащие Codex, а также загрузку документации проекта. В облегчённых запусках OpenClaw (например, Cron) загрузка документации проекта по-прежнему отключается.

Инструкции разработчика OpenClaw охватывают аспекты среды выполнения OpenClaw: доставку в исходный канал, динамические инструменты OpenClaw, делегирование ACP, контекст адаптера и активные файлы профиля рабочей области агента. Каталоги навыков и указатели MEMORY.md, направляемые через инструменты, проецируются как инструкции разработчика для совместной работы в рамках хода. Когда инструменты памяти недоступны, активное содержимое BOOTSTRAP.md и полный MEMORY.md вместо этого передаются в обычном входном контексте хода.

Большинство динамических инструментов OpenClaw используют доступное для поиска пространство имён openclaw. Инструменты с пометкой catalogMode: "direct-only" используют openclaw_direct, которое Codex сохраняет непосредственно видимым модели как DirectModelOnly, не предоставляя его вложенному выполнению в режиме кода.

Привязки потоков и смена моделей

Когда сеанс OpenClaw присоединён к существующему потоку Codex, следующий ход повторно отправляет app-server текущую выбранную модель, политику подтверждений, песочницу, средство проверки подтверждений и уровень обслуживания. При переходе с openai/gpt-5.5 на openai/gpt-5.2 привязка потока сохраняется, но Codex получает запрос продолжить работу с новой выбранной моделью.

Контролируемые привязки являются исключением. Выбор модели OpenClaw остаётся заблокированным, а при возобновлении переопределения модели и провайдера не передаются, поэтому Codex восстанавливает сохранённые модель и провайдера канонического потока. Отдельный нативный элемент управления Codex может изменить эту сохранённую пару, а исходный снимок состояния может вызвать обычное предупреждение Codex о различии моделей; внешняя модель OpenClaw и цепочка резервных вариантов никогда не подменяют ни один из этих параметров.

Контроль и безопасное продолжение

Контроль Codex — это включаемая по желанию возможность того же плагина codex. Он обнаруживает нативные потоки через отдельное соединение и проецирует в каталог Gateway только неархивированные сеансы. Если параметры соединения appServer не заданы явно, это соединение использует управляемый stdio из домашнего каталога пользователя, а обычная инфраструктура остаётся привязанной к агенту. Получение списка и чтение метаданных пассивны: они не возобновляют поток, не подписывают OpenClaw на его события в реальном времени и не отвечают на его запросы подтверждения.

Для сохранённого или бездействующего сеанса на компьютере Gateway действие Продолжить как ветвь создаёт обычный чат с заблокированной моделью и зеркалирует ограниченную историю сообщений пользователя и ассистента вплоть до последнего сохранённого завершённого хода источника. Первый обычный ход чата устанавливает настоящие обработчики подтверждений и использует временное нативное ответвление, чтобы закрепить снимок состояния без переопределения модели или провайдера. Codex App Server использует текущую нативную конфигурацию и возвращает выбранную пару; если эта модель отличается от последней зарегистрированной модели источника, он выдаёт обычное предупреждение. Через то же контрольное соединение OpenClaw запускает канонический поток инфраструктуры Codex с источником appServer в его рабочем каталоге и с его политикой среды выполнения, используя для первоначального запуска в точности возвращённые модель и провайдера, внедряет ограниченную видимую историю и архивирует временное ответвление. Исходный поток никогда не возобновляется. Канонический поток располагает полным набором инструментов инфраструктуры OpenClaw; рассуждения, вызовы инструментов и результаты их работы из исходного потока в него не клонируются. Область приватного соединения сохраняется в ожидающих и зафиксированных состояниях привязки, поэтому каждый последующий ход остаётся в этом соединении с нативной аутентификацией и конфигурацией провайдера. При отключённом контроле или расхождении привязки либо соединения система безопасно завершает операцию с отказом, а не переключается на обычную инфраструктуру из домашнего каталога агента.

Исходный поток CLI или VS Code остаётся доступным в обоих каталогах. Каноническая ветвь является нативным потоком Codex, но тип её источника — appServer; нативные клиенты могут отфильтровывать этот тип источника, поэтому отображение ветви в Codex Desktop не гарантируется.

Для активных источников нельзя создать новую ветвь или выполнить архивацию; существующий контролируемый чат при этом по-прежнему можно открыть. notLoaded означает, что активность неизвестна, а не что поток бездействует; OpenClaw разрешает архивацию локальной строки idle или notLoaded только после явного подтверждения отсутствия другого исполнителя и нового чтения состояния в рамках локального процесса. Codex сериализует изменения потоков в пределах одного процесса App Server, но не предоставляет эксклюзивную межпроцессную аренду исполнителя или владельца подтверждений, поэтому такое чтение не может доказать, что поток не используется другим процессом. OpenClaw блокирует известного активного владельца привязки для точной цели или любого неархивированного порождённого потомка, возвращённого постраничным запросом потомков Codex. Ошибки перечисления, циклы и исчерпание пределов безопасности приводят к безопасному отказу. Нативная архивация всё ещё может вступить в гонку с новым ходом в другом процессе, поэтому подтверждение охватывает неизвестные клиенты и промежуток между чтением состояния и архивацией. Контролируемый чат с заблокированной моделью нельзя удалить, пока он защищает нативную привязку.

Каталоги сопряжённых узлов в первом выпуске содержат только метаданные. Текущая граница вызова узла работает по схеме «запрос — ответ» и не может передавать долгоживущие события хода, запросы подтверждения или потоковый вывод, необходимые для настоящей привязки инфраструктуры Codex. Поэтому удалённые действия Продолжить и Архивировать остаются недоступными, даже когда строка находится в состоянии бездействия.

Сведения о настройке оператором и видимом поведении Control UI см. в разделе Контроль Codex.

Видимые ответы и Heartbeat

Для прямых ходов и ходов исходного чата через инфраструктуру Codex по умолчанию включена автоматическая доставка окончательного ответа ассистента на внутренних поверхностях WebChat в соответствии с контрактом инфраструктуры Pi: агент отвечает обычным образом, а OpenClaw публикует окончательный текст в исходной беседе. Установите messages.visibleReplies: "message_tool", чтобы окончательный текст ассистента оставался приватным, если агент не вызовет message(action="send").

Ходы Heartbeat Codex по умолчанию получают heartbeat_respond в доступном для поиска каталоге инструментов OpenClaw, чтобы агент мог указать, следует ли пробуждению остаться незаметным или отправить уведомление. Рекомендации по инициативности Heartbeat передаются как инструкция разработчика режима совместной работы Codex, действующая только в рамках хода Heartbeat; обычные ходы чата остаются в режиме Codex Default. Если HEARTBEAT.md не пуст, инструкции Heartbeat указывают Codex на файл вместо встраивания его содержимого.

Границы хуков

OpenClaw не использует проектные или глобальные файлы Codex hooks.json для маршрутизации поведения плагинов. Для моста нативных инструментов и разрешений OpenClaw внедряет в каждый поток конфигурацию Codex для PreToolUse, PostToolUse, PermissionRequest и Stop.

Когда подтверждения app-server Codex включены (approvalPolicy не равно "never"), внедряемая по умолчанию конфигурация нативных хуков не включает PermissionRequest, чтобы средство проверки app-server Codex и мост подтверждений OpenClaw обрабатывали реальные запросы повышения прав после проверки. Добавьте permission_request в nativeHookRelay.events, чтобы всё равно принудительно использовать ретранслятор совместимости. Другие хуки Codex, такие как SessionStart и UserPromptSubmit, остаются элементами управления уровня Codex; в контракте v1 они не предоставляются как хуки плагинов OpenClaw.

Для динамических инструментов OpenClaw сам OpenClaw выполняет инструмент после того, как Codex запрашивает вызов, поэтому поведение плагинов и промежуточного слоя выполняется в адаптере инфраструктуры. Для нативных инструментов Codex канонической записью инструмента управляет Codex; OpenClaw может зеркалировать выбранные события, но не может изменять нативный поток, если Codex не предоставляет такую возможность через app-server или обратные вызовы нативных хуков.

События PreToolUse режима отчётов app-server Codex откладывают подтверждение плагина до соответствующего подтверждения app-server. Если хук OpenClaw before_tool_call возвращает requireApproval, а в нативной полезной нагрузке задано openclaw_approval_mode: "report", ретранслятор нативных хуков регистрирует требование подтверждения плагина и не возвращает нативное решение. Когда позднее Codex отправляет запрос подтверждения app-server для того же использования инструмента, OpenClaw открывает запрос подтверждения плагина и передаёт решение обратно в Codex. События Codex PermissionRequest представляют собой отдельный путь подтверждения и при соответствующей настройке моста также могут направляться через подтверждения OpenClaw.

Уведомления app-server Codex об элементах также предоставляют асинхронные наблюдения after_tool_call для завершений нативных инструментов, ещё не охваченных нативным ретранслятором PostToolUse. Они предназначены только для телеметрии и совместимости; они не могут блокировать, задерживать или изменять вызов нативного инструмента.

Проекции Compaction и жизненного цикла LLM поступают из уведомлений app-server Codex и состояния адаптера OpenClaw, а не из команд нативных хуков Codex. before_compaction, after_compaction, llm_input и llm_output являются наблюдениями уровня адаптера, а не побайтовыми копиями внутренних запросов или полезных нагрузок Compaction Codex.

Нативные уведомления app-server Codex hook/started и hook/completed проецируются как события агента codex_app_server.hook для отслеживания траектории и отладки. Они не вызывают хуки плагинов OpenClaw.

Контракт поддержки V1

Поддерживается в среде выполнения Codex v1:

Не поддерживается в среде выполнения Codex v1:

Нативные разрешения и запросы MCP

Для PermissionRequest OpenClaw возвращает явные решения о разрешении или запрете, только когда политика принимает решение. Отсутствие решения не означает разрешение: Codex трактует это как отсутствие решения хука и передаёт запрос собственному защитному механизму или в путь подтверждения пользователем.

Режимы подтверждения сервера приложения Codex по умолчанию не используют этот нативный хук. Это правило действует, если permission_request явно не включён в nativeHookRelay.events или его не устанавливает совместимая среда выполнения.

Когда оператор выбирает allow-always для запроса нативного разрешения Codex, OpenClaw запоминает точный отпечаток поставщика, сеанса, входных данных инструмента и cwd на ограниченный период сеанса. Запомненное решение преднамеренно применяется только при точном совпадении: изменённая команда, аргументы, полезная нагрузка инструмента или cwd создают новый запрос подтверждения.

Запросы подтверждения инструментов Codex MCP направляются через поток подтверждения плагинов OpenClaw, когда Codex помечает _meta.codex_approval_kind как "mcp_tool_call". Запросы Codex request_user_input отправляются обратно в исходный чат, а следующее поставленное в очередь последующее сообщение отвечает на этот нативный запрос сервера, а не направляется как дополнительный контекст. Прочие запросы MCP отклоняются при отсутствии явного разрешения.

Общий поток подтверждения плагинов, передающий эти запросы, описан в разделе Запросы разрешений плагинов.

Управление очередью

Управление очередью активного запуска сопоставляется с turn/steer сервера приложения Codex. При стандартном messages.queue.mode: "steer" OpenClaw объединяет сообщения чата в режиме управления за настроенное окно ожидания и отправляет их одним запросом turn/steer в порядке поступления.

Проверка Codex и ходы ручной Compaction могут отклонять перенаправление в том же ходе. В этом случае OpenClaw ожидает завершения активного запуска, прежде чем начать обработку запроса. Используйте /queue followup или /queue collect, если сообщения по умолчанию должны добавляться в очередь, а не перенаправлять текущий ход. См. Очередь перенаправления.

Отправка отзывов Codex

Когда /diagnostics [note] одобрена для сеанса в нативной среде Codex, OpenClaw также вызывает feedback/upload сервера приложений Codex для соответствующих веток Codex, включая журналы каждой указанной ветки и порождённых подветок Codex, если они доступны.

Отправка выполняется через обычный механизм отзывов Codex на серверы OpenAI. Если отправка отзывов Codex отключена на этом сервере приложений, команда возвращает ошибку сервера приложений. В ответе о завершённой диагностике перечисляются каналы, идентификаторы сеансов OpenClaw, идентификаторы веток Codex и локальные команды codex resume <thread-id> для отправленных веток.

Если вы отклоните или проигнорируете запрос на одобрение, OpenClaw не выведет эти идентификаторы Codex и не отправит отзыв Codex. Отправка не заменяет локальный экспорт диагностики Gateway. Сведения об одобрении, конфиденциальности, локальном пакете и поведении в групповых чатах см. в разделе Экспорт диагностики.

Используйте /codex diagnostics [note] только тогда, когда требуется отправить отзыв Codex для текущей подключённой ветки без полного пакета диагностики Gateway.

Compaction и зеркало расшифровки

Когда выбранная модель использует среду Codex, нативная Compaction ветки выполняется сервером приложений Codex. OpenClaw не выполняет предварительную Compaction для ходов Codex, не заменяет Compaction Codex сжатием контекстного движка и не переходит к суммаризации OpenClaw или общедоступного OpenAI, если нативную Compaction не удаётся запустить. OpenClaw хранит зеркало расшифровки для истории канала, поиска, /new, /reset и будущего переключения модели или среды.

Явные запросы Compaction, такие как /compact или запрошенная плагином ручная операция сжатия, запускают нативную Compaction Codex с помощью thread/compact/start. OpenClaw оставляет запрос и аренду общего клиента открытыми, пока Codex не выдаст соответствующий элемент завершения contextCompaction, после чего сообщает о завершении хода Compaction. Если этот завершающий ход превышает настроенный тайм-аут Compaction, OpenClaw запрашивает нативное прерывание хода. Аренда и блокировка Compaction для ветки остаются удержанными, пока Codex не сообщит конечное состояние или не подтвердит RPC прерывания. Если Codex не подтвердит его в течение льготного периода прерывания, OpenClaw выводит соединение из эксплуатации, прежде чем снять блокировку. Для удалённых соединений также отсоединяется соответствующая привязка ветки, чтобы последующая работа не могла пересекаться с неподтверждённым удалённым ходом. Другие ходы в выведенном из эксплуатации соединении завершаются ошибкой и могут быть повторены с новым клиентом. Закрытие клиента, отмена запроса или неудачный ход Compaction возвращают неудачную операцию. Автоматическая Compaction при нехватке контекста выполняется Codex; OpenClaw запускает нативную Compaction только для запрошенных вручную триггеров.

Когда контекстный движок запрашивает проекцию начальной загрузки ветки Codex, OpenClaw проецирует имена и идентификаторы вызовов инструментов, структуры входных данных и отредактированное содержимое результатов инструментов в новую ветку Codex. Необработанные значения аргументов вызовов инструментов в эту проекцию не копируются.

Зеркало включает запрос пользователя, окончательный текст ассистента и облегчённые записи рассуждений или плана Codex, когда сервер приложений их выдаёт. OpenClaw записывает начало нативной Compaction и её конечное состояние, но не предоставляет удобочитаемую сводку Compaction или доступный для аудита список записей, сохранённых Codex после Compaction.

Поскольку канонической нативной веткой управляет Codex, tool_result_persist не перезаписывает нативные записи результатов инструментов Codex. Она применяется только тогда, когда OpenClaw записывает результат инструмента в расшифровку сеанса, принадлежащую OpenClaw.

Мультимедиа и доставка

OpenClaw по-прежнему управляет доставкой мультимедиа и выбором поставщика мультимедиа. Для изображений, видео, музыки, PDF, TTS и анализа мультимедиа используются соответствующие настройки поставщика и модели, такие как agents.defaults.imageGenerationModel, videoGenerationModel, pdfModel и messages.tts.

Текст, изображения, видео, музыка, TTS, одобрения и вывод инструментов обмена сообщениями по-прежнему проходят через обычный механизм доставки OpenClaw; для создания мультимедиа устаревшая среда выполнения не требуется. Когда Codex выдаёт нативный элемент создания изображения с savedPath, OpenClaw пересылает этот точный файл через обычный путь мультимедиа в ответе, даже если ход Codex не содержит текста ассистента.

См. также

• Среда Codex
• Справочник по среде Codex
• Контроль Codex
• Нативные плагины Codex
• Перехватчики плагинов
• Плагины среды агентов
• Экспорт диагностики
• Экспорт траектории