Codex CLI config.toml Deep Dive: 7 Setting Production 2026

Codex CLI config.toml là gì? Đây là file TOML mặc định ở ~/.codex/config.toml chứa toàn bộ cấu hình cho Codex CLI: model mặc định, approval policy, sandbox mode, MCP server, hooks lifecycle, profile per-context, web search behavior. Khác hẳn settings.json của Claude Code ở định dạng (TOML vs JSON) và cấu trúc section.

Bài này deep dive vào toàn bộ key documented trong file, dựa trên official Codex CLI config reference truy cập ngày 20/05/2026, kết hợp 1 tháng tinh chỉnh production trên ongboit codebase với 47 PR đo lường. Tập trung vào 7 setting OpenAI docs chưa highlight đủ mà power user thực sự cần.

Codex CLI config.toml Là Gì? Đường Dẫn Mặc Định Ở Đâu?

Codex CLI đọc 3 file chính: ~/.codex/config.toml (user-level global, áp dụng mọi project), .codex/config.toml trong root project (project-level override, chỉ load nếu repo được mark trusted), và requirements.toml (admin/managed config, ưu tiên cao nhất, dùng trong môi trường enterprise).

Khác với Claude Code dùng JSON cho ~/.claude/settings.json, Codex CLI dùng TOML. Lý do design choice: TOML có syntax sạch hơn cho config phức tạp với nhiều nested section, hỗ trợ comment inline, và xử lý array tốt hơn JSON cho danh sách dài như mcp_servers hay profiles. Convention naming theo OpenAI là snake_case (không camelCase như JSON Anthropic).

Biến môi trường CODEX_HOME override location mặc định nếu cần. Mình hay set CODEX_HOME=/mnt/data/.codex trên VPS để tách config khỏi home directory chính, dễ backup cùng project data. Detail xem ở config reference, để hiểu tool gốc đọc thêm bài Codex CLI là gì, cài đặt từ đầu qua hướng dẫn install Codex CLI 3 OS, hoặc so sánh tool với Claude Code vs Codex CLI.

~/.codex/config.toml Có Cấu Trúc Hoàn Chỉnh Ra Sao?

File config được tổ chức thành các section TOML top-level và nested table. Đây là structure đầy đủ của một config.toml production:

# ~/.codex/config.toml , Production-grade reference (ongboit setup)

# === Core model settings ===
model = "gpt-5.4"
model_context_window = 128000
model_reasoning_effort = "medium"   # minimal, low, medium, high, xhigh
model_reasoning_summary = "auto"    # auto, concise, detailed, none
model_verbosity = "medium"          # low, medium, high

# === Sandbox + security ===
sandbox_mode = "workspace-write"    # read-only, workspace-write, danger-full-access
approval_policy = "on-request"      # untrusted, on-request, never

# === Web search ===
web_search = "cached"               # disabled, cached, live

[tools.web_search]
context_size = "medium"
allowed_domains = ["developers.openai.com", "docs.anthropic.com"]

# === History persistence ===
[history]
persistence = "save-all"            # save-all, none
max_bytes = 104857600               # 100MB cap

# === Profile per context ===
profile = "default"

[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"

[profiles.quick]
model = "gpt-5-mini"
sandbox_mode = "read-only"

# === MCP servers ===
[mcp_servers.filesystem]
command = "npx @modelcontextprotocol/server-filesystem /workspace"
enabled = true
startup_timeout_sec = 10

[mcp_servers.github]
command = "npx @modelcontextprotocol/server-github"
enabled = true
enabled_tools = ["create_issue", "list_pulls"]

# === Shell environment policy ===
[shell_environment_policy]
inherit = "core"                    # all, core, none
set = { PATH = "/usr/local/bin:/usr/bin" }
exclude = ["AWS_*", "*SECRET*", "*TOKEN*"]

# === Hooks lifecycle ===
[[hooks.PreToolUse]]
matcher = "^Bash$"
type = "command"
command = '/usr/bin/python3 ~/.codex/hooks/audit_log.py'
timeout = 30

# === Observability ===
[otel]
exporter = "otlp-http"
environment = "prod"
log_user_prompt = false

Mỗi section có vai trò riêng: model settings điều khiển reasoning + verbosity, sandbox kiểm soát quyền filesystem + network, profiles cho phép switch context nhanh qua flag --profile X, mcp_servers khai báo integration tool, hooks gọi script trước/sau tool call, otel xuất metric ra OpenTelemetry collector.

AGENTS.md vs CLAUDE.md: Format Khác Nhau Như Thế Nào?

Codex CLI đọc file AGENTS.md ở root project làm “system prompt” mô tả project context, peer-level với CLAUDE.md của Claude Code. Tuy nhiên có 2 khác biệt lớn về format và scope:

Convention recommend cho dual-tool workflow (chi tiết tại bài Claude Code và Codex CLI cùng project): pick MỘT file làm source of truth (mình dùng CLAUDE.md ~1,200 dòng đầy đủ), file còn lại là adapter ngắn ~80 dòng point ngược về source. Tránh maintain song song để không bị drift sau 2-3 update.

Global vs Project-Level Config: Khi Nào Dùng Cái Nào?

Codex CLI hỗ trợ 2 layer config theo precedence từ thấp tới cao: ~/.codex/config.toml (global, mọi project đều load) → .codex/config.toml trong project root (override global) → requirements.toml (managed admin, override tất cả). Project-level chỉ được load nếu repo nằm trong trusted list của user.

Quy tắc placement đơn giản:

• Global ~/.codex/config.toml: dùng cho personal default , model preference, approval policy, MCP server cá nhân (GitHub auth của bạn), profile shortcuts. Setting machine-local như provider auth bắt buộc ở đây.
• Project-level .codex/config.toml: dùng cho team-shared config , sandbox mode chặt hơn cho repo nhạy cảm, MCP server riêng cho stack (n8n MCP cho project automation), profiles tuned cho codebase đó. Commit vào git cho team đồng bộ.
• requirements.toml: chỉ enterprise/admin dùng , managed hook policy, restricted features. Bỏ qua nếu solo dev.

Lưu ý quan trọng từ official docs: project-scoped .codex/config.toml KHÔNG override được machine-local provider, auth, hay notification settings, các setting đó luôn phải ở user level. Nếu muốn project A dùng API endpoint khác project B, dùng [profiles.X] trong ~/.codex/config.toml và switch qua codex --profile X thay vì project-level config.

7 Setting Hữu Ích Mà OpenAI Docs Chưa Highlight Đủ

OpenAI documentation cover từng setting nhưng không gom thành recipe production. Sau 1 tháng dùng thật trên ongboit, đây là 7 setting làm thay đổi workflow rõ rệt nhất:

1. model_reasoning_effort = "high" cho profile review. Setting này điều khiển compute spend cho reasoning step. Default medium phù hợp daily task. Với code review hoặc architecture analysis, set "high" hoặc "xhigh" qua profile riêng giúp output sâu hơn rõ. Cost token tăng 2-3 lần nhưng accuracy improvement đáng giá cho task quan trọng.

2. [shell_environment_policy] exclude = ["*SECRET*", "*TOKEN*", "*KEY*"]. Mặc định Codex inherit toàn bộ env var của shell, bao gồm secret token bạn export. Set inherit = "core" + exclude pattern để Codex KHÔNG nhìn thấy OPENAI_API_KEY, GITHUB_TOKEN, hay AWS credentials trong tool call. Security best practice production.

3. [history] persistence = "save-all" + max_bytes = 104857600. History persistence cho phép resume session sau crash hoặc reboot. Default đã enable nhưng max_bytes không cap, file history có thể phình lên vài GB. Set 100MB là sweet spot cho daily workflow.

4. [profiles.X] switching workflow. Tạo profile theo environment-based naming convention (dev / ci / prod / agent) thay vì project-based hay person-based, đây là pattern recommended 2026 theo Codex profiles deep dive. Tạo 3 profile cơ bản:

[profiles.review]      # PR review, high reasoning
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"
sandbox_mode = "read-only"

[profiles.refactor]    # Architecture refactor
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

[profiles.quick]       # Quick boilerplate
model = "gpt-5-mini"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Chạy codex --profile review để mở session với config tương ứng. Workflow nhanh hơn 30-40% so với edit config mỗi lần đổi task.

2 Recipe Profile Production Đáng Sao Chép Cho CI/CD Và Production Agent

Ngoài 3 profile workflow trên, đây là 2 recipe production-grade ongboit dùng cho CI/CD pipeline và long-running production agent (per Codex profiles 2026 reference):

# Recipe 1: CI/CD pipeline unattended runs
[profiles.ci]
model = "gpt-5.4"
sandbox_mode = "workspace-write"    # cần write để tạo PR
approval_policy = "untrusted"        # auto-approve mọi tool call vì không có human
model_reasoning_effort = "medium"
disable_response_storage = true      # không persist history trong CI

[profiles.ci.shell_environment_policy]
inherit = "none"                     # CI không cần shell env user
exclude = ["AWS_SECRET_*", "GH_TOKEN"]   # filter secret cụ thể

# Recipe 2: Read-only production agent (analytics, monitoring)
[profiles.prod-readonly]
model = "gpt-5.4-mini"               # nhẹ + rẻ cho long-running
sandbox_mode = "read-only"           # KHÔNG được sửa file production
approval_policy = "untrusted"        # tự chạy, không human gate
model_reasoning_effort = "low"       # task đơn giản

Recipe 1 chạy trong GitHub Actions hoặc GitLab CI: token auth qua secrets manager, no human in loop, output PR review hoặc test gen vào branch riêng. Recipe 2 cho production agent giám sát logs, generate weekly report, không touch code. Combo này cover 80% use case unattended. Cost cho 2 profile này: xem Codex CLI pricing + 6 mẹo tối ưu cost, recipe 2 dùng gpt-5.4-mini rẻ hơn 3x default.

Set Default Profile + Config Precedence Rule

Để 1 profile chạy mặc định không cần gõ --profile, thêm dòng profile = "dev" ở top-level config.toml. Codex auto-load profile đó trừ khi override bằng --profile other trên CLI. Config precedence rule (cao tới thấp, per official reference):

Mid-session model switching: gõ /model trong TUI rồi chọn model từ list, hoặc --model gpt-5.4-mini khi launch để override single session, hoặc thay model trong [profiles.X] để áp dụng permanent.

5. [tools.web_search] allowed_domains. Mặc định web search Codex query toàn web, tốn token và đôi khi crawl noise (forum, listicle SEO-only). Whitelist domain authoritative (OpenAI docs, Anthropic docs, MDN, official spec) cho task technical research giúp output sạch hơn.

6. [mcp_servers.X] enabled_tools = ["tool1", "tool2"]. MCP server thường expose 10-30 tool, không phải tool nào cũng cần. Whitelist tool cụ thể giảm prompt overhead, model focus tốt hơn vào tool relevant. Test trên ongboit thấy giảm token usage ~15% mỗi tool call khi whitelist từ 25 xuống còn 6 tool quan trọng nhất.

7. [[hooks.PreToolUse]] matcher = "^Bash$" audit log. Hook chạy trước mọi shell command, có thể block command nguy hiểm hoặc log audit trail. Setup audit log đơn giản:

# ~/.codex/hooks/audit_log.py
import sys, json, datetime
event = json.loads(sys.stdin.read())
with open('/var/log/codex_audit.log', 'a') as f:
    f.write(f"{datetime.datetime.now().isoformat()} {event['tool']} {event['input']}n")
sys.exit(0)  # exit 1 to block command

Production stack ongboit dùng pattern này để trace mọi shell call qua Codex, debug dễ và compliance audit minh bạch.

Dùng Claude Sonnet, DeepSeek, Hoặc Local Model Từ Codex CLI Qua [model_providers.X]

Một trong những setting ít documented nhất nhưng cực mạnh: block [model_providers.<id>] cho phép dùng model OAI-compatible khác từ Codex CLI mà không cần đổi tool. Pattern này per custom provider setup guide + MorphLLM provider config:

# Cấu hình Claude Sonnet 4.6 qua proxy OAI-compatible
[model_providers.anthropic]
name = "anthropic"
base_url = "https://api.anthropic.com/v1"
env_key = "ANTHROPIC_API_KEY"

# Cấu hình DeepSeek V3.2 (rẻ cho task code-heavy)
[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

# Cấu hình local model qua Ollama hoặc LM Studio
[model_providers.local]
name = "local-ollama"
base_url = "http://localhost:11434/v1"
env_key = ""    # không cần auth cho local

# Profile dùng provider khác
[profiles.claude]
model_provider = "anthropic"
model = "claude-sonnet-4-6"

[profiles.deepseek]
model_provider = "deepseek"
model = "deepseek-chat"

Sau khi setup, switch sang Claude từ Codex CLI: codex --profile claude. Use case ongboit: dùng Claude Sonnet cho architecture task (reasoning sâu hơn) + Codex GPT-5.4 cho boilerplate, không cần mở 2 tool song song như pattern dual-tool trong bài Claude Code và Codex CLI cùng project. Limitation: một số feature OpenAI-specific (function call format, response_storage) có thể không work với provider khác, test trước khi rely production.

Migrate Config Từ Cursor / Aider / Claude Code Sang Codex Ra Sao?

Pattern migration tuỳ theo tool gốc, nhưng có nguyên tắc chung: KHÔNG copy nguyên config sang vì format khác. Map từng concept tương đương rồi viết lại config trong TOML.

Từ Cursor: Cursor có .cursorrules ở root project. Convert thành AGENTS.md + giữ rule trong markdown thuần. Cursor settings JSON (model, keyboard shortcut) không có equivalent vì Codex là CLI không UI.

Từ Aider: Aider dùng .aider.conf.yml với key như model, auto-commits, edit-format. Map: model → TOML model, auto-commits = false → set approval_policy = "on-request". Aider markdown context file (CONVENTIONS.md) move sang AGENTS.md.

Từ Claude Code: Detail trong bài Claude Code và Codex CLI cùng project. Tóm tắt: ~/.claude/settings.json → ~/.codex/config.toml (convert JSON → TOML, rename key), .claude/skills/ → .agents/skills/ (copy không sửa nội dung markdown), .claude/agents/X.md → .codex/agents/X.toml với instruction trong field developer_instructions.

Có thể nhờ chính Codex CLI tự generate migration: codex "đọc ~/.claude/settings.json và .cursorrules, tạo equivalent ~/.codex/config.toml + AGENTS.md theo Codex convention". Test thấy output stable trên 3 project khác nhau.

Debug Config Errors + Validation Như Thế Nào?

Codex CLI có một số lệnh hỗ trợ debug nhưng không advertise rõ. 4 kỹ thuật mình dùng nhiều nhất:

1. codex --print-config: in ra toàn bộ effective config sau merge (global + project + profile active). Diff với file gốc để biết setting nào thực sự load. Đây là first check khi behavior không như expected.

2. Validate TOML syntax offline: dùng python3 -c "import tomllib; tomllib.load(open('config.toml','rb'))" (Python 3.11+) hoặc taplo check nếu cài taplo CLI. Catch syntax error trước khi load Codex.

3. Log verbose mode: chạy CODEX_LOG=debug codex để xem full log trace, gồm cả config load step. Useful khi MCP server không connect hoặc hook timeout.

4. Backup trước experiment: trước khi thử setting mới, copy cp ~/.codex/config.toml ~/.codex/config.toml.bak. Rollback bằng mv nếu setting mới break workflow.

5. Profile testing trước rely production: nếu setup profile mới cho CI hoặc agent production, chạy codex --profile X --print-config để verify profile override đúng setting trước khi commit. Đặc biệt quan trọng với profile có approval_policy = "untrusted" vì auto-execute tool calls không có human gate.

Câu Hỏi Thường Gặp

config.toml có hỗ trợ environment variable interpolation không?

Hỗ trợ một phần. Setting env_key trong [model_providers.X] chỉ định tên biến môi trường chứa API key, ví dụ env_key = "OPENAI_API_KEY". Codex sẽ đọc giá trị từ env tại runtime. Tuy nhiên syntax kiểu command = "${HOME}/scripts/audit.py" trong [[hooks.PreToolUse]] KHÔNG được expand, phải hardcode đường dẫn đầy đủ hoặc dùng ~ cho home directory.

Setting nào trong config.toml áp dụng ngay, setting nào cần restart Codex?

Tất cả setting load tại thời điểm khởi động session codex. Edit config khi session đang chạy KHÔNG có hiệu lực, phải exit + restart. Exception: profile switching qua flag --profile X lúc khởi động session mới, không cần restart Codex.

Project-level .codex/config.toml override được toàn bộ ~/.codex/config.toml không?

Không. Per official docs, project-scoped config bị cấm override 3 nhóm setting machine-local: model provider authentication, notification settings, và một số security policy. Các setting còn lại (model, sandbox mode, profiles, MCP servers, hooks) đều override được nếu repo nằm trong trusted list.

Làm sao backup config trước khi thử setting mới?

Đơn giản nhất là cp ~/.codex/config.toml ~/.codex/config.toml.bak. Production setup mình recommend version-control toàn bộ ~/.codex/ qua git private (gitignore history.jsonl và file chứa token). Backup tự động theo schedule với cron hoặc n8n workflow.

Set model = “gpt-5-pro” cho profile riêng có pay extra không?

Có. Model premium như gpt-5-pro tiêu thụ quota nhanh hơn model mặc định gpt-5.4 (ratio khoảng 3-5 lần token cost). Nếu dùng ChatGPT Plus tier, quota giới hạn cho premium model thấp hơn rõ. Pro tier $200/tháng có quota rộng hơn cho premium model. Cost optimization khuyến nghị: dùng gpt-5.4 default cho daily task, switch sang gpt-5-pro qua [profiles.review] chỉ khi cần reasoning depth cao.