このドキュメントでは、OpenClaw Agent が LLM に送信する完全な System Prompt 構造の詳細を説明します。
バージョン:
v2.1
更新日時:
2026-03-05
全体アーキテクチャ図
クイックナビゲーション (TL;DR)
初心者必読:
- レイヤー 7 (Workspace Files) - 直接編集可能な設定ファイル。
- レイヤー 8 (Bootstrap Hook) - スクリプトを記述して動的にコンテンツを注入できる場所。
- その他のレイヤーはフレームワークが自動生成するため、理解するだけで十分。
よくあるニーズ:
- Agent のアイデンティティを定義したい？ → レイヤー 7 の IDENTITY.md を編集。
- プロジェクトドキュメントを追加したい？ → レイヤー 8 の bootstrap-extra-files Hook を使用。
- リアルタイムコンテキストを注入したい？ → レイヤー 8 の before_prompt_build Hook を使用。
- ファイルサイズを制御したい？ → bootstrapMaxChars 設定を調整。
レイヤー 1: OpenClaw Framework コア
アナロジー
操作マニュアルの「使用上の注意」のようなもの。LLM に「あなたは誰か」「何ができるか」「どう応答すべきか」を伝えます。
コンポーネント
実用例
あなたは「クリエイティブパートナー」として実行されています。AI コンテンツ作成エキスパート Agent です。
現在時刻: 2026-03-05 14:37:00 CST
=== ツール呼び出し仕様 ===
- XML スタイルのツール呼び出し形式を使用。
- 各ツール呼び出しには一意の tool_call_id を含める必要があります。
- ツール結果は <tool_result> タグで返されます。
- ツール実行時には AbortSignal を考慮してキャンセルをサポートしてください。
=== 安全境界 ===
- 破壊的操作 (rm -rf、フォーマットなど) は厳禁。
- 機密性の高いユーザー情報は処理時に暗号化する必要があります。
- 許可されていないチャネルへのメッセージ送信は禁止されています。
設計上のトレードオフ
なぜこのように設計したのか？
- トレードオフ: 柔軟性 vs. 一貫性
- 判断: フレームワーク層で統一生成することで、すべての Agent に一貫した基本動作を保証。
- メリット: ユーザーは各 Agent に基本ルールを繰り返し記述する必要がなく、フレームワークのアップグレード時にすべての Agent が自動的に新機能を獲得。設定ミスのリスクを低減。
- コスト: ユーザーはこれらのコアルールを変更できません。特殊な振る舞いはレイヤー 7/8 を介して間接的に実装する必要があります。
レイヤー 2: ツール定義
アナロジー
スイスアーミーナイフのツールリストのようなもの。LLM に「どんなツールがあるか」「各ツールの機能」「使用方法」を伝えます。
コンポーネント
ツール定義例
{
"name": "read",
"description": "ファイルの内容を読み取ります。テキストファイルと画像 (jpg/png/gif/webp) をサポート。画像は添付ファイルとして送信されます。テキスト出力は 2000 行または 50KB に制限されます。",
"parameters": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "ファイルパス (相対パスまたは絶対パス)"
},
"offset": {
"type": "number",
"description": "開始行番号 (1 から開始)"
},
"limit": {
"type": "number",
"description": "読み取る最大行数"
}
},
"required": ["path"]
}
}
設計上のトレードオフ
なぜ JSON Schema を使うのか？
- トレードオフ: 柔軟性 vs. 型安全性
- 判断: 厳格な JSON Schema を使用してツールパラメータを定義。
- メリット: LLM がツールの使用方法をより正確に理解。呼び出し前にフレームワークがパラメータを検証可能。ドキュメントと型定義を自動生成。
- コスト: 新しいツールを追加するには完全な Schema を記述する必要がある。完全に動的なパラメータ構造はサポートできない。
レイヤー 3: スキルレジストリ
アナロジー
レストランの「おすすめメニュー」のようなもの。LLM にどの専門的な「レシピ」を呼び出せるかを伝えます。
設計上のトレードオフ
なぜ手動登録ではなくディレクトリスキャンなのか？
- トレードオフ: 柔軟性 vs. メンテナンスコスト
- 判断: ~/development/openclaw/skills/ ディレクトリを自動スキャン。
- メリット: 新しい Skill を追加するにはディレクトリに配置するだけで設定変更不要。すべての Agent が自動的に新しい Skill を取得。設定ミスのリスクを低減。
- コスト: 各 Agent が利用できる Skill を正確に制御できない。すべての Skill が System Prompt に注入される (トークン消費が増加)。
コンポーネント
レイヤー 4: モデルエイリアス
アナロジー
「ショートカット」のようなもの。複雑なモデルパスに短いエイリアスを与えて簡単に呼び出せるようにします。
設計上のトレードオフ
なぜモデルエイリアスが必要なのか？
- トレードオフ: 柔軟性 vs. 可読性
- 判断: ユーザーがよく使うモデルに短いエイリアスを定義できるようにする。
- メリット: モデル呼び出しを簡略化 (glm-5 で zhipu/glm-5 を指定可能)。複数の Provider 間の切り替えをサポート (同じエイリアスで異なる Provider を指定可能)。A/B テストとモデル移行を容易にする。
- コスト: エイリアス設定ファイルの管理が必要。混乱を招く可能性がある (同じエイリアスが Agent によって異なるモデルを指す可能性)。
コンポーネント
実用例
System Prompt 内では、モデルエイリアスは次のように表示されます:
モデルエイリアス
- GLM-5: zhipu/glm-5
- Opus 4.6: xiaowang886/claude-opus-4-6-thinking
- Sonnet 4.5: xiaowang886/claude-sonnet-4-5
LLM はエイリアスを使用してモデルを切り替えることができます: /model glm-5
レイヤー 5: プロトコル仕様
アナロジー
「交通ルール」のようなもの。Agent とシステム間の標準プロトコルを定義します。
設計上のトレードオフ
なぜプロトコル仕様が必要なのか？
- トレードオフ: 自由度 vs. 一貫性
- 判断: 標準化された対話プロトコル (Silent Replies、Heartbeats、Reply Tags など) を定義。
- メリット: すべての Agent で一貫した動作を保証。自動監視とヘルスチェックをサポート。マルチ Agent コラボレーションを簡素化。
- コスト: Agent の表現の自由度を制限。LLM がプロトコルを厳密に遵守する必要がある (無視される可能性もある)。
コンポーネント
実用例
Silent Replies の例:
ユーザー: Received
Agent: NO_REPLY
Heartbeats の例:
システム: [Heartbeat Poll]
Agent: HEARTBEAT_OK
Reply Tags の例:
Agent: [[reply_to_current]] タスク完了 ✓
レイヤー 6: ランタイム情報
アナロジー
「ダッシュボード」のようなもの。LLM に現在の実行環境のリアルタイムステータスを伝えます。
設計上のトレードオフ
なぜ毎回ランタイム情報を注入するのか？
- トレードオフ: トークン消費 vs. コンテキスト精度
- 判断: リクエストごとに最新のランタイムステータスを注入。
- メリット: LLM が現在時刻を把握 (時刻の混乱を回避)。LLM が現在のモデルを把握 (能力の誤判断を回避)。LLM が現在の環境を把握 (パスエラーを回避)。
- コスト: リクエストごとに約 2KB のトークンを消費。情報に冗長性が含まれる可能性あり。
コンポーネント
実用例
ランタイム
レイヤー 7: Workspace Files ★ ユーザー制御可能
アナロジー
「あなたの作業メモ」のようなもの。直接編集できる静的設定ファイルです。
設計上のトレードオフ
なぜこのレイヤーのみ静的に編集可能なのか？
- トレードオフ: フレームワークの安定性 vs. ユーザーの自由度
- 判断: 「変更するもの」と「変更しないもの」を分離。フレームワーク層は一貫性を保ち、ユーザー層はカスタマイズを可能にする。
- メリット: ユーザーは Agent のアイデンティティ、作業仕様、メモリを定義可能。フレームワークのアップグレードでユーザー設定が壊れない。設定ファイルをバージョン管理、バックアップ、共有可能。
- コスト: ユーザーはコアフレームワークの動作を変更できない。TELOS フレームワークとファイル構造を学ぶ必要がある。
コアファイル
レイヤー 8: Bootstrap Hook System ★ ユーザー制御可能
アナロジー
「プログラム可能な注射器」のようなもの。スクリプトを書いて System Prompt に動的にコンテンツを注入できます。
設計上のトレードオフ
なぜ Hook システムが必要なのか？
- トレードオフ: 静的設定のシンプルさ vs. 動的注入の柔軟性
- 判断: 静的な Workspace Files に加えて、動的な Hook メカニズムを提供。
- メリット: コンテキスト (チャネル、送信者、時刻) に基づいて注入コンテンツを動的に調整可能。シェルコマンドを実行して出力を注入可能 (例: 現在の天気、Git ステータス)。外部ファイルを読み込んで注入可能 (例: プロジェクトドキュメント、API ドキュメント)。条件ロジック (if/else) をサポート。
- コスト: Hook システムの構文とトリガーメカニズムを学ぶ必要がある。Hook スクリプトのエラーで System Prompt に異常が発生する可能性。システムの複雑さが増す。
4 つの Hook メカニズム
- agent:bootstrap Hook (内部 Hook システム)
トリガー位置: bootstrap-hooks.ts の applyBootstrapHookOverrides()
機能:
- bootstrapFiles 配列を完全に制御。
- ファイルの追加、削除、修正が可能。
- ファイルの並び替えが可能。
- ファイルの内容を変更可能。
登録できる対象:
- OpenClaw プラグイン。
- Workspace Hooks (~/.openclaw/workspace-*/hooks/ ディレクトリ)。
- 内部モジュール。
コード例:
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
// bootstrapFiles 配列を完全に制御
context.bootstrapFiles = [
{ path: "CUSTOM.md", content: "カスタムコンテンツ" }
];
});
- bootstrap-extra-files Hook (バンドル Hook)
トリガー位置: hooks/bundled/bootstrap-extra-files/ の handler.ts
機能:
- ファイルの追加のみ。既存ファイルは変更しない。
- 設定ファイルで追加ファイルを指定。
設定例:
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["extra/*.md", "docs/CONTEXT.md"]
}
}
}
適用シナリオ:
- プロジェクト固有のコンテキストファイルを注入したい場合。
- デフォルトの 8 つの Bootstrap ファイルを変更したくない場合。
- 追加のドキュメントを動的に読み込みたい場合。
- before_prompt_build Hook (プラグイン Hook)
トリガー位置: attempt.ts の runBeforePromptBuild()
機能:
- 最終プロンプトを変更 (システムプロンプト構築後、LLM 送信前)。
- コンテキストを先頭に追加可能 (プロンプトの前にコンテンツを追加)。
- systemPrompt をオーバーライド可能。
イベントデータ:
{
prompt: string; // ユーザー入力
messages: unknown[]; // セッションメッセージ履歴
}
戻り値:
{
prependContext?: string; // プロンプトの前に追加するコンテンツ
systemPrompt?: string; // システムプロンプトをオーバーライド
}
適用シナリオ:
- セッション履歴に基づいてプロンプトを動的に調整したい場合。
- リアルタイムコンテキスト (例: 現在時刻、天気) を注入したい場合。
- システムプロンプトを完全に置き換えたい場合。
- bootstrapMaxChars / bootstrapTotalMaxChars (設定項目)
種類: 設定項目 (Hook ではない)
機能:
- 文字数予算を制御。
- 単一ファイルのデフォルト: 20K。
- 合計のデフォルト: 150K。
- 超過時は先頭 70% + 末尾 20% を残して切り詰め。
設定場所:
{
"agents": {
"defaults": {
"bootstrapMaxChars": 20000,
"bootstrapTotalMaxChars": 150000
}
}
}
実用的なアドバイス
シナリオ 1: プロジェクトドキュメントを追加したい
推奨解決策: bootstrap-extra-files
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["docs/API.md", "docs/ARCHITECTURE.md"]
}
}
}
シナリオ 2: タスクタイプに応じてファイルを動的に読み込みたい
推奨解決策: カスタム agent:bootstrap Hook
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
const sessionKey = context.sessionKey;
// セッションタイプに応じて異なるファイルを読み込み
if (sessionKey.includes("coding")) {
context.bootstrapFiles.push({
path: "CODING_GUIDELINES.md",
content: fs.readFileSync("...").toString()
});
}
});
シナリオ 3: リアルタイムコンテキスト (現在時刻など) を注入したい
推奨解決策: before_prompt_build Hook
on("before_prompt_build", (event, ctx) => {
return {
prependContext: 現在時刻: ${new Date().toISOString()}
};
});
レイヤー 9: Inbound Context
アナロジー
「リアルタイム交通情報」のようなもの。リクエストごとに現在の会話のコンテキスト情報を動的に注入します。
設計上のトレードオフ
なぜ毎回コンテキストを注入するのか？
- トレードオフ: トークン消費 vs. 会話の一貫性
- 判断: リクエストごとに最新のメッセージメタデータ、送信者情報、会話履歴を注入。
- メリット: LLM が現在誰が話しているかを把握 (送信者の混乱を回避)。LLM が会話履歴を把握 (コンテキストの一貫性を維持)。LLM が自分が @ メンションされたかを把握 (応答するかどうかを判断)。
- コスト: リクエストごとに約 3KB のトークンを消費。会話履歴にノイズが含まれる可能性あり。
コンポーネント
完全な System Prompt 組み立てプロセス
ユーザー制御可能なレイヤーのまとめ
OpenClaw は 3 種類のユーザー制御可能なメカニズム を提供します:
- レイヤー 7 (Workspace Files) - 静的設定ファイル。シナリオ: Agent のアイデンティティ、作業仕様、メモリの定義。メリット: シンプルで直感的、バージョン管理が容易。デメリット: 動的に調整できない。
- レイヤー 8 (Bootstrap Hook System) - 動的注入スクリプト。シナリオ: コンテキストに基づくコンテンツ注入、コマンド実行、外部ファイル読み込み。メリット: 柔軟で強力、ロジックとコマンドをサポート。デメリット: Hook システムの学習が必要。スクリプトエラーで問題が発生。
- 間接的なレイヤー 9 (Inbound Context) の制御 - メッセージ送信によるコンテキストへの影響。シナリオ: チャット履歴や引用メッセージで LLM の動作に影響。メリット: 設定不要、自然な対話。デメリット: 正確な制御ができない。
サイズ比較表
⚠️
注: 以下のデータは概算です。実際のサイズは設定とランタイムコンテキストによって異なります。フレームワークのレイヤー (レイヤー 1-6 + 9) は理論上同じになるはずですが、ツール定義や読み込まれる Skill などにより若干異なる場合があります。
注:
- レイヤー 7 とレイヤー 8 はユーザー制御可能なため、サイズは Agent 設定によって異なります。
- その他のレイヤーは自動生成され、理論上すべての Agent で同じです。
- 実際の測定値は、利用可能なツール、Skill の読み込み、ランタイムコンテキストによって異なる場合があります。
最適化の提案
- ユーザー制御可能部分の最適化 (レイヤー 7 + 8)
レイヤー 7 と 8 はユーザーが制御するため、最適化戦略は以下の通りです:
レイヤー 7 (静的ファイル) の最適化:
✅ 推奨されるスリム化戦略:
- IDENTITY.md: コアの TELOS フレームワークを維持し、冗長な説明を削除。段落ではなく表を使用。
- AGENTS.md: 長い段落ではなくチェックリストを使用。コマンドはコードブロックで表示。重複するルール説明を削除。
- MEMORY.md: MemOS の自動エクスポートに依存。手動でコンテンツを追加せず、システムに管理させる。
❌ 避けるべきプラクティス:
- OpenClaw フレームワークが既に認識している説明を繰り返さない。
- 詳細な Skill 説明を Workspace Files にコピーしない。
- 過度なレトリックや装飾的な言葉を使用しない。
レイヤー 8 (Hook システム) の最適化:
✅ 推奨される使用戦略:
- シンプルなシナリオでは bootstrap-extra-files を優先。
- 条件ロジックが必要な複雑なシナリオでは agent:bootstrap を使用。
- リアルタイムコンテキストが必要な動的シナリオでは before_prompt_build を使用。
❌ 避けるべきプラクティス:
- Hook 内で時間のかかる操作を実行しない (System Prompt 生成をブロック)。
- Hook 内で過剰な量のコンテンツを注入しない (トークン制限を超過)。
- Hook 内で不安定な外部依存関係を使用しない (起動障害の原因)。
- プロンプト削減戦略
System Prompt が大きすぎる場合は、以下を検討:
結論
OpenClaw の System Prompt は単一ファイルではなく、注意深く調整された 9 層アーキテクチャ です:
- レイヤー 1-6: フレームワークが自動生成し、一貫性と安定性を保証。
- レイヤー 7: ユーザーが編集可能な静的設定ファイル (IDENTITY.md、AGENTS.md など)。
- レイヤー 8: ユーザーがプログラミング可能な動的注入スクリプト (Bootstrap Hook System)。
- レイヤー 9: フレームワークが自動注入するリアルタイムコンテキスト (Inbound Context)。
ユーザーが制御可能なレイヤーは 2 つ (レイヤー 7 と 8) です。以前誤ってレイヤー 7 だけと言ったのは間違いでした。
これらのレイヤーの違いと関連性を理解することが、OpenClaw 設定をマスターする鍵です。
