入力欄に質問を書き、送信ボタンを押すと、数秒後にAIの返答が現れます。読み込み中の表示や、うまくいかないときのエラーメッセージも付きます。
この記事は、準備から確認までを通して、VS CodeのOpenAI Codexに依頼文をコピペするだけで完成できる道案内です。APIキーは環境変数で安全に守り、Next.jsのRoute Handler（サーバールート）を通して呼び出します。
この回のゴール
- できること：Next.jsで最小のAIチャットUIを作り、質問を送って返答を画面で見られる。
- 用意するもの：パソコン、ブラウザ、VS Code、OpenAIアカウント（API利用可）、Node.js LTS。
- 大切な約束：APIキーはコードに直書きしない。環境変数で保存し、Route Handlerでサーバー経由にする。仕様や料金は変わるため公式ドキュメントで都度確認する。
最初に知っておきたい用語
- Next.js：Web画面とサーバーの処理をまとめて作れる道具。家（画面）と台所（サーバー）を同じ場所で用意できる感じ。
- Route Handler：Next.jsのサーバー側の受け口。手紙を受け取る郵便窓口のように、ブラウザからの依頼を受けて処理する。
- 環境変数：秘密のメモを金庫に入れておく方法。APIキーなどをコードに書かず、安全に読める場所。
- OpenAI API：文章を作るなどのAI機能を提供するサービス。質問を送ると返答の文章が返ってくる。
- VS Code：作業机のようなアプリ。ファイルを編集したり拡張機能でAIに手伝ってもらえる。
- OpenAI Codex：VS Code内でコード作成を助けるAIコーディングエージェント。依頼文を送ると必要なファイルを作ってくれる。
- fetch：ブラウザやサーバーから別の場所へ依頼を送る操作。おつかいに行って結果を持ち帰るイメージ。
- .env.local：開発中だけ手元で使う秘密メモ帳。APIキーなどを保存し、外へ公開されない。
1. この記事でできること
Next.jsで最小のAIチャットUIを作り、入力→送信→返答表示の往復を体験します。
VS CodeのOpenAI Codexに作業を任せ、私たちは指示文をコピペして進みます。
APIキーは環境変数で守り、ブラウザへ露出しない形にします。所要時間の目安は約60分です。
たとえると、質問は郵便ポスト、Route Handlerは郵便局、OpenAI APIは返事を書いてくれる人。迷子にならないように順路を作ります。
2. 完成イメージ
- 画面要素：テキスト入力欄、送信ボタン、メッセージ表示、送信中インジケーター、エラー表示。
- 1問1答の最小ループ。ページを更新すると履歴は消える簡易版。
完成後は、メモアプリのように一言入れて押すだけ。信号機のように「送信中→完了→失敗」を見分けられます。
3. 最初に知っておきたいこと
仕組みは「ポスト（フォーム）→配達員（fetch）→郵便局窓口（Route Handler）→手紙の返事（OpenAI APIのレスポンス）」です。
フォームは入力の受け皿、Route Handlerはサーバーの受け口、OpenAI APIは文章を作ります。
APIキーを守るため、キーはサーバー側だけで使います。机の引き出し（ブラウザ）に鍵を置かず、金庫（環境変数）にしまうイメージです。
4. 対象読者
- 中学生〜社会人の初学者。
- ReactやNext.jsに少し触れていると進みやすいですが、なくてもOK。
- WebでAI機能の入り口を作って体験したい人。
プラモデルを作るときの説明書のように、押す場所と確認ポイントを細かく示します。
5. 必要なものと入れ方
Node.js（LTS）
- これは何？：アプリを動かす土台。ゲーム機本体のように、ソフト（Next.js）が動くために必要です。
- 用意するもの：インターネット接続、管理者権限のあるPC。
- 入れ方・開き方：公式サイトを開き、LTS版を選んでダウンロード。表示の案内に従ってインストール。Windowsはインストーラーを実行、macOSは.pkgを開いて進めます。
- 最初の設定：特別な設定は不要。完了後にPCを再起動すると確実です。
- できたか確認：VS Codeのターミナルで「node -v」「npm -v」が表示されればOK。バージョンの数字が出れば成功です。
Visual Studio Code（VS Code）
- これは何？：作業机。ファイルを開いたり、AIの手伝い（拡張機能）を足せます。
- 用意するもの：PC、ネット、マウスとキーボード。
- 入れ方・開き方：公式サイトからダウンロード。Windowsはセットアップを進めて起動、macOSはアプリをApplicationsへ移動して起動。
- 最初の設定：日本語表示にしたい場合は「表示→コマンドパレット→言語」で切替可能。
- できたか確認：ウィンドウ左下に「管理」アイコン、左側にファイルや拡張機能のアイコンが見えればOK。
OpenAI Codex拡張（VS Code）
- これは何？：AIコーディングエージェント。大工さんに設計図を渡して作ってもらう感覚です。
- 用意するもの：OpenAIのアカウント（APIまたはChatGPTでサインインできるもの）。
- 入れ方・開き方：VS Code左側の四角い「拡張機能」アイコンを押す→検索欄に「Codex」と入力→OpenAIのCodex拡張を選ぶ→「インストール」を押す→完了後に拡張の「開く」を押す。
- 最初の設定：拡張の案内に従ってサインイン。成功するとCodexのチャット欄が開きます。
- できたか確認：「Codex」タイトルのチャット欄にメッセージ入力ボックスがあり、送信ボタンが押せれば準備OK。
Next.js（create-next-app）
- これは何？：Web画面とサーバーを一緒に作る道具箱。レゴの基本セットのように最初の形を作ってくれます。
- 用意するもの：Node.js LTS、ネット回線。
- 入れ方・開き方：この作業はCodexに任せます。私たちは依頼文を送るだけです。
- 最初の設定：プロジェクトのフォルダを開き、開発サーバーを起動します（Codexに依頼）。
- できたか確認：ブラウザで http://localhost:3000 が開き、Next.jsの初期ページが出ればOK。
前回の記事を読んでおらず、Codexを使った依頼の流れに不安がある人は、シリーズの前回「AIを読む人から使う人へ：中学生にも分かるSNS自動投稿パイプラインを作る #2」で、拡張の使い方を一度確認しておくと安心です。
6. エージェントと作るものの全体像
今回つくるフォルダとファイルの例です。Codexが自動で用意します。
- /app/page.tsx：画面の本体。入力欄、送信ボタン、表示エリアを持つ。
- /app/api/chat/route.ts：Route Handler。ブラウザからの依頼を受け、OpenAI APIへつなぐ。
- /.env.local：環境変数。OPENAI_API_KEYを保存。Gitには載せない。
データの流れは、入力→fetchで/api/chat→OpenAI API→返答→UI更新。
安全設計は、.env.localでキーを保存し、Route Handlerでのみキーを使います。財布（ブラウザ）に大金（キー）を入れず、家の金庫（サーバー）に置いて取りに行くイメージです。
7. 手順1: ツールを準備する
目的と全体の流れ
Node.jsとVS Code、Codexを使える状態にします。続いて、Codexに新規のNext.jsプロジェクト作成を依頼します。
読者がする画面操作
- VS Codeを開く→左の拡張機能アイコン→「Codex」を検索→OpenAIのCodex拡張をインストール→サインイン。
- VS Codeのスタート画面で「フォルダーを開く」から作業用の空フォルダを作成して開く。
Codexに送る内容
下のボックスはまだ送りません。まず起動確認まで完了してから次の手順で使います。
成功の見分け方
- Codexのチャット欄が使える。
- Node.jsのバージョンが表示される（node -v）。
つまづいたら
Codexのサインイン画面の指示を読み直し、ネットワークに接続されているか確認します。
8. 手順2: APIキーを安全に用意する
目的
OpenAIのAPIキーを発行し、.env.localへ保存します。APIキーは絶対にコードや画面に直書きしません。
読者がする画面操作
- OpenAIアカウントにサインインしてAPIキーを作成。
- VS Codeでプロジェクトを開いたあと、Codexに「.env.localを作成してOPENAI_API_KEYを保存する」作業を依頼します。実際のキーの文字列は、自分で貼り付けるタイミングだけで扱い、画面共有やスクリーンショットには映さないでください。
成功の見分け方
- プロジェクト直下に.env.localができている。
- .gitignoreに.env.localが含まれている。
つまづいたら
環境変数名のスペル（OPENAI_API_KEY）と、保存場所がプロジェクト直下かを確認します。
9. 手順3: エージェントにアプリを作ってもらう
目的
UI、Route Handler、状態管理、最小のスタイルをCodexにまとめて作ってもらいます。
読者がする画面操作
- VS CodeのCodexチャットを開く。
- 下のボックスを丸ごとコピーして、Codexへ貼り付けて送信。
このボックスをコピーして、VS Code内のCodexチャットに送ります。
Codexに送るプロンプト
目的：Next.js（App Router）で、最小のAIチャットUIを作ってください。ユーザーは1行の質問を入力→送信→返答を表示、の単発QAです。コードやコマンドは私に直接入力させず、必要な操作はあなたから提案し、ファイルの追加・修正はあなたが行ってください。
前提条件：
- プロジェクトはこのフォルダ内に作成してください（create-next-appを提案し、実行と初期起動まで誘導）。
- TypeScript・App Routerを使用。
- 依存関係の追加が必要な場合は提案し、理由を短く説明してから行ってください。
必要なファイル：
- app/page.tsx：入力欄・送信ボタン・メッセージ表示・送信中インジケーター・エラー表示。use client指定。fetchで/api/chatにPOSTする。送信中はボタン無効化。
- app/api/chat/route.ts：POSTのみ許可。サーバー側でOpenAI APIのテキスト生成（Chat Completions等、公式ガイドにある方法）を呼び出し、返答テキストだけをJSONで返す。環境変数OPENAI_API_KEYはサーバー側のみで読み取り、キーの未設定時は400系で明示的なエラーJSONを返す。
- .env.local：OPENAI_API_KEY=（値は私が入れます）。.gitignoreで保護。READMEに「APIキーはコードに書かない」と注意書きを入れる。
安全なAPIキー管理：
- APIキーは.env.localに保存。クライアント側コードには絶対に露出させない。Route Handler内でprocess.envから読む。
UI要件：
- 1行テキスト入力と「送信」ボタン。返答表示領域。エラー時は赤い小さなメッセージ。
- 送信中はスピナーや「考え中...」を表示。
- シンプルなCSS（インラインまたはモジュール）で最小限の余白・幅・フォント調整。
動作確認：
- npm run devでhttp://localhost:3000を開くとフォームが表示される。
- 「テスト」と送るとAPI経由で返答が表示される。
- ブラウザの開発者ツールのNetworkで/api/chatが200で返り、JSONにtextフィールドがある。
分からないとき：
- 途中で情報が不足したら私に質問してください。選択肢がある場合は2〜3案を理由付きで提案してから実施してください。Codexが作るものと、確認ポイント
- app/page.tsxに、入力・送信・表示・読み込み・エラーがそろっていること。
- app/api/chat/route.tsに、POST処理と環境変数の読み出し、エラーハンドリングがあること。
- .env.localが作成され、READMEに注意書きがあること。
10. 手順4: 動かして確認する
目的
ローカルで開発サーバーを起動し、実際に質問を送り、返答が表示されるか確かめます。
読者がする画面操作
- Codexに「開発サーバーを起動して、ブラウザを開いてください。起動方法も案内してください。」と依頼。
- ブラウザで http://localhost:3000 を開く。
- 入力欄に短い質問を書き、送信ボタンを押す。
成功の見分け方
- 数秒後に返答テキストが表示される。
- 送信中はボタンが無効になり、「考え中…」などの表示が出る。
- ブラウザの開発者ツール→Network→/api/chat が200で成功し、レスポンスJSONにtextがある。
つまづいたら
画面でエラー表示が出たら、Networkタブのステータスコードとレスポンス本文を確認。Codexに状況を伝えて修正を依頼します。
11. 手順5: エージェントと直す
目的
細かな使い心地や見た目を、Codexへの依頼で素早く調整します。料理の味見をして塩加減を直す感じです。
読者がする画面操作
- Codexに、送信中のボタン無効化や、エラー文の日本語化、余白や幅の微調整を依頼。
- タイムアウトやネットワーク失敗時に「もう一度試す」ボタンを表示する改善を依頼。
依頼例
「エラー時に『通信に失敗しました。数分後に再度お試しください』と表示してください。再送ボタンを付けて、直前の入力を保持してください。」
成功の見分け方
- 失敗時の表示が短くわかりやすい。
- 送信中は二重送信が起きない。
- 全体の余白が整い、スマホ幅でも崩れない。
12. よくあるエラー
-
画面で見えること：/api/chat が401や403、レスポンスに「invalid api key」。
よくある原因：OPENAI_API_KEY未設定、スペルミス。
最初に確認：.env.localのキー名・値、Next.jsの再起動。
Codexに送る質問：「.env.localの読み込みとRoute Handlerでのprocess.env参照を再確認し、未設定時は400系エラーJSONを返すように点検してください。」 -
画面で見えること：ブラウザのコンソールに「Failed to fetch」やNetworkで500。
よくある原因：Route Handlerのメソッド不一致、エラー未処理、依存関係不足。
最初に確認：/app/api/chat/route.tsがPOSTを実装しているか、try/catchと適切なstatusがあるか。
Codexに送る質問：「/api/chatのPOST実装を再点検し、エラー時に原因をJSONのmessageに含め、500を返すよう修正してください。」 -
画面で見えること：クライアント側のコードにAPIキーが見える、あるいはビルド時に公開変数として出ている。
よくある原因：クライアントで環境変数を参照、NEXT_PUBLICでキーを設定。
最初に確認：キーがサーバー側のみで参照されているか、NEXT_PUBLIC_を付けていないか。
Codexに送る質問：「クライアントコードからキー参照をすべて除去し、Route Handler経由でのみ呼ぶ設計に戻してください。セキュリティ上の注意もREADMEに追記してください。」 -
画面で見えること：「Too Many Requests」や429。
よくある原因：レート制限。
最初に確認：一定時間待つ、再送間隔を伸ばす。
Codexに送る質問：「429時は数秒待ってから再試行するバックオフ処理と、ユーザー向けの待機メッセージを追加してください。」
13. 次に試すこと
- メッセージ履歴を保持して、会話をつなげる。
- OpenAI APIのストリーミングで、入力中のように文字が流れる表示。
- 簡単なスタイルフレームワーク（例：CSS Modulesや軽量UI）を導入。
商店の黒板に書くメニューを増やすように、少しずつ機能を足しましょう。変更のたびに公式ドキュメントで仕様を確認します（料金・制限は変わることがあります）。
14. まとめ
最小のNext.js製AIチャットUIを、Codexへの依頼だけで形にしました。
サーバー経由と環境変数の管理を押さえたので、次の拡張に備えられます。
Route Handler、環境変数、OpenAI APIの基本は、公式ドキュメントで最新の仕様を確認してください。
この続きでは、会話の履歴やストリーミングなど、使い心地を高める工夫に進みます。
参考：公式ドキュメント
- Next.js documentation：App Router、Route Handlers、環境変数、デプロイ。
- OpenAI API Quickstart：導入、SDK、キーの設定、基本的な呼び出し。
- OpenAI API Text generation：テキスト生成のガイド、モデル選択、リクエスト、ストリーミング。
