Codex vem com um importador de comando único que migra automaticamente a maior parte das configurações do Claude Code. O desafio real está nos detalhes: parte da configuração precisa ser montada manualmente, e um item específico não é migrado diretamente — não se trata de um arquivo de configuração, mas dos próprios modelos Anthropic.
Migrar quase todo o conjunto de configurações do Claude Code para o Codex leva aproximadamente 20 minutos. Abaixo estão as referências básicas para uma inicialização rápida.
1. O que migra e o que não migra — Veredito rápido
1.1. Diagnóstico expresso: tabela de compatibilidade de superfícies
| Questão | Solução / Resposta |
|---|---|
| É possível migrar a maior parte da configuração? | Sim. 9 das 12 superfícies são migradas ou reconstruídas sem problemas graves. |
| Caminho mais rápido? | codex → /import (Codex 0.140+), depois ajuste manualmente 3 itens. |
| O que é migrado automaticamente? | Arquivos de memória, servidores MCP, skills, slash-commands, endpoints customizados. |
| O que requer ajuste manual? | Modelo de permissões de acesso, formato de hooks, wrappers de subagentes. |
| Único beco sem saída? | Modelos Anthropic Claude. O Codex vanilla funciona apenas com modelos OpenAI. |
| Solução para o beco sem saída? | Adicionar um gateway como model_provider e continuar usando o Claude dentro do Codex. |
📌 Versões do ambiente: Este guia foi testado no Codex CLI 0.142.5 (1º de julho de 2026) e no Claude Code 2.1.178. Se você estiver usando uma versão anterior do Codex, atualize obrigatoriamente, pois o comando
/importfoi introduzido na versão 0.140.0.
1.2. Componentes automáticos e manuais da migração
O que pode ser migrado sem obstáculos:
- Instruções do repositório e configurações pessoais (conteúdo de
CLAUDE.md). - Servidores MCP — comandos e argumentos são migrados literalmente.
- Skills — elas seguem a convenção Agent Skills comum a ambas as ferramentas.
- Slash-commands e prompts reutilizáveis.
- Endpoints de API customizados e chaves de autorização.
O que requer um caminho alternativo ou reconstrução manual:
- Lista operacional de permissões (
permission allowlist) do Claude Code — o Codex usa um sandbox de dois níveis. - Hook de evento
ConfigChange(o Codex possuiPreCompact/PostCompact, mas não há gatilho para alteração de arquivo de configuração). - Output styles — o conceito de estilos de saída não existe no Codex.
- Modelos Anthropic — o Codex padrão suporta apenas modelos OpenAI; para usar o Claude, é necessário um gateway/provider.
2. Mapa completo: todas as 12 configurações do Claude Code e seus análogos no Codex
2.1. Matriz comparativa resumida das superfícies de configuração
A maioria dos parâmetros é migrada sem perdas, pois ambas as ferramentas resolvem os mesmos desafios de engenharia, utilizando formatos de serialização diferentes: o Claude Code baseia-se em JSON (settings.json, .mcp.json) e Markdown (CLAUDE.md, .claude/agents/*.md), enquanto o Codex utiliza um único arquivo TOML (~/.codex/config.toml) e AGENTS.md.
| № | Superfície do Claude Code | Análogo no Codex | Veredito da migração |
|---|---|---|---|
| 1 | CLAUDE.md (memória) | AGENTS.md (ou nome de arquivo alternativo) | Migrável |
| 2 | .mcp.json (JSON) | [mcp_servers.*] em config.toml | Migrável, com reformatação |
| 3 | .claude/skills/ | Skills do Codex ([[skills.config]]) | Migrável |
| 4 | .claude/commands/ | Slash-commands / prompts do Codex | Migrável, requer reconstrução |
| 5 | .claude/agents/ (Markdown) | Arquivos .codex/agents/*.toml | Reconstruído |
| 6 | settings.json (JSON) | config.toml + perfis (TOML) | Reconstruído |
| 7 | permissions.allow/ask/deny | approval_policy + sandbox_mode | Não migrável diretamente |
| 8 | Hooks (PreToolUse, Stop, …) | [[hooks.*]] em config.toml | Reconstruído |
| 9 | Hook ConfigChange | Sem análogo | Sem análogo |
| 10 | Endpoint ANTHROPIC_BASE_URL | [model_providers.*] | Migrável |
| 11 | outputStyle | Sem análogo | Sem análogo |
| 12 | Modelos Anthropic Claude | Apenas modelos OpenAI por padrão | Beco sem saída (resolvido via gateway) |
2.2. Principais diferenças arquiteturais: JSON vs TOML
As linhas 9 e 11 da matriz têm caráter cosmético: outputStyle praticamente não impacta a performance, e ConfigChange é necessário apenas para um nicho restrito de desenvolvedores com configurações dinâmicas de sessão.
A principal barreira costuma ser a linha 12 (modelos Anthropic). No entanto, conectar um gateway através da seção [model_providers] permite preservar sem obstáculos as capacidades intelectuais habituais do Claude dentro do ambiente Codex.
3. Quando migrar e quando permanecer no Claude Code
3.1. Cenários e critérios técnicos para transição ao Codex
A migração para o Codex é justificada se seus fluxos de trabalho forem centrados em tarefas autônomas e isolamento do sistema de arquivos:
- Automação em CI/CD: Necessidade de executar agentes de forma não interativa com restrições rígidas "read-only" ou "workspace-write".
- Padronização de equipe: Necessidade de ter um único arquivo
config.tomlversionado com perfis prontos para diferentes níveis de risco, em vez de fragmentados.claude/settings.local.json. - Novos modelos OpenAI Codex: Acesso necessário aos modelos
gpt-5.5egpt-5.4como ferramenta principal de geração de código.
3.2. Casos em que é conveniente permanecer no Claude Code
Permaneça no Claude Code se seu pipeline apresentar as seguintes características:
- Dependência de hooks específicos: Uso de gatilhos
ConfigChangeou estilos de formataçãooutputStyle. - Formato dialógico de interação: Todo o trabalho é estruturado como uma longa conversa interativa. A natureza conversacional do Claude Code é otimizada para isso melhor do que o ciclo batch "tarefa → verificação" do Codex.
- Allowlist fino de permissões: Se configurada uma lista de permissões multinível com regex para cada chamada de sistema, a transição para políticas de sandbox mais grossas do Codex exigirá revisão de todo o modelo de segurança.
💡 Regra de parada: Se seu objetivo é testar a qualidade da geração de código do Codex no repositório atual, não é necessário migrar toda a configuração. Basta executar o comando
/importno terminal do Codex. A configuração manual detalhada é necessária apenas para quem planeja tornar o Codex a ferramenta de trabalho principal.
4. Requisitos de sistema antes de começar
4.1. Verificação de versões CLI, projeto e permissões de acesso
Antes de editar a configuração, certifique-se de cumprir quatro condições obrigatórias:
- Codex CLI versão 0.140.0 ou superior. Verifique a versão com o comando
codex --version. - Projeto Claude Code preservado: O diretório
.claude/e o arquivoCLAUDE.mddevem permanecer intactos até a verificação completa da migração. - Chave de API do provider: Uma chave ativa da OpenAI ou chave de gateway (por exemplo, ofox.ai) é necessária para trabalhar com o Claude.
- Permissões de escrita no diretório home: O Codex lê parâmetros globais de
~/.codex/config.tomla cada execução.
4.2. Rota de migração: pipeline passo a passo da transição
O processo geral de transição consiste em seis etapas sequenciais:
5. Migração passo a passo da configuração
5.1. Passo 1: Executar o importador automático (/import)
Inicie o Codex na pasta raiz do seu projeto e execute o comando interno de importação:
O comando /import realiza uma migração seletiva de configurações, instruções de sistema e últimas sessões. Como resultado, será gerado o arquivo inicial ~/.codex/config.toml, o AGENTS.md do projeto e um relatório sobre parâmetros ignorados.
5.2. Passo 2: Instruções — transição de CLAUDE.md para AGENTS.md
O Codex procura automaticamente por AGENTS.md. Para manter a compatibilidade ou continuar lendo o arquivo antigo sem renomeá-lo, adicione caminhos alternativos à configuração:
O conteúdo das instruções não requer edição: regras de code style, comandos de build e testes são carregados no contexto do agente sem alterações.
5.3. Passo 3: Servidores MCP — conversão de JSON para TOML
Ambas as plataformas usam o padrão Model Context Protocol. Muda apenas a sintaxe da descrição: a configuração de .mcp.json é migrada para tabelas TOML.
Registro original em .mcp.json:
Registro equivalente em ~/.codex/config.toml:
Se o servidor exigir variáveis de ambiente, especifique-as inline: env = { GITHUB_TOKEN = "..." }. São suportados tanto processos locais STDIO quanto servidores remotos SSE/HTTP.
5.4. Passo 4: Subagentes — configuração em .codex/agents/
O Claude Code armazena agentes como arquivos Markdown em .claude/agents/. O Codex usa o formato TOML, onde cada subagente é descrito em um arquivo separado no diretório ~/.codex/agents/ ou .codex/agents/:
Os subagentes no Codex estão ativos por padrão e são invocados mediante solicitação explícita do usuário ou do agente principal.
5.5. Passo 5: Modelo de permissões de acesso — configuração de sandbox e approval
Os conceitos de segurança das ferramentas diferem significativamente: em vez de uma lista granular de regras glob (permissions.allow), o Codex usa parâmetros de isolamento do sistema de arquivos (sandbox_mode) e confirmação de ações (approval_policy).
| Cenário no Claude Code | Propósito | Configuração no Codex (~/.codex/config.toml) |
|---|---|---|
allow: ["Bash(npm run test *)"] | Execução automática de comandos seguros | sandbox_mode = "workspace-write"approval_policy = "on-request" |
ask: ["Bash(python *)"] | Solicitar confirmação antes da execução | approval_policy = "on-request" |
deny: ["Read(./.env)"] | Bloqueio de acesso fora do diretório | sandbox_mode = "workspace-write" |
Plan mode | Modo de análise sem alterações | sandbox_mode = "read-only" |
--dangerously-skip-permissions | Autonomia total | approval_policy = "never"sandbox_mode = "danger-full-access" |
Configuração balanceada para desenvolvimento diário:
5.6. Passo 6: Hooks — migração de eventos de ciclo de vida
Os hooks no Codex estão ativados por padrão e cobrem eventos-chave do sistema: PreToolUse, PostToolUse, SessionStart, Stop, PreCompact e PostCompact.
⚠️ Atenção: O evento
ConfigChangenão é suportado pelo Codex. Qualquer lógica que reagisse à modificação de arquivos de configuração "on the fly" deve ser movida para scripts pré-execução da sessão.
6. Beco sem saída da migração: modelos Claude no Codex e como preservá-los
6.1. Arquitetura de gateway model_provider para modelos Anthropic
O Codex é otimizado para o ecossistema OpenAI (gpt-5.5, gpt-5.4) e não possui um switch direto para modelos Anthropic. Se você precisar do Claude Opus ou Claude Sonnet para resolver desafios arquiteturais, utilize a conexão através de um gateway de API compatível.
Adicione a definição do provider em ~/.codex/config.toml:
6.2. Configuração wire_api=responses e seleção do perfil claude
Ao configurar o gateway, é crítico considerar dois parâmetros:
wire_api = "responses": o suporte ao protocolo legadochatfoi removido do Codex em fevereiro de 2026.requires_openai_auth = false: desativa a validação do prefixosk-no lado do cliente.
Crie um perfil para executar o Claude em ~/.codex/claude.config.toml:
A execução do agente com este perfil é feita pelo comando:
7. Erros comuns na migração e suas soluções
7.1. Matriz de diagnóstico e troubleshooting
| Sintoma | Causa raiz | Solução de engenharia |
|---|---|---|
Codex ignora CLAUDE.md | Por padrão, espera-se AGENTS.md | Renomeie o arquivo ou adicione project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"] |
Provider customizado retorna erro 401 | Cliente espera token OpenAI com prefixo sk- | Adicione a diretiva requires_openai_auth = false na seção [model_providers.*] |
Erro de execução chat wire API deprecated | Protocolo chat obsoleto e removido | Especifique o parâmetro wire_api = "responses" |
| Subagentes não executam ações | Falta arquivo de descrição ou agente não invocado explicitamente | Crie .codex/agents/NAME.toml; o Codex ativa agentes apenas sob comando direto |
| Hooks não disparam | Erro no nome do evento ou template regex incorreto | Verifique a sintaxe do evento e a expressão matcher em [[hooks.*]] |
| Comando do allowlist bloqueado | Sandbox do Codex é mais rigoroso que regras pontuais | Expanda sandbox_mode ou defina approval_policy = "on-request" |
7.2. Verificação de diretórios confiáveis e validação de configuração
Se o arquivo .codex/config.toml no projeto for totalmente ignorado, certifique-se de que o repositório foi adicionado à lista de confiáveis. Por razões de segurança, o Codex carrega configurações locais apenas para caminhos verificados e bloqueia tentativas de arquivos de projeto sobrescreverem a autorização global ou chaves de providers.
8. Migração para equipes
8.1. Centralização config.toml vs .local.json individuais
No ambiente Claude Code, as equipes eram obrigadas a manter dois níveis: um arquivo compartilhado .claude/settings.json no repositório e arquivos locais de cada desenvolvedor .claude/settings.local.json. O Codex simplifica esse esquema:
| Aspecto da interação | Claude Code | OpenAI Codex CLI |
|---|---|---|
| Configuração compartilhada da equipe | .claude/settings.json (versionado) | .codex/config.toml (versionado no repositório) |
| Configurações pessoais | .claude/settings.local.json | Arquivos de perfil pessoais em ~/.codex/ |
| Instruções base do projeto | CLAUDE.md | AGENTS.md |
| Granularidade de níveis de risco | permission allowlist | Flags --profile strict ou --profile fast |
8.2. Gateway de API único e billing compartilhado da equipe
O uso de um gateway único via model_provider otimiza os custos da equipe:
- O administrador adiciona parâmetros do gateway no arquivo versionado
.codex/config.toml. - Cada engenheiro recebe uma chave pessoal através do gerenciador corporativo de secrets (
OFOX_API_KEY). - Toda a equipe usa um único ponto de roteamento com billing compartilhado, independentemente de o desenvolvedor estar trabalhando com
openai/gpt-5.5ouanthropic/claude-opus-4.8.
9. Nível avançado: perfis para CI, trabalho local e review
9.1. Configuração de perfis de segurança especializados
Os perfis no Codex são armazenados como arquivos separados no diretório ~/.codex/ e ativados através da flag --profile. Isso elimina a necessidade de alterar arquivos de configuração globais.
Exemplo de configuração para auditoria automática em CI/CD:
9.2. Cenários práticos: auditoria isolada em CI e desenvolvimento local
Executar o comando codex --profile ci garante que o agente poderá revisar código e gerar relatórios, mas não terá capacidade técnica de fazer alterações não autorizadas em arquivos ou enviar dados para fora.
Para desenvolvimento diário, use um perfil local com sandbox_mode = "workspace-write", e para análise arquitetural complexa — codex --profile claude, que ativa o Claude Opus sem alterar as configurações globais do sistema.
10. Perguntas Frequentes (FAQ)
10.1. Compatibilidade de modelos e arquivos de configuração
❓ É possível usar os modelos originais do Claude no Codex CLI?
O Codex padrão funciona apenas com modelos OpenAI. No entanto, você pode conectar qualquer modelo Anthropic (por exemplo,anthropic/claude-opus-4.8) registrando um gateway de API compatível com OpenAI na seção[model_providers]e especificando-o no perfil.
❓ O Codex CLI lê o arquivo de memória CLAUDE.md?
Por padrão, o Codex procura porAGENTS.md. Para manter a compatibilidade sem duplicar informações, adicione à linhaproject_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]em~/.codex/config.toml.
❓ Como importar rapidamente configurações prontas do Claude Code?
Executecodexno diretório do projeto e rode o comando/import. O importador embutido migrará instruções, servidores MCP e comandos contextuais, além de gerar uma lista de itens que requerem atenção manual.
❓ Há diferenças entre os arquivos AGENTS.md e CLAUDE.md?
Sua funcionalidade é idêntica.AGENTS.mdé um padrão aberto multi-ferramenta para agentes de IA, enquantoCLAUDE.mdé o formato interno do Claude Code. O conteúdo de ambos os arquivos é interpretado igualmente.
10.2. Nuances técnicas de hooks, MCP e subagentes
❓ O Codex CLI suporta ciclos de vida de hooks como o Claude Code?
Sim, os hooks estão habilitados por padrão. São suportados os eventosPreToolUse,PostToolUse,SessionStart,Stop,PreCompactePostCompact. O único hook sem análogo direto éConfigChange.
❓ Claude Code e Codex podem usar simultaneamente os mesmos servidores MCP?
Sim. A mecânica do protocolo MCP é a mesma. Muda apenas a forma de registro: em vez da estrutura JSON em.mcp.json, os parâmetros são declarados como tabelas TOML emconfig.toml.
❓ Preciso reescrever o código dos subagentes durante a migração?
Não, as próprias instruções de sistema são migradas sem alterações. É preciso apenas mudar o wrapper: mover o texto dos arquivos Markdown.claude/agents/*.mdpara o parâmetrodeveloper_instructionsnos arquivos correspondentes.codex/agents/*.toml.