English 中文 العربية 日本語 Português

Codex: Configuração e Personalização do Codex

Última atualização: 2026-08-31

O Codex oferece ricas opções de configuração — desde configurações básicas de API até políticas de aprovação avançadas e configurações de sandbox, tudo pode ser personalizado às suas necessidades.

📋 Pré-requisitos: Codex instalado e uso básico completado

1. O Que Você Vai Aprender

2. Localização dos Arquivos de Configuração

Tipo de Config Caminho Escopo
Config global ~/.codex/config.toml Todos os projetos
Config de auth ~/.codex/auth.json API Keys, etc.
Config de projeto .codex/config.toml Projeto atual
AGENTS.md AGENTS.md Regras e contexto do projeto

3. Configuração Global config.toml

(1) Configuração Básica

TOML 
# ~/.codex/config.toml

# Configurações de modelo
model = "gpt-5-codex"

# Política de aprovação: ask / approve / deny
approval_policy = "ask"

# Modo sandbox: readonly / workspace-write / full-access
sandbox_mode = "workspace-write"

# Tamanho da janela de contexto (tokens)
context_window = 128000

(2) Configuração de Auth auth.json

JSON 
{
  "OPENAI_API_KEY": "sk-your-api-key",
  "OPENAI_BASE_URL": "https://api.openai.com/v1"
}

▶ Exemplo 1: Configuração de Alice

TOML 
# Config global de Alice
model = "gpt-5-codex"
approval_policy = "ask"
sandbox_mode = "workspace-write"

# Prefixo de prompt personalizado
system_prompt_prefix = """
You are a senior full-stack engineer, proficient in TypeScript and Python.
Code style guidelines:
- Use type annotations
- Functions no longer than 50 lines
- Every function has a docstring
"""

4. Configuração Avançada

(1) Detalhes da Política de Aprovação

Política Comportamento Caso de Uso
ask Confirmar cada operação sensível Desenvolvimento diário (padrão)
approve Auto-aprovar todas as operações Cenários de automação confiáveis
deny Negar todas as operações sensíveis Revisão somente leitura
TOML 
# Configuração de aprovação por tipo de operação
[approval]
shell_commands = "ask"          # comandos shell precisam de confirmação
file_writes = "approve"         # escrita de arquivos auto-aprovada
network_access = "deny"         # negar acesso à rede
sensitive_paths = "ask"         # caminhos sensíveis precisam de confirmação

(2) Configuração do Sandbox

TOML 
# Modo sandbox
[sandbox]
mode = "workspace-write"        # Apenas permite escrita dentro do workspace
allowed_paths = ["src/", "test/"]  # Restringir caminhos graváveis
blocked_paths = [".env", "secrets/"]  # Caminhos de acesso bloqueados
network = false                 # Negar acesso à rede

(3) Gerenciamento de Contexto

TOML 
[context]
auto_compact = true             # Auto-comprimir contexto
compact_threshold = 0.8         # Acionar compressão aos 80% de uso
max_file_size = "100KB"         # Tamanho máximo de leitura de arquivo único
include_patterns = ["*.py", "*.ts", "*.js"]  # Padrões de arquivos incluídos
exclude_patterns = ["node_modules/", ".git/"]  # Padrões excluídos

5. Configuração em Nível de Projeto

Crie .codex/config.toml na raiz do projeto para sobrescrever configurações globais:

TOML 
# .codex/config.toml (nível de projeto)

# Modelo específico do projeto
model = "deepseek-coder"

# Política de aprovação específica do projeto
approval_policy = "approve"

# Sandbox específico do projeto
[sandbox]
allowed_paths = ["src/", "tests/"]
blocked_paths = ["production/", "secrets/"]

▶ Exemplo 2: Configuração de Projeto de Bob

TOML 
# Config do projeto frontend de Bob
# .codex/config.toml

model = "gpt-5-codex"
approval_policy = "ask"

[context]
include_patterns = ["*.tsx", "*.ts", "*.css"]
exclude_patterns = ["node_modules/", "dist/", ".next/"]

[sandbox]
allowed_paths = ["src/", "public/", "styles/"]
blocked_paths = [".env.local", ".env.production"]

6. Regras de Projeto AGENTS.md

O AGENTS.md é um arquivo de regras em nível de projeto colocado na raiz do projeto. O Codex o lê automaticamente:

MARKDOWN 
# AGENTS.md

## Regras do Projeto
- Usar TypeScript strict mode
- Todos os endpoints de API devem ter validação de entrada
- Cobertura de testes não inferior a 80%
- Executar npm run lint antes de commitar

## Estilo de Código
- Usar componentes funcionais
- Nomenclatura: camelCase
- Arquivos: kebab-case

## Operações Proibidas
- Não modificar arquivos .env
- Não deletar arquivos de teste
- Não instalar novas dependências (requer confirmação manual)

7. Configuração via Variáveis de Ambiente

Variável Descrição Exemplo
OPENAI_API_KEY Chave de API sk-xxx
OPENAI_BASE_URL Endpoint da API https://api.deepseek.com
CODEX_MODEL Modelo padrão gpt-5-codex
CODEX_SANDBOX Modo sandbox workspace-write
BASH 
# Sobrescrever temporariamente
CODEX_MODEL=deepseek-coder codex

8. Prioridade de Configuração

TEXT 📖 Somente leitura 
Argumentos CLI > Variáveis de ambiente > Config de projeto > Config global > Padrões

▶ Exemplo 3: Prioridade na Prática

BASH 
# Config global: model = "gpt-5-codex"
# Config de projeto: model = "deepseek-coder"
# Variável de ambiente: CODEX_MODEL="gpt-4o"

# Final: gpt-4o (variável de ambiente > config de projeto > config global)
CODEX_MODEL="gpt-4o" codex

# Argumento CLI tem prioridade mais alta
codex --model o3
# Final: o3

❓ Perguntas Frequentes

P: E se as configs de projeto e global conflitarem? R: A config de projeto tem prioridade. O Codex lê a config global primeiro, depois sobrescreve com a config de projeto.

P: Qual a diferença entre AGENTS.md e config.toml? R: config.toml é configuração técnica (modelo, sandbox, política de aprovação); AGENTS.md é regras em linguagem natural (estilo de código, operações proibidas, convenções do projeto). Eles se complementam.

P: Posso colocar API Keys na config de projeto? R: Não recomendado. API Keys devem ficar em ~/.codex/auth.json ou variáveis de ambiente para evitar vazamento em repositórios git.

P: Como vejo a configuração efetiva atual? R: Execute codex --show-config para ver a configuração completa mesclada.

P: E se eu configurar algo errado? R: Edite o arquivo de config diretamente, ou delete-o para restaurar os padrões. O Codex relê a configuração na próxima inicialização.

📖 Resumo

📝 Exercícios

  1. Básico (⭐): Crie um arquivo de config global e defina o modelo padrão e a política de aprovação.
  2. Intermediário (⭐⭐): Crie config em nível de projeto e AGENTS.md para seu projeto, definindo estilo de código e operações proibidas.
  3. Avançado (⭐⭐⭐): Desenhe um esquema de configuração multi-ambiente — DeepSeek para desenvolvimento, OpenAI para tarefas relacionadas a produção — com troca automática.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%