OpenMOSS 入門：マルチエージェント協調で AI を24時間稼働の企業チームに変える

難易度：入門 | 所要時間：30 分 | 獲得スキル：OpenMOSS の4役割協調体系を理解し、独自の AI 企業チームを構築する

---

ターゲット読者

すでに OpenClaw を使用しており、チャット、コード作成、タスク実行といった単体エージェントの能力を体感している方。しかし、タスクが複雑になったり、多段階の協調が必要になったりすると、単体のエージェントでは特定のプロセスで滞り、指示を待つだけの状態（「フリーズ」状態）になってしまうことに気づいているかもしれません。

OpenMOSS はまさにこの問題を解決します。その考え方はシンプルです。1つのエージェントにすべてを任せるのではなく、AI に組織構造を持たせることです。プランナー（設計者）がニーズを分解し、エグゼキューター（実行者）が作業を行い、レビュワー（審査者）が品質を管理し、パトロール（巡回者）が監視を行う。これら4つの役割がそれぞれの職務を全うし、定期的な呼び出しによって自律的に稼働することで、クローズドループの AI 企業チームを形成します。

OpenMOSS 自体はミドルウェアであり、具体的な業務内容は問わず、スケジューリングと協調のみを管理します。どのようなスキル（Skill）を割り当てるかによって、自動的に協調してタスクを完了させることができます。

本記事の対象：

• OpenClaw を使用中で、マルチエージェント協調を体験したい方
• 人手による監視なしで、AI を自動かつ継続的に稼働させたい方
• コンテンツ制作ライン、自動化運用、コードレビューなどのワークフローを構築したい方

---

コア依存関係と環境

GitHub リポジトリ：https://github.com/uluckyXH/OpenMOSS

---

プロジェクト構造の全容

OpenMOSS/
├── app/                          # FastAPI バックエンド
│   ├── main.py                   # エントリポイント：ルーティング登録、ミドルウェア、SPA 静的サービス
│   ├── config.py                 # 設定のロード
│   ├── database.py               # データベース初期化（SQLAlchemy）
│   ├── models/                  # データモデル（10個のテーブル）
│   ├── routers/                 # API ルーティング
│   ├── services/                # ビジネスロジック層
│   └── schemas/                 # Pydantic シリアル化モデル
├── webui/                        # Vue 3 フロントエンドソースコード（ビルドが必要）
├── static/                       # フロントエンドビルド成果物（バックエンドが直接配信）
├── prompts/                      # エージェント役割プロンプトテンプレート
│   ├── templates/                # 役割の基本テンプレート
│   ├── agents/                   # エージェントプロンプト例
│   └── tool/                    # ツール呼び出しプロンプト
├── skills/                        # OpenClaw エージェントスキルの定義
│   ├── task-cli.py              # 各スキル共通の API 呼び出しスクリプト
│   ├── task-planner-skill/      # プランナー（設計者）スキル
│   ├── task-executor-skill/      # エグゼキューター（実行者）スキル
│   ├── task-reviewer-skill/     # レビュワー（審査者）スキル
│   ├── task-patrol-skill/       # パトロール（巡回者）スキル
│   └── dist/                    # パッケージ化されたスキル .zip アーカイブ
├── config.example.yaml            # 設定ファイルのテンプレート
├── requirements.txt              # Python 依存関係
├── Dockerfile
└── docker-compose.yml

---

ステップ・バイ・ステップ手順

Step 1：プロジェクトのクローンと依存関係のインストール

# プロジェクトをクローン
git clone https://github.com/uluckyXH/OpenMOSS.git openmoss
cd openmoss

# Python 依存関係をインストール
pip install -r requirements.txt

リポジトリ内に static/ ディレクトリがない場合（フロントエンドが未ビルドの場合）は、フロントエンドをビルドする必要があります：

cd webui
npm install
npm run build

# ビルド成果物を static/ ディレクトリにコピー
rm -rf ../static/*
cp -r dist/* ../static/
cd ..

---

Step 2：config.yaml の設定

初回起動時、OpenMOSS は config.example.yaml から config.yaml を自動生成します。テンプレートをコピーしてから修正することをお勧めします：

cp config.example.yaml config.yaml

その後、config.yaml を編集します。以下のフィールドは設定必須です：

# 管理者パスワード（初回起動後に自動的に暗号化されます）
admin:
  password: "your-secure-password-here"

# エージェント登録トークン（エージェント登録時に必要。ランダム生成を推奨）
agent:
  registration_token: "your-random-token-here"
  allow_registration: true

# ワークスペース（エージェントの成果物保存先）
workspace:
  root: "/home/your-user/TaskWork"

# サーバーの外部公開アドレス（エージェントが接続する際のアドレス）
server:
  external_url: "http://your-server-ip:6565"

---

Step 3：サービスの起動と初期化ウィザードの完了

python -m uvicorn app.main:app --host 0.0.0.0 --port 6565

初回起動時には以下が自動的に行われます：

1. config.yaml の生成（存在しない場合）
2. SQLite データベースの初期化（data/tasks.db）
3. フロントエンドの自動マウント（static/ ディレクトリが存在する場合）

ブラウザで http://localhost:6565 にアクセスすると、初期化ウィザードが表示されます。以下の設定を行ってください：

• 管理者パスワードの設定
• プロジェクト名の設定
• エージェント登録トークンの生成
• 通知チャネルの設定（任意）

完了後、以下のサービスアドレスが表示されます：

---

Step 4：WebUI へのログインと管理画面の確認

初期化完了後、管理者アカウントで WebUI にログインすると、以下のページが表示されます：

起動直後は、エージェントリストは空です。まだエージェントを登録していないためです。次の Step 5 で作成を開始します。

---

Step 5：4つのエージェントを作成し OpenClaw に登録する

OpenMOSS の4つの役割は、それぞれ異なる責任を負います：

各エージェントは、本質的に OpenClaw を実行するインスタンスです。ここでは planner を例に説明しますが、他の3つの役割もプロセスは全く同じです。

方法1：WebUI からの登録（推奨）

1. WebUI の「エージェント」ページで「エージェント登録」をクリックします。
2. 基本情報を入力します：

役割: planner
名称: OpenMOSS-Planner
登録トークン: （config.yaml の agent.registration_token を入力）

1. 送信後、WebUI に以下が返されます：
   • エージェント API Key（一度しか表示されないため、大切に保存してください）
   • エージェントの SKILL.md と task-cli.py のダウンロード URL
   • 連携ガイド（登録コマンド、設定方法を含む）

方法2：API 経由での登録

curl -X POST http://localhost:6565/api/agents/register \
  -H "X-Registration-Token: your-registration-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenMOSS-Planner",
    "role": "planner"
  }'

レスポンスには API Key、登録コマンド、スキルダウンロード URL が含まれます：

{
  "api_key": "om_xxxxxxxxxxxxxxxxxxxx",
  "skill_cli_url": "http://localhost:6565/skills/task-cli.py",
  "skill_url": "http://localhost:6565/skills/task-planner-skill/SKILL.md",
  "register_command": "openclaw agents add ..."
}

同様の方法で残りの3つのエージェントを登録します：

executor → task-executor-skill
reviewer → task-reviewer-skill
patrol   → task-patrol-skill

---

Step 6：エージェントスキルの設定

エージェントの登録に成功すると、2つの重要なファイルが取得できます：

• task-cli.py — 各役割共通の OpenMOSS API 呼び出しスクリプト
• SKILL.md — その役割専用のスキル定義

これらを OpenClaw が読み取れるディレクトリ（通常はエージェントのプロンプトと同じ場所）に配置します：

# OpenClaw エージェント設定ディレクトリの例
mkdir -p ~/.openclaw/agents/openmoss-planner/skills

# スキルファイルをダウンロード
curl -o ~/.openclaw/agents/openmoss-planner/skills/task-cli.py \
  http://localhost:6565/skills/task-cli.py

curl -o ~/.openclaw/agents/openmoss-planner/skills/SKILL.md \
  http://localhost:6565/skills/task-planner-skill/SKILL.md

その後、OpenClaw のエージェント設定で SKILL.md のパスをプロンプトまたはスキル設定に追加し、エージェントが OpenMOSS のどの API を呼び出せるかを認識させます。

---

Step 7：cron 定時実行の設定（エージェントを自動「出勤」させる）

これが OpenMOSS と一般的な単体エージェントとの最大の違いです。エージェントは指示を待って行動するのではなく、従業員のように定時に出勤して業務を開始します。

OpenClaw のエージェント設定で、各エージェントに cron タスクを設定します：

planner（プランナー）— 30分ごとに新規タスクを確認：

{
  "cron": "*/30 * * * *",
  "task": "OpenMOSS のタスクキューを確認し、未計画の新規タスクがあれば計画プロセスを実行する"
}

executor（エグゼキューター）— 15分ごとに受取待ちタスクを確認：

{
  "cron": "*/15 * * * *",
  "task": "OpenMOSS のサブタスクキューを確認し、引き受けて実行する"
}

reviewer（レビュワー）— 20分ごとに審査待ち成果物を確認：

{
  "cron": "*/20 * * * *",
  "task": "OpenMOSS の審査キューを確認し、審査待ちの成果物を処理する"
}

patrol（パトロール）— 10分ごとにシステム状態を巡回：

{
  "cron": "*/10 * * * *",
  "task": "OpenMOSS のシステム状態を確認し、ブロックされているタスクをマークし、異常を発見した場合は即座に警告する"
}

エージェントが呼び出された後のワークフローは固定されています：

1. OpenMOSS API を呼び出して現在のステータスを取得
2. 自身の役割に基づき、対応する操作を実行
3. 結果を OpenMOSS に書き戻す
4. 次の呼び出しまでスリープ状態に入る

このプロセス全体において、人の介入は一切不要です。

---

Step 8：最初のタスクの発行と4役割の協調確認

WebUI の「タスク管理」ページで「タスク作成」をクリックし、以下を入力します：

タスク名：AIニュース自動翻訳・投稿
目標：中国語圏のインターネットから AI/テクノロジー/デジタルのニュースを収集し、日本語に翻訳して投稿する

プランナー（planner）が cron で起動されると、以下の動作を行います：

1. タスクを受け取り、複数のモジュール（収集 → 翻訳 → 審査 → 投稿）に分解する
2. 各モジュールに対してサブタスク（sub-task）を作成する
3. 各サブタスクの受け入れ基準（検収基準）を定義する

エグゼキューター（executor）が起動されると：

1. キューから最初の待機中サブタスクを引き受ける
2. 作業（ニュースの検索、翻訳）を実行する
3. 成果物を審査キューに提出する

レビュワー（reviewer）が起動されると：

1. 審査待ちの成果物を取得する
2. 受け入れ基準に基づきスコアリングする
3. 合格ならサブタスク完了としてマークし、不合格ならエグゼキューターに差し戻して手直しを命じる

パトロール（patrol）はシステムを継続的に監視します：

• サブタスクが進捗なく閾値時間を超えた場合、自動的に blocked とマークする
• 審査却下率が異常に上昇した場合、アラートを送信する
• エグゼキューターが無限ループに陥っているのを発見した場合、管理者に介入を通知する

WebUI の「アクティビティストリーム」ページで、全エージェントのリアルタイムな活動状況をいつでも確認できます。

---

Step 9：通知チャネルの設定

OpenMOSS は重要なイベントが発生した際に自動通知を行う機能を備えています。config.yaml で通知チャネルを設定してください：

notification:
  enabled: true
  channels:
    - "Lark(飛書)グループID"
    - "user:ou_xxx" 
  events:
    - task_completed   # サブタスク完了
    - review_rejected   # 審査却下（手直し）
    - all_done          # 全サブタスク完了
    - patrol_alert      # パトロールによる異常発見

エージェントは GET /config/notification インターフェースから通知設定を読み取り、自身の能力（メール、Lark 等）を使って通知を送信します。

---

よくあるトラブルシューティング

1. エージェントの登録失敗（registration_token の不一致）

現象：エージェント登録時に 403 エラーや "invalid token" エラーが返される。

最も多い原因は registration_token の不一致です。以下の2点を確認してください：

1. OpenMOSS config.yaml 内の agent.registration_token の値
2. エージェント登録リクエストのヘッダーにある X-Registration-Token の値

これらは空白や大文字小文字を含め、完全に一致している必要があります。config.yaml を修正した場合は、OpenMOSS サービスの再起動を忘れないでください。

---

2. cron タスクでエージェントが起動しない

現象：エージェントが自動的に業務を開始せず、コンソールにエラーログも出ない。

確認手順：

1. OpenClaw 側の cron 設定が正しいか確認 — cron 式が妥当か、タスクの記述が明確かを確認します。
2. OpenClaw インスタンスが動作しているか確認 — エージェントに対応する OpenClaw プロセスが生存しているか確認します。
3. エージェントの API Key が有効か確認 — WebUI のエージェントページでステータスが active になっているか確認します。

WebUI の「エージェント」ページで特定のエージェントの最終アクティブ時間を確認し、定時呼び出しが行われているか判断できます。

---

3. サブタスクが何度も却下され、無限ループに陥る

現象：executor が提出した成果物が reviewer に何度も却下され、同じサブタスクが繰り返される。

これは通常、executor が受け入れ基準を誤解しているか、受け入れ基準自体の定義が曖昧な場合に起こります。

解決策：

1. WebUI で却下記録を確認し、reviewer が提示した理由を確認します。
2. プランナーがサブタスク作成時に設定した受け入れ基準を、より具体的かつ定量的なものに調整します。
3. executor の能力不足が疑われる場合は、より強力なモデルに変更します（OpenClaw エージェントの API キーを更新）。

---

4. パトロール（patrol）が反応しない

現象：システムにブロックされたタスクがあるのに、patrol がマークせず、アラートも送信されない。

確認事項：

1. patrol エージェントに対応する OpenClaw インスタンスが実行中か。
2. patrol の cron 間隔が長すぎないか（*/10 の方が */60 よりも感度が高くなります）。
3. config.yaml の notification が有効で、チャネル設定が正しいか。
4. patrol エージェントが通知送信スキル（Lark/メール等）を保持しているか。

---

5. API Key の期限切れまたは権限不足

現象：エージェントが一定期間動作した後に突然停止し、ログに 401 または 403 エラーが出る。

エージェントの API Key（om_ で始まるもの）は OpenMOSS 内部の認証用であり、LLM の API Key とは異なります。ログに LLM の認証エラーがある場合は、エージェント側の LLM API Key に問題があります（残高不足、権限失効など）。

解決策：OpenClaw のエージェント設定にある LLM API Key を更新し、そのエージェントインスタンスを再起動してください。

---

6. 複数のエージェントが同時に同じタスクを引き受けてしまう

現象：2つの executor が同じサブタスクを開始し、重複作業が発生する。

OpenMOSS のタスクキューはアトミック性が保護されており、理論上は同時に引き受けることはできません。もし発生した場合は以下の可能性があります：

1. 2つの executor の cron 間隔が非常に短く、極めて近いタイミングで同時に起動した。
2. ステータスの更新に遅延があり、executor が古いデータを読み取った。

解決策：executor の cron 間隔を適切に広げ（例：*/5 から */15 へ）、各処理のステータス更新が完了するまでの時間的猶予を確保します。

---

関連資料 / ステップアップ

1. エージェント役割プロンプトのカスタマイズ

prompts/ ディレクトリに各役割のプロンプトテンプレートがあります。これを修正することで、業務ニーズに合わせたエージェントの性格を構築できます：

# プランナーのプロンプトを編集
vim prompts/agents/planner-agent-prompt.md

# エグゼキューターのプロンプトを編集
vim prompts/agents/executor-agent-prompt.md

プロンプトの修正後、エージェントが次に起動した際に自動的に反映されます。

2. WordPress スキルの連携による自動投稿の実現

skills/wordpress-skill/ には WordPress への投稿機能が含まれています。executor と組み合わせることで、翻訳済みの記事を手動操作なしで自動的に WordPress サイトへ公開できます。

3. ポイントとパフォーマンスシステムのチューニング

OpenMOSS にはエージェントポイント機能が組み込まれており、レビュワーの評価がエグゼキューターのランキングに直接影響します。WebUI の「ポイントランキング」で各エージェントの品質を確認できます。

4. Grok Search スキルによるウェブ検索の実現

skills/grok-search-runtime/ は Grok のウェブ検索機能を提供します。これを持たせた executor は、リアルタイムでインターネット上のニュースを収集し、翻訳・整理・公開することができます。これは 1M Reviews という実例のコアワークフローです。

5. PostgreSQL / MySQL への移行

デフォルトでは SQLite を使用していますが、中規模以上のチームには PostgreSQL や MySQL への切り替えを推奨します：

# config.yaml
database:
  type: postgresql  # または mysql
  connection_string: "postgresql://user:pass@localhost:5432/openmoss"

6. Docker による一括デプロイ

プロジェクトには Dockerfile と docker-compose.yml が用意されており、ワンコマンドで環境を構築できます：

# 全サービスを起動
docker-compose up -d

7. 独自のコンテンツ制作ラインの構築

1M Reviews の実際のケースを参考に、完成されたパイプラインは以下の通りです：

1. planner がタスクを分解：収集 → 翻訳 → 審査 → 投稿
2. executor (収集) が Grok Search スキルでニュースを収集
3. executor (翻訳) が翻訳 API で内容をリライト
4. reviewer がコンテンツの品質とフォーマットを審査
5. executor (投稿) が WordPress スキルでサイトへ公開
6. patrol がシステムの状態を監視し、異常があれば即座にアラート

この全プロセスが自律的に稼働するため、あなたは最初に目標を設定し、最後に結果を確認するだけで済みます。