「n8nで自動化WFを組んだはいいが、気付いたら止まっている」「修正のたびに本番が壊れて怖い」——中小企業の情シスやマーケ担当の方なら、一度は経験があるのではないでしょうか。私自身、YouTube投稿・Google Search Console（GSC）のKPI集計・Slack通知などを n8n で運用していますが、最初の半年は障害対応で疲弊しっぱなしでした。転機になったのが Claude CLI（Claude Code） との組み合わせ。WF設計から障害対応までを一気通貫で回せるようになり、復旧時間が体感1/3まで縮みました。本記事では、実際に運用している現場メモから「再現性のある手順」だけを抜き出してご紹介します。
1. この記事で解決する課題
1-1. 中小企業の現場で起きている「あるある」
n8n は強力な自動化ツールですが、運用していると必ずぶつかる壁があります。私の周りでも、こんな声をよく聞きます。
- 「n8n を立てたはいいが、OAuth トークンが切れて毎週WFが止まる」
- 「WFを直接UIで触ってしまい、誰がいつ何を変えたか分からなくなった」
- 「エラーログがどこにあるか分からず、復旧に半日溶けた」
- 「Cron 実行が止まっていることに、3日経ってから気付いた」
これらは「n8nが悪い」のではなく、運用プロセスがコード化されていないことが原因です。手順がチームメンバーの頭の中にしかないので、属人化し、AIにも引き継げず、結局「触った人が責任を取る」状態になります。
1-2. 本記事の対象読者
- すでに n8n を導入済み、または導入を検討中の中小企業の情シス／マーケ担当
- Claude CLI で日々の運用業務を効率化したい実務者
- 「自動化はしたいが、運用が回らずに困っている」と感じているチーム
逆に「n8n をこれから学ぶ」という方は、まず公式ドキュメントでノードの基本を抑えてから本記事に戻ってきていただくと、より腹落ちすると思います。
2. 結論：6ステップの修正プロトコルをファイル化せよ
先に結論を書きます。1年運用してたどり着いた答えは、シンプルです。
n8n のWF修正は、必ず「deactivate → 修正 → テスト実行 → 出力確認 → activate → 通知」の6ステップで回す。Claude CLI には WF JSON とこのプロトコルをコンテキストとして渡し、修正案を出させる運用が最も事故が少ない。
具体的にはこうです。
- やること：WF JSON をリポジトリ管理し、Claude CLI に「ファイルパス + 修正プロトコル」を指定して作業させる
- やらないこと：n8n UI で直接、本番アクティブなWFを編集する
- 得られる効果：障害対応時間が体感1/3、トークン切れ起因の連続エラーが激減、レビューが diff ベースになる
「たったそれだけ？」と思われるかもしれませんが、ポイントは「プロトコルそのものをMarkdownでリポジトリに置き、Claude CLI に毎回読ませる」こと。これをやるかやらないかで、再現性が桁違いに変わります。
3. 具体的な手順・設定方法
3-1. ディレクトリ構成（Claude CLI が読みに行く場所を固定する）
まず、リポジトリの構成を決め打ちにします。Claude CLI に「どこを読めばいいか」を毎回説明するのは非効率なので、固定パスで運用します。
claude-workspace/
├── ai-business/
│ ├── infra/n8n-workflows/ # WF JSONの正本（Git管理）
│ │ ├── wf38-gsc-kpi.json
│ │ └── wf35b-youtube-shorts-script-en.json
│ ├── scripts/
│ │ ├── youtube-oauth-reauth.py
│ │ ├── update-vps-youtube-tokens.py
│ │ └── maintenance-runner.js
│ └── docs/
│ └── workflow-n8n-ops.md # 6ステップ・プロトコルの正本
└── shared/
├── credentials.md # 認証情報（.gitignore対象）
└── domain-skills/engineering/n8n-workflow.md # 設計パターン集
なぜディレクトリを固定するのか？理由は3つあります。
- Claude CLI のプロンプトを短くできる：「infra/n8n-workflows/ のwf38を直して」だけで通じる
- diffレビューが楽になる：WF JSONがGitに乗っているので、変更点が一目瞭然
- 新メンバーのオンボーディングが速い：「このディレクトリを見て」で済む
注意点として、shared/credentials.md は必ず .gitignore に入れること。私は最初、認証情報をリポジトリにコミットしかけて、git history からの除去に半日かかりました。「秘密情報は別ファイル、本体はパス参照」のルールを最初に作っておくと事故が減ります。
3-2. WF修正プロトコル（6ステップ／本記事の核）
本記事の心臓部です。WF修正は必ずこの順番で行います。
- deactivate：APIで対象WFを非アクティブ化（自動実行と編集の衝突を防ぐ）
- 修正実施：WF JSON を直接編集、またはノード設定を変更
- n8n上でテスト実行：UI の “Execute Workflow” ボタンで単発テスト
- 成果物を直接確認：WordPress投稿／Supabaseレコード／Slackメッセージなど、実際の出力先を見る
- activate：テスト通過後に再度アクティブ化
- 完了通知：Slack通知WF（私の環境ではWF#04を集約口にしています）経由で関係者に共有
なぜこの順番なのか、各ステップに理由があります。
- ステップ1（deactivate）の理由：cron実行と編集が同時に走ると、中途半端な状態でデータが投入されます。後述する失敗④でハマったので、ここは絶対に省略しない。
- ステップ3（テスト実行）の理由：JSONの構文だけ見ても、実際に動かさないと「式の評価エラー」は出ません。n8nは
{{ $env.HOGE }}のような独自記法があり、静的解析では追いきれません。 - ステップ4（成果物確認）の理由：n8n UI上で「成功」と出ても、出力先に何も届いていないことが普通にあります。Slackチャネルやスプレッドシートを実際に開いて確認するクセを付けてください。
- ステップ6（通知）の理由：「直しました」を口頭で言うと忘れます。Slack通知に残すことで、後から「いつ復旧したか」の監査ログにもなります。
3-3. 実際に使う API コマンド集
ここからは、現場で毎日叩いているコマンドを掲載します。環境固有の値（IP、ポート、APIキー）はダミーに置換していますので、ご自身の値に差し替えて使ってください。
アクティブWF一覧の取得
curl -s "http://your-n8n.example.com:5678/api/v1/workflows?active=true" \
-H "X-N8N-API-KEY: YOUR_N8N_API_KEY" | \
python3 -c "import json,sys; [print(f'{w[\"id\"]}: {w[\"name\"]}') for w in json.load(sys.stdin)['data']]"
このコマンドを毎朝叩く習慣をつけると、「気付いたら止まっていた」が劇的に減ります。私は maintenance-runner.js から朝8時に自動実行させ、結果をSlackに流すようにしています。
deactivate / activate
# 修正前：必ず deactivate から
curl -X POST "http://your-n8n.example.com:5678/api/v1/workflows/WF_ID/deactivate" \
-H "X-N8N-API-KEY: YOUR_N8N_API_KEY"
# 修正・テストが通ったら activate
curl -X POST "http://your-n8n.example.com:5678/api/v1/workflows/WF_ID/activate" \
-H "X-N8N-API-KEY: YOUR_N8N_API_KEY"
慣れてくると「UIで deactivate ボタン押す方が早くない？」と思いがちですが、API経由で操作すると履歴が残せるのと、シェルスクリプトに組み込めるのが大きいです。私はBashエイリアスで n8n-off WF38 のように叩けるようにしています。
VPS側のログ確認
ssh [email protected] "docker logs n8n --tail 50 2>&1 | grep -E '(ERROR|error|failed)'"
n8n UIの実行履歴だけでは追いきれないエラー（コンテナ起動時の問題、メモリ枯渇など）はここに出ます。「UIでは何も出ていないのに、なぜか動かない」ときは、まずこのコマンドを叩いてください。
環境変数の確認
ssh [email protected] "cat /etc/n8n/.env | grep -E '(GSC|YOUTUBE|SLACK)' | sed 's/=.*/=[REDACTED]/'"
値を直接表示するとSSHログに認証情報が残るので、sed でマスクします。「キーが存在するかどうか」だけが知りたいときに重宝するコマンドです。
3-4. Claude CLI への渡し方（プロンプト例）
ここが本記事最大のキモです。Claude CLI への指示は、「ファイルパス + プロトコル参照 + ゴール」の3点セットで渡します。
WF#38 (infra/n8n-workflows/wf38-gsc-kpi.json) の "Generate SA JWT" ノードがエラー。
docs/workflow-n8n-ops.md の「WF修正プロトコル（6ステップ）」に従って、
以下を実施してください：
1. 該当WF JSONを読み込み、エラー箇所を特定
2. 修正案を diff 形式で提示
3. テスト実行用の curl コマンドを生成
4. activate 後のSlack通知文面案も用意
なお、本番環境変数 GSC_SA_JSON が未設定の可能性もあるので、
VPS側の確認コマンドも併せて提示してください。
このプロンプトを使うようになってから、修正の質が安定しました。「プロトコル参照」を明示することで、Claude CLI が手順を飛ばさず、必ず deactivate から始めてくれます。
逆に、初期は「wf38を直して」みたいな雑な指示をしていて、テストせずに activate するコードを返されたり、環境変数を直書きしようとしたりと、ヒヤッとする提案が混じっていました。「プロトコルファイルを毎回読ませる」のは、AIに対するガードレールだと思ってください。
4. 実際に使ってみた結果（メリット・デメリット）
4-1. メリット（運用1年で実感したもの）
① 障害復旧が速い
WF#38（GSC KPI集計）のJWT認証エラーで、過去は30分かかっていた復旧が10分まで縮みました。Claude CLI が「過去の修正履歴を踏まえて、今回も同じ env 不足では？」と先回りで仮説を出してくれるので、調査時間が圧縮されます。
② 修正履歴が完全に残る
WF JSON が Git に乗っているので、git log --oneline infra/n8n-workflows/wf38-gsc-kpi.json で「いつ誰が何を変えたか」が一覧できます。月次の振り返りミーティングで「先月WF#38を3回直してるね、根本対処しよう」みたいな議論ができるようになりました。
③ AIへの引き継ぎが容易
プロトコルをファイル化したので、Claude CLI に毎回同じ品質で作業させられます。担当者が休みでも、別メンバーが同じプロンプトを投げれば同じ手順で復旧できる。「属人化の解消」が一番大きい効果かもしれません。
④ レビュー文化が定着した
WF修正がPRベースで回るようになり、「本番直前に他メンバーが目視チェック」が当たり前になりました。これだけで、致命的なミスはほぼゼロです。
4-2. デメリット・割り切るところ
もちろん良いことばかりではありません。正直に書きます。
① 初期セットアップが面倒
n8n API キーの発行、SSH鍵の配置、サービスアカウントJSONの取得、Slack Webhookの登録……準備物が多く、初日は半日溶けます。とはいえ一度作れば後は楽なので、ここは投資と割り切りましょう。
② n8n UI と JSON の二重管理リスク
UIで触ってしまうと、リポジトリと実体に差分が出ます。私は週1回 maintenance-runner.js で「リポジトリのJSON ⇔ n8n上の実体」を diff し、差分があればSlack警告を飛ばす仕組みを入れています。「人間は必ずミスする」前提で、検出の仕組みを別途持つのが現実解です。
③ OAuth系トークンは完全自動化しきれない
YouTube やGoogle系のOAuthは、リフレッシュトークンが切れると人間のブラウザ操作が必要になります。ここは諦めて、「2日連続エラー = トークン切れ」と決め打ちで再認証スクリプトを叩く運用にしています。
④ Claude CLI の出力を盲信できない
稀に「もっともらしいけど間違ったAPI仕様」を返してくることがあります。特に n8n の独自記法（{{ $json.field }} と {{ $node["Name"].json.field }} の使い分けなど）は、私が手で最終確認するようにしています。
5. よくある失敗とその対処法
5-1. 失敗①：環境変数 GSC_SA_JSON が未設定でJWTノードが落ちる
症状：WF#38 の Generate SA JWT ノードが赤くなり、「Cannot read property ‘private_key’ of undefined」のようなエラーが出る。
原因：VPS側の /etc/n8n/.env に GSC_SA_JSON が定義されていない、もしくは JSON のエスケープが崩れている。
対処：
# 1) env 確認（値ではなく存在のみチェック）
ssh [email protected] "grep -c '^GSC_SA_JSON=' /etc/n8n/.env"
# 2) 未設定なら GCP からSA JSONを取得し、エスケープしてenvに追記
# .env ファイルでは改行とダブルクォートのエスケープが必須
# 例: GSC_SA_JSON='{"type":"service_account","project_id":"..."}'
# 3) n8n 再起動（コンテナ運用の場合）
ssh [email protected] "docker restart n8n"
# 4) WF#38 をテスト実行して通過確認
curl -X POST "http://your-n8n.example.com:5678/api/v1/workflows/WF38_ID/activate" \
-H "X-N8N-API-KEY: YOUR_N8N_API_KEY"
ハマりポイントは「JSONの中にシングルクォートが入っていると、bashの ' で囲む方式が壊れる」こと。私は最初これに気付かず、env追記後もエラーが続いて1時間悩みました。JSONをBase64エンコードして格納し、n8n側でデコードする方式に切り替えてからは事故ゼロです。
5-2. 失敗②：YouTube EN WF（#35b）が2日連続エラー
症状：YouTube Shorts投稿WFが、特にエラーメッセージなく「401 Unauthorized」で2日連続失敗。
原因：YouTube Data API の OAuth リフレッシュトークンの期限切れ。Googleはセキュリティ強化のため、未使用トークンを6ヶ月で無効化することがあります。
対処：
# ローカルでブラウザを開いてトークン再取得
python3 ai-business/scripts/youtube-oauth-reauth.py
# 取得したトークンを VPS の n8n に反映
python3 ai-business/scripts/update-vps-youtube-tokens.py
# 反映後、WF#35b を手動で1回実行して通過確認
教訓：「OAuth系は2日連続エラー＝トークン切れ」と決め打ちで動くと早いです。最初は「APIの仕様変更か？」「YouTubeのレート制限か？」と無駄な調査をして3時間溶かしました。パターンを覚えれば、判断は秒で済みます。
さらに、Claude CLI に「2日連続でWF#35bがエラー。OAuth再認証スクリプトを叩く前に、念のため別の原因（API quota、ネットワーク）をチェックする方法も提示して」と聞くと、quota確認用のcurlコマンドまで出してくれるので、消去法での切り分けが早くなりました。
5-3. 失敗③：n8n式の構文エラー（環境変数参照の書き方）
症状：「Cannot parse JSON」のような曖昧なエラーで、JWTノードが起動すらしない。
原因：{{ $env.GSC_SA_JSON }} の前後にダブルクォートを付ける／付けないで、後続のJSON.parseが落ちる。n8nの式評価は「文字列として展開→そのままJSONとして解釈」という二段階処理なので、引用符の扱いが直感に反します。
対処：Claude CLI に「infra/n8n-workflows/ 配下で、同じく env から JSON を読み込んでいる通過済みノードを探して、その記法と揃えてください」と指示すると、一発で直ります。「他で動いているコードに揃える」がデバッグの王道です。
具体的には、私の環境では以下のような記法に統一しています。
// JWT ノードの "Private Key" フィールド
{{ JSON.parse($env.GSC_SA_JSON).private_key }}
// 別ノードでservice_emailを使うとき
{{ JSON.parse($env.GSC_SA_JSON).client_email }}
「2箇所で JSON.parse するのは無駄じゃない？」と思うかもしれませんが、n8nの式はノード間で値の引き継ぎが面倒なので、各ノードでパースし直す方が結果的に保守しやすいです。
5-4. 失敗④：deactivate せずに編集して本番が止まった
症状：WFを編集中に、ちょうど cron が走り、中途半端な状態のWFが実行された。Supabaseに不完全なレコードが100件投入され、後処理で半日溶けた。
原因：「ちょっとだけ直すから deactivate しなくていいや」という油断。n8nは「Save」ボタンを押した瞬間に新しい定義が反映されるので、cronとの競合が発生します。
対処：
- 必ずプロトコル1番のdeactivateを先にやる（人間にもAIにも徹底）
- Claude CLI への指示文に「deactivateを省略しないでください」を明記
- 修正前後に
workflow-n8n-ops.mdを Read させる運用にして、プロトコル違反を防ぐ
この事故以降、私は workflow-n8n-ops.md の冒頭に「⚠️ 修正は必ず deactivate から開始すること」と赤字で書き、Claude CLI に「このファイルを最初に読んでから作業を始めてください」と明示しています。AIエージェントは指示通りに動く一方、暗黙のルールは守れません。明文化が全てです。
5-5. 失敗⑤：APIキーをチャット履歴にコピペしてしまった
症状：デバッグ中、curlコマンドにAPIキーを直書きしたまま Claude CLI に貼り付けてしまった。
対処：
- 即座にAPIキーをローテーション（n8nの管理画面から再発行）
- 以降は
export N8N_API_KEY=...でシェル環境変数化し、コマンドには$N8N_API_KEYで参照 - Claude CLI に渡すコマンドは、必ず変数参照形式に統一
地味な事故ですが、運用者なら誰もが一度はやる失敗です。「秘密情報は変数経由でしか触らない」をチームルール化することで、人為ミスを物理的に防げます。
6. まとめ・次のステップ
6-1. この記事のポイント3つ
- WF JSON は Git 管理、UI 直接編集はしない。差分レビューと履歴管理が運用の土台になります。
- 6ステップの修正プロトコルをファイル化し、Claude CLI に毎回読ませる。AIへのガードレールとして機能します。
- OAuth系トークンは「切れる前提」でスクリプト化。完全自動化を諦めて、半自動を綺麗に作る方が結果的に安定します。
6-2. 次にやるとよいこと
- Slack通知WFを1本作る：すべてのWFの完了・エラー通知を1つのチャネルに集約すると、監視コストが激減します
- maintenance-runner.js を cron 化：毎朝、アクティブWF一覧と直近24時間のエラーをSlackに流す。「気付いたら止まっていた」がほぼゼロになります
- 設計パターンを社内Wiki化：
shared/domain-skills/engineering/n8n-workflow.mdのように、よく使うWFパターン（ファンアウト、リトライ、エラーハンドリング）をテンプレ化しておく - Claude CLI のカスタムスキル化：プロトコルをスキルとして登録すると、毎回のプロンプトがさらに短くなります
6-3. さらに学びたい人へ
- n8n 公式 API ドキュメント（特に Workflow と Execution エンドポイント）
- Claude Code のカスタムスキル機能（プロトコルをスキル化すると再利用性が上がる）
- サービスアカウント運用のベストプラクティス（GCP IAM の最小権限原則）
- Docker でのn8n運用：ボリュームマウントと環境変数管理
n8n × Claude CLI の組み合わせは、「ノーコードの手軽さ」と「コード管理の堅牢さ」のいいとこ取りができる強力な選択肢です。最初の1ヶ月は準備に時間がかかりますが、半年後には「もうこの運用以外考えられない」と感じるはずです。本記事のディレクトリ構成・プロトコル・コマンド集をそのままコピペして使っていただいてOKですので、ぜひ自社の運用に組み込んでみてください。
運用していく中で「うちはこういう工夫をしている」「この部分はもっとこうすると良い」という知見が出てきたら、ぜひ社内のドキュメントに追記し、チームの財産にしていきましょう。自動化の本質は「ツール導入」ではなく「運用プロセスのコード化」です。今日の小さな1歩が、半年後の大きな安定運用につながります。
IT・SaaS専門の比較メディア。中小企業の導入担当者向けに独自調査・中立的な比較情報を提供