Codexの --image でエラー画面をAIに読ませる — スクリーンショット1枚を10分で渡す
ターミナルに赤い文字が並んだけれど、どこから読めばいいか分からない。
そんなとき、画面を見ながら全部書き写すのはけっこう大変ですよね。Codex CLIの --image を使うと、スクリーンショットを最初の依頼に添えて、画面内の文字や配置を見てもらえます。
今日は、画像機能を広く紹介する記事ではありません。やることはひとつだけです。
機密情報を隠したエラー画面を1枚渡し、見えているエラー文を1つと、次の確認コマンドを1つ受け取る。
原因の断定や自動修正までは進みません。最初の10分は、画面にある事実を拾って、次に何を確かめるか決められたら十分です。
今日の成功状態
最終的に、ターミナルで次の形のコマンドを1回実行します。
codex --image error.png "画像内のエラー文を1つ抜き出し、考えられる原因と、次に実行する確認コマンドを1つだけ教えて。ファイルは変更しないで"
たとえば画像に EADDRINUSE や port 3000 と表示されていれば、回答にもその文字が含まれ、ポート3000を使っているプロセスを確認するコマンドが1つ提案される、という状態を目指します。
成功条件は次の2つです。
- 回答に、画像内で実際に読めるエラー文が1つ含まれる
- 次に確認するコマンドが1つだけ示される
提案された原因が正しいか、コマンドを実行してよいかは、まだ人間が確認します。この線引きが大事なんです。
--image は何をする機能か
Codexは、手元のファイルを読んだり、コマンドを実行したりしながら作業を進めるAIエージェントです。ここでいう AIエージェント は、質問に文章で答えるだけでなく、与えられた道具やファイルを使って作業を進めるAI、くらいに考えてください。
Codex CLIの CLI は「ターミナルへ文字を打って操作する方式」です。ターミナルは、コマンドという短い命令を入力するための画面です。
--image は、Codexへ送る最初の依頼に画像ファイルを添付するオプションです。オプションは、コマンドの動きを少し変える追加指定のことです。短縮形の -i も使えます。
公式ドキュメントでは、エラーのスクリーンショット、画面設計、構成図、既存アセットなど、見た目の情報が必要な場面が例に挙げられています。PNGとJPEGを含む一般的な画像形式に対応し、画像を複数渡すこともできます。
ただ、今回は広げません。PNG画像を1枚、最初の依頼に添える。これだけです。
なぜ画像だけを渡して終わりにしないのか
公式ドキュメントは、画像だけに頼らず「何を見て、どんな結果がほしいか」を依頼文に書くことを勧めています。
写真を誰かに渡して「これ、どう？」と聞くより、「右下のエラー文を読んで、次に確認することを1つ教えて」と聞く方が答えやすいですよね。Codexでも同じです。
今回の依頼には、次の3点を入れます。
- 見る場所: 画像内のエラー文
- 欲しい結果: エラー文、原因の候補、確認コマンドを各1つ
- 制約: ファイルを変更しない
画像を付けること自体より、画像をどう読んでほしいかを言葉で囲うことが、失敗を減らします。
前提を確認する
この記事は、macOSのターミナルで codex-cli 0.147.0 を使って確認しています。WindowsやLinuxでも基本の構文は同じですが、スクリーンショットの撮り方やファイルの場所はOSによって違います。
まず、Codex CLIが入っているか確認します。
codex --version
次のようにバージョンが表示されれば進めます。数字は更新により変わります。
codex-cli 0.147.0
command not found と表示された場合は、先にCodex CLIを導入します。macOSやLinuxでは、公式インストーラーを次のように起動できます。
curl -fsSL https://chatgpt.com/codex/install.sh | sh
インストール後、初めて使う場合はサインインします。
codex login
ブラウザが開いたら画面に沿って進めます。Codex CLIは、ChatGPTでのサインインとAPIキーでのサインインに対応しています。この記事では料金額を扱いません。利用できる方法は契約や組織設定で異なるため、表示されたサインイン画面と公式の認証ページを確認してください。
ログイン状態は次のコマンドで確認できます。
codex login status
手順1: エラー画面を1枚用意する
スクリーンショット は、いま画面に見えている内容を画像として保存したものです。
まず、調べたいエラーが表示されている部分だけを撮ります。この記事ではファイル名を error.png とします。
画像を保存したら、添付する前に必ず開き直してください。次のものが映っていないか確認します。
- APIキー、アクセストークン、パスワード
- メールアドレス、ユーザー名、顧客名
- 社内URL、非公開リポジトリ名
- ホームフォルダなどに含まれる個人名
- 通知、別ウィンドウ、ブラウザのタブ
不要な部分はトリミングで切り取るか、復元できない形で塗りつぶします。半透明の線で隠すだけでは、下の文字が読めることがあります。
画面全体を渡す必要はありません。エラー文と、その前後が少し見える範囲で十分です。情報が少ないほど安全で、Codexも見る場所を絞りやすくなります。
手順2: 練習用フォルダへ画像を置く
画像の場所で迷いにくいよう、練習用フォルダを作ります。フォルダ は、ファイルをまとめて置く箱のようなものです。
macOSやLinuxのターミナルで次を実行します。
mkdir -p ~/codex-image-practice
cd ~/codex-image-practice
次に、撮った error.png をこのフォルダへ移します。Finderやエクスプローラーでドラッグしても構いません。
移したあと、macOSやLinuxでは次のコマンドで確認します。
ls
次のように表示されれば、Codexを起動する場所と画像の場所がそろっています。
error.png
Windows PowerShellでは、フォルダ内で次を実行すると一覧を確認できます。
Get-ChildItem
ここでいう ファイルパス は、コンピューターの中でファイルがどこにあるかを表す住所です。今回は同じフォルダに画像を置いたので、長い住所を書かず error.png だけで指定できます。
手順3: --image で画像を渡す
画像があるフォルダで、次の1コマンドを実行します。
codex --image error.png "画像内のエラー文を1つ抜き出し、考えられる原因と、次に実行する確認コマンドを1つだけ教えて。ファイルは変更しないで"
分解すると、こうなっています。
| 部分 | 意味 |
|---|---|
codex |
Codex CLIを起動する |
--image error.png |
最初の依頼に画像を1枚添付する |
| 引用符の中 | 画像の見方、欲しい結果、制約を伝える |
引用符の中はターミナルへ一緒に貼り付けます。Codex起動後の入力欄へ別々に打つ手順ではありません。
短縮形を使う場合は次でも同じ目的になります。
codex -i error.png "画像内のエラー文を1つ抜き出し、次に確認することを1つ教えて。ファイルは変更しないで"
最初は長い --image の方が、あとからコマンドを見返したときに意味を思い出しやすいと思います。
手順4: 成功したか照合する
回答が返ったら、まず画像と見比べます。
次の順で確認してください。
- 回答に書かれたエラー文は、画像に本当にあるか
- ポート番号やファイル名などの数字・文字は一致しているか
- 原因が「確定」ではなく、確認すべき候補として示されているか
- 提案されたコマンドは、読み取りや状態確認に留まっているか
たとえば EADDRINUSE が画像にあるのに、回答が MODULE_NOT_FOUND を前提にしていたら成功とは言えません。「画像内では EADDRINUSE と読めます。そこだけを前提に考え直して」と伝えます。
確認コマンドがファイル削除、プロセスの強制終了、設定変更を含む場合は、そのまま実行しないでください。最初の一歩は、事実確認で止めて大丈夫です。
筆者環境で確認できた範囲
2026年8月17日に、macOS 14.8.3と codex-cli 0.147.0 で次を確認しました。
-
codex --helpに-i, --image <FILE>...が表示される - 1000×420ピクセルのPNGを
codex exec --imageへ渡すと、画像引数を受け取って起動する - 読み取り専用サンドボックスを指定したコマンド構文が通る
ただし、筆者環境では認証が切れており、モデルから画像の説明を受け取るところは401エラーで止まりました。そのため、この記事の回答例は期待される確認観点であり、モデル応答そのものは筆者環境で動作未確認です。
うまくいかなかったところまで書くのは、再現性の一部だと思っています。読者の環境で回答が返った場合も、画像との照合は省略しないでください。
つまずきポイント
1. codex: command not found と表示される
Codex CLIが未導入か、インストール先へターミナルから到達できていません。まず公式の導入手順を終え、ターミナルを開き直してから確認します。
codex --version
2. error.png が見つからない
ターミナルがいるフォルダと、画像を保存したフォルダが違う可能性があります。
macOSやLinuxでは、現在地とファイル一覧を確認します。
pwd
ls
Windows PowerShellでは次を使えます。
Get-Location
Get-ChildItem
一覧に error.png がなければ、画像を現在のフォルダへ移すか、正しいファイルパスを指定します。
3. ファイル名に空白がある
error screen.png のような名前は、引用符で囲みます。
codex --image "error screen.png" "画像内のエラー文を1つ教えて。ファイルは変更しないで"
最初の練習では error.png のように空白のない名前へ変えると、つまずきを1つ減らせます。
4. 401やログインを求める表示が出る
画像の問題ではなく、認証情報がないか期限切れの可能性があります。ログイン状態を確認し、必要ならサインインし直します。
codex login status
codex login
APIキーや認証ファイルをスクリーンショットへ映したり、記事やチャットへ貼ったりしないでください。
5. 画像を付けたのに回答がぼんやりしている
「この画像を見て」だけでは、見る場所と出力が決まっていません。次のように、対象・結果・制約を入れます。
画像中央の赤いエラー文を1つ正確に抜き出して。
原因は候補を1つ、次の確認コマンドも1つだけ示して。
ファイル変更やプロセス終了はしないで。
6. 画像内の文字を読み間違える
文字が小さい、ぼやけている、表示が途中で切れている可能性があります。エラー部分だけを拡大して撮り直します。回答中の文字列は、必ず元画像と1文字ずつ照合してください。
7. 画像に秘密情報が映っていた
送信前なら中止し、トリミングまたは塗りつぶして新しい画像を作ります。送信後に気づいた場合は、利用している組織のルールに従い、秘密情報の失効・再発行が必要か管理者へ確認します。
「あとで消せば大丈夫」とは考えず、添付前の見直しを1工程にするのが安全です。
--image が向かない条件
反対に、エラー文をそのままコピーできるなら、画像を使わない方がよい場合があります。
テキストは文字の読み違いが起きにくく、検索もしやすく、必要な部分だけを渡せます。次のような状況では、エラー文をコードブロックで貼る方が正確で速いです。
- 1行のエラーだけで状況を説明できる
- ログを選択してコピーできる
- 画面の位置関係や色に意味がない
- 画像から秘密情報を完全に除くのが難しい
--image が効くのは、文字だけでは位置関係を伝えにくい、複数箇所を同時に見せたい、UIの状態そのものが問題、といった場合です。
画像入力は便利ですが、画像の外にある実行環境、直前の操作、内部状態までは見えません。Codexが挙げる原因は仮説です。確認コマンドや公式ドキュメントで確かめてから、修正へ進みます。
よくある質問
画像は何枚まで渡せますか
公式ドキュメントでは、1枚以上の画像を渡せて、複数の場合はカンマで区切るか --image を繰り返せると説明されています。この記事では最初の成功を小さくするため、1枚だけにしています。
PNG以外でも使えますか
公式ドキュメントは、一般的な画像形式としてPNGとJPEGを明記しています。まずはそのどちらかを使うのが分かりやすいです。
画像を渡すと自動で直してくれますか
依頼内容と権限設定によります。この記事では修正を頼まず、「ファイルは変更しないで」と明記しています。最初は読み取りと確認に限定する方が、何が起きたか追いやすいです。
画像を作り直してもらう機能ですか
違います。--image は既存画像を視覚情報として読ませる機能です。画像を生成・編集する機能とは用途が別です。
まとめ
今日の成功条件は、エラーを直し切ることではありません。
機密情報を隠したスクリーンショット1枚を codex --image で渡し、画像内のエラー文1つと、次の確認コマンド1つを得る。
この小さな成功で、AIエージェントに文字だけでなく「現場の見た目」も渡せるようになります。一方で、画像の外側の状況までは分かりません。回答を元画像と照合し、原因を仮説として扱うところまでがセットです。
次の1アクションは、自分の開発画面から秘密情報を除いたスクリーンショットを1枚だけ用意し、この記事のコマンドをそのまま試すことです。
参考リンク
生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています → X