Codex lưu cài đặt trong một tệp duy nhất, config.toml: dùng model nào, gọi API nào và agent có thể làm những gì mà không cần hỏi. Định dạng này đã thay đổi nhiều lần trong năm 2026, và nhiều hướng dẫn từ đầu năm hiện có các cài đặt khiến Codex không thể khởi động.
Hướng dẫn này cung cấp cấu hình hoạt động được trước, sau đó là những phần mà hầu hết mọi người thường thay đổi: profile, cài đặt dự án, sandbox và proxy. Cuối bài là danh sách các lỗi bạn có thể gặp cùng ý nghĩa của từng lỗi. Đã đối chiếu với tài liệu OpenAI và chạy thử trên Codex CLI 0.162.1 vào ngày 19 tháng 10 năm 2026. Các ví dụ sử dụng AIHubMix làm nhà cung cấp; mọi gateway hỗ trợ OpenAI Responses API đều hoạt động tương tự.
Tóm tắt nhanh
- Tệp nằm tại
~/.codex/config.toml, hoặcC:\Users\<you>\.codex\config.tomltrên Windows. - Nhà cung cấp tùy chỉnh cần có
base_url,wire_api = "responses"vàenv_key. Khóa API được lưu trong một biến môi trường. - Profile hiện là các tệp riêng biệt,
~/.codex/<name>.config.toml, được chọn bằng--profile <name>. - Tệp
.codex/config.tomlcủa repo chỉ hoạt động trong các dự án đáng tin cậy và không thể thay đổi nhà cung cấp. - Khởi động lại Codex sau mỗi lần chỉnh sửa; Codex chỉ đọc tệp khi khởi động.
Vị trí của config.toml
Cài đặt chính nằm trong ~/.codex/config.toml. Cả CLI lẫn tiện ích mở rộng IDE đều đọc tệp này. Nếu tệp chưa tồn tại, hãy tạo tệp.
Hai vị trí khác có thể bổ sung cài đặt:
- Tệp profile,
~/.codex/<name>.config.toml, chỉ được dùng khi bạn khởi chạy Codex bằng--profile <name>. - Tệp dự án,
.codex/config.tomlbên trong repo, dùng để chia sẻ các cài đặt mà nhóm muốn dùng chung.
Nếu chạy Codex trong WSL2 trên Windows, Codex sẽ đọc thư mục home của Linux (/home/<you>/.codex/config.toml), chứ không phải tệp trên Windows. Nếu đã đặt CODEX_HOME, Codex sẽ dùng thư mục đó thay cho ~/.codex.
Cấu hình tối thiểu hoạt động được
Tệp ~/.codex/config.toml hoàn chỉnh này sẽ chuyển các yêu cầu của Codex đến AIHubMix:
model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"
[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"
modellà ID của model cần gọi, cònmodel_reasoning_effortlà mức độ suy luận mặc định của model đó.model_providerphải khớp với tên trong[model_providers.<name>]. Đừng dùngopenai,ollamahoặclmstudio; các tên này đã được dành riêng cho nhà cung cấp tích hợp sẵn của Codex.base_urllà địa chỉ API của nhà cung cấp. Hiện Codex chỉ chấp nhận giá trịwire_api = "responses".env_keylà tên của biến môi trường, không phải bản thân khóa.
Sau đó, đặt biến đó bằng khóa lấy từ bảng điều khiển AIHubMix:
# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...
# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."
Mở một cửa sổ terminal mới, chạy codex rồi hỏi bất cứ điều gì. Nếu Codex trả lời, nhà cung cấp đã hoạt động. Việc bạn đăng nhập vào Codex hay chưa không ảnh hưởng ở đây: khóa từ codex login sẽ không bao giờ được gửi đến nhà cung cấp tùy chỉnh.
Profile: mỗi cấu hình một tệp
Profile chỉ chứa những cài đặt khác với cấu hình chính, chẳng hạn như mức suy luận sâu hơn và sandbox chỉ đọc để rà soát mã. Mỗi profile là một tệp riêng nằm cạnh config.toml, với các khóa được ghi ở cấp cao nhất:
# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"
codex --profile review
Điều này đã thay đổi trong Codex 0.134.0. Các hướng dẫn cũ đặt profile bên trong config.toml dưới dạng các bảng [profiles.review] và chọn profile bằng profile = "review". Hiện Codex từ chối khởi động nếu có dòng chọn profile đó. Nếu vẫn còn bảng [profiles.review] riêng lẻ, Codex sẽ bỏ qua mà không thông báo, khiến các cài đặt trong bảng âm thầm ngừng hoạt động. Để chuyển đổi, hãy chuyển các khóa của từng bảng vào ~/.codex/<name>.config.toml, sau đó xóa bảng và dòng profile = .... Xem thêm chi tiết trong hướng dẫn cấu hình nâng cao của OpenAI.
Cấu hình dự án: .codex/config.toml
Tệp .codex/config.toml trong repo cho phép nhóm chia sẻ model mặc định, mức suy luận hoặc chế độ sandbox. Codex chỉ đọc tệp này trong các dự án được đánh dấu là đáng tin cậy trong tệp ~/.codex/config.toml của chính bạn:
[projects."/Users/you/code/my-app"]
trust_level = "trusted"
Tệp dự án không thể thay đổi nơi gửi yêu cầu. Codex bỏ qua các khóa model_provider, model_providers, openai_base_url, profile, notify và một số khóa khác trong tệp này, đồng thời in cảnh báo khi bỏ qua. Hãy giữ cấu hình nhà cung cấp trong ~/.codex/config.toml. Dự án vẫn có thể chọn model; yêu cầu sẽ được gửi đến nhà cung cấp của riêng bạn.
Cài đặt nào được ưu tiên
Khi cùng một khóa được đặt ở nhiều nơi, mục Thông tin cơ bản về cấu hình của OpenAI đưa ra thứ tự ưu tiên sau, từ cao xuống thấp:
- Các cờ dòng lệnh, bao gồm các ghi đè bằng
-c - Tệp
.codex/config.tomlcủa dự án - Profile được chọn bằng
--profile ~/.codex/config.tomlcủa bạn- Cấu hình hệ thống,
/etc/codex/config.toml - Các giá trị mặc định tích hợp sẵn của Codex
Lưu ý rằng tệp dự án được ưu tiên hơn profile. Nếu cài đặt trong profile có vẻ không có tác dụng, hãy kiểm tra xem tệp .codex/config.toml của repo có đặt cùng khóa hay không.
Để thay đổi cài đặt chỉ cho một lần chạy, hãy dùng -c:
codex -c model_reasoning_effort=high
Sandbox và yêu cầu phê duyệt
Hai khóa kiểm soát những gì Codex có thể tự thực hiện. sandbox_mode quy định các lệnh có thể truy cập những gì, còn approval_policy quy định khi nào Codex dừng lại để hỏi bạn.
| sandbox_mode | Các lệnh có thể làm gì |
|---|---|
| read-only | Đọc tệp; mọi thao tác khác đều cần phê duyệt |
| workspace-write | Ghi trong thư mục dự án và các thư mục tạm |
| danger-full-access | Bất cứ thao tác nào, không có sandbox |
| approval_policy | Khi nào Codex hỏi |
|---|---|
| on-request | Khi cần vượt ra ngoài sandbox |
| never | Không bao giờ; các lệnh bị chặn sẽ thất bại |
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = true # off by default
Hai cài đặt này độc lập với nhau: never ngăn Codex hỏi nhưng không nới lỏng sandbox. Trong chế độ workspace-write, các lệnh không thể truy cập mạng cho đến khi bạn đặt network_access = true.
Khi dùng proxy
Codex không có cài đặt proxy trong config.toml. Codex sử dụng các biến môi trường tiêu chuẩn:
export HTTPS_PROXY=http://127.0.0.1:7890 # your proxy address
export NO_PROXY=localhost,127.0.0.1
Tài liệu của OpenAI không đề cập đến các biến này, nên chúng đã được kiểm tra trên Codex 0.162.1: các yêu cầu, kể cả yêu cầu gửi đến nhà cung cấp tùy chỉnh, đều đi qua HTTPS_PROXY (hoặc ALL_PROXY), còn các máy chủ trong NO_PROXY được truy cập trực tiếp. PAC không được hỗ trợ, vì vậy hãy nhập trực tiếp địa chỉ proxy. Nếu proxy của công ty dùng chứng chỉ gốc riêng, hãy trỏ CODEX_CA_CERTIFICATE đến chứng chỉ đó như mô tả trong tài liệu tham chiếu biến môi trường.
Thêm model vào /model
Bộ chọn /model chỉ liệt kê các model của OpenAI. Để chọn các model GLM, Claude, Gemini hoặc DeepSeek từ danh sách này, hãy thêm danh mục model: một tệp JSON có tên được khai báo bằng khóa cấp cao nhất model_catalog_json. Đặt khóa này phía trên dòng [table] đầu tiên, nếu không TOML sẽ xem nó là một phần của bảng đó và Codex sẽ bỏ qua.
Danh mục này thay thế danh sách tích hợp sẵn, và mỗi mục cần có nhiều trường, vì vậy tốt nhất nên tạo tự động thay vì viết thủ công. Hướng dẫn AIHubMix Codex CLI có một tập lệnh tạo danh mục từ 30 model hàng đầu trên AIHubMix. Ứng dụng máy tính vẫn có thể ẩn các model tùy chỉnh khỏi bộ chọn (openai/codex#19694), vì vậy hãy đổi model trong terminal.
Lỗi thường gặp và ý nghĩa
Đây là những thông báo Codex 0.162.1 đưa ra cho từng lỗi.
legacy profile = "..." config is no longer supported
Tệp config.toml của bạn vẫn còn dòng profile = "..." cũ. Hãy chuyển profile sang tệp riêng như mô tả ở trên. Chạy --profile x khi vẫn còn bảng [profiles.x] cũ sẽ gây ra lỗi tương tự: --profile x cannot be used while ... contains legacy ... config.
wire_api = "chat" is no longer supported
Codex không còn hỗ trợ Chat Completions API. Hãy đổi thành wire_api = "responses". Nhà cung cấp chỉ cung cấp Chat Completions sẽ không hoạt động nếu không có proxy chuyển đổi.
model_providers contains reserved built-in provider IDs
Bạn đã đặt tên nhà cung cấp là openai, ollama hoặc lmstudio. Hãy đổi tên bảng và model_provider sang tên khác.
approval_policy = "untrusted" is no longer supported
Xóa dòng này hoặc dùng on-request.
Missing environment variable: AIHUBMIX_API_KEY
Biến được đặt tên trong env_key chưa được thiết lập trong terminal đã khởi chạy Codex. Mở terminal mới hoặc chạy source ~/.zshrc, rồi khởi chạy lại Codex.
401 Unauthorized sau vài dòng "Reconnecting..."
Yêu cầu đã được gửi đi mà không có khóa. Hãy kiểm tra xem bảng nhà cung cấp có env_key hay không. Thông tin đăng nhập được lưu trong auth.json không có tác dụng với nhà cung cấp tùy chỉnh.
Model metadata for ... not found. Defaulting to fallback metadata
Codex không có cài đặt tích hợp sẵn cho model đó; điều này bình thường với các model không phải của OpenAI. Yêu cầu vẫn hoạt động. Hãy thêm danh mục model nếu muốn có cài đặt phù hợp và thấy model trong /model.
Ignored unsupported project-local config keys
Tệp .codex/config.toml của repo đặt một khóa chỉ hoạt động trong cấu hình của riêng bạn, thường là model_provider. Hãy chuyển khóa này vào ~/.codex/config.toml.
missing field base_instructions
Một mục trong danh mục model của bạn thiếu trường bắt buộc, khiến Codex từ chối toàn bộ tệp. Hãy tạo lại danh mục bằng tập lệnh thay vì chỉnh sửa thủ công.
Khi cài đặt không có hiệu lực
- Khởi động lại Codex sau khi chỉnh sửa.
- Đảm bảo các khóa cấp cao nhất nằm trước dòng
[table]đầu tiên. - Kiểm tra tệp
.codex/config.tomlcủa repo; tệp này được ưu tiên hơn profile của bạn. - Tìm xem có bảng
[profiles.x]cũ còn sót lại hay không. - Chạy
codex doctorđể kiểm tra bản cài đặt, cấu hình và thông tin đăng nhập.
Nếu muốn dùng OpenAI, Anthropic, Google, Zhipu, DeepSeek và các model khác trong Codex chỉ với một khóa, AIHubMix cung cấp chúng qua Responses API tại https://aihubmix.com/v1. Hãy bắt đầu với cấu hình tối thiểu ở trên, rồi thêm danh mục model khi muốn chuyển đổi model từ /model.
Câu hỏi thường gặp
Tệp Codex config.toml nằm ở đâu?
Trên macOS và Linux, tệp nằm tại ~/.codex/config.toml; trên Windows, tệp nằm tại C:\Users<you>.codex\config.toml. Nếu đã đặt CODEX_HOME, tệp sẽ nằm trong thư mục đó.
Tôi có cần khởi động lại Codex sau khi thay đổi config.toml không?
Có. Codex đọc tệp khi khởi động, vì vậy hãy thoát rồi mở lại phiên terminal hoặc ứng dụng.
Tại sao Codex báo “cấu hình hồ sơ cũ không còn được hỗ trợ”?
Codex 0.134.0 đã bỏ hỗ trợ các hồ sơ được định nghĩa bên trong config.toml. Chuyển từng hồ sơ vào ~/.codex/name.config.toml, xóa các dòng cũ rồi khởi chạy Codex với --profile name.
Tôi vẫn có thể dùng wire_api = "chat" không?
Không. Codex chỉ chấp nhận wire_api = "responses". Nhà cung cấp chỉ hỗ trợ Chat Completions cần dùng proxy để chuyển đổi sang Responses API.
Tại sao nhà cung cấp tùy chỉnh của tôi trả về lỗi 401 dù tôi đã đăng nhập vào Codex?
Khóa đăng nhập trong auth.json không được gửi đến các nhà cung cấp tùy chỉnh. Hãy thêm env_key vào bảng nhà cung cấp và đặt biến đó trong terminal.
Codex có sử dụng HTTPS_PROXY không?
Có. Trong thử nghiệm trên Codex 0.162.1, các yêu cầu được chuyển qua HTTPS_PROXY và bỏ qua những máy chủ được liệt kê trong NO_PROXY. Tệp PAC không được hỗ trợ.
Tại sao model_provider bị bỏ qua trong tệp .codex/config.toml của dự án?
Tệp dự án không thể thay đổi nơi yêu cầu được gửi đến, vì vậy kho mã không thể chuyển hướng lưu lượng truy cập của bạn. Hãy khai báo nhà cung cấp trong ~/.codex/config.toml; tệp dự án vẫn có thể thiết lập model.
Nguồn
- Thông tin cơ bản về cấu hình, OpenAI
- Cấu hình nâng cao, OpenAI
- Tài liệu tham khảo cấu hình, OpenAI
- Hướng dẫn tích hợp Codex CLI, AIHubMix
- Cấu hình proxy cho Codex CLI: SOCKS, HTTP và mạng doanh nghiệp, Daniel Vaughan
