Codex CLIとは、OpenAI の Codex を端末から動かし、コードを読み・直し・コマンドを撃たせる道具です。

  • Codex CLI のインストールと起動の手順(OpenAI の公式の文書のとおり)
  • Claude Code に慣れた人が Codex CLI へ持ち替える時に、名前や旗が違う所の対応表
  • 社の AI の席が Codex CLI で MCP・AGENTS.md・hooks・codex exec を実際に試して分かった事と、止まった所

当社は、仕事の多くを AIエージェントの席に任せています。その席を Claude Code だけでなく Codex CLI でも立てられるかを確かめるために、自社の MCP サーバーや指示の載せ方、hooks を Codex CLI につないで一つずつ撃ちました。この頁は、公式の文書に書いてある使い方と、その時の実測の記録を並べたものです。どちらが優れているかの比べではなく、違う所の記録です。

Codex CLI のインストールと起動

公式の文書が案内している手順を、そのまま並べます。

手順公式の文書に書いてある事
入れる(macOS・Linux)
単体のインストーラーで入れる:curl -fsSL https://chatgpt.com/codex/install.sh | sh
ほかの入れ方
頁には Windows・npm・Homebrew の欄も在る。Windows は Windows の頁と WSL の頁が別に在る
更新する
入れる時と同じコマンドを撃つ
起動する
プロジェクトのディレクトリを開いて codex を撃つ
サインイン
初めて動かす時に「Sign in with ChatGPT」か、ほかの使えるサインインの方法を選ぶ
人を介さずに撃つ
codex exec でスクリプトや CI から動かす。既定では読むだけのサンドボックスで走る

出典: OpenAI「Codex CLI」https://developers.openai.com/codex/cli ・「Non-interactive mode」https://developers.openai.com/codex/non-interactive-mode (どちらも 2026-11-13 に確認)。

当社が試したのは codex --version で codex-cli 0.164.0 と出る版です(社の実測 2026-10-29)。以下の記録はこの版での事で、版が変わると振る舞いが変わる事があります。

Claude Code から持ち替える時の対応表

同じ事をさせたい時に、Claude Code での書き方と Codex CLI での書き方が違う所を並べます。右の列は、当社が実際に撃って確かめたかです。

したい事Claude CodeCodex CLI当社の確かめ
プロジェクトの決まりを読ませる
CLAUDE.md・.claude/rules
AGENTS.md(CLAUDE.md と .claude/rules は読まない)
実測で確かめた
指示を起動の時に足す
system prompt を足す旗
-c developer_instructions="…"
実測で効いた
MCP サーバーをつなぐ
MCP の設定(JSON)
-c mcp_servers.<名>.command/args/env か config.toml
実測でつながった
道具の名前を指示に書く
mcp__<server>__<tool>
server と tool の 2 段(ハイフンは内部で _)
実測で名前が合わなかった
人を介さずに 1 回撃つ
-p
codex exec(Codex の -p は --profile)
help で確かめた
機械で読む出力
JSON の出力の形
codex exec --json=JSONL の事象の流れ(1 個の JSON ではない)
実測で確かめた
使える道具・ターン数を絞る
--allowedTools・--max-turns
当たる旗は help に無い
help で確かめた
hooks を入れる
settings の hooks
-c hooks.<事象>=…・hooks.json・config.toml の [hooks]
実測で同じ名前の事象が発火した

出典: 社の実測 2026-10-29(Codex CLI 0.164.0)。hooks の置き場は OpenAI「Hooks」https://developers.openai.com/codex/hooks (2026-11-13 に確認)。

Claude Code 側の書き方は、Claude Code の設定・Claude Code の MCP 設定・Claude Code の hooks の頁にまとめています。

codex mcp:自社の MCP サーバーをつないだ記録

公式の文書では、MCP サーバーは config.toml(既定は ~/.codex/config.toml)の [mcp_servers.<server-name>] の表に書き、手元で立てる形は command が要り、args と env は任意です。codex mcp add <名> -- <起動のコマンド> でも足せて、codex mcp list で一覧を見ます。この設定は CLI と IDE の拡張などで共有されます(https://developers.openai.com/codex/extend/mcp 2026-11-13 に確認)。

当社は設定のファイルに書かず、起動のたびに -c で上書きして渡しました。

# 形の例:設定のファイルを変えずに、その回だけ MCP サーバーを渡す
codex exec --json \
  -c 'mcp_servers.<名>.command="<起動するコマンド>"' \
  -c 'mcp_servers.<名>.args=["<引数>"]' \
  -c 'mcp_servers.<名>.env={<キー>="<値>"}' \
  "<指示>" </dev/null

道具が 1,537 本・79 サービスある自社の MCP サーバーを渡すと、1,537 本とも Codex から見えました(社の実測 2026-10-29)。Codex は全部の道具の定義を文脈に積まず、検索して引く形で扱っていました。その時の 1 ターンの入力は 128,853 トークンで、うち 109,184 トークンがキャッシュでした(社の実測 2026-10-29)。道具が多くても、定義を全部読ませる形にはなりませんでした。MCP と API の違いそのものは MCP と API の違いの頁に書いています。

承認の旗が無いと、MCP の呼び出しは失敗する

承認の旗を付けず -s read-only で撃つと、MCP の呼び出しは 4 本とも「MCP tool call requires approval, but approval policy is never」で失敗しました。道具は見つかっていて、呼び出しの所で止まる形です(社の実測 2026-10-29)。

--dangerously-bypass-approvals-and-sandbox を付けると、読むだけの道具 6 本がどれも completed になりました(社の実測 2026-10-29)。この判定は、モデルが返した文ではなく、--json の出力に流れる mcp_tool_call の事象で数えています。モデルの「呼びました」という文は、呼べたかの証拠にしませんでした。

この旗は承認とサンドボックスを両方外すので、書き込む道具がつながった席で使う時は、何を呼ばせるかを指示の側で絞ってから使います。

Claude Code 向けの道具の名前は、そのままでは合わない

Codex の中では、道具の名前は server と tool の 2 段で扱われ、ハイフンは内部で _ に置き換わっていました(社の実測 2026-10-29)。Claude Code 向けに mcp__<server>__<tool> の形で道具の名前を書いた指示は、Codex に渡すとそのままでは名前が合いません。指示を両方で使うなら、名前の書き方を直すか、道具の名前ではなく「何をする道具か」で書きます。

後から足した道具は、立て直すまで見えない見込み

席の途中で MCP を有効にして道具を増やす形(サーバーが tools/list_changed を知らせる形)は、撃っていません(未実測)。codex features list では mcp_tool_list_changed が under development・false と出ていたので、立て直すまでは見えない見込みです(社の実測 2026-10-29)。道具を増やす使い方をするなら、増やした後に席を立て直す手順にしておきます。

AGENTS.md と developer_instructions:CLAUDE.md は読まれない

公式の文書では、Codex は作業の前に AGENTS.md を読みます。ホーム(既定は ~/.codex)の AGENTS.md と、プロジェクトの根(ふつうは Git の根)から今のディレクトリまで降りる途中の AGENTS.md をつなぎ、今のディレクトリに近いものほど後ろに置かれて優先されます。各ディレクトリで先に AGENTS.override.md を見ます。合わせた大きさが project_doc_max_bytes(既定 32 KiB)に達すると、それ以上は足しません(https://developers.openai.com/codex/agent-configuration/agents-md 2026-11-13 に確認)。

当社が試すと、Codex は CLAUDE.md と .claude/rules を読まず、AGENTS.md だけを読みました(社の実測 2026-10-29)。CLAUDE.md にだけ決まりを書いているプロジェクトでは、Codex はその決まりを知らないまま動きます。同じ決まりを守らせるなら、AGENTS.md にも置きます。

起動の時に指示を足すのは、-c developer_instructions="…" で効きました。指示の中に合言葉を置き、それを答えさせて、指示が読まれた事を確かめています(社の実測 2026-10-29)。

ただし、-c に指示の本文を直に置くと、プロセスの引数に本文がそのまま載るので、ps で見える形になります(社の実測 2026-10-29)。人に見せたくない指示を渡す時は、この形を避けます。

codex hooks:Claude Code と同じ名前の事象が発火した

公式の文書では、hooks は hooks.json か config.toml の [hooks] の表に書き、ホームの ~/.codex とリポジトリの .codex に置けます。管理されていない hooks は、確かめて信頼してからでないと走りません。/hooks で確かめて信頼でき、--dangerously-bypass-hook-trust はその 1 回だけ信頼の確認を飛ばします(https://developers.openai.com/codex/hooks 2026-11-13 に確認)。

当社は -c hooks.<事象>=… で起動の時に hooks を渡し、次の事象が発火するかを見ました。

事象Codex CLI で発火したかClaude Code と比べて
SessionStart
発火した
同じ名前・ほぼ同じ欄
UserPromptSubmit
発火した
同じ名前・ほぼ同じ欄
PreToolUse・PostToolUse
発火した
同じ名前・ほぼ同じ欄
Stop
発火した
同じ名前・ほぼ同じ欄
SessionEnd
発火した
同じ名前・ほぼ同じ欄
StopFailure・PostToolUseFailure に当たる物
無い見込み
失敗の印を hooks で取る作りは、別の取り方が要る

出典: 社の実測 2026-10-29(Codex CLI 0.164.0)。

hooks を置かない形で同じように撃つと、発火の記録は 0 でした(陰性対照・社の実測 2026-10-29)。発火したのが自分の置いた hooks だと確かめられます。公式の事象の一覧にも、StopFailure・PostToolUseFailure の名前はありません(https://developers.openai.com/codex/hooks 2026-11-13 に確認)。

codex exec で予約の仕事を回す時に止まった所

予約で起きる席のように、人がいない所から codex exec を撃つ時に、当社が詰まった所です。

stdin を閉じないと、入力を待って止まる

codex exec は、</dev/null を付けないと「Reading additional input from stdin...」と出して止まりました。当社は 1 回目、これで 10 分止めています(社の実測 2026-10-29)。公式の文書でも、stdin をつなぐと指示に足す文脈として読み、指示を省くと stdin から指示を読む、とあります(https://developers.openai.com/codex/non-interactive-mode 2026-11-13 に確認)。読ませる物が無い時は、</dev/null で stdin を閉じてから撃ちます。

--json は JSONL の流れで、終わりの 1 個の JSON ではない

codex exec --json の出力は、事象が 1 行ずつ流れる JSONL で、終わりに 1 個の JSON が返る形ではありません(社の実測 2026-10-29)。公式の文書では、事象には thread.started・turn.started・turn.completed・turn.failed・item.*・error があり、MCP の道具の呼び出しも item として流れます(https://developers.openai.com/codex/non-interactive-mode 2026-11-13 に確認)。1 個の JSON を読む前提の写しは、行ごとに読む形に直します。

旗の名前が同じでも意味が違う

Claude Code の -p は人を介さずに撃つ旗ですが、Codex の -p は --profile です。Claude Code の --allowedTools・--max-turns に当たる旗は、Codex の help にありませんでした(社の実測 2026-10-29)。Claude Code 向けの起動の引数をそのまま Codex に回すと、別の意味で受け取られます。

対話の画面:作業中に送った 2 通目は、走っているターンに差し込まれる

Codex CLI の対話の画面では、入力欄の印は › で、作業中は Working (… esc to interrupt) と出ます(社の実測 2026-10-29)。画面の字を読んで状態を見張る仕組みを作るなら、この字に合わせます。

作業中に 2 通目を送ると、列に積まれず、走っているターンに差し込まれました。1 通目に「20 秒待ってから完了と答えよ」と送り、作業中に 2 通目を送ると、1 通目の仕事は止まって 2 通目に答えました(社の実測 2026-10-29)。作業中に足した 1 通で、それまでの仕事の向きが変わる事があるので、急がない指示は今のターンが終わってから送ります。

よくある質問

Codex CLI はどうやってインストールしますか?

macOS と Linux は、公式の単体のインストーラー curl -fsSL https://chatgpt.com/codex/install.sh | sh で入れ、更新も同じコマンドです。入れた後はプロジェクトのディレクトリで codex を撃ち、初回に ChatGPT などでサインインします(https://developers.openai.com/codex/cli 2026-11-13 に確認)。

Codex CLI で MCP サーバーを使うには?

~/.codex/config.toml の [mcp_servers.<名>] に command・args・env を書くか、codex mcp add で足します(https://developers.openai.com/codex/extend/mcp 2026-11-13 に確認)。当社の実測では、承認の旗を付けないと MCP の呼び出しは「approval policy is never」で失敗しました(社の実測 2026-10-29)。

Codex CLI は CLAUDE.md を読みますか?

当社の実測では読みませんでした。Codex は AGENTS.md を読み、CLAUDE.md と .claude/rules は読みませんでした(社の実測 2026-10-29)。同じ決まりを守らせるなら AGENTS.md にも置きます。

Codex CLI に hooks はありますか?

あります。hooks.json か config.toml の [hooks] に書き、信頼してから走ります(https://developers.openai.com/codex/hooks 2026-11-13 に確認)。当社の実測では SessionStart・UserPromptSubmit・PreToolUse・PostToolUse・Stop・SessionEnd が Claude Code と同じ名前で発火しました(社の実測 2026-10-29)。

codex exec が止まったまま進みません。

stdin からの入力を待っている事があります。当社は </dev/null を付けずに撃って「Reading additional input from stdin...」のまま 10 分止めました(社の実測 2026-10-29)。読ませる物が無い時は </dev/null を付けます。

出典

  1. OpenAI「Codex CLI」https://developers.openai.com/codex/cli (2026-11-13 に確認)
  2. OpenAI「MCP」https://developers.openai.com/codex/extend/mcp (2026-11-13 に確認)
  3. OpenAI「AGENTS.md」https://developers.openai.com/codex/agent-configuration/agents-md (2026-11-13 に確認)
  4. OpenAI「Hooks」https://developers.openai.com/codex/hooks (2026-11-13 に確認)
  5. OpenAI「Non-interactive mode」https://developers.openai.com/codex/non-interactive-mode (2026-11-13 に確認)
  6. 社の実測 2026-10-29(Codex CLI 0.164.0)