Một phiên sửa lỗi bằng agent dòng lệnh thường phụ thuộc tốc độ mạng và thời gian phản hồi của mô hình nhiều hơn bộ xử lý laptop. Codex CLI đọc mã nguồn, chỉnh sửa tệp và thực thi lệnh ngay trong terminal, nhưng tài liệu cài đặt chính thức của OpenAI xếp Windows vào diện chạy qua WSL2 chứ không phải môi trường Windows nguyên bản. Bài này đi theo đúng thứ tự đó: kích hoạt WSL2, cài gói npm, xác thực tài khoản rồi mở rộng bằng MCP.
Codex CLI đòi hỏi gì ở laptop Windows trước khi cài đặt
Tài liệu cài đặt trong kho mã của OpenAI ghi rõ ba nền tảng khả dụng: macOS 12 trở lên, Ubuntu 20.04 hoặc Debian 10 trở lên, và Windows 11 thông qua WSL2. Ngưỡng bộ nhớ tối thiểu là 4 GB RAM, mức khuyến nghị là 8 GB. Git từ phiên bản 2.23 trở lên không bắt buộc nhưng được khuyến nghị cho các thao tác liên quan tới pull request. Codex CLI gửi yêu cầu suy luận lên máy chủ nên card đồ họa rời không mang lại ưu thế đáng kể.
| Thành phần | Yêu cầu theo tài liệu chính thức | Vai trò trong quy trình |
|---|---|---|
| Hệ điều hành | Windows 11 qua WSL2 (macOS 12+ hoặc Ubuntu 20.04+ nếu dùng nền khác) | Cung cấp nhân Linux để agent chạy lệnh đúng phân quyền |
| Bộ nhớ RAM | Tối thiểu 4 GB, khuyến nghị 8 GB | Nuôi đồng thời máy ảo WSL2 và trình biên tập |
| Node.js và npm | Gói npm khai báo engines node từ 16 trở lên | Môi trường thực thi để cài gói toàn cục |
| Git | Từ 2.23 trở lên, tùy chọn nhưng nên có | Ghi nhận thay đổi và hỗ trợ thao tác pull request |
| Giấy phép gói | Apache-2.0 theo khai báo trên npm và kho GitHub | Tệp cài đặt miễn phí, chi phí nằm ở quyền gọi mô hình |
Hai cột trên tách bạch một điểm hay bị gộp nhầm: bản thân giao diện dòng lệnh là mã nguồn mở Apache-2.0, còn quyền suy luận vẫn tính qua tài khoản ChatGPT hoặc khóa API. Vì vậy bạn không cần tải tệp cài từ nguồn chia sẻ, không cần keygen và cũng không cần mua bản quyền phần mềm rời. Kho mã chính thức nằm ở kho GitHub openai/codex, nơi công bố cả mã nguồn lẫn tài liệu cài đặt.
Với máy 8 GB RAM, tôi khuyên tắt bớt máy ảo và container khi mở phiên agent vì WSL2 chiếm thêm bộ nhớ bên cạnh trình duyệt và trình biên tập. Cấu hình 16 GB thoải mái hơn khi bạn vừa chạy agent, vừa mở Docker Desktop. Cách chia bộ nhớ cho tác vụ container được phân tích kỹ trong bài chọn laptop chạy mượt Docker nên ưu tiên RAM.
Kích hoạt WSL2 và cài Ubuntu bằng lệnh PowerShell chạy quyền quản trị
Mở PowerShell ở chế độ quản trị rồi chạy wsl --install để cài WSL kèm bản phân phối mặc định, hoặc wsl --install -d Ubuntu-24.04 nếu muốn chỉ định bản phân phối. Tài liệu của Microsoft yêu cầu Windows 10 phiên bản 2004 build 19041 trở lên hoặc Windows 11; riêng WSL2 cần Windows 11 hoặc Windows 10 phiên bản 1903 build 18362 trở lên. Sau khi cài xong, hãy khởi động lại máy theo hướng dẫn hiển thị trong cửa sổ lệnh.
Danh sách bản phân phối khả dụng lấy bằng wsl --list --online, viết tắt là wsl -l -o. Muốn xem bản đã cài kèm số hiệu phiên bản thì dùng wsl --list --verbose, còn wsl --status trả về bản phân phối mặc định và phiên bản nhân đang chạy. Quy trình đầy đủ nằm trong tài liệu cài đặt WSL của Microsoft.
Nếu máy từng bật WSL1, hãy chạy wsl --set-default-version 2 để mọi bản phân phối cài mới đều dùng WSL2. Bước này quan trọng vì phần lớn lỗi phân quyền mà bạn gặp khi thao tác tệp thực chất đến từ việc chạy nhầm nhân cũ hoặc làm việc trên phân vùng Windows. Sau lệnh trên, mở lại Ubuntu và tạo tài khoản Linux kèm mật khẩu, đó là nơi Codex CLI sẽ chạy.
Cài Codex CLI trong Ubuntu rồi xác nhận phiên bản vừa nhận
Trong cửa sổ Ubuntu, kiểm tra môi trường trước bằng node -v, npm -v và git --version. Ba lệnh này cho biết Node.js đã đáp ứng ngưỡng engines node từ 16 trở lên hay chưa, đồng thời xác nhận Git đạt mốc 2.23. Nếu Ubuntu mới cài chưa có Node.js, bạn cài qua trình quản lý phiên bản Node rồi chọn một bản LTS để tránh xung đột với dự án JavaScript cũ.
Lệnh cài đặt chính là npm install -g @openai/codex, chú ý tên gói viết thường hoàn toàn. Gói này khai báo tệp thực thi tên codex, nên sau khi cài xong bạn gõ codex để mở phiên đầu tiên. Muốn xác nhận bản vừa nhận thì chạy npm list -g @openai/codex, kết quả trả về số hiệu phiên bản đang có trên máy thay vì con số bạn phải đoán.
Trên macOS và Linux còn một đường cài khác là kịch bản curl -fsSL https://chatgpt.com/codex/install.sh | sh do OpenAI phát hành. Trên Windows, tôi vẫn ưu tiên cài Codex CLI bằng npm bên trong WSL2 vì nó nằm gọn trong không gian tệp Linux, dễ gỡ và dễ cài lại. Cách này cũng giữ mọi cấu hình của agent trong thư mục nhà của tài khoản Ubuntu.
Vì sao mã nguồn nên nằm trong thư mục Linux thay vì ổ C
Microsoft khuyến nghị không làm việc chéo hệ điều hành với tệp dự án. Tài liệu về hệ thống tệp WSL nói thẳng rằng khi bạn thao tác trong dòng lệnh Linux thì nên lưu tệp trong hệ thống tệp của WSL, và nêu ví dụ đường dẫn nên dùng là /home/<user name>/Project thay cho /mnt/c/Users/<user name>/Project. Tài liệu cũng ghi nhận tốc độ sẽ tốt hơn khi tệp nằm trực tiếp trên ổ WSL.
Điều đó tương ứng với thao tác cụ thể: tạo thư mục kiểu ~/projects/ten-du-an ngay trong Ubuntu, clone kho mã vào đó rồi mới mở agent. Khi dự án nằm ở /mnt/c/, mỗi thao tác đọc ghi phải đi qua lớp chuyển tiếp giữa hai hệ thống tệp, và đó cũng là nơi phát sinh phần lớn cảnh báo quyền truy cập mà bạn thấy trong terminal.
Visual Studio Code mở dự án WSL qua tiện ích mở rộng dành cho môi trường từ xa nên bạn vẫn giữ được giao diện quen thuộc trong khi tệp vật lý nằm bên Linux. Cách bố trí này giúp agent, trình biên tập và bộ test cùng nhìn thấy một đường dẫn duy nhất, tránh tình trạng mỗi công cụ hiểu một kiểu về quyền sở hữu tệp.
Xác thực tài khoản và phân quyền cho phiên làm việc đầu tiên
Theo hướng dẫn của OpenAI, lần đầu chạy Codex CLI bằng lệnh codex bạn sẽ được nhắc đăng nhập, chọn giữa tài khoản ChatGPT hoặc khóa API lấy từ bảng điều khiển. Đăng nhập bằng tài khoản ChatGPT mở một cửa sổ trình duyệt để xác thực, cách này tiện vì bạn không phải dán chuỗi khóa dài vào terminal. Các gói ChatGPT Plus, Pro, Business, Edu và Enterprise đều bao gồm quyền dùng Codex.
Thông tin đăng nhập được lưu tại ~/.codex/auth.json hoặc trong kho lưu khóa của hệ điều hành, tùy thiết lập cli_auth_credentials_store trong tệp cấu hình. Với môi trường doanh nghiệp, khóa API nên nằm trong biến môi trường hoặc kho quản lý bí mật, tuyệt đối không ghi vào mã nguồn và không đẩy lên Git.
Trước lần chạy thật đầu tiên, hãy đọc kỹ phạm vi quyền mà agent xin cấp. Chế độ chỉ đọc đủ để khảo sát kiến trúc dự án; quyền chỉnh sửa nên bật trong một nhánh Git riêng. Quyền thực thi lệnh cần cơ chế phê duyệt từng bước vì lệnh cài gói, xóa thư mục hoặc chạy migration có thể thay đổi cơ sở dữ liệu và tệp cấu hình.
Cách tập dượt an toàn là tạo một repository thử nghiệm, nạp dữ liệu giả rồi yêu cầu agent trình bày kế hoạch trước khi sửa. Sau mỗi tác vụ, bạn kiểm tra git diff, chạy bộ test và duyệt lại danh sách tệp thay đổi. Thói quen này giữ cho mọi thay đổi tự động đều có thể hoàn tác.
Cấu hình máy chủ MCP cho Codex CLI qua tệp config.toml
MCP cho phép agent kết nối tới nguồn dữ liệu hoặc công cụ bên ngoài qua máy chủ tương thích, chẳng hạn đọc tài liệu nội bộ hay truy vấn hệ thống quản lý công việc. Tài liệu của OpenAI cho biết cấu hình mặc định nằm ở ~/.codex/config.toml, ngoài ra có thể khai báo theo từng dự án bằng tệp .codex/config.toml đặt trong dự án được đánh dấu tin cậy.
Với máy chủ dùng cơ chế OAuth, tài liệu mô tả lệnh codex mcp login kèm tên máy chủ để mở luồng đăng nhập riêng khi chưa có nguồn thông tin xác thực nào phù hợp. Vì cấu trúc tệp cấu hình có thể thay đổi theo bản phát hành, bạn nên chạy lệnh trợ giúp của bản đang cài và đối chiếu tài liệu trước khi chép nguyên một mẫu cấu hình cũ.
Mỗi máy chủ MCP mở rộng phạm vi dữ liệu mà agent tiếp cận, nên nguyên lý cấp quyền tối thiểu vẫn giữ giá trị. Hãy dùng tài khoản chỉ đọc khi có thể và tách môi trường thử nghiệm khỏi dữ liệu vận hành. Đừng nối thẳng vào cơ sở dữ liệu sản xuất hoặc kho hồ sơ khách hàng nếu chưa có nhật ký truy cập và quy trình thu hồi khóa.
Lỗi thường gặp khi chạy Codex CLI trên nền Windows và cách xử lý
Lỗi phổ biến nhất là gõ sai tên gói. Tên đúng viết thường hoàn toàn theo khai báo trên npm, mọi biến thể viết hoa đều dẫn tới thông báo không tìm thấy gói. Trường hợp thứ hai là cài gói toàn cục bằng quyền quản trị của Windows rồi chạy trong WSL2, khiến hai môi trường trỏ về hai thư mục npm khác nhau; cách xử lý gọn nhất là cài lại trong Ubuntu.
Nhóm lỗi thứ ba đến từ vị trí dự án. Khi mã nguồn nằm trên phân vùng Windows, quyền sở hữu tệp do lớp chuyển tiếp quyết định nên lệnh đổi quyền chạy trong Ubuntu có thể không giữ được kết quả. Chuyển dự án về thư mục nhà của Ubuntu là cách xử lý đúng gốc cho Codex CLI, phù hợp với khuyến nghị của Microsoft.
Nhóm cuối liên quan tới xác thực. Nếu cửa sổ trình duyệt không tự mở, bạn có thể chép đường dẫn hiển thị trong terminal sang trình duyệt Windows. Khi phiên đăng nhập hỏng, xóa tệp thông tin xác thực trong thư mục cấu hình rồi chạy lại là đủ. Cách vận hành này khá gần Claude Code, bạn có thể đối chiếu qua bài Claude Code và Copilot công cụ nào sửa lỗi code hiệu quả hơn.
Nếu đã có laptop 8 GB RAM trở lên và ổ SSD, bạn chưa cần nâng cấp máy chỉ để dùng agent dòng lệnh. Cấu hình 16 GB đáng cân nhắc khi dự án lớn hoặc bạn chạy song song container. Người cần làm việc ngoại tuyến hoàn toàn, hoặc xử lý mã nguồn bị cấm gửi ra dịch vụ bên ngoài, sẽ không phù hợp với công cụ này nếu thiếu hạ tầng và chính sách tương ứng.
Câu hỏi thường gặp (FAQ)
Cài Codex CLI có mất phí bản quyền phần mềm không?
Gói npm được phát hành theo giấy phép Apache-2.0 nên bạn không phải mua tệp cài đặt. Chi phí phát sinh nằm ở quyền gọi mô hình, thông qua gói thuê bao ChatGPT hoặc thanh toán API. Nên đặt hạn mức chi tiêu trong tài khoản trước khi giao việc thật cho agent.
Codex CLI chạy được trên Windows mà không cần WSL2 không?
Phần yêu cầu hệ thống trong tài liệu cài đặt của OpenAI liệt kê Windows 11 kèm WSL2, không nêu đường chạy trực tiếp trên Windows trong cùng mục đó. Vì vậy tôi khuyên chạy Codex CLI theo đường WSL2 để tránh khác biệt về phân quyền và đường dẫn tệp.
Laptop cấu hình nào đủ cho Codex CLI và WSL2 cùng lúc?
Tài liệu chính thức đặt mức tối thiểu 4 GB RAM và khuyến nghị 8 GB. Thực tế nếu bạn mở thêm trình biên tập, trình duyệt và container thì 16 GB dễ thở hơn. Card đồ họa rời không cần thiết vì phần suy luận diễn ra trên máy chủ của nhà cung cấp.
Để lại một bình luận