Claude CodeでDeerFlow 2.0のPoC環境を自動構築してみた, 6つのハマりポイントと解決策

Windows 11 + WSL2 + Docker Desktop 環境で DeerFlow 2.0 のPoCを自動構築した際に詰まりやすかった6つのポイントと解決策をまとめる。これから試す人が同じところで時間を溶かさないための記録です。

構築環境

WSL2 と Docker Desktop のインストールなど、管理者権限や再起動が必要な部分は人間が担当しました。その後のクローン、設定、起動、確認は Claude Code に手順書を渡して進めています。

初期値が api.moonshot.cn になっていたのに対して、実際に発行していたキーは国際版 platform.moonshot.ai 側のものでした。そのため、認証エラーが出続け、最初はキー側の問題だと勘違いしました。

原因は接続先の違いです。config.yaml の base_url を https://api.moonshot.ai/v1 に変更すると解決しました。

通常の感覚で temperature: 0.7 を入れると、400エラーになりました。理由は、kimi-k2.5 が reasoning モデルだからです。このモデルは temperature: 1 以外を受け付けません。

実際には config.yaml 側で temperature: 1 に固定して解決しました。reasoning系モデルを混ぜる時は、通常モデルと同じ感覚でパラメータを調整しない方が安全です。

KIMIで実行した時、応答途中までは返るのに最後で内部エラーになる場面がありました。原因を追うと、kimi-k2.5 が返す reasoning_content を DeerFlow 側が想定していなかったことが分かりました。

今回は patched_minimax.py に reasoning_content の処理を追加して回避しています。モデルを差し替えやすい一方で、アダプタ層の相性問題が残ることもある、ということです。

DeepSeek 側では、キーの問題だと思って調べていたら、実際は残高不足だったこともありました。地味ですが、かなり時間を取られやすいポイントです。

APIエラー時の切り分け順序は固定しておいた方が楽です。

Docker Desktop を再起動したあと、ブラウザ側で 502 Bad Gateway が出ることがありました。原因は nginx が古いコンテナIPを見続けていたことです。

この時は個別の docker restart より、make docker-stop && make docker-start で全コンテナを立て直した方が安定しました。

一番危なかったのはこれでした。docker exec でコンテナ内に入り、バインドマウントされたファイルを sed -i で編集したところ、コンテナが再起動不能になりました。

教訓は明確です。設定変更は必ずホスト側で行い、変更後にコンテナを再起動する。マウントされたファイルをコンテナ内から直接書き換えるのは避けた方がいいです。

ここを最初から固定しておけば、かなり遠回りを減らせたと感じました。

手順書を渡すだけで、クローンから設定、起動確認までかなりの部分を自動で進められたのは大きかったです。人間がやるとコピペミスや手順漏れが起きやすいところを、かなり安定して処理してくれました。

一方で、Docker内のファイルを直接編集しようとする癖や、sudoパスワードで止まりやすい点はありました。完全放置でうまくいくというより、危険な操作を避けるためのルールを手順書に明記しておく必要があります。

DeerFlow 2.0 のPoC環境は、Claude Code と手順書の組み合わせでかなりのところまで自動構築できます。ただし、モデル固有の制約、Docker再起動時の癖、マウントファイル編集の危険性など、事前に知っておいた方がいい落とし穴もあります。

最初は小さく試して、どこで詰まりやすいかを把握しながら運用ルールを固めるのがよさそうです。