config.toml của Codex: chọn model, mức suy nghĩ và profile cho từng việc

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:

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.

Những khoá nào trong config.toml đáng chỉnh?

Các khoá dưới đây đều có trong trang Config Reference đọc ngày 03/11/2026. Ví dụ dùng chỗ trống <tên-model> vì model khả dụng tuỳ tài khoản.

model = "<tên-model>"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[agents]
default_subagent_model = "<tên-model-nhỏ-hơn>"
default_subagent_reasoning_effort = "low"

[projects."/duong-dan/toi/du-an"]
trust_level = "trusted"

Chọn model và mức suy nghĩ thế nào?

Khoá model chọn model mặc định; tài liệu nhắc phải dùng model mà tài khoản hoặc workspace đã đăng nhập có quyền dùng. Khoá model_reasoning_effort chọn mức suy nghĩ, tài liệu liệt kê các mức như low, medium, high, xhigh, max hay ultra, nhưng mức nào khả dụng tuỳ model và ứng dụng. Mức cao thường chậm và tốn hạn mức hơn, song chúng tôi không có số đo riêng. Khoá plan_mode_reasoning_effort đặt mức riêng cho chế độ lập kế hoạch.

Chế độ phê duyệt và sandbox khác nhau ra sao?

approval_policy quyết định khi nào Codex dừng lại xin phép; sandbox_mode quyết định lệnh được làm gì với file và mạng. Theo tài liệu đọc ngày 03/11/2026:

1. approval_policy nhận on-request (mô hình tự quyết khi nào hỏi), never (không hỏi, dùng cho chạy tự động), hoặc một bảng granular chọn từng loại câu hỏi. Giá trị untrusted đã bị gỡ, on-failure bị đánh dấu lỗi thời.
2. sandbox_mode nhận read-only, workspace-write hoặc danger-full-access. Với workspace-write, nhóm khoá sandbox_workspace_write cho thêm thư mục ghi được (writable_roots) và bật mạng (network_access).
3. approvals_reviewer chọn ai duyệt: user (mặc định) hoặc auto_review (một subagent duyệt).

Chi tiết từng chế độ nằm trong bài chế độ phê duyệt và sandbox của Codex.

Khai báo nhà cung cấp model riêng thế nào?

Nhà cung cấp riêng khai báo trong bảng [model_providers.<id>] rồi chọn bằng khoá model_provider. Ví dụ dưới đây theo mẫu trong trang Advanced Config, địa chỉ là địa chỉ minh hoạ:

model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI qua proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

env_key là TÊN biến môi trường chứa khoá, không phải bản thân khoá. Tài liệu còn nêu wire_api, http_headers, request_max_retries, và các mã dành riêng không đặt trùng được như openai, ollama, lmstudio. Muốn chỉ đổi địa chỉ của nhà cung cấp OpenAI có sẵn, dùng openai_base_url.

Thêm máy chủ MCP vào config.toml ra sao?

Máy chủ MCP khai báo trong bảng [mcp_servers.<id>]: command và args cho máy chủ chạy qua stdio, url cho máy chủ HTTP, env cho biến môi trường, bearer_token_env_var để đọc token từ biến môi trường, enabled_tools / disabled_tools để giới hạn công cụ. Cũng có thể thêm bằng lệnh codex mcp add <tên> --url <URL> hoặc codex mcp add <tên> -- <lệnh>, xem bằng codex mcp list. Về MCP nói chung, đọc MCP là gì và MCP, skill và hooks trong Codex.

Ghi đè config.toml bằng cờ dòng lệnh thế nào?

Ghi đè bằng cờ dòng lệnh là cách đổi cấu hình cho một lần chạy mà không sửa file, vì cờ đứng trên cùng thứ tự ưu tiên. Các cờ dưới đây có trong codex --help bản 0.162.1 (đọc ngày 03/11/2026):

Cờ	Tác dụng
-m, --model	Chọn model cho lần chạy
-c, --config key=value	Ghi đè một khoá bất kỳ, dùng dấu chấm cho khoá lồng
-p, --profile	Chồng file <tên>.config.toml lên cấu hình người dùng
-s, --sandbox	read-only, workspace-write, danger-full-access
-a, --ask-for-approval	on-request hoặc never
--add-dir	Thêm thư mục ghi được ngoài thư mục làm việc

Ví dụ giả định: chạy một lần với mức suy nghĩ cao hơn mặc định.

codex -c model_reasoning_effort="high"

Giá trị sau dấu bằng được đọc như TOML. Cờ --dangerously-bypass-approvals-and-sandbox bỏ mọi xác nhận và sandbox; chính phần trợ giúp ghi chỉ dùng trong môi trường đã được cô lập bên ngoài.

Profile của Codex dùng thế nào cho từng loại việc?

Profile của Codex là một file TOML riêng tên <tên>.config.toml đặt cạnh config.toml, được chồng lên cấu hình người dùng khi chạy codex --profile <tên> hoặc codex exec --profile <tên>. Theo trang Advanced Config (đọc ngày 03/11/2026), từ Codex 0.134.0, --profile không còn đọc bảng [profiles.<tên>] trong config.toml và khoá profile = "<tên>" ở cấp trên cũng không còn được hỗ trợ. Bảng dưới là gợi ý của OPCAIOS, không phải cấu hình OPCAIOS đang chạy, và không phải khuyến nghị của OpenAI:

Profile (gợi ý)	Loại việc	Mức suy nghĩ	Sandbox	Phê duyệt
doc-code	Đọc, giải thích code, hỏi đáp	low	read-only	on-request
sua-nho	Sửa lỗi nhỏ, đổi chữ, thêm test	medium	workspace-write	on-request
ke-hoach	Thiết kế tính năng, refactor lớn	high	read-only	on-request
review	Đọc diff, tìm lỗi trước commit	high	read-only	on-request
tu-dong	Chạy codex exec theo lịch	medium	workspace-write	never

Ví dụ file profile sua-nho, nằm ở ~/.codex/sua-nho.config.toml:

model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Profile tu-dong với never chỉ nên dùng khi đã hiểu rủi ro; xem codex exec chạy tự động.

Làm sao để không lộ khoá API trong config.toml?

Giữ khoá API ngoài config.toml là nguyên tắc chính, vì file cấu hình hay bị sao chép, chia sẻ hoặc commit nhầm. Các bước thực dụng:

1. Chỉ ghi TÊN biến môi trường trong env_key, bearer_token_env_var, env_http_headers; giá trị thật đặt trong biến môi trường hoặc trình quản lý bí mật.
2. Không đặt khoá nhà cung cấp trong .codex/config.toml của dự án; tài liệu vốn bỏ qua nhóm khoá này ở cấp dự án.
3. Trước khi chia sẻ file cấu hình, xoá đường dẫn máy, địa chỉ nội bộ, tên dự án.
4. Không đọc, gửi hay commit các file đăng nhập và lịch sử phiên trong thư mục home của Codex.

Xem thêm bảo mật khi dùng AI viết code.

Kinh nghiệm của OPCAIOS

OPCAIOS dùng Codex CLI bản 0.162.x và ứng dụng desktop Codex trên máy làm việc chính, song song Claude Code và Google Antigravity. Cấu hình Codex hiện tại (kiểm tra ngày 03/11/2026), mô tả ở mức khái niệm:

1. Model mặc định và mức suy nghĩ medium. Mức giữa làm mặc định; việc khó có thể tăng cho một lần chạy bằng -c. Chúng tôi chưa đo chênh lệch chất lượng hay hạn mức giữa các mức.
2. Subagent được cấu hình dùng một model nhỏ hơn để tiết kiệm; chưa đo mức tiết kiệm.
3. Một nhà cung cấp model riêng được khai báo thêm, đi qua một cổng định tuyến model.
4. Nhiều thư mục dự án được đánh dấu tin cậy, để cấu hình và hướng dẫn cấp dự án được nạp.
5. File hướng dẫn cấp người dùng cho Codex, tương đương file của Claude Code; xem AGENTS.md là gì.

Điều chúng tôi chưa làm: chưa đưa codex exec vào CI, chưa dùng Codex trên đám mây để mở pull request.

Câu hỏi thường gặp

Không có file config.toml thì Codex có chạy được không?

Có. Codex dùng mặc định có sẵn khi không có file nào, theo thứ tự ưu tiên trong tài liệu. Bạn chỉ cần tạo ~/.codex/config.toml khi muốn đổi model mặc định, mức suy nghĩ, chế độ phê duyệt, sandbox hay thêm máy chủ MCP. Bắt đầu với vài khoá rồi thêm dần sẽ dễ tìm lỗi hơn chép nguyên file mẫu dài từ mạng.

Nên đặt mức suy nghĩ nào làm mặc định?

Không có đáp án chung, vì mức khả dụng tuỳ model và tài khoản. OPCAIOS đặt medium làm mặc định. Gợi ý của chúng tôi: chỉ tăng mức cho từng lần chạy khi việc khó, như thiết kế tính năng hay tìm lỗi khó. Lý do là mức cao thường chậm hơn và tốn hạn mức hơn; chúng tôi chưa đo con số cụ thể. Bạn có thể thử cùng một việc ở hai mức rồi so kết quả trước khi chọn.

Bài hướng dẫn cũ dùng bảng [profiles] có còn đúng không?

Không còn đúng với bản mới. Theo trang Advanced Config đọc ngày 03/11/2026, từ Codex 0.134.0 cờ --profile không đọc bảng [profiles.<tên>] trong config.toml nữa, và khoá profile cấp trên cũng không được hỗ trợ. Profile giờ là file riêng ~/.codex/<tên>.config.toml. Nếu đang dùng cấu hình cũ, chuyển từng bảng profile thành một file, rồi chạy thử với --strict-config để thấy khoá nào không còn được nhận.

Có thể để config.toml trong kho dự án để cả nhóm dùng chung không?

Có, qua file .codex/config.toml của dự án, nhưng chỉ có hiệu lực khi dự án được tin cậy trên máy từng người. File dự án hợp với thiết lập chung như sandbox hay mức suy nghĩ. Nhà cung cấp model, thông báo, profile thì tài liệu yêu cầu đặt ở cấu hình người dùng và Codex bỏ qua nếu nằm trong file dự án. Tuyệt đối không commit khoá API vào file này.

Thay đổi config.toml có hiệu lực ngay không?

Nên coi là chưa, cho tới khi mở phiên mới. Tài liệu Codex nói phải khởi động lại sau khi đổi một số khoá như tên file hướng dẫn dự phòng, và chuỗi AGENTS.md cũng chỉ dựng một lần mỗi lần chạy. Cách chắc ăn: sửa file, mở phiên mới, hỏi Codex đang dùng cấu hình gì, hoặc chạy codex doctor. Nếu muốn có người hướng dẫn dựng cấu hình Codex theo cách làm việc thật của bạn, xem khoá đào tạo ứng dụng AI của OPCAIOS.

Nguồn: tài liệu Codex của OpenAI, các trang Config basics, Advanced Config, Config Reference và AGENTS.md (developers.openai.com chuyển hướng sang learn.chatgpt.com/docs), cùng codex --help, codex exec --help, codex mcp add --help của Codex CLI 0.162.1, đọc ngày 03/11/2026. Danh sách mức suy nghĩ, giá trị phê duyệt và quy tắc profile có thể đổi theo bản cập nhật; chưa kiểm chứng chất lượng hay chi phí giữa các mức suy nghĩ; bảng profile là gợi ý của OPCAIOS. Kinh nghiệm là của OPCAIOS.