OpenClaw Agent Runtime の仕組みを理解する

エージェントを開発していると、コンテキストの管理や設定ファイルの散らばりに悩まされることがよくあります。セッションごとに挙動が変わってしまったり、指示がうまく伝わらなかったりするのは、開発者にとって大きなストレスですよね。

OpenClaw の Agent Runtime は、pi-mono をベースにした単一の組み込みランタイムを採用しており、こうした煩雑な管理をシンプルにします。

必要なもの

• agents.defaults.workspace の設定（必須）
• openclaw setup による初期化（推奨）

クイックスタート

まずは 5 分で最小構成をセットアップしましょう。

1. openclaw setup を実行します。これにより ~/.openclaw/openclaw.json が作成され、ワークスペースファイルが初期化されます。
2. openclaw.json で最低限必要な設定を行います。

{
  "agents": {
    "defaults": {
      "workspace": "/path/to/your/workspace"
    }
  },
  "channels": {
    "whatsapp": {
      "allowFrom": ["your-phone-number"]
    }
  }
}

3. ワークスペース内に生成された AGENTS.md や SOUL.md を編集して、エージェントの挙動を定義します。

ワークスペースと Bootstrap ファイル

OpenClaw は、agents.defaults.workspace で指定されたディレクトリを、ツール実行やコンテキスト保持のための唯一のカレントディレクトリ（cwd）として使用します。

セッションの開始時、OpenClaw は以下のファイルをエージェントのコンテキストに注入します。

• AGENTS.md: 指示事項と「メモリ」
• SOUL.md: ペルソナ、境界線、トーン
• TOOLS.md: ツールの使い方のメモ
• BOOTSTRAP.md: 初回実行時の儀式用（完了後に削除されます）
• IDENTITY.md: エージェント名や絵文字
• USER.md: ユーザープロフィールと呼び方

ファイルが空の場合はスキップされ、巨大なファイルはプロンプトを軽量に保つために切り詰められます。もし pre-seeded なワークスペースを使用しており、Bootstrap ファイルの自動作成を無効にしたい場合は、以下の設定を追加してください。

{ "agent": { "skipBootstrap": true } }

スキルとツール

OpenClaw は以下の場所からスキルを読み込みます。名前が衝突した場合はワークスペースのスキルが優先されます。

• インストール時に同梱されているもの
• ローカル管理: ~/.openclaw/skills
• ワークスペース: <workspace>/skills

コアツール（read/exec/edit/write など）は常に利用可能ですが、apply_patch のように tools.exec.applyPatch で制限されているものもあります。

ストリーミングの制御

メッセージの処理モード（queue mode）によって、エージェントの挙動を調整できます。

• steer モード: ツール実行の合間に新しいメッセージを確認します。ユーザーからの入力があれば、残りのツール実行をスキップして即座に対応します。
• followup / collect モード: 現在のターンが終了するまで入力を保持し、その後に新しいターンを開始します。

また、blockStreaming はデフォルトで off です。有効にする場合は agents.defaults.blockStreamingDefault: "on" のように設定し、blockStreamingChunk でチャンクサイズ（デフォルト 800–1200 文字）を調整できます。

Model refs の指定方法

モデルの設定（agents.defaults.model など）では、最初の / で区切る形式を使用します。

• 基本形式: provider/model
• OpenRouter などモデル ID 自体に / が含まれる場合: openrouter/moonshotai/kimi-k2
• プロバイダーを省略した場合: デフォルトプロバイダーのモデルとして扱われます（モデル ID に / が含まれない場合のみ）。

トラブルシューティング

• Bootstrap ファイルが作成されない: BOOTSTRAP.md は、他の Bootstrap ファイルが存在しない完全に新規のワークスペースでのみ作成されます。
• ファイルが読み込まれない: ファイルが空の場合、OpenClaw はそのファイルをスキップします。
• セッションが見つからない: OpenClaw は独自のセッション管理を行っており、レガシーな Pi/Tau のセッションフォルダは読み込みません。セッションは ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl に保存されます。

---

セットアップで困ったことがあれば、AI Setup Assistant を活用してください。

What’s Next: Group Chats