
config.toml Codex
config.toml Codex là file cấu hình dạng TOML mà Codex CLI, tiện ích IDE và ứng dụng desktop Codex cùng đọc khi khởi động: model nào được dùng, mô hình suy nghĩ sâu tới đâu, khi nào phải xin phép, lệnh được chạy trong sandbox nào, kết nối máy chủ MCP nào. Theo trang "Config basics" trong tài liệu Codex (developers.openai.com chuyển hướng sang learn.chatgpt.com, đọc ngày 03/11/2026), CLI và tiện ích IDE dùng chung các lớp cấu hình này. Bài này không hứa một bộ cấu hình "tốt nhất": model và mức suy nghĩ khả dụng tuỳ tài khoản, OPCAIOS không đo chất lượng hay chi phí giữa các mức. Mọi khoá và cờ trong bài được đối chiếu với tài liệu chính thức và codex --help bản 0.162.1. Bài gồm: file nằm ở đâu, thứ tự ưu tiên, các khoá đáng chỉnh, cách ghi đè bằng cờ dòng lệnh, profile theo loại việc, an toàn khoá API, và cấu hình thật của OPCAIOS ở mức khái niệm.

Các lớp cấu hình của Codex và nhóm khoá chính. Sơ đồ: OPCAIOS.
File config.toml của Codex nằm ở đâu?
File config.toml của Codex cấp người dùng nằm ở ~/.codex/config.toml, trong thư mục home của Codex (mặc định ~/.codex, đổi được bằng biến CODEX_HOME). Theo tài liệu Codex đọc ngày 03/11/2026, còn ba vị trí khác: file .codex/config.toml trong từng dự án, file profile ~/.codex/<tên>.config.toml, và file hệ thống /etc/codex/config.toml trên Unix. Codex chỉ nạp lớp .codex/ của dự án khi dự án được đánh dấu tin cậy; dự án không tin cậy bị bỏ qua cấu hình, hooks và rules cục bộ, còn cấu hình người dùng và hệ thống vẫn nạp. Trạng thái tin cậy ghi bằng khoá projects.<đường-dẫn>.trust_level với giá trị "trusted" hoặc "untrusted". Bản 0.162.1 có cờ --strict-config báo lỗi khi file chứa khoá lạ, và lệnh codex doctor để chẩn đoán cấu hình.
Codex ưu tiên lớp cấu hình nào trước?
Codex gộp nhiều lớp cấu hình, lớp trên thắng lớp dưới. Thứ tự theo trang "Config basics" (đọc ngày 03/11/2026), từ cao xuống thấp:
- Cờ dòng lệnh và ghi đè
-c/--config. - File
.codex/config.tomlcủa dự án, từ gốc dự án xuống thư mục hiện tại, file gần nhất thắng (chỉ khi dự án được tin cậy). - File profile chọn bằng
--profile <tên>. - File người dùng
~/.codex/config.toml. - Cấu hình mặc định do quản trị viên workspace đẩy xuống (nếu có).
- File hệ thống
/etc/codex/config.toml. - Mặc định có sẵn.
Một điểm dễ nhầm: file dự án không ghi đè được nhóm khoá gắn với máy. Theo trang Config Reference, Codex bỏ qua model_provider, model_providers, notify, profile và vài khoá khác nếu nằm trong .codex/config.toml của dự án.
Which Keys in config.toml Are Worth Adjusting?
The keys below are all found on the Config Reference page read on 03/11/2026. Examples use the placeholder <model-name> because available models vary by account.
model = "<model-name>"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[agents]
default_subagent_model = "<smaller-model-name>"
default_subagent_reasoning_effort = "low"
[projects."/path/to/my/project"]
trust_level = "trusted"
How Do I Choose Model and Reasoning Effort?
The model key selects the default model; the documentation reminds you to use a model that your account or logged-in workspace has permission to use. The model_reasoning_effort key selects the reasoning level; the documentation lists levels like low, medium, high, xhigh, max, or ultra, but which levels are available depends on the model and application. Higher levels are usually slower and consume more quota, but we don't have separate measurements. The plan_mode_reasoning_effort key sets a separate level for plan mode.
How Do Approval Mode and Sandbox Differ?
approval_policy decides when Codex stops to ask permission; sandbox_mode decides what commands can do with files and network. According to the documentation read on 03/11/2026:
approval_policyacceptson-request(the model decides when to ask),never(don't ask, for automated runs), or agranulartable that selects individual question types. The valueuntrustedhas been removed, andon-failureis marked deprecated.sandbox_modeacceptsread-only,workspace-write, ordanger-full-access. Withworkspace-write, thesandbox_workspace_writekey group adds writable directories (writable_roots) and enables network (network_access).approvals_reviewerchooses who reviews:user(default) orauto_review(a subagent reviews).
Details for each mode are in the post Codex Approval and Sandbox Modes.
How Do I Declare a Custom Model Provider?
A custom provider is declared in the [model_providers.<id>] table, then selected with the model_provider key. The example below follows the pattern in the Advanced Config page, with the address as an illustration:
model_provider = "proxy"
[model_providers.proxy]
name = "OpenAI via proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"
env_key is the NAME of the environment variable holding the key, not the key itself. The documentation also lists wire_api, http_headers, request_max_retries, and reserved identifiers that cannot be duplicated like openai, ollama, lmstudio. To only change the address of the built-in OpenAI provider, use openai_base_url.
How Do I Add an MCP Server to config.toml?
MCP servers are declared in the [mcp_servers.<id>] table: command and args for servers running over stdio, url for HTTP servers, env for environment variables, bearer_token_env_var to read the token from an environment variable, enabled_tools / disabled_tools to limit tools. You can also add them with the command codex mcp add <name> --url <URL> or codex mcp add <name> -- <command>, view them with codex mcp list. For MCP in general, read What is MCP and MCP, Skills, and Hooks in Codex.
How Do I Override config.toml with Command-Line Flags?
Overriding with command-line flags is a way to change configuration for a single run without editing the file, since flags rank highest in priority order. The flags below are in codex --help version 0.162.1 (read on 03/11/2026):
| Flag | Purpose |
|---|---|
-m, --model |
Select model for this run |
-c, --config key=value |
Override any key, use dots for nested keys |
-p, --profile |
Layer <name>.config.toml on top of user configuration |
-s, --sandbox |
read-only, workspace-write, danger-full-access |
-a, --ask-for-approval |
on-request or never |
--add-dir |
Add a writable directory outside the working directory |
Example scenario: run once with a higher reasoning level than the default.
codex -c model_reasoning_effort="high"
The value after the equals sign is read as TOML. The flag --dangerously-bypass-approvals-and-sandbox removes all confirmations and sandbox; the help text itself notes use only in isolated environments outside.
How to Use Codex Profiles for Different Tasks?
A Codex profile is a separate TOML file named <name>.config.toml placed next to config.toml, which overlays user configuration when running codex --profile <name> or codex exec --profile <name>. According to the Advanced Config page (checked on 03/11/2026), from Codex 0.134.0 onwards, --profile no longer reads the [profiles.<name>] table in config.toml, and the profile = "<name>" key at the top level is also no longer supported. The table below is a suggestion from OPCAIOS, not OPCAIOS's current running configuration, and not a recommendation from OpenAI:
| Profile (suggestion) | Task type | Reasoning level | Sandbox | Approval |
|---|---|---|---|---|
doc-code |
Reading, explaining code, Q&A | low |
read-only |
on-request |
sua-nho |
Small fixes, text changes, adding tests | medium |
workspace-write |
on-request |
ke-hoach |
Feature design, large refactoring | high |
read-only |
on-request |
review |
Reading diffs, finding bugs before commit | high |
read-only |
on-request |
tu-dong |
Running codex exec on schedule |
medium |
workspace-write |
never |
Example profile file sua-nho, located at ~/.codex/sua-nho.config.toml:
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
Profile tu-dong with never should only be used when you fully understand the risks; see codex exec running automatically.
How to Avoid Exposing API Keys in config.toml?
Keeping API keys out of config.toml is the core principle, since config files are often copied, shared, or accidentally committed. Practical steps:
- Only write ENVIRONMENT VARIABLE NAMES in
env_key,bearer_token_env_var,env_http_headers; put actual values in environment variables or a secrets manager. - Do not place provider keys in
.codex/config.tomlat the project level; the documentation already skips this key group at the project level. - Before sharing config files, remove machine paths, internal addresses, and project names.
- Do not read, send, or commit login files and session history in Codex's home directory.
See also security when using AI to write code.
OPCAIOS Experience
I use Codex CLI version 0.162.x and the Codex desktop app on my main work machine, alongside Claude Code and Google Antigravity. My current Codex configuration (checked on 03/11/2026), described at a conceptual level:
- Default model and reasoning level
medium. Medium level as default; harder tasks can be bumped up for a single run with-c. I haven't yet measured the quality difference or rate limits between levels. - Subagents configured to use a smaller model to save costs; haven't measured the savings yet.
- One additional model provider set up, going through a model routing gateway.
- Multiple project directories marked as trusted, so project-level configuration and guidelines are loaded.
- User-level guidelines file for Codex, equivalent to Claude Code's file; see What is AGENTS.md.
What I haven't done yet: haven't put codex exec into CI, haven't used Codex on the cloud to open pull requests.
Frequently Asked Questions
Will Codex run without a config.toml file?
Yes. Codex uses built-in defaults when no file exists, following the priority order in the documentation. You only need to create ~/.codex/config.toml when you want to change the default model, thinking level, approval mode, sandbox, or add MCP servers. Starting with a few keys and adding gradually will make it easier to find errors than copying a long sample file from the internet.
What thinking level should I set as default?
There is no universal answer, since level availability depends on the model and account. OPCAIOS sets medium as the default. Our suggestion: only increase the level for individual runs when the work is difficult, such as feature design or debugging tricky issues. The reason is that higher levels are usually slower and consume more quota; we haven't measured specific numbers yet. You can try the same task at two levels and compare results before deciding.
Are old tutorials using the [profiles] table still correct?
They are no longer correct with the new version. According to the Advanced Config page read on 03/11/2026, from Codex 0.134.0 the --profile flag no longer reads the [profiles.<name>] table in config.toml, and the top-level profile key is also no longer supported. Profiles are now separate files at ~/.codex/<name>.config.toml. If you are using the old configuration, convert each profile table into a separate file, then test with --strict-config to see which keys are no longer recognized.
Can I keep config.toml in the project repository so the whole team can use it?
Yes, through the project's .codex/config.toml file, but it only takes effect when the project is trusted on each person's machine. The project file works well for shared settings like sandbox or thinking level. Model provider, notifications, and profiles must be placed in user configuration according to the documentation, and Codex ignores them if they are in the project file. Never commit API keys to this file.
Do changes to config.toml take effect immediately?
You should assume they don't until you open a new session. The Codex documentation says you must restart after changing certain keys like the fallback instruction file name, and the AGENTS.md string also only builds once per run. The sure way: edit the file, open a new session, ask Codex what configuration it is using, or run codex doctor. If you want someone to guide you in setting up Codex configuration based on how you actually work, see OPCAIOS's AI application training program.
Source: Codex documentation from OpenAI, the pages Config basics, Advanced Config, Config Reference and AGENTS.md (developers.openai.com redirects to learn.chatgpt.com/docs), along with codex --help, codex exec --help, codex mcp add --help from Codex CLI 0.162.1, read on 03/11/2026. The list of thinking levels, approval values, and profile rules may change with updates; quality or cost differences between thinking levels have not been verified; the profile table is a suggestion from OPCAIOS. The experience is from OPCAIOS.
Translated from Vietnamese with AI. Read the original.
Want to apply this in your business?
Book a free 30-minute call (Vietnam time, in English or Vietnamese).
