Claude Codeでnginx設定ファイルを作成する手順

Claude Codeでnginxの設定ファイルを書くとは

Claude Codeにnginxの設定ファイルを書かせるとは、nginx.confのようなテキストファイルをClaude Codeの標準的なファイル編集機能で読み書きする作業です。書いた内容はnginx -tやnginx -s reloadのようなBashコマンドで検証・反映します。Claude Code側にnginx専用の機能はなく、ファイル編集とコマンド実行という2つの標準ツールの組み合わせで完結します。

nginxの用途は大きく3つに分かれます。静的ファイルの配信、他のサーバーへのリバースプロキシ、そしてFastCGIアプリケーションへの中継です。nginx公式のBeginner's Guideはこの3パターンを順に示しており、以下もこの順番で進めます。

前提条件

本記事はnginxがすでにインストール済みの環境を前提にします。設定ファイルは既定でnginx.confという名前で、/usr/local/nginx/conf・/etc/nginx・/usr/local/etc/nginxのいずれかに置かれます。どのパスになるかはビルド・インストール方法で変わるため、Claude Codeに依頼する前に実際のパスを確認しておくと、書き込み先を取り違えません。

Claude Code側で必要になるのは、このパスへのファイル編集権限と、nginxコマンドを実行するBash権限です。既定の権限モードでは、どちらも初回実行時に確認を求められます。

nginxの設定ファイルの構造を押さえる

nginxの設定は、ディレクティブと呼ばれる指示の集まりでできています。名前とパラメータをスペースで区切り、セミコロン(;)で終える「単純ディレクティブ」と、セミコロンの代わりに波括弧{}で囲んだブロックを持つ「ブロックディレクティブ」の2種類があります。ブロックディレクティブが内側に別のディレクティブを持てるとき、それは「コンテキスト」と呼ばれ、events・http・server・locationが代表例です。

コンテキストには入れ子の階層があります。eventsとhttpはどのブロックにも属さない最上位の「mainコンテキスト」に置き、serverはhttpの内側、locationはserverの内側に書きます。#から行末まではコメントとして無視されます。Claude Codeに設定を書かせるときも、この階層をプロンプトで明示すると、意図しない場所にディレクティブが混入するのを防げます。

nginxの起動・停止をコマンドで制御する

nginxは1つのマスタープロセスと複数のワーカープロセスで動きます。マスタープロセスが設定の読み込みとワーカープロセスの管理を担い、実際のリクエスト処理はワーカープロセスが行います。起動は実行ファイルをそのまま実行するだけで済み、起動後の制御は-sパラメータで信号を送ります。

nginx -s stop
nginx -s quit
nginx -s reload
nginx -s reopen

stopは即座に、quitは処理中のリクエストを終えてから停止します。reopenはログファイルの再オープンです。いずれのコマンドも、nginxを起動したのと同じユーザーで実行する必要があります(この制約は後述の権限設定に直結します)。プロセスIDを直接指定する場合は、nginx.pid(既定は/usr/local/nginx/logsか/var/run)に記録されたIDへ次のように送ります。

kill -s QUIT 1628
ps -ax | grep nginx

ps -ax | grep nginxで、稼働中のマスター・ワーカープロセスを確認できます。

手順1: 静的ファイルを配信するserverブロックを書かせる

最初の依頼は、決まった2つのディレクトリからファイルを返す設定です。/data/wwwにHTMLを、/data/imagesに画像を置く前提で、Claude Codeに次のようなserverブロックを書かせます。

既存のnginx.confがすでにある環境では、真っ白な状態から書き直すのではなく、Claude Codeにまず現在の内容を読ませ、cp nginx.conf nginx.conf.bakのようにバックアップを取らせてから新しいserverブロックを追記させると安全です。

server {
    location / {
        root /data/www;
    }
 
    location /images/ {
        root /data;
    }
}

locationはリクエストのURIに対するプレフィックス一致で選ばれ、複数のブロックが一致する場合は最も長いプレフィックスを持つブロックが優先されます。上の例では/images/宛のリクエストだけ/data/images/配下から返され、それ以外は/data/www/配下にマッピングされます。存在しないファイルへのリクエストには404が返ります。

書き終えたら、構文チェックと反映をClaude Codeに任せます。

nginx -t
nginx -s reload

-tは設定ファイルの文法だけを検証するオプションで、実際の反映はしません。マスタープロセスはreloadシグナルを受け取ると新しい設定の文法を検証し、成功した場合だけ新しいワーカープロセスへ切り替えます。検証に失敗すると、古い設定のまま動作を続けます。nginx -tのエラー出力をそのままClaude Codeに渡して修正させると、構文エラーの原因を自分で追わずに済みます。反映結果はaccess.log・error.logで確認します。ログの既定の場所は/usr/local/nginx/logsか/var/log/nginxで、設定ファイルの既定パス(/usr/local/nginx/conf・/etc/nginx等)とは別です。

手順2: リバースプロキシとして設定する

2つ目の依頼は、画像ファイルだけをローカルから返し、それ以外のリクエストを別サーバーへ転送する設定です。転送先にはproxy_passディレクティブを使います。

server {
    location / {
        proxy_pass http://localhost:8080/;
    }
 
    location ~ \.(gif|jpg|png)$ {
        root /data/images;
    }
}

2つ目のlocationは正規表現による一致で、末尾が.gif・.jpg・.pngのリクエストだけを対象にします。nginxはプレフィックス一致を先に比較して最長のものを覚え、そのあとで正規表現を比較します。正規表現が一致すればそちらが優先され、一致しなければ覚えていたプレフィックス一致のブロックが使われます。実際に依頼するときは、たとえば「/images/は/dataから返し、それ以外はlocalhost:8080へproxy_passするserverブロックを書いて、書き終えたらnginx -tを実行して」のように、パスと転送先、優先順位の意図をセットで書くと、生成された設定が食い違いにくくなります。

バックエンドが同じマシンで動くNext.jsアプリのような場合、proxy_passの宛先はそのアプリがlistenするポートです。そのバックエンド自体をClaude CodeでMCP連携しながら開発している場合は、Next.js MCPサーバーをClaude Codeで使う設定ガイドが設定の参考になります。

手順3: FastCGIサーバーへ中継する設定を書かせる

PHPなどFastCGIで動くアプリケーションへ中継する場合は、proxy_passをfastcgi_passに置き換え、fastcgi_paramでパラメータを渡します。

server {
    location / {
        fastcgi_pass  localhost:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param QUERY_STRING    $query_string;
    }
 
    location ~ \.(gif|jpg|png)$ {
        root /data/images;
    }
}

SCRIPT_FILENAMEはFastCGIサーバー側が実行するスクリプトのパスを決めるパラメータで、QUERY_STRINGはリクエストパラメータを渡します。この2つを書き忘れると、FastCGI側がどのスクリプトを実行すべきか判断できず、エラーになります。

権限設定 — 設定ファイルの編集とコマンド実行を許可する

/etc/nginxのような作業ディレクトリ外のパスは、Claude CodeのEdit権限ルールで個別に許可できます。フォルダ配下すべてに編集を許可する場合は、//で始まる絶対パス指定を使います。

{
  "permissions": {
    "allow": [
      "Edit(//etc/nginx/**)",
      "Bash(nginx -t)",
      "Bash(nginx -s reload)"
    ]
  }
}

EditとBashの許可ルールは、あくまでClaude Code自身が「その操作を試みてよいか」を判定する層です。OSのファイル権限はさらに外側にあり、Claude Codeの許可ルールを設定しても越えられません。/etc/nginxがroot所有でClaude Codeを一般ユーザーで動かしている場合、Edit(//etc/nginx/**)を許可していても書き込みは失敗します。同様に、前述のnginx -s reloadのような信号送信も、rootで起動したnginxに対して一般ユーザーのBashから送ることはできません。

実務での選択肢は主に2つです。1つは、sudoを使う個別コマンドをそのまま許可ルールに書く方法です。Claude Codeが自動的に読み替えるラッパーコマンド(timeout・time・nice・nohup・stdbuf等)にsudoは含まれていないため、sudo nginx -tを許可するならBash(sudo nginx -t)のようにsudoを含めた文字列をそのままルールに書きます。もう1つは、root権限が要らない作業ディレクトリの中に設定のドラフトを書かせ、人間がsudo cp等で本来の配置先へ移す方法です。どちらを選ぶかは、Claude Codeにroot操作をどこまで委ねるかという運用判断になります。

サンドボックスを有効にしている場合は、このEdit権限とは別の制限が働きます。サンドボックスの書き込み制限が対象にするのはBashコマンドが直接触るファイルシステムで、作業ディレクトリと--add-dirで追加したディレクトリ以外への書き込みは既定でブロックされます。証明書ファイルを/etc/nginx/sslへコピーする処理はBashコマンド経由の書き込みです。これをサンドボックス下で自動承認したい場合は、sandbox.filesystem.allowWriteにパスを追加します。

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/etc/nginx"]
    }
  }
}

サンドボックス機構の詳しい挙動は別記事にまとめています。書き込み制限だけを外すfilesystem.disabled設定の副作用も含め、sandbox.filesystem.disabledはファイルシステム分離だけ外す設定で扱っています。

用途別の使い分け早見表

反映後の動作確認をClaude Codeに任せる

設定を反映したあとの動作確認は、個々のパスへの単発リクエストだけでなく、負荷をかけた状態での挙動まで見ておくと、リバースプロキシ越しのタイムアウトやFastCGI側のキューイングに気づきやすくなります。Claude Codeにk6のシナリオを書かせて負荷テストをかける手順はClaude Codeでk6の負荷テストスクリプトを作成する手順にまとめています。

よくあるつまずき

• locationの優先順位を勘違いする: プレフィックス一致は長さで競い、正規表現一致はプレフィックス一致より後に比較されます。混在させたときにどちらが選ばれるかを確認せず反映すると、意図しないブロックがリクエストを処理します
• reloadだけで設定が反映されたと思い込む: nginx -s reloadは文法チェックに失敗すると古い設定のまま動き続けます。エラーの有無はerror.logを見るまで分かりません
• fastcgi_paramを省略してFastCGIが動かない: SCRIPT_FILENAMEとQUERY_STRINGはほぼ必須のパラメータです。省略するとFastCGIサーバー側がスクリプトを特定できません
• 設定ファイルの既定パスをディストリビューションで決めつける: /usr/local/nginx/conf・/etc/nginx・/usr/local/etc/nginxのどれになるかはビルド・インストール方法で変わります。Claude Codeに書き込み先を伝える前に実際のパスを確認します
• 証明書のコピーだけサンドボックスの対象外だと思い込む: /etc/nginx/sslへのコピーはBashコマンド経由の書き込みなので、サンドボックスが有効な環境ではsandbox.filesystem.allowWriteが無いと失敗することがあります

まとめ

Claude Codeにnginxの設定ファイルを書かせる作業は、ファイル編集とBashコマンドという2つの標準機能の組み合わせで完結します。静的配信・リバースプロキシ・FastCGI中継という3つの型と、locationの優先順位・fastcgi_paramの必須パラメータを押さえておけば、生成される設定の精度が上がります。反映前のnginx -tの実行と、/etc/nginxのような作業ディレクトリ外への書き込み権限――Claude Codeの許可ルールとOSのファイル権限は別の層であることも含めて――は、設定内容そのものより先に決めておく価値があります。