OpenAI Codex CLIのカスタム設定とエイリアス活用法

OpenAI Codex CLIを使い始めて数日経つと、「毎回同じオプションを指定するのが面倒」「プロジェクトのコーディング規約をいちいち説明するのが大変」という悩みが出てきます。デフォルト設定のままでは、Codex CLIの真の力を引き出せていません。

適切にカスタム設定とエイリアスを整備することで、作業効率は格段に上がります。本記事では、OpenAI Codex CLIの設定ファイルの書き方から、実用的なエイリアスパターン、SES現場での推奨設定まで、実践的な内容を網羅して解説します。

Codex CLIの設定ファイル体系を理解する

Codex CLIには2種類の主要な設定ファイルがあります。それぞれの役割を正確に理解することが設定の第一歩です。

この2つを組み合わせることで、「どのプロジェクトでも共通の動作」と「このプロジェクト固有の指示」を分けて管理できます。

codex.yaml — グローバル設定ファイル

基本構造と設定項目

~/.codex/codex.yaml はホームディレクトリの .codex フォルダ内に作成します。

# 設定ディレクトリを作成
mkdir -p ~/.codex

# 設定ファイルを開く
code ~/.codex/codex.yaml

基本的な設定例：

# ~/.codex/codex.yaml

# 使用するモデルの指定
model: gpt-4o

# 出力の創造性レベル（0.0〜2.0、低いほど一貫性重視）
temperature: 0.1

# サンドボックスポリシー（後述）
sandbox: workspace-write

# タイムアウト設定（秒）
timeout: 120

# ログレベル（debug, info, warn, error）
log-level: warn

# 自動承認ポリシー（on-failure, on-request, never）
approval-policy: on-failure

モデルの選択

2026年2月時点で利用可能な主要モデル：

# 最高精度（複雑なリファクタリング・設計作業向け）
model: o3

# バランス型（日常的なコーディング作業向け）
model: gpt-4o

# 高速・低コスト（単純なタスク・頻繁な確認向け）
model: gpt-4o-mini

プロジェクトの性質に応じてモデルを使い分けることがコスト最適化につながります。SES現場での実務では gpt-4o がバランス型として最も使いやすい選択です。

approval-policyの設定

approval-policy はCodex CLIがファイル変更・コマンド実行を行う際に確認を求めるタイミングを制御します。

# on-failure: 失敗したとき（または危険な操作）だけ確認を求める
# → 自動化を優先したい場面に適している
approval-policy: on-failure

# on-request: モデルが確認を求めたときだけ
# → バランス型。通常はこれで問題ない
approval-policy: on-request

# never: 常に確認なしで実行
# → 完全自動化。本番環境や重要なリポジトリでは非推奨
approval-policy: never

AGENTS.md — プロジェクト固有の指示ファイル

AGENTS.md はプロジェクトのルートディレクトリに配置するMarkdownファイルです。Codex CLIはタスクを実行する前に必ずこのファイルを読み込み、プロジェクト固有のコンテキストとして使用します。

AGENTS.mdの基本テンプレート

# AGENTS.md

## プロジェクト概要
このプロジェクトはTypeScript + Node.js（v20）で構築されたRESTful APIサーバーです。
Express 5.x を使用しています。

## 技術スタック
- 言語: TypeScript 5.x
- ランタイム: Node.js 20
- フレームワーク: Express 5
- ORM: Prisma
- テスト: Vitest + Supertest
- Linter: ESLint + Prettier
- パッケージマネージャー: pnpm

## ディレクトリ構造

src/ controllers/ # HTTPリクエストハンドラー services/ # ビジネスロジック repositories/ # データアクセス層 models/ # 型定義・Prismaスキーマ utils/ # ユーティリティ関数 middleware/ # Express ミドルウェア tests/ unit/ integration/

## コーディング規約
- すべての関数に JSDoc コメントを記述すること
- エラーハンドリングは `src/utils/errors.ts` の共通クラスを使うこと
- async/await を使い、Promise チェーンは避けること
- any 型の使用は禁止。unknown を使って型ガードで絞ること
- ファイルのエクスポートは named export を使い、default export は避けること

## テスト規約
- テストファイルは `*.test.ts` の命名規則
- ユニットテストは `tests/unit/` に配置
- 統合テストは `tests/integration/` に配置
- テストフレームワークは Vitest を使用すること（Jestは使わない）
- モックは vi.mock() を使用すること

## 禁止事項
- console.log をソースコードに残さないこと（logger.ts を使うこと）
- 環境変数を直接 process.env で参照しないこと（config.ts 経由で取得すること）
- node_modules を直接編集しないこと
- prisma/migrations/ ファイルを手動で編集しないこと

マルチプロジェクト対応のAGENTS.md

複数のプロジェクトで作業する場合、サブディレクトリにも AGENTS.md を配置できます。Codex CLIはディレクトリ階層を遡って複数の AGENTS.md を結合して読み込みます。

my-monorepo/
├── AGENTS.md          # モノレポ全体の共通設定
├── apps/
│   ├── frontend/
│   │   └── AGENTS.md  # フロントエンド固有の設定
│   └── backend/
│       └── AGENTS.md  # バックエンド固有の設定
└── packages/
    └── shared/
        └── AGENTS.md  # 共有パッケージの設定

# apps/frontend/AGENTS.md

## フロントエンド固有設定
- フレームワーク: React 19 + Vite
- スタイリング: Tailwind CSS v4
- 状態管理: Zustand
- コンポーネントテスト: Vitest + Testing Library
- E2Eテスト: Playwright

## コンポーネント規約
- コンポーネントは関数コンポーネントのみ使用
- props の型定義は interface ではなく type を使うこと
- スタイルはすべて Tailwind クラスで記述（CSS modules は使わない）

エイリアスの設定と活用法

エイリアスを設定することで、よく使うコマンドを短縮できます。シェルの設定ファイルに追記します。

基本的なエイリアス設定

# ~/.zshrc または ~/.bashrc に追加

# 基本エイリアス
alias cx="codex"

# フルオート実行（確認なし）
alias cxf="codex --approval-policy=never"

# テスト生成専用
alias cxt="codex 'テストを書いて'"

# コードレビュー専用
alias cxr="codex 'コードをレビューして問題点を指摘して'"

# デバッグ支援
alias cxd="codex 'このエラーの原因を調査して修正して'"

# ドキュメント生成
alias cxdoc="codex 'このコードにJSDocコメントを追加して'"

# リファクタリング
alias cxrefactor="codex 'このコードをリファクタリングして。可読性と保守性を重視して'"

設定後は以下のコマンドで反映：

source ~/.zshrc
# または
source ~/.bashrc

引数を受け取る関数エイリアス

より柔軟な使い方のために、シェル関数として定義する方法もあります：

# ~/.zshrc に追加

# 特定ファイルのテストを生成する関数
cxtest() {
  codex "$(echo "$1") のユニットテストを生成して。エッジケースも含めて"
}

# 特定ファイルをレビューする関数
cxreview() {
  codex "$(echo "$1") をコードレビューして。バグ、パフォーマンス問題、セキュリティ上の懸念点を指摘して"
}

# PRの変更をレビューする関数
cxpr() {
  local diff=$(git diff HEAD~1)
  codex "以下のgit diffをレビューして問題点を指摘して：
$diff"
}

# エラーメッセージから修正方法を調べる関数
cxfix() {
  codex "以下のエラーを修正して：$(echo "$*")"
}

使用例：

# 特定ファイルのテストを生成
cxtest src/utils/validation.ts

# 特定ファイルをレビュー
cxreview src/services/payment.service.ts

# 最新コミットのdiffをレビュー
cxpr

# エラーメッセージから修正
cxfix "TypeError: Cannot read property 'id' of undefined at line 42"

プロジェクト固有のエイリアス設定

プロジェクトごとに異なるエイリアスを管理したい場合は、.envrc（direnv）や .project.zshrc を活用できます：

# .envrc（direnvを使う場合）
export CODEX_PROJECT="my-express-api"

# プロジェクト固有のエイリアスを読み込む
if [ -f .project.zshrc ]; then
  source .project.zshrc
fi

# .project.zshrc（プロジェクトルートに配置）

# Prismaマイグレーション作業
alias cxmigrate="codex 'Prismaのスキーマ変更に合わせてマイグレーションファイルを生成して'"

# APIエンドポイント追加
alias cxapi="codex 'RESTful APIのエンドポイントを追加して。controller, service, repositoryの3層構造で'"

# テスト実行と修正
alias cxtest-fix="codex 'vitest を実行して失敗したテストを修正して'"

サンドボックスポリシーの詳細設定

サンドボックスポリシーはCodex CLIのセキュリティと自動化のバランスを決める重要な設定です。

サンドボックスポリシーの種類

# read-only: ファイルの読み取りのみ許可
# → コードレビュー、調査、質問への回答に最適
sandbox: read-only

# workspace-write: ワークスペース内のファイル書き込みを許可
# → 実装、リファクタリング、テスト追加に最適
sandbox: workspace-write

# network-disabled: ネットワークアクセスなし
# → オフライン環境やセキュリティが厳しい環境に適している
sandbox: network-disabled

シナリオ別推奨設定

# コードレビュー用の設定（~/.codex/codex-review.yaml）
model: o3
temperature: 0.0
sandbox: read-only
approval-policy: on-request

# 実装作業用の設定（~/.codex/codex-impl.yaml）
model: gpt-4o
temperature: 0.1
sandbox: workspace-write
approval-policy: on-failure
timeout: 300

複数の設定ファイルを切り替えるエイリアス：

# ~/.zshrc に追加

# レビューモード
alias cxrev="CODEX_CONFIG=~/.codex/codex-review.yaml codex"

# 実装モード
alias cximpl="CODEX_CONFIG=~/.codex/codex-impl.yaml codex"

マルチプロジェクト設定管理

複数のSES案件を掛け持ちする場合、プロジェクトごとに異なる設定を効率的に管理する方法を紹介します。

ディレクトリ構成例

~/.codex/
├── codex.yaml              # デフォルト設定（フォールバック）
├── profiles/
│   ├── typescript-web.yaml # TypeScript Webプロジェクト向け
│   ├── python-api.yaml     # Python API向け
│   ├── java-spring.yaml    # Java Spring向け
│   └── legacy-php.yaml     # PHPレガシー案件向け
└── scripts/
    └── switch-profile.sh   # プロファイル切り替えスクリプト

# ~/.codex/profiles/typescript-web.yaml
model: gpt-4o
temperature: 0.1
sandbox: workspace-write
approval-policy: on-failure

# プロジェクト固有の追加指示（AGENTS.mdを補完）
system-prompt-suffix: |
  TypeScriptプロジェクトです。
  型安全性を最優先にしてください。
  any型の使用は原則禁止です。

# ~/.codex/profiles/legacy-php.yaml
model: gpt-4o
temperature: 0.2
sandbox: workspace-write
approval-policy: on-request  # レガシーコードは慎重に

system-prompt-suffix: |
  レガシーPHPプロジェクトです。
  PHP 7.4との互換性を維持してください。
  既存のコーディングスタイルを尊重し、大幅な変更は避けてください。
  変更前に必ず影響範囲を確認してください。

プロファイル切り替えスクリプト：

#!/bin/bash
# ~/.codex/scripts/switch-profile.sh

PROFILES_DIR="$HOME/.codex/profiles"
CODEX_CONFIG="$HOME/.codex/codex.yaml"

if [ -z "$1" ]; then
  echo "使用方法: switch-profile.sh <プロファイル名>"
  echo "利用可能なプロファイル:"
  ls "$PROFILES_DIR" | sed 's/\.yaml//'
  exit 1
fi

PROFILE="$PROFILES_DIR/$1.yaml"

if [ ! -f "$PROFILE" ]; then
  echo "エラー: プロファイル '$1' が見つかりません"
  exit 1
fi

cp "$PROFILE" "$CODEX_CONFIG"
echo "プロファイル '$1' を適用しました"

# エイリアスとして登録
alias cxswitch="~/.codex/scripts/switch-profile.sh"

# 使用例
cxswitch typescript-web
cxswitch legacy-php

SES現場での推奨設定パターン

SESエンジニアが実際の現場で使いやすい設定をまとめました。

mkdir -p ~/.codex
cat > ~/.codex/codex.yaml << 'EOF'
model: gpt-4o
temperature: 0.1
sandbox: workspace-write
approval-policy: on-failure
log-level: warn
timeout: 180
EOF

cat >> ~/.zshrc << 'EOF'

# Codex CLI エイリアス
alias cx="codex"
alias cxf="codex --approval-policy=never"
alias cxt="codex 'テストを書いて'"
alias cxr="codex 'コードをレビューして問題点を指摘して'"
alias cxdoc="codex 'このコードにコメントとドキュメントを追加して'"
alias cxfix="codex 'このエラーを修正して:'"
EOF
source ~/.zshrc

現場別のAGENTS.md設定例

金融系SES案件向け：

# AGENTS.md（金融系案件向け）

## 重要: セキュリティ・コンプライアンス要件
- 個人情報（氏名、住所、電話番号）をログに出力してはいけない
- 金融データ（残高、取引履歴）の取り扱いには特別な注意を払うこと
- すべての入力値は必ずサニタイズ・バリデーションすること
- SQLは必ずプリペアドステートメントを使用すること

## 技術スタック
- Java 17 + Spring Boot 3.x
- Oracle Database 19c
- MyBatis（ORMとして使用）

## コーディング規約
- メソッド名は動詞から始めること（get/set/create/update/delete）
- 例外は必ず業務例外クラスを継承して作成すること
- Nullチェックは必ず行い、NullPointerExceptionを防ぐこと

スタートアップ系SES案件向け：

# AGENTS.md（スタートアップ向け）

## 開発方針
- スピードを重視しつつ、技術的負債を最小限に抑える
- シンプルさを優先し、過度な抽象化は避ける
- コードより動くプロダクトを優先するが、テストは書く

## 技術スタック
- TypeScript + Next.js 15
- Supabase（DB + Auth）
- Vercel Edge Functions

## 積極的に使っていいもの
- async/await
- TypeScript strict mode
- 最新のES構文

• 新しいプロジェクトに参画したらまずAGENTS.mdを作成する
• チームのコーディング規約をAGENTS.mdにコピーして同期する
• 定期的にAGENTS.mdを見直して最新の情報に更新する
• エイリアスはドットファイルで管理してGitHubにバックアップする
• 本番環境に関わるリポジトリでは approval-policy を on-request にする

設定のデバッグとトラブルシューティング

設定が正しく反映されているか確認する方法：

# 現在の設定を確認する
codex --show-config

# 特定の設定ファイルを指定して実行
codex --config ~/.codex/codex.yaml "このプロジェクトの構成を説明して"

# デバッグログを有効にして実行
codex --log-level=debug "テスト的な質問"

# AGENTS.mdが正しく読み込まれているか確認
codex "このプロジェクトのコーディング規約を説明して"
# → AGENTS.mdの内容を元に回答が返れば正しく読み込まれている

FAQ

まとめ

OpenAI Codex CLIのカスタム設定とエイリアスを適切に設定することで、日常的な開発作業が大幅にスムーズになります。

設定は一度整えてしまえば長く使えます。特に AGENTS.md は参画プロジェクトが変わるたびにすぐ作る習慣をつけると、AIとの対話品質が格段に上がります。SES現場での生産性向上にぜひ活用してください。

Link1 Link2 Link3

ああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああ