MagiClaw 入門：飛書（Feishu）で自然に協働が生まれる、AI 科研エージェントチーム

15 分でセットアップ完了｜飛書ネイティブ体験｜科研 Agent の編成｜EvoMaster の基盤をワンクリック拡張

---

プロジェクト概要

MagiClaw は、飛書上で動作する AI エージェントのプラットフォームです。中核となる発想は、「あなたが毎回わざわざ起動する必要のある独立ツール」を作ることではなく、AI エージェントを“日々あなたが使っている飛書”にそのまま埋め込むことにあります。グループチャットや個別チャットで要望を伝えるだけで、エージェントチームが稼働し始めます。

MagiClaw の背後には EvoMaster フレームワークがあり、ツール呼び出し、Skills（技能）、記憶管理、会話の接続（ルーティング）を担う軽量な Agent 基盤インフラです。つまり、「エージェントに何をさせるか」に集中でき、エンジニアリングの土台を何度も組み直す必要がありません。プロジェクトはオープンソース（Apache 2.0 ライセンス）、コード量が少なく、二次開発もしやすい設計です。

---

対象読者像

この記事は以下の開発者を想定しています：

• Python の基礎があり、飛書または Lark の協働ツールに慣れていて、AI 機能をチームの日常コミュニケーションへ直接取り込みたい方
• AI for Science のシーンに関心があり、拡張可能な科研エージェントのフレームワークを探している方
• すでに EvoMaster または類似の Agent フレームワークを使っており、フロントエンドの対話層として飛書を拡張したい方

もし「独立した科研エージェントの総合セット（フルパッケージ）」を探しているなら、MagiClaw はその答えではありません。EvoMaster のエコシステムを飛書へ接続し、科研ワークフローをチームのコミュニケーションツールの中で自然に動かすためのものです。

---

基本の依存関係と環境

---

完全なプロジェクト構成ツリー

MagiClaw/
├── evomaster/                    # コアフレームワークライブラリ
│   ├── agent/                   # Agent 基底クラスとランタイム
│   ├── core/                    # コアツール呼び出し、タスクスケジューリング
│   ├── interface/
│   │   └── feishu/             # 飛書インターフェース実装（常時接続、Webhook）
│   ├── memory/                  # 永続記憶ストレージ
│   ├── skills/                  # 再利用可能なスキルパッケージ
│   └── scheduler/               # 複数タスクのスケジューラ
├── playground/
│   ├── magiclaw/               # デフォルトの飛書対話エージェント
│   ├── agent_builder/           # メタエージェント：新しい Agent を設計 / 生成
│   ├── coding_agent/            # コード作成に特化したエージェント
│   ├── report_writer_agent/     # レポート作成に特化したエージェント
│   └── web_search_agent/        # Web 検索に特化したエージェント
├── configs/
│   ├── feishu/                  # 飛書 Bot 接続の認証情報
│   │   └── config.yaml
│   ├── magiclaw/               # LLM、ツール、MCP、記憶の設定
│   │   └── config.yaml
│   └── agent_builder/           # 計画 + 構築の二つのエージェント設定
├── run.py                       # CLI のクイック起動エントリ
├── requirements.txt
└── pyproject.toml

---

手順を追ったインストール

Step 1：コードをクローン

git clone https://github.com/sjtu-sai-agents/MagiClaw.git
cd MagiClaw

Step 2：依存関係をインストール

pip install -r requirements.txt

または uv（より高速）：

uv pip install -r requirements.txt

Step 3：飛書アプリを作成

1. 飛書オープンプラットフォーム を開き、チームアカウントでログイン
2. 企業向けの自社アプリを作成 をクリックし、名称と説明を入力
3. アプリに入ったら、左メニューで アプリケーション機能を追加 を選び、ロボット をチェック

Step 4：アプリ認証情報の設定

環境変数のテンプレートをコピー：

cp .env.template .env

.env に飛書オープンプラットフォームが提供する認証情報を入力します：

FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 5：権限範囲の取り込み

飛書オープンプラットフォームで 権限管理 → 一括インポート/エクスポートの権限 に入り、以下の JSON を貼り付けます：

{
  "scopes": {
    "tenant": [
      "im:resource",
      "docx:document",
      "docx:document:readonly",
      "drive:drive",
      "im:chat:readonly",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "wiki:wiki:readonly"
    ],
    "user": [
      "drive:drive",
      "drive:drive.metadata:readonly",
      "drive:drive.search:readonly",
      "drive:drive:readonly",
      "drive:drive.version",
      "drive:drive.version:readonly"
    ]
  }
}

Step 6：イベント購読の設定

イベントとコールバック → イベント設定 で、常時接続でイベントを受信する を選択し、以下のイベントを追加します：

コールバック設定 でも同様に常時接続を選び、購読します：

Step 7：LLM の設定

configs/magiclaw/config.yaml を編集し、LLM の認証情報を入力します：

llm:
  provider: openai              # または anthropic / custom
  model: gpt-4o
  api_key: sk-...               # .env から取得するか、設定ファイルに直書き
  base_url: https://api.openai.com/v1  # 任意：エンドポイントを指定

Step 8：アプリを公開して起動

飛書オープンプラットフォームの バージョン管理と公開 でバージョンを作成し公開し、Bot を有効化します。

その後、ロボットを起動：

python -m evomaster.interface.feishu --config configs/feishu/config.yaml

起動が成功したら、飛書で Bot にメッセージを送ってみてください。Bot は返信します。初期状態では、汎用の会話エージェントとして動作し、多輪のコンテキストと記憶機能を備えています。

---

二つのコア Agent 構成

MagiClaw の真の実力は、内蔵 Playground 二つの連携にあります：magiclaw が日常会話を担当し、agent_builder が新しい特化エージェントの作成を手助けします。

magiclaw：飛書会話オーケストレーター

magiclaw はデフォルトで有効化される飛書対話エージェントで、その中核は**編成（オーケストレーション）と委任（デリゲーション）**です。

複雑なリクエストを送った場合、magiclaw は自分一人で全部片付けようとはしません。まず、そのタスクに必要な特化能力を見極め、ツール呼び出しによって、他の登録済み Playground へ作業を委任します：

あなたが飛書で：「RAG アーキテクチャの金融分野における最新の進展を調べて、レポートを書いて」

→ magiclaw がリクエストを受信
→ 必要だと判断：文献調査（web_search_agent）＋ レポート作成（report_writer_agent）
→ それぞれ二つの Agent を呼び出す
→ 結果を集約し、飛書メッセージとして返す

この委任メカニズムにより magiclaw はシンプルに保たれます。「何でもできる必要はなく、いつ誰を呼び出すべきか」を知っていればよいのです。すべての特化 Agent の能力は、Skills とツールインターフェースによって拡張されます。

agent_builder：メタエージェント

agent_builder は MagiClaw の中で最も面白い部分です。自体もエージェントである一方、その役割は新しい Agent を設計し生成することにあります。

あなたが「どんなタイプのタスクをやらせたいか」を伝えると、agent_builder は次を実行します：

1. 要件を分析し、Agent が必要とする中核能力を抽出
2. Agent のスキルファイルを生成（YAML frontmatter + Markdown 記述）
3. playground/ ディレクトリへ書き込み、MagiClaw に登録
4. 新しい Agent は即利用可能になり、magiclaw はそれに委任できるようになります

あなたが飛書で：「コードレビューに特化した Agent が必要です」

→ agent_builder が要件を分析
→ `code_reviewer_agent.py` と対応する設定ファイルを生成
→ システムに登録
→ 返信：「code_reviewer を作成しました。magiclaw はコードレビューのタスクを今からこれに委任できます」

この自動ブートストラップ能力により、チームは自分たちの科研分野に合わせて Agent ライブラリを継続的に拡張でき、最初からすべてのシナリオを一度に定義し切る必要がありません。

---

ツール設定と Skills / 記憶メカニズム

ツール層の設定

configs/magiclaw/config.yaml では、複数種類のツールを設定できます：

tools:
  mcp:
    # MCP プロトコルのツール（ファイルシステム、Git、データベースなど）
    enabled: true
    servers:
      - name: filesystem
        command: npx @modelcontextprotocol/server-filesystem ./workspace

  web_search:
    enabled: true
    provider: duckduckgo         # 任意：bing / google / serpapi

  feishu:
    read_document: true           # 飛書ドキュメントの読み取り
    send_file: true               # ファイル送信

ツールの設定が Agent が「何をできるか」を決め、Skills が「どれだけうまくできるか」を決めます。

Skills 技能システム

Skills は、構造化されたプロンプトをパッケージ化したもので、Agent が特定のタスクでより良いパフォーマンスを発揮できるようになります。EvoMaster の Skills ディレクトリは evomaster/skills/ にあり、各 Skill は Markdown ファイルです：

---
name: research-paper-summary
trigger: literature survey, paper review, paper analysis
agent: research
---

# Research Paper Summary Skill

ユーザーが論文の要約または分析を求めた場合、以下の手順を実行します：

1. 論文タイトル、著者、掲載venue を抽出
2. 中核的貢献（contribution）を抽出
3. 方法論の要点を抽出
4. 限界（limitations）を抽出
5. 構造化要約を出力（300 字以内）

ユーザーが ArXiv のリンクを提示した場合は、まずページ内容を取得してから分析します。

Skills は必要に応じてロードされ、Agent が特定タイプのタスクを処理する際に対応する Skill を自動でマッチします。手動でトリガーする必要はありません。

永続化記憶

MagiClaw の記憶は evomaster/memory/ モジュールで管理され、複数の保存バックエンドに対応しています：

memory:
  backend: sqlite               # 任意：sqlite / redis / file
  session_ttl: 86400            # 会話記憶の保持時間（秒）
  long_term:
    enabled: true
    store: file                 # 永続化してディスクへ保存
    path: ./memory_store/

会話が終了するたびに、Agent は重要なコンテキストを自動的に記憶へ書き込みます。次の会話が始まると、Agent は過去の記憶を読み込み、セッションをまたいだ一貫性を保ちます。

---

完全なワークフローのデモ

シナリオ：チームに「論文スピードリード」Agent を組み込む

目標：飛書に Botへ ArXiv のリンクを投げると、自動で構造化された論文要約を返してくれるようにする。

Step 1：agent_builder で Agent を作成

飛書で MagiClaw にメッセージを送ります：

論文スピードリード用の Agent を作って。名前は paper_reader にして

agent_builder は playground/paper_reader/ ディレクトリを生成し、次を含みます：

playground/paper_reader/
├── __init__.py
├── agent.py                   # Agent のメインロジック
└── config.yaml                 # Agent レベルの設定

Step 2：magiclaw へ登録

新しい Agent を作成したら、configs/magiclaw/config.yaml を編集し、playgrounds の下に登録します：

playgrounds:
  - name: paper_reader
    path: playground/paper_reader
    enabled: true

ロボットを再起動すると、magiclaw は paper_reader を認識し、委任できるようになります。

Step 3：テスト

飛書で：

@Bot paper_reader https://arxiv.org/abs/2401.01234

paper_reader は自動で次を実行します：

1. ArXiv ページを取得
2. タイトル、著者、要約を抽出
3. 構造化要約を生成（貢献 + 方法 + 限界）
4. 飛書メッセージとして返す

---

よくある問題の切り分け

Q1：ロボットを起動しても飛書が反応しない

原因：イベント購読または常時接続の設定が正しくない。

切り分け手順：

# 1. Bot が公開済みであることを確認（飛書オープンプラットフォーム → バージョン管理と公開）
# 公開されていない Bot は、本番環境でメッセージを送受信できません

# 2. 常時接続が正しく設定されていることを確認
# 飛書オープンプラットフォーム → イベントとコールバック → イベント設定 → 「常時接続」を選択

# 3. 起動ログにエラーが出ていないか確認
python -m evomaster.interface.feishu --config configs/feishu/config.yaml

---

Q2：Bot はメッセージを受け取るが「この操作はサポートされていません」と返す

原因：権限範囲が不足している、またはアプリが該当範囲へ公開されていない。

切り分け手順：

飛書オープンプラットフォーム → 権限管理 で、以下の最小権限セットが開通済みであることを確認します：

"im:message",
"im:message:send_as_bot",
"im:chat:readonly"

Bot がグループに参加する必要がある場合は、さらに im:message.group_at_msg:readonly が必要です。

---

Q3：agent_builder で Agent を作成した後、magiclaw が認識できない

原因：新しい Agent が configs/magiclaw/config.yaml に登録されていない。

解決方法：

configs/magiclaw/config.yaml の playgrounds リストに新しい Agent を追加し、enabled: true が設定されていることを確認してください。設定変更後はロボットを再起動する必要があります。

---

Q4：記憶がセッションをまたいで保持されず、毎回 Agent が忘れているように見える

原因：記憶ストレージのバックエンドが正しく設定されていない、または保存先パスに書き込み権限がない。

切り分け手順：

# 1. config.yaml の memory 設定を確認
memory:
  long_term:
    enabled: true
    store: file
    path: ./memory_store/

# 2. memory_store ディレクトリが存在し、書き込み可能であることを確認
mkdir -p memory_store
chmod 755 memory_store

# 3. ロボットを再起動し、メッセージを送って記憶の書き込みをトリガー

---

Q5：Web Search ツールが空結果を返す、またはタイムアウトする

原因：ネットワークが検索サービスへ到達できない、または Search API の認証情報が未設定。

解決方法：

DuckDuckGo（無料で API Key 不要）を使う場合は、Python 環境が外部ネットワークにアクセスできることを確認します：

# ネットワークテスト
python -c "import requests; print(requests.get('https://api.duckduckgo.com/?q=test&format=json').status_code)"

200 が返るのに Bot 側で依然としてタイムアウトする場合は、configs/magiclaw/config.yaml の tools.web_search.provider 設定が正しいか確認してください。

---

Q6：MCP ツールが起動できず、「command not found」と表示される

原因：MCP Server の npx または Node.js のパスがシステム PATH に追加されていない。

解決方法：

# npx が使えることを確認
npx --version

# npx が見つからない場合は、手動でパスを指定
# configs/magiclaw/config.yaml を編集：
tools:
  mcp:
    servers:
      - name: filesystem
        command: /usr/local/bin/npx @modelcontextprotocol/server-filesystem ./workspace

---

追加で読む／発展の方向性

1. SciMaster エコシステムへの接続

MagiClaw は EvoMaster エコシステムの飛書入口であり、完全な SciMaster シリーズ（ML-Master、X-Master、Browse-Master など）は上流の EvoMaster リポジトリにあります。研究の方向性で多モーダルな材料科学分析や複数実験の協調が必要な場合は、EvoMaster と同期してこれらの特化 Agent を取り込み、MagiClaw の編成（オーケストレーション）層に接続できます。

2. カスタム MCP ツール

MagiClaw の MCP ツールインターフェースは、任意の MCP Server への接続に対応しています。内部 API、科研データベース照会ツール、HPC クラスタへの投入スクリプトを Python で MCP Server としてラップし、それを MagiClaw に登録すれば、Agent が飛書上で直接呼び出せるようになります。

3. 複数 Bot 協働アーキテクチャ

チームに複数の異なる役割の Bot（例：カレンダー担当、コード担当、文献担当）がある場合、それらを飛書のグループチャットで連携させられます。1つのグループに複数の Bot を統合し、それぞれが自分の役割を担当し、@ で切り替える運用にできます。

4. チーム専用モデルのデプロイ

EvoMaster は custom Provider に対応しており、社内でデプロイした LLM（Llama、Mistral、Qwen など）を接続できます。科研データを外部に出せない場合は、ローカルまたはプライベートクラウドにモデルをデプロイし、MagiClaw の飛書インターフェースで操作します。データは一切社内ネットワーク外へ出ません。

5. Agent 行動のチューニング

各 Playground の Agent の挙動は、主に config.yaml 内の prompt と skills によって制御されます。特定のシーンで Agent の出来が良くないと感じた場合は、対応する Skill ファイルを修正して、Agent の思考手順や出力形式を調整できます。コードを変更する必要はありません。