codex. Для настройки и решений по маршрутизации начните с
обвязки Codex.
Поверхность конфигурации Plugin
Все настройки обвязки Codex находятся вplugins.entries.codex.config.
| Поле | По умолчанию | Значение |
|---|---|---|
discovery | включено | Настройки обнаружения моделей для model/list app-server Codex. |
appServer | управляемый app-server stdio | Настройки транспорта, команды, аутентификации, одобрения, песочницы и тайм-аутов. |
codexDynamicToolsLoading | "searchable" | Используйте "direct", чтобы помещать динамические инструменты OpenClaw непосредственно в начальный контекст инструментов Codex. |
codexDynamicToolsExclude | [] | Дополнительные имена динамических инструментов OpenClaw, которые нужно исключить из ходов app-server Codex. |
codexPlugins | отключено | Нативная поддержка Plugin/приложений Codex для перенесенных курируемых Plugin, установленных из исходного кода. См. нативные Plugin Codex. |
computerUse | отключено | Настройка Codex Computer Use. См. Codex Computer Use. |
Транспорт app-server
По умолчанию OpenClaw запускает управляемый бинарный файл Codex, поставляемый с комплектным Plugin:codex, а не к
какому-либо отдельному Codex CLI, который может быть установлен локально. Задавайте
appServer.command только когда намеренно хотите запустить другой
исполняемый файл.
Для уже запущенного app-server используйте транспорт WebSocket:
appServer:
| Поле | По умолчанию | Значение |
|---|---|---|
transport | "stdio" | "stdio" запускает Codex; "websocket" подключается к url. |
command | управляемый бинарный файл Codex | Исполняемый файл для stdio-транспорта. Оставьте незаданным, чтобы использовать управляемый бинарный файл. |
args | ["app-server", "--listen", "stdio://"] | Аргументы для stdio-транспорта. |
url | не задано | URL app-server WebSocket. |
authToken | не задано | Bearer-токен для WebSocket-транспорта. Принимает строковый литерал или SecretInput, например ${CODEX_APP_SERVER_TOKEN}. |
headers | {} | Дополнительные заголовки WebSocket. Значения заголовков принимают строковые литералы или значения SecretInput, например x-codex-client-session-token: "${CODEX_CLIENT_SESSION_TOKEN}". |
clearEnv | [] | Дополнительные имена переменных окружения, удаляемые из порожденного stdio-процесса app-server после того, как OpenClaw построит наследуемое окружение. |
remoteWorkspaceRoot | не задано | Корень удаленного рабочего пространства Codex app-server. Если задан, OpenClaw выводит локальный корень рабочего пространства из разрешенного рабочего пространства OpenClaw, сохраняет текущий суффикс cwd под этим удаленным корнем и отправляет в Codex только итоговый cwd app-server. Если cwd находится вне разрешенного корня рабочего пространства OpenClaw, OpenClaw отказывает безопасно, вместо того чтобы отправлять локальный для Gateway путь на удаленный app-server. |
requestTimeoutMs | 60000 | Тайм-аут для вызовов control plane app-server. |
turnCompletionIdleTimeoutMs | 60000 | Период тишины после того, как Codex принимает ход, или после запроса app-server в рамках хода, пока OpenClaw ожидает turn/completed. |
postToolRawAssistantCompletionIdleTimeoutMs | 300000 | Защита по простоям завершения и прогрессу, используемая после передачи инструменту, завершения нативного инструмента, прогресса raw assistant после инструмента, завершения raw reasoning или прогресса reasoning, пока OpenClaw ожидает turn/completed. Используйте это для доверенных или тяжелых рабочих нагрузок, где синтез после инструмента может законно молчать дольше, чем финальный бюджет выпуска assistant. |
mode | "yolo", если локальные требования Codex не запрещают YOLO | Предустановка для YOLO или выполнения с проверкой guardian. |
approvalPolicy | "never" или разрешенная политика подтверждений guardian | Нативная политика подтверждений Codex, отправляемая при запуске потока, возобновлении и ходе. |
sandbox | "danger-full-access" или разрешенная песочница guardian | Нативный режим песочницы Codex, отправляемый при запуске и возобновлении потока. Активные песочницы OpenClaw сужают ходы danger-full-access до Codex workspace-write; флаг сети хода следует исходящему трафику песочницы OpenClaw. |
approvalsReviewer | "user" или разрешенный рецензент guardian | Используйте "auto_review", чтобы Codex проверял нативные запросы подтверждения, когда это разрешено. |
defaultWorkspaceDir | каталог текущего процесса | Рабочее пространство, используемое /codex bind, когда --cwd опущен. |
serviceTier | не задано | Необязательный уровень обслуживания Codex app-server. "priority" включает маршрутизацию fast-mode, "flex" запрашивает flex-обработку, а null очищает переопределение. Устаревшее "fast" принимается как "priority". |
networkProxy | отключено | Включает сетевое взаимодействие профиля разрешений Codex для команд app-server. OpenClaw определяет выбранную конфигурацию permissions.<profile>.network и выбирает ее через default_permissions, вместо того чтобы отправлять sandbox. |
experimental.sandboxExecServer | false | Предварительная опция, которая регистрирует поддерживаемое песочницей OpenClaw окружение Codex в Codex app-server 0.132.0 или новее, чтобы нативное выполнение Codex могло работать внутри активной песочницы OpenClaw. |
appServer.networkProxy задается явно, потому что он меняет контракт песочницы
Codex. Когда он включен, OpenClaw также задает features.network_proxy.enabled и
default_permissions в конфигурации потока Codex, чтобы сгенерированный профиль
разрешений мог запускать управляемое Codex сетевое взаимодействие. По умолчанию
OpenClaw генерирует устойчивое к коллизиям имя профиля
openclaw-network-<fingerprint> из тела профиля; используйте profileName
только когда требуется стабильное локальное имя.
danger-full-access, включение
networkProxy использует доступ к файловой системе в стиле workspace для
сгенерированного профиля разрешений. Управляемое Codex сетевое принудительное
применение является сетевым взаимодействием в песочнице, поэтому профиль с полным
доступом не защищал бы исходящий трафик.
Plugin блокирует более старые или неверсионированные рукопожатия app-server.
Codex app-server должен сообщать стабильную версию 0.125.0 или новее.
OpenClaw считает URL WebSocket-сервера приложений, не относящиеся к loopback, удаленными и требует
WebSocket-аутентификацию с идентификацией через appServer.authToken или
заголовок Authorization. appServer.authToken и каждое значение appServer.headers.*
могут быть SecretInput; среда выполнения секретов разрешает SecretRefs и сокращения
для переменных окружения до того, как OpenClaw формирует параметры запуска сервера приложений, а неразрешенные
структурированные SecretRefs завершаются ошибкой до отправки любого токена или заголовка. Когда настроены нативные
Plugin Codex, OpenClaw использует плоскость управления Plugin подключенного сервера приложений,
чтобы установить или обновить эти Plugin, а затем обновляет инвентарь приложений, чтобы
приложения, принадлежащие Plugin, были видны потоку Codex. app/list по-прежнему является
авторитетным источником инвентаря и метаданных, но политика OpenClaw решает, будет ли
thread/start отправлять config.apps[appId].enabled = true для указанного доступного
приложения, даже если Codex сейчас помечает его как отключенное. Неизвестные или отсутствующие идентификаторы приложений
остаются закрытыми при отказе; этот путь активирует только Plugin из маркетплейса через plugin/install
и обновляет инвентарь. Подключайте OpenClaw только к тем удаленным серверам приложений, которым
доверено принимать управляемые OpenClaw установки Plugin и обновления инвентаря приложений.
Режимы подтверждения и песочницы
Локальные stdio-сеансы сервера приложений по умолчанию используют режим YOLO:approvalPolicy: "never", approvalsReviewer: "user" и
sandbox: "danger-full-access". Такая доверенная локальная операторская позиция позволяет
автономным ходам OpenClaw и Heartbeat продолжать работу без нативных запросов подтверждения,
на которые некому ответить.
Если локальный файл системных требований Codex запрещает неявные значения YOLO для подтверждения,
рецензента или песочницы, OpenClaw вместо этого считает неявное значение по умолчанию guardian
и выбирает разрешенные права guardian. tools.exec.mode: "auto"
также принудительно включает проверяемые guardian подтверждения Codex и не сохраняет небезопасные
устаревшие переопределения approvalPolicy: "never" или sandbox: "danger-full-access";
задайте tools.exec.mode: "full" для намеренной позиции без подтверждений.
Записи
[[remote_sandbox_config]] в том же файле требований, совпадающие по имени хоста, учитываются
при выборе значения песочницы по умолчанию.
Задайте appServer.mode: "guardian" для подтверждений Codex с проверкой guardian:
guardian разворачивается в approvalPolicy: "on-request",
approvalsReviewer: "auto_review" и sandbox: "workspace-write", когда эти
значения разрешены. Отдельные поля политики переопределяют mode. Более старое
значение рецензента guardian_subagent по-прежнему принимается как совместимый псевдоним,
но в новых конфигурациях следует использовать auto_review.
Когда песочница OpenClaw активна, локальный процесс сервера приложений Codex все равно
работает на хосте Gateway. Поэтому OpenClaw отключает нативный режим Code Mode Codex,
пользовательские MCP-серверы и выполнение Plugin на базе приложений для этого хода, вместо того чтобы
считать песочницу на стороне хоста Codex эквивалентной бэкенду песочницы OpenClaw.
Доступ к оболочке предоставляется через динамические инструменты на базе песочницы OpenClaw,
такие как sandbox_exec и sandbox_process, когда доступны обычные инструменты exec/process.
На хостах Ubuntu/AppArmor bwrap в Codex может завершиться ошибкой в workspace-write до
запуска команды оболочки, если вы намеренно запускаете нативный Codex
workspace-write без активной песочницы OpenClaw. Если вы видите
bwrap: setting up uid map: Permission denied или
bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted, выполните
openclaw doctor и исправьте указанную политику пространств имен хоста для пользователя сервиса OpenClaw,
а не выдавайте более широкие привилегии Docker-контейнеру. Предпочитайте
ограниченный профиль AppArmor для сервисного процесса; запасной вариант
kernel.apparmor_restrict_unprivileged_userns=0 действует на весь хост и имеет
компромиссы по безопасности.
Нативное выполнение в песочнице
Стабильное значение по умолчанию закрывает отказ: активная песочница OpenClaw отключает нативные поверхности выполнения Codex, которые иначе запускались бы с хоста сервера приложений Codex. ИспользуйтеappServer.experimental.sandboxExecServer: true только когда хотите
попробовать поддержку удаленной среды Codex с бэкендом песочницы OpenClaw. Для этого
предварительного пути требуется сервер приложений Codex версии 0.132.0 или новее.
Аутентификация и изоляция окружения
Аутентификация выбирается в следующем порядке:- Явный профиль аутентификации OpenClaw Codex для агента.
- Существующая учетная запись сервера приложений в домашнем каталоге Codex этого агента.
- Только для локальных запусков stdio-сервера приложений:
CODEX_API_KEY, затемOPENAI_API_KEY, когда учетная запись сервера приложений отсутствует, а аутентификация OpenAI все еще требуется.
CODEX_API_KEY и OPENAI_API_KEY из порожденного дочернего процесса Codex. Это
оставляет API-ключи уровня Gateway доступными для embeddings или прямых моделей OpenAI,
не позволяя нативным ходам сервера приложений Codex случайно оплачиваться через API.
Явные профили API-ключей Codex и локальный запасной вариант env-key для stdio используют вход в сервер приложений
вместо унаследованного окружения дочернего процесса. WebSocket-подключения сервера приложений
не получают запасной API-ключ из окружения Gateway; используйте явный профиль аутентификации или
собственную учетную запись удаленного сервера приложений.
Запуски stdio-сервера приложений по умолчанию наследуют окружение процесса OpenClaw.
OpenClaw владеет мостом учетной записи сервера приложений Codex и задает CODEX_HOME как
каталог отдельного агента внутри состояния OpenClaw этого агента. Это удерживает конфигурацию Codex,
учетные записи, кэш/данные Plugin и состояние потока в области OpenClaw-агента
вместо утечки из личного домашнего каталога оператора ~/.codex.
OpenClaw не переписывает HOME для обычных локальных запусков сервера приложений. Подпроцессы,
запущенные Codex, такие как openclaw, gh, git, облачные CLI и команды оболочки, видят
обычный домашний каталог процесса и могут находить конфигурацию и токены из домашнего каталога пользователя. Codex также может
обнаруживать $HOME/.agents/skills и $HOME/.agents/plugins/marketplace.json;
это обнаружение .agents намеренно совместно используется с домашним каталогом оператора и
отделено от изолированного состояния ~/.codex.
Plugin OpenClaw и снимки Skills OpenClaw по-прежнему проходят через собственный
реестр Plugin и загрузчик Skills OpenClaw. Личные ресурсы Codex ~/.codex не проходят. Если
у вас есть полезные Skills или Plugin Codex CLI из домашнего каталога Codex, которые должны стать
частью агента OpenClaw, явно инвентаризируйте их:
appServer.clearEnv:
appServer.clearEnv влияет только на порожденный дочерний процесс сервера приложений Codex.
OpenClaw удаляет CODEX_HOME и HOME из этого списка при нормализации локального запуска:
CODEX_HOME остается отдельным для агента, а HOME остается унаследованным, чтобы
подпроцессы могли использовать обычное состояние домашнего каталога пользователя.
Динамические инструменты
Динамические инструменты Codex по умолчанию используют загрузкуsearchable. OpenClaw не предоставляет
динамические инструменты, дублирующие нативные операции рабочего пространства Codex:
readwriteeditapply_patchexecprocessupdate_plan
heartbeat_respond и web_search, доступны
через поиск инструментов Codex в пространстве имен openclaw. Это уменьшает начальный
контекст модели. sessions_yield и ответы источника только для инструментов сообщений
остаются прямыми, потому что это контракты управления ходом. sessions_spawn остается
доступным для поиска, чтобы нативный spawn_agent Codex оставался основной поверхностью
субагентов Codex, при этом явная делегация OpenClaw или ACP по-прежнему доступна через
пространство имен динамических инструментов openclaw.
Задавайте codexDynamicToolsLoading: "direct" только при подключении к пользовательскому серверу приложений Codex,
который не может искать отложенные динамические инструменты, или при отладке полной
полезной нагрузки инструментов.
Тайм-ауты
Вызовы динамических инструментов, принадлежащие OpenClaw, ограничены независимо отappServer.requestTimeoutMs. Каждый запрос Codex item/tool/call использует первый
доступный тайм-аут в следующем порядке:
- Положительный аргумент
timeoutMsдля конкретного вызова. - Для
image_generate:agents.defaults.imageGenerationModel.timeoutMs. - Для
image_generateбез настроенного тайм-аута: значение по умолчанию для генерации изображений 120 секунд. - Для инструмента понимания медиа
image:tools.media.image.timeoutSeconds, преобразованное в миллисекунды, или значение по умолчанию для медиа 60 секунд. Для понимания изображений это применяется к самому запросу и не уменьшается из-за ранее выполненной подготовительной работы. - Значение по умолчанию для динамических инструментов 90 секунд.
item/tool/call. Тайм-ауты запросов,
специфичные для провайдера, выполняются внутри этого вызова и сохраняют собственную семантику тайм-аутов.
Бюджеты динамических инструментов ограничены 600000 мс. При тайм-ауте OpenClaw прерывает
сигнал инструмента там, где это поддерживается, и возвращает Codex ответ динамического инструмента с ошибкой,
чтобы ход мог продолжиться, вместо того чтобы оставлять сеанс в состоянии processing.
После того как Codex принимает ход, и после того как OpenClaw отвечает на запрос сервера приложений
в области хода, обвязка ожидает, что Codex будет продвигаться в текущем ходе и
в итоге завершит нативный ход с turn/completed. Если сервер приложений молчит
в течение appServer.turnCompletionIdleTimeoutMs, OpenClaw по мере возможности
прерывает ход Codex, записывает диагностический тайм-аут и освобождает
полосу сеанса OpenClaw, чтобы последующие сообщения чата не ожидали в очереди за устаревшим
нативным ходом.
Большинство нетерминальных уведомлений для того же хода отключают этот короткий сторожевой таймер,
потому что Codex доказал, что ход все еще активен. Передачи инструментам используют более длинный
бюджет простоя после инструмента: после того как OpenClaw возвращает ответ item/tool/call, после
завершения нативных элементов инструментов, таких как commandExecution, после завершений raw
custom_tool_call_output, а также после raw-прогресса ассистента после инструмента,
завершений raw-рассуждений или прогресса рассуждений. Защита использует
appServer.postToolRawAssistantCompletionIdleTimeoutMs, если он настроен, и
иначе по умолчанию устанавливает пять минут. Тот же бюджет после инструмента также продлевает
сторожевой таймер прогресса для тихого окна синтеза до того, как Codex выдаст следующее
событие текущего хода. Завершения рассуждений, завершения
agentMessage в commentary и raw-прогресс рассуждений или ассистента до инструмента могут
сопровождаться автоматическим финальным ответом, поэтому они используют защиту ответа после прогресса
вместо немедленного освобождения полосы сессии. Только
финальные/не-commentary завершенные элементы agentMessage и raw-завершения ассистента до инструмента
включают освобождение вывода ассистента: если после этого Codex замолкает без
turn/completed, OpenClaw по мере возможности прерывает нативный ход и освобождает
полосу сессии. Отказоустойчивые для повторного воспроизведения сбои stdio app-server, включая
тайм-ауты простоя завершения хода без свидетельств ассистента, инструмента, активного элемента или
побочных эффектов, повторяются один раз в новой попытке app-server. Небезопасные
тайм-ауты все равно выводят зависший клиент app-server из обращения и освобождают полосу
сессии OpenClaw. Они также очищают устаревшую привязку нативного потока вместо
автоматического повторного воспроизведения. Тайм-ауты наблюдения за завершением показывают
специфичный для Codex текст тайм-аута: отказоустойчивые для повторного воспроизведения случаи говорят,
что ответ может быть неполным, а небезопасные случаи говорят пользователю проверить текущее состояние
перед повторной попыткой. Публичная диагностика тайм-аутов включает структурные поля, такие как
последний метод уведомления app-server, id/type/role raw-элемента ответа ассистента,
счетчики активных запросов/элементов и состояние включенного наблюдения. Когда последним уведомлением
является raw-элемент ответа ассистента, она также включает ограниченный предварительный просмотр текста
ассистента. Она не включает raw-промпт или содержимое инструмента.
Обнаружение моделей
По умолчанию Plugin Codex запрашивает у app-server доступные модели. Доступность моделей принадлежит Codex app-server, поэтому список может измениться, когда OpenClaw обновляет встроенную версию@openai/codex или когда развертывание указывает
appServer.command на другой бинарный файл Codex. Доступность также может быть
привязана к аккаунту. Используйте /codex models на работающем gateway, чтобы увидеть живой каталог
для этого harness и аккаунта.
Если обнаружение завершается ошибкой или тайм-аутом, OpenClaw использует встроенный резервный каталог для:
- GPT-5.5
- GPT-5.4 mini
- GPT-5.2
@openai/codex 0.139.0. Проба model/list
к этому встроенному app-server вернула:
| Идентификатор модели | По умолчанию | Скрытая | Модальности ввода | Усилия рассуждения |
|---|---|---|---|---|
gpt-5.5 | Да | Нет | текст, изображение | low, medium, high, xhigh |
gpt-5.4 | Нет | Нет | текст, изображение | low, medium, high, xhigh |
gpt-5.4-mini | Нет | Нет | текст, изображение | low, medium, high, xhigh |
gpt-5.3-codex | Нет | Нет | текст, изображение | low, medium, high, xhigh |
gpt-5.2 | Нет | Нет | текст, изображение | low, medium, high, xhigh |
plugins.entries.codex.config.discovery:
Файлы начальной загрузки рабочей области
Codex самостоятельно обрабатываетAGENTS.md через нативное обнаружение документации проекта. OpenClaw
не записывает синтетические файлы документации проекта Codex и не зависит от резервных
имен файлов Codex для файлов persona, потому что резервные варианты Codex применяются только когда
AGENTS.md отсутствует.
Для паритета рабочей области OpenClaw harness Codex разрешает остальные файлы начальной загрузки.
SOUL.md, IDENTITY.md, TOOLS.md и USER.md передаются как
инструкции разработчика OpenClaw Codex, потому что они определяют активного агента,
доступные указания рабочей области и профиль пользователя. Компактный список OpenClaw skills
передается как ограниченные ходом инструкции разработчика для совместной работы.
Содержимое HEARTBEAT.md не внедряется; ходы heartbeat получают указатель режима совместной работы
прочитать файл, когда он существует и не пуст. Содержимое MEMORY.md
из настроенной рабочей области агента не вставляется во входные данные нативного хода Codex,
когда для этой рабочей области доступны инструменты памяти; когда он существует, harness
добавляет небольшой указатель workspace-memory в ограниченные ходом инструкции разработчика
для совместной работы, и Codex должен использовать memory_search или memory_get, когда долговременная
память релевантна. Если инструменты отключены, поиск в памяти недоступен или
активная рабочая область отличается от рабочей области памяти агента, MEMORY.md использует
обычный ограниченный путь контекста хода.
BOOTSTRAP.md, если он присутствует, передается как справочный контекст входных данных хода OpenClaw.
Переопределения окружения
Переопределения окружения остаются доступными для локального тестирования:OPENCLAW_CODEX_APP_SERVER_BINOPENCLAW_CODEX_APP_SERVER_ARGSOPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardianOPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICYOPENCLAW_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.