Cách lên lịch cho AI agent chạy qua đêm trên VPS

Lúc 2 giờ sáng, một tác vụ đã lên lịch khởi chạy trên VPS chưa từng ngủ. Một lần chạy headless claude -p sẽ xử lý một tác vụ trong hàng đợi bên trong repo đã clone mà không hỏi ai điều gì, rồi thoát. Đến sáng khi bạn kiểm tra, đã có một commit đang chờ, hoặc một báo cáo, hoặc một log cho biết chính xác nó dừng ở đâu và vì sao. Không ai ngồi canh cả.

Đó là một thiết lập khác hẳn với việc để terminal mở suốt đêm và hy vọng kết nối SSH trụ được. Một điểm hỏng phổ biến của lần chạy agent qua đêm chính là máy chủ: laptop ngủ, gập nắp lại, mạng rớt, hoặc bản cập nhật hệ điều hành khởi động lại máy giữa chừng. Lỗi xác thực, lỗi API và việc treo chờ cấp quyền vẫn có thể giết chết tác vụ, nhưng một máy chủ luôn bật sẽ loại bỏ kiểu hỏng dễ xảy ra nhất.

Hướng dẫn này nói về cơ chế thực sự: các cờ headless mà mỗi CLI agent lập trình lớn đều có, hai cách kích hoạt một lần chạy theo lịch và nên chọn cách nào, máy chủ bên dưới cần những gì, và các rào chắn giúp một lần chạy không giám sát không tốn kém hay phá hỏng nhiều hơn mức bạn muốn phải giải thích sau này.

Phiên bản ngắn gọn

• Mọi CLI agent lập trình lớn đều có chế độ không tương tác được ghi trong tài liệu, chạy một prompt đến khi xong rồi thoát. Claude Code dùng claude -p, Codex CLI dùng codex exec, và Gemini CLI dùng gemini -p. Đây không phải cách lách, mà là tính năng chính thức.
• Claude Code cũng có cơ chế lên lịch riêng: Routines, tác vụ theo lịch trên Desktop và /loop. Với một số người, như vậy là thực sự đủ và ít phải bảo trì hơn một VPS.
• Cron hoàn toàn ổn cho một tác vụ hằng đêm. Trên máy có thể khởi động lại, systemd timer là lựa chọn mặc định tốt hơn, vì Persistent=true bắt lại lần chạy mà cron sẽ lặng lẽ bỏ qua.
• Bản thân CLI rất nhẹ vì phần suy luận chạy trên API của nhà cung cấp. Hãy chọn cấu hình VPS theo các lệnh nó sẽ chạy (test, build, container, job song song), chứ không phải theo mô hình.
• Chính các rào chắn mới khiến việc để mặc một lịch chạy trở nên an toàn: giới hạn công cụ, chặn số lượt, và rẽ nhánh theo exit code. Bản thân lịch chạy không phải là cơ chế an toàn.

Những Gì Bạn Sẽ Cần

Chuẩn bị năm thứ này trước khi viết dòng crontab hay file unit đầu tiên:

• Một VPS bạn có thể SSH vào, chạy bản phân phối Linux dùng systemd.
• CLI của agent đã cài trên VPS đó: Claude Code, Codex CLI hoặc Gemini CLI.
• Một thông tin xác thực không tương tác cho CLI bạn chọn. Chế độ bare của Claude Code không đọc phiên đăng nhập tài khoản, nên nó cần ANTHROPIC_API_KEY trong biến môi trường, hoặc một apiKeyHelper trong phần cài đặt. Một lần chạy print-mode thông thường, Codex và Gemini cũng có thể dùng thông tin đăng nhập tài khoản như tài liệu mô tả.
• Một repo hoặc thư mục tác vụ để agent làm việc trên đó.
• Quyền truy cập shell để chỉnh crontab hoặc tạo file unit của systemd.

Chạy agent mà không cần phiên nào đang mở

Mọi CLI agent lập trình lớn đều có chế độ không tương tác được tạo ra đúng cho việc này. Claude Code nhận -p, cũng viết là --print. Codex CLI nhận codex exec. Gemini CLI nhận -p, cũng viết là --prompt. Mỗi công cụ nhận một prompt, chạy đến khi xong rồi thoát. Không vòng lặp chat, không phải giữ terminal mở, không có gì để kết nối lại.

Claude Code có chạy được mà không cần phiên đang mở không? Có. Truyền -p sẽ chạy prompt ở chế độ không tương tác: Claude Code thực thi đến khi xong, in kết quả rồi thoát. Không có vòng lặp chat và không có gì phải duy trì, và nó chạy trên cùng Agent SDK vốn vận hành CLI tương tác, theo tài liệu chính thức của Anthropic về chế độ headless.

Ở đây quan trọng nhất là các cờ riêng của Claude Code, vì đó mới là thứ bạn thực sự viết script để dùng. Hai trong số đó cho phép lần chạy tiếp tục mà không dừng lại xin một quyền mà chẳng ai thức để cấp: --allowedTools, cờ này duyệt trước các công cụ cụ thể, và --permission-mode, cờ này đặt mức nền cho toàn bộ lần chạy. --max-turns giới hạn số lượt agent mà một lần chạy được phép thực hiện trước khi thoát kèm lỗi.

--bare sẽ bỏ qua hook, skill, plugin, máy chủ MCP và các chỉ dẫn cấp dự án như CLAUDE.md, để lần chạy bằng script nhanh hơn và ổn định hơn. Điều đó cũng có nghĩa mọi chỉ dẫn mà công việc phụ thuộc vào đều phải nằm trong prompt hoặc trong lệnh. Chế độ bare cũng không đọc phiên đăng nhập tài khoản của bạn, nên tài liệu của Anthropic khuyên đặt một khóa API trong biến môi trường trước khi chạy. Claude Code từ chối --bg thẳng thừng khi kết hợp với -p, và từ chối --cloud theo cách tương tự khi bạn kèm theo một mô tả tác vụ. Nó nêu rõ xung đột và dừng lại, thay vì làm điều gì đó mơ hồ.

Một lệnh gọi hoàn chỉnh, hãy chỉnh prompt và danh sách công cụ cho phù hợp với tác vụ của bạn:

claude --bare -p "Review open PRs in this repo and summarize any blockers in NOTES.md" \
  --allowedTools "Bash(gh pr list *),Bash(gh pr view *),Bash(gh pr diff *),Read,Edit" \
  --permission-mode dontAsk \
  --max-turns 8 \
  --max-budget-usd 5.00 \
  --output-format json

Hãy điều chỉnh ngân sách và các mẫu lệnh cho phù hợp với tác vụ; ví dụ này cũng giả định rằng tài khoản chạy nó đã cấu hình xác thực GitHub CLI.

Nếu bạn đang cài Claude Code trên một VPS mới và muốn hướng dẫn xác thực trên máy không có trình duyệt, nội dung đó nằm riêng trong bài cách xác thực Claude Code trên máy chủ headless; phiên bản ngắn ở trên là đủ để chạy được một lần chạy theo lịch.

Chế độ exec của Codex CLI, được mô tả trong tài liệu về chế độ không tương tác của OpenAI, nhận --sandbox để chọn một chính sách. read-only là mặc định, workspace-write cho phép agent ghi trong workspace của nó, còn --json biến stdout thành luồng sự kiện máy đọc được thay vì văn bản thuần. Hãy tránh danger-full-access cho một tác vụ không giám sát, trừ khi tiến trình đã được cô lập và rủi ro đó là có chủ ý.

Chế độ headless của Gemini CLI, được ghi trong tài liệu headless của chính dự án, tự động bật trong môi trường không có TTY, hoặc bật tường minh bằng -p. Nó thoát với mã khác 0 riêng cho lỗi chung, lỗi đầu vào và trường hợp chạm giới hạn lượt, thay vì một mã lỗi chung chung duy nhất.

Lịch chạy nên đặt ở đâu

Trước khi bắt tay vào toàn bộ phần cài đặt này: nhà cung cấp agent có thể đã lo phần lên lịch giúp bạn rồi. Claude Code có ba tùy chọn tích hợp sẵn, và một trong số đó có thể thực sự phù hợp hơn một VPS bạn tự quản lý.

Tài liệu chính thức của Anthropic về tác vụ theo lịch trình bày đây là một lựa chọn ba nhánh thực sự, không phải một thứ bậc với VPS ở trên đỉnh. Nếu tác vụ của bạn không cần trạng thái cục bộ, chấp nhận được mức tối thiểu một giờ, và bạn chỉ dùng Claude Code, thì Routines ít phải bảo trì hơn những gì trình bày tiếp theo: Anthropic chạy nó trên đám mây từ một bản clone mới trong khi máy bạn đang tắt.

/loop đáng để biết nhưng không hợp với tình huống này, vì nó đòi hỏi một phiên đang mở và rảnh, đúng là ràng buộc mà bạn đang muốn loại bỏ. Cũng tài liệu đó còn nhắc tới GitHub Actions như lựa chọn thứ tư, dành cho các đội mà trigger vốn đã nằm trong CI chứ không phải một lịch gắn với một máy cụ thể.

VPS tự quản lý xứng đáng có chỗ khi công việc cần toàn quyền truy cập hệ thống tệp cục bộ và công cụ, khi bạn muốn cùng một cơ chế chạy giống hệt nhau trên Claude Code, Codex CLI và Gemini CLI, hoặc khi khoảng thời gian mà Routines cho phép quá thô. Một hàm serverless thông thường thường vụng về ở đây vì nó phải khôi phục thông tin xác thực, clone repo và hoàn tất trong giới hạn thời gian chạy của nền tảng. Một CI runner tạm thời như GitHub Actions vẫn là con đường thứ ba hợp lệ khi việc checkout mới mỗi lần chạy là chấp nhận được. Nếu bạn đã có sẵn phần cứng luôn bật đang nhàn rỗi, một máy homelab cũng dùng được; đánh đổi là độ tin cậy của mạng nhà và khả năng truy cập từ xa của bạn, thay vì của một nhà cung cấp.

Cron hay systemd timer?

Cả hai công cụ đều có thể chạy cùng một lệnh theo cùng một lịch, nhưng chúng khác nhau ở chỗ điều gì xảy ra khi máy khởi động lại và mỗi bên tốn bao nhiêu công cài đặt:

Cron thường là đủ cho một tác vụ hằng đêm trên máy hiếm khi khởi động lại. Điểm gài là môi trường: cron khởi chạy với PATHtối thiểu, không tự chuyển vào repo giúp bạn, và sẵn sàng khởi chạy bản sao thứ hai trong khi bản đầu vẫn đang chạy. Hãy đưa đường dẫn repo, câu lệnh agent đã thu hẹp và phần nạp thông tin xác thực vào một script bọc có bảo vệ, rồi dùng flock để ngăn các lần chạy chồng lấn.

# /usr/local/bin/agent-nightly
#!/usr/bin/env bash
set -euo pipefail
export PATH=/usr/local/bin:/usr/bin:/bin
export ANTHROPIC_API_KEY="$(
  cat "$HOME/.config/agent-nightly/anthropic_api_key"
)"
cd /srv/myrepo
exec /usr/local/bin/claude --bare -p \
  "Run the nightly dependency audit and write the findings to NOTES.md" \
  --allowedTools "Bash(npm audit *),Read,Edit" \
  --permission-mode dontAsk \
  --max-turns 8 \
  --max-budget-usd 5.00 \
  --output-format json

# crontab -e
0 2 * * * /usr/bin/flock -n "$HOME/.local/state/agent-runs/nightly.lock" /usr/local/bin/agent-nightly >> "$HOME/.local/state/agent-runs/nightly.log" 2>&1

Tạo một lần các thư mục cho thông tin xác thực và log, rồi cấp quyền thực thi cho script bọc:

install -d -m 700 \
  "$HOME/.config/agent-nightly" \
  "$HOME/.local/state/agent-runs"
touch "$HOME/.config/agent-nightly/anthropic_api_key"
chmod 600 "$HOME/.config/agent-nightly/anthropic_api_key"
"${EDITOR:-nano}" \
  "$HOME/.config/agent-nightly/anthropic_api_key"
sudo chmod 755 /usr/local/bin/agent-nightly

Chỉ dán khóa API vào file thông tin xác thực. Đừng đặt trực tiếp trong crontab.

systemd timer cần cài đặt nhiều hơn nhưng cho bạn hai thứ mà cron không có: ghi log qua journald mà không phải tự chuyển hướng, và Persistent=true. Ví dụ bên dưới giả định một tài khoản riêng agent-runner sở hữu /srv/myrepo. Hãy lưu khóa API trong một file thông tin xác thực chỉ root đọc được, thay vì nhúng thẳng vào unit.

Theo tài liệu systemd.timer, việc đặt Persistent=true có nghĩa là "service unit sẽ được kích hoạt ngay lập tức nếu lẽ ra nó đã được kích hoạt ít nhất một lần trong khoảng thời gian timer không hoạt động." Vậy nên một lần chạy lẽ ra đã diễn ra khi VPS của bạn đang khởi động lại để cập nhật kernel sẽ chạy ngay khi máy trở lại, thay vì lặng lẽ biến mất cho tới khung giờ kế tiếp.

Tạo file thông tin xác thực chỉ root đọc được mà service sẽ dùng:

sudo install -d -m 700 /etc/agent-nightly
sudo touch /etc/agent-nightly/anthropic_api_key
sudo chmod 600 /etc/agent-nightly/anthropic_api_key
sudoedit /etc/agent-nightly/anthropic_api_key

Chỉ dán khóa API vào file.

# /etc/systemd/system/agent-nightly.service
[Unit]
Description=Nightly scoped agent run
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=agent-runner
Group=agent-runner
WorkingDirectory=/srv/myrepo
Environment=HOME=/home/agent-runner
Environment=PATH=/usr/local/bin:/usr/bin:/bin
LoadCredential=anthropic_api_key:/etc/agent-nightly/anthropic_api_key
ExecStart=/bin/sh -c 'export ANTHROPIC_API_KEY="$(cat "$CREDENTIALS_DIRECTORY/anthropic_api_key")"; exec /usr/local/bin/claude --bare -p "Run the nightly dependency audit and write the findings to NOTES.md" --allowedTools "Bash(npm audit *),Read,Edit" --permission-mode dontAsk --max-turns 8 --max-budget-usd 5.00 --output-format json'
StandardOutput=journal
StandardError=journal
UMask=0077

# /etc/systemd/system/agent-nightly.timer
[Unit]
Description=Run agent-nightly.service at 2am daily, catching up missed runs

[Timer]
# Uses the VPS's configured local timezone
OnCalendar=*-*-* 02:00:00
Persistent=true
Unit=agent-nightly.service

[Install]
WantedBy=timers.target

Nạp lại systemd, bật timer, rồi chạy service ngay một lần, để các vấn đề về thông tin xác thực, quyền và đường dẫn lộ ra bây giờ chứ không phải lúc 2 giờ sáng:

sudo systemctl daemon-reload
sudo systemctl enable --now agent-nightly.timer
sudo systemctl start agent-nightly.service
systemctl list-timers agent-nightly.timer
sudo journalctl \
  -u agent-nightly.service \
  -n 100 \
  --no-pager

Persistent=true là khác biệt quyết định: timer nhớ lần chạy theo lịch đã bị lỡ thay vì lặng lẽ bỏ qua.

VPS thực sự cần những gì

Đây là phần khiến người lần đầu chọn cấu hình bất ngờ: bản thân CLI rất nhẹ vì phần suy luận chạy trên API của nhà cung cấp. Nhưng agent vẫn có thể chạy build, test, trình quản lý gói, language server và container ngay tại chỗ, nên chính khối lượng công việc của repo mới đặt ra mức sàn thực sự.

Với một tác vụ theo lịch nhẹ, hãy lấy 1-2 vCPU và 2-4 GB RAM cùng ổ NVMe làm điểm khởi đầu. Repo lớn, trình biên dịch, build Docker, bộ test hay các lần chạy song song có thể cần nhiều hơn hẳn. Thứ đẩy cấu hình lên cao là câu lệnh cục bộ nặng nhất mà agent sẽ chạy, chứ không phải mô hình phía sau API. Nếu bạn đã chạy các tải Docker trên VPS này và muốn bức tranh đầy đủ hơn về ngân sách, chọn cấu hình và bảo mật máy build phân tích cùng một đánh đổi cho một loại tải không giám sát khác.

Còn một điều nữa nên tính trước: một lần chạy không giám sát sẽ sinh log mỗi đêm, dù có gì trục trặc hay không. Hãy thêm logrotate nếu cron ghi ra file, và kiểm tra giới hạn lưu giữ của journald thay vì mặc định rằng cấu hình gốc vừa với ổ đĩa VPS.

Toàn bộ cách làm này phụ thuộc vào một máy chủ vẫn thức lúc 2 giờ sáng và cứ thế duy trì, bất kể laptop của bạn đang làm gì. Đó chính là việc mà một Linux VPS có quyền root được sinh ra để làm. Không gì đưa nó vào chế độ ngủ, và bạn cũng không phải chia sẻ nó với cron job của người khác.

Xây dựng trên VPS Linux với quyền root, NVMe và sức mạnh AMD EPYC.

Xem các gói Linux

Giữ cho một lần chạy không giám sát không đi chệch hướng

Khác biệt lớn nhất giữa một lần chạy theo lịch thành công và một lần thất bại là liệu tác vụ có đủ hẹp để hoàn tất mà không cần con người trả lời câu hỏi giữa chừng hay không. Những prompt tham vọng sẽ đứng chờ một quyết định mà chẳng ai ở đó để đưa ra; những tác vụ hẹp, khép kín thì chạy xong và thoát gọn gàng.

Hai cờ quyền tồn tại để lần chạy không bị treo ở một lời hỏi quyền lúc 2 giờ sáng, nhưng quyền Bash trần trụi không phải là một rào chắn hẹp: nó làm được gần như mọi thứ mà tài khoản service làm được. Hãy ưu tiên các quy tắc theo từng lệnh cụ thể như Bash(git status *), kết hợp chúng với --permission-mode dontAsk, và chạy service dưới một tài khoản riêng không phải root. Số lượt và mức chi tiêu đều có trần riêng: --max-turns giới hạn agent được lang thang bao lâu, còn --max-budget-usd đặt trần cho mức chi của một lần chạy vào các lời gọi API.

Mẹo: hãy chạy với --output-format json và ghi lại trường total_cost_usd của mỗi lần gọi. Đó là móc nối gọn gàng nhất để theo dõi một lần chạy theo lịch thực sự tốn bao nhiêu mỗi đêm, và để cảnh báo khi một lần chạy đắt hơn hẳn những lần khác. Năm phút bỏ ra để nối dây là xứng đáng, vì thứ nó theo dõi là hóa đơn của bạn, không phải một khái niệm trừu tượng.

Vượt chi phí ở các lần chạy không giám sát không phải chuyện giả định. Trong một bài đăng trên Hacker News, một người dùng cho biết hóa đơn AWS Bedrock tổng cộng 37.901,73 đô la đến từ một quy trình agent lập trình chạy hằng ngày, trong đó việc cache prompt chỉ hiệu quả một phần, khiến khoảng 6,47 tỷ token đầu vào không được cache. Chuyện đó xảy ra trên một stack khác, không phải chế độ headless của Claude Code, nhưng nó cho thấy vì sao việc ghi log chi phí và một mức ngân sách cứng cho mỗi lần chạy nên nằm trong chính lịch chạy.

Mẹo: Claude Code thoát với mã 0 khi thành công và mã khác 0 khi thất bại. Một script bọc kiểm tra mã thoát có thể gửi thông báo cho bạn khi hỏng, để một đêm tệ lộ ra ngay sáng hôm sau thay vì ba ngày sau, lúc bạn tình cờ ngó tới.

Tối thiểu, hãy chạy mỗi công việc trên một nhánh riêng hoặc một worktree dùng một lần, và bắt buộc có người review trước khi merge. Thông tin xác thực giới hạn phạm vi, cô lập hệ thống tệp và kiểm soát bán kính thiệt hại ở mức máy chủ là một chủ đề lớn hơn, xứng đáng có bài riêng chứ không phải một đoạn gắn thêm vào cuối hướng dẫn lên lịch.

Chính các rào chắn khiến việc để mặc lịch chạy trở nên an toàn: bản thân lịch chạy không phải là cơ chế an toàn.

Khi cron không còn đủ

Một prompt duy nhất chạy theo timer không cần gì hơn những gì đã nói ở đây. Ba bước nối tiếp có điều kiện, có retry và có thông báo Slack thì lại cần thứ khác.

Có ba lựa chọn đáng biết, mỗi cái nâng cấp vì một lý do khác nhau:

• Dagu là bước nâng cấp nhẹ nhất: các job khép kín định nghĩa bằng YAML, có phụ thuộc dạng DAG, có retry và một giao diện web để xem cái gì đã chạy.
• n8n hợp nhất khi lần chạy agent chỉ là một nút giữa nhiều tích hợp và thông báo, chứ không phải toàn bộ quy trình.
• Kestra là nặng nhất trong ba, được xây để điều phối các pipeline dữ liệu và hạ tầng, và là câu trả lời đúng khi việc lên lịch cho agent chỉ là một phần của pipeline lớn hơn chứ không phải mục đích chính.

Với người chỉ chạy một prompt mỗi đêm, cả ba đều là quá mức, và điều đó đáng nói thẳng thay vì thuyết phục bạn dựng một hệ nặng hơn mức cần. Nếu một chuỗi bước rốt cuộc có lý do dùng đến, Dagu, n8n, và Kestra đều triển khai được chỉ với một cú nhấp, và đó là tiện lợi thật sự đúng vào lúc bạn đang cân nhắc xem công cài đặt có đáng hay không.

Các framework điều phối đa agent như LangChain hay CrewAI là một chủ đề hoàn toàn khác: xây dựng hệ thống agent, chứ không phải lên lịch cho một CLI vốn đã có sẵn.

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