# Migração do Claude Code para o Codex: como transferir CLAUDE.md, MCP, skills, comandos de barra e configurações

> Guia completo de migração do Claude Code para a CLI OpenAI Codex: transferência do CLAUDE.md para AGENTS.md, configuração de MCP, ajustes de permissões, hooks e preservação dos modelos Claude.

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 `/import` foi 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 possui `PreCompact`/`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.toml` versionado 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.5` e `gpt-5.4` como 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 `ConfigChange` ou estilos de formatação `outputStyle`.
- **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 `/import` no 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:
1. **Codex CLI versão 0.140.0 ou superior.** Verifique a versão com o comando `codex --version`.
2. **Projeto Claude Code preservado:** O diretório `.claude/` e o arquivo `CLAUDE.md` devem permanecer intactos até a verificação completa da migração.
3. **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.
4. **Permissões de escrita no diretório home:** O Codex lê parâmetros globais de `~/.codex/config.toml` a 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:

```mermaid
flowchart LR
    A["Аудит CLAUDE.md + settings.json"] --> B["Запуск codex /import"]
    B --> C["Аналіз звіту конфліктів"]
    C --> D["Ручне налаштування прав та хуків"]
    D --> E["Додавання model_provider для Claude"]
    E --> F["Тест із read-only профілем"]
```

---

## 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:

```bash
cd my-project
codex
# Всередині інтерактивної сесії Codex:
/import
```

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:

```toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]
project_doc_max_bytes = 32768
```

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`:

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}
```

Registro equivalente em `~/.codex/config.toml`:

```toml
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
```

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/`:

```toml
# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews diffs for correctness and style"
developer_instructions = """
Review the diff for correctness and style. Cite file and line for each issue found.
"""
```

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"`<br>`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"`<br>`sandbox_mode = "danger-full-access"` |

Configuração balanceada para desenvolvimento diário:

```toml
# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

### 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`.

```toml
# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use.sh"
```

> ⚠️ **Atenção:** O evento `ConfigChange` nã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`:

```toml
# ~/.codex/config.toml
[model_providers.ofox]
name = "ofox.ai gateway"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOX_API_KEY"
wire_api = "responses"
requires_openai_auth = false
```

### 6.2. Configuração wire_api=responses e seleção do perfil claude

Ao configurar o gateway, é crítico considerar dois parâmetros:
1. `wire_api = "responses"`: o suporte ao protocolo legado `chat` foi removido do Codex em fevereiro de 2026.
2. `requires_openai_auth = false`: desativa a validação do prefixo `sk-` no lado do cliente.

Crie um perfil para executar o Claude em `~/.codex/claude.config.toml`:

```toml
# ~/.codex/claude.config.toml
model = "anthropic/claude-opus-4.8"
model_provider = "ofox"
```

A execução do agente com este perfil é feita pelo comando:

```bash
codex --profile claude
```

---

## 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.5` ou `anthropic/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:

```toml
# ~/.codex/ci.config.toml
model = "gpt-5.5"
approval_policy = "never"
sandbox_mode = "read-only"
```

### 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 por `AGENTS.md`. Para manter a compatibilidade sem duplicar informações, adicione à linha `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]` em `~/.codex/config.toml`.

> ❓ **Como importar rapidamente configurações prontas do Claude Code?**  
> Execute `codex` no 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, enquanto `CLAUDE.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 eventos `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact` e `PostCompact`. 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 em `config.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/*.md` para o parâmetro `developer_instructions` nos arquivos correspondentes `.codex/agents/*.toml`.