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 Code | Codex 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 を付けます。
出典
- OpenAI「Codex CLI」https://developers.openai.com/codex/cli (2026-11-13 に確認)
- OpenAI「MCP」https://developers.openai.com/codex/extend/mcp (2026-11-13 に確認)
- OpenAI「AGENTS.md」https://developers.openai.com/codex/agent-configuration/agents-md (2026-11-13 に確認)
- OpenAI「Hooks」https://developers.openai.com/codex/hooks (2026-11-13 に確認)
- OpenAI「Non-interactive mode」https://developers.openai.com/codex/non-interactive-mode (2026-11-13 に確認)
- 社の実測 2026-10-29(Codex CLI 0.164.0)