Runtime do Codex App-Server

O Hermes pode, opcionalmente, entregar os turnos de openai/* e openai-codex/* para o app-server da CLI do Codex em vez de rodar o próprio laço de ferramentas. Com isso ligado, comandos de terminal, edições de arquivo, sandbox e chamadas de ferramenta MCP executam todos dentro do runtime do Codex — o Hermes vira a casca em volta dele (banco de sessões, comandos de barra, gateway, memória e revisão de skills).

Isso é opt-in. O comportamento padrão do Hermes não muda a menos que você vire a chave. O Hermes nunca te coloca nesse runtime automaticamente.

dica

Não usa o OpenAI Codex? O hermes setup --portal configura um backend sem Codex, com Claude/Gemini e afins, em um passo só. Veja Nous Portal.

Por quê

• Rode turnos de agente da OpenAI usando a sua assinatura do ChatGPT (sem precisar de chave de API), com o mesmo fluxo de autenticação da CLI do Codex.
• Use o conjunto de ferramentas e o sandbox do próprio Codex — shell para terminal, leitura, escrita e busca; apply_patch para edições estruturadas; update_plan para planejamento; tudo rodando dentro do sandbox seatbelt/landlock.
• Plugins nativos do Codex — Linear, GitHub, Gmail, Calendar, Canva etc. — instalados via codex plugin são migrados automaticamente e ficam ativos na sua sessão do Hermes.
• As ferramentas mais ricas do Hermes vêm junto — web_search, web_extract, automação de navegador, visão, geração de imagem, skills e TTS funcionam por um callback MCP. O Codex chama de volta o Hermes para as ferramentas que ele não tem embutidas.
• Memória e cutucadas de skill continuam funcionando — os eventos do Codex são projetados no formato de mensagem do Hermes, então o laço de autoaperfeiçoamento vê uma transcrição de aparência normal.

Que ferramentas o modelo tem de fato

Esta é a parte que a maioria quer saber logo de cara. Com o runtime ligado, o modelo que roda o seu turno tem três fontes independentes de ferramentas:

1. Conjunto de ferramentas embutido do Codex (sempre ligado)

Elas vêm com o próprio codex app-server — sem envolvimento do Hermes, sem MCP, sem plugins. As cinco ficam disponíveis assim que o runtime sobe:

• shell — roda comandos de shell arbitrários dentro do sandbox. É assim que o modelo lê arquivos (cat, head, tail), escreve neles (echo > foo, heredocs), busca dentro deles (find, rg, grep), navega por diretórios (ls, cd), roda builds, gerencia processos e faz qualquer outra coisa que você faria no bash.
• apply_patch — aplica um diff estruturado de vários arquivos no formato de patch do Codex. O modelo usa isso para edições de código não triviais (adicionar uma função, refatorar em vários arquivos); heredocs no shell continuam disponíveis para escritas pontuais.
• update_plan — o rastreador interno de tarefas/plano do Codex. Equivalente à ferramenta todo do Hermes, mas gerenciado inteiramente dentro do runtime do Codex.
• view_image — carrega um arquivo de imagem local na conversa para o modelo poder ver.
• web_search — o Codex tem a própria busca na web embutida quando configurada. O Hermes também expõe web_search (via Firecrawl) pelo callback descrito abaixo; o modelo escolhe a que preferir.

Ou seja, tudo que você faria pelo terminal — ler, escrever, buscar, encontrar, executar — o Codex faz nativamente. O perfil de sandbox (:workspace por padrão quando você liga o runtime) controla o que é gravável.

2. Plugins nativos do Codex (migrados da sua instalação codex plugin)

Quando você liga o runtime, o Hermes consulta o RPC plugin/list do Codex e escreve uma entrada [plugins."<nome>@openai-curated"] para cada plugin que você tem instalado. Os plugins em si são gerenciados pelo Codex e autorizados uma vez pela interface dele.

Exemplos (os que a thread do OpenClaw destacou como "dignos de vídeo no YouTube"):

• Linear — buscar e atualizar issues
• GitHub — buscar código, ver PRs, comentar
• Gmail — ler e enviar e-mail
• Google Calendar — criar e buscar eventos
• Calendário/e-mail do Outlook — mesmo formato, pelo conector da Microsoft
• Canva — geração de design
• ...e o que mais você tiver instalado via codex plugin marketplace add openai-curated + codex plugin install ...

O que NÃO é migrado:

• Plugins que você ainda não instalou — instale-os no Codex primeiro.
• Entradas do marketplace de apps do ChatGPT (app/list) — elas já ficam habilitadas dentro do Codex pela autenticação da sua conta.

3. Callback de ferramentas do Hermes (servidor MCP, registrado em ~/.codex/config.toml)

O Hermes se registra como servidor MCP para o Codex poder chamar de volta as ferramentas que ele não traz. Disponíveis pelo callback:

• web_search / web_extract — via Firecrawl; costuma ser mais limpo do que raspar a página para conteúdo estruturado.
• browser_navigate / browser_click / browser_type / browser_press / browser_snapshot / browser_scroll / browser_back / browser_get_images / browser_console / browser_vision — automação completa de navegador com Camofox ou Browserbase.
• vision_analyze — chama um modelo de visão separado para inspecionar uma imagem (diferente do view_image do Codex, que carrega a imagem na conversa).
• image_generate — geração de imagem pela cadeia do plugin image_gen do Hermes.
• skill_view / skills_list — leitura da biblioteca de skills do Hermes.
• text_to_speech — TTS pelo provedor configurado no Hermes.

Quando o modelo quer uma dessas, o Codex sobe o subprocesso hermes_tools_mcp_server via MCP por stdio, a chamada é despachada por model_tools.handle_function_call() (o mesmo caminho de código do runtime padrão do Hermes) e o resultado volta para o Codex como qualquer outra resposta MCP.

O que NÃO está disponível neste runtime

Estas quatro ferramentas do Hermes precisam do contexto do AIAgent em execução (estado no meio do laço) para serem despachadas, e um callback MCP sem estado não consegue conduzi-las. Volte para o runtime padrão (/codex-runtime auto) quando precisar de alguma delas:

• delegate_task — criar subagentes
• memory — o armazenamento de memória persistente do Hermes
• session_search — busca entre sessões
• todo — o armazenamento de tarefas do Hermes (o update_plan do Codex é o equivalente dentro do runtime)

Recursos de fluxo de trabalho (/goal, kanban, cron)

/goal (o laço Ralph)

Funciona neste runtime. As metas persistem em state_meta com chave por id de sessão, o prompt de continuação volta como uma mensagem de usuário normal por run_conversation() e o Codex executa o próximo turno nativamente. O juiz de metas roda pelo cliente auxiliar (configurado em auxiliary.goal_judge no config.yaml), independentemente de qual runtime está ativo. O veredito "bloqueado, precisa da pessoa" do juiz é uma saída limpa se o Codex travar em aprovações.

Um ponto de atenção: cada prompt de continuação é um turno novo do Codex, o que significa que o Codex reavalia a política de aprovação de comandos do zero. Se você está tocando uma meta longa com muitas escritas, espere mais pedidos de aprovação do que veria em uma tarefa única dentro da sessão. Defina default_permissions = ":workspace" (o que o Hermes faz automaticamente quando você liga o runtime) para que escritas simples no espaço de trabalho não peçam confirmação.

Kanban (despacho multiagente em worktrees)

Funciona neste runtime, com uma dependência sutil. O despachante do kanban sobe cada trabalhador como um subprocesso hermes chat -q separado que lê a configuração da pessoa — ou seja, se model.openai_runtime: codex_app_server estiver definido globalmente, os trabalhadores também sobem no runtime do Codex.

O que funciona dentro de um trabalhador no runtime do Codex:

• O conjunto completo de ferramentas do Codex (shell, apply_patch, update_plan, view_image, web_search) — o trabalhador faz o trabalho de verdade nativamente
• Os plugins migrados do Codex — Linear, GitHub etc.
• O callback de ferramentas do Hermes para browser_*, visão, image_gen, skills e TTS

O que também funciona porque o callback MCP expõe:

• kanban_complete / kanban_block / kanban_comment / kanban_heartbeat — as ferramentas de devolução do trabalhador. Elas leem HERMES_KANBAN_TASK do ambiente (definida pelo despachante), controlam o acesso corretamente e escrevem no banco SQLite por quadro fixado por HERMES_KANBAN_DB. Sem elas no callback, um trabalhador neste runtime conseguiria fazer a tarefa mas não conseguiria reportar de volta, travando até o timeout do despachante.
• kanban_show / kanban_list — consultas somente leitura ao quadro para o trabalhador conferir o próprio contexto.
• kanban_create / kanban_unblock / kanban_link — operações só de orquestrador. Disponíveis para agentes orquestradores rodando no runtime do Codex que precisam despachar novas tarefas.

As ferramentas de kanban são controladas pela variável de ambiente HERMES_KANBAN_TASK que o despachante define — essa variável é propagada para o subprocesso do Codex (que herda o ambiente) e dali para o subprocesso do servidor MCP hermes-tools. Assim as ferramentas veem o id de tarefa certo e controlam o acesso corretamente. Para trabalhadores do Codex app-server, o Hermes também passa sobrescritas estreitas de sandbox do app-server quando HERMES_KANBAN_TASK está presente: mantém o sandbox workspace-write, acrescenta o diretório do banco do quadro mais todo caminho de Kanban que o despachante fixou como raízes graváveis extras (HERMES_KANBAN_WORKSPACES_ROOT, HERMES_KANBAN_WORKSPACE, o antigo HERMES_KANBAN_ROOT — sem duplicatas, com o diretório do banco primeiro) e mantém a rede desabilitada por padrão. Isso evita a gambiarra frágil do :danger-no-sandbox e ao mesmo tempo deixa kanban_complete / kanban_block atualizarem o banco do quadro e deixa os trabalhadores escreverem relatórios e artefatos em montagens de espaço de trabalho fora do diretório do banco (por exemplo /media/.../kanban-workspaces/... em outro disco — issue #27941).

Tarefas de cron

Não foi testado especificamente. As tarefas de cron rodam por cronjob → AIAgent.run_conversation, o mesmo caminho de código da CLI. Se a configuração da tarefa tiver openai_runtime: codex_app_server, ela roda no Codex. Valem as mesmas regras de disponibilidade de ferramentas — as embutidas do Codex, os plugins e o callback MCP funcionam; as ferramentas do laço do agente (delegate_task, memory, session_search, todo) não. Se a sua tarefa de cron depende dessas, aponte o cron para um perfil que use o runtime padrão.

Compromissos

	Runtime padrão do Hermes	Codex app-server (opt-in)
Subagentes com delegate_task	sim	indisponível — precisa do contexto do laço do agente
memory, session_search, todo	sim	indisponível — precisa do contexto do laço do agente
web_search, web_extract	sim	sim (pelo callback MCP)
Automação de navegador (Camofox/Browserbase)	sim	sim (pelo callback MCP)
vision_analyze, image_generate	sim	sim (pelo callback MCP)
skill_view, skills_list	sim	sim (pelo callback MCP)
text_to_speech	sim	sim (pelo callback MCP)
shell do Codex (terminal/ler/escrever/buscar/encontrar/executar)	—	sim (embutido do Codex)
apply_patch do Codex (edições estruturadas em vários arquivos)	—	sim (embutido do Codex)
update_plan do Codex (tarefas dentro do runtime)	—	sim (embutido do Codex)
view_image do Codex (carregar imagem na conversa)	—	sim (embutido do Codex)
Sandbox do Codex (seatbelt/landlock, perfis)	—	sim (embutido do Codex)
Autenticação por assinatura do ChatGPT	—	sim (pelo provedor openai-codex)
Plugins nativos do Codex (Linear, GitHub etc.)	—	sim (migrados automaticamente)
Servidores MCP da pessoa	sim	sim (migrados para o Codex)
Memória + revisão de skills (em segundo plano)	sim	sim (por projeção de itens)
Conversas de vários turnos	sim	sim
/goal (laço Ralph)	sim	sim
Despacho de trabalhadores do kanban	sim	sim (pelo callback)
Ferramentas de orquestrador do kanban	sim	sim (pelo callback)
Todas as plataformas de gateway	sim	sim
Provedores que não são OpenAI	sim	n/d — restrito a OpenAI/Codex

Exibição ao vivo

Mesmo com o laço do agente rodando dentro do subprocesso do Codex, o runtime faz a ponte do fluxo de eventos do Codex para o mesmo caminho de exibição que o runtime padrão usa:

• Deltas do assistente ao vivo, raciocínio (incluindo deltas de resumo) e eventos de início e conclusão de ferramenta com ID estável aparecem na TUI, no desktop e nos gateways de mensagem enquanto o turno roda. O projetor de histórico, que só registra conclusões, continua separado, então uma sessão retomada reidrata os mesmos cartões de ferramenta exibidos durante o turno.
• O comentário do gateway continua visível quando o streaming de tokens está desligado, e os eventos de ferramenta ao vivo são encaminhados mesmo para notificações drenadas antes de um pedido de aprovação. O comentário respeita display.show_commentary.

Pré-requisitos

1. CLI do Codex instalada:

   npm i -g @openai/codex
   codex --version   # 0.130.0 ou mais novo

2. Login OAuth do Codex. O subprocesso do Codex lê ~/.codex/auth.json. Há dois jeitos de preenchê-lo:

   codex login                  # grava os tokens em ~/.codex/auth.json

   O hermes auth add openai-codex do próprio Hermes grava em ~/.hermes/auth.json — é outra sessão. Rode codex login à parte se ainda não rodou.

3. (Opcional) Instale os plugins do Codex que você quer. Quando você liga o runtime, o Hermes migra automaticamente os plugins da coleção curada que você já instalou pela CLI do Codex:

   codex plugin marketplace add openai-curated
   # depois, pela TUI do codex, instale Linear / GitHub / Gmail / etc.

   O Hermes descobre esses plugins e escreve entradas [plugins."<nome>@openai-curated"] em ~/.codex/config.toml sozinho.

Como ligar

Dentro de uma sessão do Hermes:

/codex-runtime codex_app_server

Esse comando:

• Verifica se a CLI codex está instalada (barra com uma dica de instalação se não estiver).
• Persiste model.openai_runtime: codex_app_server no seu config.yaml.
• Migra os servidores MCP da pessoa de ~/.hermes/config.yaml para ~/.codex/config.toml.
• Descobre e migra os plugins nativos do Codex instalados (Linear, GitHub, Gmail, Calendar, Canva etc.) consultando o RPC plugin/list do Codex.
• Registra as ferramentas do próprio Hermes como um servidor MCP para o subprocesso do Codex poder chamar de volta as ferramentas que ele não traz.
• Escreve default_permissions = ":workspace" para o sandbox permitir escritas dentro do espaço de trabalho sem pedir confirmação a cada operação.
• Conta o que foi migrado. Passa a valer na próxima sessão — o agente em cache atual mantém o runtime anterior para os caches de prompt continuarem válidos.

Sinônimos: /codex-runtime on, /codex-runtime off, /codex-runtime auto.

Para ver o estado atual sem mudar nada:

/codex-runtime

Você também pode definir na mão em ~/.hermes/config.yaml:

model:
  openai_runtime: codex_app_server   # o padrão é "auto" (= runtime do Hermes)

Laço de autoaperfeiçoamento (memória + cutucadas de skill)

O autoaperfeiçoamento em segundo plano do Hermes dispara por limiares de contador:

• A cada 10 prompts da pessoa → um agente de revisão bifurcado olha a conversa e decide se há algo a salvar na memória.
• A cada 10 iterações de ferramenta dentro de um mesmo turno → a mesma ideia, mas para skills (escritas de skill_manage).

Os dois continuam funcionando no runtime do Codex. O caminho do Codex projeta cada item commandExecution / fileChange / mcpToolCall / dynamicToolCall concluído em uma mensagem sintética de assistant tool_call + resultado tool, então, quando a revisão roda, ela vê o mesmo formato que veria no runtime padrão do Hermes.

Como a ligação se mantém equivalente:

	Runtime padrão	Runtime do Codex
Incrementos de _turns_since_memory	por prompt da pessoa, no pré-laço de run_conversation	mesmo caminho de código, antes do retorno antecipado
Incrementos de _iters_since_skill	por iteração de ferramenta no laço de chat-completions	por turn.tool_iterations depois que o turno do Codex retorna
Gatilho de memória (_turns_since_memory >= _memory_nudge_interval)	calculado no pré-laço, dispara depois da resposta	calculado no pré-laço, repassado ao helper do Codex
Gatilho de skill (_iters_since_skill >= _skill_nudge_interval)	calculado depois do laço	calculado depois do turno do Codex
_spawn_background_review(messages_snapshot=..., review_memory=..., review_skills=...)	chamado quando qualquer gatilho dispara	chamado do mesmo jeito quando qualquer gatilho dispara

Um detalhe: a bifurcação de revisão em si precisa chamar as ferramentas do laço do agente do Hermes (memory, skill_manage), que exigem o despacho do próprio Hermes. Então, quando o agente pai está em codex_app_server, a bifurcação de revisão é rebaixada para codex_responses — mesmas credenciais OAuth, mesmo provedor openai-codex, mas falando direto com a Responses API da OpenAI para o Hermes ser dono do laço e as ferramentas do laço do agente funcionarem. Isso é invisível para você.

Efeito líquido: ligue o runtime do Codex e suas cutucadas de memória e skill continuam disparando exatamente como disparariam de outro modo.

Como funcionam as aprovações

O Codex pede aprovação antes de executar comandos ou aplicar patches. Esses pedidos são traduzidos para o prompt padrão de "Dangerous Command" do Hermes:

╭───────────────────────────────────────╮
│ 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 → aprova esse comando específico.
• Allow for this session → o Codex não pergunta de novo para comandos parecidos.
• Deny → o comando é rejeitado; o Codex segue em modo somente leitura.

Para aprovações de apply_patch (edição de arquivo), o Hermes mostra um resumo do que mudou (1 add, 1 update: /tmp/new.py, /tmp/old.py) quando o Codex fornece os dados pelo item fileChange correspondente.

Perfis de permissão

O Codex tem três perfis de permissão embutidos:

• :read-only — sem escritas; todo comando de shell precisa de aprovação
• :workspace — escritas dentro do espaço de trabalho atual permitidas sem confirmação (o padrão do Hermes quando você liga o runtime)
• :danger-no-sandbox — sem sandbox nenhum (não use se você não souber exatamente o que está fazendo)

Dá para sobrescrever o padrão em ~/.codex/config.toml, fora do bloco gerenciado pelo Hermes:

default_permissions = ":read-only"

(O Hermes preserva a sua sobrescrita nas remigrações, desde que ela fique fora dos marcadores # managed by hermes-agent.)

Tarefas auxiliares e custo de tokens da assinatura do ChatGPT

Com este runtime ligado e o provedor openai-codex, as tarefas auxiliares (geração de título, compressão de contexto, detecção automática de visão, a bifurcação de revisão de autoaperfeiçoamento em segundo plano) também passam pela sua assinatura do ChatGPT por padrão, porque o cliente auxiliar do Hermes usa o provedor/modelo principal quando não há sobrescrita por tarefa.

Isso não é específico do codex_app_server — vale também para o caminho codex_responses já existente —, mas fica mais visível aqui porque você está optando explicitamente pela cobrança na assinatura.

Para mandar tarefas auxiliares específicas para um modelo mais barato ou diferente, defina sobrescritas explícitas em ~/.hermes/config.yaml:

auxiliary:
  title_generation:
    provider: openrouter
    model: google/gemini-3-flash-preview
  compression:
    provider: openrouter
    model: google/gemini-3-flash-preview
  vision:
    provider: openrouter
    model: google/gemini-3-flash-preview
  goal_judge:
    provider: openrouter
    model: google/gemini-3-flash-preview

A bifurcação de revisão do autoaperfeiçoamento herda o runtime principal via _current_main_runtime(), e o Hermes a rebaixa de codex_app_server para codex_responses automaticamente (para a bifurcação conseguir mesmo chamar memory e skill_manage — ferramentas do laço do agente do próprio Hermes). Essa bifurcação continua usando a autenticação da sua assinatura, a menos que você tenha mandado as tarefas auxiliares para outro lugar.

Como editar ~/.codex/config.toml com segurança

O Hermes envolve tudo que gerencia entre dois comentários marcadores:

# 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

Tudo que estiver fora desse bloco é seu. Rodar a migração de novo (via /codex-runtime codex_app_server ou sempre que você liga o runtime) substitui o bloco gerenciado no lugar, mas preserva o conteúdo da pessoa acima e abaixo dele, palavra por palavra. Isso significa que você pode:

• Adicionar servidores MCP próprios que o Hermes desconhece
• Sobrescrever default_permissions para :read-only se preferir ser consultado
• Configurar opções só do Codex (modelo, provedores, otel etc.)
• Adicionar perfis de permissão próprios em tabelas [permissions.<nome>]

Qualquer coisa que você adicionar dentro do bloco gerenciado será apagada na próxima migração. Se você precisa de um ajuste que exige editar o bloco gerenciado, abra uma issue que a gente acrescenta a opção.

Configurações com vários perfis ou vários inquilinos

Por padrão, o Hermes aponta o subprocesso do Codex para ~/.codex/, seja qual for o perfil do Hermes ativo. Ou seja, hermes -p work e hermes -p personal compartilham a mesma autenticação, os mesmos plugins e a mesma configuração do Codex. Para a maioria das pessoas esse é o comportamento certo — ele bate com o que rodar a CLI codex diretamente faria.

Se você quer isolamento do Codex por perfil (autenticação separada, plugins instalados separados, configuração separada), defina CODEX_HOME explicitamente em cada perfil. O jeito mais limpo é apontar para um diretório dentro do seu HERMES_HOME:

# Dentro do perfil de trabalho, você pode envolver o hermes assim:
CODEX_HOME=~/.hermes/profiles/work/codex hermes chat

Você vai precisar rodar codex login uma vez com esse CODEX_HOME definido para os tokens OAuth caírem no lugar específico do perfil. Depois disso, hermes -p work opera sobre um estado do Codex isolado.

Não fazemos esse escopo automaticamente porque mover o ~/.codex/ de quem já usa invalidaria em silêncio a autenticação da CLI do Codex — quem já rodou codex login teria que se autenticar de novo. Opt-in parece mais seguro do que surpreender as pessoas.

Repasse da variável de ambiente HOME

O Hermes NÃO reescreve HOME ao subir o subprocesso do app-server do Codex (usamos os.environ.copy() e só sobrepomos CODEX_HOME e RUST_LOG). Isso significa que:

• Os comandos que o Codex roda pela ferramenta shell veem o HOME real da pessoa e encontram ~/.gitconfig, ~/.gh/, ~/.aws/, ~/.npmrc etc. corretamente.
• O estado interno do Codex fica isolado por CODEX_HOME (que aponta para ~/.codex/ por padrão).

Isso corresponde à fronteira a que o OpenClaw chegou depois de alguma experimentação inicial: isolar o estado do Codex e deixar a pasta pessoal em paz. (Cf. openclaw/openclaw#81562.)

Migração de servidores MCP

A configuração mcp_servers do Hermes é traduzida automaticamente para o formato TOML que o Codex espera. A migração roda toda vez que você liga o runtime e é idempotente — reexecuções substituem a seção gerenciada, mas preservam qualquer configuração do Codex editada por você.

O que é traduzido:

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

O que não é migrado:

• Chaves específicas do Hermes, como sampling (o cliente MCP do Codex não tem equivalente — elas são descartadas com um aviso por servidor).

Migração de plugins nativos do Codex

Os plugins instalados via codex plugin (Linear, GitHub, Gmail, Calendar, Canva etc.) são descobertos pelo RPC plugin/list do Codex. Para cada plugin com installed: true, o Hermes escreve um bloco [plugins."<nome>@openai-curated"] habilitando-o na sua sessão do Hermes.

Ou seja: quando um amigo diz "tenho Calendar e GitHub configurados na minha CLI do Codex" e liga o runtime do Codex no Hermes, o Hermes ativa esses plugins automaticamente. Sem reconfigurar nada.

O que NÃO é migrado:

• Plugins que você ainda não instalou — instale-os no Codex primeiro.
• Plugins em que o Codex reporta availability != AVAILABLE (instalação quebrada, OAuth expirado, removido do marketplace etc.). Eles são pulados para evitar escrever uma configuração que falharia na hora da ativação.
• Entradas do marketplace de apps do ChatGPT (os resultados de app/list, por conta — elas já ficam habilitadas dentro do Codex pela autenticação da sua conta).
• OAuth de plugin — você autoriza cada plugin uma vez no próprio Codex; o Hermes não mexe em credenciais.

Callback de ferramentas do Hermes (o novo servidor MCP)

O conjunto de ferramentas embutido do Codex cobre shell, operações de arquivo e patches, mas não tem busca na web, automação de navegador, visão, geração de imagem etc. Para manter isso tudo utilizável em um turno do Codex, o Hermes se registra como servidor MCP em ~/.codex/config.toml:

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

Quando o modelo chama web_search (ou outra ferramenta do Hermes exposta), o Codex sobe o subprocesso hermes_tools_mcp_server via stdio, a requisição é despachada por model_tools.handle_function_call() e o resultado é projetado de volta para o Codex como qualquer outra resposta MCP.

Ferramentas disponíveis pelo 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.

Ferramentas NÃO disponíveis: delegate_task, memory, session_search, todo. Elas precisam do contexto do AIAgent em execução para serem despachadas (estado no meio do laço), e um callback MCP sem estado não consegue conduzi-las. Use o runtime padrão do Hermes (/codex-runtime auto) quando precisar delas.

Como desligar

Volte atrás quando quiser:

/codex-runtime auto

Vale a partir da próxima sessão. O bloco gerenciado do Codex continua em ~/.codex/config.toml para você poder religar depois sem perder configuração — ou remova-o na mão, se preferir.

Limitações

Este runtime é beta e opt-in. Funcionando no Hermes Agent 2026.5 + CLI do Codex 0.130.0:

• Conversas de vários turnos
• Aprovações de commandExecution e fileChange (apply_patch) pela interface do Hermes
• Chamadas de ferramenta MCP (verificadas com @modelcontextprotocol/server-filesystem e com o novo callback hermes-tools)
• Migração de plugins nativos do Codex (verificada com o inventário de Linear / GitHub / Calendar)
• Caminhos de negação e cancelamento
• Ciclo de ligar e desligar
• Contadores de cutucada de memória e skill (verificados ao vivo em testes de integração)
• web_search do Hermes pelo Codex (verificado ao vivo: "OpenAI Codex CLI – Getting Started" retornou de ponta a ponta)

Limitações conhecidas:

• A autenticação do Hermes e a do Codex são sessões separadas. Você precisa tanto de codex login quanto de hermes auth add openai-codex para a experiência mais limpa (o runtime usa a sessão do Codex para a chamada ao LLM). Isso é uma decisão de projeto deliberada no _import_codex_cli_tokens do Hermes — ele não compartilha estado OAuth com a CLI do Codex para os dois não se atropelarem na renovação de token.
• delegate_task, memory, session_search e todo não estão disponíveis neste runtime. Elas precisam do contexto do AIAgent em execução, que um callback MCP sem estado não consegue fornecer. Use /codex-runtime auto quando precisar delas.
• Sem prévia do patch em linha nos pedidos de aprovação quando o Codex não rastreia o conjunto de mudanças. Os parâmetros de aprovação de fileChange do Codex nem sempre trazem o changeset. O Hermes guarda em cache os dados da notificação item/started correspondente quando dá, mas se a aprovação chega antes de o item ter sido transmitido, o prompt cai no reason que o Codex fornecer.
• Cancelamento em menos de um segundo não é garantido. Interrupções no meio do fluxo (Ctrl+C enquanto o Codex responde) são enviadas por turn/interrupt, mas se o Codex já despachou a mensagem final, você recebe a resposta mesmo assim.

Se encontrar um bug, abra uma issue com a saída de hermes logs --since 5m. Cite codex-runtime no título para facilitar a triagem.

Arquitetura

                ┌─── Casca do Hermes (CLI / TUI / gateway) ┐
                │  banco de sessões · comandos de barra    │
                │  memória e revisão de skills · cron      │
                │  seletores de sessão                     │
                └──┬──────────────────────────────────────┬┘
                   │ user_message               texto     │
                   ▼                            final +   │
        ┌──────────────────────────────────┐   mensagens  │
        │  AIAgent.run_conversation()       │  projetadas  │
        │   if api_mode == codex_app_server │              │
        │     → CodexAppServerSession       │              │
        │   else: chat_completions / codex_responses (padrão)
        └────┬─────────────────────────────┘              │
             │ JSON-RPC por stdio                         │
             ▼                                            │
        ┌──────────────────────────────────┐              │
        │  codex app-server (subprocesso)   │──────────────┘
        │   thread/start, turn/start        │
        │   notificações item/*             │
        │   shell + apply_patch + update_plan│
        │   view_image + sandbox            │
        │   ┌─────────────────────────┐     │
        │   │  cliente MCP            │     │
        │   │  ├─ servidores MCP seus │     │
        │   │  ├─ plugins nativos     │     │
        │   │  │   (linear, github,   │     │
        │   │  │    gmail, calendar,  │     │
        │   │  │    canva, ...)       │     │
        │   │  └─ hermes-tools ───────┼─────────────────┐
        │   │       (callback para   │     │           │
        │   │        as ferramentas  │     │           │
        │   │        do Hermes)      │     │           │
        │   └─────────────────────────┘     │           │
        └──────────────────────────────────┘           │
                                                        │
                                                        ▼
        ┌──────────────────────────────────────────────────────────┐
        │  hermes_tools_mcp_server.py (subprocesso sob demanda)     │
        │   web_search, web_extract, browser_*, vision_analyze,    │
        │   image_generate, skill_view, skills_list, text_to_speech│
        └──────────────────────────────────────────────────────────┘

Para detalhes de implementação, veja o PR #24182 e o README do protocolo do app-server do Codex.

---