Como Migrar do Claude Code para o Codex

Migrar do Claude Code para o Codex não precisa significar reconstruir meses de configuração. O Codex já oferece um importador para trazer itens compatíveis do Claude Code, como instruções, configurações, skills, plugins, conexões MCP, memórias e conversas recentes. O ponto crítico é entender que importar não é o mesmo que validar.

Uma migração segura tem três etapas: inventariar o ambiente atual, importar somente o que faz sentido e testar cada camada no novo contexto. Este guia mostra como fazer isso sem apagar sua estrutura anterior nem colocar projetos importantes em risco.

Resumo rápido: use Settings > Import no aplicativo do Codex ou o comando /import no Codex CLI. Faça primeiro uma importação controlada, revise o AGENTS.md, revalide credenciais e execute um projeto pequeno antes de adotar o novo fluxo em produção.

O que muda ao sair do Claude Code para o Codex

Claude Code e Codex trabalham no terminal, leem repositórios, editam arquivos e executam comandos. Apesar dessa proximidade, cada ferramenta possui sua própria configuração, convenções e forma de organizar instruções.

Na prática, a migração envolve quatro camadas:

Camada	No ambiente do Claude	No Codex	O que revisar
Instruções	`CLAUDE.md` e regras relacionadas	`AGENTS.md`	Escopo, precedência, caminhos e regras duplicadas
Configuração	`settings.json` e preferências	`config.toml`	Permissões, modelo, terminal e comportamento
Capacidades	Skills, plugins, MCPs, hooks e comandos	Recursos compatíveis importados	Dependências, autenticação e disponibilidade
Histórico	Memórias e conversas	Memórias e chats importados	Relevância, privacidade e limite do importador

Essa tradução automática economiza trabalho, mas não elimina a revisão humana. Uma regra válida no Claude pode apontar para um comando que não existe no novo ambiente. Um MCP pode aparecer configurado, mas continuar desconectado por falta de autenticação. Um hook pode depender de uma variável local que não foi levada junto.

O que o importador oficial consegue trazer

Segundo a documentação oficial de importação do Codex, o fluxo atual reconhece configurações de ferramentas compatíveis e permite selecionar o que será trazido. Para o Claude Code, isso pode incluir:

arquivos de instrução convertidos para o padrão AGENTS.md;
configurações compatíveis de settings.json para config.toml;
skills e plugins;
pastas de projetos;
memórias do Claude Code;
conversas recentes;
servidores MCP;
hooks;
comandos personalizados;
subagentes.

O importador não altera a instalação anterior. Isso permite testar o Codex enquanto o Claude Code permanece disponível, o que reduz o risco de uma troca abrupta.

No Codex CLI, a documentação consultada para este artigo informa importação de até 50 conversas dos últimos 30 dias. Como limites de produto podem mudar, confirme a informação na documentação antes de uma migração extensa.

Antes de importar: faça um inventário de 15 minutos

Não comece apertando “importar tudo”. Primeiro descubra o que sustenta seu fluxo atual.

Crie uma lista com:

projetos realmente ativos;
arquivos de instrução globais e por repositório;
skills usadas no último mês;
plugins e MCPs essenciais;
hooks que executam comandos automaticamente;
variáveis de ambiente e logins necessários;
comandos personalizados que a equipe conhece;
memórias que ainda influenciam o trabalho;
tarefas que dependem de permissões especiais;
integrações que podem gerar custo ou modificar sistemas externos.

Esse inventário separa ativos úteis de configuração acumulada. Importar dez plugins esquecidos aumenta a superfície de erro sem gerar produtividade.

Também escolha um projeto piloto. O ideal é um repositório pequeno, com testes ou uma forma simples de verificar o resultado. Não use como primeiro teste um sistema de pagamento, banco de produção, autenticação ou automação que envia mensagens.

Opção 1: migrar pelo aplicativo do Codex

O aplicativo oferece o caminho mais visual para revisar a origem e os itens encontrados.

Passo 1: abra as configurações

No Codex, acesse Settings e procure a área Import. Selecione Claude Code como origem quando ela for detectada.

Passo 2: examine a prévia

O importador apresenta as categorias disponíveis. Compare essa lista com o inventário feito antes. Se um item crítico não aparecer, não presuma que ele será recriado depois.

Passo 3: selecione somente o necessário

Para o primeiro ciclo, priorize:

um projeto piloto;
instruções diretamente relacionadas a ele;
uma ou duas skills conhecidas;
os MCPs indispensáveis;
poucas conversas que contenham decisões ainda válidas.

Passo 4: conclua e revise os avisos

Itens que dependem de login, permissões ou caminhos específicos podem exigir atenção. Anote cada aviso em vez de clicar rapidamente até o final.

Passo 5: abra o projeto sem alterar nada

Peça ao Codex para mapear a estrutura, localizar instruções e explicar como pretende executar uma tarefa simples. Essa leitura inicial revela caminhos quebrados e regras conflitantes antes de qualquer edição.

Opção 2: migrar pelo Codex CLI

Para quem já trabalha no terminal, o caminho oficial é abrir o Codex CLI e executar:

/import

O assistente conduz a seleção da origem e dos elementos suportados. A importação pelo CLI é útil quando o trabalho já está concentrado em repositórios locais e a equipe prefere verificar arquivos diretamente.

Há situações em que o comando pode não estar disponível, como durante uma tarefa em execução ou em determinados contextos remotos. Se isso acontecer, finalize o trabalho atual com segurança e tente novamente em uma sessão local apropriada. Não interrompa uma execução importante apenas para migrar configurações.

Como revisar o novo AGENTS.md

O AGENTS.md é uma das partes mais importantes da migração. Ele orienta como o Codex deve trabalhar dentro de um diretório. A documentação oficial sobre instruções explica como arquivos em diferentes níveis podem participar do contexto.

Faça uma revisão linha por linha e procure:

caminhos absolutos de outra máquina;
menções a ferramentas exclusivas do Claude;
comandos inexistentes no novo ambiente;
regras repetidas ou contraditórias;
autorizações amplas demais;
instruções que mandam publicar, excluir ou enviar algo sem aprovação;
segredos copiados para texto;
referências a documentos que não foram importados.

Uma boa regra deve ser específica e verificável. “Faça tudo certo” não ajuda. “Antes de publicar, execute os testes X e confirme a URL de preview” descreve uma condição objetiva.

Também mantenha instruções do projeto perto do projeto. Regras globais enormes tendem a misturar clientes, tecnologias e processos que não deveriam aparecer em todas as tarefas.

MCPs, plugins e skills: configuração não é conexão

MCPs permitem que o agente acesse ferramentas e fontes externas. Plugins e skills adicionam processos especializados. Durante a migração, parte dessa configuração pode ser reconhecida, mas três verificações continuam obrigatórias:

1. Autenticação

Tokens, logins OAuth e chaves podem não acompanhar a configuração. Reautorize pela rota oficial, sem copiar segredo para prompts, documentação ou repositórios.

2. Disponibilidade

Uma skill pode ter sido importada, mas depender de um binário ausente. Um plugin pode existir no catálogo, porém não estar instalado ou ativo. Um servidor MCP pode apontar para um comando local que mudou de caminho.

3. Permissões

Confirme o que cada integração consegue ler e alterar. Comece com menor privilégio e amplie somente quando a tarefa exigir.

Antes de conectar serviços reais, teste uma operação somente de leitura. Depois, faça uma alteração reversível em um ambiente controlado. Somente então use o recurso em um processo importante.

Memórias e conversas: leve decisões, não ruído

Histórico pode acelerar a transição, mas também transportar premissas antigas. Uma conversa de seis meses atrás pode citar um domínio, preço ou arquitetura que já mudou.

Ao importar conversas:

priorize decisões ainda vigentes;
descarte bate-papos exploratórios sem valor futuro;
revise dados pessoais ou confidenciais;
não trate uma resposta antiga como documentação oficial;
transforme aprendizados recorrentes em instruções curtas e atuais.

O objetivo não é reproduzir todo o passado. É preservar o contexto que reduz retrabalho hoje.

Checklist de validação após a importação

Use esta sequência no projeto piloto:

[ ] O Codex encontra o repositório correto?
[ ] O AGENTS.md carregado é o esperado?
[ ] Os caminhos citados existem?
[ ] O ambiente instala e executa sem erro?
[ ] Os testes atuais passam antes de qualquer mudança?
[ ] Skills importantes aparecem e abrem suas instruções?
[ ] MCPs essenciais conectam com o escopo correto?
[ ] Hooks foram revisados antes de executar?
[ ] Nenhum segredo apareceu em arquivo versionado?
[ ] Uma tarefa simples produziu alteração compreensível?
[ ] O diff foi revisado?
[ ] O resultado foi testado de forma concreta?

Se algum item falhar, corrija a camada correspondente antes de importar mais projetos.

Plano de migração em três ondas

Para equipes ou agências, dividir a adoção evita paralisar a operação.

Onda 1: ambiente pessoal controlado

Um responsável importa um projeto pequeno e documenta diferenças. O objetivo é descobrir conflitos de instrução, autenticação e terminal.

Onda 2: projetos internos

Leve ferramentas sem impacto direto no cliente. Padronize AGENTS.md, critérios de teste, revisão de diff e regras de permissão.

Onda 3: projetos de clientes

Migre um por vez, com responsável, backup, checklist e evidência de QA. Nunca misture instruções ou credenciais entre clientes.

Essa progressão cria um padrão repetível. O ganho não está apenas em trocar de ferramenta, mas em tornar o processo mais auditável.

Erros comuns ao migrar do Claude para o Codex

Importar tudo sem seleção

Configuração antiga não é patrimônio por definição. Leve o que tem uso comprovado.

Considerar a importação concluída quando ela termina

O botão concluído confirma cópia, não funcionamento. A migração só termina depois do teste.

Apagar o ambiente anterior cedo demais

Como a importação preserva a origem, mantenha o Claude Code disponível durante o período de comparação.

Colocar credenciais em AGENTS.md

Instruções devem explicar onde e como obter acesso seguro, nunca armazenar o segredo.

Testar primeiro em produção

Use projeto piloto, branch ou ambiente de preview. Mudanças de agente não justificam pular controles existentes.

Comparar apenas a resposta escrita

Compare o processo: arquivos alterados, testes executados, tempo de revisão, clareza do diff e quantidade de correções humanas.

Vale a pena migrar?

Vale testar o Codex quando você quer integrar melhor tarefas locais, aplicativo, IDE e execuções em nuvem; padronizar instruções com AGENTS.md; ou transformar pedidos em alterações verificáveis dentro do projeto.

Mas a decisão não precisa ser “tudo ou nada”. Você pode manter o Claude Code em parte da operação enquanto valida o Codex em projetos selecionados. A métrica correta é o resultado: menos retrabalho, maior rastreabilidade e qualidade consistente.

Próximo passo recomendado

Escolha um projeto sem risco alto, faça o inventário, execute o importador oficial e valide o checklist completo. Depois registre o que funcionou em um AGENTS.md enxuto. Só então replique o processo.

Para entender como Codex e ChatGPT podem dividir o trabalho na empresa, consulte o guia /blog/chatgpt-ou-codex-qual-usar-empresa/. Se você ainda está conhecendo a ferramenta, comece pelo artigo /blog/o-que-e-openai-codex-como-usar/.

Também vale comparar este processo com nosso conteúdo sobre plugin do OpenAI Codex no Claude Code e com o guia de API da OpenAI para separar interface de agente, integração e automação.

Perguntas frequentes

O Codex importa automaticamente tudo do Claude Code? +

O fluxo importa itens suportados e permite escolher o que trazer. Integrações, plugins e conexões com autenticação própria podem exigir configuração manual depois da importação.

A importação apaga minha configuração do Claude? +

Não. A documentação oficial informa que a configuração existente do outro agente permanece inalterada.

O CLAUDE.md vira AGENTS.md? +

Arquivos de instrução suportados são levados para o padrão AGENTS.md. Mesmo assim, é importante revisar precedência, caminhos e regras específicas do novo ambiente.

Quantas conversas o Codex CLI consegue importar? +

Na documentação consultada em 29 de agosto de 2026, o CLI importa até 50 conversas dos últimos 30 dias. Esse limite deve ser conferido novamente antes de executar a migração.

MCPs e plugins continuam funcionando após a migração? +

A configuração compatível pode ser importada, mas autenticação, variáveis de ambiente, cabeçalhos, transportes e permissões precisam ser revisados antes do uso.

Como migrar do Claude Code para o Codex sem perder seu trabalho