Como migrar do Claude Code para o Codex: guia prático

Atualização (9 de novembro de 2026): Claude Fable 5.2 e Mythos 5.2 foram lançados - preços, acesso e benchmarks no meu guia do Claude Fable 5.2.

👁 112 leituras

Em 3 de novembro, assinei o plano mais caro do ChatGPT, o Pro 500, e logo surgiu um problema. Nos últimos meses, eu vinha fazendo todo o trabalho nos meus blogs, videoclipes e aplicativos com o Claude Code. Já eram centenas de anotações sobre projetos, seis skills próprios, arquivos CLAUDE.md em várias pastas e servidores MCP conectados. Na primeira inicialização, o Codex não sabia nada disso. Escrevia travessões, embora eu use apenas hífen há anos, e perguntava coisas que o Claude já sabia de cor.

A migração levou uma tarde. O mais importante não foi simplesmente copiar os arquivos, mas entender onde o Codex procura instruções. A seguir, explico o processo completo, incluindo um erro que encontrei no importador oficial e o script que uso agora.

Dois aplicativos, nomes diferentes

Claude Code e Codex fazem coisas parecidas: leem seus arquivos, executam comandos e escrevem código ou textos. Mas usam caminhos diferentes. O Claude procura regras em CLAUDE.md; o Codex, em AGENTS.md. O Claude guarda skills em ~/.claude/skills; o Codex, em ~/.agents/skills. Os servidores MCP são registrados pelo Claude em JSON e pelo Codex em um arquivo TOML. Se você ainda não sabe como essas ferramentas diferem no dia a dia, comece pelo artigo Codex ou Claude Code. Aqui, parto do princípio de que você usa os dois e quer que se comportem da mesma forma.

O Codex procura AGENTS.md em dois lugares. O primeiro é a pasta pessoal do Codex, ~/.codex/AGENTS.md, que vale para todas as conversas. O segundo é o projeto: o Codex percorre o repositório desde a pasta raiz até a pasta atual e considera no máximo um arquivo em cada diretório. Os arquivos mais próximos da pasta atual são aplicados por último e, por isso, substituem regras mais gerais. O limite padrão é de 32 KiB de instruções; o Codex corta o que ultrapassar sem avisar.

Etapa 1: regras no AGENTS.md global

Eu não tinha um CLAUDE.md global, porque minhas regras estavam guardadas como anotações separadas na memória do Claude Code: escrever em polonês, usar apenas hífen, incluir links no fim, não inventar números e não publicar na loja sem minha autorização. Reuni as instruções essenciais em um arquivo ~/.codex/AGENTS.md de 60 linhas. É melhor registrar o que realmente importa do que colar tudo: instruções mais curtas consomem menos contexto em cada mensagem.

No fim do arquivo, acrescentei uma seção que fez a maior diferença. Indiquei a pasta de memória do Claude Code como uma base de conhecimento somente para leitura. Não copio os arquivos; assim, o Codex sempre consulta a versão atual das anotações que o Claude salva continuamente.

## Conhecimento dos projetos
O conhecimento completo dos projetos está na memória do Claude Code (somente para leitura):
C:\Users\ty\.claude\projects\<nome-do-projeto>\memory\
- Comece por MEMORY.md (índice) e depois consulte os arquivos específicos.
- Para tarefas relacionadas a um projeto, pesquise primeiro nesta pasta.

Etapa 2: reutilize CLAUDE.md nos projetos

Não é preciso criar outro arquivo para projetos que já têm seu próprio CLAUDE.md. Basta adicionar duas linhas a ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]
project_doc_max_bytes = 65536

A primeira linha instrui o Codex a ler CLAUDE.md quando não houver AGENTS.md. A segunda aumenta o limite de 32 KiB para 64 KiB, porque alguns dos meus arquivos de projeto são longos. A OpenAI também usa o valor 65536 em um exemplo da documentação.

Etapa 3: coloque as skills em ~/.agents/skills

Uma skill é uma pasta com um arquivo SKILL.md; ela também pode conter scripts e materiais de apoio. O formato é compartilhado, então as skills do Claude funcionam no Codex sem modificações. No cabeçalho do SKILL.md, o Codex exige dois campos: name e description. A descrição determina quando o modelo usará a skill por conta própria, por isso vale a pena explicar claramente para que ela serve.

Primeiro, copiei as skills para ~/.codex/skills, seguindo recomendações de guias mais antigos. O Codex as carregou, mas a documentação atual indica ~/.agents/skills como pasta para skills pessoais, então movi tudo para lá. Para chamar uma skill manualmente, digite $ seguido do nome ou use /skills. O modelo também pode selecioná-la automaticamente quando a tarefa corresponder à descrição.

Um detalhe surpreendente quando há muitas skills: a lista com as descrições ocupa no máximo 2% da janela de contexto. Quando a quantidade é grande, o Codex encurta as descrições e pode ignorar algumas, com um aviso. O arquivo SKILL.md completo só é carregado quando a skill é usada.

Script pronto: synchronizuj-skille.py

Como continuo aprimorando as skills do Claude, copiá-las uma única vez não era suficiente. Escrevi um script para transferi-las com um comando, sem mexer nas skills que criei manualmente no Codex. Ele mantém um registro do que copiou e só substitui essas pastas. Também verifica se cada SKILL.md tem os campos name e description.

Baixe synchronizuj-skille.py (Python 3.8 ou superior, sem bibliotecas adicionais, para Windows, macOS e Linux)

Antes de publicar, testei o script em uma pasta limpa com cinco situações: simulação sem gravação, primeira cópia, nova execução depois de alterar uma skill, skill sem cabeçalho e pasta de origem inexistente. Uma skill com o mesmo nome que já estava no Codex não foi alterada. A skill sem cabeçalho foi copiada com um aviso e código de saída 1. Caracteres poloneses nos nomes e nas descrições foram processados sem problemas.

Como usar:

python synchronizuj-skille.py --na-sucho    # mostre o plano sem gravar nada
python synchronizuj-skille.py               # ~/.claude/skills -> ~/.agents/skills
python synchronizuj-skille.py --zrodlo D:/minhas-skills --zrodlo ~/.claude/skills
python synchronizuj-skille.py --cel ./projeto/.agents/skills

Código completo:

"""Sincronização de skills do Claude Code para o Codex.

Copia pastas de skills (cada uma com um arquivo SKILL.md) do Claude Code para a
pasta em que o Codex procura skills do usuário. Padrões:
    origem: ~/.claude/skills
    destino: ~/.agents/skills

O script mantém um registro das skills copiadas (.synchronizuj-skille.json na
pasta de destino). Nas próximas execuções, substitui apenas essas skills e
preserva as criadas manualmente no Codex. Também verifica se o SKILL.md tem
os campos name e description, necessários para o Codex carregar a skill.

Uso:
    python synchronizuj-skille.py                    # pastas padrão
    python synchronizuj-skille.py --na-sucho         # apenas mostra o que faria
    python synchronizuj-skille.py --zrodlo D:/skills --zrodlo ~/.claude/skills
    python synchronizuj-skille.py --cel ./projeto/.agents/skills

Requer Python 3.8 ou superior, sem bibliotecas adicionais. Funciona no Windows,
macOS e Linux. Depois da sincronização, reinicie o Codex para carregar as skills.
"""
import argparse
import json
import re
import shutil
import sys
from pathlib import Path

REJESTR_PLIK = ".synchronizuj-skille.json"
POMIJAJ = shutil.ignore_patterns("__pycache__", ".git", "node_modules", ".DS_Store")


def sciezka(tekst):
    return Path(tekst).expanduser().resolve()


def sprawdz_frontmatter(skill_md):
    """Retorna os campos ausentes no cabeçalho do SKILL.md (lista vazia = tudo certo)."""
    tekst = skill_md.read_text(encoding="utf-8", errors="replace")
    m = re.match(r"^---\s*\n(.*?)\n---", tekst, re.S)
    if not m:
        return ["falta o cabeçalho --- no início do arquivo"]
    naglowek = m.group(1)
    return [f"falta o campo {pole}" for pole in ("name", "description")
            if not re.search(rf"^{pole}\s*:\s*\S", naglowek, re.M)]


def main():
    p = argparse.ArgumentParser(description="Copia skills do Claude Code para o Codex.")
    p.add_argument("--zrodlo", action="append", type=sciezka,
                   help="pasta com skills (pode ser indicada várias vezes); padrão: ~/.claude/skills")
    p.add_argument("--cel", type=sciezka, default=sciezka("~/.agents/skills"),
                   help="pasta de skills do Codex; padrão: ~/.agents/skills")
    p.add_argument("--na-sucho", action="store_true", help="não grava nada, apenas mostra o plano")
    a = p.parse_args()
    zrodla = a.zrodlo or [sciezka("~/.claude/skills")]

    rejestr_plik = a.cel / REJESTR_PLIK
    nasze = set()
    if rejestr_plik.exists():
        nasze = set(json.loads(rejestr_plik.read_text(encoding="utf-8")))

    skopiowane, pominiete, ostrzezenia = [], [], []
    for zrodlo in zrodla:
        if not zrodlo.is_dir():
            print(f"AUSENTE  {zrodlo} - pasta inexistente; ignorada")
            continue
        for skill in sorted(x for x in zrodlo.iterdir() if (x / "SKILL.md").is_file()):
            cel = a.cel / skill.name
            if skill.name in skopiowane:
                pominiete.append(skill.name)
                print(f"DUPLICADA {skill.name} - já copiada de uma origem anterior; ignorada")
                continue
            if cel.exists() and skill.name not in nossas:
                pominiete.append(skill.name)
                print(f"IGNORADA {skill.name} - já existe no destino e não foi copiada por este script")
                continue
            for brak in sprawdz_frontmatter(skill / "SKILL.md"):
                ostrzezenia.append(f"{skill.name}: {brak}")
            if not a.na_sucho:
                a.cel.mkdir(parents=True, exist_ok=True)
                if cel.exists():
                    shutil.rmtree(cel)
                shutil.copytree(skill, cel, ignore=POMIJAJ)
            skopiowane.append(skill.name)
            print(f"{'PLANO' if a.na_sucho else 'OK'}{' ' * (9 - len('PLANO' if a.na_sucho else 'OK'))}{skill.name}  <- {zrodlo}")

    if not a.na_sucho and skopiowane:
        rejestr_plik.write_text(json.dumps(sorted(nossas | set(skopiowane)), ensure_ascii=False, indent=1),
                                encoding="utf-8")

    print(f"\n{'Para copiar' if a.na_sucho else 'Copiadas'}: {len(skopiowane)}, ignoradas: {len(pominiete)}, destino: {a.cel}")
    for o in ostrzezenia:
        print(f"AVISO    {o} - o Codex exige os campos name e description no cabeçalho do SKILL.md")
    if skopiowane and not a.na_sucho:
        print("Reinicie o Codex para carregar as skills.")
    return 1 if ostrzezenia else 0


if __name__ == "__main__":
    if hasattr(sys.stdout, "reconfigure"):
        sys.stdout.reconfigure(encoding="utf-8")
    sys.exit(main())

Etapa 4: servidores MCP

Você pode adicionar servidores MCP com um único comando. Para um servidor acessível por URL, como acontece com a maioria dos serviços novos, use:

codex mcp add flashboards --url https://flashboards.yaroflasher.com/api/mcp
codex mcp login flashboards
codex mcp list

Quando adicionei o FlashBoards, o Codex abriu a página de autenticação OAuth no navegador, pois eu já estava conectado ao serviço. Para adicionar servidores executados localmente, use codex mcp add nome -- comando. Variáveis de ambiente podem ser informadas com --env antes do separador. As configurações ficam nas seções [mcp_servers.nome] de config.toml. Expliquei como criar um servidor no artigo Como criar um servidor MCP em 15 minutos.

O importador tem um erro; sessões antigas podem ficar de fora

O Codex tem um importador integrado. No aplicativo, a opção Importar fica nas configurações; por trás dela, funciona a skill migrate-to-codex, com os modos --scan-only, --plan e --dry-run. Testei no meu computador. A varredura encontrou seis skills e nada além delas: nenhum comando, subagente ou CLAUDE.md global. O importador não considera a memória dos projetos, que era justamente a parte mais valiosa para mim.

O modo --plan falhou na primeira skill com caracteres poloneses: UnicodeDecodeError: 'charmap' codec can't decode byte 0x98. O script lê os arquivos usando a codificação padrão do sistema; no Windows em polonês, ela é cp1250. Uma solução é executar o programa com a variável PYTHONUTF8=1 definida. Meu script lê todos os arquivos como UTF-8, então não tem esse problema.

O importador também pode transferir conversas dos últimos 30 dias como threads do Codex. Não fiz isso e não recomendo para sessões longas. Capturas de tela coladas em uma conversa são incluídas por inteiro na transcrição. Uma das minhas threads no Codex Desktop chegou a ocupar 33 GB, e o aplicativo tentou carregá-la na memória. É melhor começar no Codex com uma conversa nova, um bom AGENTS.md e acesso às anotações.

Como verificar se o Codex está vendo tudo

Para terminar, fiz quatro perguntas de verificação ao Codex pelo terminal: qual é a regra sobre travessões, quais skills ele encontra, o que aparece nas primeiras linhas do meu índice de anotações e se tem acesso às ferramentas do FlashBoards. Ele respondeu corretamente sobre a regra e as skills logo de início. Só conseguiu ler o arquivo de anotações com acesso total (-s danger-full-access), porque a sandbox do Windows apresentava um erro no modo somente para leitura. No aplicativo, o recurso funciona sem sinalizadores adicionais quando o acesso total está ativado.

Agora, o Codex tem as mesmas regras e o mesmo conhecimento que o Claude. Expliquei quanto custa cada mensagem e como evitar gastar o limite semanal no artigo [pwlink slug=”codex-ustawienia-limit”]Codex sem estourar o limite[/pwlink]. Depois, fiz o caminho inverso: o Claude Code passou a delegar tarefas ao Codex por meio do [pwlink slug=”wtyczka-codex-claude-code”]plugin oficial da OpenAI[/pwlink].

Fontes

• OpenAI, Custom instructions with AGENTS.md: https://learn.chatgpt.com/docs/agent-configuration/agents-md
• OpenAI, Agent Skills: https://learn.chatgpt.com/docs/build-skills
• OpenAI, Model Context Protocol in Codex CLI: https://learn.chatgpt.com/docs/extend/mcp?surface=cli
• OpenAI, Configuration Reference: https://learn.chatgpt.com/docs/config-file/config-reference
• Daniel Vaughan, The Codex CLI Agent Migration System: https://codex.danielvaughan.com/2026/05/13/codex-cli-agent-migration-system-import-claude-code-sessions-skills-config/
• Teste próprio de importação e configuração, Codex CLI 0.162.1, 3 de novembro de 2026

// continue lendoGPT-6 Sol ou Claude Opus 5.5: qual é melhor?BenchmarksClaude Opus 5.5 inventa números? Teste com armadilhaBenchmarksClaude Opus 5.5 na análise de dados: 43 de 44 acertosBenchmarks