メインコンテンツまでスキップ

Cron スケジューラ

Cron スケジューラは、スクリプトをスケジュール実行します -- crontab 式、固定インターバル、 または遅延後の一回実行 -- OS の crontab や別デーモンに依存しません。ChatWalaʻau に組み込まれた 小さなファイルベースのスケジューラで、インプロセスの tick ループが（既定 60 秒ごとに）実行すべき ジョブを確認して実行します。

本機能は オプトイン で、既定では無効です。CRON_ENABLED=true で有効化します。

有効化​

Cron 実行は script-only（スクリプト実行のみ）で、コードワークスペース内で実行されるため、 コーディングツールのセキュリティ境界を再利用します。次の両方が必要です:

CRON_ENABLED=true
CODING_ENABLED=true
CODING_WORKSPACE_DIR=/path/to/your/workspace

CRON_ENABLED が無効のとき、スケジューラは起動せず、エージェントツールも登録されず、ポータルの アイコンも非表示になり、ランタイムは変化しません。

ジョブの管理​

ジョブの管理方法は 3 つあり、いずれも同じストアに書き込みます。

  • ポータル UI -- サイドバー下部の時計アイコン（情報アイコンの隣）をクリック、またはチャット 入力欄で /cron と入力します。ポータルはジョブ一覧の表示、作成・編集・削除、そして時系列の 実行タイムライン を表示します。実行をクリックすると stdout / stderr を確認できます。 Refresh ボタンで再取得します。ジョブの削除は確認ダイアログを経てから実行されます。
  • エージェント -- 自然言語で依頼します。例:「毎週平日 9 時に scripts/backup.py を実行して」 「このスクリプトを 30 分後に実行して」。アシスタントは manage_cron ツールを使います。 エージェントが作成したジョブは既定で有効です。
  • REST API -- GET/POST /api/cron/jobs、GET/PUT/DELETE /api/cron/jobs/{id}、 GET /api/cron/jobs/{id}/runs、GET /api/cron/runs/{run_id}。変更系エンドポイントは認証が必要 です（loopback は免除）。

各ジョブは カテゴリ、概要（description）、有効フラグ、スケジュール、そして スクリプト（ワークスペース内のパス。インタプリタと引数は任意）を持ちます。

スケジュールの種類​

  • cron 式 -- 標準的な crontab 表記（5 フィールド以上）。例: 0 9 * * MON。
  • recurring interval -- N 秒ごとに実行。
  • one-shot -- 絶対時刻に一回だけ実行（エージェントの「N 分後」はこれに対応）。

時刻はタイムゾーン付き ISO-8601 で保存されます。cron 式は CRON_TIMEZONE（Pacific/Honolulu のような IANA 名）で評価されます。空にするとサーバのローカルタイムゾーンを使います。

実行の仕組み​

  • スケジューラは各ジョブの 次回実行時刻 を保存し、tick ごとに next_run_at <= now だけを 確認します -- 全式を常時走査しません。
  • 実行前に次回実行時刻を進める ため、実行中にプロセスが落ちても再起動時に同じジョブが即座に 再実行されません（クラッシュループ回避）。cron と同様、逃した実行はリトライしません。
  • アプリが停止していて実行が grace window（CRON_GRACE_WINDOW_SECONDS、既定 120 秒）を超えて 遅延した場合、溜まった分をまとめて実行せず、次回の未来時刻へ fast-forward します。
  • tick は同時に 1 つだけ実行されます（クロスプラットフォームなロック）。複数ワーカーでも二重実行 しません。

実行とログ​

スクリプトはワークスペースを作業ディレクトリとして実行されます。インタプリタはジョブの interpreter フィールド、なければ拡張子から推定します（.py -> Python、.sh -> sh、 .ps1 -> pwsh、.js -> node ...）。各実行には wall-clock タイムアウト （CRON_RUN_TIMEOUT_SECONDS）があり、stdout / stderr は CRON_JOBS_DIR/output/{job_id}/{run}/ 配下に保存されます（CRON_OUTPUT_MAX_BYTES で上限）。

セキュリティ​

Cron 実行は無人実行のため、都度のツール承認プロンプトは 通りません。保護は次の通りです: 既定で無効（CRON_ENABLED）、実行には CODING_ENABLED が必須、すべてのスクリプトパスは CODING_WORKSPACE_DIR 内に限定、管理 API は認証付き。スケジュールされたジョブは人手を介さず タイマーでスクリプトを実行する点に注意し、信頼できるスクリプトのみをスケジュールしてください。

設定リファレンス​

変数既定説明
CRON_ENABLEDfalse機能全体のマスタースイッチ。
CRON_TICK_SECONDS60tick 間隔（5..3600 にクランプ）。
CRON_JOBS_DIR.cronジョブごとの JSON。実行ログは output/ 配下。
CRON_GRACE_WINDOW_SECONDS120遅延許容（120..7200 にクランプ）。超過時は fast-forward。
CRON_TIMEZONE(空)cron 式評価の IANA タイムゾーン。空 = システムローカル。
CRON_RUN_TIMEOUT_SECONDS900実行ごとの subprocess タイムアウト。
CRON_OUTPUT_MAX_BYTES1048576捕捉する stdout/stderr ログ 1 ファイルの上限。

Cron 実行には CODING_ENABLED と CODING_WORKSPACE_DIR も必要です （設定 を参照）。