difyctlとDify Workflow DSL SkillでCodexからDifyを操作する方法

この記事で紹介するのは、公式CLIであるdifyctlと、Codexで使う二つのSkillを組み合わせ、CodexからDifyを操作する構成です。DifyのWorkflowやChatflowをDSLとして扱い、ローカルDifyへ反映し、実行結果を確認するまでの作業を、Codexから進められるようになります。

最初に知っておきたい「difyctl」と二つのSkill

• difyctl（公式CLI）：実際にローカルDifyへ接続し、アプリ一覧取得、DSLのエクスポート／インポート、アプリ実行を行うコマンドラインツール。
• difyctl Skill（公式）：Codexがdifyctlの現在のコマンド仕様と、安全な操作手順を参照するためのSkill。Skill自体がDifyを操作するのではなく、CLIを正しく使うための説明書として働く。
• Dify Workflow DSL Skill（コミュニティ）：要件からDify DSLを生成・編集し、ノード、接続、変数参照の整合性をstrict検証する独立したSkill。

つまり、DSLを作る役はWorkflow DSL Skill、Difyへ反映・実行する役はdifyctl CLI、CodexがCLIを誤用しないための案内役はdifyctl Skillです。この3つを組み合わせると、Codexが「Difyで作るAIアプリ」の設計と反映を手伝えるようになります。単にYAMLを出力するだけではありません。Difyのキャンバスを、処理の内容を人が読める設計図として使える点が大きな特徴です。

AIアプリケーションを作るスピードは、ここ1年で大きく変わりました。Codexのようなコーディングエージェントに「こういう業務アプリを作りたい」と伝えると、コード、設定ファイル、テストまで一気にたたき台を作れます。

これは非常に便利です。ただ、作業をどんどん進めるほど、別の問題も出てきます。アプリの中で、どこが何をしているのか分からなくなることです。

たとえば「回答の質が少し悪い」と感じたとき、原因は一つではありません。検索前の入力整理なのか、ナレッジ検索なのか、検索後の整形なのか、LLMへ渡す指示なのか、あるいは最後の出力整形なのか。コードや設定ファイルだけで構成されたアプリでは、この切り分けに時間がかかります。

そこで役に立つのがDifyです。Codexで構築作業を加速しながら、Difyのキャンバス上で処理をノードとして見える形にしておく。すると、AIアプリケーションを「作れる」だけでなく、人が読める・説明できる・直せる状態に近づけられます。

バイブコーディングで起こりやすい「見えなくなる」問題

バイブコーディングは、自然言語で方向を伝え、AIに実装を進めてもらうやり方です。試作を早く始められる反面、処理の変更が何度も積み重なると、次のような状態になりがちです。

• 最初は単純だった処理に、例外処理や条件分岐が後から増えている。
• データの整形、検索、要約、回答生成が一つの大きな関数やプロンプトに詰め込まれている。
• 「なぜこの指示文になっているのか」「どの入力を使っているのか」が、作った本人以外には追いにくい。
• 修正依頼が来ても、影響範囲が分からず、別の部分を壊す心配がある。
• テストで失敗したときに、どの段階の出力を確認すればよいかが分からない。

これはAIに限った話ではありません。業務の流れが複雑になるほど、処理を小さな単位に分け、そのつながりを共有できることが大切になります。特に社内で使うAIアプリでは、開発担当者だけでなく、業務を知る人、確認する人、次に引き継ぐ人が関わります。

綱業商会がAI/DX支援で重視しているのも、現場の人が使い続けられることです。AIが裏側で何かをしている状態ではなく、「このノードは入力内容を整理している」「ここで検索している」「ここで回答の形式を整えている」と説明できる状態を目指します。

Difyを間に置くと、何が見えるようになるのか

Difyは、LLMを使う処理をノードとして配置できるプラットフォームです。WorkflowやChatflowでは、入力、条件分岐、LLM、ナレッジ検索、コード、HTTPリクエスト、回答といった処理を、左から右へ接続して組み立てます。

重要なのは、Difyを「ノーコードで作るためだけの画面」と考えないことです。CodexでDSL YAMLを作ったり、既存の構成を編集したりする場合でも、DifyのキャンバスはAIアプリの処理設計図になります。

たとえば「回答が曖昧だ」という問題があった場合、すぐにプロンプトを長くするのではなく、まずノードごとの出力を見ます。検索ノードが十分な情報を返していないのか、LLMノードに渡す変数が違うのか、最終出力で必要な部分を落としているのか。Dify上で処理の境界が見えていると、直す場所を決めやすくなります。

CodexとDifyをどう役割分担させるか

今回の構成では、CodexとDifyを競合するものではなく、役割の違う道具として使います。

1. Codex + Dify Workflow DSL Skillが、要件整理、DSL生成、ファイル編集、strict検証を進める。
2. Codex + difyctl Skillが、実行するdifyctl CLIのコマンド仕様と副作用を確認する。
3. difyctl CLIが、認証済みのDifyへDSLをエクスポート／インポートし、検証用アプリを実行する。
4. Difyが、AIアプリの処理単位、接続、分岐、実行結果を人に見える形で持つ。

業務要件
  ↓
Codex + Dify Workflow DSL Skill：要件をDSLに落とし込み、strict検証する
  ↓
difyctl CLI：認証済みのローカルDifyへドラフトとして反映する
  ↑
difyctl Skill：現在のコマンド仕様と副作用をCodexに案内する
  ↓
Dify：ノードと接続として処理を可視化する
  ↓
Difyプレビュー：ノードごとの実行を確認する
  ↓
テスト設問と実行結果を確認する
  ↓
次の修正を、見える設計図から始める

この構成では、CodexはDifyを操作するためのエージェントとして働きます。ただしDify APIを呼ぶ実行主体はdifyctlです。Difyの中で動く実験的な「Dify Agent」とは別の話です。本記事で扱うのは、CodexがSkillを参照しながらdifyctlを使い、Difyのアプリ構成を読み取り、DSLを編集し、検証用のドラフトへ反映する運用です。

実装の基本：DSLを成果物として扱う

DifyのWorkflowやChatflowはDSL YAMLとして保存できます。DSLを使うと、画面で作った構成をファイルとして管理し、必要に応じて別の検証環境へ反映できます。

ここでは、冒頭で紹介したdifyctl CLIと二つのSkillを使います。

• Dify Workflow DSL Skill：要件からDSLを生成・編集し、ノード、接続、変数参照の整合性を検証する。
• difyctl Skill：Codexにdifyctl help -o jsonを参照させ、そのバージョンで有効なコマンドと副作用を確認させる。
• difyctl CLI：ローカルDifyのアプリを確認し、DSLをエクスポート／インポートし、アプリを実行する。

たとえば、次のような依頼をCodexへ渡します。

社内規程を検索するChatflowを作成してください。

処理は次の順にしてください。
1. 質問を受け付ける
2. 現行版の規程だけを検索する
3. 検索結果だけを根拠に回答を作る
4. 規程名、版、適用日を表示する

ノード名は日本語にし、各ノードに入力・処理・出力の説明を付けてください。
strict検証を実行してください。

ここで大切なのは、単に動くYAMLを作ることではありません。Dify上で見たときに、誰が見ても役割を理解できるノード名にすることです。

① 質問を受け付ける
  ↓
② 現行版の規程を検索する
  ↓
③ 根拠だけで回答を作成する
  ↓
④ 規程名・版・適用日を表示する

モデル名や内部IDをノード名にせず、利用者が処理の意味を読める名前にします。LLMノードの説明には「入力」「参照する情報」「してはいけないこと」「出力形式」を書いておくと、後から調整しやすくなります。

ローカルDify、difyctl CLI、二つのSkillの導入・確認

ここからは、MacでローカルDifyを使う場合の導入順です。大事なのは、CLI本体を入れる → Difyへ認証する → CLIの使い方をCodexへ渡す → DSLを作るSkillを入れる → 既存アプリを触らない検証を行うという順番です。いきなりDSLをインポートしたり、既存アプリを上書きしたりしません。

0. 導入前に確認するもの

• Difyの実際のバージョン。Dify 1.16系ではDSL 0.7.0、1.15系ではDSL 0.6.0を前提にします。
• ローカルの接続先。標準的なDocker Compose構成ならhttp://localhostです。別ポートの場合は、そのURLを使います。
• 検証用に作る新規アプリ名。既存の公開アプリや既存ナレッジを最初の検証対象にしません。
• GitとPython 3。Gitは必須ではありませんが、Workflow DSL Skillの取得とローカル検証にはPython 3を使います。

Difyを更新する場合は、先にDocker Composeの.env、データベース、ボリュームをバックアップし、リリースノートと環境変数の差分を確認します。RC版やalpha版のCLIは特に、検証環境から始めます。

1. Difyのバージョンに合わせてdifyctl CLIを入れる

difyctlはSkillではなく、Macに入れる実行プログラムです。アプリ一覧の取得、DSLのエクスポート／インポート、実行はこのCLIが実際に行います。公式インストーラーはDIFY_VERSIONで対象Difyのリリースを指定できます。以下はDify 1.16.0の場合です。別バージョンを使う場合は、数字を実環境に合わせて変更します。

curl -fsSL https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-cli.sh \
  | DIFY_VERSION=1.16.0 sh

# 「command not found」だった場合だけPATHを追加する
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# CLI本体のバージョンとDify互換範囲を確認する
difyctl version

difyctl versionには、CLIのバージョン、対応Difyの範囲、接続済みならサーバー情報が表示されます。Dify本体、CLI、DSLの対象バージョンは別々に確認します。互換範囲が合わない状態では、インポートへ進みません。

2. ローカルDifyへデバイス認証でログインする

Docker Composeで起動したDifyがhttp://localhostにある場合の例です。実行するとブラウザでデバイス認証を完了するよう案内されるため、Difyの利用者本人がログインを完了します。ブラウザを自動で開けない端末では--no-browserを付け、表示されたURLを開きます。

difyctl auth login --host http://localhost --insecure

# 認証済みの利用者を確認する
difyctl auth whoami

# 接続・権限を確認する。JSONで見たい場合は -o json を付ける
difyctl get app -o json

--insecureはローカルHTTP環境のための指定です。インターネットに公開したHTTPS環境で、証明書検証を回避するために使うものではありません。whoamiとアプリ一覧が成功するまで、インポートや実行には進みません。パスワード、APIキー、認証トークンをDSL、エクスポートYAML、記事、共有フォルダに書かないこともここで徹底します。

3. difyctl SkillをCodexへ配置する

次はCLI本体ではなく、CodexがCLIを安全に使うための公式difyctl Skillを入れます。最初のコマンドはプレビューです。何をどこへ配置するかを確認してから、--yes付きで確定します。

# プレビュー：この時点では書き込まない
difyctl skills install --agent codex

# 確定：Codex向けSKILL.mdを配置する
difyctl skills install --yes --agent codex

# 自動検出されない場合は配置先を明示する
difyctl skills install ~/.agents/skills/difyctl --yes

これはdifyctlをインストールするコマンドではありません。すでに入っているCLIが、Codex向けのSKILL.mdを配置する操作です。Skillは実行担当ではなく、Codexにdifyctl help -o jsonを参照させ、そのバージョンで使えるコマンド、引数、読み取り／書き込みの副作用を確認させます。配置後は新しいCodexセッションを開きます。

4. Dify Workflow DSL Skillと検証用Python環境を入れる

Workflow DSL Skillは、difyctlとは別のコミュニティSkillです。要件をDSL YAMLへ落とし込み、ノード、接続、分岐、変数参照、依存プラグインを検査します。Dify 1.16系ではDSL 0.7.0、1.15系では0.6.0を選びます。Python依存関係はMac全体ではなく、このSkill用の仮想環境へ隔離します。

git clone https://github.com/yzmw123/dify-workflow-dsl-skill.git
cd dify-workflow-dsl-skill
bash install.sh --platform codex

# strict検証用の仮想環境を作る
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt

Skillを入れたらCodexを新しいセッションで起動します。確認時は「$dify-workflow-dslを使って、DSL 0.7.0の構造をstrict検証して」と依頼できます。ただしstrict検証は静的な整合性検査です。モデル認証、ワークスペース固有のプラグイン、ナレッジ、外部APIが実行できるかまでは保証しません。

5. 既存アプリを正としてエクスポートし、DSLを作る

新規作成でも、まず同じDify環境から小さな正常アプリをエクスポートして、モデル指定、プラグイン依存関係、DSLの形を確認するのが安全です。--include-secretは使いません。エクスポートには環境ごとの差が含まれることがあるため、IDや認証情報をそのまま他環境へ持ち込まないようにします。

mkdir -p ~/Documents/codex_work/dify-workflows/regulation-search/exports
cd ~/Documents/codex_work/dify-workflows/regulation-search

# app-idは get app で確認した検証対象のIDに置き換える
difyctl export studio-app <app-id> --output ./exports/baseline.yml

# Codexに要件から新しいDSLを作らせる。秘密情報はプレースホルダーのままにする
# 作成後はSkillの検証器で対象バージョンを明示して検査する
python3 /path/to/dify-workflow-dsl-skill/scripts/validate_dsl.py \
  --strict --target-version 0.7.0 ./chatflow.yml

/path/to/…は、Skillをcloneした実際のパスに置き換えます。既存のDSLを編集する場合も、先にエクスポートしてから作業します。モデルの接続情報やデータセットIDなど、ワークスペース固有の値は、エクスポートを正として確認し、Dify画面側で再接続・確認します。

6. 検証用アプリへだけインポートし、実際に動かす

static検証に通っただけで既存アプリを上書きしません。まずは検証用の新規アプリとしてインポートします。インポート後に作られたアプリIDをget appで確認し、Startノードで定義した入力名に合わせて実行テストをします。下例のquestionは例であり、実際の入力名へ置き換えます。

# 新規の検証用アプリとして作成する
difyctl import studio-app \
  --from-file ./chatflow.yml \
  --name "規程検索・検証用"

# 作成された検証用アプリのIDを確認する
difyctl get app -o json

# 入力名はStartノードの定義に合わせる
difyctl run app <test-app-id> \
  --inputs '{"question":"最新版の品質検査規程を教えて"}' \
  -o json

インポートは通常、公開済みの挙動を変えずドラフトへ反映するための操作として扱います。公開はDify画面で内容と差分を確認したうえで、人が明示的に行います。検証用アプリを更新する場合だけ、IDを指定します。

# 検証用アプリに限ってドラフトを更新する例
difyctl import studio-app \
  --from-file ./chatflow.yml \
  --app-id <test-app-id>

7. 失敗したときは、どこで止まったかを分けて確認する

この分離が、CodexとDifyを組み合わせる実務上の価値です。DSLの文法問題、Difyへの接続問題、モデルやプラグインの設定問題、アプリの出力品質を、同じ「AIが動かない」として一括りにせず、ノードと実行履歴を見ながら切り分けられます。

既存アプリを壊さずに反映する手順

AIアプリの修正で一番避けたいのは、動いているアプリを直接上書きして、原因を追えなくすることです。最初は必ず検証用アプリを作ります。

# 既存の検証アプリをDSLとして保存する
difyctl export studio-app <検証用アプリID> --output ./exports/current.yml

# DSLの形式と接続を検証する
python3 /path/to/validate_dsl.py --strict --target-version 0.7.0 ./chatflow.yml

# 新しい検証アプリとしてインポートする
difyctl import studio-app --from-file ./chatflow.yml --name "規程検索・検証用"

# 問題がなければ、検証用アプリだけを更新する
difyctl import studio-app --from-file ./chatflow.yml --app-id <検証用アプリID>

インポート結果はDifyのドラフトです。公開は別の操作なので、作成・修正・検証の段階では公開版へ影響させずに進められます。まずは変更前後のDSLとテスト結果を見比べ、「どの修正で何が変わったか」を確認します。

Knowledge Pipelineも、処理を読める形にする

Knowledge Pipelineでは、PDFやCSV、画像などをナレッジへ登録するまでの工程を扱います。ここでも、単にファイルを登録するのではなく、何を確認し、どの条件で次へ進めるかをノードとして表現します。

① PDFを受け付ける
  ↓
② 本文の抽出品質を確認する
  ├─ 良好 → ③ 議題・担当・期限を構造化する
  └─ 不良 → OCR処理へ送る
  ↓
④ 議題ごとに分割する
  ↓
⑤ 議事録ナレッジへ登録する

この構成なら、OCRの失敗、本文がないファイル、担当者が欠けている議事録などを、別のエラー経路として明示できます。「登録されなかった」という結果だけでなく、どの工程で止まったかを確認できます。

現時点では、Knowledge PipelineはStudioアプリのDSLと同じようにdifyctlだけで完結する標準操作としては扱いにくい部分があります。そのため、Difyの画面で実際のパイプライン形式を確認し、Skillでノード構成を整え、検証用ナレッジで反映とテストを行う運用にしています。

直接DSLを編集して反映する場合は、次のルールを守ります。

• 本番ナレッジではなく、検証用ナレッジで先に試す。
• Difyから得た実際の形式を基準にする。
• 変更前後のDSLと、Dify上の実行結果を見比べる。
• 反映後にDify上のテスト実行で、各ノードの入出力を確認する。

まとめ：速く作り、見える形で育てる

Codexのようなエージェントを使うと、AIアプリの試作は速く進みます。その一方で、速さだけを追うと、内部処理が見えなくなり、修正や引き継ぎが難しくなることがあります。

CodexでDSLやテストを作り、Difyで処理の流れをノードとして確認する。この組み合わせにすると、AIアプリをブラックボックスにせず、現場で説明・調整・改善できる形に近づけられます。

AIを導入することと、使い続けられる仕組みを育てることは別です。だからこそ、作る段階から「どこで何をしているか」が見える構成にしておくことが大切だと考えています。

参考情報

• Dify 1.16.0 リリースノート
• Dify GitHubリポジトリ
• 綱業商会のAI導入・DX支援