中小企業から大手企業まで、累計100社以上のAI・DX支援実績があります。
SEO/AIO対策、広告運用、AI開発、サイト改善、業務効率化まで、必要な施策を「定額」で代行します。
「マーケに詳しい人が社内にいない」
「AIやAIOも気になるが、何から始めればいいかわからない」
そんな企業様に、負担の少ない形でプロの知見をご提供します。
本記事を読めば、Codex CLIの導入・認証・承認モード・テスト実行まで扱えるようになり、既存リポジトリの修正作業を効率化できます。
Codex CLIは、ターミナルから既存コードを読ませ、修正、コマンド実行、差分確認まで進められるOpenAIの開発エージェントです。
AIzen株式会社は、業務システム開発とAI開発支援の現場で、CLIは「小さく依頼し、差分とテストで確認する」運用が最も安定すると考えています。本記事では、既存コードを壊さずにCodex CLIを使う手順を整理します。
Codex CLIとは
Codex CLIは、OpenAIのコーディングエージェントをローカルのターミナルから使うためのツールです。公式マニュアルでは、選択したディレクトリ内のコードを読み、変更し、コマンドを実行できるローカル開発向けの入口として説明されています。
既存リポジトリの調査とコード修正
Codex CLIの価値は、新規コードを生成することだけではありません。既存リポジトリの構造を読み、関連ファイルを探し、既存の命名や実装パターンに合わせて修正案を作れる点にあります。
たとえば「ログイン後のユーザー名表示が空になる原因を調査し、関連ファイルと修正方針を説明してください」と依頼すれば、まず調査に使えます。原因が確認できたら「既存の認証フックは変更せず、表示側だけを修正してください」と範囲を絞って進めます。最初から編集を任せるのではなく、調査、方針、修正の順に分けることが安全です。
コマンド実行とテスト確認
Codex CLIは、必要に応じてテストやLintなどのコマンドを実行できます。既存開発では、修正後に npm test、pnpm test、pytest、cargo test など、プロジェクトごとの確認コマンドを実行できることが重要です。
ただし、コマンド実行は便利な一方で、ネットワークアクセス、ファイル生成、環境変数の扱いに注意が必要です。公式情報では、ローカル実行はサンドボックスと承認設定で制御でき、デフォルトではワークスペース内の操作を中心に扱う考え方が示されています。プロジェクトで実行してよいコマンドをAGENTS.mdに書いておくと、Codexの判断が安定します。
差分レビューと作業ログ
Codex CLIを実務に組み込む場合、最後は必ず差分レビューで確認します。Codexがどのファイルを触ったか、なぜ変更したか、どのテストを実行したか、未確認の点は何かを見ます。
作業ログは、ターミナル上の会話だけでなく、Git差分、PR、チケットにも残すとチームで追いやすくなります。AIが作業したからこそ、通常の開発よりも「変更範囲」と「確認したコマンド」を明示する運用が必要です。
Codex CLIの導入手順
Codex CLIの導入は、インストール、認証、作業ディレクトリ選択の3段階です。公式READMEでは、Standalone installer、npm、Homebrew、GitHub Releaseからのバイナリ取得などが案内されています。実際の導入時は、利用OSと社内のパッケージ管理ルールに合わせて選びます。
npm・Homebrewでのインストール
公式のOpenAI Codexリポジトリでは、Codex CLIをnpmやHomebrewでインストールする手段が案内されています。npmを使う場合はNode.js環境が必要になり、Homebrewを使う場合はmacOSや対応環境のパッケージ管理に乗せやすくなります。
| 方法 | 向く環境 | 確認ポイント |
|---|---|---|
| Standalone installer | 標準手順で導入したい個人・チーム | 公式スクリプトのURL、社内プロキシ |
| npm | Node.js管理に慣れた開発者 | Node.jsのバージョン、グローバルインストール権限 |
| Homebrew | macOS中心の開発チーム | cask更新、MDM管理との整合 |
| GitHub Release | 固定バージョンを使いたい環境 | OS/CPUに合うバイナリ、更新手順 |
社内PCでは、個人判断でグローバルインストールするのではなく、許可されたパッケージ管理方式を確認します。
ChatGPTアカウントと認証設定
Codex CLIは、ChatGPTサインインとAPIキー認証に対応しています。公式マニュアルでは、CLIの標準的な認証パスはChatGPTサインインで、APIキーを使う場合はOpenAI Platformの通常のAPI課金に従うと説明されています。
ChatGPTサインインは、Plus、Pro、Business、Edu、EnterpriseなどのChatGPT側の利用枠やワークスペース設定を使いたい場合に向きます。APIキーは、CI/CDやプログラム的な実行など、OpenAI Platform側の課金と管理で扱いたい場合に向きます。法人では、どちらの認証方式を許可するかを先に決めます。
作業ディレクトリの指定
Codex CLIは、起動した作業ディレクトリを前提にコードを読みます。したがって、リポジトリのルートで起動するか、サブディレクトリに絞って起動するかで、Codexが見られる範囲と作業精度が変わります。
初回は、対象リポジトリのルートで git status が確認できる状態にし、未コミット変更がない、または変更内容を把握している状態で始めます。複数リポジトリをまたぐ作業では、追加ディレクトリの権限や作業範囲を明示します。作業前のGit状態を確認することが、切り戻しの前提になります。
Codex CLIの承認モードの使い分け
承認モードは、Codexにどこまで自律的に進めさせるかを決める設定です。公式マニュアルでは、読み取り中心の read-only、ワークスペース内で編集と通常コマンドを許可する workspace-write、制限を大きく外す danger-full-access などの考え方が説明されています。
読み取り中心の確認モード
読み取り中心の確認モードは、初回利用、影響範囲が不明な不具合調査、既存仕様の把握に向いています。Codexにファイルを読ませ、関連箇所、原因候補、修正方針を返してもらいます。
この段階では、コード変更やコマンド実行を急がないことが重要です。特に本番影響が大きいリポジトリでは、「コード変更は行わず、調査結果だけ報告してください」と明記します。調査結果を人が確認してから編集へ進むと、不要な差分を減らせます。
編集・コマンド実行の承認ルール
編集やコマンド実行を任せる場合は、ワークスペース内に限定し、承認が必要な操作を決めます。公式情報では、Auto相当のプリセットではワークスペース内の読み書きと通常コマンドを進め、ネットワークや範囲外の変更では承認を求める考え方が示されています。
実務では、次のように分けると扱いやすいです。
- ファイル編集: 対象ディレクトリ内のみ許可する
- テスト実行: 事前に定義したコマンドだけ許可する
- ネットワーク: 依存関係インストールや外部API呼び出しは承認する
- 秘密情報: .env や認証ファイルは読ませない
AGENTS.mdに「変更後は npm test を実行する」「本番設定ファイルは編集しない」などを書くと、チームで同じ運用にできます。
Full Auto利用時の確認項目
固定見出しではFull Autoとしていますが、公式マニュアルの現行表現ではFull Accessや danger-full-access、承認なしの実行設定など、より具体的な権限名で整理されています。要するに、承認を少なくして広い操作を任せる運用です。
この設定は、信頼できる検証環境や一時的な作業でのみ使います。業務PCの本番リポジトリ、秘密情報がある環境、外部ネットワークを使うタスクで広い権限を与えると、意図しない変更やデータ参照のリスクが高くなります。利用前には、Gitで戻せる状態か、対象ディレクトリが限定されているか、ネットワークの扱いが明確かを確認します。
Codex CLIの既存リポジトリ実務手順
既存リポジトリでCodex CLIを使うときは、依頼文、差分レビュー、テスト、失敗時の切り戻しまでを一連の手順にします。AIに任せる作業でも、通常の開発プロセスを省略しないことが品質維持につながります。
修正依頼のプロンプト設計
修正依頼では、目的、対象範囲、制約、確認方法をセットで伝えます。悪い依頼は「ログイン画面を直して」です。良い依頼は「ログイン画面でメールアドレス未入力時にエラーメッセージが出ない原因を調査し、既存のバリデーション設計に合わせて最小差分で修正してください。UI文言は変更せず、関連テストがあれば実行してください」です。
特に既存コードでは、変更しない範囲を書くことが重要です。「API仕様は変えない」「DBスキーマは変えない」「関係のないリファクタリングはしない」と伝えるだけで、差分が読みやすくなります。
差分レビューとテスト実行
Codexが修正したら、まずGit差分を確認します。変更ファイル数、変更理由、既存パターンとの整合、例外処理、不要な整形の有無を見ます。その後、対象テスト、Lint、型チェックを実行します。
テストが失敗した場合は、失敗ログをそのままCodexに渡し、「原因を特定し、追加差分を最小にしてください」と依頼します。成功した場合も、未実行のテストや確認できなかった条件があればメモに残します。PR化する場合は、Codexに変更要約を作らせてもよいですが、最終文面は人が確認します。
失敗時の追加指示と切り戻し
Codexの修正が意図と違う場合は、すぐに広げず、1つ前の差分単位で戻します。Gitで差分を確認し、必要なら作業ブランチを切り替えます。未コミット変更が多い状態で追加指示を重ねると、何が原因で壊れたか分かりにくくなります。
弊社エンジニアからのコメント：
Codex CLIで既存コードを直すときは、最初の依頼に「最小差分」「既存パターンに合わせる」「変更後に実行するテスト」を入れるだけで、レビュー時間が大きく変わります。AIに修正を任せるほど、Git差分とテスト結果を人が見る流れを固定するべきです。
Codex CLIのWindows・WSL確認ポイント
Windows環境では、PowerShell、WSL2、Git、パス、サンドボックスの扱いが混ざりやすくなります。公式マニュアルでは、WindowsネイティブではPowerShellとWindows sandbox、WSL2ではLinux sandboxを使う整理が示されています。
PowerShellとWSLの使い分け
PowerShellは、Windowsネイティブのプロジェクト、.NET、Windowsアプリ、通常の社内PC運用に向いています。WSL2は、Linux前提のツールチェーン、Docker、Linux向けスクリプト、Ubuntu上の開発環境に向いています。
どちらが正しいかではなく、チームの実行環境に合わせます。CIがLinuxで動くならWSL2で近い環境を作る価値があります。一方、Windowsアプリや社内端末の制約が強い場合はPowerShell中心で整えるほうが管理しやすいです。
パスとGit認識の確認
Windowsでよく起きるのは、リポジトリの場所とGit認識のずれです。WindowsネイティブのCodexで \\wsl$ 配下を開く場合や、WSL側から /mnt/c/… を扱う場合、パフォーマンスやGit検出で問題が出ることがあります。
公式マニュアルでは、Windowsネイティブエージェントを使うなら、プロジェクトをWindowsファイルシステムに置き、WSLからは /mnt/… 経由でアクセスするほうが信頼しやすいと説明されています。チームでは、プロジェクト配置場所を先に統一します。
サンドボックス設定の見直し
Windowsでは、PowerShell実行時はWindows sandbox、WSL2ではLinux sandboxを使います。WSL2のLinux sandboxでは bubblewrap が関わるため、環境によっては追加設定が必要です。WSL1は現行のLinux sandbox前提では対応しない扱いになっているため、WSL2を基準にします。
PowerShellで npm.ps1 cannot be loaded のような実行ポリシーのエラーが出る場合は、PowerShellの実行ポリシーを確認します。公式マニュアルでは、必要に応じて RemoteSigned を検討する例が示されていますが、社内端末では情シスのポリシーに従って変更します。
まとめ
Codex CLIは、既存リポジトリの調査、修正、テスト確認をターミナルから進められる開発エージェントです。要点は次の3つです。
- 初回は読み取り中心で調査し、方針を確認してから編集へ進む
- 承認モード、サンドボックス、実行してよいコマンドをチームで決める
- WindowsではPowerShellとWSL2の役割、パス、Git、実行ポリシーを先に確認する
AIzen株式会社では、Codex CLIの導入、AGENTS.md整備、既存リポジトリ向け依頼文テンプレート、テスト確認フローの設計まで支援しています。既存コードの修正作業を安全に効率化したい場合は、無料相談で開発環境の整理からご相談いただけます。
コメント