完成後は、小さなチャットUIに「通常/切り替え中/待機/エラー(再試行可)」の状態が表示され、開発モードでだけ疑似5xxや疑似タイムアウトを入れて、Claudeのバックアップモデルへの切り替え(Auto)を確認できます。
準備からVS CodeでのCodex利用、疑似障害の注入、動作確認、エラー時の見方までを一気通貫で扱います。
この回のゴール
- できること：疑似エラーでAutoの切り替えを安全に検証し、利用者向けの状態表示とエラー案内をUIに追加する。
- 用意するもの：VS Code、OpenAI Codex拡張、Claude APIアカウントとAPIキー、ブラウザ。
- 大切な約束：APIキーを画面やコード例に書かない。疑似障害は開発中だけ有効。本番では自動切り替え対象を5xx/短いタイムアウトに限定する。
最初に知っておきたい用語
- Claude API：文章を送ると返事をくれるAIの入り口。アプリの「頭脳」役。
- OpenAI Codex：VS Code内でコードを書いてくれるAIの相棒。アプリを作る「手伝い」役。
- stop_reason：Claudeの返答がどの理由で止まったかを示す印。続ける/やめる/別ルートを決める材料。
- フェイルオーバー：主役が動かないときに代役へ切り替えること。電球が切れたら予備に替えるイメージ。
- 疑似エラー：本物の事故を起こさずに、わざと失敗を装う仕組み。テスト用の消しゴム判子のようなもの。
- 環境変数：秘密の設定を隠して入れておく箱。コードや画面に出さないための方法。
- Auto：利用者が「自動」を選ぶと、短時間で応答しない/5xxのときだけ予備モデルへ1回切り替える動作。
1. この記事でできること
今回は、実障害を起こさずに「自動切り替え(Auto)」が正しく働くかを安全に試します。
たとえば、交通訓練用の模擬コースのように、本物の道路を止めずに練習します。
- 疑似エラーでモデル自動切り替え(Auto)の動作確認
- 画面に安全な状態表示・エラー案内を追加
- Auto以外の選択時は自動切り替えしないことを検証
2. 完成イメージ
- 小さなチャットUIに「通常/切り替え中/待機/エラー(再試行可)」などのラベル表示
- 開発モードでのみ疑似5xx/疑似タイムアウトを注入し、バックアップモデルへ切替
- 画面やログにAPIキー/詳細エラー/内部IDは表示しない
3. 最初に知っておきたいこと
信号で「黄→赤」になったら安全に止まるように、アプリも危ないときは落ち着いて止まり、短い案内を出す必要があります。
ここで大事なのがClaudeのstop_reasonです。これは「どんな理由で返答を終えたか」の札で、続ける/やめる/再試行/フォールバック(予備へ切り替え)を決める材料になります。
これを見ないと、例えるなら先生の「今日はここまで」を聞き逃してノートを書き続けるようなものです。
なぜ必要か。
本番の事故を避けつつ、ユーザー体験と信頼性の両立をねらうためです。適切に止まり、必要なら控え選手へ交代します。
4. 対象読者
- 中学生でも分かる説明で進めたい初学者
- 実障害を起こさず動作検証したい人
- VS CodeとCodexで最小構成から始めたい人
5. 必要なものと入れ方
まず役割をはっきり分けます。
Claude APIは完成するアプリの頭脳。
OpenAI Codexは、そのアプリを作る手伝いです。家庭科の授業で、レシピ(設計)は自分が決め、手伝いの人に切ったり混ぜたりをお願いするイメージです。
VS Code
- これは何？：ノートのようにファイルを並べて編集できる作業机。
- 用意するもの：インターネット、PC、メールで使えるアカウント。
- 入れ方・開き方：公式サイトからインストーラーを取得し、案内に従って入れ、アプリを開きます。Windowsは.exe、macOSは.dmgを開きます。
- 最初の設定：左の人型アイコンからサインインを行い、同期を有効にします。
- できたか確認：左下に自分のアカウント名が表示されます。
OpenAI Codex拡張
- これは何？：VS Code内で「こうして」と頼むとコードを提案する相棒。
- 用意するもの：OpenAIのアカウント、またはAPIキー。
- 入れ方・開き方：左の四角いアイコン(拡張機能)を押し、検索欄に「Codex」と入力。OpenAIのCodex拡張を選んで「インストール」。完了後、サイドバーのCodexアイコンを押してチャットを開きます。
- 最初の設定：拡張の案内に従ってサインイン。チャット欄に「こんにちは」と送って応答を確認。
- できたか確認：エディタ右側にCodexのチャットが開き、メッセージが往復します。公式ドキュメントはOpenAI Codex documentationで確認できます。
Anthropic Console(Claude API)
- これは何？：Claudeを使うための管理画面。鍵(APIキー)を発行します。
- 用意するもの：Anthropicのアカウント、支払い方法(必要な地域・プランに応じて)。
- 入れ方・開き方：ブラウザでAnthropic Consoleを開き、サインインしてAPIキーを作成します。
- 最初の設定：どのモデルが使えるかをコンソールと公式情報で確認します。最新の候補はIntro to Claudeを参照。
- できたか確認：キーが表示されますが、ここでは画面に見せるだけ。実値はどこにも貼り付けません。
Node.js(今回必要な道具)
- これは何？：サーバーを動かすためのエンジン。料理でいうコンロ。
- 用意するもの：公式サイトからインストーラーを取得できるPC。
- 入れ方・開き方：公式サイトからLTS版をダウンロードしてインストール。アプリ一覧にNode.jsが追加されます。
- 最初の設定：今回の作業フォルダをVS Codeで開き、Codexに初期セットアップを依頼します。
- できたか確認：後の手順で、Codexが作ったサーバーが起動し、ブラウザでUIが開けます。
6. エージェントと作るものの全体像
家づくりで、まず間取り図を確認するように、作る部品の関係を先に決めます。
- フロント：最小のチャットUI(入力欄・送信ボタン・状態ラベル)
- バックエンド：Claude API呼び出しと状態管理
- 切り替え戦略：メイン→バックアップ(失敗時のみ)。Auto以外は切り替えなし
- 疑似障害：開発モードだけで5xx/タイムアウトを注入。環境変数でON/OFF
- 画面表示：選んだモード(「Auto/速さ重視/品質重視」)、実際に応答したモデルの表示名、切替が起きたときだけ短い理由
- 非表示：APIキー、内部のモデルID、詳細なスタックやリクエストID
7. 手順1: ツールを準備する
目的と全体の流れ
ここでは開発机(VS Code)と手伝い役(Codex)、頭脳(Claude)の3者をつなぎます。作業は画面操作とCodexへの依頼だけで進めます。
読者がする操作
- VS Codeを開く→拡張機能→「Codex」を検索→OpenAI Codex拡張をインストール→サインイン→チャットを開く
- Anthropic Consoleにサインインし、利用可能なモデル候補を確認
成功の見分け方
- CodexのチャットがVS Codeに表示され、やりとりできる
- Anthropic ConsoleでAPIキーの管理画面が見える(実値はコピーしない)
8. 手順2: APIキーを安全に用意する
なぜ必要か
環境変数は、金庫に鍵をしまうイメージ。画面やコードに生の鍵を出さないために使います。
読者がする操作
- VS Codeで作業フォルダを開く
- Codexのチャットに「APIキーを.envで安全に読む仕組みを用意して」と依頼
成功の見分け方
- プロジェクトに.env.sampleがあり、.gitignoreに.envが含まれている
- サーバー起動時に「APIキー未設定」のような安全な案内が出る(キーの実値は表示しない)
9. 手順3: エージェントにアプリを作ってもらう
このボックスをコピーして、VS Code内のCodexチャットに送ります。
Codexに送るプロンプト
目的：前回までの小さなWebアプリを壊さずに、第5回の機能を追加してください。Claude APIはアプリの頭脳、あなた(Codex)は実装の手伝いです。私はコードやコマンドを手入力しません。
作るもの：
- 最小のチャットUIに「通常/切り替え中/待機/エラー(再試行可)」の状態ラベルを追加。
- サーバー側でClaude API呼び出しを行い、stop_reasonを見て挙動を分岐。
- 切り替え戦略：「Auto」のときだけ、(1)短いタイムアウト未応答、(2)HTTP 5xx のときに限り、バックアップモデルへ1回だけフォールバック。2回目以降は停止して安全なエラー表示に。
- 「速さ重視」「品質重視」選択時は、どんな失敗でも別モデルへは自動切り替えない。
- 画面には「選択肢(モード)/実際に回答したモデルの表示名/切り替えが起きた場合だけ短い理由」を表示。APIキー、内部のモデルID、リクエストID、詳細エラーは一切表示しない。
疑似障害(開発モード限定)：
- 環境変数(例：APP_ENV=development)のときだけ有効。
- サーバーに、(A)疑似5xx、(B)疑似タイムアウトを注入できるトグルを実装。UIからも分かるように簡単なスイッチかクエリで切替可能に。
- 本番(APP_ENV=production)では常に無効。
安全なキー管理：
- .envからサーバーだけがAPIキーを読み、.gitignoreに.envを含める。
- .env.sampleを用意し、必要なキー名のみ記載。実値は書かない。
- ログや画面にキーや詳細エラーを出さない。
必要なファイル：
- サーバー(例：Node/Express)のエントリ、Claude呼び出しモジュール、状態管理、フロントのHTML/CSS/JS、.env.sample、README(動かし方)。
stop_reasonの扱い：
- ClaudeのMessages API応答で、stop_reasonに従って「採用/続行/再試行/フォールバック/中断」を分岐。
- 参考：Anthropic公式「Handling stop reasons」。拒否や安全上の中断は自動切替の対象外とし、ユーザーに短い案内を表示。
動作確認：
- 通常：メインモデルで応答→ラベル「通常」。
- 疑似5xx：Auto選択時のみバックアップへ切替→「切り替え中→通常」に戻る。
- 疑似タイムアウト：一定時間を超えたら1回だけ再試行かフォールバック→状態に反映。
- Auto以外：疑似障害でも切替しない。
質問：
- 取りかかる前に、前回までの構成(ファイル名/起動方法)を私に質問してください。不明点は作業前に確認してください。
- 途中で不明点があれば必ず質問してから進めてください。Codexが作るものと、あなたが確認する点
- UIに状態ラベルが増え、送信中は「待機」、フォールバック時は「切り替え中」が出る
- サーバーに疑似5xx/疑似タイムアウトの注入スイッチがあり、開発モードだけ効く
- .env.sampleと.gitignoreがあり、画面やログにキーや詳細エラーが出ない
10. 手順4: 動かして確認する
通常時
目的：平常運転を確かめます。
操作：Codexの案内でサーバーを起動→ブラウザでUIを開く→モード「Auto」で送信。
成功：状態「待機→通常」、応答の下に実際に使ったモデルの「表示名」だけが出る。
疑似5xx
目的：一時的なサーバー障害の切替を確認。
操作：開発モードで疑似5xxをON→Autoで送信。
成功：「待機→切り替え中→通常」。理由に短く「一時的なエラーにより予備を使用」と表示。
疑似タイムアウト
目的：応答遅延での再試行/フォールバックを確認。
操作：疑似タイムアウトをON→Autoで送信。
成功：「待機→切り替え中/再試行→通常」。2回目以降は停止し、短い案内で終わる。
Auto以外
目的：「速さ重視」「品質重視」を選んだときに勝手に切替しないことを確認。
操作：同じ疑似障害をONにして送信。
成功：切替は起きず、分かるエラー表示で止まる。
11. 手順5: エージェントと直す
UI文言と配色
目的：読みやすさの改善。Codexに、色弱に配慮した配色と短い文言提案を依頼します。
ログ最小化とPII排除
目的：個人情報を残さない。Codexに「ユーザー入力を原文で保存しない」設定の見直しを依頼。
再試行ポリシー
目的：待ち時間と回数の調整。Codexに「最大1回/待機表示を明確に」の条件で調整を依頼。
12. よくあるエラー
APIキー未設定/読み込み失敗
- 画面で見えること：常に「エラー(再試行可)」になり、応答がこない。
- よくある原因：.envに値がない、サーバーが.envを読んでいない。
- 最初に確認：.env.sampleの項目、.gitignoreに.envがあるか、起動ログの「キー未設定」警告。
- Codexへの質問：「.envの読み込みとキー存在チェックをもう一度見直して。画面やログにキーを出さないまま原因を特定して」。
stop_reason未考慮で誤判定
- 画面で見えること：拒否や安全上の中断でもフォールバックしてしまう。
- よくある原因：stop_reasonの分岐不足。
- 最初に確認：Claude呼び出し部の分岐。参考：Handling stop reasons。
- Codexへの質問：「stop_reasonごとの分岐を、拒否/ツール/トランケーション/フォールバック/通常終了で正しく実装して」。
疑似障害が本番で有効のまま
- 画面で見えること：本番で頻繁に切替やエラーが出る。
- よくある原因：APP_ENVの判定ミス、フラグの初期値がON。
- 最初に確認：設定ファイルの環境判定とデプロイ時の環境変数。
- Codexへの質問：「APP_ENVがproductionのときは疑似障害ロジックを完全に無効化して。テスト用UIも隠して」。
CORS/ポート衝突/依存不整合
- 画面で見えること：UIが開かない/送信が失敗。
- よくある原因：同じポートを別アプリが使用、CORS設定漏れ、依存のバージョン違い。
- 最初に確認：サーバーの起動ポート、CORSミドルウェア、パッケージ一覧。
- Codexへの質問：「起動ポートを変更し、CORSと依存関係を自動で整えて。互換範囲を保ったまま更新して」。
自動切替の対象外エラーなのに切替を期待してしまう
- 画面で見えること：401/403/400/料金不足/モデル名不正でも切替されない。
- たとえ：宛先が間違った郵便物は、別の配達員に渡しても届かない。
- 技術的理由：認証・権限・入力不備・存在しないモデルは、別モデルに替えても解決しないため。
- Codexへの質問：「対象外エラーのときは、どこを直せばよいか短い案内をUIに出す実装を強化して」。
13. 次に試すこと
- 段階的バックオフと回数制限
- ユーザー可視のステータス履歴
- A/Bで切替しきい値を調整
14. まとめ
疑似障害で安全に検証し、ユーザーには必要十分な状態だけを見せる。
stop_reasonに基づく分岐で堅牢化し、Auto/手動の切替を明確にしました。
シリーズの前回は中学生にも分かるAIモデル自動切り替え機能の作り方 #4です。必要な準備がまだの人は先に確認してください。
