DeerFlow 2.0 スタートガイド：自分だけの AI Agent ワークステーションを構築する

難易度：入門 | 所要時間：15 分 | 到達目標：ゼロから実行可能な AI アシスタントを構築する

AI アシスタントが単に質問に答えるだけでなく、実際にコンピュータを操作したり、コードを書いたり、情報を検索したり、さらには完全なレポートを作成したりできればいいのに、と思ったことはありませんか？今日ご紹介する DeerFlow は、まさにそのような「実務」をこなす AI Agent です。

対象読者

• 1〜3 年目のバックエンド/フルスタックエンジニア
• AI Agent に興味があるが、どこから手をつければいいかわからない方
• AI ツールをセルフホストしたいが、コストが心配な方

コア依存関係と環境

開始する前に、開発環境が以下の要件を満たしていることを確認してください：

• Node.js：22.x 以降
• pnpm：9.x 以降
• Docker：最新安定版
• Git：プロジェクトのクローン用

[!TIP]
Docker でのデプロイを推奨します。ワンクリックで起動でき、Nginx などの手動設定も不要です。

プロジェクト構造

インストールが完了すると、以下のようなプロジェクト構造になります：

deer-flow/
├── backend/                    # バックエンドサービス
│   ├── src/
│   │   ├── client.py           # Python クライアント
│   │   ├── agent/              # Agent コア
│   │   └── skills/            # 内蔵スキル
│   └── docs/                   # 設定ドキュメント
├── frontend/                   # Web インターフェース
├── config.yaml                 # モデル設定ファイル
├── .env                        # 環境変数
└── Makefile                    # 起動コマンド

---

ステップ・バイ・ステップ

ステップ 1：プロジェクトのクローン

ターミナルを開き、以下のコマンドを実行します：

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

[!TIP]
GitHub へのアクセスが困難な場合は、ミラーサイトを利用するか、Release バージョンの圧縮ファイルを直接ダウンロードしてください。

ステップ 2：設定ファイルの生成

DeerFlow は設定生成コマンドを提供しており、テンプレートに基づいてローカル設定ファイルを作成します：

make config

実行後、プロジェクトのルートディレクトリに config.yaml と .env ファイルが作成されます。

ステップ 3：モデルの設定（重要！）

これが最も重要なステップです。DeerFlow は多くのモデルプロバイダーをサポートしていますが、Defapi の使用を強く推奨します。理由はシンプルで、価格が公式の半分だからです。

[!WARNING]
OpenAI 公式 API を直接使用すると、月額費用が数百ドルを簡単に超える可能性があります。Defapi を使用することで、このコストを半分以下に抑えることができます。

config.yaml を開き、以下のように設定します：

models:
  - name: gpt-4o-mini              # 内部識別子
    display_name: GPT-4o Mini      # 表示名
    use: langchain_openai:ChatOpenAI
    model: openai/gpt-4o-mini      # Defapi モデル識別子
    api_key: $DEFAPI_API_KEY       # 環境変数を使用
    base_url: https://api.defapi.org  # Defapi エンドポイント
    max_tokens: 4096
    temperature: 0.7
    supports_vision: true

次に、.env ファイルに Defapi の API Key を記入します：

DEFAPI_API_KEY="dk-xxxxxxxxxxxxxxxx"
TAVILY_API_KEY="your-tavily-api-key"  # Web検索用

[!TIP]
https://defapi.org でアカウントを登録してください。新規ユーザーには無料枠があり、まず体験することができます。

Defapi がサポートする人気モデル：

モデル	識別子	推奨シーン
GPT-4o Mini	openai/gpt-4o-mini	日常的な対話、高コスパ
GPT-4o	openai/gpt-4o	複雑なタスク、バランス重視
Claude Sonnet 4.5	anthropic/claude-sonnet-4.5	プログラミング能力が高い
DeepSeek V3	deepseek/deepseek-v3	推論能力が高く、低価格

ステップ 4：サンドボックスイメージのプル

Docker で実行する前に、サンドボックスイメージをプルする必要があります（この操作は一度だけ必要です）：

make docker-init

イメージのサイズが大きいため、数分かかる場合があります。

ステップ 5：サービスの起動

準備が整いました。DeerFlow を起動します：

make docker-start

以下のような出力が表示されれば、起動成功です：

✔ Frontend started on http://localhost:2026
✔ Backend started on http://localhost:8000

ステップ 6：インターフェースへのアクセス

ブラウザで http://localhost:2026 にアクセスすると、モダンなチャットインターフェースが表示されます。

ステップ 7：最初のタスク

チャットボックスに次のように入力してみてください：

こんにちは、自己紹介をしてください

DeerFlow が答えるだけでなく、どのような能力を持っているかも教えてくれます：

• Web 検索
• ファイルの読み書き
• コマンド実行
• レポート、スライド、Web ページの生成

さらに挑戦的なタスクを試してみましょう：

現在のディレクトリのファイル構造をリストアップしてください

DeerFlow はサンドボックス環境でコマンドを実行し、結果を返します。これが普通のチャットボットとの本質的な違いです。実際に「仕事をしてくれる」のです。

---

トラブルシューティング

Q1：コンテナの起動に失敗し、ポートが使用中と表示される

# 2026 ポートを使用しているプロセスを確認
lsof -i :2026
# または
netstat -ano | findstr 2026

プロセスを特定して終了させるか、config.yaml でポートを変更してください。

Q2：API Key は正しいのにエラーが出る

.env ファイルがプロジェクトのルートディレクトリにあるか、source .env を実行したか、またはコンテナを再起動したかを確認してください。

Q3：モデルがツール呼び出しをサポートしていない

一部のモデルは function calling をサポートしていません。GPT-4o、Claude、Gemini など、ツール呼び出しをサポートしているモデルを使用していることを確認してください。Defapi が提供するモデルは一般的に OpenAI プロトコルと互換性があるため、問題ありません。

Q4：Web 検索の結果が空になる

TAVILY_API_KEY が正しく設定されているか確認してください。Tavily は DeerFlow のデフォルトの検索プロバイダーです。

Q5：Docker のメモリ不足

Docker のデフォルトメモリ設定では不足する場合があります。4GB 以上に設定することを推奨します：

// Docker Desktop -> Settings -> Resources

Q6：ローカル開発モードを使いたい

Docker を使いたくない場合は、ローカルで実行することも可能です：

make check    # 環境チェック
make dev      # 開発サービスの起動

---

ステップアップ

1. カスタム Skills

DeerFlow の Skills システムは非常に柔軟です。独自の Skill を作成できます：

/mnt/skills/custom/
└── my-awesome-skill/
    └── SKILL.md

内蔵 Skill の形式を参考に Markdown ファイルを記述するだけです。

2. MCP サーバーによる拡張

DeerFlow は MCP プロトコルをサポートしており、様々な外部ツールと連携できます。詳細は公式ドキュメント MCP Server Guide を参照してください。

3. 他のモデルへの切り替え

DeepSeek や Claude を試したい場合は、config.yaml を変更するだけです：

# DeepSeek 設定例
models:
  - name: deepseek-v3
    display_name: DeepSeek V3
    use: langchain_openai:ChatOpenAI
    model: deepseek/deepseek-v3
    api_key: $DEFAPI_API_KEY
    base_url: https://api.defapi.org
    supports_thinking: true

4. 組み込み Python クライアントの使用

DeerFlow は Python ライブラリも提供しており、プロジェクトに直接組み込むことができます：

from src.client import DeerFlowClient

client = DeerFlowClient()
response = client.chat("この論文を分析して", thread_id="my-thread")

# ストリーミング出力
for event in client.stream("hello"):
    print(event.data)

---

まとめ

今日は DeerFlow 2.0 の構築からサービスの起動、最初のタスクまでを一緒に行いました。これが単なるチャットボットではなく、本当に仕事をしてくれる AI ワークステーションであることがお分かりいただけたかと思います。

DeerFlow の主なメリット：

• 拡張性：Skills、MCP、Sub-Agents すべてがカスタマイズ可能
• 安全で制御可能：サンドボックスによる隔離、タスクは Docker コンテナ内で実行
• 柔軟なコスト：Defapi を通じてコストを公式の半分に抑えられる

ぜひ試してみてください！コードを書かせたり、情報を検索させたり、レポートを作成させたり。AI の新しい使い道が見つかるはずです。

構築過程で問題が発生した場合は、コメント欄で教えてください。できる限りお答えします。次回は、特定のタスクを完了させるためのカスタム Skills の作り方について詳しく解説します。

ハッピーハッキング！