技術ブログ

Hermes Agentのcron新機能を使う前に｜公式docsと手元CLIの差を確かめる

約12分で読めます
#Hermes Agent#AIエージェント#Cron#運用
Hermes Agentのcron新機能を使う前に｜公式docsと手元CLIの差を確かめる

公式 docs には--pausedがあるのに、手元のhermes cron create --helpには出てきませんでした。2026 年 9 月 8 日、稼働中の Hermes Agent は v0.21.0 でした。一方、公式 repository の main には、cron job を停止状態で作る変更が入っています。

この差を見落として本番用の作成コマンドを組むと、単に失敗するだけでは済みません。互換用の代替手順として「作成してから pause する」を選べば、作成と停止の間に scheduler が job を拾う余地が戻るからです。

私は、無人 job の新機能を試すときほど、機能の説明より先に実行中の CLI を見ます。docs、release、手元の help は、同じ日に同じ状態とは限りません。

前回完了時から今回完了後まで

前回の「Hermes Agentのcronに再開地点を残す」では、起動後に止まった job を重複なく再開する判断を扱いました。今回は一段手前です。job を登録する前に、使おうとしているフラグが手元の版に存在するか確認します。

時点状態
前回完了時failedやunknownの後で、外部結果を照合して再開できます
今回開始時docsにある新しい引数を、手元のCLIでも使えると考えがちです
今回完了後versionとhelpを機械判定し、未対応ならjobを作らず停止できます

cron の再実行事故だけを調べたい場合は、前回の記事へ進めます。すでに--pausedが help へ表示される環境では、「対応有無を 1 行で判定する」まで飛ばせます。

なぜversion確認がjob作成より先なのか

Hermes Agent の公式 docs は、公開 repository の開発とともに更新されます。package の release、ローカル checkout、起動中の gateway は、別々の時点を指すことがあります。

今回の実機では、次の警告も出ました。

A previous `hermes update` pulled new code but did not restart running gateways.
Gateways may still be serving pre-update modules (mixed sys.modules).

つまり、確認対象が 1 つでは済みません。

[公式docs / repository main]
              │
              ├── 実装済みの機能
              │
              ▼
[インストール済みCLI] ── versionとhelpを確認
              │
              ▼
[起動中gateway] ─────── restart前は古いmoduleの可能性
              │
              ▼
[cron jobs.json] ────── 実際に保存されるjob定義

hermes --versionが古ければ、新しい引数を渡しません。更新後、gateway を再起動していない場合は、CLI だけでなく process も確認します。この順番なら、本番 job を検証器として使わずに済みます。

用語表

用語この回での意味
CLI help手元の実行ファイルが受け付ける引数の一覧です
version skewdocs、導入済みCLI、起動中processの版がずれた状態です
paused creationjobを最初の保存からenabled: false、state: pausedにする作成方法です
scheduling racejob作成後、pauseが保存される前にschedulerが発火する競合です
gatewaycronのtickとjob実行を担う常駐processです
fail closed対応を確認できないとき、推測で実行せず停止する方針です

実機のversionを読む

repository の外からでも、まず次の 1 本で確認できます。

hermes --version

2026 年 9 月 8 日に確認した先頭行です。

Hermes Agent v0.21.0 (2026.8.31) · upstream baf7ceea

この出力は製品名だけでなく、release 日と upstream commit も示します。記事執筆時の公式 repository main では、paused creation を追加した commit は39ed610f8c2fb2b5474550776edaca77c6880e42でした。手元のbaf7ceeaとは一致しません。

version 番号だけで対応可否を決めず、次に help を見ます。開発版や backport では、version 文字列だけでは機能を判定できないためです。

対応有無を1行で判定する

目視で長い help を読む代わりに、終了コードを含めて判定します。

if hermes cron create --help 2>&1 | grep -q -- '--paused'; then
  printf '%s\n' 'SUPPORTED'
else
  printf '%s\n' 'NOT_SUPPORTED'
fi

今回の実測結果です。

NOT_SUPPORTED

grep -qの結果をifで受けるため、未対応でも shell 全体を異常終了させません。CI や監視 script へ組み込みやすい形です。

引数の周辺まで見る場合は、help をそのまま開きます。

hermes cron create --help

今回の usage には--model、--provider、--continuityまでありましたが、--pausedと--paused-reasonはありませんでした。この状態では、公式 docs の paused creation コマンドを実行しません。

未対応なら、作成してからpauseで代用しない

古い CLI でも、次の 2 操作は個別に使える場合があります。

1. cron jobを有効状態で作成します
2. 作成したjobをpauseします

ただし、これは paused creation と同じではありません。1 回目の保存ではenabled: trueになり、next_run_atも設定されます。gateway の tick と重なれば、2 回目の pause より先に実行対象へ入る余地があります。

公式の paused creation は、最初の locked write で次の状態をまとめて保存します。

enabled: false
state: paused
next_run_at: null
paused_at: 作成時刻
paused_reason: 監査用の理由

さらに、停止中の job は scheduler provider へ trigger 登録されません。作成後に止める方法との違いは、画面上の状態ではなく「有効だった瞬間がない」ことです。

本番公開、課金 API、外部投稿をする job では、この差が重要です。未対応なら更新計画を立て、既存 job や gateway へ変更を加えずに終えます。

対応版で使うコマンド

手元の判定がSUPPORTEDになった後で、公式 docs の書式を使います。次は 1 時間ごとの検証 job を、停止状態で保存する例です。

hermes cron create "every 1h" \
  "読み取り専用の稼働確認を実行し、異常時だけ報告する" \
  --name "morning-canary" \
  --paused \
  --paused-reason "Awaiting operator review"

対応版では、作成結果に停止状態が表示され、次回実行時刻はまだ設定されません。公式実装の CLI メッセージは次の文です。

Created PAUSED — resume to schedule, or explicitly run now.

ここで注意したいのは、paused が権限境界ではないことです。明示的なRun nowや force-run は、停止中でも operator 操作として残ります。操作権限を持つ人まで止める仕組みではありません。

レビュー後に定刻実行へ移す場合は、名前より job ID を優先します。同名 job が複数ある可能性を避けるためです。

hermes cron list --all

一覧で対象を 1 本に絞り、表示された正確な ID を使って resume します。ここでは実在しない ID を例示しません。resume後は、次の未来時刻が計算されたことを一覧で読み返します。

gatewayの版ずれも確認する

CLI を更新しても、起動中 gateway が古い module を保持している場合があります。最初に状態を読みます。

hermes cron status

次に、更新ツールが再起動を求めていないか確認します。今回の実機では、hermes cron create --helpの前に mixed modules の警告が出ました。この警告がある状態で本番 job を変更しません。

更新と gateway 再起動は、稼働中 job へ影響します。定刻直前を避け、実行履歴と次回時刻を控えてから保守枠で行います。再起動後は次の順で読み取り確認します。

hermes --version
hermes cron create --help
hermes cron status
hermes cron list --all

最後に、同じ機能判定をもう一度実行します。

if hermes cron create --help 2>&1 | grep -q -- '--paused'; then
  printf '%s\n' 'SUPPORTED'
else
  printf '%s\n' 'NOT_SUPPORTED'
fi

期待する出力はSUPPORTEDです。NOT_SUPPORTEDのままなら、job 作成へ進みません。

よくあるエラー

症状原因対応
docsのコマンドがunrecognized argumentsになります導入済みCLIが新機能より古い版ですhermes --versionとhermes cron create --helpを確認します
CLI helpには新機能がありますが、gatewayの挙動が古いままです更新前のmoduleを常駐processが保持しています保守枠でgatewayを再起動し、statusとjob一覧を読み返します
pausedで作ったのに手動実行できましたpauseは自動発火を止めますが、operatorのforce-runは残します実行権限と承認手順を別に制御します
--paused-reasonだけで失敗します理由は--pausedと組み合わせる引数です両方を指定します
更新前の代替としてcreate後にpauseしました2操作の間にjobが有効になる競合があります本番jobでは代用せず、対応版まで作成を止めます
versionは新しいのにhelpにフラグがありませんlauncher、source checkout、virtualenvの参照先がずれていますcommand -v hermesと導入先を確認し、公式更新手順で揃えます
listに停止jobが出ません通常一覧がdisabled jobを省く版がありますhermes cron list --allを使います

私は「docsにある」だけでは本番へ入れない

新機能を早く使うことより、実行面がそろっていることを優先します。確認するのは、公式 docs の記載、公開 source の commit、手元 CLI の version と help、起動中 gateway の状態です。

今回の環境はNOT_SUPPORTEDでした。そのため、cron job の作成、pause、更新、gateway 再起動は行っていません。機能不足を見つけた時点で止まれたことが、この手順の完了です。

GSC では「hermes agent cron」が直近 28 日で 1 impression、平均掲載順位 10 位でした。大きな需要ではありませんが、検索している人がすでにいます。私は機能紹介を増やすより、version 差を踏んだときに本番 job を動かさない確認手順を残す方が、無人運用には役立つと考えています。

一次情報

出典確認した内容
Hermes Agent Scheduled TaskscronのCLI、paused creation、gateway、job lifecycleを確認しました
Hermes Agent Cron Internalsjob保存、scheduler tick、state、trigger登録の仕組みを確認しました
paused creationを追加した公式commitenabled、state、next_run_at、CLI引数、testの実装差分を確認しました
NousResearch/hermes-agent releases公開releaseと更新日の確認先です

CLI の実測は 2026 年 9 月 8 日に行いました。新しい版では出力や引数が変わるため、操作時点のhermes cron create --helpを正とします。

この記事をシェア
hibana
この記事を書いた人
hibana

技術ブログを運営しています。日々の学びや発見を発信中。

関連記事