「動かないn8n」に毎週消耗していた話 ― きっかけは深夜のWP誤投稿
n8nを業務に取り入れて1年。便利なのは確かなのですが、正直なところ最初の半年は「作ったが運用できない」「直そうとして壊す」の繰り返しでした。30個近いワークフロー（以下WF）を一人で抱えていると、ある日突然「翻訳WFが2日連続でエラー」「YouTube投稿WFがOAuth切れで止まっている」「GSC（Google Search Console）KPI集計WFが認証エラー」と、何かしらが壊れている状態が常態化します。
転機は、deactivateし忘れたまま編集していたWP投稿WFが深夜のcronで暴発し、中途半端な下書きが本番公開されてしまった事件でした。これを機に、Claude CLI（Claude Codeのターミナル版）にn8n運用の半分を任せる仕組みを作り、半年運用してきた知見をこの記事にまとめます。
結論を先に書きます。
- n8nのWF修正は「deactivate → 修正 → テスト実行 → 成果物確認 → activate → 通知」の6ステップを必ず守る。本番障害の体感9割はこの順番違反で起きます。
- Claude CLIには「運用カード」（
workflow-n8n-ops.md）を読ませる。コマンド・パス・認証情報の在処を1ファイルに集約すれば、CLIが状況判断して修正提案まで自走してくれます。 - 認証情報は環境変数（VPSの
/etc/n8n/.env）に寄せる。WF JSONには絶対に埋め込まない。トークン切れは再取得スクリプトで自動化する。
以下、実際にコピペで動かせるレベルで手順を書いていきます。なお、コマンド中のIPアドレス・ドメイン・認証情報は全てダミー値（192.168.x.x、your-server.example.com、YOUR_N8N_API_KEY等）に置き換えてあります。自社環境の値に差し替えてご利用ください。
全体アーキテクチャ：手元のClaude CLIからVPS上のn8nを操作する
まず構成のイメージから共有します。難しいことはしていません。手元のMac（あるいはWindows + WSL）から、Claude CLI経由でn8nのAPIとVPSのSSHを叩いているだけです。
[手元のMac：Claude CLI]
├─ workflow-n8n-ops.md（運用カード）を読み込み
├─ n8n API（curl）でWF操作
├─ SSH で VPS の /etc/n8n/.env を確認
└─ 認証再取得スクリプト（Python）を実行
↓
[VPS：Docker上のn8n]
├─ /etc/n8n/.env（GSC_SA_JSON 等を集約）
└─ docker logs n8n（実行ログ確認）
↓
[連携先：WordPress / Supabase / Slack / YouTube]
ポイントは、「Claude CLIが自走するために必要な情報を、すべて1枚のMarkdownに集約しておく」こと。これがないと、毎回「VPSのIPは？」「APIキーはどこ？」と聞かれて手が止まります。逆にこれさえ整っていれば、「WF#38が落ちてるので調査して直してください」とだけ伝えれば、CLI側でログ取得 → 原因切り分け → 修正案提示まで進めてくれます。
ステップ1：運用カード（workflow-n8n-ops.md）を1枚作る
最重要かつ、一番面倒な作業です。私は半日かけて書きました。書く項目はざっくり以下の通り。
- n8nインスタンス情報（管理画面URL、Basic認証の所在、APIキーの所在）
- 認証方式（OAuth/サービスアカウント/JWT生成ノードの仕組み）
- ファイルパス一覧（WF JSON / 認証情報 / 再認証スクリプト）
- WF修正プロトコル（6ステップ）
- 既知の障害WF一覧（症状・原因・対処手順）
テンプレートとして使えるよう、抜粋を載せておきます。実値は伏せた状態の例です。
# Workflow: n8n 運用管理（認証 + WF修正）
## n8n インスタンス情報
| 項目 | 値 |
|------|-----|
| 管理画面（直接IP） | http://192.168.x.x:5678 |
| 管理画面（ドメイン） | https://your-server.example.com |
| Basic認証ユーザー名 | shared/credentials.md 参照 |
| Basic認証パスワード | shared/credentials.md 参照 |
| n8n API キー | shared/credentials.md の N8N_API_KEY |
## VPS 接続情報
- SSH: ssh [email protected]
- n8nコンテナ名: n8n
- 環境変数ファイル: /etc/n8n/.env
## 認証情報の格納場所
- GSCサービスアカウント: VPS /etc/n8n/.env の GSC_SA_JSON
- YouTube OAuth（JP/EN）: VPS /etc/n8n/.env の YT_*_TOKEN
- WordPress App Password: VPS /etc/n8n/.env の WP_APP_PASSWORD
## ファイルパス
- WF JSON 正本: ~/claude-workspace/ai-business/infra/n8n-workflows/
- 認証情報: ~/claude-workspace/shared/credentials.md（chmod 600）
- 再認証スクリプト: ~/claude-workspace/ai-business/scripts/
このとき絶対に守るべきは「認証情報の実値を書かない」ことです。書くのは「どこに保管してあるか」の場所だけ。私の場合はshared/credentials.md（パーミッション600、Gitignore済み）に実値を集約し、運用カードからは参照のみにしています。Claude CLIに渡しても安全な設計です。
やってみて分かったこと：このカードを書き上げると、自分の頭の中の「暗黙知」がいかに散らかっていたかが可視化されます。「あのAPIキーどこに保存したっけ」と探していた時間が嘘のようになくなりました。半日の投資はすぐペイします。
ステップ2：WF修正プロトコル（6ステップ）を徹底する
これがすべての中核です。n8nのWFを修正するときは、必ずこの順番で行います。
① deactivate（最優先）
修正中の自動実行を止めます。これを忘れると本当に痛い目に遭います。
curl -X POST "http://192.168.x.x:5678/api/v1/workflows/<WF_ID>/deactivate" \
-H "X-N8N-API-KEY: YOUR_N8N_API_KEY"
なぜAPIを使うか？ n8n UIでもdeactivateできますが、UIだと「ボタンを押したつもりで押せていない」事故が起きがちです。コマンド一発のほうが確実で、しかもClaude CLIに任せられます。「WF#38を直すので先にdeactivateしてください」と伝えれば、CLIがそのままcurlを叩いてくれます。
② 修正実施
WF JSONを直接編集するか、n8n UI上でノード設定を変更します。ここで決めておくべき大事なルールが「正本（Source of Truth）はどこか」。私の場合はinfra/n8n-workflows/*.jsonを正本とし、UIで編集したら必ずExport → Git commitする運用にしています。これを決めないと差分管理が地獄になります（実際に1回やらかしました）。
③ n8n上でテスト実行
UIの「Execute Workflow」ボタンを押すだけ。ですが、これを飛ばす人が本当に多い。「コードちょっといじっただけだから動くでしょ」が事故の元です。私は飛ばしてWP投稿が500記事分エラーキューに溜まったことがあります。
④ 成果物・出力を直接確認
WF実行が「成功」と表示されても、それは内部の処理が完了しただけです。必ず実際の成果物を確認すること。
- WP投稿WF → WordPress管理画面で実際の記事を確認
- Supabase書き込みWF → Supabase Studioでレコードを確認
- Slack通知WF → 実際にチャンネルにメッセージが届いたか確認
n8nの「Success」は信用しない、と覚えてください。私はAPIレスポンスが200だけど中身が空、というケースで2回ハマりました。
⑤ activate
curl -X POST "http://192.168.x.x:5678/api/v1/workflows/<WF_ID>/activate" \
-H "X-N8N-API-KEY: YOUR_N8N_API_KEY"
⑥ Slack通知
関係者への通知も自動化します。私の環境ではWF#04（運用通知用WF）にWebhookで投げると、Slackの#n8n-opsチャンネルに「WF#XX をactivateしました」と自動投稿される仕組みにしています。通知自体もWF化することで、属人化を防げます。
ステップ3：アクティブWF一覧をワンライナーで取得
WFが30個を超えると、「いま動いてるのどれだっけ」が分からなくなります。これを毎朝のチェックに使っているコマンドがこちら。
curl -s "http://192.168.x.x: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']]"
Claude CLIに「いまアクティブなWFをリストアップして」とお願いすると、このコマンドを実行して整形までしてくれます。さらに「このうちcron実行しているものはどれ？」と続けて聞けば、各WFのトリガーノードを調べて返してくれます。一人運用の強い味方です。
やってみて分かったこと：このコマンドを毎朝の習慣にしただけで、「気付いたら無効化されていたWF」「テスト用に作ったまま残っていた重複WF」が一気に可視化されました。最初に走らせた朝、47個もWFがあって、うち14個は不要なゴミでした。
ステップ4：認証情報を環境変数に集約する
n8nを運用していて一番事故りやすいのが認証情報の管理です。WFのJSONに直書きしていると、Gitに上げる際の事故、UI上での誤コピー、引き継ぎ時の漏洩など、リスクだらけ。
解決策はシンプルで、すべてVPSの/etc/n8n/.envに集約し、WF内では{{ $env.変数名 }}で参照すること。例えばGSC用のサービスアカウントJSONなら、こうします。
# VPSの /etc/n8n/.env に追記
GSC_SA_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'
# 確認コマンド（実値は出さず、設定されてるかだけ確認）
ssh [email protected] "grep -c '^GSC_SA_JSON=' /etc/n8n/.env"
# n8nコンテナを再起動して反映
ssh [email protected] "docker restart n8n"
WFのGenerate SA JWTノード内では{{ $env.GSC_SA_JSON }}と書くだけ。実値はWF JSONには現れません。
ハマりポイント：JSON文字列内のダブルクォートをエスケープし忘れて、.envファイル自体が壊れる事故が頻発します。シングルクォートで全体を囲むのが安全です。それと、.envを編集したら必ずdocker restart。再起動しないと変数が読み込まれず、「設定したのに動かない」と30分悩むことになります（実体験）。
ステップ5：OAuthトークン切れに備えて再取得を自動化
YouTube連携WFのトラブル原因の8割はOAuthトークンの期限切れです。手動再取得を毎回やっていられないので、Pythonスクリプトを2本用意して回しています。
# ① 手元でOAuthフローを通してトークンを再取得
python3 ~/claude-workspace/ai-business/scripts/youtube-oauth-reauth.py
# ② 再取得したトークンをVPSへ反映
python3 ~/claude-workspace/ai-business/scripts/update-vps-youtube-tokens.py
# ③ n8nを再起動して反映
ssh [email protected] "docker restart n8n"
1本目はローカルでブラウザを開いてOAuth同意画面を通し、refresh_tokenを取得。2本目はSCPでVPSの.envに書き戻すだけ。シンプルですが、これがあるとないとで作業時間が10倍違います。
Claude CLIに任せるときは、「WF#35bがエラーで止まっているので、OAuth切れかどうか確認し、切れていれば再取得手順を案内してください」と伝えれば、docker logsを見て切り分け、必要なら上記スクリプトの実行コマンドを提示してくれます。
ステップ6：エラー発生時のログ確認は最初の30秒で
WFが落ちたとき、まず叩くのはこれ。
ssh [email protected] \
"docker logs n8n --tail 100 2>&1 | grep -E '(ERROR|error|failed|Unauthorized|expired)'"
これでだいたい原因の当たりがつきます。よくある検出パターンは以下。
Unauthorized→ 認証情報の期限切れ、もしくは権限変更ECONNREFUSED→ 連携先サービスがダウン中Rate limit exceeded→ APIの呼び出し上限超過（特に翻訳APIで頻発）Cannot read properties of undefined→ 前段ノードの出力が想定と違う（API仕様変更が多い）
実際に使ってみたメリット
1. WF修正の所要時間が体感3分の1に
以前は「修正 → 動かない → 慌てて戻す」を繰り返していた時間が、6ステップ徹底だけでほぼゼロになりました。本番ロールバックは過去3か月で0回。
2. 属人化の解消
運用カードができたことで、「自分が休んでも誰かに引き継げる」状態になりました。実際、私が体調を崩した日にチームメンバーが運用カード片手にWF#38の認証エラーを復旧してくれて、感動しました。
3. 複数WFの棚卸しが楽
API一発でアクティブWFが一覧化できるので、月次の棚卸し（不要WFの削除、命名規則チェック）が10分で終わります。
4. 認証更新フローの標準化
YouTube OAuth・GCPサービスアカウントの再取得が「スクリプト2発」に圧縮されたのは精神衛生上もとてもいい。
デメリット・注意点
1. 初期の運用カード作成に半日〜1日かかる
これは正直しんどいです。ただし1度書けば資産になり、Claude CLIに渡せばさらにCLIが行間を補完して動いてくれるので、投資対効果は高い。
2. n8n APIキー / SSH鍵の取り扱いに細心の注意
Claude CLIに渡す前提なら、認証情報はshared/credentials.md（パーミッション600、Gitignore済み）のような場所に集約必須。間違ってもGitリポジトリに直接コミットしないこと。Pre-commitフックでgit-secretsを仕込んでおくと安心です。
3. JSON直編集とUI編集が混在しがち
n8nはDBにWFの状態を持つため、JSONファイルだけ変えても反映されません。正本をどちらにするか決めないと差分管理で詰みます。私のおすすめはinfra/n8n-workflows/*.jsonを正本にし、UI編集後は必ずExport → Git commitするルール。
よくある失敗とその対処法
失敗1：deactivateせずに修正してWFが暴発
症状：修正中のWFがcronで動き、中途半端なWP記事が公開された（私の実話）。
対処：プロトコルの1番（deactivate）を絶対の最初に。Claude CLIに「修正に入ります」と伝えた時点で最初に必ずdeactivate APIを叩く、というルールを運用カードに明記しています。
失敗2：Generate SA JWTノードが失敗（GSC KPI集計WF）
症状：GSC_SA_JSON環境変数が未設定、または式の構文ミス。
対処手順は以下。
# 1. envの存在確認
ssh [email protected] "grep -c '^GSC_SA_JSON=' /etc/n8n/.env"
# 2. 未設定なら GCPコンソールでサービスアカウントJSONを取得し、
# シングルクォートで囲んで .env に追記
# GSC_SA_JSON='{"type":"service_account",...}'
# 3. 再起動
ssh [email protected] "docker restart n8n"
# 4. WFをテスト実行してJWT生成ノードが通過することを確認
失敗3：YouTube Shorts WFが2日連続エラー
原因：OAuthトークン期限切れ。
対処：前述のyoutube-oauth-reauth.py → update-vps-youtube-tokens.pyの2発で復旧。所要時間5分。
失敗4：翻訳WFが突然停止
原因：翻訳API認証期限切れ、またはAPI使用量上限到達。
調査手順：n8n UIでWFの実行履歴を開き、最後のエラーログを確認 → APIプロバイダのダッシュボードで残量チェック。月初にリセットされるタイプのAPIだと、月末に突然止まるので、残量アラートを別WFで監視するのも有効です。
失敗5：WF JSONを直編集したがn8n UIに反映されない
原因：n8nはDBに状態を持つため、JSONファイルだけ書き換えても反映されない。
対処：JSON編集 → n8n UIでImport（または API PUT /workflows/<id>）→ activate の順を守る。これはn8nの仕様なので、慣れるしかありません。
Claude CLIへの指示の出し方（実例）
参考までに、私が普段Claude CLIに投げているプロンプトのパターンを共有します。
# パターン1：状況把握
「workflow-n8n-ops.md を読み込んで、現在アクティブなn8n WFを一覧表示してください」
# パターン2：障害対応
「WF#38（GSC KPI集計）が昨晩エラーで止まっています。
docker logs と /etc/n8n/.env を確認して、原因と対処手順を提示してください。
ただし、本番への変更コマンドは私の確認を取ってから実行してください」
# パターン3：定期メンテ
「今月分の不要WF棚卸しをします。
過去30日間1度も実行されていないWFをリストアップしてください」
ポイントは「本番への変更コマンドは確認を取ってから」と明記すること。Claude CLIは賢いですが、prompt次第ではcurl POSTまで一気に走らせてしまうこともあるので、人間のレビューを挟む運用が安全です。
まとめと次のアクション
n8nは本当に便利なツールですが、「運用」を仕組み化しないとあっという間に破綻します。逆に言えば、運用カード（Markdown 1枚）+ Claude CLI + 6ステップのプロトコル、というシンプルな3点セットを整えるだけで、現場は驚くほど安定します。
読者の方が明日から自社で動かすなら、以下の順番でやってみてください。
- 今日やる：自社n8nの運用カードを書く。最低限、管理画面URL、認証情報の保管場所、VPSへのSSH接続情報、アクティブWFのID・名前一覧。
- 今週やる：WF修正プロトコル（6ステップ）をチームのSlackに固定ピン。全員で守る合意を取る。
- 今月やる：OAuth系の再取得をスクリプト化。手動運用から卒業する。
- 発展：n8nメンテナンス用スクリプト（ヘルスチェック、不要WF検出、認証期限警告）を定期実行化する。
n8nもClaude CLIも、単体では「便利ツール」止まりです。組み合わせて、運用ドキュメントを介して「会話するように業務を回す」と、初めて中小企業の現場で実用に乗ります。本記事の手順テンプレートが、皆さんの現場の負担を少しでも軽くできれば幸いです。
運用が回り始めたら、次は「n8nメンテナンス用スクリプトでWF全体のヘルスチェックを定期実行する」「Claude CLIのCLAUDE.mdに運用カードを読み込ませて自走度を上げる」あたりが発展ステップになります。tech-picks.netでは引き続き、中小企業向けの実践的なAI活用・自動化ノウハウを発信していきます。
IT・SaaS専門の比較メディア。中小企業の導入担当者向けに独自調査・中立的な比較情報を提供