"invalid transport in mcp_servers.codex_app" no Codex: por que todo chat falha e como resolver
Voltar para o Blog
Artigocodextroubleshootingwindowsmcpopenai

"invalid transport in mcp_servers.codex_app" no Codex: por que todo chat falha e como resolver

Mafra15 de novembro de 20266 min de leitura

Você abre o Codex Desktop no Windows, escolhe um projeto e manda a primeira mensagem. O chat nem começa. O terminal ou a UI devolve:

failed to load configuration: invalid transport
in `mcp_servers.codex_app`

Você abre o config.toml procurando esse servidor. Não existe. Você nunca configurou nada chamado codex_app. É aí que a maioria das pessoas começa a mexer no que não devia, reinstala o app, limpa o .codex e perde uma tarde.

A mensagem não é sobre a sua configuração. É sobre um componente interno do próprio app que deixou de ser válido no ambiente onde o backend está rodando. E existe uma causa dominante, com um ajuste de uma linha.

Fluxograma: todo chat falha com invalid transport, confirmar no log, checar se o backend roda no WSL, desligar o WSL e, se ainda falhar, fechar e reabrir o app
O caminho do erro: o transporte do servidor interno não existe dentro do WSL, e a falha derruba o carregamento da configuração inteira.

O que essa mensagem está dizendo?

O Codex Desktop embarca um plugin interno, codex-app-tools@openai-bundled, que registra um servidor MCP chamado codex_app. Esse servidor não é uma integração sua. Ele é o que sustenta a orquestração de threads e subagentes, com ferramentas como create_thread, fork_thread e send_message_to_thread.

O transporte dele é declarado assim, no arquivo %USERPROFILE%\.codex\plugins\cache\openai-bundled\codex-app-tools\0.1.3\desktop-mcp.json:

{
  "mcpServers": {
    "codex_app": {
      "command": "cmd.exe",
      "args": ["/d", "/s", "/c", "call", "./scripts/launch_codex_app_tools_mcp.cmd", "./server.mjs"],
      "cwd": ".",
      "enabled": true
    }
  }
}

Leia a linha do command: cmd.exe. É um transporte que só existe no Windows. Quando o backend do app roda dentro do WSL, quem tenta abrir esse processo é um binário Linux, que não resolve cmd.exe. O carregador de configuração rejeita o servidor com invalid transport, e como a rejeição é fatal, todo thread/start volta com o código -32600. Não é um chat quebrado, são todos.

Como confirmar em dois minutos?

Vá nos logs do app e procure duas coisas: a string do erro e a linha que mostra em qual ambiente o backend está rodando.

# Windows (PowerShell), logs do pacote instalado pela Microsoft Store
cd "$env:LOCALAPPDATA\Packages\[OI].Codex_2p2nqsd0c76g0\LocalCache\Local\Codex\Logs"
Select-String -Path *.log -Pattern "invalid transport","Spawning process inside WSL"

Se as duas aparecerem juntas, o diagnóstico está fechado. Na issue #40910 do repositório oficial, o teste A/B é exatamente esse: mesmo app, mesmo config.toml, mesma máquina, só a chave do WSL invertida. Com o WSL ligado, 125 ocorrências do erro em várias sessões. Com o WSL desligado, nenhuma, e a mensagem é enviada e processada normalmente.

Como resolver?

Abra o config.toml (fica em %USERPROFILE%\.codex\config.toml) e desligue a execução dentro do WSL:

runCodexInWindowsSubsystemForLinux = false

Se a chave já existir, só troque o valor. Feche o app inteiro, não apenas a janela, e abra de novo. A correção é imediata e confiável, é o que a issue relata como solução que funciona sempre.

Atenção a um detalhe que engana: no app, esse ajuste aparece como um toggle nas configurações, com o rótulo "Run Codex in WSL". Mudar pelo toggle e pelo arquivo tem o mesmo efeito, mas o app precisa reiniciar para reler. Se você mudou e nada aconteceu, provavelmente só fechou a janela.

Por que desligar o plugin não resolve?

Este é o passo que consome mais tempo de quem tenta resolver sozinho. A tentação é desabilitar o plugin que aparece no erro:

[plugins."codex-app-tools@openai-bundled"]
enabled = false

Não funciona. O servidor continua sendo carregado e continua falhando, porque ele não passa pelo toggle normal de plugin. A issue #40910 registra isso explicitamente. Se você chegou até aqui tentando essa saída, pode parar de tentar.

E se você precisa do WSL?

Aqui a resposta honesta é que não existe correção suportada até agora. Desligar o WSL resolve o erro, mas muda o ambiente de execução: caminhos /mnt/..., servidores MCP que só existem no Linux e toolchain nativo deixam de valer. Se o seu fluxo depende disso, desligar não é workaround, é trocar de problema.

As alternativas reais hoje:

  • Rodar o CLI dentro do WSL, em vez do Desktop. O bug está no caminho de código do app desktop, não no CLI. O CLI dentro do WSL não passa por esse transporte.
  • Manter o Desktop no Windows nativo e chamar o WSL por comando. Menos fluido, mas preserva o acesso ao ambiente Linux quando você precisa dele pontualmente.
  • Não contar com downgrade. O app atualiza pela Microsoft Store, que não expõe versões antigas, e as releases do repositório só trazem binários do CLI. A issue #26914 pede justamente isso e segue sem resposta de mantenedor.

Quando o erro aparece sem WSL nenhum?

Existe uma segunda família de causas, menos comum e mais chata, em que o WSL está desligado e o erro continua. Ela costuma vir de uma chave legada que o renderer envia antes de o app terminar de inicializar. Nesse caso o sintoma é intermitente: funciona em alguns lançamentos e falha em outros, e um quit completo seguido de reabertura limpa a sessão.

Há ainda a variante de permissão de socket, documentada na #56677 para Macs com mais de uma conta de usuário. O diretório /private/tmp/codex-app-tools fica com dono de outra conta, e o app não consegue criar o socket. O log mostra EACCES e listen EACCES: permission denied. A recuperação é devolver o acesso ao diretório e reabrir o app, mas o diretório pode voltar ao estado errado depois.

SintomaCausaO que resolve
Todo chat falha, sempre, no WindowsBackend dentro do WSL, transporte cmd.exe inválidorunCodexInWindowsSubsystemForLinux = false
Falha intermitente, some ao reabrirChave legada enviada pelo renderer antes da inicializaçãoQuit completo e reabrir
Falha só para um usuário do Mac/private/tmp/codex-app-tools com dono de outra contaDevolver o acesso ao diretório e reabrir
Desabilitar o plugin codex-app-toolsNão passa pelo toggle normalNada, essa saída não existe
Espelhar o bloco em config.tomlFunciona, mas os caminhos são específicos da versãoQuebra no próximo update do app

O que dá para aprender com esse erro?

A falha tem uma característica que vale reconhecer em qualquer ferramenta: um componente interno registrou um transporte que só existe em um sistema operacional, e a falha dele é fatal para a sessão inteira. O app não degrada. Ele simplesmente não abre conversa nenhuma.

Um servidor MCP quebrado não deveria derrubar o carregamento da configuração, e é isso que a própria issue sugere como terceira direção de correção: tornar a falha daquele servidor não fatal, desligando só a feature que depende dele. Enquanto isso não chega, o caminho é diagnosticar pelo log e cortar a causa na raiz.

Na Verboo Code, cada servidor MCP é declarado por você, com transporte explícito, e o estado de cada um é visível separadamente. Um servidor que não conecta vira uma linha com falha, não um app que não abre. Se quiser ver como isso funciona na prática, comece por aqui.

Gostou deste artigo?
Compartilhe conhecimento com sua rede.
// Leia também

Artigos relacionados