Claude Code から Codex へ移行（2026）: 設定12項目と唯一の壁

Claude Code から Codex への移行は、その大部分がリネームと再フォーマットの作業であり、Codex には今やその大半を代行してくれるワンコマンドのインポーターが同梱されています。厄介なのは、インポーターが残していくものの中に隠れています。しかもそのうちの1つは、設定ファイルですらありません。

30秒でわかる移行の結論

Claude Code のセットアップのほぼ全体を、約20分で Codex へ移せます。スクロールする前に、まずは判断材料を示します。

本ガイドの検証環境: Codex CLI 0.142.5（2026年7月1日）と Claude Code 2.1.178。古いバージョンの Codex を使っている場合は、まずアップグレードしてください。/import コマンドは 0.140.0 より前には存在しませんでした。

いま移せるもの（と移せないもの）

ほぼすべてが移せます。というのも、2つのツールは同じ問題を異なるファイル形式で解決しているからです。Claude Code は JSON（settings.json、.mcp.json）と Markdown（CLAUDE.md、.claude/agents/*.md）に依存しています。Codex は単一の TOML ファイル（~/.codex/config.toml）と AGENTS.md に依存しています。移行は、この2つの方言間の翻訳作業がほとんどです。

移せるもの:

• リポジトリおよび個人向けの指示（CLAUDE.md の内容）
• MCP サーバー（command と args はそのまま）
• スキル（すでに共通の Agent Skills 慣習に従っている）
• スラッシュコマンドと再利用可能なプロンプト
• カスタム API エンドポイントとキー

回避策なしには移せないもの:

• Claude Code のコマンドごとの権限許可リスト（Codex に直接の相当機能はない）
• ConfigChange hook イベント（Codex には PreCompact/PostCompact はあるが、設定ファイルの変更で発火するものはない）
• 出力スタイル（Codex にはモデル化されていない）
• Anthropic モデルそのもの（これが本当の障壁であり、最後のセクションの理由）

以下が全項目のマップです。この表を保存してください。移行の全体像が1画面に収まっています。

行9と行11は表面的なものです。outputStyle がなくても困りませんし、ConfigChange は設定ファイルがセッション途中で変更されたことに反応する自動化を組んでいた場合にのみ関係します。人々を止めるのは行12であり、これには多くの移行ガイドが飛ばしているきれいな解決策があります。

判断の枠組み: いつ移行すべきか（そして留まるべきか）

作業がタスク型で、より厳格なサンドボックス化を求めるなら移行しましょう。作業が会話型で hook 駆動なら Claude Code に留まりましょう。2つのツールは異なるメンタルモデルを持っており、設定の違いはそこから生じています。

移行すべきとき

• CI で非対話的にエージェントを走らせ、デフォルトの姿勢として read-only または workspace-write のサンドボックスを求めている。
• チームが、settings.json に加えて settings.local.json の上書きの山を抱えるのではなく、リスクレベルごとのプロファイルを持つ1つのコミット済み config.toml を望んでいる。
• OpenAI の現行 Codex モデル（gpt-5.5）をデフォルトのドライバーにしたい。旧来の gpt-5.3-codex は 2026-05-26 にユーザー選択可能な Codex モデルとして非推奨になったため、gpt-5.5 か gpt-5.4 を選んでください。

移行すべきでないとき

• ConfigChange hooks や出力スタイルに依存している。これらは Codex に居場所がないので、作り直しを見込むか、そのまま留まってください。
• ワークフロー全体が長時間の対話的ペアリングセッションになっている。Claude Code の会話型モデルは、Codex のタスク＆レビューのループよりもそれに適しています。
• 手作業で細かく調整した大量の権限許可リストを持っている。Codex の粗いサンドボックス階層は物足りなく感じられ、意図の移植には本当に頭を使います（ステップ5を参照）。

見送りの判断基準

既存のリポジトリに対して Codex のモデルを試すことだけが目的なら、設定の移行はまったく必要ありません。Codex をリポジトリに向け、/import を実行し、そこで止めてください。このガイドの残りは、Codex を主力ツールにする人のためのものです。

システム要件

設定に手をつける前に、以下の4つの前提条件を確認してください。Codex が古いことは、/import や [features] ブロックが黙って何もしない最も一般的な原因です。

• Codex CLI 0.140.0 以降。 codex --version で確認してください。/import コマンドは 0.140.0 で登場しました。本ガイドは 0.142.5 で検証しています。
• 既存の Claude Code プロジェクト。.claude/ ディレクトリと CLAUDE.md を無傷のまま。移行が検証できるまで削除しないでください。
• API キー（Codex を駆動させるプロバイダーのもの）。デフォルトは OpenAI、または Claude モデルを維持するならゲートウェイのキー。
• ~/.codex/ への書き込みアクセス。 Codex は呼び出しのたびに ~/.codex/config.toml を読み、信頼されたプロジェクトではリポジトリルートの .codex/config.toml も読みます。

移行パスは、全体を通してこのようになります。

flowchart LR
    A[Audit CLAUDE.md + settings.json] --> B[Run codex /import]
    B --> C[Review conflict report]
    C --> D[Hand-fix permissions + hooks]
    D --> E[Add model_provider for Claude models]
    E --> F[Test with a read-only profile]

ステップバイステップ: 全設定項目のマッピング

まず自動インポーターを実行し、その後インポーターが完全には処理できない5つの項目を順に確認してください。手動パスを飛ばさないでください。インポーターは残していくものについて正直ですが、それでも確かに残していきます。

ステップ1: インポーターを実行する

プロジェクト内で Codex を起動し、インポートします。

cd my-project
codex
# then, inside the session:
/import

Codex 0.140 は、Claude Code からセットアップ・プロジェクト設定・最近のチャットを選択的に取り込むための /import を追加しました（OpenAI Codex changelog より）。取り込みたい項目を選びます。期待される結果: 内容の埋まった ~/.codex/config.toml、AGENTS.md のドラフト、そしてスキップした項目や競合としてフラグを立てた項目を列挙した短いレポート。

ステップ2: 指示、CLAUDE.md から AGENTS.md へ

Codex は CLAUDE.md ではなく AGENTS.md を読みます。インポーターがまだ作成していなければ、ファイルをリネームするか、Codex に古い名前を読み続けるよう指示してください。

# ~/.codex/config.toml
project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]
project_doc_max_bytes = 32768

期待される結果: 次回の実行時に、リポジトリレベルの指示が Codex のコンテキストに読み込まれます。内容はそのまま引き継がれ、ファイル名とロードパスだけが異なります。そもそも AGENTS.md という慣習がツール横断で存在するのは、まさにこのためです。

ステップ3: MCP サーバー、JSON から TOML へ

MCP プロセスは同一です。形が変わるのは宣言だけです。次のような Claude Code の .mcp.json エントリは:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

~/.codex/config.toml の TOML テーブルになります:

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

期待される結果: codex が起動時に github の MCP ツールを列挙します。サーバーが環境変数を必要とする場合は、インラインで追加します: env = { "GITHUB_TOKEN" = "..." }。両方のトランスポートが引き継がれます。Codex は Claude Code で動かしていた STDIO のコマンドベースサーバーをそのまま受け入れ、同じテーブル内でストリーミング HTTP サーバーも受け付けます。したがって、リモートでホストされた MCP エンドポイントは、ローカルプロセスを起動せずに移行できます。

ステップ4: サブエージェントを .codex/agents/ へ

Claude Code はサブエージェントを .claude/agents/ に Markdown として保存します。Codex は各サブエージェントを、エージェント1つにつき1ファイルの独立した TOML ファイルとして、~/.codex/agents/（個人用）または .codex/agents/（プロジェクトスコープ）以下に保存します。サブエージェントはデフォルトで有効なので、切り替える機能フラグはありません。

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews diffs for correctness and style"
developer_instructions = """
Review the diff for correctness and style. Cite file and line for each issue.
"""

期待される結果: reviewer のロールが Codex のサブエージェントワークフローを通じて利用可能になります。Codex はこれを、明示的に要求したときにのみ呼び出します。古い Markdown ファイルのプロンプト本文は developer_instructions に移り、変わるのはラッパーです。サブエージェントが多かった場合、これは最も面倒な手動パスですが、機械的な作業です。

ステップ5: 権限をサンドボックスと承認へ

これは本当に破綻する項目です。というのも、2つのツールは安全性を異なる形でモデル化しているからです。Claude Code は glob ルールを使ったコマンドごとの許可リストを使います。Codex は2つの粗いダイヤル、すなわちファイルシステムのサンドボックスと承認ポリシーを使います。きれいな1対1のマッピングは存在しないので、ルールではなく意図を移植します。

# ~/.codex/config.toml, a sane default
approval_policy = "on-request"
sandbox_mode = "workspace-write"

期待される結果: Codex はリポジトリ内で自由に動き、その外部に触れたりネットワークに到達したりする前に確認します。Claude Code で持っていた細かなコマンドごとの制御は生き残りません。長く精密な許可リストに依存していたなら、Codex のモデルは設計上より粗いと受け入れてください。オプションの全セットは Codex configuration reference にあります。

ステップ6: Hooks

Codex には今や hooks があり、デフォルトで有効で、Claude Code のイベントの大半をカバーしています。config.toml にテーブル配列のブロックとして宣言します。システム全体をオフにするには [features] hooks = false を設定します。

# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = "^Bash$"          # same idea as Claude Code's PreToolUse matcher

  [[hooks.PreToolUse.hooks]]
  type = "command"
  command = "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use.sh"

期待される結果: JSON ハンドラーを TOML に翻訳すれば、PreToolUse、PostToolUse、SessionStart、Stop、さらには PreCompact/PostCompact まで、Claude Code のときと同じように発火します。唯一のギャップは ConfigChange で、これには Codex のイベントがありません。したがって、設定ファイルがセッション途中で変更されたことに反応するために組んだ自動化は、hook セットアップの中で唯一移行できない部分です。それらの Claude Code hooks が何をしていたかの復習には、Claude Code hooks・サブエージェント・スキルガイドをご覧ください。

相当機能がないもの: Claude モデル（とその解決策）

ネイティブな答えがない唯一の移行ステップは、Claude モデルを維持することです。というのも、素の Codex は OpenAI に対して認証し、gpt-5.5 や gpt-5.4 といった OpenAI モデルを駆動するからです。Claude Opus や Sonnet を選択する組み込みのスイッチはありません。サンドボックスとワークフローを目当てに Codex へ移行したものの、それでもコードを書くのは Opus であってほしいなら、橋渡しが必要です。

その橋渡しがカスタムの model_provider です。Codex はあらゆる OpenAI 互換ゲートウェイと通信できるので、1つ登録してプロファイルを Claude モデルに向けます。~/.codex/config.toml にプロバイダーを追加します:

[model_providers.ofox]
name = "ofox.ai gateway"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOX_API_KEY"
wire_api = "responses"
requires_openai_auth = false

人がつまずく2つのポイント。第一に、wire_api = "responses" を設定してください。Codex は 2026年2月に旧来の chat プロトコルのサポートを削除したため、wire_api = "chat" のままのプロバイダーは起動時にエラーになります。ofox は同じ /v1 ベース URL 配下で Responses 互換のエンドポイントを提供しているので、実際に接続するのは responses です。第二に、requires_openai_auth = false を設定して、Codex が sk- のキープレフィックスを期待するのを止めさせてください。それから ~/.codex/claude.config.toml にプロファイルファイルを作成します:

model = "anthropic/claude-opus-4.8"
model_provider = "ofox"

codex --profile claude で実行します。これで Codex のタスクループとサンドボックスが Anthropic の anthropic/claude-opus-4.8 を駆動し、2つ目のプロファイルで model = "openai/gpt-5.5" に入れ替えれば、認証を変えることなく両者を A/B できます。リトライやヘッダーを含むプロバイダーブロックのステップバイステップは、Codex のカスタムモデルプロバイダーの解説にあり、キーのセットアップは ofox docs 全体でカバーしています。これは、ゲートウェイが便利さではなく、目当てにしたものを維持する唯一の方法である、唯一の移行項目です。

移行中によくあるエラー（とその修正）

6つの失敗が、行き詰まる移行のほぼすべてをカバーします。パターンは毎回同じです。Codex が共有していない Claude Code の前提が原因です。

プロジェクトの .codex/config.toml が完全に無視されている場合は、そのプロジェクトが信頼済みとしてマークされているか確認してください。Codex は信頼されたディレクトリでのみプロジェクトスコープの設定を読み込み、プロジェクトファイルがプロバイダー・認証・プロファイル選択を上書きすることは許しません。

チーム / 複数開発者での移行

チームにとって、移行はソロのケースよりもきれいです。というのも、Codex は Claude Code の2つのファイルを1つのコミット済み設定にまとめるからです。Claude Code では、チーム用の .claude/settings.json を配布し、各開発者に gitignore された .claude/settings.local.json を持たせていました。Codex では、リポジトリルートに1つの .codex/config.toml をコミットし、各開発者にプロファイルを選ばせます。

チームの見返りは、前セクションと同じゲートウェイの技を一度だけ適用したものです。コミット済み設定に1つの model_provider を登録し、全開発者にシークレットマネージャー経由で同じ OFOX_API_KEY の方式を渡せば、openai/gpt-5.5 を実行しようが anthropic/claude-opus-4.8 を実行しようが、チーム全体が1つのエンドポイント・1つの請求ビューを通じてルーティングされます。この単一エンドポイントのルーティングこそが、共有ゲートウェイが開発者ごとの OpenAI キーに勝る具体的な理由です。設定の詳細は config.toml 徹底解説にあり、インストールの基本は Codex インストールガイドにあります。

ツールを Codex に移行することは、移行の目当てだったモデルを手放すことを意味してはなりません。そして1つのプロバイダーブロックがあれば、そうはなりません。

応用: CI・ローカル・レビュー用のプロファイル

プロファイルこそが、Codex が移行の労力を報いる場所です。というのも、settings.json を settings.local.json と併せてやりくりする Claude Code の習慣を置き換えるからです。プロファイルは ~/.codex/ 以下の別ファイルであり、--profile で実行ごとに選択します。あなたがそう決めるまで、グローバルには何も変わりません。

3つのリスク姿勢のために、3つのファイルを作成します:

# ~/.codex/ci.config.toml
model = "gpt-5.5"
approval_policy = "never"
sandbox_mode = "read-only"

codex --profile ci で CI での自動レビューを実行すれば、すべてを読めても何も変更できません。日々の作業のために workspace-write の local.config.toml を持ち、難しい問題に Anthropic のモデルを使いたいときにはドライバーを anthropic/claude-opus-4.8 に入れ替える、前セクションの claude.config.toml を持ちます。ベースの config.toml は共有部分、すなわちプロバイダー・MCP サーバー・hooks を保持し、各プロファイルは異なる2〜3個のキーだけを上書きします。この単一ファイルの規律こそが、移行を終えたあと、Codex のセットアップを Claude Code のスコープスタックよりも見通しやすくするものです。

FAQ

Codex CLI で Claude モデルを使えますか？ 素の Codex では使えません。Codex は OpenAI 専用です。OpenAI 互換のゲートウェイを model_provider として登録し、プロファイルを anthropic/claude-opus-4.8 に向けてください。これがネイティブな相当機能を持たない唯一の項目です。

Codex CLI は CLAUDE.md を読みますか？ デフォルトでは読みません。AGENTS.md を読みます。古いファイルを維持するには project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"] を追加するか、リネームしてください。

Claude Code の設定を Codex に取り込むには？ codex を実行し、/import を入力します。Codex 0.140 は、セットアップ・プロジェクト設定・最近のチャットのための選択式インポーターを追加しました。作業の大半をこなし、残りをレポートします。

Codex CLI には Claude Code のような hooks がありますか？ あります。デフォルトでオンです。PreToolUse、PostToolUse、SessionStart、Stop、PreCompact、PostCompact を含むイベントに対して [[hooks.Event]] ブロックを宣言します。相当がない唯一の Claude Code hook は ConfigChange です。

Claude Code と Codex で同じ MCP サーバーを共有できますか？ できます。MCP プロセスは同一です。移動するのは宣言だけで、.mcp.json の JSON から [mcp_servers.NAME] 以下の TOML へ移ります。

Claude Code のサブエージェントを Codex 用に書き直す必要がありますか？ 書き直すのではなく、宣言し直します。プロンプト本文はそのまま引き継がれ、ラッパーが .claude/agents/ の Markdown から .codex/agents/ の独立した TOML ファイルへ移ります。サブエージェントはデフォルトでオンなので、有効にするフラグはありません。

AGENTS.md は CLAUDE.md と同じものですか？ 役割は同じですが、名前が異なります。AGENTS.md はツール横断的な慣習であり、CLAUDE.md は Claude Code 独自のメモリファイルです。内容はそのまま移せます。

この更新で確認した情報源

• OpenAI Codex Configuration Reference、2026-07-03 検証。model_providers、approval_policy、sandbox_mode、[features]、AGENTS.md フォールバックの情報源。
• OpenAI Codex Changelog、2026-07-03 検証。Claude Code からの /import が 0.140.0 で登場したこと、最新リリースが 0.142.5 であることを確認。
• OpenAI Codex Hooks Reference、2026-07-03 検証。hooks がデフォルトで有効であること、PreCompact/PostCompact がサポート対象イベントであることを確認。
• Claude Code Settings Reference、2026-07-03 検証。settings.json、permissions、hook イベント、.mcp.json の情報源。
• ofox.ai モデルカタログのスナップショット、2026-07-03 検証。anthropic/claude-opus-4.8、anthropic/claude-sonnet-5、openai/gpt-5.5、ベース URL https://api.ofox.ai/v1 を確認。