完成すると、画面に「資料を登録」「登録状態」「質問欄」「回答欄」「参照元」の5つが並びます。AIはまず資料を探し、見つかった内容を根拠として答え、参照元のファイル名を示します。
この第1回では、VS CodeとOpenAI Codexの準備、OpenAI PlatformのAPIキーを安全に扱う考え方、サンプル資料での練習方針、最小構成の完成イメージ、確認のしかたまでを丁寧に進めます。
この回のゴール
- できること：VS CodeでOpenAI Codexを使う準備を整え、RAG（File Search）型アプリの完成形と安全なサンプル資料の使い方を理解する。
- 用意するもの：PC、インターネット、ブラウザ、VS Code、OpenAIアカウント、OpenAI Codex拡張、Node.js。
- 大切な約束：APIキーはサーバー側の環境変数で管理し、個人情報や社内資料は練習に使わない。料金や仕様は変わるため、公式ドキュメントで常に確認する。
最初に知っておきたい用語
- RAG：質問に関係する資料を先に探し、その内容を基にAIが答える仕組み。
- File Search：OpenAIの検索ツール。登録したファイルを意味で探し、回答に参照元を添えられる。
- ベクトルストア：資料を意味で探せるように整理して置く保管場所のこと。
- APIキー：サービスを機械から安全に使うための秘密の鍵。人に見せない。
- 環境変数：アプリが設定を読む引き出しのような場所。APIキーをここに隠す。
- VS Code：プログラムを書く作業机のアプリ。拡張機能で機能を増やせる。
- OpenAI Codex：VS Code内でコード作成を手伝うAIコーディングエージェント。
- Responses API：OpenAIのAI回答を得るAPI。File Searchと一緒に使える。
1. この記事でできること
この回では、RAG（Retrieval-Augmented Generation）という「先に探してから答える」考え方を、手を動かす準備と一緒に身につけます。
ゴールは、VS CodeでOpenAI Codexが動き、OpenAI PlatformのAPIキーを安全に扱う準備ができ、最小のRAGアプリの完成形を具体的に思い描けることです。
たとえば、料理を始める前に台所を整え、材料を並べ、火加減のルールを知る段階にあたります。ここを丁寧にすると、このあとがスムーズです。
2. 完成イメージ
- 画面に並ぶ5要素：資料登録、登録状態、質問、回答、参照元。
- 流れ：ファイルを登録 → AIが関連部分を検索 → 回答を表示 → 使われたファイル名を参照元に表示。
- この回ではUIモック（見た目）と安全なサンプル資料で動線を確認。API連携は次回以降に深めます。
- 参照元はAPIが返す「ファイル名」をそのまま表示。ページ番号など不明な情報は作らない。
イメージは、学校の図書室の掲示板のようなシンプルさ。必要な場所だけが並び、何をすればいいか迷いません。
3. 最初に知っておきたいこと
RAGは「図書館の係が、まず質問に合うページを探し、そのページを見ながら案内する」に似ています。
技術的には、ファイルをベクトルストアに登録し、質問の意味に近い部分を探し（File Search）、見つけた内容を根拠にResponses APIで答えを作ります。
File Searchは意味検索やキーワード検索を活用できますが、常に正しい答えを保証する機能ではありません。資料に無いことは「登録した資料の中では確認できません」と返す動きが大切です。
モデル名、対応ファイル、上限、料金は変わる可能性があります。必ずOpenAI File Search guideとOpenAI API Quickstartの最新情報を確認してください。
4. 対象読者
- 中学生〜社会人までの初心者。
- 自分のPDFやメモに質問したい人。
- 会社データを触る前に、安全なやり方で練習したい人。
自転車の補助輪のように、まずは安全なサンプル資料だけで走り方を覚えます。
5. 必要なものと入れ方
VS Code
- これは何？：ノートと道具が一体になった作業机。コードを書いたり整理したりできます。
- 用意するもの：PC、インターネット、ブラウザ。
- 入れ方・開き方：
1) 公式のVisual Studio Code setupを開く。
2) OSに合ったダウンロードを押す。
3) インストーラーの案内に従って入れる。
4) アプリを起動する。 - 最初の設定：左下の歯車→設定で表示言語やテーマを好みに合わせる。
- できたか確認：「Welcome」や「Get Started」が表示され、上部にメニュー（File/Editなど）が見えればOK。
OpenAI Codex（VS Code拡張）
- これは何？：となりで相談に乗る「コードの家庭教師」。頼むと設計や修正を手伝ってくれます。
- 用意するもの：VS Code、インターネット、OpenAIのサインイン手段（ChatGPTアカウントまたはOpenAI APIキー）。
- 入れ方・開き方：
1) VS Code左の四角いアイコン（Extensions）を押す。
2) 検索欄に「Codex」と入力。
3) OpenAIのCodex拡張を選ぶ。
4) Install（インストール）を押す。
5) 画面の案内でサインインする。
6) 左側にCodexのチャット欄が出るか、ステータスが有効になるのを確認する。 - 最初の設定：新しい作業フォルダをVS Codeで開き、Codexがそのフォルダを扱えるようにする。
- できたか確認：Codexのチャットに短い文を送れ、返信が表示されたら成功。
OpenAI Platform（API利用）
- これは何？：AIの「受付カウンター」。APIキーの発行や利用状況の確認を行います。
- 用意するもの：OpenAIのアカウントとブラウザ。
- 入れ方・開き方：
1) OpenAI API Quickstartを開き、手順のリンクからPlatformに進む。
2) アカウントでサインインする。 - 最初の設定：利用プランや支払い方法の設定が必要な場合は画面に従う。料金や制限は変わるため、その都度公式で確認する。
- できたか確認：ダッシュボードに入り、APIキー発行や使用量の画面に進めればOK。
Node.js
- これは何？：Webアプリの下で動く「エンジン」。サーバーの処理を担当します。
- 用意するもの：PC、インターネット、インストール権限。
- 入れ方・開き方：
1) VS Codeのセットアップページからリンクをたどるか、公式サイト経由でLTS版を入れる。
2) インストーラーの案内に従い完了する。WindowsとmacOSで手順が少し異なるが、基本は画面の「Next」や「続ける」に従う。 - 最初の設定：特に不要。VS Codeで作業フォルダを作れば準備OK。
- できたか確認：VS Codeの「ターミナル」メニューを開けることを確認。バージョン表示は次回以降Codexに代わりに確認してもらいます。
6. エージェントと作るものの全体像
最小構成のフォルダ例は、家の間取り図のようなものです。どこに何を置くかを決めると迷いません。
方針：
– クライアント（画面）とサーバー（裏方）を分ける。
– APIキーはサーバーだけが読む.envに保管し、Gitに載せない。
– OpenAIのFile Searchを使い、ベクトルストアに安全なサンプル資料だけを登録する。
– Responses APIからの回答に参照元（ファイル名）を添えて表示する。
ここで扱うのは動線と安全設計の原則です。細かなコードは次回以降、Codexに依頼して書いてもらいます。
7. 手順1: ツールを準備する
目的と理由
この手順では、VS CodeとCodexが使える作業机を整えます。机が片付いていると、後の作業が早くなります。
画面の操作
- VS Codeを起動し、「Open Folder」で作業用の空フォルダ（例：my-file-search）を作って開く。
- 左の拡張機能から「Codex」を検索し、OpenAIのCodex拡張をインストール。
- 案内に従ってサインインし、Codexのチャット欄を開く。
Codexに頼むこと
この回ではコード入力は行いません。後の手順でCodexにまとめて依頼します。
成功の見分け方
- VS Code左側にCodexのチャットが表示され、短い質問に応答が返ってくる。
- 作業フォルダ名がVS Codeの上部に表示されている。
次に進む前の確認
Codexの返信が見えること、作業フォルダが空であることを確認します。
8. 手順2: APIキーを安全に用意する
目的と理由
APIキーは金庫の鍵にあたります。画面やコードに直接書くと、うっかり見えてしまうことがあります。.envという秘密のメモにしまい、アプリからは環境変数として読みます。
画面の操作（概要）
- ブラウザでOpenAI API Quickstartを開き、案内に従ってOpenAI Platformに進む。
- サインイン後、APIキーの発行画面に進む。料金や制限は変更される可能性があるため、画面の説明をよく読む。
- 発行したキーは画面に一度だけ表示されることが多いので、その場で安全に保存する。この記事では値を貼らず、次回以降、Codexが
.envに保存する手順を案内します。
なぜ直書きしないか
鍵を玄関に貼り付けないのと同じです。
APIキーは、.envに保管し、.gitignoreで除外し、サーバー側だけが読む。ブラウザへ送らない。この4点を守ります。
成功の見分け方
PlatformでAPIキーを発行でき、保管場所を決めたら準備完了です。
9. 手順3: エージェントにアプリを作ってもらう
目的と理由
ここから、OpenAI Codexに具体的な依頼を送り、最小のRAG File Searchアプリの雛形を作ってもらいます。あなたは設計書を渡す役です。
画面の操作
- VS Codeで作業フォルダを開いたまま、Codexのチャット欄を開く。
- 下のボックスを丸ごとコピーして、チャットに貼り付けて送る。
このボックスをコピーして、VS Code内のCodexチャットに送ります。
Codexに送るプロンプト
あなたはVS Code内で動くOpenAI Codexです。初心者向けの最小RAG（File Search）型「自分の資料に答えるAI検索」Webアプリの雛形を、このフォルダに作ってください。条件は必ず守ってください。
【作るもの（最小構成）】
- ブラウザ画面：以下の5要素だけを縦に並べたシンプルなUIモック（HTML/CSS/最小のフロントJS）。
1) 資料を登録する場所（後で有効にするアップロード欄のダミー）
2) 登録状態（「まだ未連携」の表示）
3) 質問入力欄（テキスト）
4) 回答欄（テキスト）
5) 参照元（ファイル名のリスト領域）
- サーバー（Node.js/Express）：/health だけ応答する仮API。Responses APIとFile Searchの実装は次回以降に差し込む前提で、構成を整える。
- プロジェクト設定：package.json、npm scripts（dev/start）、.gitignore、READMEを用意。
【OpenAIの使い方に関する方針】
- OpenAI Responses APIとFile Searchを使う前提のフォルダ構成にし、実装箇所はコメントで明確化。
- APIキーは環境変数（.env）からのみ読む。HTMLやクライアントJSにキーやベクトルストアIDを出さない。
- .env.sample を作成し、実値は書かない。READMEに安全な保存方法を短く説明。
【安全なサンプル資料】
- 実在の個人情報や社内データ、有料コンテンツは使わない。
- READMEに「Codexが生成した架空の短文テキスト（例：学校行事の案内や空想クラブ規約）」を練習に使う指示を書き、/samples フォルダにダミーTXTを自動生成するスクリプトまたは初期ファイルを用意。
【依存とコマンド】
- 使用技術：Node.js、Express、dotenv、（将来）OpenAI公式SDK。
- npm install などのコマンド実行は、初心者が自分で打たなくてよいよう、必要ならVS CodeのタスクやREADMEの「Codexに依頼する言い方」を用意。
【確認方法】
- 起動：npm run dev でローカルサーバーが立ち上がる想定（ポート番号は.envに PORT として設定、READMEで説明）。
- ブラウザでUIが表示され、5要素が見えること。
- /health にアクセスすると {status:"ok"} を返すこと。
【質問と段取り】
- 不明点があれば作業前に質問してください。初心者が迷わないように、作成後は画面で何を押して何が見えれば成功かをREADMEに具体的に書いてください。
- 既存ファイルを壊さないでください。上書きが必要なら事前に理由を説明してから行ってください。Codexが作るものと確認ポイント
- UIモックに5要素が並ぶ。
- .env.sample と .gitignore があり、実値は空欄のまま。
- /health が {status:”ok”} を返す。
- samples フォルダに安全なダミー資料が入る（または生成手順がREADMEにある）。
10. 手順4: 動かして確認する
目的と理由
雛形が動くか、画面とサーバーの入口が正しく作られたかを確かめます。家のカギが回るか、ドアが開くかの点検です。
画面の操作
- Codexの指示にしたがって、npm scriptsからローカルサーバーを起動。
- ブラウザで表示されたUIに、5要素が並んでいるか確認。
- ブラウザの別タブで /health にアクセスし、{status:”ok”} が見えるか確認。
成功の見分け方
- 画面の各欄に仮のラベルが表示される。
- 参照元の欄が空欄でも、枠が確認できる。
- エラー表示が出ず、/health が応答する。
次に進む前の確認
READMEの手順で迷わなかったか、分かりにくいラベルがあればメモします。次の手順でCodexに改善を依頼します。
11. 手順5: エージェントと直す
目的と理由
小さな違和感を早めに直し、次回のAPI連携に備えます。靴ひもをしっかり結ぶイメージです。
画面の操作
- Codexのチャットに、気づいた点（ラベル名、説明文、色のコントラストなど）を箇条書きで伝える。
- 起動時のメッセージやREADMEの言い回しを、初心者向けにやさしくしてもらう。
Codexに送る内容の例
「参照元」の説明に「回答の根拠に使ったファイル名を表示」と追記してください、など具体的に伝えます。
成功の見分け方
- UIのラベルや説明が分かりやすくなる。
- READMEの手順が、画面で何を押すかまで具体的になる。
12. よくあるエラー
APIキー未読込
- 画面で見えること：サーバー起動時に「API key not found」などのメッセージ。
- よくある原因：.envが未作成、環境変数名のスペル違い、dotenv未設定。
- 最初に確認する場所：.env.sample と README。.gitignore に .env が含まれているか。
- Codexへの質問：このログを貼り「.envの読込を確認し、足りない設定を教えて。ブラウザにはキーを出さないで。」
バージョン違い
- 画面で見えること：依存関係の警告や起動失敗。
- よくある原因：Node.jsの古い/新しい版との不整合。
- 最初に確認する場所：READMEの対応バージョン。Codexに現在の環境を確認してもらう。
- Codexへの質問：「このエラーに合うNode.js LTS版に合わせて依存を調整して。何を押せば更新できるか案内して。」
CORS/ポート競合
- 画面で見えること：ブラウザで読み込みエラー、サーバー起動時に「port already in use」。
- よくある原因：他アプリが同じポートを使用、CORS設定不足。
- 最初に確認する場所：.env の PORT、サーバー起動ログ。
- Codexへの質問：「競合しないポートに変更して、CORSを開発用に最小で許可する設定を追加して。」
レート制限
- 画面で見えること：API応答が429エラー。
- よくある原因：短時間の連続リクエスト。
- 最初に確認する場所：Platformの使用量画面。
- Codexへの質問：「指数バックオフのリトライをサーバー側に実装して。失敗時は丁寧な日本語エラーメッセージを返して。」
料金やモデル、制限は変動します。常にFile Search guideとAPI Quickstartで最新を確認してください。
13. 次に試すこと
- PDFアップロード対応（サイズや拡張子の制限をサーバー側で実装）。
- 複数ファイルの登録とタグ付け。
- 簡易キャッシュ（同じ質問の再回答を短縮）。
14. まとめ
第1回では、RAG（先に探してから答える）の考え方、安全なAPIキー管理、VS CodeとCodexの準備、最小UIの完成イメージを固めました。
次回以降、Responses APIとFile Searchをサーバーに組み込み、参照元（ファイル名）を表示しながら答える流れを作ります。料金や仕様は変わるため、都度公式ドキュメントで確認しながら進めましょう。
