Hướng dẫn đầy đủ cài đặt Codex CLI trên Windows: Node.js, npm.ps1 và biến môi trường

Khi cài đặt Codex CLI trên Windows, các vấn đề chủ yếu xoay quanh Node.js, npm, PowerShell và biến môi trường. Bài viết trình bày các bước theo đúng thứ tự thực hiện, đồng thời phân tích cách khắc phục một số lỗi thường gặp.

Bài viết chỉ tập trung vào việc cài đặt và sử dụng cơ bản Codex CLI.

1. Kiểm tra trước khi cài đặt

Mở PowerShell và chạy lần lượt từng lệnh sau:

node --version
npm --version

Nếu cả hai lệnh đều hiển thị số phiên bản, bạn có thể chuyển thẳng đến phần «Cài đặt Codex CLI».

Nếu node hoặc npm không được nhận diện, thường có hai nguyên nhân:

• Node.js chưa được cài đặt trên máy tính.
• Node.js đã được cài, nhưng cửa sổ terminal hiện tại chưa nạp lại biến môi trường mới.

2. Cài đặt Node.js

Truy cập trang chủ chính thức của Node.js:

https://nodejs.org/

Tải bản LTS dành cho Windows và làm theo trình hướng dẫn cài đặt. Thông thường chỉ cần giữ nguyên các tùy chọn mặc định.

Sau khi cài xong, đóng cửa sổ PowerShell cũ, mở cửa sổ mới rồi kiểm tra lại:

node --version
npm --version

Nếu số phiên bản hiển thị, nghĩa là Node.js và npm đã sẵn sàng.

3. Xử lý khi npm.ps1 bị chặn thực thi

Trên một số máy Windows, khi chạy npm trong PowerShell sẽ xuất hiện thông báo đại loại như sau:

Không thể tải tệp npm.ps1 vì việc chạy tập lệnh đã bị vô hiệu hóa trên hệ thống này.

Thông thường điều này không có nghĩa là npm bị hỏng: chính sách thực thi tập lệnh (Execution Policy) của PowerShell đang chặn npm.ps1.

Mà không cần thay đổi chính sách thực thi, bạn có thể gọi trực tiếp tệp lệnh npm dành cho Windows:

npm.cmd --version

Nếu lệnh hiển thị số phiên bản, thì ở bước cài đặt Codex CLI sau đó bạn cũng có thể dùng npm.cmd.

Trên máy tính cá nhân, sau khi đã chắc chắn về nguồn gốc đáng tin cậy của tập lệnh, bạn cũng có thể đặt RemoteSigned chỉ cho người dùng hiện tại:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Sau khi thay đổi, hãy mở lại PowerShell. Trên các máy do công ty hoặc trường học quản lý, có thể tồn tại các hạn chế của tổ chức; trong trường hợp đó hãy liên hệ quản trị viên.

4. Cài đặt Codex CLI

Chạy trong PowerShell:

npm.cmd install -g @openai/codex@latest

Sau khi cài đặt, kiểm tra phiên bản:

codex.cmd --version

Nếu hiển thị codex-cli cùng số phiên bản, nghĩa là công cụ dòng lệnh đã được cài đặt thành công. Chạy qua codex.cmd giúp tránh việc tập lệnh cùng tên codex.ps1 bị PowerShell chặn.

Để cập nhật về sau, chạy lại:

npm.cmd install -g @openai/codex@latest
codex.cmd --version

5. Sau khi cài đặt vẫn không tìm thấy lệnh codex

Nếu quá trình cài đặt không báo lỗi nhưng hệ thống vẫn không nhận diện codex, trước tiên hãy đóng cửa sổ PowerShell hiện tại và mở một cửa sổ mới.

Sau đó chạy:

Get-Command codex.cmd -ErrorAction SilentlyContinue
npm.cmd config get prefix

Lệnh thứ nhất kiểm tra xem hệ thống có tìm thấy Codex hay không. Lệnh thứ hai hiển thị thư mục cài đặt toàn cục của npm.

Nếu Get-Command không trả về gì, hãy kiểm tra xem thư mục toàn cục của npm đã được thêm vào biến môi trường Path của người dùng hiện tại hay chưa. Sau khi sửa biến môi trường, cần mở lại terminal để thay đổi có hiệu lực.

6. Chạy Codex trong thư mục dự án

Khuyến nghị trước tiên hãy tạo một thư mục riêng để thực hành. Đừng chạy công cụ xử lý mã nguồn trực tiếp trong toàn bộ thư mục người dùng hoặc trong thư mục chứa nhiều tệp cá nhân.

New-Item -ItemType Directory -Path "$env:USERPROFILE\CodexProjects\demo" -Force
Set-Location "$env:USERPROFILE\CodexProjects\demo"
codex.cmd

Ở lần chạy đầu tiên, hãy xác thực theo cách mà terminal đề xuất. Các phương thức đăng nhập có thể khác nhau tùy theo phiên bản và trạng thái tài khoản; hãy căn cứ vào giao diện hiện tại và hướng dẫn chính thức.

Nếu không thể hoàn tất đăng nhập qua trang xác thực, đừng liên tục thay đổi những thiết lập mà bạn không hiểu rõ, cũng đừng dùng các tập lệnh không rõ nguồn gốc. Hãy kiểm tra lần lượt các điểm sau:

1. Xác nhận thời gian hệ thống và múi giờ được đặt chính xác.
2. Xác nhận trình duyệt mở được trang đăng nhập một cách bình thường.
3. Đóng terminal cũ và chạy lại codex.cmd.
4. Kiểm tra trạng thái tài khoản và khả năng truy cập dịch vụ được hỗ trợ.
5. Đọc hướng dẫn đăng nhập mới nhất trong tài liệu chính thức của Codex.

Tài liệu chính thức của Codex:

https://developers.openai.com/codex/cli/

7. Chọn thư mục tin cậy và thiết lập sandbox

Codex có thể yêu cầu bạn xác nhận tin cậy thư mục hiện tại. Chỉ tiếp tục khi bạn đồng ý cho công cụ đọc và chỉnh sửa các tệp trong thư mục đó.

Trong quá trình sử dụng, khuyến nghị tuân thủ các nguyên tắc sau:

• Chạy công cụ trong một thư mục dự án riêng biệt.
• Kiểm tra lệnh và đường dẫn đích trước khi thực thi.
• Trước khi sửa các tệp quan trọng, hãy dùng hệ thống quản lý phiên bản hoặc tạo bản sao lưu.
• Không để lộ mật khẩu, token và các thông tin xác thực khác trong câu lệnh yêu cầu, mã nguồn hay ảnh chụp màn hình.
• Không tắt toàn bộ cơ chế bảo vệ chỉ vì muốn tiện lợi.

Nếu chỉ cần đọc và phân tích mã nguồn, hãy chọn mức giới hạn chặt chẽ hơn. Chỉ cấp quyền ghi tệp và thực thi lệnh tương ứng với nhu cầu của từng tác vụ cụ thể.

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

1. Lệnh node không được nhận diện

Hãy xác nhận Node.js đã được cài đặt và bạn đã mở lại PowerShell sau khi cài. Nếu vẫn chưa được, hãy kiểm tra xem thư mục cài đặt Node.js có nằm trong Path hay không.

2. Không chạy được npm.ps1

Bạn có thể dùng npm.cmd thay cho npm. Chỉ thay đổi chính sách thực thi của PowerShell cho người dùng hiện tại sau khi đã xác nhận rằng bạn tự quản lý thiết bị và tin tưởng nguồn gốc của tập lệnh.

3. Xuất hiện lỗi quyền truy cập trong quá trình cài đặt

Trước tiên hãy kiểm tra xem thư mục cài đặt toàn cục của npm có thuộc về người dùng hiện tại hay không. Đừng tắt các tính năng bảo vệ của hệ thống và đừng chạy những tập lệnh nâng quyền không rõ nguồn gốc khi chưa xác định được nguyên nhân.

4. codex.cmd --version chạy được nhưng sau khi khởi động lại không đăng nhập được

Điều này thường có nghĩa là bản thân CLI đã được cài đặt. Nhiều khả năng vấn đề nằm ở khâu xác thực, trình duyệt, trạng thái tài khoản, môi trường mạng hoặc khả năng truy cập dịch vụ. Hãy lần lượt kiểm tra các khả năng đó dựa trên thông báo lỗi gốc hiển thị trong terminal.

5. Làm sao biết đang dùng bản Codex nào?

Chạy:

Get-Command codex.cmd | Format-List Name,Source,Version
codex.cmd --version

Hai lệnh này giúp xác định đường dẫn của lệnh và phiên bản hiện tại.

9. Danh sách kiểm tra sau khi cài đặt

• [ ] node --version hiển thị đúng số phiên bản.
• [ ] npm.cmd --version hiển thị đúng số phiên bản.
• [ ] codex.cmd --version hiển thị đúng số phiên bản.
• [ ] Đã mở lại PowerShell để nạp biến môi trường.
• [ ] Codex được chạy trong một thư mục dự án riêng.
• [ ] Đăng nhập bằng phương thức chính thức mà phiên bản hiện tại đề xuất.
• [ ] Không công khai mật khẩu, token và các liên kết chứa tham số nhạy cảm.
• [ ] Các tệp quan trọng đã được sao lưu hoặc đưa vào hệ thống quản lý phiên bản.

Kiểm tra tuần tự Node.js, npm, Codex CLI, bước đăng nhập và thư mục dự án thường giúp tìm ra vấn đề nhanh hơn so với việc thay đổi nhiều thiết lập cùng một lúc. Phiên bản công cụ và giao diện đăng nhập có thể được cập nhật, vì vậy các lựa chọn cụ thể nên được đối chiếu với giao diện Codex hiện tại và tài liệu chính thức.