本文へ移動
BenriWorks LabBenriWorks トップ

ガイド更新日

Codexが止まったときの、原因の探し方

この記事で分かること

Codex 集中講座の第16回。「起動しない」「依頼が進まない」「本番で動かない」を切り分けます。診断、検査のログ、実際の画面から、次に調べる場所を絞ります。

エラーの出た画面とメモを見比べながら、こちらを向いている女性の開発者
目次 読みたいところから

Codexが動かない、という一言でも、原因を探す場所は違います。起動する前なのか、依頼を実行する途中なのか、公開した画面なのか。まず、どこまで進んだかを確かめます。

道具、実行、結果、検査環境、画面の5つに分けて調べます。試したことと出力を残すと、直らなかった場合にも次の確認先を選べます。

症状ではなく、層で切り分ける

エラーの文面から原因を当てにいくと、当たるまで探し続けることになります。当たらないうちは、何も進みません。

代わりに、下から順に「ここまでは正しい」を確かめます。層は5つです。

切り分けの5つの層を下から積み上げた図。道具が動くか、依頼が届くか、出てきたものが合っているか、他の環境でも通るか、実際の画面で正しいかの順に並び、下の層から確かめることが示されている
下から確かめる。上の層の調査は、下が正しいと分かってから
  1. 道具が動いているか
  2. 依頼が届いて、実行できているか
  3. 出てきたものが、頼んだものと合っているか
  4. 他の環境でも通るか
  5. 実際の画面で正しく動いているか

上の層の症状に見えても、原因が下の層にあることは珍しくありません。だから下から確かめます。

層1: 道具が動いているか

Codex そのものが動いていない場合です。ここには専用の道具があります。

codex doctor

第2回で載せた出力を、もう一度引きます。執筆環境で実行した実物です。

Notes
   ✗ auth         no Codex credentials were found - Run codex login or provide an API key ...
   ⚠ updates      update configuration is locally consistent
   ⚠ websocket    Responses WebSocket failed; HTTPS fallback may still work - ...
   ✗ reachability one or more required provider endpoints are unreachable over HTTP - ...

認証、通信、ディスク、Git の検出が並びます。ここに印が付いているなら、上の層を調べても無駄です。

この層で一番多いのは認証切れです。しばらく使っていなかったあとに動かないときは、まずここを見てください。

層2: 依頼が届いて、実行できているか

道具は動くが、作業が進まない場合です。

最初に疑うのはネットワークです。第5回で扱ったとおり、既定の workspace-write では外へ出られません。npm install も pip install も失敗します。「依頼したのにライブラリを入れてくれない」の原因は、ほぼこれです。

次に疑うのは範囲です。作業フォルダの外にあるファイルは、既定では書き換えられません。編集したいファイルがフォルダの外にあるなら、--add-dir で足すか、起動するフォルダを変えます。

どちらでもないときは、枠の中で実際にコマンドを打ってみます。

codex sandbox npm test

Codex と同じ枠の中で走るので、枠が原因かどうかがはっきりします。

層3: 出てきたものが、頼んだものと合っているか

動いてはいるが、返ってくるものが的外れな場合です。

原因が2つに分かれます。

依頼が足りていないなら、第6回の3つを見直します。文脈と制約と完了の条件。抜けているのはたいてい完了の条件です。

会話が長すぎるなら、/compact で畳みます。長い会話を持ち続けると、古いやり取りに引きずられて、もう関係ない前提で答えが返ります。答えが急に的外れになったら、まず畳む。作業を変えたのに会話を続けている状態が、この症状の一番多い原因です。

差分が大きすぎて読めないときは、直す先が依頼の側です。第7回で書いたとおり、1つの依頼で20ファイルが変わるなら依頼が大きすぎます。分けてください。

層4: 他の環境でも通るか

手元では通るのに、GitHub Actions で落ちる場合です。

原因は1つに絞れます。手元の環境に、記録されていない何かが残っている。手で入れた道具、生成されたまま追跡されていないファイル、設定した環境変数。このどれかです。

確かめ方は、使い捨ての環境で一から組み立てることです。第14回で触れたクラウドの環境設定も、第13回のワークフローも、これを書き出す作業でした。書き出せていないものが、この症状として出てきます。

BenriWorks でも何度か踏みました。書式の自動整形を手元で通していなかったために落ちたことがあり、そのときは整形を走らせて反映しただけで直りました。もう1つは、設計資料の内容から計算した指紋を検査していて、資料を書き換えたのに指紋を更新していなかった例です。検査そのものは正しく働いていました。

層5: 実際の画面で正しく動いているか

ビルドも検査も通っているのに、開くと動かない場合です。ここが一番やっかいで、実際に開いて確かめるしかありません。

実際に踏んだものを3つ挙げます。

ひとつは、開発用のサーバーで確認していて気づかなかった例です。開発用サーバーの通信がうまくつながらず、画面は出るのに操作が一切効かない状態になっていました。ビルドしたものを配信する形で起動し直したら、そのまま動きました。開発用の起動でおかしいときは、本番と同じ組み立て方で一度確かめる。

ふたつ目は、記述の中のエスケープが壊れていた例です。画面の部品の中に文字列として埋め込んだ処理に、そのままでは通らない書き方が混ざっていて、ブラウザで構文の誤りになっていました。サーバー側の検査は全部通っています。文字列として埋め込むものは、埋め込んだあとの形で確かめないと分かりません。この件のあと、埋め込んだ結果の構文を検査する項目をビルドの前に足しました。

みっつ目は、安全のための設定が原因だった例です。読み込む先を制限する設定があり、そこに計測用の送信先が入っていなかったために通信が全部止まっていました。コードは正しく、設定が足りていませんでした。

3つに共通するのは、ソースコードを読んでも分からないことです。この層の調査は、必ず動いているものを見てください。

調べ方そのものを間違えた例

もう1つ、層の話とは別の失敗を書きます。

16のサイトで計測が届いているかを確認する仕事で、渡した仕様書に「読み込む先を制限する設定は、どのリポジトリにも入っていない」と書いてありました。これが事実と違っていました。

なぜ間違えたかというと、リポジトリの中の文字列を検索して、見つからなかったから「ない」と結論していたからです。実際には、配信の設定として付いていました。本番の応答を見れば分かったことです。

探した場所にないことは、存在しないことを意味しません。設定は、コードの中だけでなく、配信の設定や管理画面にも置かれます。「ない」と書くときは、どこを探して「ない」と言っているのかを自分に確認してください。

この失敗の記録は「GPT-6 Astra の Codex に、16サイトの疎通確認を任せた記録」にまとめています。

直せないときに残すもの

全部が直るわけではありません。時間の制約で、分からないまま進めることもあります。

そのときに残すのは2つです。

何が起きているかの記述。再現する手順、出たエラー、試して駄目だったこと。将来の自分か、誰かが引き継ぎます。

そして、確かめていないと分かる形の印です。BenriWorks では、本文に TODO: 要確認 の形で残す約束にしています。第9回で引用した規約の3行がこれにあたります。分からないことを分からないと書く形式が先に決まっていると、埋めるために推測する動機がなくなります。

一番まずいのは、直っていないのに直ったことにすることです。次に困る人が、直っている前提で調べ始めます。

症状から確認先を選ぶ

「起動しない」「手元の検査は通るがCIで落ちる」「ビルドは通るが画面が動かない」を、本文の層に対応づけます。それぞれ最初に見る出力や画面を書いてください。

現在の症状があれば、試した操作と結果も残します。どこまで進んだかが見えれば、調べる場所を絞れます。

次の回

止まった場所を調べる手段が揃ったら、次に任せる仕事と、人が判断する部分を決めます。「Codexに任せる仕事と、人が決める仕事」へ進めます。

参照した情報

  • codex doctor の出力は codex-cli 0.167.0 を執筆環境へ導入して取得(2026年11月時点)
  • 挙げた失敗は BenriWorks の各リポジトリで2026年に実際に起きたもの

READ NEXT

次はこれを読む

Codex 集中講座の次の回へ

Codexに任せる仕事と、人が決める仕事

Codex 集中講座の最終回。次に任せたい仕事を、戻せる操作、検査できる結果、人の判断に分けます。依頼から確認、公開までに必要な基準を、自分の仕事へ当てはめます。

続きを読む →
作業を終えた机の前で、腕を組んでこちらを向いている男性の開発者

よくある質問

エラーが出たら、まず何をすればよいですか
症状で原因を当てにいく前に、どの層で止まっているかを決めてください。道具が動いていないのか、依頼が通っていないのか、出てきたものが合っていないのか。層が決まれば、確かめる場所は数個に絞れます。層を決めずに調べると、当たりを引くまで探し続けることになります。
Codex が依存関係を入れてくれません
既定の設定ではネットワークが切られています。第5回で扱ったとおり、`workspace-write` の状態では外へ出られないため、パッケージの取得は失敗します。必要なものを先に自分で入れておくか、設定でネットワークを有効にしてください。
手元では通るのに GitHub Actions で落ちます
手元の環境に、記録されていない何かが残っています。手で入れた道具、生成されたまま追跡されていないファイル、設定した環境変数のどれかです。使い捨ての環境で一から組み立てて再現するのが、一番速い確かめ方になります。