【#1】 OpenClaw を読み解く — 百万行の森の地図と憲法
連載初回は、コードを1行も読む前に押さえておきたい「OpenClaw とは何か」「なぜこの構造なのか」を、リポジトリの一次情報（VISION.md / README.md / AGENTS.md）からたどります。地図を持たずに、テストを除いても 100 万行超の森には入れません。
連載「OpenClaw を読み解く」
OpenClaw とは何者か — 「手を動かす」AI の宣言
VISION.md の冒頭はこう宣言しています。
OpenClaw is the AI that actually does things.
It runs on your devices, in your channels, with your rules.
つまり OpenClaw は「手を動かす（実際にタスクを実行する）」パーソナル AI アシスタントです。クラウドの SaaS ではなく、**自分のマシン上で動く Gateway（制御プレーン）**を中心に据えるのが最大の特徴です。README.md の表現を借りれば、
The Gateway is just the control plane — the product is the assistant.
Gateway はあくまで土台で、ユーザーが触れる「アシスタント」が製品本体、という位置づけです。
出自
VISION.md には改名の歴史が刻まれています。
Warelay -> Clawdbot -> Moltbot -> OpenClaw
個人が「AI を学び、本当に役立つものを作る」遊び場として始まったプロジェクトが、いまや 20 以上のメッセージングチャネルと多数のモデルプロバイダを抱える基盤に育った、という背景です。READMEが対応チャネルとして挙げるのは WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal, WeChat, QQ, WebChat ……と圧巻です。
巨大な森 — 数字が突きつける森の広さ
2026.6.2（main）時点の実測値です（find + wc による概算）。
| 対象 | 規模 |
|---|---|
src/ TypeScript |
8,860 ファイル / 約 252 万行（テスト含む） |
src/ TypeScript（*.test.ts 等を除外） |
5,197 ファイル / 約 113 万行 |
extensions/（プラグイン実装） |
6,510 ファイル / 131 個の package.json
|
packages/（共有パッケージ） |
430 ファイル / 21 パッケージ |
docs/ |
723 ファイル（Markdown/MDX は 671） |
このサイズの OSS を「読み解ける」と言えるのは、後述する**明確な所有境界（ownership boundary）**が一貫して敷かれているからです。
森の地図 — ディレクトリという名の道しるべ
ルート直下の主要ディレクトリを、役割で分類します。
openclaw/
├── src/ # コア（プラグイン非依存のランタイム）
│ ├── entry.ts # CLI プロセスのエントリポイント（#02 で詳説）
│ ├── gateway/ # 制御プレーン本体（#03）
│ ├── plugin-sdk/ # プラグインが core に入る唯一の窓口（#04）
│ ├── plugins/ # プラグインローダー（#04）
│ ├── channels/ # チャネル抽象（transport-only, #05）
│ ├── provider-runtime/ # プロバイダ実行時フック（#06）
│ ├── model-catalog/ # モデルカタログ・正規化（#06）
│ ├── llm/ # LLM 共通型・実行補助（#06）
│ ├── agents/ # エージェントループ（#07）
│ ├── context-engine/ # 文脈管理（#08）
│ ├── sessions/ # セッション履歴（#08）
│ ├── trajectory/ # 実行軌跡（#08）
│ ├── memory/ # メモリ（#09）
│ ├── state/ # 永続状態・SQLite（#10）
│ ├── media-*/ # メディア系能力（#11）
│ ├── mcp/ acp/ # 外部プロトコル（#11）
│ └── ...
├── extensions/ # プラグイン群（チャネル / プロバイダ / その他）
├── packages/ # ワークスペース共有パッケージ
│ ├── gateway-protocol/ # プロトコル定義（#03）
│ ├── agent-core/ llm-core/ llm-runtime/ # コアロジックの抽出
│ └── ...
├── docs/ # ドキュメント源（docs.openclaw.ai に publish）
├── apps/ # macOS / iOS / Android / Windows コンパニオン
└── ui/ # Control UI（Web フロントエンド）
packages/ と src/ の使い分けが最初は分かりにくいですが、おおむね「複数箇所から再利用される純ロジックは packages/ の *-core に切り出し、ランタイムの組み立ては src/ が行う」という分担です。gateway-protocol・agent-core・llm-core あたりがその典型です。
巨大さを支える三本の柱 — このプロジェクトの「憲法」
OpenClaw のコードを読むうえで最重要なのは、AGENTS.md（リポジトリルートの開発規約）に書かれた アーキテクチャ規律 です。これは AI エージェントへの指示書という体裁ですが、実質的にこのプロジェクトの「憲法」です。読み解きの羅針盤になるので、核心を3つに絞って紹介します。
原則1: コアはプラグイン非依存（plugin-agnostic core）
Core stays plugin-agnostic. No bundled ids/defaults/policy in core when manifest/registry/capability contracts work.
src/ のコアには、特定のチャネル名・プロバイダ名・モデル ID を直接書き込みません。「Telegram だったらこうする」「Anthropic ならこう」といった分岐をコアに持たせず、マニフェスト／レジストリ／capability 契約という汎用的な仕組みを通して、プラグインが自分の振る舞いを宣言します。
プラグインがコアに触れられるのは唯一 src/plugin-sdk/* の公開バレル経由だけ、というのも AGENTS.md の明文化されたルールです。
Plugins cross into core only via
openclaw/plugin-sdk/*, manifest metadata, injected runtime helpers, documented barrels.
この「一方向の依存」が、130 以上のプラグインを抱えてもコアが膨張しない理由です。VISION.md も「Core stays lean; optional capability should usually ship as plugins.（コアは薄く保ち、任意機能は原則プラグインで出す）」と明言しています。
原則2: 正準パスは一つ（one canonical path）
Refactor default: one canonical path. Delete the old path unless user explicitly wants compat or the shipped public contract is obvious and cited.
OpenClaw は「後方互換のためのフォールバック分岐」を極端に嫌います。設定スキーマも現行の形だけをランタイムが読み、古い形は openclaw doctor --fix のマイグレーションコードでのみ正準形へ変換する、という割り切りです。
Runtime reads canonical config only. No silent compat for old/malformed config keys.
これにより、「読むべき分岐」が1本に保たれます。互換シム・エイリアス・フォールバックスタックが散らばっていないため、各サブシステムの挙動を追うときに迷いが少ないのです。
原則3: 状態は SQLite に集約
Storage default: SQLite only. Do not add JSON/JSONL/TXT/sidecar files for OpenClaw-owned runtime state...
ランタイムの状態（キャッシュ・キュー・レジストリ・カーソル・チェックポイント等）は原則 SQLite に置きます。共有状態は state/openclaw.sqlite、エージェント単位の状態は agents/<agentId>/agent/openclaw-agent.sqlite、という二層構成です。SQL も生文字列ではなく Kysely 経由（DDL やマイグレーション等の例外を除く）。
SQLite runtime access uses Kysely helpers, not raw SQL statement strings, except schema DDL, migrations, low-level DB bootstrap...
ファイルストレージは「import/export・添付・ログ・バックアップ」など名前のついた成果物のときだけ許される、という線引きです。#10 で詳説します。
誰が何を持つのか — 所有境界という補助線
AGENTS.md はルート1枚では終わりません。extensions/、src/{plugin-sdk,channels,plugins,gateway,agents}/、packages/、docs/、ui/ などのサブツリーには、それぞれスコープ付きの AGENTS.md が置かれています（ルート規約では新規 AGENTS.md に同名 CLAUDE.md シンボリックリンクを添える運用です。ツリー全体に必ず並ぶわけではありません）。
Skills own workflows; root owns hard policy and routing.
つまり「どのコードが何を所有するか」が、ディレクトリ構造とドキュメントの両方で表現されています。本連載で各サブシステムを読むときも、まずそのディレクトリの AGENTS.md を開くのが最短ルートです。
なぜ TypeScript だったのか — 「いじれること」への賭け
VISION.md の理由づけが端的です。
OpenClaw is primarily an orchestration system: prompts, tools, protocols, and integrations.
TypeScript was chosen to keep OpenClaw hackable by default.
OpenClaw の本質は「プロンプト・ツール・プロトコル・連携」を束ねるオーケストレーションであり、誰でも読めて改造しやすい言語として TypeScript（strict ESM）が選ばれています。実際コードは strict 運用で、any を避け unknown と narrow adapter で境界を固める、という方針が AGENTS.md の Code 節に並びます。
拒まれたものたちの肖像 — 「マージしない」が語る思想
最後に VISION.md の "What We Will Not Merge" を見ておきましょう。これは設計思想の裏返しです。
- ClawHub で配れる新規コアスキル
- すでに対応済みチャネルへの薄いラッパーチャネル
- 既存の MCP / ACPX / プラグイン経路を重複させるだけの MCP 実装
- マネージャ・オブ・マネージャ型のエージェント階層フレームワーク（デフォルト構造としては不採用）
- 既存のエージェント／ツール基盤を重複させる重いオーケストレーション層
共通するのは「重複を作らない／コアを太らせない」という一貫した拒否です。これが、巨大なのに読み解ける OpenClaw の正体だと考えてよいでしょう。
次回予告 — openclaw と打ってから、起動まで
#02 は、src/entry.ts から始まる起動フローを追います。isMainModule ガード、コンパイルキャッシュ、プロセス再起動（respawn）プランといった「起動時の地雷」をどう踏まないように設計しているのか。Gateway が立ち上がるまでの一本道を読み解きます。
参考: VISION.md / README.md / ルート AGENTS.md / package.json:3（version 2026.6.2）
