Claude Code module và cách chạy remote từ VPS

SSH vào VPS, gõ lệnh mà có Claude Code tự động viết code, sửa lỗi, deploy, nghe hấp dẫn đúng không? Nhưng nếu bạn là sysadmin hoặc dev làm việc remote, câu hỏi đặt ra là: Claude Code module và gói nào chạy remote từ VPS được? Không phải module nào cũng hoạt động tốt nếu bạn chạy qua SSH tunnel hoặc proxy. Bài này mình sẽ chỉ bạn cách chọn module Claude Code Agent phù hợp, cấu hình gói API tương ứng, và chạy thực tế trên VPS Linux, tất cả đều có lệnh kiểm tra, có verify.

Yêu cầu trước khi bắt đầu

• VPS chạy Ubuntu 24.04 hoặc Debian 12 (mình xài Ubuntu 24.04 trong bài này). Bạn nên thuê VPS Linux có RAM tối thiểu 2GB, hàng đầu 4GB cho Claude Code Agent chạy mượt.
• User sudo non-root đã cấu hình SSH key. Nếu chưa, đọc bài cấu hình fail2ban chống brute force SSH trên Ubuntu 24.04 để biết cách bảo mật.
• API key của Anthropic, bạn cần đăng ký tại console.anthropic.com. Gói Claude 3.5 Sonnet hoặc Claude 3 Opus đều hỗ trợ chạy remote qua Claude Code.
• Curl, Git, Node.js 18+ đã cài trên VPS. Mình sẽ hướng dẫn cài nếu chưa có.

Vì sao chạy Claude Code remote từ VPS?

Khi bạn làm việc với codebase lớn trên máy local, Claude Code có thể ngốn hết CPU và RAM, nhất là nếu bạn chạy Agent mode (tự động đọc code, sửa file, chạy lệnh). Chạy remote trên VPS giúp bạn: tận dụng tài nguyên server mạnh, không ảnh hưởng đến máy làm việc, và có thể truy cập từ bất kỳ đâu qua SSH. Nhưng không phải module nào cũng chạy được remote, module Claude Code Agent yêu cầu kết nối API ổn định, còn module Claude Code CLI cơ bản chỉ cần gói API có quyền truy cập model.

Bước 1, Cài Node.js và Claude Code CLI trên VPS

Đầu tiên, cập nhật hệ thống và cài Node.js bản LTS hiện tại (18.x hoặc 20.x). Dùng nvm để dễ quản lý phiên bản:

sudo apt update && sudo apt upgrade -y
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
node --version
# Output mong đợi: v20.x.x

Sau đó cài Claude Code CLI global:

npm install -g @anthropic-ai/claude-code
claude --version
# Output: version 0.x.x (tùy thời điểm)

Verify: Lệnh claude --help phải hiển thị danh sách subcommand. Nếu báo lỗi "command not found", kiểm tra lại PATH, thêm export PATH="$HOME/.npm-global/bin:$PATH" vào ~/.bashrc.

Bước 2, Cấu hình API key và gói Claude Code module

Claude Code module và gói nào chạy remote từ VPS được? Câu trả lời: tất cả các module hiện tại đều chạy được remote nếu bạn có API key hợp lệ và gói API tương ứng. Cụ thể:

Để cấu hình API key, export biến môi trường hoặc dùng file .env:

export ANTHROPIC_API_KEY="sk-ant-..."
echo "ANTHROPIC_API_KEY=sk-ant-..." >> ~/.bashrc
source ~/.bashrc

Verify: Chạy echo $ANTHROPIC_API_KEY, phải thấy key. Nếu không, kiểm tra file ~/.bashrc có dòng export chưa.

Bước 3, Chạy Claude Code Agent mode trên VPS qua SSH tunnel

Agent mode cho phép Claude Code tự động đọc codebase, đề xuất sửa lỗi, và thực thi lệnh. Để chạy remote, bạn cần mở một SSH tunnel và chạy Claude Code ở chế độ daemon:

# Từ máy local, kết nối SSH với port forwarding
ssh -L 8080:localhost:8080 user@vps-ip

# Trên VPS, chạy Claude Code Agent
claude agent --port 8080 --api-key $ANTHROPIC_API_KEY
# Output: "Claude Code Agent listening on http://localhost:8080"

Trên máy local, mở trình duyệt hoặc curl để kiểm tra:

curl http://localhost:8080/health
# Output: {"status":"ok","model":"claude-3-5-sonnet-20241022"}

Lưu ý nếu không thấy output: Kiểm tra firewall trên VPS. Nếu dùng ufw, mở port 8080 tạm thời:

sudo ufw allow 8080/tcp
# Sau khi xong, nhớ đóng
sudo ufw delete allow 8080/tcp

Nếu bạn dùng VPS n8n để tự động hóa workflow, Claude Code Agent có thể tích hợp làm worker xử lý code tự động.

Bước 4, Cấu hình proxy cho Claude Code trên VPS

Trường hợp VPS của bạn nằm sau proxy corporate hoặc cần route traffic qua một IP cố định, cấu hình biến môi trường HTTPS_PROXY:

export HTTPS_PROXY="http://proxy-ip:port"
export HTTP_PROXY="http://proxy-ip:port"
claude code --model claude-3-5-sonnet-20241022

Verify: Chạy lệnh đơn giản yêu cầu Claude Code viết một đoạn code nhỏ:

echo "viết một hàm Python tính Fibonacci đến n" | claude code --stdin
# Output: function và giải thích

Nếu không có output sau 30 giây, kiểm tra kết nối API:

curl -v -x $HTTPS_PROXY https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"hello"}]}'
# Output: JSON response với content

Bước 5, Tối ưu hiệu suất Claude Code trên VPS

Khi chạy remote, 2 yếu tố ảnh hưởng nhất là RAM và latency mạng. Đây là kinh nghiệm từ thực tế:

• RAM: Claude Code Agent có thể ngốn 1.5-3GB RAM. Trên VPS 2GB, giới hạn bằng cách thêm flag --max-memory 1500 (tính bằng MB).
• Latency: Ping đến API Anthropic lý tưởng <100ms. Nếu VPS đặt tại Việt Nam, ping đến US west coast thường 150-250ms, chấp nhận được cho code generation nhưng slow với agent mode. Cân nhắc thuê VPS Việt Nam có route quốc tế tốt, hoặc dùng Cloudflare Workers làm proxy gần hơn.
• Timeout: Agent mode có timeout mặc định 120 giây cho mỗi request. Nếu codebase lớn, tăng lên CLAUDE_CODE_TIMEOUT=300.

# Kiểm tra RAM sử dụng
free -h
# Kiểm tra latency
ping -c 5 api.anthropic.com

Xử lý lỗi thường gặp

Lỗi 1: "API key invalid" khi chạy Claude Code
Nguyên nhân: Key hết hạn hoặc sai region. Kiểm tra lại key trong ~/.bashrc. Với curl test trực tiếp API như bước 4. Nếu key đúng nhưng lỗi 401, tạo key mới tại console.anthropic.com.

Lỗi 2: "Connection refused" khi SSH tunnel
Port 8080 không được mở hoặc sai interface. Trên VPS, chạy ss -tlnp | grep 8080, nếu không thấy, Claude Code Agent chưa chạy. Thử chạy trực tiếp không qua tunnel: claude agent --port 8080 --host 0.0.0.0 (chỉ dùng để debug, không production).

Lỗi 3: "Model not available" với gói API miễn phí
Một số gói API chỉ hỗ trợ Claude 3 Haiku, không chạy được Agent mode yêu cầu Sonnet/Opus. Kiểm tra gói của bạn tại billing console. Nếu chỉ có Haiku, dùng claude code --model claude-3-haiku-20240307.

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

Bài viết liên quan

• Kinh nghiệm sử dụng Claude và top skill nên cài trên VPS
• Cách cài Docker trên VPS Ubuntu chi tiết từ A đến Z
• Hệ thống trợ lý AI cho doanh nghiệp với BizMaC