Cách cài OpenAI Codex CLI lên VPS Ubuntu 24.04 trong 5 phút

OpenAI Codex CLI là cách nhanh nhất để có 1 trợ lý coding agent trên server. Khác với chạy trên laptop hay Mac, VPS giúp bạn để Codex chạy task dài qua đêm, không tốn pin máy chính, và đặc biệt phù hợp khi codebase nằm trên server. Bài này hướng dẫn cài đặt từ đầu trên Ubuntu 24.04 LTS, thời gian khoảng 5-10 phút.

Mình giả định bạn đã có VPS đang chạy Ubuntu 24.04 với quyền sudo. Nếu chưa có VPS, có thể thuê Cloud VPS TND, hệ điều hành đã preinstall sẵn Ubuntu 22/24. Toàn bộ command chỉ dùng terminal, không cần GUI.

Nội dung tập trung vào kiến trúc cài đặt nên không bị lỗi thời theo version. Khi OpenAI ra version mới của Codex CLI, lệnh cài và workflow này vẫn áp dụng được, chỉ con số phụ thuộc thời điểm bạn đọc.

Yêu cầu phần cứng và mạng

Codex CLI tương đối nhẹ vì việc nặng (chạy model AI) được OpenAI xử lý phía server. Tool trên VPS chỉ là client orchestrate, edit file, gọi API. Nên yêu cầu phần cứng thấp.

Quan trọng hơn cấu hình là network: Codex CLI gọi API liên tục, nên latency từ VN ra server OpenAI ảnh hưởng trải nghiệm. VPS đặt ở VN có latency cao tới OpenAI (200-300ms), nhưng bù lại nhanh khi bạn SSH từ máy local. VPS Singapore/Tokyo có latency tới OpenAI thấp hơn nhưng SSH từ VN chậm hơn chút.

Bước 1: cập nhật hệ thống và cài node.js LTS

Codex CLI cần Node.js LTS 20.x trở lên. Ubuntu 24.04 repo mặc định có Node nhưng version cũ. Dùng NodeSource hoặc nvm để cài version mới.

# SSH vào VPS với user thường (không phải root)
ssh user@your-vps-ip

# Cập nhật hệ thống
sudo apt update && sudo apt upgrade -y

# Cài curl nếu chưa có
sudo apt install -y curl ca-certificates

# Cài Node.js 22 LTS qua NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Kiểm tra version
node -v
npm -v

Sau khi chạy xong, node -v phải in ra v22.x.x. Nếu thấy version cũ hơn, kiểm tra lại bước NodeSource. Đừng dùng node của apt mặc định Ubuntu vì có thể quá cũ, Codex CLI sẽ báo lỗi không tương thích.

Bước 2: cấu hình npm để khỏi cần sudo

Mặc định npm install -g cần sudo, nhưng cài Codex CLI dưới sudo có thể gây lỗi quyền sau này. Cấu hình npm dùng thư mục user là practice tốt.

# Tạo thư mục global cho npm trong user home
mkdir -p $HOME/.npm-global
npm config set prefix "$HOME/.npm-global"

# Thêm vào PATH (cho .bashrc hoặc .zshrc)
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> $HOME/.bashrc
source $HOME/.bashrc

# Verify
which npm
echo $PATH | tr ':' 'n' | grep npm-global

Sau bước này, mọi npm install -g sẽ đặt vào $HOME/.npm-global thay vì /usr/lib/node_modules. Tránh được lỗi EACCES kinh điển.

Bước 3: cài Codex CLI qua npm

Codex CLI có package chính thức trên npm. Cài 1 lệnh là xong.

# Cài Codex CLI global
npm install -g @openai/codex

# Kiểm tra cài đặt
codex --version
codex --help

Nếu lệnh codex báo "command not found", chắc chắn PATH đã có $HOME/.npm-global/bin. Mở terminal mới hoặc chạy lại source $HOME/.bashrc. Nếu vẫn lỗi, kiểm tra ls $HOME/.npm-global/bin/ xem file codex có ở đó không.

Bước 4: login bằng tài khoản ChatGPT

Codex CLI dùng OAuth qua browser để xác thực với OpenAI. Trên VPS không có browser, có 2 cách: dùng device code flow (cho copy code sang máy có browser) hoặc forward port SSH.

# Cách 1: login flow tự động, Codex sẽ in URL để bạn mở trên máy local
codex login

# Codex sẽ in một URL dạng https://chatgpt.com/oauth?code=...
# Copy URL đó, dán vào browser trên laptop/Mac của bạn
# Login bằng tài khoản ChatGPT Plus/Pro/Business
# Sau khi approve, Codex CLI tự nhận token và lưu vào ~/.codex/auth.json

Quy trình thường mất 30 giây. Token lưu local trên VPS, dùng cho các session sau mà không cần login lại. Nếu VPS bị reset hoặc bạn xóa thư mục $HOME/.codex, phải login lại.

Bước 5: chạy task Codex đầu tiên

Sau khi login, test bằng task đơn giản trong thư mục code thực tế. Clone 1 repo nhỏ hoặc tạo project mới.

# Tạo project test
mkdir -p $HOME/projects/test-codex
cd $HOME/projects/test-codex

# Khởi tạo git để Codex có thể commit
git init
git config user.email "[email protected]"
git config user.name "Your Name"

# Tạo file đơn giản
echo "console.log('hello');" > app.js

# Mở Codex CLI trong thư mục này
codex

Một interactive prompt sẽ xuất hiện. Gõ thử "Thêm function tính tổng 2 số vào app.js" và xem Codex edit file, tạo commit. Nếu mọi thứ chạy đúng, bạn đã sẵn sàng.

Bước 6: chạy headless trong tmux để task dài qua đêm

Đây là lý do chính cài Codex trên VPS thay vì laptop. Tmux giữ session sống ngay cả khi bạn đóng SSH. Bạn cho Codex chạy task lớn, đi ngủ, sáng mở SSH lại là thấy kết quả.

# Cài tmux nếu chưa có
sudo apt install -y tmux

# Tạo session named "codex"
tmux new -s codex

# Trong tmux, chạy Codex như bình thường
cd $HOME/projects/main-project
codex

# Detach mà giữ session: Ctrl+B sau đó D
# Đóng SSH, đi ngủ

# Sáng sau, SSH lại và attach
ssh user@your-vps-ip
tmux attach -t codex

Có thể tạo nhiều session cho nhiều project song song: tmux new -s codex-projectA, tmux new -s codex-projectB. List session bằng tmux ls.

Bước 7: cấu hình AGENTS.md cho project

AGENTS.md (hoặc file tương tự tùy version Codex CLI) là instruction file đặt ở root project. Codex đọc file này mỗi lần start session để biết context dự án.

# Mở editor để tạo AGENTS.md ở root project
nano AGENTS.md
# hoặc dùng vim, vi, code tùy preference

Nội dung file AGENTS.md mẫu cho project Next.js TypeScript:

# Project context
Đây là Next.js 14 app cho startup VN.
- Dùng TypeScript strict mode
- Sử dụng Tailwind cho styling
- Test với Vitest, không phải Jest
- Commit message dùng conventional commits: feat, fix, chore
- Không commit file .env

# Folder conventions
- src/components/: React components
- src/lib/: utility functions
- src/app/api/: Next.js route handlers

File này nên commit vào git để team cùng dùng. Khi Codex chạy với AGENTS.md đúng, chất lượng output tăng đáng kể vì tool hiểu convention dự án thay vì đoán.

Troubleshoot các lỗi phổ biến

Sau khi hỗ trợ vài chục dev VN cài Codex CLI trên VPS, đây là các lỗi gặp nhiều nhất:

• Node version cũ: codex báo "Node 16 not supported" - cài Node 22 LTS theo Bước 1.
• EACCES khi npm install -g: chưa setup npm prefix - làm lại Bước 2.
• Login URL không mở được: firewall outbound đang chặn - kiểm tra ufw, iptables.
• Token expired sau vài tuần: chạy codex login lại để refresh.
• Codex báo "rate limit exceeded" ngay sau login: tài khoản chưa có gói Plus/Pro/Business hoặc quota đã dùng hết ở máy khác.
• Time drift trên VPS: đồng hồ VPS lệch giờ thật - cài chrony hoặc ntp.

# Fix time drift
sudo apt install -y chrony
sudo systemctl enable chrony
sudo systemctl start chrony
chronyc tracking
# Đảm bảo dòng "Leap status: Normal" và offset gần 0

Bảo mật cơ bản cho VPS chạy Codex

VPS chạy Codex CLI có chứa code dự án + token OpenAI. Cần khóa cẩn thận để tránh leak.

• Tắt password SSH, chỉ dùng key (PermitRootLogin no, PasswordAuthentication no).
• Cài fail2ban để chặn brute force SSH.
• Bật ufw firewall, chỉ mở port 22 (và port app nếu có).
• Đổi port SSH mặc định 22 sang số khác (3-4 chữ số) để giảm noise log.
• chmod 600 cho $HOME/.codex/auth.json.
• Không clone code khách hàng vào VPS shared với dự án khác - dùng VPS riêng.

# Setup ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw enable
sudo ufw status

# Setup fail2ban
sudo apt install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Backup config và token

Token Codex CLI là tài sản quan trọng. VPS có thể bị xóa nhầm (rebuild, snapshot lỗi). Backup thư mục $HOME/.codex định kỳ.

# Cron backup hằng đêm
crontab -e

# Thêm dòng (chạy 3h sáng)
0 3 * * * tar -czf /backup/codex-$(date +%F).tar.gz $HOME/.codex/ && find /backup -name 'codex-*.tar.gz' -mtime +14 -delete

Cloud VPS TND có snapshot 1-click và backup hằng ngày tự động ở mức infrastructure, nên bạn không phải lo nếu chọn gói có backup. Nhưng backup application-level vẫn nên có cho granular hơn.

Update Codex CLI khi có version mới

OpenAI ra version mới khá thường xuyên. Update đơn giản qua npm.

# Check version hiện tại
codex --version

# Check version mới nhất trên npm
npm view @openai/codex version

# Update lên latest
npm install -g @openai/codex@latest

# Verify
codex --version

Recommend update mỗi 2-4 tuần để có bug fix và feature mới. Đọc release note trước khi update để biết có breaking change không. Backup $HOME/.codex/ trước update phòng trường hợp config bị migrate khác.

FAQ về cài Codex CLI trên VPS

VPS cần spec bao nhiêu để chạy Codex CLI mượt?

Tối thiểu 1 vCPU, 2GB RAM. Khuyến nghị 2 vCPU, 4GB RAM cho dev solo. Codex CLI rất nhẹ vì việc nặng (model AI) chạy phía OpenAI server. Phần lớn RAM dùng cho Node process và code project bạn đang làm việc, không phải bản thân Codex.

Có cần GPU không?

Không. Codex CLI chỉ là client gọi API OpenAI cloud. Không có model nào chạy local trên VPS. Việc GPU chỉ cần thiết nếu bạn dùng tool khác như Ollama hay LM Studio để chạy model local, nhưng đó không phải Codex CLI.

VPS ở VN hay nước ngoài tốt hơn?

Tùy use case. VN nhanh khi SSH từ laptop bạn, latency tới OpenAI cao hơn 1 chút. Singapore/Tokyo nhanh tới OpenAI nhưng SSH từ VN chậm vài chục ms. Với Codex CLI chủ yếu là streaming text, latency ~200ms không thay đổi trải nghiệm rõ. Mình recommend VN cho dev VN vì SSH responsive quan trọng hơn.

Có cần cài Docker để chạy Codex CLI không?

Không bắt buộc. Codex CLI là npm package thuần Node.js, cài thẳng lên Ubuntu host là dùng được. Docker chỉ cần thiết nếu bạn muốn isolation giữa nhiều project có dependency xung đột, hoặc muốn portable image deploy nhiều VPS. Cho dev solo, cài thẳng là đơn giản và nhanh nhất.

Token Codex CLI có hết hạn không?

Có, token có thời hạn (thường vài tuần đến vài tháng tùy chính sách OpenAI). Khi hết hạn, Codex CLI sẽ báo Unauthorized, bạn chỉ cần chạy codex login lại để refresh. Khuyên cron 1 task tuần kiểm tra token còn valid để không bị gián đoạn task headless giữa chừng.

Có thể cài Codex CLI mà không có tài khoản ChatGPT Plus không?

Cài thì được, nhưng login sẽ báo lỗi quota = 0 hoặc tier không đủ. Codex CLI yêu cầu ít nhất Plus để có quota meaningful. Free tier không có quota Codex CLI tại thời điểm viết. Đầu tư Plus là bước cần thiết trước khi bắt đầu.