• #Claude Code
  • #Codex CLI
  • #GPT-5.2
  • #AGENTS.md
  • #codex.toml
  • #Windows
  • #AI連携
  • #スキル
開発claude-code-toolsメモ

Claude CodeとCodex CLIの連携ガイド

この記事で解説すること

  • AGENTS.md（Codex用プロンプト設定ファイル）の書き方とベストプラクティス
  • Voltaを使ったCodex CLIのインストール問題と解決方法
  • /codex-review スキルの実装
  • codex.tomlの設定（web_search_requestの修正など）
  • Windows環境での別ウィンドウ実行方法

背景：なぜ2つのAI CLIを連携させるのか

Claude Code（Anthropic、Opus 4.5）とCodex CLI（OpenAI、GPT-5.2）は、それぞれ異なる強みを持つ。Claude Codeで作成した計画やドキュメントを、Codexでクロスレビューすることで、単一AIのバイアスを軽減できる。

当初は手動で切り替えていたが、スラッシュコマンド一発で実行できるようにしたかった。

AGENTS.mdのベストプラクティス

AGENTS.mdとは

AGENTS.mdはOpenAI Codex CLI用のプロンプト設定ファイル。Claude CodeでいうCLAUDE.mdに相当する。プロジェクトルートに配置すると、Codexがそのプロジェクトで作業する際に自動的に読み込まれる。

配置場所

project-root/
├── AGENTS.md          # プロジェクト全体の指示
└── .codex/
    └── AGENTS.md      # Codex固有の追加指示（オプション）

2つの配置場所がある。プロジェクトルートの AGENTS.md はCodexが自動で読み込む。.codex/AGENTS.md は追加の指示を記述できるが、こちらも読み込まれる。

書き方の例

以下は実際に使用しているAGENTS.mdの構成。

# AGENTS.md

OpenAI Codex および他のコーディングエージェント向けのプロジェクト指示書。

## 環境設定

### 言語・エンコーディング

- **応答言語**: 日本語で応答すること
- **ファイルエンコーディング**: 常にUTF-8（BOMなし）を使用
- **改行コード**: LF（Unix形式）を推奨

### Windows環境でのUTF-8設定

シェルコマンド実行時は以下のラッパーを使用して文字化けを防ぐ：

```powershell
# PowerShell実行時のUTF-8設定
[Console]::InputEncoding = [Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
$OutputEncoding = [Text.UTF8Encoding]::new($false)
chcp 65001 > $null


### ベストプラクティス

#### 1. 環境設定を明示する

Codexはデフォルトで英語応答するため、日本語で応答してほしい場合は明示的に指定する。

```markdown
## 環境設定

- **応答言語**: 日本語で応答すること
- **ファイルエンコーディング**: 常にUTF-8（BOMなし）を使用

2. プロジェクト構造を説明する

Codexがプロジェクトを理解しやすくなる。

## プロジェクト概要

Nuxt 3 モノレポ。@nuxt/content を使用したMDXコンテンツ管理システム。

mdx-playground/ ├── apps/ │ └── web/ # メインNuxtアプリケーション ├── content/ # Markdownコンテンツ（日付別ディレクトリ） └── .claude/ # Claude Code設定（参考用）

3. 禁止事項を明記する

特にプロセス管理は重要。

## 禁止事項

### プロセス管理

開発サーバーを停止する場合は、プロセス名ではなくポート番号で特定：

```powershell
# ✅ 正しい方法 - ポート3000のプロセスのみ終了
$pid = (Get-NetTCPConnection -LocalPort 3000 -ErrorAction SilentlyContinue).OwningProcess | Select-Object -Unique
if ($pid) { Stop-Process -Id $pid -Force }

# ❌ 禁止 - 他のNode.jsアプリも巻き込む可能性
taskkill /IM node.exe /F


#### 4. CLAUDE.mdを参照として記載する

Claude Codeの設定ファイルを参照として記載しておくと、両ツールの設定を同期しやすい。

```markdown
## 追加情報

より詳細なアーキテクチャ情報は以下を参照：

- `CLAUDE.md` - Claude Code向け設定（参考）
- `.claude/rules/architecture.md` - プロジェクト構造詳細

Continuity Ledger（コンテキスト維持機能）

.codex/AGENTS.md には、Continuity Ledgerという仕組みを追加できる。これはCodexのコンテキスト圧縮（compaction）を乗り越えて作業状態を維持するための機能。

## Continuity Ledger (compaction-safe)

Maintain a single Continuity Ledger for this workspace in `CONTINUITY.md`.
The ledger is the canonical session briefing designed to survive context compaction.

### How it works
- At the start of every assistant turn: read `CONTINUITY.md`, update it
- Keep it short and stable: facts only, no transcripts
- Mark uncertainty as `UNCONFIRMED` (never guess)

### `CONTINUITY.md` format (keep headings)
- Goal (incl. success criteria):
- Constraints/Assumptions:
- Key decisions:
- State:
  - Done:
  - Now:
  - Next:
- Open questions (UNCONFIRMED if needed):
- Working set (files/ids/commands):

これを設定すると、Codexは CONTINUITY.md ファイルを作成・更新して作業状態を追跡する。長い作業でコンテキストが圧縮されても、このファイルを読むことで作業を継続できる。

Voltaを使ったCodex CLIのインストール

問題の概要

Volta環境でCodexをインストール・アップデートする際、以下のようなエラーが発生することがある。

Volta error: Could not remove directory
at C:\Users\<ユーザー名>\AppData\Local\Volta\tools\image\packages\@openai/codex

Please ensure you have correct permissions to the Volta directory.

解決策1: volta installを使う（推奨）

volta install @openai/codex

npmの npm install -g ではなく、Voltaのコマンドを使う。

解決策2: アンインストールしてから再インストール

volta uninstall @openai/codex
volta install @openai/codex

解決策3: 手動でディレクトリを削除

上記で解決しない場合のみ、手動削除を行う。

PowerShellで削除：

# Codexディレクトリのみを削除
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Volta\tools\image\packages\@openai\codex" -ErrorAction Stop

# 再インストール
volta install @openai/codex

Git Bashで削除（PowerShellで失敗する場合）：

rm -rf "$LOCALAPPDATA/Volta/tools/image/packages/@openai/codex"

PowerShellで削除できない場合、ファイルがロックされている可能性がある。Git Bashは異なる方法でファイルにアクセスするため、成功することがある。

バージョン確認

codex --version

/codex-review スキルの実装

スキルの概要

Claude Codeのスキル機能を使い、/codex-review コマンドを実装した。

~/.claude/skills/codex-review/
└── SKILL.md

ユーザーレベル（~/.claude/skills/）に配置したため、どのプロジェクトからでも利用できる。

使い方

/codex-review          # デフォルト（gpt-5.2-codex）
/codex-review max      # gpt-5.1-codex-max（深い分析）
/codex-review mini     # gpt-5.1-codex-mini（高速）

モデル指定オプション

引数モデル説明
(なし)gpt-5.2-codexデフォルト。最新のagentic codingモデル
maxgpt-5.1-codex-maxより深い分析が必要な場合
minigpt-5.1-codex-mini軽量・高速なレビュー

利用可能なモデルは codex models で確認できる。

実行フロー

1. ユーザー: /codex-review max
2. Claude Code: スキルを読み込む
3. Claude Code: 引数 "max" → -m gpt-5.1-codex-max に変換
4. Claude Code: 対象ファイルのパスを特定（会話文脈から推測）
5. Claude Code: codex exec -m gpt-5.1-codex-max "..." を実行
6. Codex: ファイルを読んでレビュー
7. Claude Code: 結果を .claude/codex-review/ に保存
8. Claude Code: サマリーをユーザーに表示
9. Claude Code: 「詳細は {パス} を参照」と案内

レビュー結果の保存

レビュー結果は .claude/codex-review/ ディレクトリに保存する。

.claude/codex-review/
├── 2026-01-14_071530.md
├── 2026-01-14_083045.md
└── ...

ファイル名は YYYY-MM-DD_HHMMSS.md 形式で、実行日時を記録する。このディレクトリは .gitignore に追加しておく。

実行コマンドの例

# タイムスタンプ生成 & Codex実行 & 保存 & 表示
timestamp=$(date +%Y-%m-%d_%H%M%S) && \
codex exec "対象ファイル.md をレビューして" \
  > .claude/codex-review/${timestamp}.md 2>&1 && \
cat .claude/codex-review/${timestamp}.md

&& で繋いで1コマンドにまとめることで、Claude Codeの承認を1回で済ませる。

SKILL.mdの内容

---
name: "codex-review"
description: "Codex CLI（GPT-5.2）にレビューを依頼する"
---

# Codex Review

## Overview

Claude CodeからCodex CLI v0.80.0（GPT-5.2）を呼び出し、
計画・記事・コードなどのレビューを依頼する。

## 引数

| 引数 | モデル | 説明 |
|------|--------|------|
| (なし) | gpt-5.2-codex | デフォルト |
| `max` | gpt-5.1-codex-max | 深い分析向け |
| `mini` | gpt-5.1-codex-mini | 高速 |

## 実行フロー

1. 対象ファイルのパスを特定
2. codex exec "ファイルパス をレビューして" > 結果.md
3. 結果をユーザーに表示

## 注意点

- diffをコマンド引数に渡すのは禁止（長すぎてコマンドが失敗する）
- 外部パス（/tmp等）を渡さない（Codexの作業ディレクトリ外は読めない）
- | tee を使わない（出力が空になることがある）

codex.tomlの設定

設定ファイルの場所

~/.codex/config.toml

設定例

trust_level = "trusted"
hide_agent_reasoning = true
network_access = true

# 通知音（Windows用バッチファイル）
notify = ["C:\\Users\\numbe\\.codex\\codex_beep.bat"]

# デフォルトモデル
model = "gpt-5.2-codex"

# プロジェクト別の設定
[projects.'\\?\C:\Users\numbe\Git_repo\mdx-playground']
trust_level = "trusted"

# MCP Server設定
[mcp_servers.chrome-devtools]
command = "npx"
args = ["chrome-devtools-mcp@latest"]

# モデル移行通知
[notice.model_migrations]
gpt-5-codex = "gpt-5.2-codex"

# 実験的機能
[features]
experimental_windows_sandbox = true
elevated_windows_sandbox = true
web_search_request = true

主要な設定項目

trust_level

Codexがファイルを読み書きできる権限レベル。

値説明
"untrusted"読み取りのみ
"trusted"読み書き可能

hide_agent_reasoning

エージェントの思考過程を隠すかどうか。true にすると出力がすっきりする。

network_access

ネットワークアクセスを許可するかどうか。Web検索やAPI呼び出しに必要。

model

デフォルトで使用するモデル。

model = "gpt-5.2-codex"

notify

コマンド完了時の通知。Windowsではバッチファイルを指定できる。

notify = ["C:\\Users\\numbe\\.codex\\codex_beep.bat"]

通知音のバッチファイル例（codex_beep.bat）：

@echo off
powershell -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\notify.wav').PlaySync()"

features.web_search_request

Web検索機能を有効にする。Codexがインターネットで情報を検索できるようになる。

[features]
web_search_request = true

これは2026-01-14時点で実験的機能。web_search = true という古い設定名は非推奨になっており、web_search_request に変更する必要がある。

experimental_windows_sandbox

Windowsサンドボックス機能を有効にする。

[features]
experimental_windows_sandbox = true
elevated_windows_sandbox = true

Windows環境での別ウィンドウ実行

問題

codex exec は結果のみを返す。思考過程（Thinking...）やツール呼び出しの詳細は表示されない。デバッグや学習目的でCodexの動作を見たい場合は、対話モード（codex コマンド単体）を使う必要がある。

解決策：別ウィンドウで起動

# 別ウィンドウでCodexを起動
start powershell -NoExit -Command "codex '対象ファイル.md をレビューして'"

start コマンドは新しいウィンドウを開くため、Claude Codeのセッションをブロックしない。

モデル指定付きの例

start powershell -NoExit -Command "codex -m gpt-5.1-codex-max '対象ファイルをレビューして'"

Git Bashからの実行

Git Bashから実行する場合は、PowerShellを経由する。

powershell "start powershell -NoExit -Command 'codex \"対象ファイル.md をレビューして\"'"

codex execの詳細

基本構文

codex exec "プロンプト"

対話モードとの違い

項目codex execcodex（対話モード）
入力1回のプロンプトのみ対話的に複数回
出力結果のみ思考過程も表示
終了自動終了明示的に終了
用途スクリプト・自動化対話的な作業

ファイル内容の渡し方

ファイルパスを渡す（推奨）：

codex exec "apps/web/content/2026-01-14/article.md をレビューして"

Codexは作業ディレクトリ内のファイルを自分で読める。パスを伝えるだけでよい。

ファイル内容を直接渡す（短いファイル向け）：

# Bash
codex exec "以下をレビューして。

$(cat article.md)"

# PowerShell
codex exec "以下をレビューして。

$(Get-Content article.md -Raw)"

コマンド長制限があるため、長いファイルはパスを渡す方式を使う。

サンドボックス制限

codex exec はデフォルトでサンドボックス（workspace-write）で実行される。作業ディレクトリ内のファイルは読み書きできるが、それ以外は制限される。

検討した連携方式

方式1: tmux（断念）

最初に思いついたのはtmuxを使った連携だ。tmux（terminal multiplexer）は1つのターミナルで複数セッションを管理でき、send-keys で別ペインにコマンドを送れる。

# tmuxでの連携イメージ
tmux send-keys -t codex "codex 'plan.md をレビューして'" Enter

ただし、tmuxはWindowsネイティブでは公式サポートされていない。WSL、MSYS2、Cygwin経由なら動くが、普段Windowsネイティブ環境で作業しているなら余計な設定が必要になる。

方式2: 共有ファイル経由（複雑すぎた）

次に検討したのが、ファイルを介して通知し合う方式だ。

Claude Code → plan.md → Codex → review.md → Claude Code

ステータスファイルで完了を監視し、結果ファイルを読み込む。動くには動くが、ファイル監視とステータス管理が煩雑だった。

方式3: codex exec（採用）

最終的に採用したのは、codex exec で標準出力を直接受け取る方式だ。

codex exec "対象ファイル.md をレビューして"

codex exec は非インタラクティブモードでCodexを実行し、結果を標準出力に返す。ファイル監視も不要でシンプルだ。

注意点

やってはいけないこと

  1. diffをコマンド引数に渡す - 長すぎてコマンドが失敗する
  2. 外部パス（/tmp等）を渡す - Codexの作業ディレクトリ外は読めない
  3. 機密情報を含むファイルを渡す - 履歴やログに残る可能性がある
  4. | tee を使う - Codexの出力と相性が悪く空ファイルになることがある

正しいアプローチ

  1. プロジェクト内の相対パスを渡す - Codexは作業ディレクトリ内のファイルを読める
  2. リダイレクト（>）で保存 - teeではなくリダイレクトを使う
  3. 1コマンドにまとめる - && で繋いで承認を1回に

まとめ

  • AGENTS.md: プロジェクトルートに配置。言語設定、プロジェクト構造、禁止事項を明記
  • Voltaでのインストール: volta install @openai/codex を使う
  • tmuxの代替: Windows TerminalのStart-Processで別ウィンドウを開く
  • 非インタラクティブ: codex exec でスクリプトから実行可能
  • 結果保存: .claude/codex-review/ にタイムスタンプ付きで保存
  • モデル指定: -m mini / -m max で分析の深さを調整
  • codex.toml: trust_level、web_search_request、notifyなどを設定
  • スキル化: /codex-review でどのプロジェクトからでも呼び出せる

異なるAI間のクロスレビューにより、単一AIでは気づきにくい問題を発見できる。設定は多少手間だが、一度作れば継続的に使える。