🏠 Главная › user guide › codex app server runtime

Codex App-Server Runtime

Hermes может опционально передавать обработку запросов openai/* и openai-codex/* Codex CLI app-server вместо использования собственного цикла инструментов. При включении терминальные команды, редактирование файлов, песочница и вызовы MCP-инструментов выполняются внутри рантайма Codex — Hermes становится оболочкой вокруг него (база сессий, слеш-команды, шлюз, память и обзор навыков).

Это только опционально. Поведение Hermes по умолчанию не меняется, пока вы не включите флаг. Hermes никогда не перенаправляет вас на этот рантайм автоматически.

Зачем

Какие инструменты на самом деле есть у модели

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

1. Встроенный набор инструментов Codex (всегда включен)

Они поставляются с codex app-server — без участия Hermes, без MCP, без плагинов. Все пять доступны сразу после запуска рантайма:

Таким образом, всё, что вы делаете через терминал — чтение/запись/поиск/запуск — Codex делает нативно. Профиль песочницы (:workspace по умолчанию при включении рантайма) контролирует, что доступно для записи.

2. Нативные плагины Codex (автоматически переносятся из вашей установки codex plugin)

Когда вы включаете рантайм, Hermes запрашивает RPC plugin/list у Codex и записывает запись [plugins."<name>@openai-curated"] для каждого установленного плагина. Сами плагины управляются Codex и авторизуются один раз через собственный UI Codex.

Примеры (те, что в обсуждении OpenClaw были названы "достойными видео на YouTube"):

Что НЕ переносится: - Плагины, которые вы ещё не установили — сначала установите их в Codex. - Записи маркетплейса приложения ChatGPT (app/list) — они уже включены внутри Codex благодаря аутентификации вашей учётной записи.

3. Колбэк инструментов Hermes (MCP-сервер, зарегистрированный в ~/.codex/config.toml)

Hermes регистрирует себя как MCP-сервер, чтобы Codex мог вызывать инструменты, которых нет в поставке Codex. Доступны через колбэк:

Когда модель хочет использовать один из этих инструментов, Codex запускает подпроцесс hermes_tools_mcp_server через stdio MCP, вызов обрабатывается через model_tools.handle_function_call() (тот же путь кода, что и в рантайме Hermes по умолчанию), и результат возвращается в Codex как любой другой MCP-ответ.

Что НЕДОСТУПНО в этом рантайме

Эти четыре инструмента Hermes требуют контекста работающего AIAgent (состояние внутри цикла) для диспетчеризации, и статический MCP-колбэк не может их запустить. Переключитесь обратно на рантайм по умолчанию (/codex-runtime auto), когда они понадобятся:

Возможности рабочего процесса (/goal, канбан, cron)

/goal (цикл Ralph)

Работает в этом рантайме. Цели сохраняются в state_meta по идентификатору сессии, подсказка продолжения возвращается как обычное сообщение пользователя через run_conversation(), и Codex нативно выполняет следующий шаг. Судья целей работает через вспомогательный клиент (настраивается через auxiliary.goal_judge в config.yaml), независимо от активного рантайма. Вердикт судьи "заблокировано, требуется ввод пользователя" является чистым выходом, если Codex застрял на одобрениях.

Стоит учитывать: каждая подсказка продолжения — это новый шаг Codex, что означает, что Codex заново оценивает политику одобрения команд. Если вы выполняете долгосрочную цель с множеством записей, ожидайте больше запросов на одобрение, чем при одной задаче в сессии. Установите default_permissions = ":workspace" (Hermes делает это автоматически при включении рантайма), чтобы простые записи в рабочем пространстве не требовали подтверждения.

Канбан (многоагентная диспетчеризация worktree)

Работает в этом рантайме, с одной тонкой зависимостью. Диспетчер канбана запускает каждого рабочего как отдельный подпроцесс hermes chat -q, который читает конфигурацию пользователя — это означает, что если model.openai_runtime: codex_app_server установлен глобально, рабочие также запускаются на рантайме Codex.

Что работает внутри рабочего на рантайме Codex: - Полный набор инструментов Codex (shell, apply_patch, update_plan, view_image, web_search) — рабочий выполняет свою фактическую задачу нативно - Перенесённые плагины Codex — Linear, GitHub и т.д. - Колбэк инструментов Hermes для browser_*, vision, image_gen, skills, TTS

Что также работает, потому что MCP-колбэк их предоставляет: - kanban_complete / kanban_block / kanban_comment / kanban_heartbeat — инструменты передачи управления рабочим. Они читают HERMES_KANBAN_TASK из окружения (устанавливается диспетчером), правильно проверяют доступ и записывают в ~/.hermes/kanban.db. Без них в колбэке рабочий на этом рантайме мог бы выполнить задачу, но не смог бы сообщить о результате, зависнув до тайм-аута диспетчера. - kanban_show / kanban_list — запросы доски только для чтения, чтобы рабочий мог проверить свой контекст. - kanban_create / kanban_unblock / kanban_link — операции только для оркестратора. Доступны для агентов-оркестраторов, работающих на рантайме Codex, которым нужно диспетчеризировать новые задачи.

Инструменты канбана защищены переменной окружения HERMES_KANBAN_TASK, которую устанавливает диспетчер — эта переменная передаётся в подпроцесс Codex (Codex наследует окружение), а оттуда в запущенный подпроцесс MCP-сервера hermes-tools. Таким образом, инструменты видят правильный идентификатор задачи и правильно проверяют доступ.

Cron-задачи

Специально не тестировались. Cron-задачи запускаются через cronjob → AIAgent.run_conversation, тот же путь кода, что и CLI. Если в конфигурации cron-задачи установлено openai_runtime: codex_app_server, она будет выполняться на Codex. Применяются те же правила доступности инструментов — встроенные инструменты Codex + плагины + MCP-колбэк работают, инструменты цикла агента (delegate_task, memory, session_search, todo) — нет. Если ваша cron-задача полагается на них, ограничьте cron профилем, использующим рантайм по умолчанию.

Компромиссы

Рантайм Hermes по умолчанию Codex app-server (опционально)
Подагенты delegate_task да недоступно — требуется контекст цикла агента
memory, session_search, todo да недоступно — требуется контекст цикла агента
web_search, web_extract да да (через MCP-колбэк)
Автоматизация браузера (Camofox/Browserbase) да да (через MCP-колбэк)
vision_analyze, image_generate да да (через MCP-колбэк)
skill_view, skills_list да да (через MCP-колбэк)
text_to_speech да да (через MCP-колбэк)
shell Codex (терминал/чтение/запись/поиск/запуск) — да (встроенный в Codex)
apply_patch Codex (структурированные многофайловые правки) — да (встроенный в Codex)
update_plan Codex (todo внутри рантайма) — да (встроенный в Codex)
view_image Codex (загрузка изображения в разговор) — да (встроенный в Codex)
Песочница Codex (seatbelt/landlock, профили) — да (встроенная в Codex)
Аутентификация через подписку ChatGPT — да (через провайдер openai-codex)
Нативные плагины Codex (Linear, GitHub и т.д.) — да (автоматически переносятся)
Пользовательские MCP-серверы да да (автоматически переносятся в Codex)
Фоновый обзор памяти + навыков да да (через проекцию элементов)
Многошаговые разговоры да да
/goal (цикл Ralph) да да
Диспетчеризация рабочих канбана да да (через колбэк)
Инструменты оркестратора канбана да да (через колбэк)
Все платформы шлюза да да
Провайдеры, отличные от OpenAI да н/д — ограничено OpenAI/Codex

Предварительные требования

  1. Установлен Codex CLI: bash npm i -g @openai/codex codex --version # 0.130.0 или новее

  2. Вход в Codex по OAuth. Подпроцесс Codex читает ~/.codex/auth.json. Два выхода обойти его: bash codex login # записывает токены в ~/.codex/auth.json Собственный код входа в систему аутентификации Гермеса в Гермесе записывает в ~/.hermes/auth.json — это отдельная сессия. Запустите codex login отдельно, если ещё не сделали этого.

  3. (Необязательно) Установите нужные плагины Codex. Когда вы загрузите рантайм, Hermes автоматически перенесёт курируемые плагины, которые вы уже установили через интерфейс командной строки Codex: bash codex plugin marketplace add openai-curated # затем через TUI Codex установите Linear / GitHub / Gmail и т.д. Hermes подключит их и автоматически запишет записи [plugins."<name>@openai-curated"] в ~/.codex/config.toml.

Включение

В сессии Гермес:

/codex-runtime codex_app_server

Эта команда: - Проверяет, установлен ли CLI codex (блокирует с подсказкой по установке, если нет). - Сохраняет model.openai_runtime: codex_app_server в вашем config.yaml. - Переносит пользовательские MCP-серверы из ~/.hermes/config.yaml в ~/.codex/config.toml. - Обнаруживает и переносит установленные собственные плагины Codex (Linear, GitHub, Gmail, Calendar, Canva и т.д.), запрашивая RPC plugin/list в Codex. - Регистрирует собственные инструменты Hermes как MCP-сервер, чтобы выполнять обработку Codex мого инструментов, которых нет в поставке Codex. - Записывает default_permissions = ":workspace", чтобы песочница разрешила запись в рабочее пространство без запроса для каждой операции. - Сообщает, что было перенесено. Вступает в силу в следующей сессии — данный кэшированный агент сохраняет предыдущий рантайм, чтобы кэши подсказок оставались действительными.

Синонимы: /codex-runtime on, /codex-runtime off, /codex-runtime auto.

Чтобы проверить текущее состояние без изменений:

/codex-runtime

Вы также можете установить это вручную в ~/.hermes/config.yaml:

model:
  openai_runtime: codex_app_server   # по умолчанию "auto" (= рантайм Hermes)

Цикл самоулучшения (напоминания о памяти + навыках)

Фоновое самоулучшение Hermes реализовано по пороговым значениям счётчиков:

Оба продолжают работать на рантайме Кодекса. Путь Кодекс проецирует каждый завершённый элемент commandExecution / fileChange / mcpToolCall / dynamicToolCall в синтетическое сообщение assistanttool_call + результат tool, так что к моменту запуска обзора он видит ту же самую форму, что и на тайме Гермеса по умолчанию.

Как соединение эквивалентным:

Рантайм по умолчанию Рантайм Кодекс
_turns_since_memory увеличивается на каждую подсказку пользователя, в предварительном цикле run_conversation тот же путь кода, до раннего возврата
_iters_since_skill увеличивается инструмент для каждой итерации в цикле чат-завершений по turn.tool_iterations после возврата шага Кодекса
Триггер памяти (_turns_since_memory >= _memory_nudge_interval) происходит в предварительном цикле, с после выполнения ответа происходит в предварительном цикле, передаётся в хелпер Codex
Триггер навыка (_iters_since_skill >= _skill_nudge_interval) возвращается после цикла возвращается после шага Кодекса
_spawn_background_review(messages_snapshot=..., review_memory=..., review_skills=...) возникает при разработке любого триггера возникает идентично при разработке любого триггера

Одна деталь: сам разветвлённый обзор должен включать инструменты цикла агента Hermes («memory», «skill_manage»), которые требуют собственной диспетчеризации Hermes. Поэтому, когда родительский агент находится на codex_app_server, разветвлённый обзор понижается до codex_responses — те же учётные данные OAuth, тот же провайдер openai-codex, но общается напрямую с API ответов OpenAI, так что Hermes использует цикл, и инструменты обработки агента работают. Это незаметно для пользователя.

Итоговый эффект: включается рантайм Кодекса, и ваши воспоминания о памяти + навыки будут продолжать создавать точно так же, как иначе.

Как работают одобрения

Кодекс запрашивает рекомендации перед выполнением команд или применением обновлений. Они преобразуются в стандартное приглашение Hermes "Опасная команда":

╭───────────────────────────────────────╮
│ Опасная команда                       │
│                                       │
│ /bin/bash -lc 'echo hello > foo.txt'  │
│                                       │
│ ❯ 1. Разрешить один раз               │
│   2. Разрешить на эту сессию          │
│   3. Отклонить                        │
│                                       │
│ Codex запрашивает выполнение в /your/cwd │
╰───────────────────────────────────────╯

Для одобрения apply_patch (правка файла) Hermes показывает сводку изменений (1 добавление, 1 обновление: /tmp/new.py, /tmp/old.py), когда Кодекс предоставляет данные через соответствующий элемент fileChange.

Профили разрешений

В Кодексе есть три встроенных профиля: - :read-only — никаких записей; сертификат требует команды одобрения - :workspace — записи в текущем рабочем пространстве разрешены без запроса (по умолчанию в Гермесе при включении рантайма) - :danger-no-sandbox — вообще без песочницы (не викор, если не понимаете последствия)

Вы можете переопределить значение по умолчанию в ~/.codex/config.toml вне управляемого блока Hermes:

default_permissions = ":read-only"

(Гермес сохранит ваше переопределение при повторном переносе, если оно находится вне маркеров # под управлением агента Гермеса.)

Вспомогательные задачи и стоимость токенов подписки ChatGPT

Когда этот рантайм включен с провайдером openai-codex, ** вспомогательные задачи (генерация заголовков, сжатие контекста, автоопределение видения, обобщение поиска по сессиям, разветвленный обзор самоулучшения), а также по умолчанию передача через вашу подписку ChatGPT**, потому что вспомогательный клиент Hermes использует основного провайдера/модель, если не задано переопределение для конкретной задачи.

Это не специфично для codex_app_server — это верно и для Существующего пути codex_responses — но здесь это более заметно, потому что вы явно соглашаетесь на биллинговую подписку.

Чтобы редактировать последующие вспомогательные задачи на более дешёвую/другую модель, установите явные переопределения в ~/.hermes/config.yaml:

auxiliary:
  title_generation:
    provider: openrouter
    model: google/gemini-3-flash-preview
  context_compression:
    provider: openrouter
    model: google/gemini-3-flash-preview
  vision_detect:
    provider: openrouter
    model: google/gemini-3-flash-preview
  session_search:
    provider: openrouter
    model: google/gemini-3-flash-preview
  goal_judge:
    provider: openrouter
    model: google/gemini-3-flash-preview

Разветвленный обзор самоулучшения наследует основной рантайм через _current_main_runtime(), и Hermes автоматически понижает его с codex_app_server до codex_responses (чтобы разветвлённый обзор мог использовать memory и skill_manage — собственные инструменты агента цикла Hermes). Этот разветвлённый обзор ещё использует аутентификацию вашей подписки, если вы не перенаправили вспомогательные задачи в другое место.

Безопасное редактирование ~/.codex/config.toml

Гермес оборачивает всё, что командует, между двумя маркерными замечаниями:

# managed by hermes-agent — `hermes codex-runtime migrate` regenerates this section
default_permissions = ":workspace"
[mcp_servers.filesystem]...
[plugins."github@openai-curated"]...
# end hermes-agent managed section

Всё, что находится вне этого блока, принадлежит вам. Повторный запуск запуска (через /codex-runtime codex_app_server или при включении рантайма) заменяет управляемый блок на месте, но сохраняет пользовательский контент выше и ниже него без изменений. Это означает, что вы можете:

Всё, что вы добавите внутри управляемого блока, будет перезаписано при такой ситуации. Если вам нужна настройка, требующая редактирования управляемого блока, создайте проблему и добавим соответствующий рычаг.

Многопрофильные/мультитенантные настройки

По умолчанию Гермес направляет подпроцесс Кодекса на ~/.codex/ независимо от того, какой профиль Гермеса активирован. Это означает, что hermes -p work и hermes -p Personal используют одну и ту же аутентификацию Кодекса, плагины и конфигурацию. Для большинства пользователей это правильное поведение — оно соответствует тому, что делает прямой запуск CLI codex.

Если вы хотите изолировать Кодекс по профилям (отдельная аутентификация, установленные плагины, отдельные компоненты), установите CODEX_HOME явно для каждого профиля. Самый чистый способ — указать каталог внутри вашего HERMES_HOME:

# Внутри рабочего профиля вы можете обернуть hermes:
CODEX_HOME=~/.hermes/profiles/work/codex hermes chat

Вам нужно будет один раз запустить codex login с установленным CODEX_HOME, чтобы токены OAuth попали в место, соответствующее профилю. После этого hermes -p work будет работать с изолированным состоянием Кодекса.

Мы не делаем этого автоматически, потому что перемещение существующего ~/.codex/ пользователя молчанием аннулировалось его аутентификацией Codex CLI — любой, кто уже запустил codex login, должен был повторно аутентифицироваться. Опциональный подход кажется безопаснее, чем неожиданные сюрпризы для пользователей.

Передача переменного окружения HOME

Hermes НЕ перезаписывает HOME при запуске подпроцесса codex app-server (мы используем os.environ.copy() и накладываем только CODEX_HOME и RUST_LOG). Это означает:

Это соответствует границе, к которой пришёл OpenClaw после нескольких экспериментов: изолировать состояние Кодекса, оставить домашний каталог пользователя в каком-то месте. (См. openclaw/openclaw#81562.)

Перенос MCP-серверов

Конфигурация mcp_servers в Hermes автоматически переводится в формат TOML, ожидаемый Codex. Миграция запускается каждый раз при включении рантайма и является идемпотентной — повторные запуски заменяют управляемый раздел, но сохраняют все отредактированные пользовательские настройки Codex.

Что переводится:

Гермес (config.yaml) Кодекс (config.toml)
команда + args + env студия транспорта
url + заголовки потоковый_http транспорт
тайм-аут tool_timeout_sec
connect_timeout startup_timeout_sec
включено: ложь включено = ложь

Что не переносится: - Специальные для Гермеса ключи, такие как выборка (у MCP-клиента Codex нет эквивалента — они выбрасываются с предупреждением для каждого сервера).

Перенос нативных плагинов Codex

Плагины, установленные через «плагин кодекса» (Linear, GitHub, Gmail, Calendar, Canva и т.д.), обнаруживаются через RPC «плагин/список» Codex. Для каждого плагина, где installed: true, Hermes записывает блок [plugins."<name>@openai-curated"], включая его в вашу сессию Hermes.

Это означает: когда ваш друг говорит «У меня настроены Calendar и GitHub в моем Codex CLI» и включает рантайм Codex в Hermes, Hermes активирует их автоматически. Никакой перенастройки не требуется.

Что НЕ переводится: - Плагины, которые вы ещё не установили — сначала установите их в Кодексе. - Плагины, для которых Кодекс сообщает availability!= AVAILABLE (сломанная установка, истёкший OAuth, удален из маркетплейса и т.д.). Они предлагают не записывать конфигурацию, которая не сработает при активации. - Запись маркетплейса приложения ChatGPT (результаты app/list для каждой учётной записи — они уже включены внутри Кодекса благодаря аутентификации вашей учётной записи). - Плагины OAuth — вы исследуете каждый плагин один раз в самом Кодексе; Гермес не трогает учётные данные.

Колбэк-инструменты Hermes (новый MCP-сервер)

Встроенный набор инструментов Кодекса отвечает за операции с оболочками/файлами/патчами, но не включает веб-поиск, автоматизацию браузера, видение, генерацию изображений и т.д. Чтобы они выбрали доступными в шаге Кодекса, Hermes регистрирует себя как MCP-сервер в ~/.codex/config.toml:

[mcp_servers.hermes-tools]
command = "/path/to/python"
args = ["-m", "agent.transports.hermes_tools_mcp_server"]
env = { HERMES_HOME = "/your/.hermes", PYTHONPATH = "...", HERMES_QUIET = "1" }
startup_timeout_sec = 30.0
tool_timeout_sec = 600.0

Когда модель вызывает web_search (или другой предоставленный инструмент Hermes), Кодекс запускает подпроцесс hermes_tools_mcp_server через stdio, запрос обрабатывается через model_tools.handle_function_call(), и результат проецируется обратно в Кодекс как любой другой MCP-ответ.

Инструменты, доступные через колбэк: web_search, web_extract, browser_navigate, browser_click, browser_type, browser_press, browser_snapshot, browser_scroll, browser_back, browser_get_images, browser_console, «browser_vision», «vision_analyze», «image_generate», «skill_view», «skills_list», «text_to_speech».

Инструменты НЕ доступны: delegate_task, memory, session_search, todo. Для них требуется контекст работающего AIAgent (состояние внутри цикла), и статический MCP-колбэк не может их запустить. Используйте рантайм Hermes по умолчанию (/codex-runtime auto), когда они нужны.

Отключение

Переключитесь обратно в любое время:

/codex-runtime auto

Вступает в силу в следующую сессию. Управляемый блок Codex остается в ~/.codex/config.toml, так что вы можете повторно включить его позже без потери конфигурации или удалить вручную, если предпочитаете.

Ограничения

Этот рантайм является опциональной бета-версией. Работает на Hermes Agent 2026.5 + Codex CLI 0.130.0:

Известные ограничения:

Если вы обнаружили ошибку, откройте проблему с выводом hermes logs --since 5m. Упомяните codex-runtime в заголовке, чтобы было легко сортировать.

Архитектура

                ┌─── Оболочка Hermes (CLI / TUI / шлюз) ───┐
                │  БД сессий · слеш-команды · память      │
                │  и обзор навыков · cron · выбор сессий  │
                └──┬──────────────────────────────────────┬┘
                   │ user_message               final     │
                   ▼                            text +    │
        ┌──────────────────────────────────┐   projected  │
        │  AIAgent.run_conversation()       │   messages   │
        │   if api_mode == codex_app_server │              │
        │     → CodexAppServerSession       │              │
        │   else: chat_completions / codex_responses (default)
        └────┬─────────────────────────────┘              │
             │ JSON-RPC over stdio                        │
             ▼                                            │
        ┌──────────────────────────────────┐              │
        │  codex app-server (subprocess)    │──────────────┘
        │   thread/start, turn/start        │
        │   item/* notifications            │
        │   shell + apply_patch + update_plan│
        │   view_image + sandbox            │
        │   ┌─────────────────────────┐     │
        │   │  MCP client             │     │
        │   │  ├─ user MCP servers    │     │
        │   │  ├─ native plugins      │     │
        │   │  │   (linear, github,   │     │
        │   │  │    gmail, calendar,  │     │
        │   │  │    canva,...)       │     │
        │   │  └─ hermes-tools ───────┼─────────────────┐
        │   │       (callback to     │     │           │
        │   │        Hermes' richer  │     │           │
        │   │        tools)          │     │           │
        │   └─────────────────────────┘     │           │
        └──────────────────────────────────┘           │
                                                        │
                                                        ▼
        ┌──────────────────────────────────────────────────────────┐
        │  hermes_tools_mcp_server.py (subprocess on demand)        │
        │   web_search, web_extract, browser_*, vision_analyze,    │
        │   image_generate, skill_view, skills_list, text_to_speech│
        └──────────────────────────────────────────────────────────┘

Для реализации деталей см. PR #24182 и README протокола App-Server Codex.