Codex 学習（基礎概念）

① やさしい定義

AGENTS.md は、プロジェクトのフォルダに置いておく「指示書」です。Codexは毎回の会話のはじめにこれを読むので、「うちのルール」「テストの回し方」などを書いておくと、何度も説明しなくてすみます。Claude Code の CLAUDE.md と同じ役割で、どちらも良いしくみ。中身は Markdown（＝見出しや箇条書きの書ける文章）です。動作の細かい設定を書く ~/.codex/config.toml（＝TOML形式の設定ファイル）とは別物なので、混同しないのがコツです。

③ よく使うコマンド

• /init対話中に打つと、コードを見て AGENTS.md のたたき台を作ってくれる
• AGENTS.mdプロジェクト直下に置く指示ファイル本体。手で書き足してもOK
• ~/.codex/config.tomlこちらは「設定」ファイル（TOML）。指示ではなく動作の既定を決める別物

④ いつ使うか

同じ説明を2回したら、書き足すサインです。プロジェクト直下に置けばチームで共有でき、ホーム（~/.codex/AGENTS.md）に置けば自分の全プロジェクト共通のメモになります。ただし太らせすぎ注意。「この行を消したらCodexが間違える？」の答えが「いいえ」なら、その行は削って身軽にしておくと読み込みも軽くなります。

① やさしい定義

承認ポリシーは、Codexがファイル編集やコマンド実行をする前に、あなたに「これ、やっていいですか？」と確認する度合いの設定です。on-request（必要なときに確認）と never（確認しない＝人が見ていない自動実行向け）の2つが基本。以前あった untrusted は廃止されたので、慎重に進めたいときは承認を on-request にしたうえで、サンドボックスを read-only（読むだけ）にします。あなたがOKを出すまで実行されないのが、安心して任せられる土台になります。

③ よく使うコマンド

• codex -a on-request起動時に承認の度合いを指定（-a は --ask-for-approval の短い形）
• /permissions対話中に今の権限を確認・調整。以前の /approvals は現在これに名称変更
• /approveその場で出てきた操作を承認する
• approval_policy = "on-request"config.toml に既定を書く。値は on-request / never（untrusted は廃止）

④ いつ使うか

ふだんの対話は on-request が安心です。人が見ていないCIやスクリプトでは never（聞かない）にしますが、その代わりサンドボックスで「触れる範囲」を狭めてバランスを取ります。なお、かつてあった on-failure は現在は非推奨なので、on-request か never を選ぶのがおすすめです。

① やさしい定義

サンドボックス（＝AIが触れる範囲を制限する安全な箱）は、Codexが「どこまで触れてよいか」を決めるしくみです。read-only（読むだけ・何も書き換えない）→ workspace-write（今の作業フォルダの中だけ書き込みOK）→ danger-full-access（制限なし・パソコン全体に手が届く＝危険）の3段階。承認ポリシーが「聞く度合い」なのに対し、こちらは「触れる範囲」を決める、別の軸です。

③ よく使うコマンド

• codex -s read-only読むだけモードで起動（-s は --sandbox の短い形）
• codex -s workspace-write作業フォルダ内だけ書き込みを許可
• sandbox_mode = "workspace-write"config.toml に既定を書く
• [sandbox_workspace_write] network_access = true書き込みモード中のネット接続の可否を切り替える
• codex sandbox -- <コマンド>サンドボックスの中で試しにコマンドを走らせる

④ いつ使うか

まず全体像を知りたい・下調べだけしたいときは read-only。実際に直してもらうなら workspace-write。danger-full-access は、こわれても困らない隔離された環境（＝ほかと切り離した使い捨ての作業場所）でだけにしておくのが安心です。「まず読むだけで探索、必要になったら書き込み」の順が、失敗しにくい流れです。

① やさしい定義

承認ポリシーとサンドボックスは、それぞれ独立した設定です。承認は「どれくらい確認するか」、サンドボックスは「どこまで触れるか」。この2つをかけ合わせると、たとえば「聞かない（never）× 読むだけ（read-only）」＝勝手にどんどん進むけれど何も壊せない、といった安全な自動化ができます。片方だけでなく、2つセットで考えるのがポイントです。

③ よく使うコマンド

• codex -a on-request -s workspace-write承認とサンドボックスを同時に指定して起動
• codex exec --sandbox workspace-write "…"exec（非対話）で、作業フォルダ内だけ書き込みを許して進める。以前の --full-auto は Codex 0.147.0 で削除され、この書き方に置き換わりました
• --dangerously-bypass-approvals-and-sandbox別名 --yolo。承認もサンドボックスも両方外す。隔離環境だけで慎重に⚠

④ いつ使うか

対話で安全に進めたいときは「on-request × workspace-write」。CIなどで自動化したいときは「never × read-only（または workspace-write）」のように、聞かない代わりに触れる範囲を狭めます。--yolo のように両方外す設定は、こわれても困らない隔離環境でだけ。便利に見えても、安全のつまみを2つ同時に外すのは慎重に、が合言葉です。

① やさしい定義

reasoning effort は、モデルが答える前に「どれくらい考えをめぐらせるか」の深さです。minimal / low / medium / high / xhigh から選べて、深いほど丁寧で慎重になります。ただし考える時間が延び、使うトークン（＝料金のもと）も増えます。かんたんな作業に深く考えさせるのはもったいないので、作業の難しさに合わせて選ぶと、効率と料金の両方にやさしくなります。

③ よく使うコマンド

• model_reasoning_effort = "medium"config.toml に既定を書く。値は minimal / low / medium / high / xhigh
• /model対話中にモデルと合わせて、考える深さを選び直せる

④ いつ使うか

ちょっとした修正や定型作業は low 〜 minimal で軽快に。設計を練る、こみ入ったバグを追う、といった山場だけ high や xhigh に上げて本気を出してもらう、という使い分けが効率的です。ずっと最大にしていると、待ち時間も料金もかさみやすいので、ふだんは medium あたりに戻しておくとバランスがよいです。

① やさしい定義

Codexを使うには本人確認（認証）が必要で、入口が2つあります。ひとつは ChatGPT の有料プランでログインする方法。もうひとつは APIキー（＝使うたびに課金される鍵）を使う方法です。ざっくり言うと、ログインは月額プランの範囲で使えて、APIキーは使った分だけの従量課金。どちらが良い悪いではなく、使い方に合うほうを選びます。

③ よく使うコマンド

• codex loginChatGPTアカウントでサインイン。最初に一度おこなう
• codex logout保存されたサインイン情報を消す。共用パソコンのあとに
• forced_login_method = "chatgpt"config.toml でログイン方法を固定したいときに
• OPENAI_API_KEY / CODEX_API_KEYAPIキーを使う場合の環境変数。公式は CODEX_API_KEY を案内していますが、既定の openai プロバイダは事実上 OPENAI_API_KEY を見ます

④ いつ使うか

すでに ChatGPT の有料プランを持っているなら、codex login だけで始められて手軽です。自動化やチームでキーを管理したい、使った分だけ払いたい、という場合はAPIキーが向いています。料金体系や対応状況は変わりやすいので、大事な判断の前には公式ドキュメントで最新をご確認くださいね。

① やさしい定義

モデル選択は、使うAIの「頭脳のタイプ」を選ぶことです。軽くて速いモデルと、賢いけれど少しゆっくり・単価が高めのモデルがあり、作業の難しさに合わせて使い分けます。具体的なモデル名（gpt-5.x など）は変わりやすいので、名前を覚えるより「軽い／重い」の考え方でとらえておくと、名前が変わってもあわてずにすみます。

③ よく使うコマンド

• codex --model <モデル名>起動時にモデルを指定（-m は --model の短い形）
• /model対話の途中でモデルを切り替える
• model = "…"config.toml に既定のモデルを書く。具体名は公式で最新を確認
• codex --oss手元で動くオープンなモデルを使う選択肢

④ いつ使うか

ふだんの作業は標準的なモデルで十分です。込み入った設計や、原因のわかりにくいバグの山場だけ、賢いモデルに切り替えて深く考えてもらいましょう。ネット接続なしで試したい・ローカルで動かしたいときは --oss も選択肢になります。モデルの並びや名称は移り変わるので、迷ったら公式ドキュメントを見てみてください。

① やさしい定義

プロファイルは、よく使う設定の組み合わせに名前をつけて、まとめて呼び出せるしくみです。たとえば「探索用の安全設定」「実装用の高速設定」を別々に用意しておけば、毎回オプションを打ち直さずに切り替えられます。今は ~/.codex/<名前>.config.toml という別ファイルに分けて持つ方式です。Codex 0.134.0 以降、config.toml の中に書く [profiles.<名前>] は読まれなくなりました。

③ よく使うコマンド

• codex --profile safe名前をつけた設定セットを呼び出して起動（-p でも同じ）
• ~/.codex/safe.config.tomlプロファイル用の別ファイル。承認やサンドボックスなどの設定を、[profiles.…] で囲まずにそのまま書く
• sandbox_mode = "read-only"プロファイルのファイルに書く設定の例（読むだけ）

④ いつ使うか

「下調べは安全に、実装は速く」など、場面によって設定を変えたいときに便利です。安全設定と高速設定を分けておけば、切り替えがラクになり、うっかり危ない設定のまま作業してしまう事故も減らせます。まずは「読むだけの安全プロファイル」を1つ作っておくと、探索のときに安心です。

① やさしい定義

MCP（Model Context Protocol）は、Codexを外部のツールやデータにつなぐための共通の規格です。GitHubやデータベース、ブラウザなどを「追加の道具」としてCodexに持たせられます。つなぐと、別のツールの結果をコピペして貼りつける手間なしに、Codexが直接そのサービスを読んだり操作したりできるようになります。

③ よく使うコマンド

• codex mcp add <名前> -- <起動コマンド>使いたい外部ツールを1つ登録する
• codex mcp listいま何がつながっているか一覧で確認
• /mcp対話中に、つないだサーバーの状態を確認する
• [mcp_servers.<id>]config.toml に接続先の設定を書く

④ いつ使うか

「別のツールの結果を毎回コピペしてCodexに貼っている」と気づいたら、導入を考えるサインです。ただし、つなぐ前に、その接続先が信頼できるかを必ず確認してください。外部の内容を取り込むサーバーには、悪い指示がこっそり紛れ込む「プロンプトインジェクション」（＝入力に混ぜた不正な指示）のリスクがあるため、接続先と許可する権限はセットで見るのが安心です。

① やさしい定義

codex exec は、対話画面（TUI＝ターミナル上の操作画面）を開かず、指示を一回だけ実行する「非対話モード」です。人が横で見ていないCI（＝自動でテストなどを回すしくみ）やスクリプトの中で使うのに向いています。結果を、機械が受け取りやすい形（JSONなど）で出すこともできるので、次の処理につなげやすいのが特長です。

③ よく使うコマンド

• codex exec "…"指示を一回だけ実行（短縮形は codex e）
• --json結果を機械で読める形（JSON）で出力する
• -o result.txt最後の返答をファイルに書き出す（--output-last-message）
• --output-schema schema.json出力の「形」をあらかじめ指定する
• --skip-git-repo-checkGitで管理していない場所でも実行できるようにする

④ いつ使うか

CIや定期実行、スクリプト化など「対話せず一発でやってほしい」ときに使います。人が確認できない場所なので、承認は never（聞かない）にしつつ、サンドボックスで触れる範囲を狭めて安全を確保するのがおすすめ。出力を次の処理に渡したいときは --json や -o で受け取りやすい形にしておくとスムーズです。

① やさしい定義

セッションは、Codexを起動してから終わるまでの「ひとまとまりの会話」です。中身は保存されているので、あとから続きを再開できます。resume は過去の会話を選んで続きから、fork は途中の会話を枝分かれさせて別の道を試すしくみ。forkは元の会話を残したまま分岐するので、「こっちのやり方も試したい」を安心してできます。

③ よく使うコマンド

• codex resume過去の会話を一覧から選んで再開する
• codex resume --lastいちばん最近の会話を、選ぶ手間なくすぐ再開
• codex fork会話を枝分かれさせて、元を残したまま別案を試す
• /resume・/fork対話の途中からでも、再開や枝分かれができる

④ いつ使うか

昨日の作業の続きなら resume --last。「あのときの会話どれだっけ？」と探すなら resume で一覧から。「この続きで、もう一つ別のやり方も比べたい」なら fork が便利です。案件ごとに会話を分けておくと頭が混ざらず、forkを使えば元をこわさずに2案を見比べられます。

① やさしい定義

コンテキストは、AIの「作業机」であり「短期記憶」です。あなたとの会話・読み込んだファイル・指示が全部この机の上に載り、Codexは毎回それを見ながら答えます。容量に上限があるので、いっぱいに近づくと動きが鈍くなり、前の指示を忘れやすくなります。/compact は、それまでの会話を要約してギュッと軽くする操作。大事な流れは残しつつ、机のスペースを取り戻せます。

③ よく使うコマンド

• /compact会話を要約して圧縮。大事な流れは残しつつ軽くする
• /status今どれくらい机が埋まっているか、状況を見る物差し
• /new・/clear新しい会話を始める／今の会話をまっさらにする
• model_auto_compact_token_limitconfig.toml。自動で圧縮に入る目安を決める
• model_context_windowconfig.toml。コンテキストの広さの目安

④ いつ使うか

「動きが重いな」「前の指示を忘れがちだな」と感じたら、まず /status で様子見。同じ作業を続けたいけれど会話が長くなってきたら /compact で圧縮。まったく別の作業に切り替えるなら、続きに乗せず /new で新しい会話に。迷ったら状況確認から、が合言葉です。

① やさしい定義

画像入力は、スクリーンショット（＝画面の写真）やデザイン案などの画像をCodexに渡して、見てもらう機能です。エラーの出ている画面、崩れたレイアウト、手書きのラフなど、文字で説明するより見せたほうが早いものを共有できます。起動時に画像を添える方法と、対話の途中で添付する方法があります。

③ よく使うコマンド

• codex --image screenshot.png起動時に画像を添える（-i は --image の短い形）
• /mention対話中に、ファイルや画像を指定して添付する
• [tools] view_image = trueconfig.toml。画像を見る機能に関する設定

④ いつ使うか

エラーが出ている画面、思ったとおりに表示されないレイアウト、手書きのメモやラフなど、「文字より画像のほうが早い」ときに使います。うまく言葉にできないときほど便利で、やりとりの回数も減らせます。画面全体でなく、気になる部分を切り取って渡すと、より的確に見てもらえます。

① やさしい定義

Web検索は、Codexが必要に応じてインターネットを調べながら答える機能です。AIは学習した時点までの知識で答えるのが基本なので、それより新しい情報や、よく変わる仕様（新しいライブラリの使い方など）は、検索して確かめたほうが確実。この機能をオンにすると、うろ覚えで進まずに、調べたうえで作業してくれます。

③ よく使うコマンド

• codex --search "…"Web検索を有効にして起動する
• web_search = "live"config.toml に既定を書いておく
• [tools] web_search = trueconfig.toml。ツールとしてWeb検索を有効化する

④ いつ使うか

新しめのライブラリやAPIの使い方、最近変わった仕様、最新のニュースなど「今の情報を確かめたい」ときに向いています。ただし、検索で見つかった情報が必ず正しいとは限らないので、重要な判断につながる点は、示された参照元や公式ドキュメントで念のため確認しておくと安心です。

① やさしい定義

スキルは、決まった作業の「やり方メモ」を1つのまとまりにしたものです。中身は説明文（どんなときに使うか）と、必要なら手順やスクリプトのセット。入力欄で $名前 と打つと呼び出せて、Codexがその段取りに沿って動いてくれます。「レビューのやり方」「リリース作業の手順」など、何度もやることをスキルにしておくと、毎回ゼロから説明せずにすみます。

③ よく使うコマンド

• $skill-creator自分のスキルを対話で作れる、備え付けのスキル
• $skill-installer公開されているスキルを取り込む、備え付けのスキル
• /skillsいま使えるスキルの一覧を見る・呼び出す

④ いつ使うか

「同じ頼み方を何度もしているな」と気づいたときが、スキルにする合図です。まずは $skill-creator で1つ作ってみるのがおすすめ。Claude Code のスキルと同じ考え方（共通の仕様）なので、片方で作ったものをもう片方でも活かしやすいのも便利なところです。

① やさしい定義

プラグインは、スキルや外部ツール連携（MCP）などの「便利セット」をひとまとめにした配布物です。1つ入れるだけで、関連する機能が一式そろいます。/plugins で一覧から探して、有効・無効を切り替えられます。スキルが「1つの手順」なら、プラグインは「手順や連携をまとめた詰め合わせ」というイメージです。

③ よく使うコマンド

• /plugins使えるプラグインを探す・入れる・切り替える
• codex plugin add <名前>プラグインを追加する
• codex plugin marketplace add配布元（マーケット）を登録する

④ いつ使うか

SlackやGitHubなど、特定のサービスとまとめて連携したいときに向いています。まずは公式が用意したものから試すと安心。慣れてきたら、自分の環境に合わせて足していきましょう。「便利そう」で入れっぱなしにせず、使わないものは無効にしておくと、権限まわりもすっきりします。