Нативные плагины Codex

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

Используйте эту страницу после того, как базовая среда выполнения Codex заработает.

Требования

• Средой выполнения агента должна быть встроенная среда выполнения Codex.
• plugins.entries.codex.enabled имеет значение true.
• plugins.entries.codex.config.codexPlugins.enabled имеет значение true.
• Целевой app-server Codex должен видеть ожидаемый перечень маркетплейсов, плагинов и приложений.
• Миграция поддерживает только плагины openai-curated, которые были обнаружены как установленные из исходного кода в исходном домашнем каталоге Codex.
• Для настроенных вручную плагинов workspace-directory требуется app-server Codex, в котором plugin/list принимает marketplaceKinds, а сводки рабочих пространств без пути включают remotePluginId. Плагин уже должен быть установлен и включён, а принадлежащие ему приложения должны быть доступны в app/list.

codexPlugins не влияет на запуски через провайдер OpenClaw, привязки разговоров ACP или другие среды выполнения, поскольку эти пути никогда не создают потоки app-server Codex со встроенной конфигурацией apps.

Учётная запись Codex на стороне OpenAI, доступность приложений и настройки приложений и плагинов рабочего пространства определяются учётной записью Codex, в которую выполнен вход. Модель учётных записей и администрирования OpenAI описана в разделе Использование Codex с тарифным планом ChatGPT.

Быстрый старт

Предварительно просмотрите миграцию из исходного домашнего каталога Codex:

openclaw migrate codex --dry-run

Добавьте --verify-plugin-apps, чтобы при миграции вызывался исходный app/list, а перед планированием встроенной активации проверялось, что каждое принадлежащее плагину приложение присутствует, включено и доступно:

openclaw migrate codex --dry-run --verify-plugin-apps

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

openclaw migrate apply codex --yes

Миграция записывает явные элементы codexPlugins для подходящих плагинов и вызывает plugin/install app-server Codex для выбранных плагинов. Мигрированная конфигурация выглядит следующим образом:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_destructive_actions: true,            plugins: {              "google-calendar": {                enabled: true,                marketplaceName: "openai-curated",                pluginName: "google-calendar",              },            },          },        },      },    },  },}

Миграция по-прежнему ограничена openai-curated. Чтобы использовать существующий плагин workspace-directory, добавьте его вручную с точным идентификатором summary.id с указанием маркетплейса, возвращённым plugin/list. Например, если Codex возвращает example-plugin@workspace-directory, укажите это полное значение вместо отображаемого имени:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            plugins: {              "example-plugin": {                enabled: true,                marketplaceName: "workspace-directory",                pluginName: "example-plugin@workspace-directory",              },            },          },        },      },    },  },}

OpenClaw не вызывает plugin/install и не запускает аутентификацию для плагина workspace-directory. Установите и включите его, а также пройдите аутентификацию в Codex, прежде чем добавлять или включать политику OpenClaw. OpenClaw сохраняет приложения скрытыми, если в ответе отсутствуют точные сведения о маркетплейсе, идентификаторе плагина, идентификаторе подробностей или готовности приложения. Если Codex отклоняет явный запрос рабочего пространства plugin/list, OpenClaw сообщает marketplace_missing для каждого включённого плагина рабочего пространства и сохраняет доступность независимо обнаруженных курируемых плагинов.

После изменения codexPlugins новые разговоры Codex автоматически получают обновлённый набор приложений. Выполните /new или /reset, чтобы обновить текущий разговор. Для изменений включения или отключения плагинов перезапуск Gateway не требуется.

Управление плагинами из чата

/codex plugins проверяет или изменяет настроенные встроенные плагины Codex из того же чата, где вы работаете со средой выполнения Codex:

/codex plugins/codex plugins list/codex plugins disable google-calendar/codex plugins enable google-calendar

/codex plugins — псевдоним для /codex plugins list. В списке отображаются ключ каждого настроенного плагина, его состояние включения, имя плагина Codex и маркетплейс из plugins.entries.codex.config.codexPlugins.plugins.

enable/disable записывают данные только в ~/.openclaw/openclaw.json; они никогда не изменяют ~/.codex/config.toml и не устанавливают новые плагины Codex. Запускать их может только владелец или клиент Gateway с областью доступа operator.admin.

Включение настроенного плагина также активирует глобальный переключатель codexPlugins.enabled. Если курируемый плагин был записан отключённым, поскольку миграция вернула auth_required, повторно авторизуйте приложение в Codex, прежде чем включать его в OpenClaw. Для элемента workspace-directory включение здесь изменяет только политику OpenClaw; плагин и приложение уже должны быть активны в Codex.

Как работает настройка встроенных плагинов

Интеграция отслеживает три состояния:

Для плагинов openai-curated миграция является постоянным этапом установки и проверки соответствия требованиям:

• Во время планирования OpenClaw читает сведения исходного Codex plugin/read и проверяет, что учётная запись исходного app-server Codex является учётной записью с подпиской ChatGPT. Если учётная запись отсутствует или не относится к ChatGPT, плагины на базе приложений пропускаются с причиной codex_subscription_required.
• По умолчанию при миграции пропускается исходный вызов app/list: плагины исходного кода на базе приложений, прошедшие проверку учётной записи, планируются без проверки доступности исходных приложений, а при транспортных сбоях поиска учётной записи они пропускаются с причиной codex_account_unavailable.
• При использовании --verify-plugin-apps миграция получает новый снимок исходного app/list и требует, чтобы каждое принадлежащее плагину приложение присутствовало, было включено и доступно до планирования встроенной активации. В этом случае транспортные сбои поиска учётной записи приводят к переходу к проверке перечня исходных приложений, а не к немедленному пропуску.

Для плагинов workspace-directory настройка выполняется вне OpenClaw. OpenClaw запрашивает этот маркетплейс только при наличии хотя бы одного настроенного и включённого элемента рабочего пространства, разрешает каждый плагин по точному summary.id и повторно использует существующие проверки владения plugin/read и готовности app/list. Неустановленный, отключённый, недоступный плагин или плагин без пройденной аутентификации не предоставляет приложений; OpenClaw не пытается выполнить установку или аутентификацию.

Перечень приложений среды выполнения служит проверкой доступности целевого сеанса как для мигрированных курируемых плагинов, так и для настроенных вручную плагинов рабочего пространства. При настройке сеанса среды выполнения Codex вычисляется ограничительная конфигурация приложений потока на основе включённых и доступных приложений плагинов; она не вычисляется заново при каждом ходе, поэтому /codex plugins enable/disable влияют только на новые разговоры Codex. Используйте /new или /reset, чтобы применить изменение в текущем разговоре.

Границы поддержки V1

• Для миграции подходят только плагины openai-curated, уже установленные в перечне исходного app-server Codex.
• Среда выполнения также поддерживает явные элементы workspace-directory в сборках app-server, где plugin/list реализует marketplaceKinds и возвращает remotePluginId для сводок рабочих пространств без пути. Эти элементы должны использовать точный summary.id с указанием маркетплейса и уже быть установленными, включёнными и доступными для приложений. Отклонённый запрос списка рабочего пространства приводит к существующей диагностике marketplace_missing для каждого плагина; при отсутствии сведений о маркетплейсе, плагине, подробностях или приложении приложение рабочего пространства не предоставляется. Курируемый перечень из запроса списка по умолчанию остаётся доступным.
• Плагины исходного кода на базе приложений должны пройти проверку подписки во время миграции. --verify-plugin-apps добавляет проверку перечня исходных приложений. Учётные записи, не прошедшие проверку подписки, а в режиме проверки — недоступные, отключённые или отсутствующие исходные приложения и сбои обновления перечня приложений, отображаются как пропущенные элементы для ручной обработки, а не как включённые элементы конфигурации. Плагины с нечитаемыми сведениями пропускаются до проверки перечня приложений.
• Миграция записывает явные сущности плагинов (marketplaceName и pluginName); локальные пути кеша marketplacePath не записываются.
• codexPlugins.enabled — единственный глобальный переключатель включения; подстановочного знака или ключа конфигурации plugins["*"], который предоставляет произвольные полномочия на установку, не существует.
• Некурируемые маркетплейсы, кешированные пакеты плагинов, обработчики и файлы конфигурации Codex сохраняются в отчёте о миграции для ручной проверки, а не активируются автоматически. Среда выполнения принимает настроенные вручную элементы workspace-directory; другие маркетплейсы по-прежнему не поддерживаются.

Перечень приложений и владение

OpenClaw читает перечень приложений Codex через app/list app-server, кеширует его в памяти на один час и асинхронно обновляет устаревшие или отсутствующие элементы. Кеш действует только в рамках процесса; перезапуск CLI или Gateway очищает его, и OpenClaw создаёт его заново при следующем чтении app/list.

Миграция и среда выполнения используют разные ключи кеша:

• При проверке исходной миграции используются исходный домашний каталог Codex и параметры запуска. Она выполняется только с --verify-plugin-apps и принудительно запускает новый обход исходного app/list для этого сеанса планирования.
• При построении конфигурации приложений потока целевая среда выполнения использует сущность app-server Codex целевого агента. Активация курируемого плагина аннулирует соответствующий ключ целевого кеша, а затем принудительно обновляет его после plugin/install. При настройке workspace-directory этот путь активации никогда не выполняется.

Приложение плагина предоставляется только тогда, когда OpenClaw может сопоставить его с настроенным плагином посредством стабильного владения: точного идентификатора приложения из сведений о плагине, известного имени сервера MCP или уникальных стабильных метаданных. Владение, основанное только на отображаемом имени или неоднозначных данных, исключается до следующего обновления перечня, подтверждающего владение.

Приложения подключённой учётной записи

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

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_all_plugins: true,            allow_destructive_actions: "auto",          },        },      },    },  },}

allow_all_plugins: true получает полный снимок app/list при создании нового встроенного потока Codex и допускает только приложения, отмеченные как доступные этой учётной записи. Он не устанавливает приложения, не выполняет их аутентификацию и не включает их глобально. Существующие потоки сохраняют свой постоянный набор приложений; используйте /new, /reset или перезапустите Gateway, чтобы применить изменения, связанные с недавно подключёнными или отозванными приложениями.

Приложения учетной записи наследуют глобальное значение codexPlugins.allow_destructive_actions, которое принимает true, false, "auto" или "ask". Явная политика для отдельного плагина переопределяет глобальную политику для совпадающих идентификаторов приложений. При сбоях инвентаризации доступ блокируется вместо возврата к неограниченной политике по умолчанию.

Конфигурация приложений потока

OpenClaw внедряет ограничивающее исправление config.apps для потока Codex: _default отключен, а включены только приложения, принадлежащие включенным настроенным плагинам, или доступные приложения учетной записи, разрешенные политикой allow_all_plugins.

Значение destructive_enabled каждого приложения определяется эффективной глобальной политикой allow_destructive_actions или политикой отдельного плагина; true, "auto" и "ask" задают destructive_enabled: true, а false задает значение false. Codex по-прежнему применяет метаданные деструктивных инструментов из собственных аннотаций инструментов приложения. _default отключается с помощью open_world_enabled: false; приложения включенных плагинов получают open_world_enabled: true. OpenClaw не предоставляет отдельного параметра политики открытого мира на уровне плагина и не поддерживает отдельные для каждого плагина списки запрещенных имен деструктивных инструментов.

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

Политика деструктивных действий

Деструктивные запросы плагинов по умолчанию разрешены для настроенных плагинов Codex, тогда как небезопасные схемы и неоднозначное владение приводят к блокировке:

• Глобальное значение allow_destructive_actions по умолчанию равно true.
• Значение allow_destructive_actions отдельного плагина переопределяет глобальную политику для этого плагина.
• false: OpenClaw возвращает детерминированный отказ.
• true: OpenClaw автоматически принимает только безопасные схемы, которые может преобразовать в ответ об одобрении, например в логическое поле одобрения.
• "auto": OpenClaw предоставляет Codex доступ к деструктивным действиям плагинов, а затем преобразует запросы одобрения MCP с подтвержденным владением в одобрения плагинов OpenClaw перед возвратом ответа об одобрении Codex.
• "ask": OpenClaw использует тот же механизм контроля записи и деструктивных действий Codex, что и "auto", перед запуском потока удаляет постоянные переопределения одобрения Codex для отдельных инструментов приложения и предлагает только однократное одобрение или отказ, чтобы постоянные одобрения не могли подавлять последующие запросы для действий записи. Для каждого разрешенного приложения, использующего "ask", OpenClaw выбирает для него обработчик проверки одобрений человеком Codex, чтобы Codex отправлял свои запросы одобрения в OpenClaw; другие приложения и одобрения потока, не связанные с приложениями, сохраняют настроенные обработчик проверки и политику.
• При отсутствии идентификатора плагина, неоднозначном владении, отсутствии или несовпадении идентификатора хода либо небезопасной схеме запроса выполняется отказ без запроса пользователю.

Устранение неполадок

Плагин рабочего пространства установлен, но не отображается: убедитесь, что результат рабочего пространства plugin/list сообщает точный настроенный идентификатор как установленный и включенный, а затем убедитесь, что app/list сообщает о доступности каждого принадлежащего плагину приложения для той же учетной записи Codex. OpenClaw может включить доступное приложение для потока, даже если инвентаризация учетной записи в настоящий момент сообщает, что это приложение отключено. Если вы изменили это состояние после кеширования Gateway инвентаризации приложений, дождитесь обновления кеша через один час или перезапустите Gateway, а затем используйте /new или /reset. OpenClaw не восстанавливает и не аутентифицирует плагины рабочего пространства. Если явный запрос списка рабочего пространства отклонен, каждая включенная запись рабочего пространства сообщает marketplace_missing; обработка не связанных с ними курируемых записей продолжается на основе ответа со списком по умолчанию.

Для plugin_detail_unavailable сводка рабочего пространства без пути должна включать remotePluginId; OpenClaw сохраняет принадлежащие плагину приложения скрытыми, если этот селектор или последующий результат plugin/read недоступен. Для plugin_activation_failed курируемые плагины могут сообщать о сбое маркетплейса, аутентификации или обновления после установки. Плагин рабочего пространства сообщает этот код, если он еще не активен; установите, включите и аутентифицируйте его вне OpenClaw.

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

Деструктивное действие отклоняется: проверьте глобальное значение и значения отдельных плагинов allow_destructive_actions. Даже при true, "auto" или "ask" небезопасные схемы запросов и неоднозначная идентификация плагина по-прежнему приводят к блокировке.

См. также

• Среда выполнения Codex
• Справочник по среде выполнения Codex
• Среда исполнения среды выполнения Codex
• Справочник по конфигурации
• CLI миграции