Справочник по среде выполнения Codex

Этот справочник описывает подробную конфигурацию для встроенного Plugin codex. Для настройки и решений о маршрутизации начните с Harness Codex.

Поверхность конфигурации Plugin

Все настройки harness Codex находятся в plugins.entries.codex.config.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },          appServer: {            mode: "guardian",          },        },      },    },  },}

Поддерживаемые поля верхнего уровня:

Транспорт app-server

По умолчанию OpenClaw запускает управляемый бинарный файл Codex, поставляемый со встроенным Plugin:

codex app-server --listen stdio://

При этом версия app-server остается привязанной к встроенному Plugin codex, а не к какому-либо отдельному Codex CLI, который может быть установлен локально. Задавайте appServer.command только если намеренно хотите запустить другой исполняемый файл.

Для уже запущенного app-server используйте транспорт WebSocket:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",            requestTimeoutMs: 60000,          },        },      },    },  },}

Поддерживаемые поля appServer:

appServer.networkProxy задан явно, потому что он меняет контракт песочницы Codex. Когда он включен, OpenClaw также задает features.network_proxy.enabled и default_permissions в конфигурации треда Codex, чтобы сгенерированный профиль разрешений мог запустить управляемую сеть Codex. По умолчанию OpenClaw генерирует устойчивое к коллизиям имя профиля openclaw-network-<fingerprint> из тела профиля; используйте profileName только когда требуется стабильное локальное имя.

export default {  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },};

Если обычная среда выполнения app-server использовала бы danger-full-access, включение networkProxy использует доступ к файловой системе в стиле рабочей области для созданного профиля разрешений. Управляемое Codex сетевое принудительное применение правил — это песочница для сети, поэтому профиль с полным доступом не защитил бы исходящий трафик.

Plugin блокирует более старые или неверсионированные рукопожатия app-server. Codex app-server должен сообщать стабильную версию 0.125.0 или новее.

OpenClaw считает WebSocket URL app-server не на loopback удаленными и требует WebSocket-аутентификацию с идентификацией через appServer.authToken или заголовок Authorization. appServer.authToken и каждое значение appServer.headers.* могут быть SecretInput; среда выполнения секретов разрешает SecretRefs и сокращенную запись env до того, как OpenClaw создает параметры запуска app-server, а неразрешенные структурированные SecretRefs завершаются ошибкой до отправки любого токена или заголовка. Когда настроены нативные Codex plugins, OpenClaw использует плоскость управления plugins подключенного app-server, чтобы установить или обновить эти plugins, а затем обновляет инвентарь приложений, чтобы приложения, принадлежащие plugins, были видны потоку Codex. app/list по-прежнему является авторитетным источником инвентаря и метаданных, но политика OpenClaw решает, должен ли thread/start отправлять config.apps[appId].enabled = true для указанного доступного приложения, даже если Codex сейчас помечает его как отключенное. Неизвестные или отсутствующие id приложений остаются закрытыми при ошибке; этот путь активирует только marketplace plugins через plugin/install и обновляет инвентарь. Подключайте OpenClaw только к тем удаленным app-server, которым доверено принимать управляемые OpenClaw установки plugins и обновления инвентаря приложений.

Режимы подтверждений и песочницы

Локальные stdio-сеансы app-server по умолчанию используют режим YOLO: approvalPolicy: "never", approvalsReviewer: "user" и sandbox: "danger-full-access". Такая позиция доверенного локального оператора позволяет автономным ходам OpenClaw и Heartbeat продвигаться без нативных запросов подтверждения, на которые некому ответить.

Если локальный файл системных требований Codex запрещает неявные значения YOLO для подтверждений, проверяющего или песочницы, OpenClaw вместо этого считает неявное значение по умолчанию guardian и выбирает разрешенные разрешения guardian. tools.exec.mode: "auto" также принудительно включает подтверждения Codex с проверкой guardian и не сохраняет небезопасные устаревшие переопределения approvalPolicy: "never" или sandbox: "danger-full-access"; установите tools.exec.mode: "full" для намеренного режима без подтверждений. Записи [[remote_sandbox_config]] с сопоставлением по имени хоста в том же файле требований учитываются при выборе значения песочницы по умолчанию.

Установите appServer.mode: "guardian" для подтверждений Codex с проверкой guardian:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            mode: "guardian",            serviceTier: "priority",          },        },      },    },  },}

Предустановка guardian разворачивается в approvalPolicy: "on-request", approvalsReviewer: "auto_review" и sandbox: "workspace-write", когда эти значения разрешены. Отдельные поля политики переопределяют mode. Более старое значение проверяющего guardian_subagent по-прежнему принимается как псевдоним совместимости, но в новых конфигурациях следует использовать auto_review.

Когда активна песочница OpenClaw, локальный процесс Codex app-server все равно работает на хосте Gateway. Поэтому OpenClaw отключает нативный Code Mode Codex, пользовательские MCP-серверы и выполнение plugins на основе приложений для этого хода вместо того, чтобы считать хостовую песочницу Codex эквивалентной backend песочницы OpenClaw. Доступ к shell предоставляется через динамические инструменты OpenClaw на основе песочницы, такие как sandbox_exec и sandbox_process, когда обычные инструменты exec/process доступны.

На хостах Ubuntu/AppArmor Codex bwrap может завершаться ошибкой в workspace-write до запуска shell-команды, если вы намеренно запускаете нативный Codex workspace-write без активной песочницы OpenClaw. Если вы видите bwrap: setting up uid map: Permission denied или bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted, выполните openclaw doctor и исправьте указанную политику пространств имен хоста для сервисного пользователя OpenClaw, а не выдавайте более широкие привилегии контейнеру Docker. Предпочитайте ограниченный профиль AppArmor для сервисного процесса; fallback kernel.apparmor_restrict_unprivileged_userns=0 действует на весь хост и имеет компромиссы безопасности.

Нативное выполнение в песочнице

Стабильное значение по умолчанию — закрытие при ошибке: активная песочница OpenClaw отключает нативные поверхности выполнения Codex, которые иначе запускались бы с хоста Codex app-server. Используйте appServer.experimental.sandboxExecServer: true только когда хотите попробовать поддержку удаленной среды Codex с backend песочницы OpenClaw. Этот предварительный путь требует Codex app-server 0.132.0 или новее.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            experimental: {              sandboxExecServer: true,            },          },        },      },    },  },}

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

Этот предварительный путь работает только локально. Удаленный WebSocket app-server не может обратиться к loopback exec-server, если он не работает на том же хосте, поэтому OpenClaw отклоняет такое сочетание.

Изоляция аутентификации и среды

В домашнем каталоге для каждого агента по умолчанию аутентификация выбирается в таком порядке:

1. Явный профиль аутентификации OpenClaw Codex для агента.
2. Существующая учетная запись app-server в Codex home этого агента.
3. Только для локальных запусков stdio app-server: CODEX_API_KEY, затем OPENAI_API_KEY, когда учетная запись app-server отсутствует, а аутентификация OpenAI все еще требуется.

Когда OpenClaw видит профиль аутентификации Codex в стиле подписки ChatGPT, он удаляет CODEX_API_KEY и OPENAI_API_KEY из порожденного дочернего процесса Codex. Это сохраняет API-ключи уровня Gateway доступными для embeddings или прямых моделей OpenAI без случайного биллинга нативных ходов Codex app-server через API.

Явные профили API-ключей Codex и локальный stdio fallback по env-ключу используют вход в app-server вместо унаследованного env дочернего процесса. WebSocket-подключения app-server не получают fallback API-ключа env от Gateway; используйте явный профиль аутентификации или собственную учетную запись удаленного app-server.

Запуски stdio app-server по умолчанию наследуют среду процесса OpenClaw. OpenClaw владеет мостом учетной записи Codex app-server и устанавливает CODEX_HOME в каталог для каждого агента внутри состояния OpenClaw этого агента. Это удерживает конфигурацию Codex, учетные записи, кэш/данные plugins и состояние потоков в области агента OpenClaw, а не подтягивает их из личного home оператора ~/.codex.

Установите appServer.homeScope: "user", чтобы разделять нативное состояние Codex с Codex Desktop и CLI. Этот режим только для локального stdio использует $CODEX_HOME, если он задан, и ~/.codex в противном случае, включая нативную аутентификацию, конфигурацию, plugins и потоки. OpenClaw пропускает свой мост профиля аутентификации для app-server. Проверенные ходы владельца могут использовать codex_threads, чтобы перечислять, искать, читать, форкать, переименовывать, архивировать и восстанавливать эти потоки. Форкните поток перед продолжением его в OpenClaw; независимые процессы Codex не координируют конкурентных писателей для одного и того же потока.

OpenClaw не переписывает HOME для обычных локальных запусков app-server. Подпроцессы, запущенные Codex, такие как openclaw, gh, git, облачные CLI и shell-команды, видят обычный home процесса и могут находить конфигурацию и токены в пользовательском home. Codex также может обнаруживать $HOME/.agents/skills и $HOME/.agents/plugins/marketplace.json; это обнаружение .agents намеренно разделяется с home оператора и отделено от изолированного состояния ~/.codex.

В области агента по умолчанию OpenClaw plugins и снимки Skills OpenClaw по-прежнему проходят через собственный реестр plugins OpenClaw и загрузчик Skills; личные ресурсы Codex ~/.codex — нет. Если у вас есть полезные Skills или plugins Codex CLI из Codex home, которые должны стать частью изолированного агента OpenClaw, явно инвентаризируйте их:

openclaw migrate codex --dry-runopenclaw migrate apply codex --yes

Если развертыванию нужна дополнительная изоляция среды, добавьте эти переменные в appServer.clearEnv:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],          },        },      },    },  },}

appServer.clearEnv влияет только на порожденный дочерний процесс Codex app-server. OpenClaw удаляет CODEX_HOME и HOME из этого списка во время нормализации локального запуска: CODEX_HOME остается направленным на выбранную область агента или пользователя, а HOME остается унаследованным, чтобы подпроцессы могли использовать обычное состояние пользовательского home.

Динамические инструменты

Динамические инструменты Codex по умолчанию используют загрузку searchable. OpenClaw не предоставляет динамические инструменты, которые дублируют нативные операции Codex с рабочей областью:

• read
• write
• edit
• apply_patch
• exec
• process
• update_plan

Большинство оставшихся интеграционных инструментов OpenClaw, таких как обмен сообщениями, медиа, Cron, браузер, узлы, Gateway, heartbeat_respond и web_search, доступны через поиск инструментов Codex в пространстве имен openclaw. Это уменьшает начальный контекст модели. sessions_yield и ответы источника только для message-tool остаются прямыми, потому что это контракты управления ходом. sessions_spawn остается доступным для поиска, чтобы нативный spawn_agent Codex оставался основной поверхностью субагентов Codex, а явная делегация OpenClaw или ACP по-прежнему была доступна через пространство имен динамических инструментов openclaw.

Устанавливайте codexDynamicToolsLoading: "direct" только при подключении к пользовательскому Codex app-server, который не может искать отложенные динамические инструменты, или при отладке полной полезной нагрузки инструментов.

Тайм-ауты

Вызовы динамических инструментов, принадлежащих OpenClaw, ограничены независимо от appServer.requestTimeoutMs. Каждый запрос Codex item/tool/call использует первый доступный тайм-аут в таком порядке:

• Положительный аргумент timeoutMs для конкретного вызова.
• Для image_generate — agents.defaults.imageGenerationModel.timeoutMs.
• Для image_generate без настроенного тайм-аута — значение по умолчанию 120 секунд для генерации изображений.
• Для инструмента понимания медиа image — tools.media.image.timeoutSeconds, преобразованный в миллисекунды, или значение по умолчанию 60 секунд для медиа. Для понимания изображений это применяется к самому запросу и не уменьшается из-за более ранней подготовительной работы.
• Значение по умолчанию 90 секунд для динамического инструмента.

Этот watchdog является внешним бюджетом динамического item/tool/call. Специфичные для provider тайм-ауты запросов выполняются внутри этого вызова и сохраняют собственную семантику тайм-аутов. Бюджеты динамических инструментов ограничены 600000 мс. При тайм-ауте OpenClaw прерывает сигнал инструмента там, где это поддерживается, и возвращает Codex неуспешный ответ динамического инструмента, чтобы ход мог продолжиться, а не оставлять сеанс в processing.

После того как Codex принимает ход, и после того как OpenClaw отвечает на запрос app-server в области хода, harness ожидает, что Codex будет продвигать текущий ход и в итоге завершит нативный ход через turn/completed. Если app-server затихает на appServer.turnCompletionIdleTimeoutMs, OpenClaw по возможности прерывает ход Codex, записывает диагностический тайм-аут и освобождает линию сеанса OpenClaw, чтобы последующие сообщения чата не стояли в очереди за устаревшим нативным ходом.

Большинство нетерминальных уведомлений для того же хода снимают этот короткий сторожевой таймер с охраны, потому что Codex доказал, что ход все еще активен. Передачи инструментам используют более длинный бюджет простоя после инструмента: после того как OpenClaw возвращает ответ item/tool/call, после завершения нативных элементов инструментов, таких как commandExecution, после завершений сырых custom_tool_call_output, а также после сырого прогресса ассистента после инструмента, завершений сырого reasoning или прогресса reasoning. Защита использует appServer.postToolRawAssistantCompletionIdleTimeoutMs, если он настроен, а иначе по умолчанию использует пять минут. Тот же бюджет после инструмента также продлевает сторожевой таймер прогресса для безмолвного окна синтеза до того, как Codex выдаст следующее событие текущего хода. За завершениями reasoning, завершениями комментариев agentMessage и сырым прогрессом reasoning или ассистента до инструмента может последовать автоматический финальный ответ, поэтому они используют защиту ответа после прогресса вместо немедленного освобождения полосы сессии. Только финальные/некомментарийные завершенные элементы agentMessage и сырые завершения ассистента до инструмента ставят на охрану освобождение вывода ассистента: если после этого Codex замолкает без turn/completed, OpenClaw по возможности прерывает нативный ход и освобождает полосу сессии. Безопасные для повтора сбои stdio-сервера приложения, включая тайм-ауты простоя завершения хода без свидетельств ассистента, инструмента, активного элемента или побочных эффектов, повторяются один раз в новой попытке сервера приложения. Небезопасные тайм-ауты все равно выводят застрявший клиент сервера приложения из эксплуатации и освобождают полосу сессии OpenClaw. Они также очищают устаревшую привязку нативного потока вместо автоматического повтора. Тайм-ауты наблюдения за завершением показывают текст тайм-аута, специфичный для Codex: безопасные для повтора случаи говорят, что ответ может быть неполным, а небезопасные случаи просят пользователя проверить текущее состояние перед повторной попыткой. Публичная диагностика тайм-аутов включает структурные поля, такие как последний метод уведомления сервера приложения, id/type/role сырого элемента ответа ассистента, счетчики активных запросов/элементов и состояние поставленной на охрану проверки. Когда последнее уведомление является сырым элементом ответа ассистента, она также включает ограниченный предпросмотр текста ассистента. Она не включает сырое содержимое промптов или инструментов.

Обнаружение моделей

По умолчанию Plugin Codex запрашивает у сервера приложения доступные модели. Доступность моделей принадлежит серверу приложения Codex, поэтому список может измениться, когда OpenClaw обновляет встроенную версию @openai/codex или когда развертывание указывает appServer.command на другой бинарный файл Codex. Доступность также может зависеть от учетной записи. Используйте /codex models на запущенном Gateway, чтобы увидеть живой каталог для этого harness и учетной записи.

Если обнаружение завершается ошибкой или тайм-аутом, OpenClaw использует встроенный резервный каталог для:

• GPT-5.5
• GPT-5.4 mini

Текущий встроенный harness — @openai/codex 0.142.5. Проверка model/list на этом встроенном сервере приложения вернула следующие публичные строки средства выбора:

Скрытые модели могут возвращаться каталогом сервера приложения для внутренних или специализированных потоков, но они не являются обычными вариантами в средстве выбора модели.

Настройте обнаружение в plugins.entries.codex.config.discovery:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },        },      },    },  },}

Отключите обнаружение, когда нужно, чтобы запуск не проверял Codex и использовал только резервный каталог:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: false,          },        },      },    },  },}

Файлы начальной загрузки рабочей области

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

Для паритета рабочей области OpenClaw harness Codex разрешает остальные файлы начальной загрузки. SOUL.md, IDENTITY.md, TOOLS.md и USER.md передаются как инструкции разработчика OpenClaw Codex, потому что они определяют активного агента, доступные рекомендации рабочей области и профиль пользователя. Компактный список Skills OpenClaw передается как инструкции разработчика для совместной работы в области хода. Содержимое HEARTBEAT.md не внедряется; ходы Heartbeat получают указатель режима совместной работы на чтение файла, когда он существует и не пуст. Содержимое MEMORY.md из настроенной рабочей области агента не вставляется во вход нативного хода Codex, когда для этой рабочей области доступны инструменты памяти; когда он существует, harness добавляет небольшой указатель на память рабочей области в инструкции разработчика для совместной работы в области хода, а Codex должен использовать memory_search или memory_get, когда долговременная память релевантна. Если инструменты отключены, поиск по памяти недоступен или активная рабочая область отличается от рабочей области памяти агента, MEMORY.md использует обычный ограниченный путь контекста хода. BOOTSTRAP.md, когда присутствует, передается как справочный контекст входа хода OpenClaw.

Переопределения окружения

Переопределения окружения остаются доступными для локального тестирования:

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

OPENCLAW_CODEX_APP_SERVER_BIN обходит управляемый бинарный файл, когда appServer.command не задан.

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 был удален. Вместо этого используйте plugins.entries.codex.config.appServer.mode: "guardian" или OPENCLAW_CODEX_APP_SERVER_MODE=guardian для разового локального тестирования. Конфигурация предпочтительна для повторяемых развертываний, потому что она держит поведение Plugin в том же проверяемом файле, что и остальная настройка harness Codex.

См. также

• Harness Codex
• Среда выполнения harness Codex
• Нативные Plugin Codex
• Codex Computer Use
• Провайдер OpenAI
• Справочник конфигурации