推奨する読み進め順
OpenClawのコードベースは大規模ですが、以下の順序で読み進めることで
効率的に全体像を理解できます。
Step 1: プロジェクトドキュメントを読む
| ファイル | 内容 | 所要目安 |
|---|
README.md | プロジェクト概要、機能一覧、セットアップ | 最初に |
VISION.md | プロジェクトのビジョン、方向性、設計方針 | 最初に |
AGENTS.md | 開発ガイドライン、コーディング規約、テスト方法 | 開発時に |
Step 2: エントリポイントを追う
読み始めるファイル：src/entry.ts → src/cli/run-main.ts → src/gateway/server.impl.ts
| ファイル | 読むべきポイント |
|---|
src/entry.ts | プロセス起動の最初のステップ。再スポーン機構に注目。 |
src/cli/run-main.ts | runCli()関数。高速ルートと通常ルートの分岐。 |
src/cli/program/build-program.ts | Commander.jsプログラム構築。コマンド登録パターン。 |
src/gateway/server.impl.ts | startGatewayServer()。15ステップの起動シーケンス。 |
Step 3: システムプロンプト構築を理解する
最重要ファイル：src/agents/system-prompt.ts
| ファイル | 読むべきポイント |
|---|
src/agents/system-prompt.ts | buildAgentSystemPrompt()。20+セクションの組み立てロジック全体。 |
src/agents/system-prompt-params.ts | buildSystemPromptParams()。ランタイム情報の解決。 |
src/agents/identity.ts | アイデンティティ解決の階層（ACKリアクション、メッセージプレフィックス）。 |
src/agents/identity-file.ts | IDENTITY.mdの解析。 |
src/agents/workspace.ts | ブートストラップファイルの読み込みとフィルタリング。412-466行のファイルリスト。 |
src/agents/bootstrap-files.ts | ブートストラップファイルのコンテキスト構築と切り詰め。 |
src/agents/sanitize-for-prompt.ts | プロンプトインジェクション対策。 |
Step 4: エージェントランタイム（PI Embedded）を理解する
核心のファイル群。コード量が多いので、関数シグネチャとコメントを先に追うことを推奨。
| ファイル | 読むべきポイント |
|---|
src/agents/pi-embedded.ts | バレルモジュール。エクスポートの全体像を把握。 |
src/agents/pi-embedded-runner.ts | バレルモジュール。run/attempt/compact等のre-export。 |
src/agents/pi-embedded-runner/run.ts | runEmbeddedPiAgent()。メインループ。174-1081行。 |
src/agents/pi-embedded-runner/run/attempt.ts | 1回の試行の全ステップ。222-1282行。 |
src/agents/pi-embedded-subscribe.ts | subscribeEmbeddedPiSession()。ストリーミングイベント処理。 |
src/agents/pi-embedded-runner/compact.ts | コンパクション（コンテキスト圧縮）。 |
src/agents/compaction.ts | コンパクションアルゴリズム（チャンキング、要約、刈り込み）。 |
src/agents/tool-loop-detection.ts | ツールループ検出システム。 |
Step 5: メモリシステムを理解する
| ファイル | 読むべきポイント |
|---|
src/memory/manager.ts | MemoryIndexManager。検索エントリポイント、シングルトンキャッシュ。 |
src/memory/embeddings.ts | Embeddingプロバイダファクトリ。autoモードの解決ロジック。 |
src/memory/hybrid.ts | ハイブリッドマージアルゴリズム。ベクトル+キーワードの統合。 |
src/memory/mmr.ts | MMR多様性再ランキング。 |
src/memory/temporal-decay.ts | 時間的減衰。エバーグリーン vs 時限的知識の判定。 |
src/memory/internal.ts | チャンキング、ハッシュ、コサイン類似度。 |
src/agents/memory-search.ts | エージェント側のメモリ検索設定解決。 |
Step 6: 自律的行動システムを理解する
| ファイル | 読むべきポイント |
|---|
src/cron/service.ts | CronServiceクラス。CRUD操作。 |
src/cron/service/timer.ts | タイマーティック処理。armTimer()とonTimer()。 |
src/cron/isolated-agent.ts | 分離エージェントジョブの実行。 |
src/auto-reply/dispatch.ts | 受信メッセージディスパッチのエントリポイント。 |
src/auto-reply/heartbeat.ts | ハートビートメカニズム。プロンプトと応答処理。 |
src/agents/subagent-spawn.ts | サブエージェントスポーンのバリデーションと実行。 |
src/agents/subagent-registry.ts | サブエージェントライフサイクル管理。 |
src/agents/subagent-announce.ts | 完了アナウンスフロー。 |
src/hooks/internal-hooks.ts | フックシステムの登録と発火。 |
Step 7: チャンネルとツールを理解する
| ファイル | 読むべきポイント |
|---|
src/channels/dock.ts | チャンネルDockメタデータ。各チャンネルの振る舞い定義。 |
src/channels/registry.ts | チャンネルレジストリ。8コアチャンネル。 |
src/agents/pi-tools.ts | createOpenClawCodingTools()。ツール組み立てとポリシーパイプライン。 |
src/agents/tool-policy.ts | ツールプロファイルとグループ定義。 |
src/agents/openclaw-tools.ts | createOpenClawTools()。ネイティブツールの生成。 |
src/agents/tools/message-tool.ts | messageツール。53アクションの動的スキーマ。 |
src/agents/skills.ts | スキル読み込みと優先度解決。 |
主要呼び出しフロー図
フロー1: ユーザーメッセージ受信 → AI応答
[チャンネル] ユーザーがメッセージ送信
│
▼ チャンネルプラグインが受信
│
▼ dispatchInboundMessage() [src/auto-reply/dispatch.ts:35]
│
▼ dispatchReplyFromConfig() [src/auto-reply/reply/dispatch-from-config.ts:83]
├── 重複排除
├── フック発火 (message_received)
├── コマンド検出 (/status, /reset 等)
│
▼ getReplyFromConfig()
│
▼ runReplyAgent() [src/auto-reply/reply/agent-runner.ts]
│
▼ runEmbeddedPiAgent() [src/agents/pi-embedded-runner/run.ts:174]
├── モデル解決
├── 認証プロファイル解決
│
▼ attempt() [src/agents/pi-embedded-runner/run/attempt.ts:222]
├── ツール生成: createOpenClawCodingTools() [src/agents/pi-tools.ts:164]
├── システムプロンプト構築: buildAgentSystemPrompt() [src/agents/system-prompt.ts:169]
├── セッション作成
├── 履歴サニタイズ
├── サブスクリプション: subscribeEmbeddedPiSession() [src/agents/pi-embedded-subscribe.ts]
│
▼ activeSession.prompt(effectivePrompt) ← LLM呼び出し
│
▼ [ストリーミング応答]
├── ツール呼び出し → ツール実行 → 結果をLLMに返却 → 繰り返し
├── テキスト出力 → ブロックチャンキング → onBlockReply()
│
▼ 結果収集 (assistantTexts, toolMetas, usage)
│
▼ 応答ペイロード生成
│
▼ TTS変換（設定時）
│
▼ チャンネルルーティング → ユーザーへ送信
フロー2: Cronジョブ実行 → 自律的行動
Cronタイマーティック
│
▼ onTimer() [src/cron/service/timer.ts:187]
├── ジョブ期限チェック
│
▼ executeJobCore() [src/cron/service/timer.ts:455]
│
├─[メインセッション]─────────────────────────────────┐
│ ▼ enqueueSystemEvent() │
│ ▼ requestHeartbeatNow() or runHeartbeatOnce() │
│ ▼ ハートビートプロンプト送信 │
│ ▼ メインエージェントがHEARTBEAT.md読み込み │
│ ▼ タスク実行 or HEARTBEAT_OK応答 │
│ │
├─[分離セッション]─────────────────────────────────────┐
│ ▼ runIsolatedAgentJob() [src/cron/isolated-agent/run.ts]
│ ▼ 独立PIエージェントスポーン │
│ ▼ ツール付きでタスク実行 │
│ ▼ 結果配信（announce/webhook/none） │
└──────────────────────────────────────────────────────┘
フロー3: サブエージェントスポーン → 結果アナウンス
親エージェントが sessions_spawn ツールを呼び出し
│
▼ spawnSubagentDirect() [src/agents/subagent-spawn.ts:70]
├── 深度チェック (maxSpawnDepth)
├── 子数チェック (maxChildren)
├── 許可リストチェック
│
▼ 子セッション作成（Gateway経由）
▼ サブエージェント用システムプロンプト構築
▼ Gateway agent()呼び出し → 子PIエージェント実行
▼ レジストリに登録
│
▼ [子エージェント実行中...]
│ ├── ツール実行
│ ├── さらにサブエージェント生成可（深度制限内）
│ └── 完了
│
▼ runSubagentAnnounceFlow() [src/agents/subagent-announce.ts:710]
├── PIラン完了待機
├── 最新出力取得
├── 子孫完了待機
├── 統計付き完了メッセージ構築
│
▼ 親セッションへ配信
├── steered: アクティブセッションに注入
├── queued: 後で処理キュー
└── direct: Gateway直接呼び出し
フロー4: メモリ検索
エージェントが memory_search ツールを呼び出し
│
▼ MemoryIndexManager.search() [src/memory/manager.ts:203]
├── ダーティなら同期実行
│
├─[Embeddingあり]────────────────────────────────────┐
│ ▼ embed(query) → ベクトル生成 │
│ ▼ vectorSearch(): cosine距離で近傍検索 │
│ ▼ keywordSearch(): FTS5 BM25ランキング │
│ ▼ hybridMerge(): 0.7×vector + 0.3×text │
│ ▼ temporalDecay(): 時間的減衰適用 │
│ ▼ mmrRerank(): 多様性再ランキング │
│ ▼ minScore=0.35フィルタ + maxResults=6 │
│ │
├─[Embeddingなし]────────────────────────────────────┐
│ ▼ extractKeywords(): ストップワード除去 │
│ ▼ 各キーワードで独立FTS検索 │
│ ▼ マージ・重複排除 │
└──────────────────────────────────────────────────────┘
│
▼ 結果をエージェントに返却（パス、行番号、関連テキスト）
設定ファイル対応表
| ファイル | 場所 | 型定義 |
|---|
openclaw.json | ~/.openclaw/openclaw.json | src/config/types.ts |
SOUL.md | ワークスペースルート | - |
IDENTITY.md | ワークスペースルート | src/agents/identity-file.ts:5 |
USER.md | ワークスペースルート | - |
AGENTS.md | ワークスペースルート | - |
TOOLS.md | ワークスペースルート | - |
MEMORY.md | ワークスペースルート | - |
HEARTBEAT.md | ワークスペースルート | - |
BOOTSTRAP.md | ワークスペースルート（初回のみ） | - |
jobs.json | ~/.config/openclaw/cron/ | src/cron/types.ts |
*.jsonl | ~/.openclaw/sessions/ | - |
*.sqlite | ~/.openclaw/state/memory/ | - |
主要型定義の場所
| 型 | ファイル |
|---|
OpenClawConfig | src/config/config.ts |
IdentityConfig | src/config/types.base.ts:187 |
ChannelPlugin | src/channels/plugins/types.plugin.ts:48 |
ChannelDock | src/channels/dock.ts:47 |
CronJob | src/cron/types.ts |
SubagentRunRecord | src/agents/subagent-registry.ts |
SkillEntry | src/agents/skills/types.ts:66 |
PromptMode | src/agents/system-prompt.ts:15 |
デバッグ・調査のコツ
*.e2e.test.ts ファイルは実際の使用パターンを示しており、動作仕様の理解に最適*.test-harness.ts ファイルはテスト用のモック・ヘルパーで、依存関係の把握に役立つ- 設定スキーマは
src/config/types.*.ts の30以上のファイルに分散。全体像は src/config/types.ts のインポートから追える
src/agents/defaults.ts にデフォルトプロバイダ・モデルの定義がある- ツールの具体的実装は
src/agents/tools/ ディレクトリ内の各ファイル