# Codex's config.toml: choosing model, thinking level, and profile for each task

URL: https://opcaios.org/en/blog/cau-hinh-codex-config-toml
Date: 2026-11-03
Author: Lê Quốc Nghĩa

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

![Sơ đồ cấu hình Codex: cờ dòng lệnh và -c đứng trên cùng, rồi .codex/config.toml của dự án đã tin cậy, rồi file profile, rồi ~/.codex/config.toml của người dùng, rồi cấu hình hệ thống và mặc định; các nhóm khoá model, mức suy nghĩ, phê duyệt, sandbox, nhà cung cấp, MCP, subagent](https://opcaios.org/images/blog/cau-hinh-codex-config-toml/so-do.webp)
*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:

1. Cờ dòng lệnh và ghi đè `-c` / `--config`.
2. File `.codex/config.toml` củ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).
3. File profile chọn bằng `--profile <tên>`.
4. File người dùng `~/.codex/config.toml`.
5. Cấu hình mặc định do quản trị viên workspace đẩy xuống (nếu có).
6. File hệ thống `/etc/codex/config.toml`.
7. 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.

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

1. `approval_policy` accepts `on-request` (the model decides when to ask), `never` (don't ask, for automated runs), or a `granular` table that selects individual question types. The value `untrusted` has been removed, and `on-failure` is marked deprecated.
2. `sandbox_mode` accepts `read-only`, `workspace-write`, or `danger-full-access`. With `workspace-write`, the `sandbox_workspace_write` key group adds writable directories (`writable_roots`) and enables network (`network_access`).
3. `approvals_reviewer` chooses who reviews: `user` (default) or `auto_review` (a subagent reviews).

Details for each mode are in the post [Codex Approval and Sandbox Modes](/blog/che-do-phe-duyet-va-sandbox-cua-codex).

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

```toml
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](/blog/mcp-la-gi) and [MCP, Skills, and Hooks in Codex](/blog/mcp-skill-va-hooks-trong-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.

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

```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](/blog/codex-exec-chay-tu-dong).

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

1. 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.
2. Do not place provider keys in `.codex/config.toml` at the project level; the documentation already skips this key group at the project level.
3. Before sharing config files, remove machine paths, internal addresses, and project names.
4. 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](/blog/bao-mat-khi-dung-ai-viet-code).

## OPCAIOS Experience

I use Codex CLI version 0.162.x and the Codex desktop app on my main work machine, alongside [Claude Code](/tien-ich/claude-code) and [Google Antigravity](/tien-ich/google-antigravity). My current Codex configuration (checked on 03/11/2026), described at a conceptual level:

1. **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.
2. **Subagents configured to use a smaller model** to save costs; haven't measured the savings yet.
3. **One additional model provider** set up, going through a model routing gateway.
4. **Multiple project directories marked as trusted**, so project-level configuration and guidelines are loaded.
5. **User-level guidelines file** for Codex, equivalent to Claude Code's file; see [What is AGENTS.md](/blog/agents-md-la-gi).

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](/services/dao-tao-ung-dung-ai).

*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.*
