Codex App-Server Runtime

Hermes는 선택적으로 openai/*와 openai-codex/* turn을 자체 tool loop 대신 Codex CLI app-server에 넘길 수 있습니다. 이 runtime을 켜면 terminal command, file edit, sandboxing, MCP tool call이 Codex runtime 안에서 실행됩니다. Hermes는 그 바깥 shell 역할을 맡습니다. 즉 sessions DB, slash commands, gateway, memory/skill review는 Hermes가 유지합니다.

이 기능은 opt-in only입니다. flag를 켜지 않으면 기본 Hermes 동작은 바뀌지 않습니다. Hermes가 사용자를 이 runtime으로 자동 route하는 일은 없습니다.

Why

• ChatGPT subscription으로 OpenAI agent turn을 실행할 수 있습니다. API key가 필요 없고 Codex CLI와 같은 auth flow를 사용합니다.
• Codex 자체 toolset과 sandbox를 사용합니다. terminal/read/write/search용 shell, structured edit용 apply_patch, planning용 update_plan이 seatbelt/landlock sandbox 안에서 실행됩니다.
• codex plugin으로 설치한 native Codex plugins(Linear, GitHub, Gmail, Calendar, Canva 등)이 자동 migration되어 Hermes session에서도 활성화됩니다.
• Hermes의 더 풍부한 tools도 함께 사용할 수 있습니다. web_search, web_extract, browser automation, vision, image generation, skills, TTS는 MCP callback을 통해 동작합니다. Codex에 built-in으로 없는 tool을 Hermes가 대신 제공합니다.
• Memory와 skill nudges도 계속 동작합니다. Codex event가 Hermes message shape로 projection되므로 self-improvement loop는 일반 transcript처럼 볼 수 있습니다.

What tools the model actually has

사용자가 가장 먼저 알고 싶어 하는 부분입니다. 이 runtime이 켜져 있으면 turn을 실행하는 model은 세 가지 독립 source에서 tool을 받습니다.

1. Codex's built-in toolset (always on)

이 tool들은 codex app-server 자체에 포함되어 있습니다. Hermes, MCP, plugin과 무관하며 runtime 시작 즉시 사용할 수 있습니다.

• shell - sandbox 안에서 arbitrary shell command를 실행합니다. file read(cat, head, tail), write(echo > foo, heredoc), search(find, rg, grep), directory navigation(ls, cd), build 실행, process 관리 등 bash에서 하는 대부분의 작업을 처리합니다.
• apply_patch - Codex patch format의 structured multi-file diff를 적용합니다. 함수 추가나 multi-file refactor 같은 non-trivial code edit에 사용됩니다. one-off write에는 shell heredoc도 계속 사용할 수 있습니다.
• update_plan - Codex internal todo/plan tracker입니다. Hermes의 todo tool에 해당하지만 Codex runtime 안에서 관리됩니다.
• view_image - local image file을 conversation에 load해 model이 볼 수 있게 합니다.
• web_search - configured 상태라면 Codex 자체 built-in web search를 사용할 수 있습니다. Hermes도 아래 callback을 통해 Firecrawl-backed web_search를 제공합니다. model은 상황에 맞게 선택합니다.

즉 terminal로 할 수 있는 read/write/search/find/run 작업은 Codex가 native로 처리합니다. writable scope는 sandbox profile로 제어됩니다. Hermes가 runtime을 enable할 때 기본값은 :workspace입니다.

2. Native Codex plugins (auto-migrated from your codex plugin install)

runtime을 enable하면 Hermes는 Codex의 plugin/list RPC를 조회하고, 설치된 각 plugin에 대해 [plugins."<name>@openai-curated"] entry를 ~/.codex/config.toml에 씁니다. plugin 자체의 관리와 authorization은 Codex가 맡으며, Codex UI에서 한 번 authorize합니다.

예시:

• Linear - issue 찾기/수정
• GitHub - code search, PR 보기, comment
• Gmail - mail 읽기/전송
• Google Calendar - event 생성/검색
• Outlook calendar/email - Microsoft connector를 통한 같은 형태의 작업
• Canva - design generation
• 기타 codex plugin marketplace add openai-curated와 codex plugin install ...로 설치한 plugin

자동 migration되지 않는 것:

• 아직 설치하지 않은 plugin. 먼저 Codex에서 설치해야 합니다.
• ChatGPT app marketplace entry(app/list). account auth 덕분에 이미 Codex 내부에서 enable되어 있습니다.

3. Hermes tool callback (MCP server, registered in ~/.codex/config.toml)

Hermes는 자기 자신을 MCP server로 등록해 Codex가 built-in으로 제공하지 않는 tool을 callback으로 호출할 수 있게 합니다. callback으로 사용할 수 있는 tool:

• web_search / web_extract - Firecrawl-backed. structured content를 얻을 때 일반 scraping보다 clean한 경우가 많습니다.
• browser_navigate / browser_click / browser_type / browser_press / browser_snapshot / browser_scroll / browser_back / browser_get_images / browser_console / browser_vision - Camofox 또는 Browserbase를 통한 full browser automation.
• vision_analyze - 별도의 vision model로 image를 inspect합니다. Codex view_image는 image를 conversation에 load하는 기능이고, 이 tool은 별도 model call입니다.
• image_generate - Hermes image_gen plugin chain을 통한 image generation.
• skill_view / skills_list - Hermes skill library에서 읽기.
• text_to_speech - Hermes에 설정된 provider를 통한 TTS.

model이 이들 중 하나를 호출하면 Codex는 stdio MCP로 hermes_tools_mcp_server subprocess를 spawn합니다. call은 model_tools.handle_function_call()로 dispatch됩니다. 이는 Hermes 기본 runtime과 같은 code path이며, result는 다른 MCP response처럼 Codex로 반환됩니다.

What's NOT available on this runtime

다음 네 Hermes tool은 실행 중인 AIAgent context, 즉 mid-loop state가 있어야 dispatch할 수 있습니다. stateless MCP callback으로는 구동할 수 없습니다. 이 tool이 필요하면 default runtime으로 돌아가세요(/codex-runtime auto).

• delegate_task - subagents spawn
• memory - Hermes persistent memory store
• session_search - cross-session search
• todo - Hermes todo store. Codex의 update_plan이 in-runtime equivalent입니다.

Workflow features (/goal, kanban, cron)

/goal (the Ralph loop)

이 runtime에서 동작합니다. goal은 session id를 key로 state_meta에 저장되고, continuation prompt는 run_conversation()을 통해 일반 user message처럼 다시 들어갑니다. 다음 turn은 Codex가 native로 실행합니다. goal judge는 active runtime과 독립적인 auxiliary client를 사용합니다(config.yaml의 auxiliary.goal_judge). Codex가 approval에서 멈췄을 때 judge의 "blocked, needs user input" verdict가 clean escape 역할을 합니다.

알아둘 점: 각 continuation prompt는 fresh Codex turn입니다. 따라서 Codex는 command approval policy를 매번 다시 평가합니다. write가 많은 long-running goal을 수행하면 single in-session task보다 approval prompt가 더 많이 나올 수 있습니다. Hermes가 runtime enable 시 자동으로 설정하는 default_permissions = ":workspace"를 사용하면 workspace 안의 단순 write는 prompt 없이 허용됩니다.

Kanban (multi-agent worktree dispatch)

이 runtime에서 동작하지만 작은 dependency가 있습니다. kanban dispatcher는 각 worker를 별도 hermes chat -q subprocess로 spawn하며, worker는 사용자의 config를 읽습니다. 따라서 model.openai_runtime: codex_app_server가 global로 설정되어 있으면 worker도 Codex runtime으로 올라옵니다.

Codex-runtime worker 안에서 동작하는 것:

• Codex full toolset(shell, apply_patch, update_plan, view_image, web_search). worker는 실제 task 작업을 native로 수행합니다.
• migrated Codex plugins(Linear, GitHub 등).
• browser_*, vision, image_gen, skills, TTS를 위한 Hermes tool callback.

MCP callback이 expose하기 때문에 추가로 동작하는 것:

• kanban_complete / kanban_block / kanban_comment / kanban_heartbeat - worker handoff tools. dispatcher가 설정한 HERMES_KANBAN_TASK env를 읽고 access를 gate하며 ~/.hermes/kanban.db에 기록합니다. callback에 이 tool들이 없으면 Codex runtime worker는 task 자체는 수행해도 보고를 못 해서 dispatcher timeout까지 걸릴 수 있습니다.
• kanban_show / kanban_list - worker가 자신의 context를 확인하기 위한 read-only board queries.
• kanban_create / kanban_unblock / kanban_link - 새 task dispatch가 필요한 orchestrator agent용 operations.

kanban tool은 dispatcher가 설정하는 HERMES_KANBAN_TASK env var로 gate됩니다. Codex subprocess가 env를 inherit하고, 거기서 spawn되는 hermes-tools MCP server subprocess에도 전달되므로 tool은 올바른 task id를 보고 gate할 수 있습니다.

Cron jobs

별도 집중 테스트는 아직 제한적입니다. cron job은 CLI와 같은 code path인 cronjob -> AIAgent.run_conversation으로 실행됩니다. cron job config에 openai_runtime: codex_app_server가 있으면 Codex에서 실행됩니다. tool availability rule도 같습니다. Codex built-ins + plugins + MCP callback은 동작하고, agent-loop tools(delegate_task, memory, session_search, todo)는 동작하지 않습니다. cron job이 이 tool에 의존한다면 default runtime을 사용하는 profile로 scope하세요.

Trade-offs

	Hermes default runtime	Codex app-server (opt-in)
delegate_task subagents	yes	not available - agent loop context 필요
memory, session_search, todo	yes	not available - agent loop context 필요
web_search, web_extract	yes	yes (via MCP callback)
Browser automation (Camofox/Browserbase)	yes	yes (via MCP callback)
vision_analyze, image_generate	yes	yes (via MCP callback)
skill_view, skills_list	yes	yes (via MCP callback)
text_to_speech	yes	yes (via MCP callback)
Codex shell (terminal/read/write/search/find/run)	no	yes (Codex built-in)
Codex apply_patch (structured multi-file edits)	no	yes (Codex built-in)
Codex update_plan (in-runtime todo)	no	yes (Codex built-in)
Codex view_image (load image into conversation)	no	yes (Codex built-in)
Codex sandbox (seatbelt/landlock, profiles)	no	yes (Codex built-in)
ChatGPT subscription auth	no	yes (via openai-codex provider)
Native Codex plugins (Linear, GitHub, etc.)	no	yes (auto-migrated)
User MCP servers	yes	yes (auto-migrated to Codex)
Memory + skill review (background)	yes	yes (via item projection)
Multi-turn conversations	yes	yes
/goal (Ralph loop)	yes	yes
Kanban worker dispatch	yes	yes (via callback)
Kanban orchestrator tools	yes	yes (via callback)
All gateway platforms	yes	yes
Non-OpenAI providers	yes	n/a - OpenAI/Codex-scoped

Prerequisites

1. Codex CLI installed:

   npm i -g @openai/codex
   codex --version   # 0.130.0 or newer

2. Codex OAuth login. Codex subprocess는 ~/.codex/auth.json을 읽습니다. token을 채우는 방법은 두 가지입니다.

   codex login                  # writes tokens to ~/.codex/auth.json

   Hermes의 hermes auth login codex는 ~/.hermes/auth.json에 씁니다. 이는 별도 session입니다. 아직 하지 않았다면 codex login을 따로 실행하세요.

3. (Optional) Install the Codex plugins you want. runtime을 enable할 때 Hermes는 Codex CLI에서 이미 설치해 둔 curated plugins를 자동 migration합니다.

   codex plugin marketplace add openai-curated
   # then via codex's TUI, install Linear / GitHub / Gmail / etc.

   Hermes가 이를 discover하고 [plugins."<name>@openai-curated"] entry를 ~/.codex/config.toml에 자동으로 씁니다.

Enabling

Hermes session 안에서:

/codex-runtime codex_app_server

이 command가 하는 일:

• codex CLI가 설치되어 있는지 확인합니다. 없으면 install hint와 함께 block합니다.
• model.openai_runtime: codex_app_server를 config.yaml에 persist합니다.
• user MCP servers를 ~/.hermes/config.yaml에서 ~/.codex/config.toml로 migration합니다.
• Codex의 plugin/list RPC를 조회해 installed native Codex plugins(Linear, GitHub, Gmail, Calendar, Canva 등)을 discover하고 migration합니다.
• Codex subprocess가 Codex에 없는 tool을 callback할 수 있도록 Hermes tools를 MCP server로 등록합니다.
• sandbox가 workspace 안 write를 매번 prompt 없이 허용하도록 **default_permissions = ":workspace"**를 씁니다.
• 무엇이 migration되었는지 알려 줍니다. 변경 사항은 다음 session부터 적용됩니다. 현재 cached agent는 이전 runtime을 유지해 prompt cache validity를 보존합니다.

동의어: /codex-runtime on, /codex-runtime off, /codex-runtime auto.

현재 상태만 확인하려면:

/codex-runtime

~/.hermes/config.yaml에 직접 설정할 수도 있습니다.

model:
  openai_runtime: codex_app_server   # default is "auto" (= Hermes runtime)

Self-improvement loop (memory + skill nudges)

Hermes background self-improvement는 counter threshold에서 실행됩니다.

• user prompt 10개마다 forked review agent가 conversation을 보고 memory에 저장할 내용이 있는지 판단합니다.
• single turn 안의 tool iteration 10개마다 같은 방식으로 skills를 검토합니다(skill_manage writes).

둘 다 Codex runtime에서 계속 동작합니다. Codex path는 완료된 commandExecution / fileChange / mcpToolCall / dynamicToolCall item을 synthetic assistant tool_call + tool result message로 projection합니다. review가 실행될 때는 default Hermes runtime과 같은 message shape를 보게 됩니다.

동등성을 유지하는 wiring:

	Default runtime	Codex runtime
_turns_since_memory increments	user prompt마다 run_conversation pre-loop에서 증가	같은 code path, early-return 전
_iters_since_skill increments	chat-completions loop의 tool iteration마다 증가	Codex turn 반환 후 turn.tool_iterations로 증가
Memory trigger (_turns_since_memory >= _memory_nudge_interval)	pre-loop에서 계산, response 후 실행	pre-loop에서 계산되어 Codex helper로 전달
Skill trigger (_iters_since_skill >= _skill_nudge_interval)	loop 이후 계산	Codex turn 이후 계산
_spawn_background_review(messages_snapshot=..., review_memory=..., review_skills=...)	trigger가 있으면 호출	trigger가 있으면 동일하게 호출

한 가지 detail이 있습니다. review fork 자체는 Hermes agent-loop tools(memory, skill_manage)를 호출해야 하므로 Hermes가 dispatch를 소유해야 합니다. 따라서 parent agent가 codex_app_server에 있더라도 review fork는 codex_responses로 downgrade됩니다. 같은 OAuth credential, 같은 openai-codex provider를 사용하지만 OpenAI Responses API에 직접 말하므로 Hermes가 loop를 소유하고 agent-loop tools가 동작합니다. 이 과정은 사용자에게 보이지 않습니다.

결과적으로 Codex runtime을 켜도 memory + skill nudges는 기존과 같은 방식으로 계속 실행됩니다.

How approvals work

Codex는 command 실행이나 patch 적용 전에 approval을 요청합니다. Hermes는 이를 표준 "Dangerous Command" prompt로 변환합니다.

Dangerous Command

/bin/bash -lc 'echo hello > foo.txt'

1. Allow once
2. Allow for this session
3. Deny

Codex requests exec in /your/cwd

• Allow once - 이 command 한 번만 approve합니다.
• Allow for this session - 유사 command에 대해 Codex가 다시 묻지 않습니다.
• Deny - command가 reject되고 Codex는 read-only mode로 계속합니다.

apply_patch file edit approval의 경우, Codex가 해당 fileChange item으로 data를 제공하면 Hermes는 변경 summary를 보여줍니다. 예: 1 add, 1 update: /tmp/new.py, /tmp/old.py.

Permission profiles

Codex에는 세 가지 built-in permission profile이 있습니다.

• :read-only - write 금지. 모든 shell command가 approval을 요구합니다.
• :workspace - 현재 workspace 안 write는 prompt 없이 허용됩니다. Hermes가 runtime enable 시 쓰는 기본값입니다.
• :danger-no-sandbox - sandbox가 전혀 없습니다. 의미를 정확히 이해하지 않는 한 사용하지 마세요.

Hermes managed block 바깥의 ~/.codex/config.toml에서 기본값을 override할 수 있습니다.

default_permissions = ":read-only"

override가 # managed by hermes-agent marker 바깥에 있으면 Hermes는 re-migration 때 이를 보존합니다.

Auxiliary tasks and ChatGPT subscription token cost

이 runtime이 openai-codex provider와 함께 켜져 있으면, auxiliary tasks(title generation, context compression, vision auto-detect, session search summarization, background self-improvement review fork)도 기본적으로 ChatGPT subscription을 통해 흐릅니다. per-task override가 없을 때 Hermes auxiliary client가 main provider/model을 사용하기 때문입니다.

이는 codex_app_server에만 해당하는 특성은 아닙니다. 기존 codex_responses path도 같습니다. 다만 subscription billing으로 opt in한다는 점이 여기서 더 분명하게 보일 뿐입니다.

특정 aux task를 더 저렴하거나 다른 model로 route하려면 ~/.hermes/config.yaml에 explicit override를 설정하세요.

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

self-improvement review fork는 _current_main_runtime()을 통해 main runtime을 inherit하고, Hermes는 이를 codex_app_server에서 codex_responses로 자동 downgrade합니다. 그래야 fork가 memory와 skill_manage 같은 Hermes agent-loop tool을 실제로 호출할 수 있습니다. aux task를 다른 곳으로 route하지 않았다면 이 fork도 subscription auth를 사용합니다.

Editing ~/.codex/config.toml safely

Hermes는 자신이 관리하는 내용을 두 marker comment 사이에 둡니다.

# 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

그 block 바깥은 사용자 영역입니다. migration을 다시 실행하면(/codex-runtime codex_app_server 또는 runtime on toggle) managed block만 in-place로 교체하고, 위아래의 user content는 그대로 보존합니다. 따라서 다음이 가능합니다.

• Hermes가 모르는 MCP server를 직접 추가
• prompt를 선호하면 default_permissions를 :read-only로 override
• Codex-only options(model, providers, otel 등) 구성
• [permissions.<name>] table에 user-defined permission profile 추가

managed block 안에 넣은 내용은 다음 migration 때 덮어써집니다. managed block 편집이 필요한 tweak가 있다면 issue를 열어 knob를 추가하는 편이 맞습니다.

Multi-profile / multi-tenant setups

기본적으로 Hermes는 어떤 Hermes profile이 active인지와 무관하게 Codex subprocess가 ~/.codex/를 보도록 합니다. 즉 hermes -p work와 hermes -p personal은 같은 Codex auth, plugins, config를 공유합니다. 대부분의 사용자는 이 동작이 맞습니다. Codex CLI를 직접 실행하는 것과 같은 boundary이기 때문입니다.

profile별 Codex isolation이 필요하면, 즉 auth, installed plugins, config를 분리하고 싶다면 profile마다 CODEX_HOME을 명시적으로 설정하세요. 가장 깔끔한 방법은 HERMES_HOME 아래 directory를 가리키는 것입니다.

# Inside the work profile, you might wrap hermes:
CODEX_HOME=~/.hermes/profiles/work/codex hermes chat

그 CODEX_HOME을 설정한 상태에서 codex login을 한 번 다시 실행해야 OAuth token이 profile-scoped location에 저장됩니다. 이후 hermes -p work는 isolated Codex state로 동작합니다.

Hermes가 이를 자동으로 scope하지 않는 이유는 기존 사용자의 ~/.codex/를 옮기면 Codex CLI auth를 조용히 무효화할 수 있기 때문입니다. 이미 codex login을 실행한 사용자는 다시 authenticate해야 합니다. 놀라운 자동 변경보다 opt-in이 안전합니다.

HOME environment variable passthrough

Hermes는 Codex app-server subprocess를 spawn할 때 HOME을 rewrite하지 않습니다. os.environ.copy()를 사용하고 CODEX_HOME과 RUST_LOG만 overlay합니다. 따라서:

• Codex가 shell tool로 실행하는 command는 실제 user HOME을 보고 ~/.gitconfig, ~/.gh/, ~/.aws/, ~/.npmrc 등을 정상적으로 찾습니다.
• Codex internal state는 CODEX_HOME을 통해 격리됩니다. 기본값은 ~/.codex/입니다.

이는 초기 실험 후 OpenClaw가 도달한 boundary와 같습니다. Codex state는 격리하고, user home은 그대로 둡니다(openclaw/openclaw#81562 참고).

MCP server migration

Hermes의 mcp_servers config는 Codex가 기대하는 TOML format으로 자동 변환됩니다. migration은 runtime을 enable할 때마다 실행되며 idempotent합니다. 다시 실행해도 managed section만 교체하고 user-edited Codex config는 보존합니다.

변환되는 항목:

Hermes (config.yaml)	Codex (config.toml)
command + args + env	stdio transport
url + headers	streamable_http transport
timeout	tool_timeout_sec
connect_timeout	startup_timeout_sec
enabled: false	enabled = false

변환되지 않는 항목:

• sampling 같은 Hermes-specific key. Codex MCP client에는 equivalent가 없으므로 per-server warning과 함께 drop됩니다.

Native Codex plugin migration

codex plugin으로 설치한 plugin(Linear, GitHub, Gmail, Calendar, Canva 등)은 Codex의 plugin/list RPC로 discovery됩니다. installed: true인 plugin마다 Hermes는 [plugins."<name>@openai-curated"] block을 써서 Hermes session에서 enable합니다.

즉 "내 Codex CLI에 Calendar와 GitHub를 설정해 뒀다"는 사용자가 Hermes Codex runtime을 켜면, Hermes가 이를 자동 활성화합니다. 재설정이 필요 없습니다.

자동 migration되지 않는 것:

• 아직 설치하지 않은 plugin. Codex에서 먼저 설치하세요.
• Codex가 availability != AVAILABLE로 보고하는 plugin. broken install, expired OAuth, marketplace에서 제거된 plugin 등은 activation 실패를 피하기 위해 skip됩니다.
• ChatGPT app marketplace entry. account-level app/list 결과는 account auth 덕분에 Codex 내부에서 이미 enable되어 있습니다.
• plugin OAuth. 각 plugin은 Codex 자체에서 한 번 authorize하며 Hermes는 credential을 건드리지 않습니다.

Hermes tool callback (the new MCP server)

Codex built-in toolset은 shell/file ops/patches를 다루지만 web search, browser automation, vision, image generation 등은 없습니다. Codex turn에서도 이 기능을 쓰기 위해 Hermes는 자신을 ~/.codex/config.toml의 MCP server로 등록합니다.

[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

model이 web_search 또는 다른 exposed Hermes tool을 호출하면 Codex는 stdio로 hermes_tools_mcp_server subprocess를 spawn합니다. request는 model_tools.handle_function_call()을 통해 dispatch되고 result는 일반 MCP response처럼 Codex로 projection됩니다.

Tools available via the callback: 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.

Tools NOT available: delegate_task, memory, session_search, todo. 이들은 running AIAgent context, 즉 mid-loop state가 있어야 dispatch할 수 있고 stateless MCP callback으로는 구동할 수 없습니다. 필요하면 default Hermes runtime(/codex-runtime auto)을 사용하세요.

Disabling

언제든 다시 전환할 수 있습니다.

/codex-runtime auto

다음 session부터 적용됩니다. Codex managed block은 ~/.codex/config.toml에 남아 있으므로 config를 잃지 않고 나중에 다시 enable할 수 있습니다. 원하면 직접 제거해도 됩니다.

Limitations

이 runtime은 opt-in beta입니다. Hermes Agent 2026.5 + Codex CLI 0.130.0 기준으로 동작 확인된 항목:

• Multi-turn conversations
• Hermes UI를 통한 commandExecution과 fileChange(apply_patch) approval
• MCP tool calls(@modelcontextprotocol/server-filesystem과 새 hermes-tools callback 기준)
• Native Codex plugin migration(Linear / GitHub / Calendar inventory 기준)
• Deny/cancel paths
• Toggle on/off cycle
• Memory and skill nudge counters(integration tests에서 live 검증)
• Codex를 통한 Hermes web_search(live 검증: "OpenAI Codex CLI - Getting Started"가 end-to-end로 반환)

Known limitations:

• Hermes auth와 Codex auth는 별도 session입니다. 가장 깔끔한 UX를 위해서는 codex login과 hermes auth login codex가 모두 필요합니다. runtime은 LLM call에 Codex session을 사용합니다. Hermes의 _import_codex_cli_tokens에서 의도적으로 이렇게 설계했습니다. Hermes와 Codex CLI가 token refresh 과정에서 서로 덮어쓰지 않게 하기 위해서입니다.
• delegate_task, memory, session_search, todo는 이 runtime에서 사용할 수 없습니다. running AIAgent context가 필요하고 stateless MCP callback으로 제공할 수 없습니다. 필요하면 /codex-runtime auto를 사용하세요.
• Codex가 changeset을 추적하지 않는 경우 approval prompt에서 inline patch preview가 없을 수 있습니다. Codex의 fileChange approval params가 항상 changeset을 포함하는 것은 아닙니다. Hermes는 가능한 경우 해당 item/started notification에서 data를 cache하지만, approval이 item stream보다 먼저 도착하면 Codex가 제공한 reason에 fallback합니다.
• Sub-second cancellation은 보장되지 않습니다. Codex가 응답 중일 때 Ctrl+C 같은 mid-stream interrupt는 turn/interrupt로 전송되지만, Codex가 이미 final message를 flush했다면 response를 받게 됩니다.

bug를 발견하면 hermes logs --since 5m output과 함께 issue를 열어 주세요. triage하기 쉽도록 title에 codex-runtime을 포함하세요.

Architecture

Hermes shell (CLI / TUI / gateway)
  - sessions DB, slash commands, memory & skill review
  - cron, session pickers, gateway routing
  |
  | user message
  v
AIAgent.run_conversation()
  if api_mode == codex_app_server:
      CodexAppServerSession
  else:
      chat_completions / codex_responses (default)
  |
  | JSON-RPC over stdio
  v
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
            |
            v
        hermes_tools_mcp_server.py subprocess
          web_search, web_extract, browser_*, vision_analyze,
          image_generate, skill_view, skills_list, text_to_speech
  |
  v
final text + projected messages back into Hermes

implementation detail은 PR #24182와 Codex app-server protocol README를 참고하세요.