無料相談する

カテゴリー / VS Code・Git・ツール連携

Claude CodeとCodexの連携方法｜MCP・AGENTS.md共有の設定手順

NO WAVE公開 更新 読了目安 14分

この記事の目次

Claude CodeとCodexの連携で、Claude Code側で決めることは2つです。Codexを呼び出す経路（MCPサーバー登録、プラグイン、コマンドの直接実行のどれか）と、指示ファイルの共有（AGENTS.md）です。ただし、CodexがMCPサーバーとして起動できるか、対応するプラグインがあるか、どのコマンドと認証で動くか、AGENTS.md を読むかはOpenAI側の仕様で、この記事では確認していません。Codex側でそれらを確認できた場合に、Claude Code側で何をどう設定するかを、公式ドキュメントの記述をもとに示します。Codex側で先に確かめる項目は、すぐ下の章にまとめました。

どちらを使うべきかの比較はClaude CodeとCodexの比較で扱っているので、ここでは両方を使う前提で進めます。

Claude CodeとCodexの連携は、Claude Code側で何を設定すればいいのか？

Codex側でどの方法に対応しているかによって、Claude Code側で触る場所が変わります。

経路 Claude Code側で起きること 設定する場所 確認方法
MCPサーバー登録 Codex側が提供するMCPサーバーのツールを、Claude CodeがMCPツールとして呼ぶ claude mcp add（保存先は ~/.claude.json か .mcp.json） claude mcp list、セッション内の /mcp
プラグイン 対応するプラグインがある場合、それがフックやMCPサーバーをまとめて持ち込む /plugin install または claude plugin install /plugin のパネル
CLIの直接実行 ClaudeがBashツールでCodexのコマンドを実行する 権限ルール（Bash(...) の allow / ask / deny） /permissions
指示ファイルの共有 Claude Codeが AGENTS.md をプロジェクトの指示として読む /config の Project instructions、または CLAUDE.md の @AGENTS.md /context

上の3行は呼び出し経路で、Codex側が対応しているものから1つ選びます。経路を1つに決めておくと、権限と確認先が散らばりません。4行目の指示ファイルの共有は呼び出しとは別の話で、Codex側も AGENTS.md を読むと確認できた場合に、規約を1つのファイルにまとめる手段になります。

Codex側で先に確かめること

次の点はOpenAI側の仕様なので、この記事では書いていません。設定を始める前に、Codexの公式ドキュメントで確かめてください。

  • Codexのインストールと認証の方法
  • CodexをMCPサーバーとして起動するコマンド（claude mcp add の -- 以降に入れる部分）があるか
  • Codex連携をうたうプラグインがあるなら、その提供元と中身
  • Codexがどの指示ファイルを読むか（AGENTS.md を共通の本体にする前提が成り立つか）

CodexをMCPサーバーとして登録する場合、どう書けばいいか？

Codex側がMCPサーバーとしての起動方法を案内している場合、自分のマシンで動くプロセスとしてつなぐなら、Claude Code側では stdio サーバーとして登録します。公式ドキュメント（MCP）にある基本構文は次のとおりです。

claude mcp add [options] <name> -- <command> [args...]

<command> [args...] の部分には、Codex側が案内している起動コマンドを入れます。ここで間違えやすいのが3点です。

  • -- を省かない。 -- はClaude Code自身のオプション（--transport、--env、--scope）と、サーバーを起動するコマンドを分ける区切りです。省くと、サーバー側のフラグをClaude Codeが自分のオプションとして解釈しようとします。
  • --env の直後にサーバー名を置かない。 --env は KEY=value を複数受け取るため、直後のサーバー名もペアとして読まれて拒否されます。間に --transport stdio などを1つ挟みます。
  • スコープを決めてから登録する。 既定は local で、自分だけ・今のプロジェクトだけで有効です。全プロジェクトで使うなら --scope user、チームで共有するなら --scope project を付けます。

設定の範囲ごとの保存先は次のとおりです。

スコープ 保存先 使える人と範囲
local（既定） ~/.claude.json のこのプロジェクトの項目 自分だけ、このプロジェクトだけ
project プロジェクト直下の .mcp.json リポジトリを取得した全員
user ~/.claude.json の mcpServers 自分だけ、全プロジェクト

project スコープで .mcp.json をコミットした場合、チームメンバーは初回にサーバーの承認を求められます。クローンしたリポジトリが本人の同意なしにプロセスを起動できないようにするための仕組みです。また公式ドキュメントは、接続する前にそのサーバーを信頼できるか確かめるよう求めています。登録できたかは、シェルなら次のコマンドで確かめます。

claude mcp list

MCP全般の仕組みとチームでの運用はClaude CodeのMCPガイドにまとめています。

プラグインで入れる場合、何を確かめてから入れるか？

Codex連携に対応するプラグインがあり、その提供元を確認できた場合の手順です。公式ドキュメント（プラグインのインストール）では、プラグインはマーケットプレイスを一度追加してから、その中のプラグインを入れる2段階です。GitHubで公開されているマーケットプレイスなら owner/repo の形で追加し、続けて <plugin>@<marketplace> の形でインストールします。セッション内の /plugin install はすぐには入らず、/plugin パネルでそのプラグインの詳細を開き、内容を確認してスコープを選んでから入れる流れです。

/plugin marketplace add owner/repo
/plugin install <plugin>@<marketplace>

シェルから入れる場合は claude plugin install <plugin>@<marketplace> です。シェルで入れたプラグインは、次にClaude Codeを起動したとき、または開いているセッションで /reload-plugins を実行したときに読み込まれます。

確かめるべきは中身です。公式ドキュメントは、プラグインがフックやMCPサーバーを実行できるため、インストール前に詳細画面を読むよう案内しています。プラグインの中身は「どのコマンドを、どのタイミングで実行するフックか」「どのMCPサーバーを起動するか」で中身が決まります。提供元と、追加される機能の一覧を確認してから入れてください。プラグインを入れるかどうかの判断軸はClaude Codeのプラグインガイドで扱っています。

Codexのコマンドを直接実行させるとき、権限はどう絞るか？

MCPやプラグインを使わず、ClaudeにBashツールでコマンドを実行させる形もあります。Codex側で実行するコマンドと認証を確認できている場合、Claude Code側で決めるのは権限ルールです（公式ドキュメント（権限））。

公式ドキュメントが強調しているのは、権限ルールはモデルではなくClaude Code本体が強制するという点です。CLAUDE.md に「Codexはレビューにだけ使う」と書いても、それはClaudeの判断を方向づけるだけで、許可される範囲は変わりません。必ず守らせたい権限境界は、権限ルールかフックで決めます。

Codex連携でBashのルールを書くときの要点は次の3つです。

  • * より前に書いた語が範囲を決める。 公式の例では、Bash(git log *) は git log だけを許可し、Bash(git *) はgitのすべてのコマンドを許可します。どのコマンドでも、許可したい語まで書いてから * を置くほど範囲が狭くなります。
  • 評価の順番は deny、ask、allow。 最初に一致したものが結果を決め、ルールの細かさは順番に影響しません。広い deny に一致すれば、より狭い allow があっても実行されません。
  • MCPで登録した場合は mcp__<server>__<tool> で書く。 サーバーの全ツールなら mcp__<server>__* です。

今どのルールが効いているかは、セッション内の /permissions で確認できます。権限モードの違いはClaude Codeの権限モード、設定ファイルの書き方はsettings.jsonガイドにあります。

CLAUDE.mdとAGENTS.mdは、どちらに書けばいいか？

Claude Codeは AGENTS.md をプロジェクトの指示として読めます（公式ドキュメント（メモリ））。公式ドキュメントでは、他のコーディングエージェント向けに整えたリポジトリが、CLAUDE.md やインポート、設定を足さなくてもそのまま動くと説明されています。ただし既定の読み込みには適用条件があります。

  • 既定値は claude-md-or-agents-md で、作業ディレクトリかその上に CLAUDE.md（または CLAUDE.local.md）が無いときだけ AGENTS.md を読みます。
  • 両方がある場合、既定では CLAUDE.md だけが読まれ、AGENTS.md は読まれません。
  • AGENTS.md を直接読むには Claude Code v2.1.277 以降が必要です。

見落としやすいのが CLAUDE.local.md です。AGENTS.md だけで運用しているプロジェクトに、自分用のメモとして CLAUDE.local.md を1つ足すと、その時点で AGENTS.md が読まれなくなります。Claude Codeで両方を読ませたいときは、セッション内で /config を開き、Project instructions を claude-md-and-agents-md に変えます。設定ファイルで指定する場合は ~/.claude/settings.json に次のように書きます（プロジェクトやローカルの設定ファイルに書いた分は無視されます）。

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

v2.1.285 より前のバージョンでは、このIDは agents-md@builtin で、cc-plugin-agents-md@builtin の項目は無視されます。v2.1.277 以降で v2.1.285 より前のバージョンも同じ設定ファイルを読むなら、agents-md@builtin で書きます。

Claude Code専用の指示も書きたい場合は、AGENTS.md を本体にし、CLAUDE.md から読み込む形が公式の案内です。次は公式ドキュメントの例です。インポートの下にClaude Code向けの指示を書くと、Claudeは AGENTS.md を先に読み、その後に残りを読みます。

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

@AGENTS.md を残しておいても二重には読まれません。逆に、CLAUDE.md に文章で「AGENTS.mdを読むこと」と書くだけの方法は、Claudeがファイルを開くと判断したときしか読まれません。Claude Code固有の指示が不要ならシンボリックリンク（ln -s AGENTS.md CLAUDE.md）でも動きますが、Windowsで作業する人がいるリポジトリではインポートを使うよう公式ドキュメントは案内しています。

公式ドキュメントでは、対話セッションで AGENTS.md を読んだときの表示例として no CLAUDE.md found; AGENTS.md loaded: で始まる行が挙げられています。実際に読まれたかは /context で確かめます。読まれていないときは、まず上の既定の条件（CLAUDE.md や CLAUDE.local.md の有無）を見て、そのうえで、v2.1.277 未満で動いている、/plugin で AGENTS.md を読む組み込みプラグインを無効にした、v2.1.276 以前からのアップグレード直後の初回セッションである、のどれかに当たっていないかを見ます。CLAUDE.md 自体の書き方はCLAUDE.mdの書き方で扱っています。

つながらない・止まる・出力が切れるときは、何を順に確認するか？

MCPで登録した場合は、確認手順に沿って見ると原因の場所を絞れます（各項目は公式ドキュメント（MCPのクイックスタート）と設定のデバッグの記述にもとづきます）。

  1. 登録が見えているか。 /mcp に何も出ないなら、別のプロジェクトで local スコープに登録した可能性があります。今のプロジェクトで登録し直すか、--scope user で登録します。手で設定ファイルを書いた場合、読まれるのは ~/.claude.json と <project>/.mcp.json だけで、~/.claude/mcp.json のようなパスは読まれません。
  2. 登録したコマンドが意図どおりか。 サーバーのコマンドをシェルで単体実行し、入力待ちで止まればサーバー自体は動いています。次に claude mcp get <name> で表示されるコマンドと見比べ、違っていれば -- の付け忘れを疑います。.mcp.json に相対パスを書いた場合、起動したディレクトリ基準で解決されるため、ここで失敗しやすくなります。
  3. 起動が時間切れになっていないか。 stdioサーバーの起動タイムアウトの既定は30秒です。初回起動が遅い場合は、ミリ秒で MCP_TIMEOUT を指定して延ばします。
MCP_TIMEOUT=60000 claude
  1. 接続済みなのにツールが0件ではないか。 ! Connected · tools fetch failed は、接続確認はできたがツール一覧を取れていない状態です。/mcp から Reconnect を選び、それでも0件なら claude --debug=mcp で起動し、~/.claude/debug/<session-id>.txt にあるサーバーのエラー出力を読みます。
  2. 途中で止まる、出力が切れる。 stdioサーバーへのツール呼び出しは、応答も進捗通知も無いまま30分経つとエラーで打ち切られます。これとは別に、サーバーごとのツール実行の上限時間は .mcp.json の該当エントリに timeout（ミリ秒）を書いて変えられます。また、MCPツールの出力は10,000トークンを超えると警告が出て、既定では25,000トークンで制限されます。長い結果を返す呼び方をしているなら MAX_MCP_OUTPUT_TOKENS で上限を変えます。

stdioサーバーはClaude Codeが自動では再接続しないため、セッション途中で落ちたら /mcp から手動でつなぎ直します。CLIを直接実行する形で失敗する場合は、まず /permissions で該当コマンドが deny に一致していないかを見て、設定ファイル自体の不正は claude doctor で確認します。指示が効いていない場合は /context で CLAUDE.md や AGENTS.md が読み込まれているかを確かめます。Claude Code全体のエラーの切り分けはClaude Codeのエラー対処ガイドにあります。

バージョン番号はいつ時点の境目か？

本文中のバージョン番号（v2.1.277、v2.1.285）は、2026年10月18日に確認した公式ドキュメントに書かれている境目です。Claude Code側の記述もバージョンで変わるため、設定がうまく反映されないときは、使っているバージョンと公式ドキュメントの現在の記述を照らし合わせてください。

連携の運用を体系的に学ぶには

設定を一度通したあとも、指示ファイルの分け方や権限の絞り方は、プロジェクトが育つたびに見直しが必要になります。こうした運用まで含めて学びたい場合は、月額1,980円から参加できる学習コミュニティ「AI駆動ラボ」（lab.no-wave.jp）があります。必要になったタイミングで覗いてみてください。

CONTINUE THE SESSION

関連記事