Codex CLI 使い方｜コマンド一覧・config.toml・AGENTS.md

Codex CLI は、OpenAI のコーディングエージェントをターミナルで動かすツールです。npm install -g @openai/codex で入れて、リポジトリのフォルダで codex と打つと対話画面が開きます。 指示は AGENTS.md、設定は ~/.codex/config.toml に書きます。スクリプトや CI からは codex exec "依頼文" で、対話なしに動かせます。

確認環境：@openai/codex 0.162.1（npm）、Node.js 22.22.2、Linux x86_64。--help とサブコマンドの help、codex mcp add が書き込む config.toml、codex debug prompt-input で見た AGENTS.md の読み込み、codex exec が最初に出す設定の行、対話画面（スラッシュコマンドの一覧・ショートカット・/permissions・/status）は手元で出力を確かめました。モデルとの通信はできない環境のため、回答の中身や料金・利用枠は公式ドキュメントに基づいて書いています（確認日 2026年10月12日）。

Codex CLI とは：何ができて、何が要るか

Codex CLI は、手元のファイルを読み、編集し、コマンドを実行しながら作業を進めるエージェントです。 補完（入力中のコードの続きを出す機能）ではなく、「このテストが落ちる原因を調べて直して」のような依頼を、ファイルの読み書きとコマンド実行を組み合わせてこなします。

npm の @openai/codex 0.162.1 は、optionalDependencies に linux-x64・linux-arm64・darwin-x64・darwin-arm64・win32-x64・win32-arm64 の 6 つを持っていました。手元の linux-x64 では、node_modules 全体が 432MB でした。package.json の engines は node >=16 です。

インストールとバージョン確認

README にある入れ方は次の 3 通りです。

# npm
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask codex

# 単体インストーラ（Mac・Linux）
curl -fsSL https://chatgpt.com/codex/install.sh | sh

入ったら、版を確かめます。

$ codex --version
codex-cli 0.162.1

更新は codex update です。動かない、つながらないときは codex doctor が、インストール・設定・認証・通信をまとめて診断します。ログインしていない状態で実行すると、次のように原因と次の手が出ました（抜粋）。

$ codex doctor --summary --ascii
Codex Doctor v0.162.1 · linux-x86_64

Notes
   [XX] auth         no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.
   [XX] reachability one or more required provider endpoints are unreachable over HTTP - Check proxy, VPN, firewall, DNS, and custom CA configuration.

ログイン：ChatGPT アカウントか API キー

ログインしないで codex を起動すると、最初に次の 3 択が出ました。

  Welcome to Codex, OpenAI's command-line coding agent
> 1. Sign in with ChatGPT
     Usage included with Plus, Pro, Business, and Enterprise plans
  2. Sign in with Device Code
     Sign in from another device with a one-time code
  3. Provide your own API key
     Pay for what you use

API キーを登録すると、codex login status は次のように表示しました（キーは一部が伏せられます）。ログインしていないときは Not logged in を出して終了コード 1 でした。

$ printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
Reading API key from stdin...
Successfully logged in
$ codex login status
Logged in using an API key - sk-****

ドキュメントでは、認証情報は ~/.codex/auth.json（CODEX_HOME を変えるとその下）か OS の資格情報ストアに保存され、cli_auth_credentials_store（file・keyring・auto・ephemeral）で選べます。auth.json にはアクセストークンが入るので、パスワードと同じ扱いが勧められています。

対話モードの基本：最初の 5 分

リポジトリのフォルダで codex を起動すると、初回は「このフォルダを信頼するか」を聞かれます。

  Folder access
  /home/you/proj
  Trust this folder? Codex can read, edit, and run files here, subject to your permission settings. ...
› 1. Trust and continue
  2. Quit

「Trust and continue」を選ぶと、~/.codex/config.toml に次の行が足されました。プロジェクト用の .codex/config.toml は、信頼したフォルダでだけ読まれます（ドキュメントの記載）。

[projects."/home/you/proj"]
trust_level = "trusted"

最初に打つと便利なのは次のコマンドです。

/status は、手元では次のように出ました。Agents.md: の行で、どの指示ファイルが読まれたかが分かります。

  Model:               GPT-6.1-Sol (reasoning low, summaries auto)
  Model provider:      openai
  Directory:           /home/you/proj
  Permissions:         Workspace (Ask for approval)
  Agents.md:           ~/.codex/AGENTS.md, AGENTS.md
  Account:             API key configured (run codex login to use ChatGPT)
  Collaboration mode:  Default
  Token usage:         0 total  (0 input + 0 output)

スラッシュコマンド一覧（0.162.1 の全50個）

対話画面で / を打つと出る一覧を、上から順に全部書き出しました。説明は画面の英語を訳したものです。

ドキュメントのコマンド一覧はデスクトップアプリと共通の書き方で、CLI だけの一覧は載っていませんでした。版によって増減するので、使っている版の / の一覧を正とします。

キーボードショートカット

入力欄が空のときに ? を押すと出る一覧です（0.162.1 の画面そのまま）。

Enter で送信、Ctrl+J で改行です。割り当ては /keymap で変えられます。

サンドボックスと承認：安全に任せる範囲を決める

Codex は「サンドボックス（何が技術的にできるか）」と「承認ポリシー（いつ人に聞くか）」の 2 つで、任せる範囲を決めます。

0.162.1 の -a に指定できるのは on-request と never の 2 つでした。untrusted を渡すとエラーになります。ドキュメントにも「untrusted はサポート終了」とあります。

$ codex -a untrusted
error: invalid value 'untrusted' for '--ask-for-approval <APPROVAL_POLICY>'
  [possible values: on-request, never]

対話画面の /permissions では、次の 3 つから選びます。 Git 管理下のフォルダでは、最初は「Ask for approval」でした。

codex exec の最初に出る設定の行で、オプションごとの違いを確かめました。

--full-auto は 0.162.1 では使えませんでした。 codex exec --full-auto は error: unexpected argument '--full-auto' found で止まります。ドキュメントでは「互換のため警告つきで残す」とされ、新しいスクリプトには --sandbox workspace-write が勧められています。以前の版を前提にした記事のコマンドを写すときは、ここが違いになります。

--dangerously-bypass-approvals-and-sandbox は、help に「外側ですでに隔離された環境（コンテナなど）専用」と書かれたオプションです。

AGENTS.md：どこに置くと、どう読まれるか

AGENTS.md は、Codex に毎回渡すプロジェクトの決まりごと（ビルド方法・テストの実行方法・書き方のルール）を書く Markdown です。 codex debug prompt-input を使うと、モデルに渡る文面を JSON で見られます。3 か所に置いて確かめました。

~/.codex/AGENTS.md          「# Global」
proj/AGENTS.md              「# Project」（Git のルート）
proj/sub/AGENTS.md          「# Sub」

proj/sub で実行すると、次の 1 つのまとまりとして渡っていました。

# AGENTS.md instructions for /home/you/proj/sub

<INSTRUCTIONS>
# Global
- 回答は日本語で書く

--- project-doc ---

# Project
- テストは ./mvnw test で実行する


# Sub
- sub 用のルール

</INSTRUCTIONS>

ドキュメントの記載では、project_doc_max_bytes の既定は 32 KiB、空のファイルは飛ばされ、1 つのフォルダから採るのは 1 ファイルだけです。Claude Code と同じリポジトリで使うなら、project_doc_fallback_filenames = ["CLAUDE.md"] を設定すると、CLAUDE.md をそのまま読ませられます。 書く中身のテンプレートは、関連記事「AGENTS.mdの書き方テンプレ｜copilot-instructions比較」で扱っています。

config.toml の雛形（そのまま使える形）

設定は ~/.codex/config.toml に TOML で書きます。 次の雛形は、手元で --strict-config（知らない項目があるとエラーにする）を付けて読み込み、エラーが出ないことを確かめたものです。

# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"     # low / medium / high / xhigh など（モデルによる）
approval_policy = "on-request"        # on-request / never
sandbox_mode = "workspace-write"      # read-only / workspace-write / danger-full-access
web_search = "cached"                 # disabled / cached / indexed / live
file_opener = "vscode"                # 出力のファイル参照を開くエディタ
project_doc_max_bytes = 65536         # AGENTS.md の上限（既定 32 KiB）
project_doc_fallback_filenames = ["CLAUDE.md"]

[sandbox_workspace_write]
network_access = false                # true で workspace-write でもネット接続を許す
writable_roots = []                   # 書き込みを許すフォルダを足す

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 20              # 既定 10 秒
tool_timeout_sec = 60                 # 既定 60 秒
enabled = true

[tui]
notifications = true

知らない項目を書くと、--strict-config のときは次のように止まりました。項目名の打ち間違いを見つけるのに使えます。

Error loading config.toml:
/home/you/.codex/config.toml:26:1: unknown configuration field `projects./home/you/proj.bogus_key`

よく使う項目の一覧

プロファイルで設定を切り替える

0.162.1 のプロファイルは、~/.codex/<名前>.config.toml という別ファイルです。 -p 名前 で、基本の設定の上に重ねて読みます。

# ~/.codex/readonly.config.toml
approval_policy = "never"
sandbox_mode = "read-only"

基本の設定が workspace-write のまま codex exec -p readonly を実行すると、sandbox: read-only に変わり、reasoning effort: medium は基本の設定から引き継がれていました。ドキュメントでは、以前の [profiles.名前] の書き方は、プロジェクトの config では無視されるとされています。

1 回だけ値を変えるなら -c を使います。

codex -c model_reasoning_effort="high" "このモジュールの設計上の問題を挙げて"

MCP サーバーをつなぐ

codex mcp add で追加すると、~/.codex/config.toml の [mcp_servers.名前] に書き込まれます。

# ローカルで起動する（stdio）サーバー
codex mcp add context7 -- npx -y @upstash/context7-mcp

# URL でつなぐ（streamable HTTP）サーバー
codex mcp add docs --url https://example.com/mcp

実行後の codex mcp list と、書き込まれた内容です。

Name      Command  Args                      Env  Cwd  Status   Auth
context7  npx      -y @upstash/context7-mcp  -    -    enabled  Unsupported

Name  Url                      Bearer Token Env Var  Status   Auth
docs  https://example.com/mcp  -                     enabled  Unknown

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.docs]
url = "https://example.com/mcp"

MCP そのものの仕組みは、関連記事「MCPとは？サーバーとクライアントの仕組みと設定例を図解」で扱っています。

codex exec：スクリプトと CI で使う

codex exec は、対話画面を開かずに 1 回の依頼を実行して終わるコマンドです。 ドキュメントでは、途中経過は標準エラー、最後の回答だけが標準出力に出ます。

# 読むだけ（既定は read-only）
codex exec "リポジトリの構成を要約して、変更が危ない箇所を5つ挙げて"

# ファイルの編集も任せる
codex exec -s workspace-write "失敗しているテストを直して"

# 標準入力を渡す（依頼文があると <stdin> ブロックとして後ろに付く）
git diff | codex exec "この差分のレビューコメントを書いて"

# JSON Lines でイベントを受け取る
codex exec --json "summarize the repo structure" | jq

# 最後の回答をファイルに書く・形を JSON Schema で決める
codex exec "プロジェクト情報を抜き出して" --output-schema ./schema.json -o ./meta.json

# 前回の続き
codex exec resume --last "見つけた競合状態を直して"

Git リポジトリの外（信頼していないフォルダ）で実行すると、次のメッセージで止まりました。

$ cd /tmp && codex exec "hi"
Reading additional input from stdin...
Not inside a trusted directory and --skip-git-repo-check was not specified.

ドキュメントでは、codex exec には環境変数 CODEX_API_KEY で API キーを渡せます。GitHub Actions では、CLI を自分で入れる代わりに openai/codex-action@v1 を使う形が勧められ、リポジトリのコードを動かすジョブ全体に API キーを環境変数で置かないよう注意書きがあります。

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

コードレビューだけなら、専用の codex review があります。

codex review --uncommitted          # 未コミットの変更（ステージ前・未追跡も含む）
codex review --base main            # main との差分
codex review --commit <SHA>         # 1 コミット分

サブコマンド一覧（codex --help）

codex features list では、0.162.1 の機能フラグが stable・experimental・under development・removed の区分つきで並びました。hooks・goals・fast_mode などは stable true です。

Claude Code との対応表

Claude Code を使っている人向けに、同じことをするコマンドとファイルを並べました。Claude Code 側は公式ドキュメント（code.claude.com）の記載に基づきます。

Claude Code のドキュメントでは、CLAUDE.md がある階層では AGENTS.md は読まれず、両方読ませる設定（claude-md-and-agents-md）が別にあります。 両方を同じリポジトリで使うなら、どちらか 1 つを正にして、もう一方から読む形にすると内容がずれません。Claude Code 側のコマンドは、関連記事「Claude Code コマンド 一覧｜CLI・スラッシュ・ショートカット早見表」で扱っています。Gemini CLI の使い方は関連記事「Gemini CLI 使い方｜コマンド一覧・設定・GEMINI.md・無料枠」、Cursor の Rules は関連記事「Cursor 使い方｜Cursor Rulesの書き方・ショートカット・雛形」で扱っています。

よくある質問

Q. Windows でも使えますか。 A. npm パッケージには win32-x64 と win32-arm64 のバイナリが含まれていて、README には PowerShell 用のインストーラ（irm https://chatgpt.com/codex/install.ps1 | iex）も載っています。

Q. ネット記事の --approval-mode full-auto や -q が動きません。 A. 0.162.1 の help には --approval-mode・--quiet・--full-auto はありませんでした。今の版では、承認は -a（on-request・never）、書き込み範囲は -s、対話なしは codex exec です。設定ファイルも、以前の config.yaml・config.json ではなく config.toml です。

Q. 料金はどうなりますか。 A. README とドキュメントでは、ChatGPT の Plus・Pro・Business・Edu・Enterprise の契約に含まれる範囲で使えるほか、API キーなら API の料金で課金されます。利用枠は契約によって違うので、/status の Limits と、ChatGPT の使用量のページ（chatgpt.com/settings/usage）で確かめます。

Q. ネット接続をさせたくありません。 A. 既定の workspace-write は、ドキュメントでも手元の表示でもネット接続なしでした。danger-full-access・--dangerously-bypass-approvals-and-sandbox・sandbox_workspace_write.network_access = true を使わなければ、接続は承認を求める形になります。

Q. Claude Code の設定をまとめて移せますか。 A. Codex には /import（Claude Code から設定・プロジェクト・最近の会話を取り込む）があり、Claude Code には /import codex があります。指示ファイルだけなら、上の project_doc_fallback_filenames が手軽です。

まとめ

• 入れるは npm install -g @openai/codex、起動は codex、対話なしは codex exec
• 任せる範囲は -s（read-only／workspace-write／danger-full-access）と -a（on-request／never） の組み合わせ。0.162.1 では --full-auto と untrusted は使えない
• AGENTS.md は ~/.codex → Git のルート → 今のフォルダの順に連結。AGENTS.override.md でその階層を差し替え、project_doc_fallback_filenames で CLAUDE.md も読める
• 設定は ~/.codex/config.toml。--strict-config で打ち間違いを見つけられる。プロファイルは <名前>.config.toml
• 困ったら codex doctor と /status

参考・出典

確認日はいずれも 2026年10月12日です。

• openai/codex（GitHub、README・docs）：https://github.com/openai/codex
• @openai/codex（npm）：https://www.npmjs.com/package/@openai/codex
• Codex ドキュメント「AGENTS.md」：https://learn.chatgpt.com/docs/agent-configuration/agents-md
• Codex ドキュメント「Configuration reference」：https://learn.chatgpt.com/docs/config-file/config-reference
• Codex ドキュメント「Agent approvals & security」：https://learn.chatgpt.com/codex/agent-approvals-security
• Codex ドキュメント「Non-interactive mode」：https://learn.chatgpt.com/docs/non-interactive-mode
• Codex ドキュメント「Authentication」：https://learn.chatgpt.com/docs/auth
• Claude Code ドキュメント「CLI reference」：https://code.claude.com/docs/en/cli-reference
• Claude Code ドキュメント「Commands」：https://code.claude.com/docs/en/commands
• Claude Code ドキュメント「How Claude remembers your project」（CLAUDE.md・AGENTS.md）：https://code.claude.com/docs/en/memory
• Claude Code ドキュメント「Connect Claude Code to tools via MCP」：https://code.claude.com/docs/en/mcp

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。