Table of Contents
- 起源と変更
- これは何？
- ️ アーキテクチャ
- セクションの依存関係
- ⚡ クイックスタート
- ️ 学習パス
- セクションの詳細
- リポジトリ構造
- 前提条件
- 依存関係
- 関連プロジェクト
Gitリポジトリ: truongpx396/learn-harness-engineering-by-building-mini-openclaw
起源と変更
このリポジトリは shareAI-lab/claw0 のフォークです
このフォークで行った変更:
- SDK移行: Anthropic SDK から OpenAI SDK へ移行し、すべてのセクションが OpenAI 互換の任意のエンドポイントと互換になるようにしました。
- ️ ローカルモデル対応: LM Studio、Ollama、および GPT4All を使って完全にオフラインで動かすためのセットアップガイドを追加しました — クラウドAPIは不要です。
- ⚙️
.envベースの設定: どのセクションもコードを触らずに別のプロバイダやローカルサーバを指せるようにするため、OPENAI_BASE_URLとMODEL_IDの環境変数を導入しました。
元のカリキュラム、アーキテクチャ、および教育アプローチに関するすべての功績は shareAI-lab にあります。
ゼロから1へ：AIエージェント・ゲートウェイを構築する
10の段階的セクション — 各セクションは単一の、実行可能なPythonファイルです。
コード + ドキュメントを同じ場所に配置。
これは何？
多くのエージェントのチュートリアルは「APIを1回呼び出す」で止まります。このリポジトリはその while ループから始め、プロダクション品質のゲートウェイへまで導きます。
最小のAIエージェント・ゲートウェイをゼロから、セクションごとに構築します。10セクション、10の中核コンセプト、約7,000行のPython。各セクションでは、ちょうど1つだけ新しいアイデアを導入し、これまでのコードはすべて維持します。10がすべて揃ったら、OpenClaw のプロダクションコードベースを自信を持って読めるようになります。
s01: エージェントループ -- 土台: while + finish_reason
s02: ツール利用 -- モデルにツールを呼ばせる: ディスパッチテーブル
s03: セッション & コンテキスト -- 会話を永続化し、オーバーフローを扱う
s04: チャンネル -- Telegram + Feishu: 実チャンネルのパイプライン
s05: ゲートウェイ & ルーティング -- 5層バインディング、セッションの分離
s06: インテリジェンス -- 魂、メモリ、スキル、プロンプト組み立て
s07: ハートビート & Cron -- 能動的なエージェント + スケジュールタスク
s08: デリバリー -- バックオフ付きの信頼できるメッセージキュー
s09: レジリエンス -- 3層リトライのオニオン + 認証プロファイルのローテーション
s10: 並行性 -- 名前付きレーンで混沌をシリアライズ
️ アーキテクチャ
+--- エージェント層 ---+
| |
| s10: 並行性 （名前付きレーン、生成トラック） |
| s09: レジリエンス （認証ローテーション、オーバーフロー圧縮）|
| s08: デリバリー （書き込み先行キュー、バックオフ） |
| s07: ハートビート （レーンロック、cronスケジューラ） |
| s06: インテリジェンス （8層プロンプト、ハイブリッドメモリ） |
| s05: ゲートウェイ （WebSocket、5層ルーティング） |
| s04: チャンネル （Telegramパイプライン、Feishuフック） |
| s03: セッション （JSONL永続化、3段階リトライ）|
| s02: ツール （ディスパッチテーブル、4つのツール） |
| s01: エージェントループ （while True + finish_reason） |
| |
+-----------------------------------------------------+
セクションの依存関係
s01 --> s02 --> s03 --> s04 --> s05
| |
v v
s06 ----------> s07 --> s08
| |
v v
s09 ----------> s10
- s01-s02: 基礎（依存なし）
- s03: s02 の上に構築（ツールループに永続化を追加）
- s04: s03 の上に構築（チャンネルがセッション向け InboundMessage を生成）
- s05: s04 の上に構築（チャンネルのメッセージをエージェントへルーティング）
- s06: s03 の上に構築（コンテキストにセッションを使い、プロンプト層を追加）
- s07: s06 の上に構築（ハートビートがプロンプト用に魂/メモリを使用）
- s08: s07 の上に構築（ハートビート出力がデリバリーキューに流れる）
- s09: s03+s06 の上に構築（オーバーフロー用の ContextGuard と、モデル設定を再利用）
- s10: s07 の上に構築（単一の Lock を名前付きレーンシステムに置き換え）
⚡ クイックスタート
# 1. クローンして移動
git clone https://github.com/truongpx396/learn-harness-engineering-by-building-mini-openclaw && cd learn-harness-engineering-by-building-mini-openclaw
# 2. 仮想環境を作成して有効化
python3 -m venv .venv
source .venv/bin/activate # macOS / Linux
# .venv\Scripts\activate # Windows
# 3. 依存関係をインストール
pip install -r requirements.txt
# 4. 設定
cp .env.example .env
# .env を編集: OPENAI_API_KEY, MODEL_ID, OPENAI_BASE_URL を設定
# 5. 任意のセクションを実行
python sessions/en/s01_agent_loop.py
️ 学習パス
各セクションは、ちょうど1つの新しいコンセプトを追加します。これまでのコードはすべて維持されます:
第1フェーズ: 基礎 第2フェーズ: 接続性 第3フェーズ: 脳 第4フェーズ: 自律性 第5フェーズ: 本番
+----------------+ +-------------------+ +-----------------+ +-----------------+ +-----------------+
| s01: ループ | | s03: セッション | | s06: インテリジェンス| | s07: ハートビート | | s09: レジリエンス |
| s02: ツール | ---> | s04: チャンネル | --> | soul, memory, | ->| & Cron |-->| & 並行性 |
| | | s05: ゲートウェイ | | skills, プロンプト | | s08: デリバリー | | s10: レーン |
+----------------+ +-------------------+ +-----------------+ +-----------------+ +-----------------+
while + dispatch persist + route personality + recall proactive + reliable retry + serialize
セクションの詳細
返却形式: {"translated": "翻訳されたHTML"}| # | セクション | 中核となる概念 | 行数 |
|---|---|---|---|
| 01 | エージェントループ |
while True + finish_reason -- それがエージェント |
~175 |
| 02 | ツール使用 | ツール = スキーマ辞書 + ハンドラーマップ。モデルが名前を選ぶので、それを引いて使う | ~445 |
| 03 | セッション | JSONL: 書き込みは追記、読み取りは再生。大きすぎる？ 古い部分は要約する | ~890 |
| 04 | チャンネル | プラットフォームはそれぞれ違うが、すべて同じ InboundMessage を生成する
|
~780 |
| 05 | ゲートウェイ | バインディングテーブルが (channel, peer) をエージェントにマップする。最も具体的なものが勝つ | ~625 |
| 06 | インテリジェンス | システムプロンプト = ディスク上のファイル。ファイルを差し替えて性格を変える | ~750 |
| 07 | ハートビート & Cron | タイマースレッド: 「今実行すべき？」 + キューに溜まった作業をユーザーメッセージと並行して処理する | ~660 |
| 08 | 配送 | まずディスクに書き込んでから送る。クラッシュしてもメッセージを失わない | ~870 |
| 09 | レジリエンス | 3層リトライのオニオン: 認証ローテーション、オーバーフロ―圧縮、ツール使用ループ | ~1130 |
| 10 | 並行性 | FIFOキューを持つ名前付きレーン、生成（ジェネレーション）管理、Futureベースの結果 | ~900 |
リポジトリ構造
learn-harness-engineering-by-building-a-mini-openclaw/
README.md 英語のREADME
.env.example 設定テンプレート
requirements.txt Pythonの依存関係
sessions/ すべてのティーチングセッション（コード＋ドキュメント）
en/ 英語
s01_agent_loop.py s01_agent_loop.md
s02_tool_use.py s02_tool_use.md
... （10 .py + 10 .md）
workspace/ 共通のワークスペースサンプル
SOUL.md IDENTITY.md TOOLS.md USER.md
HEARTBEAT.md BOOTSTRAP.md AGENTS.md MEMORY.md
CRON.json
skills/example-skill/SKILL.md
前提条件
- Python 3.11+
- OpenAI互換のAPIキー（例: GitHub Models、Azure OpenAI、または任意のプロバイダー）
ローカルで実行（クラウドAPI不要）
すべてのエージェントはOpenAIのチャット補完（chat-completions）プロトコルを話します。互換性のあるエンドポイントを公開するローカルサーバーならすぐに動作します。GPUは不要で、CPUのみの推論は、以下の3つの選択肢すべてでサポートされています。
オプションA — ️ LM Studio
LM Studio は、モデルのダウンロードと配信（提供）を行うためのGUIを提供します。
1. モデルをインストール＆読み込み
- LM Studio をダウンロードしてインストールします。
- Discover タブで、小さめのinstruction-tunedモデルを検索します。
CPU向けの良い選択肢:
Qwen2.5-7B-Instruct、Mistral-7B-Instruct、Phi-3-mini。 - 選んだモデルの横にある Download をクリックします。
2. ローカルサーバーを起動
- 左サイドバーの Developer タブ（
</>アイコン）を開きます。 - ドロップダウンからモデルを選択し、Start Server をクリックします。
- LM Studio は
http://localhost:1234/v1で待ち受けます。表示されるモデル識別子（例:lmstudio-community/Qwen2.5-7B-Instruct-GGUF）をコピーします。
3. .env を設定
OPENAI_API_KEY=lm-studio # 空でない文字列なら何でもOK
OPENAI_BASE_URL=http://localhost:1234/v1
MODEL_ID=lmstudio-community/Qwen2.5-7B-Instruct-GGUF
オプションB — Ollama
Ollama は、1つのコマンドでモデルの管理と配信（提供）を行う軽量なCLIです。
1. Ollamaをインストール
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh
# Windows: https://ollama.com/download からインストーラーをダウンロード
2. モデルを取得してサーバーを起動
ollama pull qwen2.5:7b # または: mistral, phi3, llama3.2, gemma2:2b …
ollama serve # http://localhost:11434 で起動します
ollama pullをollama serveなしで実行した場合、サーバーはすでにバックグラウンドで起動しています。追加の手順は不要です。
3. .env を設定
OPENAI_API_KEY=ollama # 空でない文字列なら何でもOK
OPENAI_BASE_URL=http://localhost:11434/v1
MODEL_ID=qwen2.5:7b # 取得したモデル名と一致している必要があります
オプションC — GPT4All
GPT4All は、APIサーバーモードを内蔵したデスクトップアプリを提供します。
1. GPT4Allをインストール
- nomic.ai/gpt4all からデスクトップアプリをダウンロードしてインストールします。
2. モデルをダウンロードしてAPIサーバーを有効化
- Models に移動し、モデルを参照してダウンロードします（例:
Mistral 7B Instruct）。 - Settings → API Server を開き、Enable API Server をオンにします。
- サーバーは
http://localhost:4891/v1で起動します。
3. .env を設定
OPENAI_API_KEY=gpt4all # 空でない文字列なら何でもOK
OPENAI_BASE_URL=http://localhost:4891/v1
MODEL_ID=Mistral 7B Instruct # アプリに表示されるモデル名と一致している必要があります
4. 実行（すべてのオプションで同じ）
python sessions/en/s01_agent_loop.py
CPU推論のヒント
- 8 GB未満のRAM: 1.5B〜3Bモデルを使います。例:
Qwen2.5-1.5B-Instruct、Llama-3.2-1B-Instruct。- 8 GB〜16 GBのRAM: 4-bit量子化された7B〜8Bモデルを使います。例:
Llama-3.1-8B-Instruct (Q4)、Mistral-7B-Instruct (Q4)。- 16 GB以上のRAM: 通常の7B〜13Bモデルなら、追加の量子化なしでもうまく動きます。
- サーバーの設定でコンテキスト長を4096以下に保ち、RAMへの負荷を下げます。
- エージェント側ですでに
max_tokensを8096で上限設定しているため、小さなモデルでも圧倒されません。
依存関係
openai>=1.0.0
python-dotenv>=1.0.0
websockets>=12.0
croniter>=2.0.0
python-telegram-bot>=21.0
httpx>=0.27.0
関連プロジェクト
- learn-claude-code -- 12の段階的なセッションを通じて、エージェントフレームワーク（nano Claude Code）をゼロから構築する、伴走型の教材リポジトリです。learn-harness-engineering-by-building-a-mini-openclawがゲートウェイのルーティング、チャネル、先回りした振る舞いに焦点を当てているのに対し、learn-claude-codeはエージェントの内部設計に深く踏み込みます。具体的には、構造化された計画（TodoManager + nag）、コンテキスト圧縮（3層コンパクト）、依存関係グラフを伴うファイルベースのタスク永続化、チーム連携（JSONLメールボックス、シャットダウン/計画承認のFSM）、自律的な自己組織化、並列実行のためのgit worktreeの分離などです。内部で本番品質のユニットエージェントがどのように動くのかを理解したいなら、まずここから始めてください。
この投稿について
Wechatでスキャンして私たちとつながってください、
またはXでフォロー: shareAI-Lab
役に立ったと思ったら、 あるいはコメントで知らせてください！また、この投稿が誰かの役に立つと思うなら、ぜひ共有してください！どうもありがとうございます！
