Cài Codex từ đầu trên Windows và macOS: từ mở terminal đến kết nối API và dùng ứng dụng desktop

Hướng dẫn từng bước cho người mới, có cách cài tự động, cấu hình thủ công và bài tập kiểm tra bằng một tệp nhỏ.

Bạn đã tìm được lệnh cài Codex nhưng chưa biết dán vào đâu? Hoặc CLI đã hiện phiên bản, còn ứng dụng desktop vẫn báo thiếu API key? Hai tình huống này nằm ở những bước khác nhau. Hiểu thứ tự xử lý sẽ giúp bạn tránh cài lại phần mềm mỗi khi gặp lỗi kết nối.

Lộ trình dưới đây là: chuẩn bị key, chọn một cách cài CLI, nhận câu trả lời đầu tiên, rồi chuyển sang desktop. Mục 2 và mục 3 là hai lựa chọn thay thế nhau. Làm xong một lựa chọn thì chuyển đến mục 4.

1. Chuẩn bị tài khoản và hiểu ba thành phần cần dùng

CLI là chương trình chạy trong terminal. Ứng dụng desktop có giao diện đồ họa và cần cài riêng. API key là thông tin xác thực để chương trình gọi dịch vụ; nó không phải mật khẩu đăng nhập máy tính hay mật khẩu website.

Ví dụ dùng Crazyrouter. Mở hướng dẫn kết nối Codex, vào phần đăng ký của website, điền thông tin và hoàn thành xác minh email theo yêu cầu. Sau đó đăng nhập bảng điều khiển.

Ảnh chụp trang đăng ký thật; một số giao diện nguồn sử dụng tiếng Trung.

Tìm phần quản lý API key hoặc token. Tài liệu dịch vụ gọi phần này là “Token Management”, với thao tác “Create Token”. Tạo token, kiểm tra thời hạn, hạn mức và quyền truy cập mô hình, rồi sao chép key bằng nút của trang.

Ví dụ bên dưới dùng gpt-5.6-sol. Token phải được phép gọi mô hình này và tài khoản cần có số dư sử dụng được. Đăng ký không đồng nghĩa với được cấp lượt gọi miễn phí. Script cài đặt cũng không tự đăng ký hay nạp tiền thay bạn.

Lý do cân nhắc dịch vụ trung gian thường là so sánh giá mô hình và quản lý nhiều mô hình trong một tài khoản. Tuy nhiên, cần xem cả giá đầu vào, đầu ra, hỗ trợ Responses API và cách xử lý sự cố. API chính thức vẫn là một lựa chọn; gói ChatGPT và phí API theo mức sử dụng không phải cùng một sản phẩm. Nếu gói đang có đã đáp ứng nhu cầu, nên kiểm tra quyền lợi đó trước khi mua thêm.

2. Cách nhanh: dùng script đúng chế độ

full dành cho lần đầu: kiểm tra Git, Node.js, Codex CLI, bổ sung thành phần còn thiếu và cấu hình kết nối. switch dành cho máy đã có CLI, chỉ cần đổi cấu hình. Cả hai đều yêu cầu key của bạn và không cài ứng dụng desktop.

Lệnh tắt trong ảnh dùng switch. Khi cài lần đầu, chọn full như phần dưới.

Trên Windows

Nhấn phím Windows, tìm “PowerShell” và chọn mở. Khi thấy dòng PS C:\Users\...> cùng con trỏ, cửa sổ đã sẵn sàng nhận lệnh.

Sao chép dòng đầu bằng Ctrl+C, dán vào PowerShell bằng Ctrl+V, rồi nhấn Enter. Làm tương tự với dòng thứ hai. Không sao chép dấu nhắc PS ...> hoặc nhãn ngôn ngữ của khối mã.

Các lệnh dưới đây tải một phiên bản cố định của script và thay địa chỉ API cũ trước khi chạy. Cấu hình được tạo và OPENAI_BASE_URL cùng dùng https://api.crazyrouter.com/v1; kho mã nguồn gốc không bị sửa. Hãy sao chép lệnh đã sửa bên dưới, không dùng lệnh trong ảnh chụp cũ.

$env:CRAZYROUTER_CODEX_MODE='full'
(Invoke-WebRequest -UseBasicParsing -ErrorAction Stop 'https://raw.githubusercontent.com/xujfcn/crazyrouter-codex-cli/b68d1db167950df4ab597b853ca0aec1b16295b8/install-crazyrouter-codex.ps1').Content.Replace('https://cn.crazyrouter.com/v1', 'https://api.crazyrouter.com/v1') | Invoke-Expression

Nếu đã có CLI, đổi 'full' thành 'switch' ở dòng đầu. Dòng đầu có thể không in gì vì chỉ chọn chế độ. Dòng thứ hai tải và chạy script công khai; bạn có thể xem mã nguồn qua trang tích hợp trước khi chạy.

Chế độ full có thể mở trình cài đặt hoặc hộp thoại quyền và sử dụng tùy chọn chấp nhận thỏa thuận phần mềm. Hãy đọc tên chương trình trong các thông báo đó.

Khi được hỏi API key, chỉ dán key rồi nhấn Enter, không thêm dấu nháy hay Bearer. Ký tự bị ẩn khi nhập là bình thường. Tiếp theo, chỉ chấp nhận mô hình mặc định nếu token có quyền dùng; nếu không, nhập ID tương thích mà tài khoản cho phép. Chờ hoàn tất, đóng toàn bộ PowerShell hoặc Windows Terminal rồi mở lại.

Trên macOS

Nhấn Command+Space, tìm Terminal và nhấn Return. Dán bằng Command+V, chạy từng dòng bằng Return. Các bước này dùng zsh; nếu bạn dùng shell khác, hãy chạy zsh trước.

touch ~/.zshrc
curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-codex-cli/b68d1db167950df4ab597b853ca0aec1b16295b8/install-crazyrouter-codex.sh | sed 's#https://cn\.crazyrouter\.com/v1#https://api.crazyrouter.com/v1#g' | bash -s -- --full

Dòng đầu bảo đảm tệp cấu hình zsh tồn tại mà không xóa nội dung cũ. Đã có CLI thì thay --full bằng --switch. Nhập key và mô hình khi từng lời nhắc xuất hiện. Nếu trình cài yêu cầu mật khẩu hệ thống, đó là mật khẩu đăng nhập Mac.

Nếu thiếu Git, chạy xcode-select --install, hoàn thành cài công cụ phát triển và kiểm tra git --version trước khi thử lại script. Sau khi hoàn tất:

source ~/.zshrc
codex --version

Nếu npm đã cài thành công nhưng không tìm thấy codex, thử thêm đường dẫn tạm thời:

export PATH="$PATH:$(npm config get prefix)/bin"
codex --version

Nếu cách này giải quyết được lỗi, mở nano ~/.zshrc, lưu đúng dòng export vào tệp. Trong nano, nhấn Control+O, Return để lưu, rồi Control+X để thoát. Sau cách cài tự động, chuyển đến mục 4.

3. Cách thủ công: tách chương trình, cấu hình và key

Đây là lựa chọn dành cho người muốn biết từng thiết lập được lưu ở đâu. Nếu đã hoàn tất script, không cần làm lại mục này.

Cài CLI

Windows: tải Node.js LTS từ website chính thức, chọn đúng kiến trúc máy và giữ tùy chọn PATH. Mở lại PowerShell rồi chạy từng dòng:

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

Hai dòng đầu phải hiện phiên bản trước khi tiếp tục cài. Nếu cần Git, cài từ website Git for Windows chính thức. macOS có thể dùng trình cài CLI độc lập chính thức, không cần cài Node.js trước:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Làm theo hướng dẫn PATH của trình cài, mở lại terminal và kiểm tra codex --version.

Ghi cấu hình kết nối

Trên Windows, các lệnh sau tạo thư mục, sao lưu cấu hình đã có và mở Notepad:

$codexConfigDir = Join-Path $env:USERPROFILE '.codex'
New-Item -ItemType Directory -Path $codexConfigDir -Force | Out-Null
$codexConfigPath = Join-Path $env:USERPROFILE '.codex\config.toml'
if (Test-Path -LiteralPath $codexConfigPath) { Copy-Item -LiteralPath $codexConfigPath -Destination ($codexConfigPath + '.backup-' + (Get-Date -Format 'yyyyMMdd-HHmmss')) }
if (-not (Test-Path -LiteralPath $codexConfigPath)) { New-Item -ItemType File -Path $codexConfigPath | Out-Null }
notepad.exe $codexConfigPath

Trên Mac:

mkdir -p ~/.codex
if [ -f ~/.codex/config.toml ]; then cp ~/.codex/config.toml ~/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S); fi
nano ~/.codex/config.toml

Dán nội dung sau vào trình soạn thảo vừa mở, không chạy trong terminal:

Giữ nguyên dấu xuống dòng khi dán cấu hình vào tệp. Mỗi thiết lập và tiêu đề mục trong ngoặc vuông phải nằm trên một dòng riêng. Không gộp thành một dòng hoặc sao chép nhãn ngôn ngữ.

model = "gpt-5.6-sol"
model_provider = "crazyrouter"

[model_providers.crazyrouter]
name = "Crazyrouter"
base_url = "https://api.crazyrouter.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Nếu tệp đã có thiết lập, sửa các trường tương ứng và giữ phần không liên quan. Hai trường trên cùng nằm trước section đầu tiên có dấu ngoặc vuông; không tạo hai section nhà cung cấp trùng tên.

Lưu Notepad bằng Ctrl+S, tránh tên config.toml.txt. Với nano: Control+O, Return, rồi Control+X.

env_key là tên biến môi trường; giá trị bí mật được lưu riêng.

Cả hai cách đều dùng https://api.crazyrouter.com/v1, không thêm /responses.

Lưu key

Windows bắt đầu bằng lời nhắc nhập ẩn:

$codexApiKey = Read-Host 'Paste your API Key, then press Enter' -AsSecureString

Dán key tại lời nhắc rồi nhấn Enter. Khi dấu nhắc PowerShell trở lại, chạy:

[Environment]::SetEnvironmentVariable('OPENAI_API_KEY', ([System.Net.NetworkCredential]::new('', $codexApiKey)).Password, 'User')
Remove-Variable codexApiKey

Lệnh cập nhật biến của người dùng; công cụ khác cũng có thể đang dùng biến này. Đóng toàn bộ ứng dụng terminal rồi mở mới để nhận giá trị.

Mac: chạy nano ~/.zshrc, thêm hoặc sửa dòng:

export OPENAI_API_KEY='YOUR_API_KEY'

Thay phần giữ chỗ bằng key của bạn, giữ dấu nháy. Lưu và chạy source ~/.zshrc. Tệp chứa key dạng văn bản rõ, không đưa vào Git hay ảnh chụp chia sẻ.

4. Xác nhận bằng một yêu cầu nhỏ

Kiểm tra tiến trình hiện tại có đọc được biến hay không. Windows:

if ([string]::IsNullOrWhiteSpace($env:OPENAI_API_KEY)) { 'KEY_MISSING' } else { 'KEY_FOUND' }

Mac:

if [ -n "${OPENAI_API_KEY:-}" ]; then echo KEY_FOUND; else echo KEY_MISSING; fi

KEY_FOUND chỉ xác nhận có giá trị, chưa xác nhận quyền sử dụng. Tạo thư mục thực hành trên Windows:

$codexPracticeDir = Join-Path $env:USERPROFILE 'Projects\codex-first-test'
New-Item -ItemType Directory -Path $codexPracticeDir -Force | Out-Null
Set-Location -LiteralPath $codexPracticeDir
codex

Trên Mac:

mkdir -p ~/Projects/codex-first-test
cd ~/Projects/codex-first-test
codex

Nếu PowerShell chặn codex.ps1, dùng codex.cmd. Kiểm tra đúng thư mục nếu có câu hỏi về độ tin cậy. Trong ô hội thoại Codex, gửi:

Hãy giải thích công dụng của tệp README bằng ba câu. Không đọc hoặc sửa bất kỳ tệp nào.

Ngày 14/10/2026, câu hỏi tương đương bằng tiếng Trung đã nhận được phản hồi qua CLI không tương tác trên Windows, với cả cấu hình thủ công và cấu hình từ script. Môi trường dùng Node.js 24.21.0, npm 11.19.0, Git 2.53.0 và CLI 0.162.1.

Máy đã có sẵn các phụ thuộc. Kết quả đó không đại diện cho cài đặt trên máy trắng, thử nghiệm Mac hay yêu cầu độc lập từ desktop. Hãy ghi giờ gọi của bạn và đối chiếu nhật ký sử dụng. Số token còn có thể bao gồm ngữ cảnh của công cụ, không chỉ số chữ trong câu hỏi.

5. Cài desktop và kiểm tra lại môi trường của ứng dụng

Tải từ hướng dẫn cài ứng dụng chính thức. Trang hiện gọi giao diện chung là “ChatGPT desktop app”; sau khi mở, chọn Codex trong menu sản phẩm. Quyền dùng tính năng bằng API key có thể khác gói đăng nhập qua thuê bao.

Cài desktop là bước riêng, không nằm trong script CLI.

Windows làm theo trình cài hoặc Microsoft Store được cung cấp. Nếu ứng dụng đã mở trước lúc lưu key, thoát hoàn toàn rồi mở lại. Chọn %USERPROFILE%\Projects\codex-first-test làm thư mục làm việc và gửi lại câu hỏi README trong cuộc trò chuyện mới.

Trên Mac, vào menu Apple → About This Mac để xác định Apple silicon hay Intel, chọn gói phù hợp và kiểm tra yêu cầu macOS. Với .dmg, kéo ứng dụng vào Applications theo hướng dẫn; với .pkg, làm theo trình cài.

Chọn theo bộ xử lý của máy, không theo trình duyệt đang dùng.

Ứng dụng mở từ Dock không tự đọc .zshrc. Thoát bằng Command+Q, tải key trong terminal, xác nhận KEY_FOUND rồi truyền biến vào phiên đăng nhập đồ họa:

source ~/.zshrc
launchctl setenv OPENAI_API_KEY "$OPENAI_API_KEY"

Mở lại ứng dụng. Trong hộp chọn thư mục, nhấn Command+Shift+G và nhập ~/Projects/codex-first-test. Gửi lại câu hỏi. Biến truyền theo cách này chỉ tồn tại trong phiên hiện tại; sau đăng xuất hoặc khởi động lại phải thực hiện lại.

Việc dùng chung cấu hình giả định cùng người dùng cục bộ và thư mục mặc định. WSL, tài khoản khác hoặc thư mục cấu hình riêng cần được kiểm tra như môi trường khác.

6. Chuyển từ câu trả lời sang một thay đổi quan sát được

API trả lời được chưa chứng minh Codex có quyền lưu tệp. Trong CLI, mở /permissions; trên desktop, xem bộ chọn quyền dưới ô nhập. Chế độ “Ask for approval” trong tài liệu cho phép thao tác trong workspace và hỏi khi vượt ra ngoài. Chính sách cấp cao hơn vẫn có thể giới hạn ghi.

Đây là ảnh tài liệu về quyền, không phải bằng chứng đã lưu tệp thành công.

Trong thư mục thực hành, gửi:

Hãy thực sự tạo learning-checklist.md trong thư mục hiện tại, mã hóa UTF-8.
Đặt tiêu đề “Bài tập Codex” và ba việc chưa đánh dấu hoàn thành theo cú pháp Markdown:
- Cấu hình CLI
- Nhận phản hồi API
- Sửa tệp cục bộ
Chỉ tạo tệp này, không cài phần mềm hay sửa tệp khác. Cho biết đường dẫn đã lưu.

Mở tệp thật bằng Explorer hoặc Finder. Sau đó yêu cầu chỉ đánh dấu hai mục đầu, rồi kiểm tra có hai dòng - [x] và một dòng - [ ]. Trong môi trường kiểm tra trước đó, việc ghi bị chính sách chỉ đọc từ chối, nên bài tập này không được trình bày như một kết quả ghi tệp đã thành công.

Khi gặp lỗi, chọn đúng nhóm để kiểm tra: không tìm thấy lệnh thì xem cài đặt và PATH; 401 thì xem key, thời hạn và nhà cung cấp; 403 cần nội dung lỗi cùng quyền mô hình. Chỉ desktop lỗi thì so sánh môi trường tiến trình. Trả lời được nhưng không ghi được thì kiểm tra thư mục và quyền. Mỗi lần chỉ sửa phần có bằng chứng liên quan, rồi lặp lại một yêu cầu nhỏ.