Hogyan ütemezzünk AI-ügynököket éjszakai futásra egy VPS-en

Hajnali 2-kor egy ütemezett feladat indul el egy VPS-en, amely soha nem aludt el. Egy headless claude -p futás végigmegy egy sorban álló feladaton egy klónozott repóban anélkül, hogy bárkitől bármit kérdezne, majd kilép. Mire reggel megnézed, ott vár egy commit, egy jelentés vagy egy napló, amely pontosan megmutatja, hol és miért állt le. Senki nem figyelte.

Ez egészen más felállás, mint egész éjjel nyitva hagyni egy terminált, és reménykedni, hogy az SSH-kapcsolat kitart. Egy éjszakai ügynökfutás gyakori hibapontja maga a gazdagép: a laptop elalszik, lecsukják a fedelét, elmegy a hálózat, vagy egy rendszerfrissítés újraindítja a gépet a feladat közepén. A hitelesítési hibák, az API-hibák és a jogosultságra várakozás továbbra is megölhetik a feladatot, de egy folyamatosan futó gazdagép megszünteti a legegyszerűbb hibalehetőséget.

Ez az útmutató a tényleges működést járja körül: a headless kapcsolókat, amelyeket minden nagyobb kódoló ügynök CLI-je hoz, az ütemezett futtatás két módját és azt, melyiket érdemes választani, hogy mire van szüksége az alatta lévő gazdagépnek, és azokat a védőkorlátokat, amelyek megakadályozzák, hogy egy felügyelet nélküli futás többe kerüljön vagy többet törjön el, mint amennyit később magyarázni szeretnél.

A rövid verzió

• Minden nagyobb kódoló ügynök CLI-je dokumentált, nem interaktív módot kínál, amely egy promptot végigfuttat, majd kilép. A Claude Code-ban ez a claude -p, a Codex CLI-ben a codex exec, a Gemini CLI-ben pedig a gemini -p. Ez nem kerülőmegoldás, hanem hivatalos funkció.
• A Claude Code-nak saját ütemezése is van: Routines, Desktop ütemezett feladatok és /loop. Néhány olvasónak ez tényleg elég, és kevesebb karbantartást igényel, mint egy VPS.
• Egy éjszakai feladathoz a cron tökéletesen megfelel. Egy olyan gépen, amely újraindulhat, a systemd időzítő a jobb alapértelmezés, mert a Persistent=true elkapja azt a futást, amelyet a cron csendben kihagyna.
• Maga a CLI könnyű, mert a következtetés a szolgáltató API-ján fut. A VPS-t azokhoz a parancsokhoz méretezd, amelyeket futtatni fog (tesztek, buildek, konténerek, párhuzamos feladatok), nem a modellhez.
• A védőkorlátok teszik biztonságossá, hogy magára hagyd az ütemezést: szűkített eszközkészlet, körlimit, kilépési kód szerinti elágazás. Maga az ütemezés nem biztonsági mechanizmus.

Amire szükséged lesz

Készítsd elő ezt az öt dolgot, mielőtt egyetlen crontab-sort vagy unit fájlt is írnál:

• Egy VPS, amelyre SSH-val be tudsz lépni, systemd-alapú Linux disztribúcióval.
• Az ügynök CLI-je telepítve arra a VPS-re: Claude Code, Codex CLI vagy Gemini CLI.
• Nem interaktív hitelesítő adat a választott CLI-hez. A Claude Code bare módja nem olvas fiókbejelentkezést, ezért szüksége van a ANTHROPIC_API_KEY változóra a környezetben, vagy egy apiKeyHelper a beállításaiban. Egy szokásos print módú futás, a Codex és a Gemini a dokumentált fiókbejelentkezési adatokat is használhatja.
• Egy repó vagy feladatkönyvtár, amelyen az ügynök dolgozni fog.
• Shell-hozzáférés, amellyel szerkeszthetsz crontabot vagy írhatsz systemd unit fájlt.

Ügynök futtatása csatolt munkamenet nélkül

Minden nagyobb kódoló ügynök CLI-je kínál egy pontosan erre készült, nem interaktív módot. A Claude Code a -pkapcsolót fogadja el, hosszú alakban --print. A Codex CLI a codex execparancsot fogadja el. A Gemini CLI a -pkapcsolót fogadja el, hosszú alakban --promptkapcsolót fogadja el. Mindegyik elfogad egy promptot, végigfuttatja, majd kilép. Nincs chatciklus, nincs nyitva tartandó terminál, nincs mihez visszakapcsolódni.

Futhat a Claude Code élő munkamenet nélkül? Igen. A -p kapcsoló nem interaktív módban futtatja a promptot: a Claude Code végigviszi, kiírja az eredményt, majd kilép. Nincs chatciklus és nincs mit életben tartani, ráadásul ugyanazon az Agent SDK-n fut, amely az interaktív CLI-t is hajtja, lásd az Anthropic saját headless módról szóló dokumentációját.

Itt a Claude Code saját kapcsolói számítanak a legtöbbet, mert valójában ezekre fogsz szkriptet írni. Közülük kettő engedi, hogy a futás továbbmenjen anélkül, hogy megállna egy olyan engedélyért, amelyet éjjel senki nem tud megadni: --allowedTools, amely előre jóváhagy bizonyos eszközöket, és a --permission-mode, amely az egész futás alapszintjét állítja be. --max-turns korlátozza, hány ügynökkört tehet meg egy futás, mielőtt hibával kilép.

--bare kihagyja a hookokat, a skilleket, a bővítményeket, az MCP-szervereket és az olyan projektutasításokat, mint a CLAUDE.md, a gyorsabb és kiszámíthatóbb szkriptelt futás érdekében. Ez azt is jelenti, hogy minden utasításnak, amelytől a feladat függ, benne kell lennie a promptban vagy a parancsban. A bare mód a fiókbejelentkezésedet sem olvassa, ezért az Anthropic dokumentációja azt írja, hogy állíts be egy API-kulcsot a környezetben , mielőtt futtatnád. A Claude Code elutasítja a --bg kapcsolót, ha a -pkapcsolóval együtt adod meg, és ugyanígy elutasítja a --cloud kapcsolót, ha feladatleírást adsz mellé. Megnevezi az ütközést, és megáll, ahelyett hogy valami félreérthetőt tenne.

Egy kidolgozott hívás, a promptot és az eszközlistát igazítsd a saját feladatodhoz:

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

A költségkeretet és a parancsmintákat igazítsd a feladathoz; ez a példa azt is feltételezi, hogy a GitHub CLI hitelesítése már be van állítva a futtató fiókhoz.

Ha friss VPS-en állítod be a Claude Code-ot, és a böngésző nélküli gépen történő hitelesítés lépéseit keresed, azt külön tárgyaljuk itt: hogyan hitelesítsd a Claude Code-ot headless szerveren; a fenti rövid változat elég ahhoz, hogy egy ütemezett futás működjön.

A Codex CLI exec módja, amelyet ez ismertet: az OpenAI nem interaktív módról szóló dokumentációja, és elfogadja a --sandbox kapcsolót a szabály kiválasztásához. read-only az alapértelmezés, workspace-write engedi az ügynöknek az írást a munkaterületén belül, a --json kapcsoló pedig gépi feldolgozásra alkalmas eseményfolyammá alakítja a stdout kimenetet sima szöveg helyett. Kerüld a danger-full-access kapcsolót felügyelet nélküli feladatnál, hacsak a folyamat nem elszigetelt és a kockázatot nem tudatosan vállalod.

A Gemini CLI headless módja, amelyet ez dokumentál: a projekt saját headless dokumentációja, automatikusan bekapcsol nem TTY környezetben, vagy kifejezetten a -pkapcsolóval. Külön nem nulla kilépési kóddal zár általános hiba, bemeneti hiba és a körlimit elérése esetén, egyetlen általános hibakód helyett.

Hol lakjon az ütemezés

Mielőtt belefognál ebbe a beállítási munkába: lehet, hogy az ügynök szállítója már ütemezi helyetted. A Claude Code három beépített lehetőséget kínál, és az egyikük tényleg jobban illhet, mint egy saját kezűleg üzemeltetett VPS.

Az Anthropic saját, ütemezett feladatokról szóló dokumentációja valódi háromfelé ágazó választásként mutatja be, nem pedig hierarchiaként, amelynek tetején a VPS áll. Ha a feladatodnak nincs szüksége gépi helyi állapotra, elviseli az egyórás alsó határt, és csak Claude Code-ot használsz, a Routines kevesebb karbantartást igényel, mint ami ezután következik: az Anthropic a felhőben, friss klónból futtatja, miközben a géped ki van kapcsolva.

/loop érdemes ismerni, de erre a felhasználásra nem való, mert nyitott, tétlen munkamenetet igényel, vagyis pontosan azt a megkötést, amitől szabadulni próbálsz. Ugyanaz a dokumentáció negyedik lehetőségként a GitHub Actionst is megemlíti, olyan csapatoknak, amelyeknél a kiváltó esemény már a CI-ban él, nem pedig egy adott géphez kötött ütemezésben.

A saját kezűleg üzemeltetett VPS akkor érdemli ki a helyét, ha a feladatnak teljes hozzáférés kell a helyi fájlrendszerhez és az eszközökhöz, ha ugyanazt a mechanizmust akarod egyformán működtetni Claude Code, Codex CLI és Gemini CLI alatt, vagy ha a Routines által engedett időköz túl durva. Egy hagyományos serverless függvény itt általában esetlen, mert vissza kell állítania a hitelesítő adatokat, klónoznia kell a repót, és a platform futásidő-korlátain belül kell végeznie. Egy eldobható CI runner, például a GitHub Actions, továbbra is életképes harmadik út, ha futásonként elfogadható egy friss checkout. Ha van már amúgy is folyamatosan futó, kihasználatlan hardvered, egy homelab gép is megteszi; cserébe a saját otthoni hálózatod megbízhatóságára és távoli elérésére támaszkodsz, nem a szolgáltatóéra.

Cron vagy systemd időzítő?

Mindkét eszköz el tudja indítani ugyanazt a parancsot ugyanazzal az ütemezéssel, de eltérnek abban, mi történik a gép újraindulásakor, és mennyi beállítást igényelnek:

Egy ritkán újrainduló gépen az egyszerű cron tökéletesen megfelel egy éjszakai feladathoz. A csapda a környezet: a cron minimális PATHPATH értékkel indul, nem lép be helyetted a repóba, és vidáman elindít egy második példányt, miközben az első még fut. Tedd a repó elérési útját, a szűkre szabott ügynökparancsot és a hitelesítő adat betöltését egy védett wrapper szkriptbe, majd használd a flock parancsot, hogy ne fedjék át egymást a futások.

# /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

Hozd létre egyszer a hitelesítő adatok és a naplók könyvtárát, majd tedd futtathatóvá a wrapper szkriptet:

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

A hitelesítő fájlba csak az API-kulcsot illeszd be. Ne tedd közvetlenül a crontabba.

Egy systemd időzítő több beállítást igényel, viszont két olyat ad, ami a cronból hiányzik: journald naplózást kézzel írt átirányítás nélkül, és a Persistent=true. Az alábbi példa feltételezi, hogy egy dedikált agent-runner fiók a tulajdonosa ennek: /srv/myrepo. Az API-kulcsot csak a root által olvasható hitelesítő fájlban tárold, ne ágyazd bele a unitba.

Szerint a systemd.timer kézikönyveszerint a Persistent=true beállítás azt jelenti, hogy „a szolgáltatásegység azonnal elindul, ha legalább egyszer el kellett volna indulnia az alatt az idő alatt, amíg az időzítő inaktív volt." Így az a futás, amely akkor indult volna, amikor a VPS-ed kernelfrissítés miatt újraindult, abban a pillanatban elindul, ahogy a gép visszatér, ahelyett hogy csendben eltűnne a következő ütemezett időpontig.

Hozd létre a csak a root által olvasható hitelesítő fájlt, amelyet a szolgáltatás használ:

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

A fájlba csak az API-kulcsot illeszd be.

# /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

Töltsd újra a systemd konfigurációt, engedélyezd az időzítőt, és futtasd le a szolgáltatást egyszer azonnal, hogy a hitelesítési, jogosultsági és elérésiút-problémák most bukjanak ki, ne hajnali 2-kor:

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 a döntő különbség: az időzítő emlékszik a kimaradt naptári futásra, ahelyett hogy csendben eldobná.

Mire van valójában szüksége a VPS-nek

Ez az a rész, ami meglepi azokat, akik először méretezik: maga a CLI könnyű, mert a következtetés a szolgáltató API-ján fut. Az ügynök viszont továbbra is indíthat helyben buildeket, teszteket, csomagkezelőket, nyelvi szervereket és konténereket, így a valódi alsó határt a repó terhelése szabja meg.

Egy könnyű ütemezett feladathoz vegyél kiindulásként 1-2 vCPU-t és 2-4 GB RAM-ot NVMe tárolóval. A nagy repók, fordítók, Docker buildek, tesztkészletek vagy párhuzamos futások ennél sokkal többet igényelhetnek. A felfelé méretezést az ügynök által futtatott legnehezebb helyi parancs kényszeríti ki, nem az API mögötti modell. Ha már futtatsz Docker-terheléseket ezen a VPS-en, és teljesebb képet szeretnél a költségvetésről, egy build gép méretezése és biztonságossá tétele ugyanezt a kompromisszumot járja körül egy másik, felügyelet nélküli terhelésre.

Még valami, amivel érdemes tervezni: egy felügyelet nélküli futás minden éjjel naplót termel, akár történt hiba, akár nem. Ha a cron fájlba ír, tedd hozzá a logrotate eszközt, és nézd meg a journald megőrzési korlátait ahelyett, hogy feltételeznéd: az alapértékek elférnek a VPS lemezén.

Az egész megközelítés egy olyan gazdagépen áll, amely hajnali 2-kor is ébren van, és az is marad, függetlenül attól, hogy a laptopod éppen mit csinál. Pontosan erre való egy root hozzáférésű Linux VPS Linux VPS. Semmi nem altatja el, és nem osztozol rajta mások cron feladataival.

Hogyan ne fusson félre egy felügyelet nélküli futás

A működő és a nem működő ütemezett futás közti legnagyobb különbség az, hogy a feladat elég szűkre van-e szabva ahhoz, hogy befejeződjön anélkül, hogy menet közben ember válaszolna egy kérdésre. A nagyra törő promptok megállnak, és olyan döntésre várnak, amelyet senki nem tud meghozni; a szűk, önmagukban zárt feladatok végigfutnak, és tisztán kilépnek.

A két jogosultsági kapcsoló azért van, hogy egy futás ne akadjon el hajnali 2-kor egy kérdésen, de a csupasz Bash hozzáférés nem szűk védőkorlát: szinte mindent megtehet, amit a szolgáltatásfiók. Válassz inkább parancsspecifikus szabályokat, például Bash(git status *), párosítsd őket a --permission-mode dontAskkapcsolóval, a szolgáltatást pedig dedikált, nem root fiók alatt futtasd. A körszámnak és a költésnek külön plafonja van: --max-turns korlátozza, meddig kóborolhat az ügynök, a --max-budget-usd pedig felső határt szab annak, mennyit költhet egyetlen futás API-hívásokra.

Tipp: futtasd a --output-format json kapcsolóval, és naplózd a total_cost_usd mezőt minden hívásból. Ez a legtisztább fogódzó ahhoz, hogy kövesd, mennyibe kerül valójában egy ütemezett futás éjszakánként, és hogy riasztást kapj, ha egy futás észrevehetően többe kerül a többinél. Megéri az öt percet, amíg összekötöd, mert amit követ, az a te számlád, nem egy elvont fogalom.

A felügyelet nélküli futások költségtúllépése nem elméleti veszély. Egy Hacker News-bejegyzésbenegy felhasználó 37 901,73 dolláros bruttó AWS Bedrock-számláról számolt be, amely egy naponta futó kódoló ügynök munkafolyamatból származott, ahol a prompt-gyorsítótárazás csak részben működött, és nagyjából 6,47 milliárd bemeneti token maradt gyorsítótár nélkül. Ez egy másik stacken történt, nem a Claude Code headless módjában, de jól mutatja, miért való az ütemezésbe a költségnaplózás és a futásonkénti kemény költségkeret.

Tipp: a Claude Code sikeres futáskor 0, hiba esetén nem nulla kilépési kóddal zár. Egy wrapper szkript, amely ellenőrzi a kilépési státuszt, hiba esetén értesítést küldhet neked, így egy rosszul sikerült éjszaka másnap reggel derül ki, nem három nappal később, amikor véletlenül ránézel.

Legalább annyit tegyél meg, hogy minden feladatot külön ágon vagy eldobható worktree-ben futtatsz, és emberi átnézést követelsz meg a merge előtt. A szűk hatókörű hitelesítő adatok, a fájlrendszer-elszigetelés és a szerverszintű hatássugár-kezelés nagyobb téma, amely önálló tárgyalást érdemel, nem egy ütemezési útmutató végére biggyesztett bekezdést.

A védőkorlátok teszik biztonságossá, hogy magára hagyd az ütemezést: maga az ütemezés nem biztonsági mechanizmus.

Mikor nem elég már a cron

Egyetlen prompt egy időzítőn semmi többet nem igényel annál, mint ami eddig szóba került. Három láncba fűzött lépés feltétellel, újrapróbálkozással és Slack-értesítéssel viszont már mást kíván.

Három lehetőséget érdemes ismerni, mindegyik más okból jelent egy szinttel többet:

• Dagu a legkönnyebb lépés felfelé: önmagukban zárt, YAML-ben definiált feladatok DAG-függőségekkel, újrapróbálkozásokkal és egy webes felülettel, ahol látod, mi futott le.
• n8n akkor illik a legjobban, ha az ügynökfutás csak egy csomópont több integráció és értesítés között, nem pedig maga a teljes munkafolyamat.
• Kestra a három közül a legnehezebb, adat- és infrastruktúra-pipeline-ok vezénylésére készült, és akkor a helyes válasz, ha az ügynök ütemezése egy nagyobb pipeline része, nem pedig a lényege.

Annak, aki egyetlen éjszakai promptot futtat, mindhárom túlzás, és ezt jobb kimondani, mint rábeszélni téged a szükségesnél nehezebb felállásra. Ha egy lépéslánc idővel tényleg indokolttá teszi valamelyiket, Dagu, n8n, és Kestra mind egykattintásos telepítéssel érhető el, ami valódi könnyebbség pontosan akkor, amikor azt mérlegeled, megéri-e a beállítás ára.

A többügynökös vezénylési keretrendszerek, mint a LangChain vagy a CrewAI, teljesen más témát jelentenek: ügynökrendszerek építését, nem pedig egy már létező CLI ütemezését.

Gyakran ismételt kérdések

Futhat a Claude Code élő munkamenet nélkül?

Igen. A -p kapcsoló nem interaktív módban futtatja a promptot: a Claude Code végigviszi, kiírja az eredményt, majd kilép, chatciklus és nyitva tartandó munkamenet nélkül.

Kell VPS, ha a Claude Code-nak már van Routines funkciója?

Nem mindig. A Routines az Anthropic felhőjében fut kikapcsolt géppel is, és friss klónból indul, viszont nem fér hozzá a csak a te gépeden létező fájlokhoz, és egyórás minimális időköze van. Egy saját kezűleg üzemeltetett VPS akkor érdemli ki a helyét, ha a feladathoz helyi fájlok, tetszőleges időközök vagy több gyártó CLI-jén egyformán működő mechanizmus kell.

Cront vagy systemd időzítőt használjak ütemezett ügynökhöz?

systemd időzítőt, ha a VPS valaha újraindul karbantartás miatt. Persistent=true lefuttatja azt a feladatot, amely a leállás alatt indult volna, amint a rendszer visszatér; a cronban erre nincs megfelelő. Egy folyamatosan futó gépen az éjszakai feladathoz a cron megfelel.

Mennyi RAM kell egy ütemezett AI-ügynöknek egy VPS-en?

Egy könnyű ütemezett feladathoz indulj 1-2 vCPU-ról és 2-4 GB RAM-ról, majd méretezz az ügynök által futtatott legnehezebb helyi parancshoz. A buildek, tesztek, a Docker, a nagy repók és a párhuzamos futások sokkal többet nyomnak a latban, mint a távoli modellkövetkeztetés.

Megváltoztatja a számlázást, ha ütemezetten futtatok egy ügynököt?

Az ütemezés nem hoz létre külön számlázási módot. A Claude Code -p használhat előfizetéses hitelesítést vagy API-kulcsot, de a --bare figyelmen kívül hagyja az előfizetéses bejelentkezést, ezért szüksége van a ANTHROPIC_API_KEY változóra a környezetben, vagy egy apiKeyHelper beállításaiban. A Codex és a Gemini azt a hitelesítési módot követi, amelyet a saját CLI-jükhöz beállítottál. Mivel az árak és a használati feltételek gyorsan változnak, a beüzemeléskor nézd meg a szolgáltató aktuális árait és a saját használati adataidat. API-n futó Claude Code esetén naplózhatod a total_cost_usd mezőt a JSON kimenetből.