Claude Code ユーザーが、Codex CLI を使うためにした工夫と運用Tips

Claude Codeユーザーのための Codex CLI 実践メモ（工夫と設定）

記事の目的：Claude Code ユーザーが Codex CLI を検討・移行する際に、実運用で効いた工夫・設定・ワークアラウンドをまとめる。
執筆日時：2025-08-11。記事中のバージョンや挙動は当時のものである。Codex CLI は開発がそれなりに活発なので最新情報は公式を確認すること。

想定読者・前提

• 想定読者：Claude Code ユーザーで Codex CLI を試す・乗り換えたいと考えている人 、具体的な設定を知りたい人。
• 前提：概要や導入方法（インストールや初回ログインなど）の初歩は公式に譲る。

追記 08-15

• 0.21.0 https://github.com/openai/codex/releases/tag/rust-v0.21.0 のリリースにより、「スキーマ互換の揺れ等により、一部サーバーでエラーや動作不良を起こす現象」は解消されたようである。

1. なぜ今 Claude Code ユーザーが Codex CLI なのか

なぜ今、Claude Code ユーザーが Codex CLI を選ぶのか。第一に、gpt‑5 がリリースされ、コーディング能力が高い。指示追従や複雑タスクの手応えが高く、Opus を凌ぐ成績である（参考: OpenAI 開発者向け発表, Anthropic Claude 4）。

第二に、Chat と CLI を同一プランで統一する意図があった。私の個人的事情として、ChatGPT Pro と Claude にそれぞれ $200 を支払っていた。Chat 側で ChatGPT を使うなら、CLI も同じアカウント（Plus/Pro/Team）でそのまま使えるため、コストは半額となる。さらに、Sign in with ChatGPT によりログイン可能である。

3. Claude Code との比較

使って良かったところ

まずモデルとしての基礎体力が高く、特に gpt‑5 は指示追従性が高いぶん暴走や抜けが少なく、複雑タスクでも「段取り→実行→検証」を一気通貫で通しやすいと感じる。
加えて、Sign in with ChatGPT により ChatGPT の有料プランからそのまま使い始められる 手軽さも、移行の心理的コストを下げてくれる。
日々の運用で Claude Code と同様によかった点は、/init で Codex CLI のルールファイル AGENTS.md を自動生成できることである。最初の運用ルール整備がすぐ済むこと、エージェント自身がタスクリストを作成して作業してくれること、そしてプロンプト履歴参照（↑キー）での反復が軽快なことも良い。
また、Claude Code の Hooks では作業終了時に音を鳴らしたり要約させたりする設定をよく使う。Codex CLI では notify 設定で同様のことが可能である。

残念だったところ

追記 2025-08-25: v0.23.0 で、/model による reasoning effort の動的変更に対応。
軽量寄りへの切り替えといった運用がしやすくなった。詳細はリリースノート参照（リリース）。

一方で、状況に応じた挙動調整をその場で行いたい局面では不便が残る。
具体的には、対話中に編集モードを切り替えられないところ（実行時引数かプロファイルで事前選択が必要）である。
暫定的にはプロファイル運用の型を用意して使い分けることで吸収したが、対話中にモードを切り替えられる仕組みが欲しいところである。

また、gpt‑5 の力強さは魅力である反面、軽作業では過剰で応答待ちが伸びがちである。
さらに、対話の途中で軽量モデルへ切り替えられない点は惜しい。用途に応じて最適な重さへ寄せたいからである。
Claude Code ではラージモデル/スモールモデルという設定があり、各作業において自動で切り替えながら進めてくれる。
Codex CLI にも自動モデル切り替えや /model 的な任意切替の仕組みがあると理想である。
なお gpt‑5‑mini を指定して利用しようとすると、手元では Unsupported model エラーとなり利用できなかった。issue も上がっているようである（GitHub）。

さらに、MCP（Model Context Protocol）サーバーは config.toml で拡張できる。
一方、現状（v0.20.0 時点）ではスキーマ互換の揺れ等により、一部サーバーでエラーや不動作が生じがちである。
これに対しては、後述の自作ラッパーで .mcp.json の一括読込・スキーマ正規化・タイムアウト管理を挟み、安定化させている。

そして、細かい使い勝手の点がある。
詳細 UI（たとえば ctrl+r での再表示）がない。
また、CLI コマンドの直接実行（Claude Code では ! を入力すると可能）も用意されていない。
エージェント実行中に次のプロンプトを投入できない、セッション再開の仕組みもない ため、長尺作業を並行して受け付ける使い方がつらい。
--continue や --resume のような再開オプションがあると実運用の自由度が上がる。画像貼り付けやサブエージェントには未対応である。

Codex CLIよ、短所多すぎでしょ 伸び代が大きいね。

4. 設定のコア：~/.codex/config.toml 実践メモ

設定例。

# === 基本 ===
model = "gpt-5"                               # 既定モデル。0.15.0以降はgpt‑5が標準に（所感/後述参照）
approval_policy = "on-request"                # モデル判断で都度承認を促す推奨設定
sandbox_mode = "workspace-write"              # 作業ディレクトリ内の読書きは自動、危険操作は承認
# ↑ READMEの「Fine-tuning in config.toml」準拠。詳細は公式参照

network_access = true                          # インターネットアクセスも設定で許可/禁止可能

# === 通知（音） ===
notify = ["bash", "-lc", "afplay /System/Library/Sounds/Glass.aiff"]  # 応答完了の通知音などに

# === カスタムプロファイル: 例 読み込み専用===
[profiles.light]
approval_policy = "never"
sandbox_mode = "read-only"

5. 工夫その1：自作 MCP ラッパーで安定運用

Codex CLI の MCP は柔軟である。しかし、現状はサーバー側の JSON Schema の揺れや初期化の遅延・失敗により、体験が不安定になりがちである。そして、.mcp.json にも対応していない。
そこで、ローカルディレクトリの .mcp.json を読み込み各 MCP サーバーをまとめて起動するラッパーを用意した。integer → number などのスキーマ差異を吸収し、初期化や tools/list をタイムアウトで守る構成とすることで、安定運用に寄与している。
リポジトリは kazuhideoki/codex-mcp-wrapper である。
README に目的・環境変数・挙動を記載している（GitHub）。
※ とりあえず動けばよいレベルのものをバイブコーディングで作成した。すべての MCP サーバーを動かせるようになったわけではなく、見た目上エラーが出たりする。公式が対応するまでの繋ぎのつもりである。

設定は ~/.codex/config.toml の [mcp_servers.mcp] にラッパーを登録するだけである。実際の起動は npx tsx path/to/index.ts とし、環境変数で .mcp.json の場所やタイムアウトを渡す（例は下記）。

# === MCP（ラッパー経由で一括登録） ===
[mcp_servers.mcp]
command = "npx"
args = ["-y", "tsx", "/path/to/codex-mcp-wrapper/src/index.ts"]
env = {
  CODEX_MCP_WRAPPER_CONFIG = "$(pwd)/.mcp.json",
  WRAPPER_INIT_TIMEOUT_MS = "4000",
  WRAPPER_TOOLS_LIST_TIMEOUT_MS = "4000",
}

実装の要所（抜粋・簡略コード例）

※イメージを掴むための最小例。実装はリポジトリ本体を参照。

// 擬似コード：.mcp.json を読み込み、各サーバーを起動しつつ型の揺れを正規化
import { spawn } from "node:child_process";
import fs from "node:fs";

type Tool = { name: string; inputSchema?: any };
type Server = {
  name: string;
  command: string;
  args?: string[];
  env?: Record<string, string>;
};

const cfgPath = process.env.CODEX_MCP_WRAPPER_CONFIG!;
const initTimeout = Number(process.env.WRAPPER_INIT_TIMEOUT_MS ?? 4000);
const listTimeout = Number(process.env.WRAPPER_TOOLS_LIST_TIMEOUT_MS ?? 4000);

// 1) 設定読込
const servers: Server[] = JSON.parse(fs.readFileSync(cfgPath, "utf-8"));

// 2) 起動 & tools/list の集約
async function start(server: Server) {
  const child = spawn(server.command, server.args ?? [], {
    env: { ...process.env, ...(server.env ?? {}) },
  });
  // ... init 完了を待つ（initTimeout で打ち切り）
  // ... tools/list を叩いてツール一覧を取得（listTimeout で打ち切り）
  const tools: Tool[] = await listTools(child);
  return tools.map(normalizeTool); // 型の揺れを吸収
}

function normalizeTool(t: Tool): Tool {
  const s = t.inputSchema;
  if (s?.type === "integer") s.type = "number"; // 代表例：integerをnumberとして扱う
  if (Array.isArray(s?.type) && s.type.includes("integer"))
    s.type = [
      ...new Set(s.type.map((x: string) => (x === "integer" ? "number" : x))),
    ];
  return { ...t, inputSchema: s };
}

// 3) すべての MCP サーバーから集約し、Codex に「ひとつの MCP」として見せる
(async () => {
  const all = (await Promise.allSettled(servers.map(start))).flatMap((r) =>
    r.status === "fulfilled" ? r.value : [],
  );
  // ... Codex CLI の MCP プロトコルに従って tools/list 応答を返す
})();

6. 工夫その2：物理サンドボックス（コンテナ）導入

Codex CLI は論理サンドボックス（ファイルシステム/ネットワークの権限分離と承認フロー）を標準搭載しており、日常運用では心強い。
とはいえ、理想は OS レベルでプロセスを隔離する「物理サンドボックス」（コンテナ/VM）で守ることだ。
公式の方針も「物理分離があるなら CLI のサンドボックスを切ってよい」という立場である。
Linux では Landlock/seccomp の事情により、CLI 内サンドボックスが効かない場合もある。
その場合は Docker などのコンテナ側で隔離を担保する。コンテナ内の Codex は --sandbox danger-full-access（または --dangerously-bypass-approvals-and-sandbox）で動かすとよい。

公式には scripts/build_container.sh と scripts/run_in_container.sh（9）が用意されており、自前でビルドして実行する運用が前提である。run_in_container.sh はファイアウォール初期化や許可ドメイン検証なども含み、実運用の足場となる。

私は Claude Code を使っている。Claude Code の devcontainer（10）をベースにしたサンドボックスが手元にあり、これを Codex CLI 用にアレンジして利用している。
隔離コンテナという意味では本質的に同じなので問題ない。

公式スクリプトで実隔離

git clone https://github.com/openai/codex
cd codex

# 1) イメージをローカルにビルド
codex-cli/scripts/build_container.sh

# 2) 作業ディレクトリをマウントして起動（APIキー例）
OPENAI_API_KEY=sk-... \
codex-cli/scripts/run_in_container.sh --work_dir "$PWD" -- \
  codex --ask-for-approval on-request --sandbox danger-full-access

• 補足: 公開イメージは用意されず、自前ビルド前提という議論が上がっている。(GitHub)

試行錯誤余談

• ログ: ~/.codex/log/codex-tui.log に保存される。環境を整える際のチェックに役立つ。

8. まとめ & これから

• 結論:
  gpt‑5 のモデルは強力である。プロファイル運用と物理サンドボックスの併用で実用水準に達する。ChatGPT プラン連携のコスト面の利点も大きい。一方で、Claude Code と比べるとツール周りは貧弱であり、工夫で補う段階である。
• 今後に期待:
  継続改善が期待できるため、適宜フォローを推奨する（直近 2025/08/11 は 0.20.0）。

9. 付録（参考リソース）

• OpenAI / Codex CLI 公式（README・設定・サンドボックス方針・MCP）(GitHub)
• Codex CLI リリース（最新版の把握に）(GitHub)
• notify 設定（Rust CLIの [notify]）に関するメンテナ回答(GitHub)
• 自作 MCP ラッパー（本記事の「工夫その1」）：kazuhideoki/codex-mcp-wrapper（READMEに目的・環境変数・挙動の解説）(GitHub)