Como migrar do Claude Code para o Codex em 2026: guia passo a passo

Documentação da Ailoot: API, chaves e configuração.

Porque é que a ferramenta Codex Migration é necessária?#

A OpenAI adicionou esta funcionalidade ao Codex no início de junho de 2026. O changelog oficial descreve-a sucintamente:

Por outras palavras: quando inicia a aplicação Codex pela primeira vez, ou nas definições de um cliente que já esteja em execução, é iniciado um assistente que lê as configurações locais de outro agente. Atualmente, são suportados o Claude Code e o Claude Cowork.

É claro porque é que a OpenAI está a fazer isto. Depois do lançamento do Sites e da atualização da aplicação Codex em maio–junho de 2026, o Codex passou a ter tudo aquilo em que o Claude Code levava anteriormente vantagem sobre a OpenAI: um terminal, plugins, sessões longas e orquestração. A migração elimina o último obstáculo para as equipas que já integraram o Claude Code na sua stack: «as definições suportadas podem ser importadas e verificadas pelo inventário original».

A razão pela qual poderá precisar desta ferramenta é menos óbvia. Comparei os dois lado a lado no guia Codex vs. Claude Code: o Claude continua a ser melhor em discussões arquiteturais longas e no Plan Mode, enquanto o Codex é mais rápido em tarefas autónomas e PR paralelos. Se decidiu mudar completamente, continue a ler. Se está a considerar uma combinação, os padrões de colaboração poderão ser mais relevantes.

O que é que a ferramenta Migration transfere automaticamente?#

Vou percorrer os grupos e explicar exatamente o que acontece a cada parte de ~/.claude.

1. Instruções e contexto. Os ficheiros CLAUDE.md — o ficheiro global em ~/.claude/ e os ficheiros de projeto nos repositórios — são convertidos para o formato AGENTS.md. O ficheiro global fica em ~/.codex/AGENTS.md; os ficheiros de projeto permanecem na raiz do repositório e nas pastas subordinadas. O formato AGENTS.md é essencialmente o mesmo tipo de ficheiro Markdown com regras; as diferenças são sobretudo cosméticas — nomes das secções e algumas diretivas específicas. Expliquei o que é AGENTS.md e porque é que o Codex precisa dele.

2. Skills. A pasta ~/.claude/skills/ é analisada na íntegra; cada skill é adaptada à estrutura do Codex e colocada em $HOME/.agents/skills. As skills de projeto da pasta .claude/skills/ de um repositório são movidas para .agents/skills. O formato SKILL.md com frontmatter é transferido quase tal e qual. Se uma skill utilizar acionadores específicos do Claude, é assinalada para revisão.

3. Servidores MCP. A configuração .mcp.json (tanto global como ao nível do projeto) é importada para o formato do Codex. Os nomes dos servidores, os comandos de arranque e os caminhos são preservados. O que não é transferido: tokens e variáveis de ambiente. Por motivos de segurança, o Codex voltará a pedir-lhe as chaves API e as palavras-passe, para que não sejam expostas durante a migração. É uma tarefa única: abra a secção MCP na aplicação Codex e introduza os tokens que já tem no seu gestor de palavras-passe.

4. Hooks. Este é o grupo mais complicado. Os hooks com lógica determinística (bloquear rm -rf, alertar para caminhos que pareçam conter credenciais, registar provas) são transferidos na íntegra. Os hooks com acionadores sem equivalente no Codex (por exemplo, eventos específicos do ciclo de vida do Claude Code) são assinalados para «revisão manual» e não são ativados automaticamente. Expliquei em detalhe como funcionam os hooks no Claude Code, como referência — o Codex tem menos tipos.

5. Histórico de sessões. Até aos últimos 30 dias de atividade do Claude Code são importados como referência. Isto não significa «continuar exatamente de onde ficou», mas as suas conversas anteriores estarão visíveis no Codex, para que possa recuperar rapidamente o contexto do projeto sem voltar a explicar tudo.

A ferramenta Migration não distingue entre ficheiros ativos e artefactos experimentais — transfere tudo. Depois da migração, é útil eliminar manualmente tudo o que não utiliza há seis meses.

O que NÃO é transferido, e porquê?#

Vou percorrer cada grupo na perspetiva de «o que fazer depois da migração».

Tokens MCP e chaves API. Esta é a parte mais previsível. Depois da análise, o Codex apresenta uma lista de todos os servidores MCP que encontrou no Claude. Pedirá chaves e tokens para cada um. O mais fácil é ter o gestor de palavras-passe à mão e percorrer todos os servidores de uma só vez. Depois disso, o MCP funciona da mesma forma no Codex e no Claude Code. Consulte a documentação do servidor MCP que escolheu para verificar o comando e os parâmetros de ligação.

Comandos slash /name. No Claude Code, está habituado a chamar uma skill com /skill-name. No Codex, a invocação canónica é diferente: $skill-name. Um erro de migração comum é considerar os comandos /name como prova de que as skills foram carregadas.

Depois da migração, teste algumas skills importantes com $skill-name no Codex. Se funcionarem, a migração foi realmente bem-sucedida. Não confie na caixa «skills migrated» do assistente — confirme invocando-as.

Hooks sem equivalente no Codex. Se tinha um hook para eventos específicos do Claude Code — por exemplo, em pre-tool-use para uma determinada combinação de ferramentas — esse acionador poderá não existir no Codex. A ferramenta Migration vai assinalá-los e deixá-los inativos. Terá de decidir se os reescreve para obter um equivalente no Codex, se os elimina ou se os mantém no Claude Code (caso o esteja a executar em paralelo). Uma boa regra: transfira apenas hooks determinísticos; qualquer outro tipo é uma razão para não duplicar a escada na nova ferramenta.

Fluxos de trabalho de equipa baseados em subagentes. Expliquei o que são subagentes no Claude Code e como utilizar subagentes aninhados. No Codex, os subagentes são organizados através de perfis e funções (ver abaixo). Se tinha no Claude um fluxo complexo com vários subagentes em cadeia, terá de o reescrever em torno do conceito de perfil do Codex. A ferramenta Migration assinala estas configurações como «exigem reformulação arquitetural».

Ficheiros CLAUDE.md extensos e específicos do Claude. Se um ficheiro tiver crescido até às 2 000–3 000 linhas, com secções para cada projeto, o Codex poderá aceitá-lo, mas é uma má prática. O AGENTS.md foi concebido para ser compacto e distribuído: regras globais em ~/.codex/AGENTS.md, regras específicas do projeto na raiz do repositório e substituições específicas nas pastas subordinadas. Depois da migração, não deixe o CLAUDE.md como um «ficheiro de instruções gigante»; divida-o por níveis. Expliquei como configurar corretamente o CLAUDE.md; a mesma abordagem aplica-se ao AGENTS.md.

Passo a passo: 4 ações na aplicação Codex#

Segue-se a lista de passos concreta.

1. Passo 1: Atualize a aplicação Codex para a versão 26.608 ou posterior

   A ferramenta Migration surgiu na versão 26.608 (lançada a 9 de junho de 2026). No macOS, abra a aplicação Codex e procure atualizações. Faça o mesmo no Windows. Se executar o Codex CLI, confirme que é compatível com a aplicação atual. Sem a versão mais recente, a opção «Import other agent setup» não aparecerá em Settings.

2. Passo 2: Inicie a importação em Settings

   Na aplicação Codex, abra Settings e procure «Import other agent setup». Se acabou de instalar a aplicação Codex, o assistente irá propor a migração durante a configuração inicial. Depois de iniciado, o assistente analisa o sistema de ficheiros: ~/.claude/ e os repositórios que contêm CLAUDE.md ou .claude/. A análise demora entre 30 segundos e vários minutos, consoante o número de ficheiros.

3. Passo 3: Confirme o plano de migração

   Depois da análise, o Codex apresenta um inventário: quantas skills foram encontradas, quantos servidores MCP, quantos ficheiros CLAUDE.md, que hooks são elegíveis para migração e quantos dias de histórico de sessões estão disponíveis. Pode desmarcar qualquer grupo que não queira transferir. Por predefinição, está selecionado tudo o que o Codex considera seguro importar.

4. Passo 4: Aguarde pela conclusão e introduza os tokens

   A importação demora 1–5 minutos. Quando terminar, o Codex abrirá uma janela de seguimento: «eis o que não consegui transferir automaticamente; verifique manualmente». Normalmente, trata-se de uma lista de servidores MCP que precisam de tokens. Abra o gestor de palavras-passe e introduza as chaves no formulário do Codex. Depois disso, a parte principal da migração estará concluída.

Em seguida, verifique o resultado. Abra um projeto em que costumava trabalhar no Claude Code e confirme:

• cat ~/.codex/AGENTS.md — as regras globais estão lá?
• Execute uma skill qualquer: $skill-name. Deve carregar.
• Abra .mcp.json no projeto e confirme que os servidores necessários estão em execução.
• Inicie uma conversa que reflita a sua forma habitual de trabalhar. O Codex mostrará os hooks importados que não consegue utilizar; são itens concretos do inventário para tratar manualmente; não existe uma parcela fixa estabelecida.

Hooks e subagentes: equivalentes no Codex e o que reescrever#

Hooks. No Claude Code, pode associar um comando shell a cada evento do ciclo de vida (pre-tool-use, post-tool-use, on-error, on-context-load, etc.). O Codex dispõe de um conjunto mais reduzido de eventos: pode verificar antes da execução, registar provas e bloquear comandos perigosos. Se tinha um hook pre-tool-use que filtrava uma combinação específica, no Codex terá de o integrar numa verificação geral anterior à execução ou eliminá-lo. Expliquei em detalhe a arquitetura dos hooks do Claude Code; se os usava extensivamente, liste cada acionador e efeito exigido, identifique equivalente suportado e verifique antes de ativar.

Subagentes. No Claude Code, um subagente é um contexto separado com o seu próprio prompt de sistema, iniciado através de um /command ou a partir da conversa principal. O Codex tem um conceito semelhante nos perfis: pode definir um perfil com um conjunto específico de skills, permissões e política de aprovação. Os perfis resolvem aproximadamente o mesmo problema — isolar o contexto para uma determinada categoria de tarefas — mas através das definições, em vez da invocação explícita de um agente.

O que isto significa na prática:

• Se tinha um subagente «security-reviewer» com o seu próprio prompt, crie no Codex um perfil security-review com as permissões necessárias e um esforço de raciocínio superior.
• Se tinha um subagente «feature-developer», trata-se simplesmente de um perfil de trabalho por predefinição; não é preciso fazer nada de especial.
• Se utilizava subagentes aninhados, isso não funcionará da mesma forma no Codex; repense o processo com uma cadeia de perfis ou skills explícitas.

A ferramenta Migration tentará criar perfis com os nomes dos seus subagentes e assinalará os acionadores que não foram transferidos. O esforço depende de funções, acionadores, permissões e dependências; teste cada fluxo necessário antes de o considerar migrado.

Quando mudar completamente e quando manter as duas ferramentas#

Um critério simples para decidir:

Mudar completamente para o Codex faz sentido se:

• Se dedica sobretudo a PR autónomos e tarefas paralelas.
• O seu fluxo de trabalho com o GitHub está profundamente integrado e o Codex Cloud Agent trata de 80% do trabalho.
• Não passa muito tempo em discussões arquiteturais e no Plan Mode.
• Quer pagar por uma ferramenta em vez de duas.

Manter Claude Code e Codex em conjunto se:

• Utiliza regularmente o Plan Mode para decisões arquiteturais longas.
• Precisa de trabalho paralelo: o Codex trabalha na cloud numa tarefa enquanto o Claude Code mantém o contexto de outra.
• Faz muitos hacks pontuais e microprojetos para os quais o Plan Mode é excessivo.
• Tem um fluxo complexo de subagentes que não pode ser reescrito numa noite.

Pessoalmente, utilizo ambos: o Claude Code mantém a conversa longa, enquanto o Codex trata de tarefas como «corrigir N bugs em paralelo» ou «rever um PR». Expliquei melhor como isto funciona no guia para trabalhar com Claude Code e Codex em conjunto.

A principal coisa que diria sobre a migração é esta: a ferramenta Migration elimina o obstáculo técnico à mudança, mas não responde à questão de saber se precisa de mudar. Primeiro, decida que tipo de trabalho faz. Depois, escolha a ferramenta.

Se precisar de acesso a redes neuronais através da Ailoot, consulte a Ailoot.