build-your-own-openclaw を読む: 18ステップでAIエージェントの構造を追うチュートリアル

このチュートリアルが埋めようとしている穴

エージェントフレームワークの多くは、動くものを渡してくれる代わりに内部を見せない。ツール呼び出しも記憶もルーティングも、ライブラリの奥に隠れる。build-your-own-openclaw はその逆を行く。README によれば、これは「a step-by-step tutorial to build your own AI agent」であり、対象は OpenClaw の「a lightweight version」を自分で組み上げたい読者だ。完成品を配るのではなく、18 の段階を踏ませて構造を腹に落とさせる。各ステップには設計判断を説明する README.md と、実行可能なコードベースが対で用意される。想定読者は、LLM を API 越しに叩いた経験はあるが、エージェントのループやイベント処理を自分で設計したことはない層だろう。フレームワークの利用者から、フレームワークの中身を読む側へ移りたい人に向いている。

4つのフェーズと18ステップの刻み方

ステップは4つのフェーズに分かれる。Phase 1（00〜06）は単一エージェントを作る。00-chat-loop から始まり、01-tools でツールを1つ与え、02-skills で SKILL.md による拡張、03-persistence で会話の保存、04-slash-commands でセッションの直接操作、05-compaction で履歴の圧縮、06-web-tools で外部情報へのアクセスを扱う。Phase 2（07〜10）はイベント駆動への作り替えで、07-event-driven で CLI の外にエージェントを出し、08-config-hot-reload で再起動なしの設定編集、09-channels で携帯電話からの対話、10-websocket でプログラムからの操作を加える。Phase 3（11〜15）は自律化とマルチエージェントで、11-multi-agent-routing、12-cron-heartbeat、13-multi-layer-prompts、14-post-message-back、15-agent-dispatch が並ぶ。Phase 4（16〜17）は 16-concurrency-control と 17-memory で、並行実行の制御と長期記憶を扱う。番号がそのまま依存関係の順序になっており、途中を飛ばすと後のステップが前提とする部品が欠ける構成だ。

ステップが積み上がる仕組みと、参照実装の位置づけ

各ステップは独立したディレクトリとして置かれ、それぞれが実行可能なコードベースを持つ。つまり前のステップの成果物を書き換えて次のステップにするのではなく、段階ごとに完結したコードが並ぶ。学習者は差分を追いやすい反面、全体を通したときにどこで何が変わったのかは自分で突き合わせる必要がある。README は参照実装として pickle-bot を挙げ、これを「our reference implementation」と説明する。個々のステップが最小構成なのに対し、pickle-bot は統合された姿を見るための材料という位置づけになる。設計の流れとしては、単一プロセスのチャットループから始めて、設定のホットリロードやチャネル追加を経てイベント駆動へ移り、そこにスケジューラとルーティングを載せ、最後に並行制御とメモリで締める。順序そのものが、小さいエージェントが運用上の要求に押されて構造を変えていく過程をなぞっている。

動かすまでの手順と設定ファイル

README が示すセットアップは短い。まず default_workspace/config.example.yaml を default_workspace/config.user.yaml にコピーする。

cp default_workspace/config.example.yaml default_workspace/config.user.yaml

次に config.user.yaml を編集して API キーを入れる。対応プロバイダの一覧は LiteLLM の providers ドキュメントへのリンクで示され、具体例はリポジトリ内の PROVIDER_EXAMPLES.md にまとまっている。LiteLLM を経由する設計なので、プロバイダ固有の SDK を各ステップが直接呼ぶのではなく、共通のインターフェース越しにモデルを差し替える形になる。README の指示は「Just follow each steps, read and try it out」の一言で、セットアップはこの2手で終わる。ただし config.example.yaml にどのキー名が並んでいるか、どのプロバイダが既定で有効になっているかは手元のファイルを見ないと分からない。ステップごとに追加の設定キーが必要になる可能性も、README の記述からは判断できない。

イベント駆動への作り替えが山場になる理由

Phase 1 と Phase 2 の間には質的な断層がある。Phase 1 のエージェントは、入力を受けて応答を返す一本のループだ。07-event-driven でこれをイベント駆動に組み替えると、入力の発生源が CLI に限らなくなる。09-channels で携帯電話から話しかけられるようになり、10-websocket で外部プログラムから操作できるようになるのは、この組み替えがあってこそだ。08-config-hot-reload も同じ文脈に置かれている。再起動なしに設定を書き換えられるということは、動作中のプロセスが設定の変更を検知して状態を更新する仕組みを持つということで、単純なループでは実現しにくい。ここでつまずくと以降のステップが全部理解できなくなる。逆に言えば、このチュートリアルの中心は Phase 2 にあり、Phase 1 はその前提を揃える助走だと読める。

この教材が向かない場面

第一に、動くエージェントが今すぐ必要な人には向かない。18 ステップを順に追う構成なので、目的の機能に到達するまでに相応の時間がかかる。第二に、API キーの用意と config.user.yaml の編集を避けたい場合、どのステップも動かない。README はこの設定を最初の必須手順として明示しており、キーなしで試せるモックの経路は示されていない。第三に、本番運用のノウハウを求める読者には物足りない。Phase 4 は 16-concurrency-control と 17-memory の2ステップしかなく、監視、障害時の再試行、コスト管理といった運用面の話題は README の目次には現れない。第四に、各ステップの README.md は設計判断の説明に重点が置かれ、API リファレンスのような網羅的な仕様は期待できない。ライブラリとして使うのではなく、読んで写して理解するための教材だと割り切る必要がある。

フレームワーク利用との違い、そして保守とライセンス

比較対象として素直なのは、既存のエージェントフレームワークをそのまま使う道だ。違いは抽象化の位置にある。フレームワークはツール呼び出しや記憶の管理を内部に隠し、利用者は設定とプロンプトだけを書く。build-your-own-openclaw はその抽象化を自分で作らせる。たとえば 05-compaction では履歴を圧縮する仕組みを自分で実装し、17-memory では長期記憶を自分で設計する。フレームワークなら1行の設定で済む部分に、設計判断と実装が伴う。得られるのは、ツール呼び出しのループがどこで壊れやすいか、履歴の圧縮で何が失われるかを体で知っている状態だ。保守の観点では、各ステップが独立したコードベースなので、1つのステップの変更が他に波及しにくい。反面、依存パッケージの更新を18箇所で追う必要があるかどうかは、リポジトリの構成を見ないと判断できない。ライセンスは MIT と明記されており、コードを自分のプロジェクトに取り込む際の条件は比較的緩い。ただし依存する LiteLLM や各プロバイダの SDK は別のライセンスに従うため、そこは個別に確認する必要がある。

編集部の結論

採用を検討すべきなのは、エージェントの内部構造を手を動かして理解したい個人開発者と、社内でエージェント基盤を設計する前に構成要素を洗い出したいエンジニアだ。逆に、すぐ動くエージェントを業務に投入したいだけのチームには向かない。着手前に確認すべきは、default_workspace/config.example.yaml にどのプロバイダのキー項目が並んでいるか、そして各ステップのコードが依存するパッケージが requirements 相当のファイルに固定されているかどうかである。この2点が自分の環境と噛み合わなければ、ステップ0のチャットループすら動かずに詰まる。

公式情報源

1. czl9707/build-your-own-openclaw on GitHub
2. Issues
3. License: MIT
4. Project website
5. README