5. 自律的行動システム

Cron、ハートビート、Auto-Reply、フック、サブエージェント

概要

OpenClawが「パーソナルアシスタント」たる最大の特徴は、ユーザーの指示を待たずに能動的にタスクを実行する能力です。この自律的行動は、5つのサブシステムが連携することで実現されています。

自律ループ： Cronがスケジュールジョブを発火 → ハートビートでメインエージェントを起動 → エージェントがHEARTBEAT.mdを読んで行動 → 必要に応じてサブエージェントを生成 → 結果がAuto-Replyを通じてユーザーのチャンネルに配信 → フックが全ステージでイベントを発行

1. Cronシステム（スケジュールタスク）

src/cron/service.ts

アーキテクチャ

完全なジョブスケジューラで、時間ベースの自律的エージェント実行を可能にします。

スケジュールタイプ

種類	説明	例
`at`	一回限りの実行（絶対時刻指定）	「15:00にリマインダー」
`every`	固定間隔（everyMs + anchorMs）	「30分ごとにチェック」
`cron`	標準cron式（タイムゾーン対応）	`0 9 * * *`（毎朝9時）

実行モード

モード	動作
メインセッション	システムイベントテキストをキューに入れ、ハートビートを起動してメインエージェントを呼び出す
分離セッション	独立したPIエージェントをスポーンし、独自のセッション・ツール・モデルで実行。結果はアナウンス/Webhook/なしで配信

実行フロー

armTimer() → setTimeout(60秒上限) │ ▼ onTimer() → タイマーティック │ ├── ジョブリストから期限切れジョブを検索 ├── 各ジョブをrunning状態にマーク ├── 逐次実行 │ ├── [メイン] enqueueSystemEvent() + runHeartbeatOnce() │ └── [分離] runIsolatedAgentJob() → 完全PIエージェント ├── 結果適用 ├── 次回実行時刻の再計算 ├── 状態永続化（JSON5ファイル） └── セッションリーパー（古いCronセッションの掃除）

安全メカニズム

メカニズム	設定
指数バックオフ	30秒 → 1分 → 5分 → 15分 → 60分（連続エラー時）
最小再発火間隔	2秒（スピンループ防止）
ジョブタイムアウト	10分（デフォルト）
スケジュールエラー上限	3回連続でジョブ自動無効化
スタックラン検出	2時間で古いrunningマーカーをクリア
ワンショット自動無効化	`at`ジョブは任意の終了状態後に無効化

2. ハートビートシステム（定期チェックイン）

src/auto-reply/heartbeat.ts

ハートビートとは：定期的にメインエージェントを起動し、 HEARTBEAT.mdファイルに記載された保留中のタスクを確認させる仕組みです。

動作フロー

Cronサービスがハートビートトリガーを発火
ハートビートプロンプトが送信: 「Read HEARTBEAT.md if it exists. Follow it strictly. Do not infer or repeat old tasks. If nothing needs attention, reply HEARTBEAT_OK.」
エージェントがHEARTBEAT.mdを読み、タスクがあれば実行
タスクなしの場合 HEARTBEAT_OK を返却 → ユーザーには通知されない

最適化

デフォルト間隔: 30分
isHeartbeatContentEffectivelyEmpty(): HEARTBEAT.mdにアクション可能なコンテンツがない場合、API呼び出しをスキップ
stripHeartbeatToken(): HEARTBEAT_OK応答を検出し、ユーザーへの送信を抑制
短いACKメッセージ（300文字以下）も抑制対象

3. Auto-Replyシステム（自動応答）

src/auto-reply/

全体フロー

受信メッセージ │ ▼ dispatchInboundMessage() (dispatch.ts:35) │ ▼ dispatchReplyFromConfig() (dispatch-from-config.ts:83) ├── メッセージ重複排除 ├── プラグインフック発火（message_received） ├── 内部フック発火 ├── 停止コマンドの高速中断チェック │ ▼ getReplyFromConfig() → AI応答生成 │ ▼ runReplyAgent() (agent-runner.ts) → PIエージェント実行 ├── セッション履歴読み込み ├── コンテキスト構築 ├── PIエンベデッドエージェント実行（ツール付き） ├── モデルフォールバック処理 ├── リマインダーコミットメント検出 │ └── "I'll remember"と言いつつ未スケジュール → 警告ノート追加 │ ▼ 応答ペイロード生成 │ ▼ TTS変換（設定時） │ ▼ チャンネルルーティング → 送信元チャンネルへ返信

インバウンドデバウンス

src/auto-reply/inbound-debounce.ts

チャンネルごとに設定可能なデバウンスで、連続メッセージをバッチ処理します。

グループアクティベーション

src/auto-reply/group-activation.ts

モード	動作
`mention`	@メンションされた場合のみ応答
`always`	グループ内の全メッセージに応答

メッセージキューモード

モード	動作
`steer`	実行中のエージェントセッションにメッセージを注入
`followup`	次のターンにキュー
`collect`	メッセージをバッチ収集
`steer-backlog`	steerを試行、失敗時にキュー
`interrupt`	現在の処理を中断

4. フックシステム（イベント駆動）

src/hooks/internal-hooks.ts

イベントタイプ

タイプ	発火タイミング
`agent:bootstrap`	エージェント初期化時（ワークスペースDir、ブートストラップファイル、設定を含む）
`gateway:startup`	Gateway起動時
`message:received`	受信メッセージ（from、content、channelId等）
`message:sent`	送信後（to、content、success/error）
`command`	コマンド実行時
`session`	セッションイベント
`agent`	エージェントイベント

フック登録と実行

registerInternalHook(eventKey, handler) — タイプレベル（command）と具体的アクション（command:new）の両方をサポート
triggerInternalHook(event) — タイプレベルと具体的キーの両方のハンドラを発火
エラーはハンドラごとにキャッチ（カスケード障害を防止）

フックの設定可能性

src/hooks/config.ts

shouldIncludeHook(): 明示的無効化、OS要件、プラットフォームチェック、バイナリ可用性、環境変数、設定パスに基づいてフック実行を制御
always: true フラグですべてのチェックをバイパス可能

5. サブエージェントシステム（生成型ワーカー）

src/agents/subagent-spawn.ts、src/agents/subagent-registry.ts

スポーンフロー

サブエージェントスポーン要求 │ ▼ バリデーション ├── スポーン深度チェック（callerDepth >= maxSpawnDepth → 拒否） ├── アクティブ子プロセス数チェック（activeChildren >= maxChildren → 拒否） └── エージェントID許可リストチェック │ ▼ セッション作成 ├── Gatewayで子セッション作成 ├── モデルオーバーライド・思考レベル適用 ├── サブエージェント用システムプロンプト構築 │ ├── "Stay focused"（集中しろ） │ ├── "Complete the task"（タスクを完了しろ） │ ├── "Don't initiate"（自発的行動するな） │ ├── "Be ephemeral"（一時的な存在であれ） │ ├── ユーザー会話禁止 │ ├── 外部メッセージ送信禁止 │ ├── Cronジョブ作成禁止 │ └── 永続的状態保持禁止 │ ▼ 実行 ├── Gatewayのagentメソッドで子タスクを実行 └── サブエージェントレジストリに登録

レジストリ

src/agents/subagent-registry.ts

インメモリMap + ディスク永続化でクロスプロセス可視性を確保
SubagentRunRecord: runId、childSessionKey、requesterSessionKey、タスク、モデル、タイムアウト、結果、アナウンス状態を追跡
ライフサイクルリスナー: lifecycle:start、lifecycle:end、lifecycle:error を監視
スイーパー: 60秒間隔で古いセッションをアーカイブ・削除

アナウンスフロー

src/agents/subagent-announce.ts:710-991

PIランの完了を待機
最新のサブエージェント出力をチャット履歴から取得
子孫サブエージェントの完了を待機（部分的なアナウンスを防止）
統計付き完了メッセージを構築（実行時間、トークン数）
要求者のセッションへ配信
- steered: アクティブセッションに注入
- queued: 後で処理するためにキュー
- direct: Gateway直接呼び出し
ネスト配信: 要求者サブエージェントが消滅済みなら祖父母にバブルアップ
リトライ: 最大3回、指数バックオフ（1秒→2秒→4秒→8秒）、5分で期限切れ

システム連携の全体像

自律的行動の全体フロー: Cronスケジューラ ─┬─[メイン]──→ enqueueSystemEvent() │ │ │ ▼ │ ハートビート起動 │ │ │ ▼ │ メインエージェント │ HEARTBEAT.md読み込み │ │ │ ├── タスクあり → 実行 │ │ └── サブエージェント生成可 │ └── タスクなし → HEARTBEAT_OK │ └─[分離]──→ 独立PIエージェント │ ├── ツール実行 ├── サブエージェント生成可 └── 結果配信 │ ▼ Auto-Reply パイプライン │ フォーマット → TTS → チャンネルルーティング │ ▼ ユーザーへ配信

安全メカニズムまとめ

メカニズム	場所	目的
スポーン深度制限	subagent-spawn.ts	無限エージェント生成の防止（デフォルト最大1）
エージェントあたり最大子数	subagent-spawn.ts	同時子エージェントの制限（デフォルト最大5）
エージェント許可リスト	subagent-spawn.ts	スポーン可能エージェントの制御
Cronエラーバックオフ	timer.ts	指数バックオフ 30秒→60分
Cron自動無効化	jobs.ts	3回のスケジュールエラーでジョブ無効化
ジョブタイムアウト	timer.ts	10分の実行上限
スタック検出	jobs.ts	2時間で古いマーカーをクリア
アナウンスリトライ上限	subagent-registry.ts	最大3回リトライ
アナウンス期限	subagent-registry.ts	5分で古いアナウンスを強制期限切れ
ハートビートスキップ	heartbeat.ts	空のHEARTBEAT.mdでAPI呼び出しスキップ
サブエージェント制約	subagent-announce.ts	Cron/能動的行動/副次クエスト禁止
デバウンス	inbound-debounce.ts	連射メッセージ処理の防止
送信ポリシー	send-policy.ts	自動応答のallow/denyオーバーライド
フックエラー分離	internal-hooks.ts	ハンドラごとのtry/catchでカスケード障害防止

← メモリシステムチャンネルとツール →